From 2a3ccf3ce770bfe537328c4eaf0097ea3847e476 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Wed, 8 Nov 2017 02:42:13 +0900 Subject: [PATCH 001/188] Update the example of `Where-Object -IsNot` (#1841) --- reference/3.0/Microsoft.PowerShell.Core/Where-Object.md | 4 ++-- reference/4.0/Microsoft.PowerShell.Core/Where-Object.md | 4 ++-- reference/5.0/Microsoft.PowerShell.Core/Where-Object.md | 4 ++-- reference/5.1/Microsoft.PowerShell.Core/Where-Object.md | 4 ++-- reference/6/Microsoft.PowerShell.Core/Where-Object.md | 4 ++-- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Where-Object.md b/reference/3.0/Microsoft.PowerShell.Core/Where-Object.md index fe6405119d6e..0e20d28acf73 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Where-Object.md @@ -428,7 +428,7 @@ Accept wildcard characters: False Specifies the Is operator, which gets objects when the property value is an instance of the specified .NET Framework type. Enclose the type name in square brackets. -For example, `Get-Process | where StartTime -is \[DateTime\]` +For example, `Get-Process | where StartTime -Is [DateTime]` This parameter is introduced in Windows PowerShell 3.0. @@ -447,7 +447,7 @@ Accept wildcard characters: False ### -IsNot Specifies the Is-Not operator, which gets objects when the property value is not an instance of the specified .NET Framework type. -For example, `Get-Process | where StartTime -IsNot \[System.String\]` +For example, `Get-Process | where StartTime -IsNot [DateTime]` This parameter is introduced in Windows PowerShell 3.0. diff --git a/reference/4.0/Microsoft.PowerShell.Core/Where-Object.md b/reference/4.0/Microsoft.PowerShell.Core/Where-Object.md index 6f3fd361f8f4..c1d95481b976 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Where-Object.md @@ -713,7 +713,7 @@ Accept wildcard characters: False Specifies the Is operator, which gets objects when the property value is an instance of the specified .NET Framework type. Enclose the type name in square brackets. -For example, `Get-Process | where StartTime -Is \[DateTime\]` +For example, `Get-Process | where StartTime -Is [DateTime]` This parameter is introduced in Windows PowerShell 3.0. @@ -732,7 +732,7 @@ Accept wildcard characters: False ### -IsNot Specifies the Is-Not operator, which gets objects when the property value is not an instance of the specified .NET Framework type. -For example, `Get-Process | where StartTime -IsNot \[System.String\]` +For example, `Get-Process | where StartTime -IsNot [DateTime]` This parameter is introduced in Windows PowerShell 3.0. diff --git a/reference/5.0/Microsoft.PowerShell.Core/Where-Object.md b/reference/5.0/Microsoft.PowerShell.Core/Where-Object.md index b104b14f37ab..a27311f44647 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Where-Object.md @@ -729,7 +729,7 @@ Accept wildcard characters: False Indicates that this cmdlet gets objects if the property value is an instance of the specified .NET Framework type. Enclose the type name in square brackets. -For example, `Get-Process | where StartTime -Is \[DateTime\]` +For example, `Get-Process | where StartTime -Is [DateTime]` This parameter was introduced in Windows PowerShell 3.0. @@ -748,7 +748,7 @@ Accept wildcard characters: False ### -IsNot Indicates that this cmdlet gets objects if the property value is not an instance of the specified .NET Framework type. -For example, `Get-Process | where StartTime -IsNot \[System.String\]` +For example, `Get-Process | where StartTime -IsNot [DateTime]` This parameter was introduced in Windows PowerShell 3.0. diff --git a/reference/5.1/Microsoft.PowerShell.Core/Where-Object.md b/reference/5.1/Microsoft.PowerShell.Core/Where-Object.md index 4595a4b2bb0c..07bb47dbde5e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Where-Object.md @@ -729,7 +729,7 @@ Accept wildcard characters: False Indicates that this cmdlet gets objects if the property value is an instance of the specified .NET Framework type. Enclose the type name in square brackets. -For example, `Get-Process | where StartTime -Is \[DateTime\]` +For example, `Get-Process | where StartTime -Is [DateTime]` This parameter was introduced in Windows PowerShell 3.0. @@ -748,7 +748,7 @@ Accept wildcard characters: False ### -IsNot Indicates that this cmdlet gets objects if the property value is not an instance of the specified .NET Framework type. -For example, `Get-Process | where StartTime -IsNot \[System.String\]` +For example, `Get-Process | where StartTime -IsNot [DateTime]` This parameter was introduced in Windows PowerShell 3.0. diff --git a/reference/6/Microsoft.PowerShell.Core/Where-Object.md b/reference/6/Microsoft.PowerShell.Core/Where-Object.md index 4595a4b2bb0c..07bb47dbde5e 100644 --- a/reference/6/Microsoft.PowerShell.Core/Where-Object.md +++ b/reference/6/Microsoft.PowerShell.Core/Where-Object.md @@ -729,7 +729,7 @@ Accept wildcard characters: False Indicates that this cmdlet gets objects if the property value is an instance of the specified .NET Framework type. Enclose the type name in square brackets. -For example, `Get-Process | where StartTime -Is \[DateTime\]` +For example, `Get-Process | where StartTime -Is [DateTime]` This parameter was introduced in Windows PowerShell 3.0. @@ -748,7 +748,7 @@ Accept wildcard characters: False ### -IsNot Indicates that this cmdlet gets objects if the property value is not an instance of the specified .NET Framework type. -For example, `Get-Process | where StartTime -IsNot \[System.String\]` +For example, `Get-Process | where StartTime -IsNot [DateTime]` This parameter was introduced in Windows PowerShell 3.0. From f778a37db8799d2c8f0a52eff72df09cdf127d36 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Thu, 9 Nov 2017 00:24:22 +0900 Subject: [PATCH 002/188] Update Example 5 in Group-Object.md (#1845) --- .../Group-Object.md | 28 ++++++++++--------- .../Group-Object.md | 28 ++++++++++--------- .../Group-Object.md | 28 +++++++++++-------- .../Group-Object.md | 28 +++++++++++-------- .../Group-Object.md | 28 +++++++++++-------- 5 files changed, 81 insertions(+), 59 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md b/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md index 5017d9b84e94..21ab7f95fcd4 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md @@ -67,24 +67,26 @@ The command uses the Property parameter to specify that the events should be gro In the output, the Count column represents the number of entries in each group, the Name column represents the EventID values that define a group, and the Group column represents the objects in each group. ### Example 5 +```powershell +PS C:\> Get-Process | Group-Object -Property PriorityClass + +Count Name Group +----- ---- ----- + 55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnosti... + 1 {System.Diagnostics.Process (Idle)} + 3 High {System.Diagnostics.Process (Newproc), System.Diagnostic... + 2 BelowNormal {System.Diagnostics.Process (winperf), ``` -PS C:\> get-process | group-object -property priorityclass -Count Name Group ------ ---- ----- -55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnostics.Process (alg), System.Dia... -1 {System.Diagnostics.Process (Idle)} -3 High {System.Diagnostics.Process (Newproc), System.Diagnostics.Process (winlogon), System.D... -2 BelowNormal {System.Diagnostics.Process (winperf), - -PS C:\> get-process | group-object -property company -noelement +```powershell +PS C:\> Get-Process | Group-Object -Property PriorityClass -NoElement Count Name ----- ---- -55 Normal -1 -3 High -2 BelowNormal + 55 Normal + 1 + 3 High + 2 BelowNormal ``` This example demonstrates the effect of the NoElement parameter. diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Group-Object.md b/reference/4.0/Microsoft.PowerShell.Utility/Group-Object.md index 5053394e660b..d504fce222a0 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Group-Object.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Group-Object.md @@ -74,24 +74,26 @@ The command uses the Property parameter to specify that the events should be gro In the output, the Count column represents the number of entries in each group, the Name column represents the EventID values that define a group, and the Group column represents the objects in each group. ### Example 5 +```powershell +PS C:\> Get-Process | Group-Object -Property PriorityClass + +Count Name Group +----- ---- ----- + 55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnosti... + 1 {System.Diagnostics.Process (Idle)} + 3 High {System.Diagnostics.Process (Newproc), System.Diagnostic... + 2 BelowNormal {System.Diagnostics.Process (winperf), ``` -PS C:\> get-process | group-object -property priorityclass -Count Name Group ------ ---- ----- -55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnostics.Process (alg), System.Dia... -1 {System.Diagnostics.Process (Idle)} -3 High {System.Diagnostics.Process (Newproc), System.Diagnostics.Process (winlogon), System.D... -2 BelowNormal {System.Diagnostics.Process (winperf), - -PS C:\> get-process | group-object -property company -noelement +```powershell +PS C:\> Get-Process | Group-Object -Property PriorityClass -NoElement Count Name ----- ---- -55 Normal -1 -3 High -2 BelowNormal + 55 Normal + 1 + 3 High + 2 BelowNormal ``` This example demonstrates the effect of the NoElement parameter. diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Group-Object.md b/reference/5.0/Microsoft.PowerShell.Utility/Group-Object.md index d2ba6ca1314a..1dc7b6a684c2 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Group-Object.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Group-Object.md @@ -73,20 +73,26 @@ The command uses the *Property* parameter to specify that the events should be g In the output, the Count column represents the number of entries in each group, the Name column represents the EventID values that define a group, and the Group column represents the objects in each group. ### Example 5: Group processes by priority class -``` +```powershell PS C:\> Get-Process | Group-Object -Property PriorityClass -Count Name Group ------ ---- ----- -55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnostics.Process (alg), System.Dia... -1 {System.Diagnostics.Process (Idle)} -3 High {System.Diagnostics.Process (Newproc), System.Diagnostics.Process (winlogon), System.D... -2 BelowNormal {System.Diagnostics.Process (winperf), PS C:\> Get-Process | Group-Object -Property company -NoElement + +Count Name Group +----- ---- ----- + 55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnosti... + 1 {System.Diagnostics.Process (Idle)} + 3 High {System.Diagnostics.Process (Newproc), System.Diagnostic... + 2 BelowNormal {System.Diagnostics.Process (winperf), +``` + +```powershell +PS C:\> Get-Process | Group-Object -Property PriorityClass -NoElement + Count Name ----- ---- -55 Normal -1 -3 High -2 BelowNormal + 55 Normal + 1 + 3 High + 2 BelowNormal ``` This example demonstrates the effect of the *NoElement* parameter. diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Group-Object.md b/reference/5.1/Microsoft.PowerShell.Utility/Group-Object.md index 2d60f1516e56..454e3d84d85b 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Group-Object.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Group-Object.md @@ -73,20 +73,26 @@ The command uses the *Property* parameter to specify that the events should be g In the output, the Count column represents the number of entries in each group, the Name column represents the EventID values that define a group, and the Group column represents the objects in each group. ### Example 5: Group processes by priority class -``` +```powershell PS C:\> Get-Process | Group-Object -Property PriorityClass -Count Name Group ------ ---- ----- -55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnostics.Process (alg), System.Dia... -1 {System.Diagnostics.Process (Idle)} -3 High {System.Diagnostics.Process (Newproc), System.Diagnostics.Process (winlogon), System.D... -2 BelowNormal {System.Diagnostics.Process (winperf), PS C:\> Get-Process | Group-Object -Property company -NoElement + +Count Name Group +----- ---- ----- + 55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnosti... + 1 {System.Diagnostics.Process (Idle)} + 3 High {System.Diagnostics.Process (Newproc), System.Diagnostic... + 2 BelowNormal {System.Diagnostics.Process (winperf), +``` + +```powershell +PS C:\> Get-Process | Group-Object -Property PriorityClass -NoElement + Count Name ----- ---- -55 Normal -1 -3 High -2 BelowNormal + 55 Normal + 1 + 3 High + 2 BelowNormal ``` This example demonstrates the effect of the *NoElement* parameter. diff --git a/reference/6/Microsoft.PowerShell.Utility/Group-Object.md b/reference/6/Microsoft.PowerShell.Utility/Group-Object.md index 28e1b749cdf5..9f93095351f9 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Group-Object.md +++ b/reference/6/Microsoft.PowerShell.Utility/Group-Object.md @@ -74,20 +74,26 @@ The command uses the *Property* parameter to specify that the events should be g In the output, the Count column represents the number of entries in each group, the Name column represents the EventID values that define a group, and the Group column represents the objects in each group. ### Example 5: Group processes by priority class -``` +```powershell PS C:\> Get-Process | Group-Object -Property PriorityClass -Count Name Group ------ ---- ----- -55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnostics.Process (alg), System.Dia... -1 {System.Diagnostics.Process (Idle)} -3 High {System.Diagnostics.Process (Newproc), System.Diagnostics.Process (winlogon), System.D... -2 BelowNormal {System.Diagnostics.Process (winperf), PS C:\> Get-Process | Group-Object -Property company -NoElement + +Count Name Group +----- ---- ----- + 55 Normal {System.Diagnostics.Process (AdtAgent), System.Diagnosti... + 1 {System.Diagnostics.Process (Idle)} + 3 High {System.Diagnostics.Process (Newproc), System.Diagnostic... + 2 BelowNormal {System.Diagnostics.Process (winperf), +``` + +```powershell +PS C:\> Get-Process | Group-Object -Property PriorityClass -NoElement + Count Name ----- ---- -55 Normal -1 -3 High -2 BelowNormal + 55 Normal + 1 + 3 High + 2 BelowNormal ``` This example demonstrates the effect of the *NoElement* parameter. From 1357977e649f583c4e73102cb3d0774dd068fa01 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 7 Nov 2017 10:43:17 -0800 Subject: [PATCH 003/188] removing @{Text=} tags --- .../Enter-PSHostProcess.md | 4 ++-- .../Microsoft.PowerShell.Core/Out-Default.md | 2 +- .../Unprotect-CmsMessage.md | 4 ++-- .../Disable-RunspaceDebug.md | 10 ++++----- .../Enable-RunspaceDebug.md | 12 +++++----- .../Get-Runspace.md | 4 ++-- .../Get-RunspaceDebug.md | 10 ++++----- .../Select-Object.md | 2 +- reference/5.0/PowershellGet/Find-Command.md | 2 +- reference/5.0/PowershellGet/Publish-Module.md | 2 +- .../Enter-PSHostProcess.md | 4 ++-- .../Microsoft.PowerShell.Core/Get-Module.md | 4 ++-- .../Get-PSHostProcessInfo.md | 4 ++-- .../Microsoft.PowerShell.Core/Out-Default.md | 2 +- .../Get-AuthenticodeSignature.md | 2 +- .../Unprotect-CmsMessage.md | 4 ++-- .../Disable-RunspaceDebug.md | 10 ++++----- .../Enable-RunspaceDebug.md | 12 +++++----- .../Format-Hex.md | 2 +- .../Get-FormatData.md | 2 +- .../Get-Runspace.md | 4 ++-- .../Get-RunspaceDebug.md | 10 ++++----- .../Select-Object.md | 2 +- .../PSScheduledJob/Register-ScheduledJob.md | 2 +- .../5.1/PSScheduledJob/Set-ScheduledJob.md | 2 +- .../5.1/PackageManagement/Get-Package.md | 6 ++--- .../5.1/PackageManagement/Install-Package.md | 6 ++--- .../PackageManagement/Uninstall-Package.md | 6 ++--- reference/5.1/PowershellGet/Find-Command.md | 2 +- .../5.1/PowershellGet/Find-DscResource.md | 2 +- reference/5.1/PowershellGet/Find-Module.md | 2 +- .../5.1/PowershellGet/Find-RoleCapability.md | 2 +- reference/5.1/PowershellGet/Find-Script.md | 4 ++-- reference/5.1/PowershellGet/Install-Module.md | 4 ++-- reference/5.1/PowershellGet/Install-Script.md | 6 ++--- reference/5.1/PowershellGet/Publish-Module.md | 4 ++-- reference/5.1/PowershellGet/Publish-Script.md | 2 +- .../PowershellGet/Register-PSRepository.md | 4 ++-- reference/5.1/PowershellGet/Save-Module.md | 2 +- reference/5.1/PowershellGet/Save-Script.md | 2 +- .../5.1/PowershellGet/Set-PSRepository.md | 2 +- reference/5.1/PowershellGet/Update-Module.md | 2 +- reference/5.1/PowershellGet/Update-Script.md | 2 +- .../Compress-Archive.md | 2 +- .../Disable-PSSessionConfiguration.md | 2 +- .../Enter-PSHostProcess.md | 4 ++-- .../6/Microsoft.PowerShell.Core/Get-Module.md | 4 ++-- .../Get-PSHostProcessInfo.md | 6 ++--- .../New-ModuleManifest.md | 12 +++++----- .../Microsoft.PowerShell.Core/Out-Default.md | 2 +- reference/6/Microsoft.PowerShell.Core/oss.md | 4 ++-- .../New-WinEvent.md | 8 +++---- .../Convert-Path.md | 4 ++-- .../Get-ItemPropertyValue.md | 4 ++-- .../Get-PSProvider.md | 4 ++-- .../New-Service.md | 6 ++--- .../Remove-PSDrive.md | 4 ++-- .../Restart-Service.md | 6 ++--- .../Resume-Service.md | 6 ++--- .../Start-Process.md | 4 ++-- .../Start-Service.md | 6 ++--- .../Stop-Service.md | 6 ++--- .../Suspend-Service.md | 6 ++--- .../Wait-Process.md | 4 ++-- .../Get-AuthenticodeSignature.md | 4 ++-- .../Add-Member.md | 4 ++-- .../Clear-Variable.md | 4 ++-- .../Compare-Object.md | 4 ++-- .../Debug-Runspace.md | 4 ++-- .../Disable-PSBreakpoint.md | 4 ++-- .../Disable-RunspaceDebug.md | 16 +++++++------- .../Enable-PSBreakpoint.md | 4 ++-- .../Enable-RunspaceDebug.md | 18 +++++++-------- .../Export-FormatData.md | 4 ++-- .../Format-Custom.md | 4 ++-- .../Format-Hex.md | 2 +- .../Format-Table.md | 4 ++-- .../Format-Wide.md | 4 ++-- .../Get-Culture.md | 4 ++-- .../Microsoft.PowerShell.Utility/Get-Event.md | 4 ++-- .../Get-EventSubscriber.md | 4 ++-- .../Get-FormatData.md | 6 ++--- .../Microsoft.PowerShell.Utility/Get-Host.md | 4 ++-- .../Get-PSCallStack.md | 4 ++-- .../Get-Random.md | 4 ++-- .../Get-Runspace.md | 10 ++++----- .../Get-RunspaceDebug.md | 16 +++++++------- .../Get-TraceSource.md | 4 ++-- .../Get-UICulture.md | 4 ++-- .../Get-Unique.md | 4 ++-- .../Get-Variable.md | 4 ++-- .../Import-Clixml.md | 4 ++-- .../Import-LocalizedData.md | 4 ++-- .../Invoke-Expression.md | 4 ++-- .../Measure-Object.md | 4 ++-- .../Microsoft.PowerShell.Utility/New-Alias.md | 4 ++-- .../Microsoft.PowerShell.Utility/New-Event.md | 4 ++-- .../New-Object.md | 4 ++-- .../New-TimeSpan.md | 4 ++-- .../New-Variable.md | 4 ++-- .../Microsoft.PowerShell.Utility/Out-File.md | 6 ++--- .../Out-String.md | 4 ++-- .../Remove-Event.md | 4 ++-- .../Remove-PSBreakpoint.md | 4 ++-- .../Remove-Variable.md | 4 ++-- .../Select-Object.md | 2 +- .../Select-Xml.md | 4 ++-- .../Microsoft.PowerShell.Utility/Set-Alias.md | 4 ++-- .../Microsoft.PowerShell.Utility/Set-Date.md | 4 ++-- .../Set-TraceSource.md | 4 ++-- .../Set-Variable.md | 4 ++-- .../Sort-Object.md | 4 ++-- .../Trace-Command.md | 4 ++-- .../Unblock-File.md | 4 ++-- .../Unregister-Event.md | 4 ++-- .../Update-TypeData.md | 4 ++-- .../Wait-Debugger.md | 4 ++-- .../Wait-Event.md | 4 ++-- .../Write-Debug.md | 4 ++-- .../Write-Host.md | 4 ++-- .../Write-Output.md | 4 ++-- .../Write-Progress.md | 4 ++-- .../Write-Verbose.md | 4 ++-- .../Write-Warning.md | 4 ++-- reference/6/PackageManagement/Find-Package.md | 6 ++--- .../PackageManagement/Find-PackageProvider.md | 4 ++-- reference/6/PackageManagement/Get-Package.md | 6 ++--- .../6/PackageManagement/Install-Package.md | 12 +++++----- .../Install-PackageProvider.md | 4 ++-- .../Register-PackageSource.md | 4 ++-- reference/6/PackageManagement/Save-Package.md | 6 ++--- .../6/PackageManagement/Set-PackageSource.md | 4 ++-- .../6/PackageManagement/Uninstall-Package.md | 6 ++--- reference/6/PowerShellGet/Find-Command.md | 6 ++--- reference/6/PowerShellGet/Find-DscResource.md | 6 ++--- reference/6/PowerShellGet/Find-Module.md | 6 ++--- .../6/PowerShellGet/Find-RoleCapability.md | 6 ++--- reference/6/PowerShellGet/Find-Script.md | 8 +++---- reference/6/PowerShellGet/Install-Module.md | 10 ++++----- reference/6/PowerShellGet/Install-Script.md | 12 +++++----- reference/6/PowerShellGet/Publish-Module.md | 6 ++--- reference/6/PowerShellGet/Publish-Script.md | 4 ++-- .../6/PowerShellGet/Register-PSRepository.md | 22 +++++++++---------- reference/6/PowerShellGet/Save-Module.md | 6 ++--- reference/6/PowerShellGet/Save-Script.md | 6 ++--- reference/6/PowerShellGet/Set-PSRepository.md | 10 ++++----- reference/6/PowerShellGet/Update-Module.md | 6 ++--- reference/6/PowerShellGet/Update-Script.md | 6 ++--- 148 files changed, 369 insertions(+), 369 deletions(-) diff --git a/reference/5.0/Microsoft.PowerShell.Core/Enter-PSHostProcess.md b/reference/5.0/Microsoft.PowerShell.Core/Enter-PSHostProcess.md index 87e377c45c35..402fe8ff5955 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Enter-PSHostProcess.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Enter-PSHostProcess.md @@ -103,7 +103,7 @@ PS C:\> ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String @@ -118,7 +118,7 @@ Accept wildcard characters: False ``` ### -HostProcessInfo -@{Text=} + ```yaml Type: PSHostProcessInfo diff --git a/reference/5.0/Microsoft.PowerShell.Core/Out-Default.md b/reference/5.0/Microsoft.PowerShell.Core/Out-Default.md index f4f02142a169..6ca8749f6f6f 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Out-Default.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Out-Default.md @@ -49,7 +49,7 @@ Accept wildcard characters: False ``` ### -Transcript -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md b/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md index 4bd0b4d82954..5a56a41010e8 100644 --- a/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md +++ b/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md @@ -56,7 +56,7 @@ The **Unprotect-CmsMessage** cmdlet returns the decrypted content. ### Example 1: Decrypt a message ``` -PS C:\> C:\Users\gabyk\Documents\PowerShell_ISEUnprotect-CmsMessage -LiteralPath "C:\Users\Test\Documents\PowerShell ISE\Future_Plans.txt" -To '‎0f 8j b1 ab e0 ce 35 1d 67 d2 f2 6f a2 d2 00 cl 22 z9 m9 85' +PS C:\> C:\Users\gabyk\Documents\PowerShell_ISEUnprotect-CmsMessage -LiteralPath "C:\Users\Test\Documents\PowerShell ISE\Future_Plans.txt" -To '???????0f 8j b1 ab e0 ce 35 1d 67 d2 f2 6f a2 d2 00 cl 22 z9 m9 85' Try the new Break All command ``` @@ -97,7 +97,7 @@ Accept wildcard characters: False ``` ### -IncludeContext -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md b/reference/5.0/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md index 32b62fd41ed7..8d5fdcfe4c18 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md @@ -58,7 +58,7 @@ The **Disable-RunspaceDebug** cmdlet disables debugging on one or more runspaces ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String[] @@ -73,7 +73,7 @@ Accept wildcard characters: False ``` ### -ProcessName -@{Text=} + ```yaml Type: String @@ -104,7 +104,7 @@ Accept wildcard characters: False ``` ### -RunspaceId -@{Text=} + ```yaml Type: Int32[] @@ -119,7 +119,7 @@ Accept wildcard characters: False ``` ### -RunspaceInstanceId -@{Text=} + ```yaml Type: Guid[] @@ -134,7 +134,7 @@ Accept wildcard characters: False ``` ### -RunspaceName -@{Text=} + ```yaml Type: String[] diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md b/reference/5.0/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md index d53ee2c4ab42..7e7b4c4640ed 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md @@ -58,7 +58,7 @@ The **Enable-RunspaceDebug** cmdlet enables debugging on runspaces where any bre ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String[] @@ -73,7 +73,7 @@ Accept wildcard characters: False ``` ### -BreakAll -@{Text=} + ```yaml Type: SwitchParameter @@ -88,7 +88,7 @@ Accept wildcard characters: False ``` ### -ProcessName -@{Text=} + ```yaml Type: String @@ -119,7 +119,7 @@ Accept wildcard characters: False ``` ### -RunspaceId -@{Text=} + ```yaml Type: Int32[] @@ -134,7 +134,7 @@ Accept wildcard characters: False ``` ### -RunspaceInstanceId -@{Text=} + ```yaml Type: Guid[] @@ -149,7 +149,7 @@ Accept wildcard characters: False ``` ### -RunspaceName -@{Text=} + ```yaml Type: String[] diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Get-Runspace.md b/reference/5.0/Microsoft.PowerShell.Utility/Get-Runspace.md index cc52ad350a03..ab90a6d68f3a 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Get-Runspace.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Get-Runspace.md @@ -48,7 +48,7 @@ The **Get-Runspace** cmdlet gets active runspaces in a Windows PowerShell host p ## PARAMETERS ### -Id -@{Text=} + ```yaml Type: Int32[] @@ -78,7 +78,7 @@ Accept wildcard characters: False ``` ### -Name -@{Text=} + ```yaml Type: String[] diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md b/reference/5.0/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md index 23d63c3bd0c1..9fcb9f34939a 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md @@ -58,7 +58,7 @@ The **Get-RunspaceDebug** cmdlet shows runspace debugging options. ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String[] @@ -73,7 +73,7 @@ Accept wildcard characters: False ``` ### -ProcessName -@{Text=} + ```yaml Type: String @@ -104,7 +104,7 @@ Accept wildcard characters: False ``` ### -RunspaceId -@{Text=} + ```yaml Type: Int32[] @@ -119,7 +119,7 @@ Accept wildcard characters: False ``` ### -RunspaceInstanceId -@{Text=} + ```yaml Type: Guid[] @@ -134,7 +134,7 @@ Accept wildcard characters: False ``` ### -RunspaceName -@{Text=} + ```yaml Type: String[] diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Select-Object.md b/reference/5.0/Microsoft.PowerShell.Utility/Select-Object.md index 265609e99f03..a4c27a971c6a 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Select-Object.md @@ -313,7 +313,7 @@ Accept wildcard characters: False ``` ### -SkipLast -@{Text=} + ```yaml Type: Int32 diff --git a/reference/5.0/PowershellGet/Find-Command.md b/reference/5.0/PowershellGet/Find-Command.md index 0903376d9a76..af29fdd558f8 100644 --- a/reference/5.0/PowershellGet/Find-Command.md +++ b/reference/5.0/PowershellGet/Find-Command.md @@ -115,7 +115,7 @@ Accept wildcard characters: False ``` ### -MaximumVersion -@{Text=} + ```yaml Type: Version diff --git a/reference/5.0/PowershellGet/Publish-Module.md b/reference/5.0/PowershellGet/Publish-Module.md index 0bced0f1b219..6be02e89a614 100644 --- a/reference/5.0/PowershellGet/Publish-Module.md +++ b/reference/5.0/PowershellGet/Publish-Module.md @@ -78,7 +78,7 @@ Accept wildcard characters: False ``` ### -FormatVersion -@{Text=} + ```yaml Type: Version diff --git a/reference/5.1/Microsoft.PowerShell.Core/Enter-PSHostProcess.md b/reference/5.1/Microsoft.PowerShell.Core/Enter-PSHostProcess.md index be51178cf5ee..3be07ee1258f 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Enter-PSHostProcess.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Enter-PSHostProcess.md @@ -103,7 +103,7 @@ PS C:\> ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String @@ -118,7 +118,7 @@ Accept wildcard characters: False ``` ### -HostProcessInfo -@{Text=} + ```yaml Type: PSHostProcessInfo diff --git a/reference/5.1/Microsoft.PowerShell.Core/Get-Module.md b/reference/5.1/Microsoft.PowerShell.Core/Get-Module.md index 0c77199bcfe8..72ecec08ab61 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Get-Module.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Get-Module.md @@ -212,7 +212,7 @@ PS C:\> Get-Content $m.Path GUID="{8FA5064B-8479-4c5c-86EA-0D311FE48875}" Author="Microsoft Corporation" CompanyName="Microsoft Corporation" -Copyright="© Microsoft Corporation. All rights reserved." +Copyright="???? Microsoft Corporation. All rights reserved." ModuleVersion="1.0.0.0" Description="Windows Powershell File Transfer Module" PowerShellVersion="2.0" @@ -448,7 +448,7 @@ Accept wildcard characters: False ``` ### -PSEdition -@{Text=} + ```yaml Type: String diff --git a/reference/5.1/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md b/reference/5.1/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md index 7ea1fee4fa89..aa6468da76ef 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md @@ -46,7 +46,7 @@ PS C:\> ## PARAMETERS ### -Id -@{Text=} + ```yaml Type: Int32[] @@ -61,7 +61,7 @@ Accept wildcard characters: False ``` ### -Name -@{Text=} + ```yaml Type: String[] diff --git a/reference/5.1/Microsoft.PowerShell.Core/Out-Default.md b/reference/5.1/Microsoft.PowerShell.Core/Out-Default.md index 53e941bf60d4..0b497ebe34d3 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Out-Default.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Out-Default.md @@ -49,7 +49,7 @@ Accept wildcard characters: False ``` ### -Transcript -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/5.1/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md b/reference/5.1/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md index 37b9d1d844a5..0ecc731bfb26 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md +++ b/reference/5.1/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md @@ -70,7 +70,7 @@ The results of the **Get-AuthenticodeSignature** command are sent to a Where-Obj ## PARAMETERS ### -Content -@{Text=} + ```yaml Type: Byte[] diff --git a/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md b/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md index 4bd0b4d82954..5a56a41010e8 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md +++ b/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md @@ -56,7 +56,7 @@ The **Unprotect-CmsMessage** cmdlet returns the decrypted content. ### Example 1: Decrypt a message ``` -PS C:\> C:\Users\gabyk\Documents\PowerShell_ISEUnprotect-CmsMessage -LiteralPath "C:\Users\Test\Documents\PowerShell ISE\Future_Plans.txt" -To '‎0f 8j b1 ab e0 ce 35 1d 67 d2 f2 6f a2 d2 00 cl 22 z9 m9 85' +PS C:\> C:\Users\gabyk\Documents\PowerShell_ISEUnprotect-CmsMessage -LiteralPath "C:\Users\Test\Documents\PowerShell ISE\Future_Plans.txt" -To '???????0f 8j b1 ab e0 ce 35 1d 67 d2 f2 6f a2 d2 00 cl 22 z9 m9 85' Try the new Break All command ``` @@ -97,7 +97,7 @@ Accept wildcard characters: False ``` ### -IncludeContext -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md b/reference/5.1/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md index 32b62fd41ed7..8d5fdcfe4c18 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md @@ -58,7 +58,7 @@ The **Disable-RunspaceDebug** cmdlet disables debugging on one or more runspaces ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String[] @@ -73,7 +73,7 @@ Accept wildcard characters: False ``` ### -ProcessName -@{Text=} + ```yaml Type: String @@ -104,7 +104,7 @@ Accept wildcard characters: False ``` ### -RunspaceId -@{Text=} + ```yaml Type: Int32[] @@ -119,7 +119,7 @@ Accept wildcard characters: False ``` ### -RunspaceInstanceId -@{Text=} + ```yaml Type: Guid[] @@ -134,7 +134,7 @@ Accept wildcard characters: False ``` ### -RunspaceName -@{Text=} + ```yaml Type: String[] diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md b/reference/5.1/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md index 4886c9e38a80..4ab106448d1d 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md @@ -58,7 +58,7 @@ The **Enable-RunspaceDebug** cmdlet enables debugging on runspaces where any bre ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String[] @@ -73,7 +73,7 @@ Accept wildcard characters: False ``` ### -BreakAll -@{Text=} + ```yaml Type: SwitchParameter @@ -88,7 +88,7 @@ Accept wildcard characters: False ``` ### -ProcessName -@{Text=} + ```yaml Type: String @@ -119,7 +119,7 @@ Accept wildcard characters: False ``` ### -RunspaceId -@{Text=} + ```yaml Type: Int32[] @@ -134,7 +134,7 @@ Accept wildcard characters: False ``` ### -RunspaceInstanceId -@{Text=} + ```yaml Type: Guid[] @@ -149,7 +149,7 @@ Accept wildcard characters: False ``` ### -RunspaceName -@{Text=} + ```yaml Type: String[] diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Format-Hex.md b/reference/5.1/Microsoft.PowerShell.Utility/Format-Hex.md index 1592b1367322..125545cb9096 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Format-Hex.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Format-Hex.md @@ -147,7 +147,7 @@ Accept wildcard characters: False ``` ### -Raw -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Get-FormatData.md b/reference/5.1/Microsoft.PowerShell.Utility/Get-FormatData.md index f2fcf649d863..da166c6085be 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Get-FormatData.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Get-FormatData.md @@ -91,7 +91,7 @@ The final command shows an excerpt of the format.ps1xml file content. ## PARAMETERS ### -PowerShellVersion -@{Text=} + ```yaml Type: Version diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Get-Runspace.md b/reference/5.1/Microsoft.PowerShell.Utility/Get-Runspace.md index 453de800bd66..252801918821 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Get-Runspace.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Get-Runspace.md @@ -48,7 +48,7 @@ The **Get-Runspace** cmdlet gets active runspaces in a Windows PowerShell host p ## PARAMETERS ### -Id -@{Text=} + ```yaml Type: Int32[] @@ -78,7 +78,7 @@ Accept wildcard characters: False ``` ### -Name -@{Text=} + ```yaml Type: String[] diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md b/reference/5.1/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md index 23d63c3bd0c1..9fcb9f34939a 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md @@ -58,7 +58,7 @@ The **Get-RunspaceDebug** cmdlet shows runspace debugging options. ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String[] @@ -73,7 +73,7 @@ Accept wildcard characters: False ``` ### -ProcessName -@{Text=} + ```yaml Type: String @@ -104,7 +104,7 @@ Accept wildcard characters: False ``` ### -RunspaceId -@{Text=} + ```yaml Type: Int32[] @@ -119,7 +119,7 @@ Accept wildcard characters: False ``` ### -RunspaceInstanceId -@{Text=} + ```yaml Type: Guid[] @@ -134,7 +134,7 @@ Accept wildcard characters: False ``` ### -RunspaceName -@{Text=} + ```yaml Type: String[] diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md b/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md index 237d14badeae..2b7b70b965e6 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md @@ -313,7 +313,7 @@ Accept wildcard characters: False ``` ### -SkipLast -@{Text=} + ```yaml Type: Int32 diff --git a/reference/5.1/PSScheduledJob/Register-ScheduledJob.md b/reference/5.1/PSScheduledJob/Register-ScheduledJob.md index e8976550516d..382fb81623b2 100644 --- a/reference/5.1/PSScheduledJob/Register-ScheduledJob.md +++ b/reference/5.1/PSScheduledJob/Register-ScheduledJob.md @@ -309,7 +309,7 @@ Accept wildcard characters: False ``` ### -RunEvery -@{Text=} + ```yaml Type: TimeSpan diff --git a/reference/5.1/PSScheduledJob/Set-ScheduledJob.md b/reference/5.1/PSScheduledJob/Set-ScheduledJob.md index 6b99f0df51e1..1abcf98a0e1d 100644 --- a/reference/5.1/PSScheduledJob/Set-ScheduledJob.md +++ b/reference/5.1/PSScheduledJob/Set-ScheduledJob.md @@ -337,7 +337,7 @@ Accept wildcard characters: False ``` ### -RunEvery -@{Text=} + ```yaml Type: TimeSpan diff --git a/reference/5.1/PackageManagement/Get-Package.md b/reference/5.1/PackageManagement/Get-Package.md index a36490c0f0af..a1f1c51ffdb8 100644 --- a/reference/5.1/PackageManagement/Get-Package.md +++ b/reference/5.1/PackageManagement/Get-Package.md @@ -123,7 +123,7 @@ Accept wildcard characters: False ``` ### -AllowClobber -@{Text=} + ```yaml Type: SwitchParameter @@ -291,7 +291,7 @@ Accept wildcard characters: False ``` ### -NoPathUpdate -@{Text=} + ```yaml Type: SwitchParameter @@ -385,7 +385,7 @@ Accept wildcard characters: False ``` ### -SkipPublisherCheck -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/5.1/PackageManagement/Install-Package.md b/reference/5.1/PackageManagement/Install-Package.md index d918c3795779..6e1888b776f6 100644 --- a/reference/5.1/PackageManagement/Install-Package.md +++ b/reference/5.1/PackageManagement/Install-Package.md @@ -154,7 +154,7 @@ Accept wildcard characters: False ``` ### -AllowClobber -@{Text=} + ```yaml Type: SwitchParameter @@ -509,7 +509,7 @@ Accept wildcard characters: False ``` ### -NoPathUpdate -@{Text=} + ```yaml Type: SwitchParameter @@ -697,7 +697,7 @@ Accept wildcard characters: False ``` ### -SkipPublisherCheck -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/5.1/PackageManagement/Uninstall-Package.md b/reference/5.1/PackageManagement/Uninstall-Package.md index 206f206f6dff..2b0c05a512c5 100644 --- a/reference/5.1/PackageManagement/Uninstall-Package.md +++ b/reference/5.1/PackageManagement/Uninstall-Package.md @@ -131,7 +131,7 @@ Accept wildcard characters: False ``` ### -AllowClobber -@{Text=} + ```yaml Type: SwitchParameter @@ -329,7 +329,7 @@ Accept wildcard characters: False ``` ### -NoPathUpdate -@{Text=} + ```yaml Type: SwitchParameter @@ -427,7 +427,7 @@ Accept wildcard characters: False ``` ### -SkipPublisherCheck -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/5.1/PowershellGet/Find-Command.md b/reference/5.1/PowershellGet/Find-Command.md index 0903376d9a76..af29fdd558f8 100644 --- a/reference/5.1/PowershellGet/Find-Command.md +++ b/reference/5.1/PowershellGet/Find-Command.md @@ -115,7 +115,7 @@ Accept wildcard characters: False ``` ### -MaximumVersion -@{Text=} + ```yaml Type: Version diff --git a/reference/5.1/PowershellGet/Find-DscResource.md b/reference/5.1/PowershellGet/Find-DscResource.md index 4bb2d12dbb59..819ac715c9eb 100644 --- a/reference/5.1/PowershellGet/Find-DscResource.md +++ b/reference/5.1/PowershellGet/Find-DscResource.md @@ -137,7 +137,7 @@ Accept wildcard characters: False ``` ### -MaximumVersion -@{Text=} + ```yaml Type: Version diff --git a/reference/5.1/PowershellGet/Find-Module.md b/reference/5.1/PowershellGet/Find-Module.md index ad0c6d0ff7c7..5cad7bbacf01 100644 --- a/reference/5.1/PowershellGet/Find-Module.md +++ b/reference/5.1/PowershellGet/Find-Module.md @@ -140,7 +140,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/5.1/PowershellGet/Find-RoleCapability.md b/reference/5.1/PowershellGet/Find-RoleCapability.md index 9999d8b05520..8a51ffebfd58 100644 --- a/reference/5.1/PowershellGet/Find-RoleCapability.md +++ b/reference/5.1/PowershellGet/Find-RoleCapability.md @@ -118,7 +118,7 @@ Accept wildcard characters: False ``` ### -MaximumVersion -@{Text=} + ```yaml Type: Version diff --git a/reference/5.1/PowershellGet/Find-Script.md b/reference/5.1/PowershellGet/Find-Script.md index def0ff3285e8..3ad8164e86c5 100644 --- a/reference/5.1/PowershellGet/Find-Script.md +++ b/reference/5.1/PowershellGet/Find-Script.md @@ -74,7 +74,7 @@ Type : Script Description : Description for the Required-Script2 script Author : pattif CompanyName : Microsoft Corporation -Copyright : © 2015 Microsoft Corporation. All rights reserved. +Copyright : ???? 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/14/2015 2:37:01 PM LicenseUri : http://required-script2.com/license ProjectUri : http://required-script2.com/ @@ -204,7 +204,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/5.1/PowershellGet/Install-Module.md b/reference/5.1/PowershellGet/Install-Module.md index ff8ffd9d58a5..c12a2ecd7139 100644 --- a/reference/5.1/PowershellGet/Install-Module.md +++ b/reference/5.1/PowershellGet/Install-Module.md @@ -82,7 +82,7 @@ This example installs the newest version of the module ContosoServer to $home\Do ## PARAMETERS ### -AllowClobber -@{Text=} + ```yaml Type: SwitchParameter @@ -297,7 +297,7 @@ Accept wildcard characters: False ``` ### -SkipPublisherCheck -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/5.1/PowershellGet/Install-Script.md b/reference/5.1/PowershellGet/Install-Script.md index c05f1a1bf647..7eb13f6da42a 100644 --- a/reference/5.1/PowershellGet/Install-Script.md +++ b/reference/5.1/PowershellGet/Install-Script.md @@ -57,7 +57,7 @@ Type : Script Description : Description for the Required-Script2 script Author : pattif CompanyName : -Copyright : © 2015 Microsoft Corporation. All rights reserved. +Copyright : ???? 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/15/2015 12:42:39 AM LicenseUri : http://required-script2.com/license ProjectUri : http://required-script2.com/ @@ -96,7 +96,7 @@ Type : Script Description : Description for the Required-Script3 script Author : pattif CompanyName : -Copyright : © 2015 Microsoft Corporation. All rights reserved. +Copyright : ???? 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/15/2015 12:42:45 AM LicenseUri : http://required-script3.com/license ProjectUri : http://required-script3.com/ @@ -280,7 +280,7 @@ Accept wildcard characters: False ``` ### -NoPathUpdate -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/5.1/PowershellGet/Publish-Module.md b/reference/5.1/PowershellGet/Publish-Module.md index 8dfb6adcddd4..8676f1185398 100644 --- a/reference/5.1/PowershellGet/Publish-Module.md +++ b/reference/5.1/PowershellGet/Publish-Module.md @@ -78,7 +78,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -108,7 +108,7 @@ Accept wildcard characters: False ``` ### -FormatVersion -@{Text=} + ```yaml Type: Version diff --git a/reference/5.1/PowershellGet/Publish-Script.md b/reference/5.1/PowershellGet/Publish-Script.md index b85aa89333ed..a663d405d989 100644 --- a/reference/5.1/PowershellGet/Publish-Script.md +++ b/reference/5.1/PowershellGet/Publish-Script.md @@ -120,7 +120,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/5.1/PowershellGet/Register-PSRepository.md b/reference/5.1/PowershellGet/Register-PSRepository.md index d8f83d95c7ce..e39918b6286b 100644 --- a/reference/5.1/PowershellGet/Register-PSRepository.md +++ b/reference/5.1/PowershellGet/Register-PSRepository.md @@ -63,7 +63,7 @@ The second command gets registered repositories and displays the results. ## PARAMETERS ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -78,7 +78,7 @@ Accept wildcard characters: False ``` ### -Default -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/5.1/PowershellGet/Save-Module.md b/reference/5.1/PowershellGet/Save-Module.md index 78a91d64b7ff..57ddded050d4 100644 --- a/reference/5.1/PowershellGet/Save-Module.md +++ b/reference/5.1/PowershellGet/Save-Module.md @@ -116,7 +116,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/5.1/PowershellGet/Save-Script.md b/reference/5.1/PowershellGet/Save-Script.md index 56882ea8b267..205405419d24 100644 --- a/reference/5.1/PowershellGet/Save-Script.md +++ b/reference/5.1/PowershellGet/Save-Script.md @@ -79,7 +79,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/5.1/PowershellGet/Set-PSRepository.md b/reference/5.1/PowershellGet/Set-PSRepository.md index 6e20cf6aa137..cccc151df005 100644 --- a/reference/5.1/PowershellGet/Set-PSRepository.md +++ b/reference/5.1/PowershellGet/Set-PSRepository.md @@ -44,7 +44,7 @@ This command sets the source location and publish location for myInternalSource ## PARAMETERS ### -Credential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/5.1/PowershellGet/Update-Module.md b/reference/5.1/PowershellGet/Update-Module.md index 9e5664157c32..80fd9c7f7422 100644 --- a/reference/5.1/PowershellGet/Update-Module.md +++ b/reference/5.1/PowershellGet/Update-Module.md @@ -90,7 +90,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/5.1/PowershellGet/Update-Script.md b/reference/5.1/PowershellGet/Update-Script.md index 423785e848a4..e0225067158e 100644 --- a/reference/5.1/PowershellGet/Update-Script.md +++ b/reference/5.1/PowershellGet/Update-Script.md @@ -57,7 +57,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/Microsoft.PowerShell.Archive/Compress-Archive.md b/reference/6/Microsoft.PowerShell.Archive/Compress-Archive.md index 2f4bedaa9afa..3ce111c58c13 100644 --- a/reference/6/Microsoft.PowerShell.Archive/Compress-Archive.md +++ b/reference/6/Microsoft.PowerShell.Archive/Compress-Archive.md @@ -226,7 +226,7 @@ Accept wildcard characters: False ``` ### -Force -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/6/Microsoft.PowerShell.Core/Disable-PSSessionConfiguration.md b/reference/6/Microsoft.PowerShell.Core/Disable-PSSessionConfiguration.md index 90734a505b83..e500b62eed57 100644 --- a/reference/6/Microsoft.PowerShell.Core/Disable-PSSessionConfiguration.md +++ b/reference/6/Microsoft.PowerShell.Core/Disable-PSSessionConfiguration.md @@ -165,7 +165,7 @@ Accept wildcard characters: False ``` ### -NoServiceRestart -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/6/Microsoft.PowerShell.Core/Enter-PSHostProcess.md b/reference/6/Microsoft.PowerShell.Core/Enter-PSHostProcess.md index be51178cf5ee..3be07ee1258f 100644 --- a/reference/6/Microsoft.PowerShell.Core/Enter-PSHostProcess.md +++ b/reference/6/Microsoft.PowerShell.Core/Enter-PSHostProcess.md @@ -103,7 +103,7 @@ PS C:\> ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String @@ -118,7 +118,7 @@ Accept wildcard characters: False ``` ### -HostProcessInfo -@{Text=} + ```yaml Type: PSHostProcessInfo diff --git a/reference/6/Microsoft.PowerShell.Core/Get-Module.md b/reference/6/Microsoft.PowerShell.Core/Get-Module.md index 36461fb4aeac..8b69589bd0a6 100644 --- a/reference/6/Microsoft.PowerShell.Core/Get-Module.md +++ b/reference/6/Microsoft.PowerShell.Core/Get-Module.md @@ -212,7 +212,7 @@ PS C:\> Get-Content $m.Path GUID="{8FA5064B-8479-4c5c-86EA-0D311FE48875}" Author="Microsoft Corporation" CompanyName="Microsoft Corporation" -Copyright="© Microsoft Corporation. All rights reserved." +Copyright="???? Microsoft Corporation. All rights reserved." ModuleVersion="1.0.0.0" Description="Windows Powershell File Transfer Module" PowerShellVersion="2.0" @@ -493,7 +493,7 @@ Accept wildcard characters: False ``` ### -PSEdition -@{Text=} + ```yaml Type: String diff --git a/reference/6/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md b/reference/6/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md index f70fb68b1f98..a82402055cf2 100644 --- a/reference/6/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md +++ b/reference/6/Microsoft.PowerShell.Core/Get-PSHostProcessInfo.md @@ -46,7 +46,7 @@ PS C:\> ## PARAMETERS ### -Id -@{Text=} + ```yaml Type: Int32[] @@ -61,7 +61,7 @@ Accept wildcard characters: False ``` ### -Name -@{Text=} + ```yaml Type: String[] @@ -76,7 +76,7 @@ Accept wildcard characters: False ``` ### -Process -@{Text=} + ```yaml Type: Process[] diff --git a/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md b/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md index 26616f97d663..39f47a75b26c 100644 --- a/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md +++ b/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md @@ -210,7 +210,7 @@ IscsiTarget 4.0 Kds 4.0 Microsoft.PowerShell.Diagnostics 4.0 Microsoft.PowerShell.Host 4.0 -Microsoft.PowerShell.Management 4.0… +Microsoft.PowerShell.Management 4.0??????? ``` This example shows how to get the module manifest values of a module. @@ -401,7 +401,7 @@ Accept wildcard characters: False ``` ### -DscResourcesToExport -@{Text=} + ```yaml Type: String[] @@ -516,7 +516,7 @@ Accept wildcard characters: False ``` ### -IconUri -@{Text=} + ```yaml Type: Uri @@ -531,7 +531,7 @@ Accept wildcard characters: False ``` ### -LicenseUri -@{Text=} + ```yaml Type: Uri @@ -740,7 +740,7 @@ Accept wildcard characters: False ``` ### -ProjectUri -@{Text=} + ```yaml Type: Uri @@ -858,7 +858,7 @@ Accept wildcard characters: False ``` ### -Tags -@{Text=} + ```yaml Type: String[] diff --git a/reference/6/Microsoft.PowerShell.Core/Out-Default.md b/reference/6/Microsoft.PowerShell.Core/Out-Default.md index 53e941bf60d4..0b497ebe34d3 100644 --- a/reference/6/Microsoft.PowerShell.Core/Out-Default.md +++ b/reference/6/Microsoft.PowerShell.Core/Out-Default.md @@ -49,7 +49,7 @@ Accept wildcard characters: False ``` ### -Transcript -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/6/Microsoft.PowerShell.Core/oss.md b/reference/6/Microsoft.PowerShell.Core/oss.md index 945c661d1143..6b08a8fccde0 100644 --- a/reference/6/Microsoft.PowerShell.Core/oss.md +++ b/reference/6/Microsoft.PowerShell.Core/oss.md @@ -64,7 +64,7 @@ If you omit the Stream parameter, the command displays all of the aliases, becau ## PARAMETERS ### -InformationAction -@{Text=} + ```yaml Type: ActionPreference @@ -80,7 +80,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=} + ```yaml Type: String diff --git a/reference/6/Microsoft.PowerShell.Diagnostics/New-WinEvent.md b/reference/6/Microsoft.PowerShell.Diagnostics/New-WinEvent.md index ffa8c505f434..1160aaa87900 100644 --- a/reference/6/Microsoft.PowerShell.Diagnostics/New-WinEvent.md +++ b/reference/6/Microsoft.PowerShell.Diagnostics/New-WinEvent.md @@ -36,7 +36,7 @@ This command uses the **New-WinEvent** cmdlet to create event 45090 for the Micr ## PARAMETERS ### -Id -@{Text=} + ```yaml Type: Int32 @@ -51,7 +51,7 @@ Accept wildcard characters: False ``` ### -Payload -@{Text=} + ```yaml Type: Object[] @@ -66,7 +66,7 @@ Accept wildcard characters: False ``` ### -ProviderName -@{Text=} + ```yaml Type: String @@ -81,7 +81,7 @@ Accept wildcard characters: False ``` ### -Version -@{Text=} + ```yaml Type: Byte diff --git a/reference/6/Microsoft.PowerShell.Management/Convert-Path.md b/reference/6/Microsoft.PowerShell.Management/Convert-Path.md index 76f45341cdbb..93ad90c9629b 100644 --- a/reference/6/Microsoft.PowerShell.Management/Convert-Path.md +++ b/reference/6/Microsoft.PowerShell.Management/Convert-Path.md @@ -57,7 +57,7 @@ This command converts the path to the home directory of the current provider, wh ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -71,7 +71,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Management/Get-ItemPropertyValue.md b/reference/6/Microsoft.PowerShell.Management/Get-ItemPropertyValue.md index 256d47af6866..1ee26202a558 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-ItemPropertyValue.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-ItemPropertyValue.md @@ -169,7 +169,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -183,7 +183,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Management/Get-PSProvider.md b/reference/6/Microsoft.PowerShell.Management/Get-PSProvider.md index b512fa391f55..6d02e16f2428 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-PSProvider.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-PSProvider.md @@ -94,7 +94,7 @@ The Home property value is optional, but for the FileSystem provider, it is defi ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -108,7 +108,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Management/New-Service.md b/reference/6/Microsoft.PowerShell.Management/New-Service.md index 93ecd973ca8d..7c7329bb66aa 100644 --- a/reference/6/Microsoft.PowerShell.Management/New-Service.md +++ b/reference/6/Microsoft.PowerShell.Management/New-Service.md @@ -142,7 +142,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -156,7 +156,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -274,4 +274,4 @@ This cmdlet returns an object that represents the new service. [Suspend-Service](Suspend-Service.md) -[Remove-Service](Remove-Service.md) \ No newline at end of file +[Remove-Service](Remove-Service.md) diff --git a/reference/6/Microsoft.PowerShell.Management/Remove-PSDrive.md b/reference/6/Microsoft.PowerShell.Management/Remove-PSDrive.md index a1c321d1af50..3b9ce5609e23 100644 --- a/reference/6/Microsoft.PowerShell.Management/Remove-PSDrive.md +++ b/reference/6/Microsoft.PowerShell.Management/Remove-PSDrive.md @@ -76,7 +76,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -90,7 +90,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Management/Restart-Service.md b/reference/6/Microsoft.PowerShell.Management/Restart-Service.md index 889c1e4c9349..4961451a4a8d 100644 --- a/reference/6/Microsoft.PowerShell.Management/Restart-Service.md +++ b/reference/6/Microsoft.PowerShell.Management/Restart-Service.md @@ -140,7 +140,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -154,7 +154,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -278,4 +278,4 @@ Otherwise, this cmdlet does not generate any output. [Suspend-Service](Suspend-Service.md) -[Remove-Service](Remove-Service.md) \ No newline at end of file +[Remove-Service](Remove-Service.md) diff --git a/reference/6/Microsoft.PowerShell.Management/Resume-Service.md b/reference/6/Microsoft.PowerShell.Management/Resume-Service.md index 39e93623664c..1a021d3214c5 100644 --- a/reference/6/Microsoft.PowerShell.Management/Resume-Service.md +++ b/reference/6/Microsoft.PowerShell.Management/Resume-Service.md @@ -120,7 +120,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -134,7 +134,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -259,4 +259,4 @@ Otherwise, this cmdlet does not generate any output. [Suspend-Service](Suspend-Service.md) -[Remove-Service](Remove-Service.md) \ No newline at end of file +[Remove-Service](Remove-Service.md) diff --git a/reference/6/Microsoft.PowerShell.Management/Start-Process.md b/reference/6/Microsoft.PowerShell.Management/Start-Process.md index aba4aa71623d..e1173db45a80 100644 --- a/reference/6/Microsoft.PowerShell.Management/Start-Process.md +++ b/reference/6/Microsoft.PowerShell.Management/Start-Process.md @@ -179,7 +179,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -193,7 +193,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Management/Start-Service.md b/reference/6/Microsoft.PowerShell.Management/Start-Service.md index 28a85326b151..d0d997a40172 100644 --- a/reference/6/Microsoft.PowerShell.Management/Start-Service.md +++ b/reference/6/Microsoft.PowerShell.Management/Start-Service.md @@ -161,7 +161,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -175,7 +175,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -305,4 +305,4 @@ Otherwise, this cmdlet does not generate any output. [Suspend-Service](Suspend-Service.md) -[Remove-Service](Remove-Service.md) \ No newline at end of file +[Remove-Service](Remove-Service.md) diff --git a/reference/6/Microsoft.PowerShell.Management/Stop-Service.md b/reference/6/Microsoft.PowerShell.Management/Stop-Service.md index cb0fe1742407..86220491d566 100644 --- a/reference/6/Microsoft.PowerShell.Management/Stop-Service.md +++ b/reference/6/Microsoft.PowerShell.Management/Stop-Service.md @@ -146,7 +146,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -160,7 +160,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -307,4 +307,4 @@ The service names appear in the **Name** column and the display names appear in [Suspend-Service](Suspend-Service.md) -[Remove-Service](Remove-Service.md) \ No newline at end of file +[Remove-Service](Remove-Service.md) diff --git a/reference/6/Microsoft.PowerShell.Management/Suspend-Service.md b/reference/6/Microsoft.PowerShell.Management/Suspend-Service.md index 84c6894fe8d5..94eec91a72a7 100644 --- a/reference/6/Microsoft.PowerShell.Management/Suspend-Service.md +++ b/reference/6/Microsoft.PowerShell.Management/Suspend-Service.md @@ -132,7 +132,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -146,7 +146,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -275,4 +275,4 @@ Otherwise, this cmdlet does not generate any output. [Stop-Service](Stop-Service.md) -[Remove-Service](Remove-Service.md) \ No newline at end of file +[Remove-Service](Remove-Service.md) diff --git a/reference/6/Microsoft.PowerShell.Management/Wait-Process.md b/reference/6/Microsoft.PowerShell.Management/Wait-Process.md index 925f769e1f8a..3d9ca6cacb66 100644 --- a/reference/6/Microsoft.PowerShell.Management/Wait-Process.md +++ b/reference/6/Microsoft.PowerShell.Management/Wait-Process.md @@ -102,7 +102,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -116,7 +116,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md b/reference/6/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md index c0685057b781..48db0b7037e5 100644 --- a/reference/6/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md +++ b/reference/6/Microsoft.PowerShell.Security/Get-AuthenticodeSignature.md @@ -106,7 +106,7 @@ Accept wildcard characters: False ``` ### -Content -@{Text=} + ```yaml Type: Byte[] @@ -121,7 +121,7 @@ Accept wildcard characters: False ``` ### -SourcePathOrExtension -@{Text=} + ```yaml Type: String[] diff --git a/reference/6/Microsoft.PowerShell.Utility/Add-Member.md b/reference/6/Microsoft.PowerShell.Utility/Add-Member.md index 2a939951f93d..d119a02b4ece 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/6/Microsoft.PowerShell.Utility/Add-Member.md @@ -262,7 +262,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -276,7 +276,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Clear-Variable.md b/reference/6/Microsoft.PowerShell.Utility/Clear-Variable.md index bfedfb53753c..00a3de8b7a69 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Clear-Variable.md +++ b/reference/6/Microsoft.PowerShell.Utility/Clear-Variable.md @@ -112,7 +112,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -126,7 +126,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Compare-Object.md b/reference/6/Microsoft.PowerShell.Utility/Compare-Object.md index 921382ec667b..39b32095b6c2 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Compare-Object.md +++ b/reference/6/Microsoft.PowerShell.Utility/Compare-Object.md @@ -146,7 +146,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -160,7 +160,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Debug-Runspace.md b/reference/6/Microsoft.PowerShell.Utility/Debug-Runspace.md index 03b103868f34..b9a664f7bc46 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Debug-Runspace.md +++ b/reference/6/Microsoft.PowerShell.Utility/Debug-Runspace.md @@ -104,7 +104,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -118,7 +118,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Disable-PSBreakpoint.md b/reference/6/Microsoft.PowerShell.Utility/Disable-PSBreakpoint.md index 0bb3d54976cd..695ba81eb707 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Disable-PSBreakpoint.md +++ b/reference/6/Microsoft.PowerShell.Utility/Disable-PSBreakpoint.md @@ -125,7 +125,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -139,7 +139,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md b/reference/6/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md index 7bcba07c65d1..7c9c99825ae5 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md +++ b/reference/6/Microsoft.PowerShell.Utility/Disable-RunspaceDebug.md @@ -63,7 +63,7 @@ The **Disable-RunspaceDebug** cmdlet disables debugging on one or more runspaces ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String[] @@ -78,7 +78,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -92,7 +92,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -105,7 +105,7 @@ Accept wildcard characters: False ``` ### -ProcessName -@{Text=} + ```yaml Type: String @@ -120,7 +120,7 @@ Accept wildcard characters: False ``` ### -Runspace -@{Text=} + ```yaml Type: Runspace[] @@ -135,7 +135,7 @@ Accept wildcard characters: False ``` ### -RunspaceId -@{Text=} + ```yaml Type: Int32[] @@ -150,7 +150,7 @@ Accept wildcard characters: False ``` ### -RunspaceInstanceId -@{Text=} + ```yaml Type: Guid[] @@ -165,7 +165,7 @@ Accept wildcard characters: False ``` ### -RunspaceName -@{Text=} + ```yaml Type: String[] diff --git a/reference/6/Microsoft.PowerShell.Utility/Enable-PSBreakpoint.md b/reference/6/Microsoft.PowerShell.Utility/Enable-PSBreakpoint.md index 4001fefff458..85399df3b192 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Enable-PSBreakpoint.md +++ b/reference/6/Microsoft.PowerShell.Utility/Enable-PSBreakpoint.md @@ -146,7 +146,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -160,7 +160,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md b/reference/6/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md index 66e887b88c75..a044019eab58 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md +++ b/reference/6/Microsoft.PowerShell.Utility/Enable-RunspaceDebug.md @@ -63,7 +63,7 @@ The **Enable-RunspaceDebug** cmdlet enables debugging on runspaces where any bre ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String[] @@ -78,7 +78,7 @@ Accept wildcard characters: False ``` ### -BreakAll -@{Text=} + ```yaml Type: SwitchParameter @@ -93,7 +93,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -107,7 +107,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -120,7 +120,7 @@ Accept wildcard characters: False ``` ### -ProcessName -@{Text=} + ```yaml Type: String @@ -135,7 +135,7 @@ Accept wildcard characters: False ``` ### -Runspace -@{Text=} + ```yaml Type: Runspace[] @@ -150,7 +150,7 @@ Accept wildcard characters: False ``` ### -RunspaceId -@{Text=} + ```yaml Type: Int32[] @@ -165,7 +165,7 @@ Accept wildcard characters: False ``` ### -RunspaceInstanceId -@{Text=} + ```yaml Type: Guid[] @@ -180,7 +180,7 @@ Accept wildcard characters: False ``` ### -RunspaceName -@{Text=} + ```yaml Type: String[] diff --git a/reference/6/Microsoft.PowerShell.Utility/Export-FormatData.md b/reference/6/Microsoft.PowerShell.Utility/Export-FormatData.md index a4a5fb278c2e..a90d1520a03a 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Export-FormatData.md +++ b/reference/6/Microsoft.PowerShell.Utility/Export-FormatData.md @@ -128,7 +128,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -142,7 +142,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Format-Custom.md b/reference/6/Microsoft.PowerShell.Utility/Format-Custom.md index 664d23081f01..332b3f7cda9b 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Format-Custom.md +++ b/reference/6/Microsoft.PowerShell.Utility/Format-Custom.md @@ -152,7 +152,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -166,7 +166,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Format-Hex.md b/reference/6/Microsoft.PowerShell.Utility/Format-Hex.md index 1592b1367322..125545cb9096 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Format-Hex.md +++ b/reference/6/Microsoft.PowerShell.Utility/Format-Hex.md @@ -147,7 +147,7 @@ Accept wildcard characters: False ``` ### -Raw -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/6/Microsoft.PowerShell.Utility/Format-Table.md b/reference/6/Microsoft.PowerShell.Utility/Format-Table.md index e84614c799c5..c49e5a3c9694 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Format-Table.md +++ b/reference/6/Microsoft.PowerShell.Utility/Format-Table.md @@ -248,7 +248,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -262,7 +262,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md b/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md index ba6d66ba8bc2..2ecf27f13eac 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md +++ b/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md @@ -172,7 +172,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -186,7 +186,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-Culture.md b/reference/6/Microsoft.PowerShell.Utility/Get-Culture.md index 18f35ab09123..1905e1e15f89 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-Culture.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-Culture.md @@ -120,7 +120,7 @@ The fifth command uses dot notation to display the value of the FirstDayOfWeek p ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -134,7 +134,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-Event.md b/reference/6/Microsoft.PowerShell.Utility/Get-Event.md index dc0399f047ad..cb570b346359 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-Event.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-Event.md @@ -113,7 +113,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -127,7 +127,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-EventSubscriber.md b/reference/6/Microsoft.PowerShell.Utility/Get-EventSubscriber.md index 150063e7ad72..0f417e2c2db3 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-EventSubscriber.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-EventSubscriber.md @@ -147,7 +147,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -161,7 +161,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-FormatData.md b/reference/6/Microsoft.PowerShell.Utility/Get-FormatData.md index 15fe0ff721b4..788d1a6b930d 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-FormatData.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-FormatData.md @@ -92,7 +92,7 @@ The final command shows an excerpt of the format.ps1xml file content. ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -106,7 +106,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -136,7 +136,7 @@ Accept wildcard characters: False ``` ### -PowerShellVersion -@{Text=} + ```yaml Type: Version diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-Host.md b/reference/6/Microsoft.PowerShell.Utility/Get-Host.md index c3ea486b6cce..789e75c103be 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-Host.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-Host.md @@ -197,7 +197,7 @@ To see all of the properties of the object in the $Host.PrivateData property, ty ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -211,7 +211,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-PSCallStack.md b/reference/6/Microsoft.PowerShell.Utility/Get-PSCallStack.md index fde39f639b58..b61402ad084d 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-PSCallStack.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-PSCallStack.md @@ -79,7 +79,7 @@ The final command is a Step-Out command (o) that exits the debugger and continue ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -93,7 +93,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-Random.md b/reference/6/Microsoft.PowerShell.Utility/Get-Random.md index 35f87130e40c..6f30a86f451b 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-Random.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-Random.md @@ -225,7 +225,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -239,7 +239,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-Runspace.md b/reference/6/Microsoft.PowerShell.Utility/Get-Runspace.md index 744479089417..9daccb771d37 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-Runspace.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-Runspace.md @@ -51,7 +51,7 @@ The **Get-Runspace** cmdlet gets active runspaces in a Windows PowerShell host p ## PARAMETERS ### -Id -@{Text=} + ```yaml Type: Int32[] @@ -66,7 +66,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -80,7 +80,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -93,7 +93,7 @@ Accept wildcard characters: False ``` ### -InstanceId -@{Text=} + ```yaml Type: Guid[] @@ -108,7 +108,7 @@ Accept wildcard characters: False ``` ### -Name -@{Text=} + ```yaml Type: String[] diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md b/reference/6/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md index 588e5fddf2b9..ae1684ddfc48 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-RunspaceDebug.md @@ -63,7 +63,7 @@ The **Get-RunspaceDebug** cmdlet shows runspace debugging options. ## PARAMETERS ### -AppDomainName -@{Text=} + ```yaml Type: String[] @@ -78,7 +78,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -92,7 +92,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -105,7 +105,7 @@ Accept wildcard characters: False ``` ### -ProcessName -@{Text=} + ```yaml Type: String @@ -120,7 +120,7 @@ Accept wildcard characters: False ``` ### -Runspace -@{Text=} + ```yaml Type: Runspace[] @@ -135,7 +135,7 @@ Accept wildcard characters: False ``` ### -RunspaceId -@{Text=} + ```yaml Type: Int32[] @@ -150,7 +150,7 @@ Accept wildcard characters: False ``` ### -RunspaceInstanceId -@{Text=} + ```yaml Type: Guid[] @@ -165,7 +165,7 @@ Accept wildcard characters: False ``` ### -RunspaceName -@{Text=} + ```yaml Type: String[] diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-TraceSource.md b/reference/6/Microsoft.PowerShell.Utility/Get-TraceSource.md index 247a8804062d..f49eb60283a7 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-TraceSource.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-TraceSource.md @@ -47,7 +47,7 @@ This command gets all of the Windows PowerShell components that can be traced. ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -61,7 +61,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-UICulture.md b/reference/6/Microsoft.PowerShell.Utility/Get-UICulture.md index 4c9ae29fd9a7..aeb1b670b429 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-UICulture.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-UICulture.md @@ -62,7 +62,7 @@ To see all of the subproperties of the DateTimeFormat property of the UI culture ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -76,7 +76,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-Unique.md b/reference/6/Microsoft.PowerShell.Utility/Get-Unique.md index 6f4c64650a42..103424343727 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-Unique.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-Unique.md @@ -106,7 +106,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -120,7 +120,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-Variable.md b/reference/6/Microsoft.PowerShell.Utility/Get-Variable.md index 964515f7b62d..64676007ca87 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-Variable.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-Variable.md @@ -94,7 +94,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -108,7 +108,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md b/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md index 82d3f2863d8c..9b10800a07a1 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md +++ b/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md @@ -69,7 +69,7 @@ This eliminates the risk of exposing plain-text passwords in your script. ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -83,7 +83,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Import-LocalizedData.md b/reference/6/Microsoft.PowerShell.Utility/Import-LocalizedData.md index 055fc2db63e3..906bc16b031a 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Import-LocalizedData.md +++ b/reference/6/Microsoft.PowerShell.Utility/Import-LocalizedData.md @@ -237,7 +237,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -251,7 +251,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Invoke-Expression.md b/reference/6/Microsoft.PowerShell.Utility/Invoke-Expression.md index d9f97bad12e6..b0bee8675608 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Invoke-Expression.md +++ b/reference/6/Microsoft.PowerShell.Utility/Invoke-Expression.md @@ -107,7 +107,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -121,7 +121,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Measure-Object.md b/reference/6/Microsoft.PowerShell.Utility/Measure-Object.md index 8d49ecb819e2..1ba952372c8f 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Measure-Object.md +++ b/reference/6/Microsoft.PowerShell.Utility/Measure-Object.md @@ -143,7 +143,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -157,7 +157,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/New-Alias.md b/reference/6/Microsoft.PowerShell.Utility/New-Alias.md index a66d539083c7..876d163cde33 100644 --- a/reference/6/Microsoft.PowerShell.Utility/New-Alias.md +++ b/reference/6/Microsoft.PowerShell.Utility/New-Alias.md @@ -81,7 +81,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -95,7 +95,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/New-Event.md b/reference/6/Microsoft.PowerShell.Utility/New-Event.md index 55ea99449932..049ace2fe5d4 100644 --- a/reference/6/Microsoft.PowerShell.Utility/New-Event.md +++ b/reference/6/Microsoft.PowerShell.Utility/New-Event.md @@ -81,7 +81,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -95,7 +95,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/New-Object.md b/reference/6/Microsoft.PowerShell.Utility/New-Object.md index 6a333cd16809..9deba2f7082a 100644 --- a/reference/6/Microsoft.PowerShell.Utility/New-Object.md +++ b/reference/6/Microsoft.PowerShell.Utility/New-Object.md @@ -210,7 +210,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -224,7 +224,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/New-TimeSpan.md b/reference/6/Microsoft.PowerShell.Utility/New-TimeSpan.md index ec416b5c51dd..415053a4fd01 100644 --- a/reference/6/Microsoft.PowerShell.Utility/New-TimeSpan.md +++ b/reference/6/Microsoft.PowerShell.Utility/New-TimeSpan.md @@ -135,7 +135,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -149,7 +149,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/New-Variable.md b/reference/6/Microsoft.PowerShell.Utility/New-Variable.md index edd6fc46c3e7..62cb1b804e0f 100644 --- a/reference/6/Microsoft.PowerShell.Utility/New-Variable.md +++ b/reference/6/Microsoft.PowerShell.Utility/New-Variable.md @@ -136,7 +136,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -150,7 +150,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Out-File.md b/reference/6/Microsoft.PowerShell.Utility/Out-File.md index 9580006481a5..5b7cc06f3a6d 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Out-File.md +++ b/reference/6/Microsoft.PowerShell.Utility/Out-File.md @@ -175,7 +175,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -189,7 +189,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv @@ -303,7 +303,7 @@ Accept wildcard characters: False ``` ### -NoNewline -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/6/Microsoft.PowerShell.Utility/Out-String.md b/reference/6/Microsoft.PowerShell.Utility/Out-String.md index daea29da2343..c8a93b0eb622 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Out-String.md +++ b/reference/6/Microsoft.PowerShell.Utility/Out-String.md @@ -88,7 +88,7 @@ It should be noted that `-NoNewLine` does not strip newlines embedded within a s ## PARAMETERS ### -InformationAction -@{Text=} + ```yaml Type: ActionPreference @@ -104,7 +104,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=} + ```yaml Type: String diff --git a/reference/6/Microsoft.PowerShell.Utility/Remove-Event.md b/reference/6/Microsoft.PowerShell.Utility/Remove-Event.md index a404953ea5ab..f155bdfaf0dc 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Remove-Event.md +++ b/reference/6/Microsoft.PowerShell.Utility/Remove-Event.md @@ -75,7 +75,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -89,7 +89,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Remove-PSBreakpoint.md b/reference/6/Microsoft.PowerShell.Utility/Remove-PSBreakpoint.md index 997addcc3b32..6dff35dc51b2 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Remove-PSBreakpoint.md +++ b/reference/6/Microsoft.PowerShell.Utility/Remove-PSBreakpoint.md @@ -118,7 +118,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -132,7 +132,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Remove-Variable.md b/reference/6/Microsoft.PowerShell.Utility/Remove-Variable.md index e9df7ceb8968..fc1b90c86701 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Remove-Variable.md +++ b/reference/6/Microsoft.PowerShell.Utility/Remove-Variable.md @@ -89,7 +89,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -103,7 +103,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Select-Object.md b/reference/6/Microsoft.PowerShell.Utility/Select-Object.md index e7cbb544fbbc..b20a15a7fcca 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/6/Microsoft.PowerShell.Utility/Select-Object.md @@ -322,7 +322,7 @@ Accept wildcard characters: False ``` ### -SkipLast -@{Text=} + ```yaml Type: Int32 diff --git a/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md b/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md index 562b520ff850..049b264b4022 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md +++ b/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md @@ -204,7 +204,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -218,7 +218,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Set-Alias.md b/reference/6/Microsoft.PowerShell.Utility/Set-Alias.md index 793c55a757b2..55211b0d5365 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Set-Alias.md +++ b/reference/6/Microsoft.PowerShell.Utility/Set-Alias.md @@ -127,7 +127,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -141,7 +141,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Set-Date.md b/reference/6/Microsoft.PowerShell.Utility/Set-Date.md index 09b9153765a7..95fc2e54bcb3 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Set-Date.md +++ b/reference/6/Microsoft.PowerShell.Utility/Set-Date.md @@ -139,7 +139,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -153,7 +153,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md b/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md index 524b5b745823..2b255f16c570 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md +++ b/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md @@ -110,7 +110,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -124,7 +124,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Set-Variable.md b/reference/6/Microsoft.PowerShell.Utility/Set-Variable.md index 98eaff8541fa..fbe9e0cecbc3 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Set-Variable.md +++ b/reference/6/Microsoft.PowerShell.Utility/Set-Variable.md @@ -152,7 +152,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -166,7 +166,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Sort-Object.md b/reference/6/Microsoft.PowerShell.Utility/Sort-Object.md index b04761e681a1..e2a718aab1d4 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Sort-Object.md +++ b/reference/6/Microsoft.PowerShell.Utility/Sort-Object.md @@ -243,7 +243,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -257,7 +257,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md b/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md index 0ea2ef54218b..396b67bc49f9 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md +++ b/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md @@ -164,7 +164,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -178,7 +178,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Unblock-File.md b/reference/6/Microsoft.PowerShell.Utility/Unblock-File.md index 52068c9c1290..0bbd4bfda216 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Unblock-File.md +++ b/reference/6/Microsoft.PowerShell.Utility/Unblock-File.md @@ -88,7 +88,7 @@ This command shows how to find and unblock Windows PowerShell scripts. ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -102,7 +102,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Unregister-Event.md b/reference/6/Microsoft.PowerShell.Utility/Unregister-Event.md index 8dc0b3908145..06e7548ea122 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Unregister-Event.md +++ b/reference/6/Microsoft.PowerShell.Utility/Unregister-Event.md @@ -87,7 +87,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -101,7 +101,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Update-TypeData.md b/reference/6/Microsoft.PowerShell.Utility/Update-TypeData.md index 9ca06b65467a..da6b69eeec7e 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Update-TypeData.md +++ b/reference/6/Microsoft.PowerShell.Utility/Update-TypeData.md @@ -178,7 +178,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -192,7 +192,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Wait-Debugger.md b/reference/6/Microsoft.PowerShell.Utility/Wait-Debugger.md index 7c248d7517f4..35efdaecc43d 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Wait-Debugger.md +++ b/reference/6/Microsoft.PowerShell.Utility/Wait-Debugger.md @@ -37,7 +37,7 @@ PS C:\> ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -51,7 +51,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Wait-Event.md b/reference/6/Microsoft.PowerShell.Utility/Wait-Event.md index 715b17ab00bd..db544ece0c39 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Wait-Event.md +++ b/reference/6/Microsoft.PowerShell.Utility/Wait-Event.md @@ -75,7 +75,7 @@ If the specified time expires, the wait ends. ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -89,7 +89,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Write-Debug.md b/reference/6/Microsoft.PowerShell.Utility/Write-Debug.md index 2ff820eb7b29..151b23559ecf 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Write-Debug.md +++ b/reference/6/Microsoft.PowerShell.Utility/Write-Debug.md @@ -82,7 +82,7 @@ For more information about $DebugPreference, see about_Preference_Variables. ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -96,7 +96,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Write-Host.md b/reference/6/Microsoft.PowerShell.Utility/Write-Host.md index ec0586e69ec0..0b5acf3c9686 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Write-Host.md +++ b/reference/6/Microsoft.PowerShell.Utility/Write-Host.md @@ -136,7 +136,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -150,7 +150,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Write-Output.md b/reference/6/Microsoft.PowerShell.Utility/Write-Output.md index 47acc45eedb8..fb2f76061d2b 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Write-Output.md +++ b/reference/6/Microsoft.PowerShell.Utility/Write-Output.md @@ -68,7 +68,7 @@ This command adds the *NoEnumerate* parameter to treat a collection or array as ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -82,7 +82,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Write-Progress.md b/reference/6/Microsoft.PowerShell.Utility/Write-Progress.md index 27196f5c2bb5..95c277f2d325 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Write-Progress.md +++ b/reference/6/Microsoft.PowerShell.Utility/Write-Progress.md @@ -150,7 +150,7 @@ Accept wildcard characters: False ``` ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -164,7 +164,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Write-Verbose.md b/reference/6/Microsoft.PowerShell.Utility/Write-Verbose.md index d2e3669fb3dd..d484fba5cdcb 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Write-Verbose.md +++ b/reference/6/Microsoft.PowerShell.Utility/Write-Verbose.md @@ -55,7 +55,7 @@ The second command writes a verbose message. ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -69,7 +69,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/Microsoft.PowerShell.Utility/Write-Warning.md b/reference/6/Microsoft.PowerShell.Utility/Write-Warning.md index 6a37b9f9f57e..7842e516a840 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Write-Warning.md +++ b/reference/6/Microsoft.PowerShell.Utility/Write-Warning.md @@ -89,7 +89,7 @@ For more information about the *WarningAction* common parameter, see about_Commo ## PARAMETERS ### -InformationAction -@{Text=}```yaml +```yaml Type: ActionPreference Parameter Sets: (All) Aliases: infa @@ -103,7 +103,7 @@ Accept wildcard characters: False ``` ### -InformationVariable -@{Text=}```yaml +```yaml Type: String Parameter Sets: (All) Aliases: iv diff --git a/reference/6/PackageManagement/Find-Package.md b/reference/6/PackageManagement/Find-Package.md index c5485b2d4b9b..06f2f41fe868 100644 --- a/reference/6/PackageManagement/Find-Package.md +++ b/reference/6/PackageManagement/Find-Package.md @@ -494,7 +494,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -509,7 +509,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential @@ -524,7 +524,7 @@ Accept wildcard characters: False ``` ### -RoleCapability -@{Text=} + ```yaml Type: String[] diff --git a/reference/6/PackageManagement/Find-PackageProvider.md b/reference/6/PackageManagement/Find-PackageProvider.md index 7d613e8e6a37..e881a6312f01 100644 --- a/reference/6/PackageManagement/Find-PackageProvider.md +++ b/reference/6/PackageManagement/Find-PackageProvider.md @@ -213,7 +213,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -228,7 +228,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PackageManagement/Get-Package.md b/reference/6/PackageManagement/Get-Package.md index 2f07e37bf1da..9ae9cd554410 100644 --- a/reference/6/PackageManagement/Get-Package.md +++ b/reference/6/PackageManagement/Get-Package.md @@ -326,7 +326,7 @@ Accept wildcard characters: False ``` ### -AllowClobber -@{Text=} + ```yaml Type: SwitchParameter @@ -371,7 +371,7 @@ Accept wildcard characters: False ``` ### -NoPathUpdate -@{Text=} + ```yaml Type: SwitchParameter @@ -386,7 +386,7 @@ Accept wildcard characters: False ``` ### -SkipPublisherCheck -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/6/PackageManagement/Install-Package.md b/reference/6/PackageManagement/Install-Package.md index bee50ad7d3e6..b89d5c336565 100644 --- a/reference/6/PackageManagement/Install-Package.md +++ b/reference/6/PackageManagement/Install-Package.md @@ -571,7 +571,7 @@ Accept wildcard characters: False ``` ### -AllowClobber -@{Text=} + ```yaml Type: SwitchParameter @@ -691,7 +691,7 @@ Accept wildcard characters: False ``` ### -NoPathUpdate -@{Text=} + ```yaml Type: SwitchParameter @@ -706,7 +706,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -721,7 +721,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential @@ -736,7 +736,7 @@ Accept wildcard characters: False ``` ### -RoleCapability -@{Text=} + ```yaml Type: String[] @@ -751,7 +751,7 @@ Accept wildcard characters: False ``` ### -SkipPublisherCheck -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/6/PackageManagement/Install-PackageProvider.md b/reference/6/PackageManagement/Install-PackageProvider.md index a56313357e5b..cfbdf744c59e 100644 --- a/reference/6/PackageManagement/Install-PackageProvider.md +++ b/reference/6/PackageManagement/Install-PackageProvider.md @@ -309,7 +309,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -324,7 +324,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PackageManagement/Register-PackageSource.md b/reference/6/PackageManagement/Register-PackageSource.md index 34dc9b16c5aa..09d104f3135c 100644 --- a/reference/6/PackageManagement/Register-PackageSource.md +++ b/reference/6/PackageManagement/Register-PackageSource.md @@ -267,7 +267,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -282,7 +282,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PackageManagement/Save-Package.md b/reference/6/PackageManagement/Save-Package.md index b234e02cbd21..4445e05d8163 100644 --- a/reference/6/PackageManagement/Save-Package.md +++ b/reference/6/PackageManagement/Save-Package.md @@ -564,7 +564,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -579,7 +579,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential @@ -594,7 +594,7 @@ Accept wildcard characters: False ``` ### -RoleCapability -@{Text=} + ```yaml Type: String[] diff --git a/reference/6/PackageManagement/Set-PackageSource.md b/reference/6/PackageManagement/Set-PackageSource.md index e4c5906221e1..86f1662552f2 100644 --- a/reference/6/PackageManagement/Set-PackageSource.md +++ b/reference/6/PackageManagement/Set-PackageSource.md @@ -337,7 +337,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -352,7 +352,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PackageManagement/Uninstall-Package.md b/reference/6/PackageManagement/Uninstall-Package.md index 6f2e58244ff0..5c60a0e9a4c2 100644 --- a/reference/6/PackageManagement/Uninstall-Package.md +++ b/reference/6/PackageManagement/Uninstall-Package.md @@ -389,7 +389,7 @@ Accept wildcard characters: False ``` ### -AllowClobber -@{Text=} + ```yaml Type: SwitchParameter @@ -434,7 +434,7 @@ Accept wildcard characters: False ``` ### -NoPathUpdate -@{Text=} + ```yaml Type: SwitchParameter @@ -449,7 +449,7 @@ Accept wildcard characters: False ``` ### -SkipPublisherCheck -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/6/PowerShellGet/Find-Command.md b/reference/6/PowerShellGet/Find-Command.md index d8555a9a0fae..56044c57037b 100644 --- a/reference/6/PowerShellGet/Find-Command.md +++ b/reference/6/PowerShellGet/Find-Command.md @@ -131,7 +131,7 @@ Accept wildcard characters: False ``` ### -MaximumVersion -@{Text=} + ```yaml Type: Version @@ -207,7 +207,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -222,7 +222,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PowerShellGet/Find-DscResource.md b/reference/6/PowerShellGet/Find-DscResource.md index 93e336bdd1c0..379115242b69 100644 --- a/reference/6/PowerShellGet/Find-DscResource.md +++ b/reference/6/PowerShellGet/Find-DscResource.md @@ -237,7 +237,7 @@ Accept wildcard characters: False ``` ### -MaximumVersion -@{Text=} + ```yaml Type: Version @@ -252,7 +252,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -267,7 +267,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PowerShellGet/Find-Module.md b/reference/6/PowerShellGet/Find-Module.md index 5371fac50a6d..a6765ef852f6 100644 --- a/reference/6/PowerShellGet/Find-Module.md +++ b/reference/6/PowerShellGet/Find-Module.md @@ -323,7 +323,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -338,7 +338,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -353,7 +353,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PowerShellGet/Find-RoleCapability.md b/reference/6/PowerShellGet/Find-RoleCapability.md index 7faa43964f05..c8abaf5dee33 100644 --- a/reference/6/PowerShellGet/Find-RoleCapability.md +++ b/reference/6/PowerShellGet/Find-RoleCapability.md @@ -211,7 +211,7 @@ Accept wildcard characters: False ``` ### -MaximumVersion -@{Text=} + ```yaml Type: Version @@ -226,7 +226,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -241,7 +241,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PowerShellGet/Find-Script.md b/reference/6/PowerShellGet/Find-Script.md index 6a44288ed9ee..cc009834d5d6 100644 --- a/reference/6/PowerShellGet/Find-Script.md +++ b/reference/6/PowerShellGet/Find-Script.md @@ -74,7 +74,7 @@ Type : Script Description : Description for the Required-Script2 script Author : pattif CompanyName : Microsoft Corporation -Copyright : © 2015 Microsoft Corporation. All rights reserved. +Copyright : ???? 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/14/2015 2:37:01 PM LicenseUri : http://required-script2.com/license ProjectUri : http://required-script2.com/ @@ -343,7 +343,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -358,7 +358,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -373,7 +373,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PowerShellGet/Install-Module.md b/reference/6/PowerShellGet/Install-Module.md index 17a8cad30478..3f63e45fe787 100644 --- a/reference/6/PowerShellGet/Install-Module.md +++ b/reference/6/PowerShellGet/Install-Module.md @@ -238,7 +238,7 @@ Accept wildcard characters: False ``` ### -AllowClobber -@{Text=} + ```yaml Type: SwitchParameter @@ -253,7 +253,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -283,7 +283,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -298,7 +298,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential @@ -313,7 +313,7 @@ Accept wildcard characters: False ``` ### -SkipPublisherCheck -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/6/PowerShellGet/Install-Script.md b/reference/6/PowerShellGet/Install-Script.md index 586d66baed73..37dfb6e050d6 100644 --- a/reference/6/PowerShellGet/Install-Script.md +++ b/reference/6/PowerShellGet/Install-Script.md @@ -57,7 +57,7 @@ Type : Script Description : Description for the Required-Script2 script Author : pattif CompanyName : -Copyright : © 2015 Microsoft Corporation. All rights reserved. +Copyright : ???? 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/15/2015 12:42:39 AM LicenseUri : http://required-script2.com/license ProjectUri : http://required-script2.com/ @@ -96,7 +96,7 @@ Type : Script Description : Description for the Required-Script3 script Author : pattif CompanyName : -Copyright : © 2015 Microsoft Corporation. All rights reserved. +Copyright : ???? 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/15/2015 12:42:45 AM LicenseUri : http://required-script3.com/license ProjectUri : http://required-script3.com/ @@ -318,7 +318,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -348,7 +348,7 @@ Accept wildcard characters: False ``` ### -NoPathUpdate -@{Text=} + ```yaml Type: SwitchParameter @@ -363,7 +363,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -378,7 +378,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PowerShellGet/Publish-Module.md b/reference/6/PowerShellGet/Publish-Module.md index d6d534e97d6b..8883eb488b51 100644 --- a/reference/6/PowerShellGet/Publish-Module.md +++ b/reference/6/PowerShellGet/Publish-Module.md @@ -79,7 +79,7 @@ Accept wildcard characters: False ``` ### -FormatVersion -@{Text=} + ```yaml Type: Version @@ -270,7 +270,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -285,7 +285,7 @@ Accept wildcard characters: False ``` ### -Force -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/6/PowerShellGet/Publish-Script.md b/reference/6/PowerShellGet/Publish-Script.md index b816d20f0ee0..4e73dee99fbb 100644 --- a/reference/6/PowerShellGet/Publish-Script.md +++ b/reference/6/PowerShellGet/Publish-Script.md @@ -204,7 +204,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -219,7 +219,7 @@ Accept wildcard characters: False ``` ### -Force -@{Text=} + ```yaml Type: SwitchParameter diff --git a/reference/6/PowerShellGet/Register-PSRepository.md b/reference/6/PowerShellGet/Register-PSRepository.md index 44746f3de574..b6edc64212bd 100644 --- a/reference/6/PowerShellGet/Register-PSRepository.md +++ b/reference/6/PowerShellGet/Register-PSRepository.md @@ -63,7 +63,7 @@ The second command gets registered repositories and displays the results. ## PARAMETERS ### -InstallationPolicy -@{Text=} + ```yaml Type: String @@ -79,7 +79,7 @@ Accept wildcard characters: False ``` ### -Name -@{Text=} + ```yaml Type: String @@ -94,7 +94,7 @@ Accept wildcard characters: False ``` ### -PackageManagementProvider -@{Text=} + ```yaml Type: String @@ -109,7 +109,7 @@ Accept wildcard characters: False ``` ### -PublishLocation -@{Text=} + ```yaml Type: Uri @@ -124,7 +124,7 @@ Accept wildcard characters: False ``` ### -ScriptPublishLocation -@{Text=} + ```yaml Type: Uri @@ -139,7 +139,7 @@ Accept wildcard characters: False ``` ### -ScriptSourceLocation -@{Text=} + ```yaml Type: Uri @@ -154,7 +154,7 @@ Accept wildcard characters: False ``` ### -SourceLocation -@{Text=} + ```yaml Type: Uri @@ -169,7 +169,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -184,7 +184,7 @@ Accept wildcard characters: False ``` ### -Default -@{Text=} + ```yaml Type: SwitchParameter @@ -199,7 +199,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -214,7 +214,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PowerShellGet/Save-Module.md b/reference/6/PowerShellGet/Save-Module.md index 5201ac0a60d2..b243bb0aeb0f 100644 --- a/reference/6/PowerShellGet/Save-Module.md +++ b/reference/6/PowerShellGet/Save-Module.md @@ -260,7 +260,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -290,7 +290,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -305,7 +305,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PowerShellGet/Save-Script.md b/reference/6/PowerShellGet/Save-Script.md index 9751d35b676e..fc6aaae311c8 100644 --- a/reference/6/PowerShellGet/Save-Script.md +++ b/reference/6/PowerShellGet/Save-Script.md @@ -223,7 +223,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -253,7 +253,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -268,7 +268,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PowerShellGet/Set-PSRepository.md b/reference/6/PowerShellGet/Set-PSRepository.md index 8aa03787f6a2..7444b8dea935 100644 --- a/reference/6/PowerShellGet/Set-PSRepository.md +++ b/reference/6/PowerShellGet/Set-PSRepository.md @@ -106,7 +106,7 @@ Accept wildcard characters: False ``` ### -ScriptPublishLocation -@{Text=} + ```yaml Type: Uri @@ -121,7 +121,7 @@ Accept wildcard characters: False ``` ### -ScriptSourceLocation -@{Text=} + ```yaml Type: Uri @@ -152,7 +152,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -167,7 +167,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -182,7 +182,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PowerShellGet/Update-Module.md b/reference/6/PowerShellGet/Update-Module.md index 0a1100620b11..f385461bbd66 100644 --- a/reference/6/PowerShellGet/Update-Module.md +++ b/reference/6/PowerShellGet/Update-Module.md @@ -174,7 +174,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -189,7 +189,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -204,7 +204,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential diff --git a/reference/6/PowerShellGet/Update-Script.md b/reference/6/PowerShellGet/Update-Script.md index 368696986ef4..324b802ecccc 100644 --- a/reference/6/PowerShellGet/Update-Script.md +++ b/reference/6/PowerShellGet/Update-Script.md @@ -135,7 +135,7 @@ Accept wildcard characters: False ``` ### -Credential -@{Text=} + ```yaml Type: PSCredential @@ -150,7 +150,7 @@ Accept wildcard characters: False ``` ### -Proxy -@{Text=} + ```yaml Type: Uri @@ -165,7 +165,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential -@{Text=} + ```yaml Type: PSCredential From efba6514346594ba0867e1ae5a85dc7022f82c81 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 7 Nov 2017 10:59:47 -0800 Subject: [PATCH 004/188] fixing UTF8 characters --- .../Unprotect-CmsMessage.md | 18 ++--- .../Microsoft.PowerShell.Core/Get-Module.md | 34 ++++---- .../Unprotect-CmsMessage.md | 18 ++--- reference/5.1/PowershellGet/Find-Script.md | 34 ++++---- reference/5.1/PowershellGet/Install-Script.md | 44 +++++----- .../6/Microsoft.PowerShell.Core/Get-Module.md | 34 ++++---- .../New-ModuleManifest.md | 80 +++++++++---------- reference/6/PowerShellGet/Find-Script.md | 34 ++++---- reference/6/PowerShellGet/Install-Script.md | 44 +++++----- 9 files changed, 170 insertions(+), 170 deletions(-) diff --git a/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md b/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md index 5a56a41010e8..49135884a825 100644 --- a/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md +++ b/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md @@ -56,7 +56,7 @@ The **Unprotect-CmsMessage** cmdlet returns the decrypted content. ### Example 1: Decrypt a message ``` -PS C:\> C:\Users\gabyk\Documents\PowerShell_ISEUnprotect-CmsMessage -LiteralPath "C:\Users\Test\Documents\PowerShell ISE\Future_Plans.txt" -To '???????0f 8j b1 ab e0 ce 35 1d 67 d2 f2 6f a2 d2 00 cl 22 z9 m9 85' +PS C:\> C:\Users\gabyk\Documents\PowerShell_ISEUnprotect-CmsMessage -LiteralPath "C:\Users\Test\Documents\PowerShell ISE\Future_Plans.txt" -To '0f 8j b1 ab e0 ce 35 1d 67 d2 f2 6f a2 d2 00 cl 22 z9 m9 85' Try the new Break All command ``` @@ -72,7 +72,7 @@ Specifies an encrypted string, or a variable containing an encrypted string. ```yaml Type: String Parameter Sets: ByContent -Aliases: +Aliases: Required: True Position: 0 @@ -87,7 +87,7 @@ Specifies an event log record ID that represents a CMS encryption operation. ```yaml Type: PSObject Parameter Sets: ByWinEvent -Aliases: +Aliases: Required: True Position: 0 @@ -102,7 +102,7 @@ Accept wildcard characters: False ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -121,7 +121,7 @@ Single quotation marks tell Windows PowerShell not to interpret any characters a ```yaml Type: String Parameter Sets: ByLiteralPath -Aliases: +Aliases: Required: True Position: 0 @@ -136,7 +136,7 @@ Specifies the path to encrypted content that you want to decrypt. ```yaml Type: String Parameter Sets: ByPath -Aliases: +Aliases: Required: True Position: 0 @@ -146,7 +146,7 @@ Accept wildcard characters: False ``` ### -To -Specifies one or more CMS message recipients, identified in any of the following formats. +Specifies one or more CMS message recipients, identified in any of the following formats. - An actual certificate (as retrieved from the certificate provider). - Path to the a file containing the certificate. @@ -157,7 +157,7 @@ Specifies one or more CMS message recipients, identified in any of the following ```yaml Type: CmsMessageRecipient[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 1 @@ -171,7 +171,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS -### +### You can pipe an object containing encrypted content to **Unprotect-CmsMessage**. ## OUTPUTS diff --git a/reference/5.1/Microsoft.PowerShell.Core/Get-Module.md b/reference/5.1/Microsoft.PowerShell.Core/Get-Module.md index 72ecec08ab61..7be5573af794 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Get-Module.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Get-Module.md @@ -102,8 +102,8 @@ This command gets all of the exported files for all available modules. ### Example 4: Get a module by its fully qualified name ``` PS C:\> Get-Module -FullyQualifiedName @{ModuleName="Microsoft.PowerShell.Management";ModuleVersion="3.1.0.0"} | Format-Table -Property Name,Version -Name Version ----- ------- +Name Version +---- ------- Microsoft.PowerShell.Management 3.1.0.0 ``` @@ -212,7 +212,7 @@ PS C:\> Get-Content $m.Path GUID="{8FA5064B-8479-4c5c-86EA-0D311FE48875}" Author="Microsoft Corporation" CompanyName="Microsoft Corporation" -Copyright="???? Microsoft Corporation. All rights reserved." +Copyright="?Microsoft Corporation. All rights reserved." ModuleVersion="1.0.0.0" Description="Windows Powershell File Transfer Module" PowerShellVersion="2.0" @@ -299,7 +299,7 @@ Without this parameter, **Get-Module** gets only the default module in each modu ```yaml Type: SwitchParameter Parameter Sets: Loaded, Available -Aliases: +Aliases: Required: False Position: Named @@ -319,7 +319,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String Parameter Sets: CimSession -Aliases: +Aliases: Required: False Position: Named @@ -339,7 +339,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: Uri Parameter Sets: CimSession -Aliases: +Aliases: Required: False Position: Named @@ -363,7 +363,7 @@ However, you can import only CIM-based and Cmdlet Definition XML (CDXML)-based m ```yaml Type: CimSession Parameter Sets: CimSession -Aliases: +Aliases: Required: True Position: Named @@ -375,10 +375,10 @@ Accept wildcard characters: False ### -FullyQualifiedName Specifies names of modules in the form of **ModuleSpecification** objects. These objects are described in the Remarks section of [ModuleSpecification Constructor (Hashtable)](https://msdn.microsoft.com/library/jj136290) in the MSDN library. -For example, the *FullyQualifiedName* parameter accepts a module name that is specified in the following formats: +For example, the *FullyQualifiedName* parameter accepts a module name that is specified in the following formats: @{ModuleName = "modulename"; ModuleVersion = "version_number"} -@{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}. +@{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}. **ModuleName** and **ModuleVersion** are required, but **Guid** is optional. @@ -387,7 +387,7 @@ You cannot specify the *FullyQualifiedName* parameter in the same command as a * ```yaml Type: ModuleSpecification[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -399,13 +399,13 @@ Accept wildcard characters: False ### -ListAvailable Indicates that this cmdlet gets all installed modules. **Get-Module** gets modules in paths listed in the **PSModulePath** environment variable. -Without this parameter, **Get-Module** gets only the modules that are both listed in the **PSModulePath** environment variable, and that are loaded in the current session. +Without this parameter, **Get-Module** gets only the modules that are both listed in the **PSModulePath** environment variable, and that are loaded in the current session. *ListAvailable* does not return information about modules that are not found in the **PSModulePath** environment variable, even if those modules are loaded in the current session. ```yaml Type: SwitchParameter Parameter Sets: Available -Aliases: +Aliases: Required: True Position: Named @@ -417,7 +417,7 @@ Accept wildcard characters: False ```yaml Type: SwitchParameter Parameter Sets: PsSession, CimSession -Aliases: +Aliases: Required: False Position: Named @@ -438,7 +438,7 @@ To return modules by specifying a GUID, use *FullyQualifiedName* instead. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 0 @@ -453,7 +453,7 @@ Accept wildcard characters: False ```yaml Type: String Parameter Sets: Available, PsSession -Aliases: +Aliases: Required: False Position: Named @@ -475,7 +475,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: PSSession Parameter Sets: PsSession -Aliases: +Aliases: Required: True Position: Named @@ -498,7 +498,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: SwitchParameter Parameter Sets: Available, PsSession, CimSession -Aliases: +Aliases: Required: False Position: Named diff --git a/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md b/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md index 5a56a41010e8..49135884a825 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md +++ b/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md @@ -56,7 +56,7 @@ The **Unprotect-CmsMessage** cmdlet returns the decrypted content. ### Example 1: Decrypt a message ``` -PS C:\> C:\Users\gabyk\Documents\PowerShell_ISEUnprotect-CmsMessage -LiteralPath "C:\Users\Test\Documents\PowerShell ISE\Future_Plans.txt" -To '???????0f 8j b1 ab e0 ce 35 1d 67 d2 f2 6f a2 d2 00 cl 22 z9 m9 85' +PS C:\> C:\Users\gabyk\Documents\PowerShell_ISEUnprotect-CmsMessage -LiteralPath "C:\Users\Test\Documents\PowerShell ISE\Future_Plans.txt" -To '0f 8j b1 ab e0 ce 35 1d 67 d2 f2 6f a2 d2 00 cl 22 z9 m9 85' Try the new Break All command ``` @@ -72,7 +72,7 @@ Specifies an encrypted string, or a variable containing an encrypted string. ```yaml Type: String Parameter Sets: ByContent -Aliases: +Aliases: Required: True Position: 0 @@ -87,7 +87,7 @@ Specifies an event log record ID that represents a CMS encryption operation. ```yaml Type: PSObject Parameter Sets: ByWinEvent -Aliases: +Aliases: Required: True Position: 0 @@ -102,7 +102,7 @@ Accept wildcard characters: False ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -121,7 +121,7 @@ Single quotation marks tell Windows PowerShell not to interpret any characters a ```yaml Type: String Parameter Sets: ByLiteralPath -Aliases: +Aliases: Required: True Position: 0 @@ -136,7 +136,7 @@ Specifies the path to encrypted content that you want to decrypt. ```yaml Type: String Parameter Sets: ByPath -Aliases: +Aliases: Required: True Position: 0 @@ -146,7 +146,7 @@ Accept wildcard characters: False ``` ### -To -Specifies one or more CMS message recipients, identified in any of the following formats. +Specifies one or more CMS message recipients, identified in any of the following formats. - An actual certificate (as retrieved from the certificate provider). - Path to the a file containing the certificate. @@ -157,7 +157,7 @@ Specifies one or more CMS message recipients, identified in any of the following ```yaml Type: CmsMessageRecipient[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 1 @@ -171,7 +171,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS -### +### You can pipe an object containing encrypted content to **Unprotect-CmsMessage**. ## OUTPUTS diff --git a/reference/5.1/PowershellGet/Find-Script.md b/reference/5.1/PowershellGet/Find-Script.md index 3ad8164e86c5..a091b39c6f8c 100644 --- a/reference/5.1/PowershellGet/Find-Script.md +++ b/reference/5.1/PowershellGet/Find-Script.md @@ -74,14 +74,14 @@ Type : Script Description : Description for the Required-Script2 script Author : pattif CompanyName : Microsoft Corporation -Copyright : ???? 2015 Microsoft Corporation. All rights reserved. +Copyright : 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/14/2015 2:37:01 PM LicenseUri : http://required-script2.com/license ProjectUri : http://required-script2.com/ IconUri : http://required-script2.com/icon -Tags : {, Tag1, Tag2, Tag-Required-Script2-2.0...} +Tags : {, Tag1, Tag2, Tag-Required-Script2-2.0...} Includes : {Function, DscResource, Cmdlet, Command} -PowerShellGetFormatVersion : +PowerShellGetFormatVersion : ReleaseNotes : Required-Script2 release notes Dependencies : {} RepositorySourceLocation : C:\MyLocalRepo @@ -178,7 +178,7 @@ Indicates that this operation finds all script versions. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -194,7 +194,7 @@ A command can be a function or workflow. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -209,7 +209,7 @@ Accept wildcard characters: False ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -224,7 +224,7 @@ Finds scripts based on the PackageManagement provider-specific search syntax. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -239,7 +239,7 @@ Indicates that this operation gets all scripts that are dependent upon the scrip ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -255,7 +255,7 @@ The acceptable values for this parameter are: Function, Workflow. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Function, Workflow Required: False @@ -272,7 +272,7 @@ The *MaximumVersion* and *RequiredVersion* parameters are mutually exclusive; yo ```yaml Type: Version Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -288,7 +288,7 @@ The *MinimumVersion* and *RequiredVersion* parameters are mutually exclusive; yo ```yaml Type: Version Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -303,7 +303,7 @@ Specifies an array of names of scripts to find. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 0 @@ -318,7 +318,7 @@ Specifies a proxy server for the request, rather than connecting directly to the ```yaml Type: Uri Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -333,7 +333,7 @@ Specifies a user account that has permission to use the proxy server that is spe ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -348,7 +348,7 @@ Specifies the friendly name of a repository that has been registered by running ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -363,7 +363,7 @@ Specifies the exact version number of the script to find. ```yaml Type: Version Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -378,7 +378,7 @@ Specifies an array of tags. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named diff --git a/reference/5.1/PowershellGet/Install-Script.md b/reference/5.1/PowershellGet/Install-Script.md index 7eb13f6da42a..d68a270f7cdf 100644 --- a/reference/5.1/PowershellGet/Install-Script.md +++ b/reference/5.1/PowershellGet/Install-Script.md @@ -50,21 +50,21 @@ CommandType Name Version So ExternalScript Required-Script2.ps1 2.0 C:\Users\pattif\Documents\WindowsPowerShell\Scripts\Required-Script2.ps1 PS C:\> Get-InstalledScript -Name "Required-Script2" Version Name Type Repository Description ------- ---- ---- ---------- ----------- -2.5 Required-Script2 Script local1 Description for the Required-Script2 script PS C:\> Get-InstalledScript -Name "Required-Script2" | Format-List * +2.5 Required-Script2 Script local1 Description for the Required-Script2 script PS C:\> Get-InstalledScript -Name "Required-Script2" | Format-List * Name : Required-Script2 Version : 2.5 Type : Script Description : Description for the Required-Script2 script Author : pattif -CompanyName : -Copyright : ???? 2015 Microsoft Corporation. All rights reserved. +CompanyName : +Copyright : 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/15/2015 12:42:39 AM LicenseUri : http://required-script2.com/license ProjectUri : http://required-script2.com/ IconUri : http://required-script2.com/icon -Tags : {Tag1, Tag2, Tag-Required-Script2-2.5, PSScript...} +Tags : {Tag1, Tag2, Tag-Required-Script2-2.5, PSScript...} Includes : {Function, DscResource, Cmdlet, Command} -PowerShellGetFormatVersion : +PowerShellGetFormatVersion : ReleaseNotes : Required-Script2 release notes Dependencies : {} RepositorySourceLocation : http://pattif-dev:8765/api/v2/ @@ -89,21 +89,21 @@ PS C:\> Install-Script -Repository "Local1" -Name "Required-Script3" -Scope "All PS C:\> Get-InstalledScript -Name "Required-Script3" Version Name Type Repository Description ------- ---- ---- ---------- ----------- -2.5 Required-Script3 Script local1 Description for the Required-Script3 script PS C:\> Get-InstalledScript -Name "Required-Script3" | Format-List * +2.5 Required-Script3 Script local1 Description for the Required-Script3 script PS C:\> Get-InstalledScript -Name "Required-Script3" | Format-List * Name : Required-Script3 Version : 2.5 Type : Script Description : Description for the Required-Script3 script Author : pattif -CompanyName : -Copyright : ???? 2015 Microsoft Corporation. All rights reserved. +CompanyName : +Copyright : ???? 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/15/2015 12:42:45 AM LicenseUri : http://required-script3.com/license ProjectUri : http://required-script3.com/ IconUri : http://required-script3.com/icon -Tags : {Tag1, Tag2, Tag-Required-Script3-2.5, PSScript...} +Tags : {Tag1, Tag2, Tag-Required-Script3-2.5, PSScript...} Includes : {Function, DscResource, Cmdlet, Command} -PowerShellGetFormatVersion : +PowerShellGetFormatVersion : ReleaseNotes : Required-Script3 release notes Dependencies : {} RepositorySourceLocation : http://pattif-dev:8765/api/v2/ @@ -192,7 +192,7 @@ Specifies a user account that has rights to install a script for a specified pac ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -207,7 +207,7 @@ Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -222,7 +222,7 @@ Accept wildcard characters: False ```yaml Type: PSObject[] Parameter Sets: InputObject -Aliases: +Aliases: Required: True Position: 0 @@ -239,7 +239,7 @@ This parameter accepts the wildcard character (*). ```yaml Type: Version Parameter Sets: NameParameterSet -Aliases: +Aliases: Required: False Position: Named @@ -255,7 +255,7 @@ The *MinimumVersion* and *RequiredVersion* parameters are mutually exclusive; yo ```yaml Type: Version Parameter Sets: NameParameterSet -Aliases: +Aliases: Required: False Position: Named @@ -270,7 +270,7 @@ Specifies an array of names of scripts to install. ```yaml Type: String[] Parameter Sets: NameParameterSet -Aliases: +Aliases: Required: True Position: 0 @@ -285,7 +285,7 @@ Accept wildcard characters: False ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -300,7 +300,7 @@ Specifies a proxy server for the request, rather than connecting directly to the ```yaml Type: Uri Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -315,7 +315,7 @@ Specifies a user account that has permission to use the proxy server that is spe ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -331,7 +331,7 @@ The default is all registered repositories. ```yaml Type: String[] Parameter Sets: NameParameterSet -Aliases: +Aliases: Required: False Position: Named @@ -346,7 +346,7 @@ Specifies the exact version number of the script to install. ```yaml Type: Version Parameter Sets: NameParameterSet -Aliases: +Aliases: Required: False Position: Named @@ -366,7 +366,7 @@ The CurrentUser scope specifies to install the script in $home\Documents\Windows ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Accepted values: CurrentUser, AllUsers Required: False diff --git a/reference/6/Microsoft.PowerShell.Core/Get-Module.md b/reference/6/Microsoft.PowerShell.Core/Get-Module.md index 8b69589bd0a6..5427512d3467 100644 --- a/reference/6/Microsoft.PowerShell.Core/Get-Module.md +++ b/reference/6/Microsoft.PowerShell.Core/Get-Module.md @@ -102,8 +102,8 @@ This command gets all of the exported files for all available modules. ### Example 4: Get a module by its fully qualified name ``` PS C:\> Get-Module -FullyQualifiedName @{ModuleName="Microsoft.PowerShell.Management";ModuleVersion="3.1.0.0"} | Format-Table -Property Name,Version -Name Version ----- ------- +Name Version +---- ------- Microsoft.PowerShell.Management 3.1.0.0 ``` @@ -212,7 +212,7 @@ PS C:\> Get-Content $m.Path GUID="{8FA5064B-8479-4c5c-86EA-0D311FE48875}" Author="Microsoft Corporation" CompanyName="Microsoft Corporation" -Copyright="???? Microsoft Corporation. All rights reserved." +Copyright="Microsoft Corporation. All rights reserved." ModuleVersion="1.0.0.0" Description="Windows Powershell File Transfer Module" PowerShellVersion="2.0" @@ -299,7 +299,7 @@ Without this parameter, **Get-Module** gets only the default module in each modu ```yaml Type: SwitchParameter Parameter Sets: Loaded, Available -Aliases: +Aliases: Required: False Position: Named @@ -319,7 +319,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String Parameter Sets: CimSession -Aliases: +Aliases: Required: False Position: Named @@ -339,7 +339,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: Uri Parameter Sets: CimSession -Aliases: +Aliases: Required: False Position: Named @@ -363,7 +363,7 @@ However, you can import only CIM-based and Cmdlet Definition XML (CDXML)-based m ```yaml Type: CimSession Parameter Sets: CimSession -Aliases: +Aliases: Required: True Position: Named @@ -375,10 +375,10 @@ Accept wildcard characters: False ### -FullyQualifiedName Specifies names of modules in the form of **ModuleSpecification** objects. These objects are described in the Remarks section of [ModuleSpecification Constructor (Hashtable)](https://msdn.microsoft.com/library/jj136290) in the MSDN library. -For example, the *FullyQualifiedName* parameter accepts a module name that is specified in the following formats: +For example, the *FullyQualifiedName* parameter accepts a module name that is specified in the following formats: @{ModuleName = "modulename"; ModuleVersion = "version_number"} -@{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}. +@{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}. **ModuleName** and **ModuleVersion** are required, but **Guid** is optional. @@ -387,7 +387,7 @@ You cannot specify the *FullyQualifiedName* parameter in the same command as a * ```yaml Type: ModuleSpecification[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -399,13 +399,13 @@ Accept wildcard characters: False ### -ListAvailable Indicates that this cmdlet gets all installed modules. **Get-Module** gets modules in paths listed in the **PSModulePath** environment variable. -Without this parameter, **Get-Module** gets only the modules that are both listed in the **PSModulePath** environment variable, and that are loaded in the current session. +Without this parameter, **Get-Module** gets only the modules that are both listed in the **PSModulePath** environment variable, and that are loaded in the current session. *ListAvailable* does not return information about modules that are not found in the **PSModulePath** environment variable, even if those modules are loaded in the current session. ```yaml Type: SwitchParameter Parameter Sets: Available -Aliases: +Aliases: Required: True Position: Named @@ -417,7 +417,7 @@ Accept wildcard characters: False ```yaml Type: SwitchParameter Parameter Sets: PsSession, CimSession -Aliases: +Aliases: Required: False Position: Named @@ -438,7 +438,7 @@ To return modules by specifying a GUID, use *FullyQualifiedName* instead. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 0 @@ -460,7 +460,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: PSSession Parameter Sets: PsSession -Aliases: +Aliases: Required: True Position: Named @@ -483,7 +483,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: SwitchParameter Parameter Sets: Available, PsSession, CimSession -Aliases: +Aliases: Required: False Position: Named @@ -498,7 +498,7 @@ Accept wildcard characters: False ```yaml Type: String Parameter Sets: Available, PsSession -Aliases: +Aliases: Required: False Position: Named diff --git a/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md b/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md index 39f47a75b26c..a5a12f94a2f7 100644 --- a/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md +++ b/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md @@ -151,8 +151,8 @@ For information about the HelpInfo XML file, see "Supporting Updatable Help" in ``` PS C:\> Get-Module PSScheduledJob -List | Format-List -Property * -LogPipelineExecutionDetails : -FalseName : +LogPipelineExecutionDetails : +FalseName : PSScheduledJobPath : C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\PSScheduledJob\PSScheduledJob.psd1 Definition : Description : @@ -161,7 +161,7 @@ HelpInfoUri : http://go.microsoft.com/fwlink/?LinkID=223911 ModuleBase : C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\PSScheduledJob PrivateData : Version : 1.0.0.0 -ModuleType : +ModuleType : BinaryAuthor : Microsoft Corporation AccessMode : ReadWrite ClrVersion : 4.0 @@ -210,7 +210,7 @@ IscsiTarget 4.0 Kds 4.0 Microsoft.PowerShell.Diagnostics 4.0 Microsoft.PowerShell.Host 4.0 -Microsoft.PowerShell.Management 4.0??????? +Microsoft.PowerShell.Management 4.0 ``` This example shows how to get the module manifest values of a module. @@ -238,7 +238,7 @@ If you omit this parameter, **New-ModuleManifest** creates an **AliasesToExport* ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -255,7 +255,7 @@ If you omit this parameter, **New-ModuleManifest** creates an **Author** key wit ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -270,7 +270,7 @@ Specifies the minimum version of the Common Language Runtime (CLR) of the Micros ```yaml Type: Version Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -291,7 +291,7 @@ If you omit this parameter, **New-ModuleManifest** creates a **CmdletsToExport** ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -308,7 +308,7 @@ If you omit this parameter, **New-ModuleManifest** creates a **CompanyName** key ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -341,7 +341,7 @@ All rights reserved." where \ is the current year and \ is the ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -361,7 +361,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -376,7 +376,7 @@ Describes the contents of the module. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -391,7 +391,7 @@ Specifies the minimum version of the Microsoft .NET Framework that the module re ```yaml Type: Version Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -406,7 +406,7 @@ Accept wildcard characters: False ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -424,7 +424,7 @@ The files listed in the key are not automatically exported with the module. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -442,7 +442,7 @@ Because formatting files are not scoped, they affect all session states in the s ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -463,7 +463,7 @@ If you omit this parameter, **New-ModuleManifest** creates an **FunctionsToExpor ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -483,7 +483,7 @@ To create a new GUID in Windows PowerShell, type "\[guid\]::NewGuid()". ```yaml Type: Guid Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -506,7 +506,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -521,7 +521,7 @@ Accept wildcard characters: False ```yaml Type: Uri Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -536,7 +536,7 @@ Accept wildcard characters: False ```yaml Type: Uri Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -559,7 +559,7 @@ The modules that are listed in the value of this key are not automatically proce ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -577,7 +577,7 @@ If you omit this parameter, **New-ModuleManifest** creates a **ModuleVersion** k ```yaml Type: Version Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -606,7 +606,7 @@ To run a script in the caller's session state, list the script file name in the ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -622,7 +622,7 @@ By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -646,7 +646,7 @@ To use a variable, include the **Path** parameter in the command. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 0 @@ -665,7 +665,7 @@ To find the name of a host program, in the program, type `$host.name`. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -681,7 +681,7 @@ Enter a version number, such as 1.1. ```yaml Type: Version Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -697,7 +697,7 @@ For example, you can enter 3.0, 4.0, or 5.0 as the value of this parameter. ```yaml Type: Version Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -712,7 +712,7 @@ Specifies data that is passed to the module when it is imported. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -729,7 +729,7 @@ None indicates unknown or unspecified. ```yaml Type: ProcessorArchitecture Parameter Sets: (All) -Aliases: +Aliases: Accepted values: None, MSIL, X86, IA64, Amd64, Arm Required: False @@ -745,7 +745,7 @@ Accept wildcard characters: False ```yaml Type: Uri Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -760,7 +760,7 @@ Specifies release notes. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -780,7 +780,7 @@ This includes assemblies that must be loaded to update any formatting or type fi ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -805,7 +805,7 @@ It just verifies that the required modules are in the global session state. ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -848,7 +848,7 @@ To specify scripts that run in the module's session state, use the **NestedModul ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -863,7 +863,7 @@ Accept wildcard characters: False ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -881,7 +881,7 @@ Because type files are not scoped, they affect all session states in the session ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -902,7 +902,7 @@ If you omit this parameter, **New-ModuleManifest** creates a **VariablesToExport ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -934,7 +934,7 @@ For information about PSEdition, see [Modules with compatible PowerShell Edition ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Desktop, Core Required: False diff --git a/reference/6/PowerShellGet/Find-Script.md b/reference/6/PowerShellGet/Find-Script.md index cc009834d5d6..aa62fb4473cb 100644 --- a/reference/6/PowerShellGet/Find-Script.md +++ b/reference/6/PowerShellGet/Find-Script.md @@ -74,14 +74,14 @@ Type : Script Description : Description for the Required-Script2 script Author : pattif CompanyName : Microsoft Corporation -Copyright : ???? 2015 Microsoft Corporation. All rights reserved. +Copyright : 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/14/2015 2:37:01 PM LicenseUri : http://required-script2.com/license ProjectUri : http://required-script2.com/ IconUri : http://required-script2.com/icon -Tags : {, Tag1, Tag2, Tag-Required-Script2-2.0...} +Tags : {, Tag1, Tag2, Tag-Required-Script2-2.0...} Includes : {Function, DscResource, Cmdlet, Command} -PowerShellGetFormatVersion : +PowerShellGetFormatVersion : ReleaseNotes : Required-Script2 release notes Dependencies : {} RepositorySourceLocation : C:\MyLocalRepo @@ -178,7 +178,7 @@ Indicates that this operation finds all script versions. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -194,7 +194,7 @@ A command can be a function or workflow. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -209,7 +209,7 @@ Finds scripts based on the PackageManagement provider-specific search syntax. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -224,7 +224,7 @@ Indicates that this operation gets all scripts that are dependent upon the scrip ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -240,7 +240,7 @@ The acceptable values for this parameter are: Function, Workflow. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Function, Workflow Required: False @@ -257,7 +257,7 @@ The *MaximumVersion* and *RequiredVersion* parameters are mutually exclusive; yo ```yaml Type: Version Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -273,7 +273,7 @@ The *MinimumVersion* and *RequiredVersion* parameters are mutually exclusive; yo ```yaml Type: Version Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -288,7 +288,7 @@ Specifies an array of names of scripts to find. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 1 @@ -303,7 +303,7 @@ Specifies the friendly name of a repository that has been registered by running ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -318,7 +318,7 @@ Specifies the exact version number of the script to find. ```yaml Type: Version Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -333,7 +333,7 @@ Specifies an array of tags. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -348,7 +348,7 @@ Accept wildcard characters: False ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -363,7 +363,7 @@ Accept wildcard characters: False ```yaml Type: Uri Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -378,7 +378,7 @@ Accept wildcard characters: False ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named diff --git a/reference/6/PowerShellGet/Install-Script.md b/reference/6/PowerShellGet/Install-Script.md index 37dfb6e050d6..919582e5b3dd 100644 --- a/reference/6/PowerShellGet/Install-Script.md +++ b/reference/6/PowerShellGet/Install-Script.md @@ -50,21 +50,21 @@ CommandType Name Version So ExternalScript Required-Script2.ps1 2.0 C:\Users\pattif\Documents\WindowsPowerShell\Scripts\Required-Script2.ps1 PS C:\> Get-InstalledScript -Name "Required-Script2" Version Name Type Repository Description ------- ---- ---- ---------- ----------- -2.5 Required-Script2 Script local1 Description for the Required-Script2 script PS C:\> Get-InstalledScript -Name "Required-Script2" | Format-List * +2.5 Required-Script2 Script local1 Description for the Required-Script2 script PS C:\> Get-InstalledScript -Name "Required-Script2" | Format-List * Name : Required-Script2 Version : 2.5 Type : Script Description : Description for the Required-Script2 script Author : pattif -CompanyName : -Copyright : ???? 2015 Microsoft Corporation. All rights reserved. +CompanyName : +Copyright : 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/15/2015 12:42:39 AM LicenseUri : http://required-script2.com/license ProjectUri : http://required-script2.com/ IconUri : http://required-script2.com/icon -Tags : {Tag1, Tag2, Tag-Required-Script2-2.5, PSScript...} +Tags : {Tag1, Tag2, Tag-Required-Script2-2.5, PSScript...} Includes : {Function, DscResource, Cmdlet, Command} -PowerShellGetFormatVersion : +PowerShellGetFormatVersion : ReleaseNotes : Required-Script2 release notes Dependencies : {} RepositorySourceLocation : http://pattif-dev:8765/api/v2/ @@ -89,21 +89,21 @@ PS C:\> Install-Script -Repository "Local1" -Name "Required-Script3" -Scope "All PS C:\> Get-InstalledScript -Name "Required-Script3" Version Name Type Repository Description ------- ---- ---- ---------- ----------- -2.5 Required-Script3 Script local1 Description for the Required-Script3 script PS C:\> Get-InstalledScript -Name "Required-Script3" | Format-List * +2.5 Required-Script3 Script local1 Description for the Required-Script3 script PS C:\> Get-InstalledScript -Name "Required-Script3" | Format-List * Name : Required-Script3 Version : 2.5 Type : Script Description : Description for the Required-Script3 script Author : pattif -CompanyName : -Copyright : ???? 2015 Microsoft Corporation. All rights reserved. +CompanyName : +Copyright : 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/15/2015 12:42:45 AM LicenseUri : http://required-script3.com/license ProjectUri : http://required-script3.com/ IconUri : http://required-script3.com/icon -Tags : {Tag1, Tag2, Tag-Required-Script3-2.5, PSScript...} +Tags : {Tag1, Tag2, Tag-Required-Script3-2.5, PSScript...} Includes : {Function, DscResource, Cmdlet, Command} -PowerShellGetFormatVersion : +PowerShellGetFormatVersion : ReleaseNotes : Required-Script3 release notes Dependencies : {} RepositorySourceLocation : http://pattif-dev:8765/api/v2/ @@ -177,7 +177,7 @@ Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -194,7 +194,7 @@ This parameter accepts the wildcard character (*). ```yaml Type: Version Parameter Sets: NameParameterSet -Aliases: +Aliases: Required: False Position: Named @@ -210,7 +210,7 @@ The *MinimumVersion* and *RequiredVersion* parameters are mutually exclusive; yo ```yaml Type: Version Parameter Sets: NameParameterSet -Aliases: +Aliases: Required: False Position: Named @@ -225,7 +225,7 @@ Specifies an array of names of scripts to install. ```yaml Type: String[] Parameter Sets: NameParameterSet -Aliases: +Aliases: Required: True Position: 1 @@ -241,7 +241,7 @@ The default is all registered repositories. ```yaml Type: String[] Parameter Sets: NameParameterSet -Aliases: +Aliases: Required: False Position: Named @@ -256,7 +256,7 @@ Specifies the exact version number of the script to install. ```yaml Type: Version Parameter Sets: NameParameterSet -Aliases: +Aliases: Required: False Position: Named @@ -276,7 +276,7 @@ The CurrentUser scope specifies to install the script in $home\Documents\Windows ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Accepted values: CurrentUser, AllUsers Required: False @@ -323,7 +323,7 @@ Accept wildcard characters: False ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -338,7 +338,7 @@ Accept wildcard characters: False ```yaml Type: PSObject[] Parameter Sets: InputObject -Aliases: +Aliases: Required: True Position: Named @@ -353,7 +353,7 @@ Accept wildcard characters: False ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -368,7 +368,7 @@ Accept wildcard characters: False ```yaml Type: Uri Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -383,7 +383,7 @@ Accept wildcard characters: False ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named From b93a6ba9a55e0fed9608b3cfb2b20a9dbedc194c Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 7 Nov 2017 13:40:15 -0800 Subject: [PATCH 005/188] removed empty H3 --- .../5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md | 1 - .../5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md | 1 - 2 files changed, 2 deletions(-) diff --git a/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md b/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md index 49135884a825..4a3773f08351 100644 --- a/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md +++ b/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md @@ -171,7 +171,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS -### You can pipe an object containing encrypted content to **Unprotect-CmsMessage**. ## OUTPUTS diff --git a/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md b/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md index 49135884a825..4a3773f08351 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md +++ b/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md @@ -171,7 +171,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS -### You can pipe an object containing encrypted content to **Unprotect-CmsMessage**. ## OUTPUTS From ec505bf2bcfde03f08f93c43e5a44ee72d25be67 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 7 Nov 2017 14:10:52 -0800 Subject: [PATCH 006/188] added H3 for input and output types --- .../5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md | 4 ++++ .../5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md b/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md index 4a3773f08351..2904dd9a3cfd 100644 --- a/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md +++ b/reference/5.0/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md @@ -171,10 +171,14 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS +### System.Diagnostics.Eventing.Reader.EventLogRecord or System.String You can pipe an object containing encrypted content to **Unprotect-CmsMessage**. ## OUTPUTS +### System.String +The unencrypted message. + ## NOTES ## RELATED LINKS diff --git a/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md b/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md index 4a3773f08351..2904dd9a3cfd 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md +++ b/reference/5.1/Microsoft.PowerShell.Security/Unprotect-CmsMessage.md @@ -171,10 +171,14 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS +### System.Diagnostics.Eventing.Reader.EventLogRecord or System.String You can pipe an object containing encrypted content to **Unprotect-CmsMessage**. ## OUTPUTS +### System.String +The unencrypted message. + ## NOTES ## RELATED LINKS From c2abb44968de990e69ebbcd2556bf3760a459588 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 7 Nov 2017 19:12:37 -0800 Subject: [PATCH 007/188] removed mangled UTF8 character --- reference/5.1/PowershellGet/Install-Script.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/5.1/PowershellGet/Install-Script.md b/reference/5.1/PowershellGet/Install-Script.md index d68a270f7cdf..c5af2f49cd55 100644 --- a/reference/5.1/PowershellGet/Install-Script.md +++ b/reference/5.1/PowershellGet/Install-Script.md @@ -96,7 +96,7 @@ Type : Script Description : Description for the Required-Script3 script Author : pattif CompanyName : -Copyright : ???? 2015 Microsoft Corporation. All rights reserved. +Copyright : 2015 Microsoft Corporation. All rights reserved. PublishedDate : 8/15/2015 12:42:45 AM LicenseUri : http://required-script3.com/license ProjectUri : http://required-script3.com/ From bbffd771de9f6d1040d92bd805aa549089b2b12d Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 8 Nov 2017 16:36:46 -0800 Subject: [PATCH 008/188] updating Out-* commands with -NoNewLine per Issue 1739 --- .../Add-Content.md | 113 ++++-- .../Set-Content.md | 116 +++--- .../Microsoft.PowerShell.Utility/Out-File.md | 204 +++++++---- .../Write-Host.md | 116 ++++-- .../Add-Content.md | 255 +++++++------ .../Set-Content.md | 118 +++--- .../Microsoft.PowerShell.Utility/Out-File.md | 195 ++++++---- .../Write-Host.md | 106 ++++-- .../Add-Content.md | 143 ++++---- .../Set-Content.md | 178 +++++---- .../Microsoft.PowerShell.Utility/Out-File.md | 115 +++--- .../Write-Host.md | 72 ++-- .../Add-Content.md | 143 ++++---- .../Set-Content.md | 178 +++++---- .../Microsoft.PowerShell.Utility/Out-File.md | 121 ++++--- .../Write-Host.md | 74 ++-- .../Add-Content.md | 341 +++++++++--------- .../Set-Content.md | 178 +++++---- .../Microsoft.PowerShell.Utility/Out-File.md | 201 ++++++----- .../Write-Host.md | 79 ++-- 20 files changed, 1721 insertions(+), 1325 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Management/Add-Content.md b/reference/3.0/Microsoft.PowerShell.Management/Add-Content.md index 45f6fb17fe94..22a32c1345c0 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Add-Content.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Add-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -9,36 +9,46 @@ title: Add-Content --- # Add-Content + ## SYNOPSIS + Adds content to the specified items, such as adding words to a file. + ## SYNTAX ### Path (Default) -``` + +```powershell Add-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Encoding ] [-Stream ] [] ``` ### LiteralPath -``` + +```powershell Add-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Encoding ] [-Stream ] [] ``` ## DESCRIPTION + The Add-Content cmdlet appends content to a specified item or file. You can specify the content by typing the content in the command or by specifying an object that contains the content. + ## EXAMPLES ### Example 1 -``` + +```powershell PS C:\> add-content -path *.txt -exclude help* -value "END" ``` This command adds "END" to all text files in the current directory, except for those with file names that begin with "help". + ### Example 2 + ``` PS C:\> add-content -Path file1.log, file2.log -Value (get-date) -passthru ``` @@ -47,8 +57,10 @@ This command adds the date to the end of the File1.log and File2.log files and t The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to Add-Content. The PassThru parameter passes an object representing the added content through the pipeline. Because there is no other cmdlet to receive the passed object, it is displayed at the command line. + ### Example 3 -``` + +```powershell PS C:\> add-content -path monthly.txt -value (get-content c:\rec1\weekly.txt) ``` @@ -58,8 +70,10 @@ The parentheses ensure that the Get-Content command is complete before the Add-C You can also copy the content of Weekly.txt to a variable, such as $w, and then use the Value parameter to pass the variable to Add-Content. In that case, the command would be "add-content -path monthly.txt -value $w". + ### Example 4 -``` + +```powershell PS C:\> add-content -value (get-content test.log) -path C:\tests\test134\logs\test134.log ``` @@ -74,26 +88,31 @@ The command creates the remaining directories and the Test134.log file. The Force parameter is not required for this command. Add-Content creates directories to complete a path even without the Force parameter. + ## PARAMETERS ### -Encoding + Specifies the file encoding. The default is ASCII. Valid values are: --- ASCII: Uses the encoding for the ASCII (7-bit) character set. --- BigEndianUnicode: Encodes in UTF-16 format using the big-endian byte order. --- Byte: Encodes a set of characters into a sequence of bytes. --- String: Uses the encoding type for a string. --- Unicode: Encodes in UTF-16 format using the little-endian byte order. --- UTF7: Encodes in UTF-7 format. --- UTF8: Encodes in UTF-8 format. --- Unknown: The encoding type is unknown or invalid. The data can be treated as binary. +- ASCII: Uses the encoding for the ASCII (7-bit) character set. +- BigEndianUnicode: Encodes in UTF-16 format using the big-endian byte order. +- Byte: Encodes a set of characters into a sequence of bytes. +- String: Uses the encoding type for a string. +- Unicode: Encodes in UTF-16 format using the little-endian byte order. +- UTF7: Encodes in UTF-7 format. +- UTF8: Encodes in UTF-8 format. +- Unknown: The encoding type is unknown or invalid. The data can be treated as binary. + +Encoding is a dynamic parameter that the FileSystem provider adds to the Add-Content cmdlet. +This parameter works only in file system drives. -Encoding is a dynamic parameter that the FileSystem provider adds to the Add-Content cmdlet. This parameter works only in file system drives.```yaml +```yaml Type: FileSystemCmdletProviderEncoding Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unknown, String, Unicode, Byte, BigEndianUnicode, UTF8, UTF7, UTF32, Ascii, Default, Oem Required: False @@ -104,12 +123,13 @@ Accept wildcard characters: False ``` ### -Force + Overrides the read-only attribute, allowing you to add content to a read-only file. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -119,14 +139,17 @@ Accept wildcard characters: False ``` ### -Stream -Adds the content to the specified alternate data stream. If the stream does not yet, exist, Add-Content creates it. Enter the stream name. Wildcards are not supported. -Stream is a dynamic parameter that the FileSystem provider adds to the Add-Content cmdlet. This parameter works only in file system drives. +Adds the content to the specified alternate data stream. If the stream does not yet, exist, Add-Content creates it. +Enter the stream name. Wildcards are not supported. +Stream is a dynamic parameter that the FileSystem provider adds to the Add-Content cmdlet. +This parameter works only in file system drives. +This parameter is introduced in PowerShell 3.0. -This parameter is introduced in Windows PowerShell 3.0.```yaml +```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -136,6 +159,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -151,6 +175,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -167,6 +192,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. @@ -184,18 +210,19 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. -This parameter is not supported by any providers installed with Windows PowerShell. +This parameter is not supported by any providers installed with PowerShell. ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -205,6 +232,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". @@ -213,7 +241,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -223,15 +251,16 @@ Accept wildcard characters: True ``` ### -Filter + Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -241,6 +270,7 @@ Accept wildcard characters: True ``` ### -Include + Adds only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". @@ -249,7 +279,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -259,11 +289,12 @@ Accept wildcard characters: True ``` ### -LiteralPath + Specifies the path to the items that receive the additional content. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -278,13 +309,14 @@ Accept wildcard characters: False ``` ### -PassThru + Returns an object representing the added content. By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -301,7 +333,7 @@ If you specify multiple paths, use commas to separate the paths. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True Position: 1 @@ -311,6 +343,7 @@ Accept wildcard characters: True ``` ### -Value + Specifies the content to be added. Type a quoted string, such as "This data is for internal use only", or specify an object that contains content, such as the DateTime object that Get-Date generates. @@ -319,7 +352,7 @@ You cannot specify the contents of a file by typing its path, because the path i ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 2 @@ -329,27 +362,34 @@ 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 the objects to be added (the Value) to Add-Content. + ## OUTPUTS ### None or System.String + When you use the Passthru parameter, Add-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output. + ## NOTES -* When you pipe an object to Add-Content, the object is converted to a string before it is added to the item. The object type determines the string format, but the format might be different than the default display of the object. To control the string format, use the formatting parameters of the sending cmdlet. - You can also refer to Add-Content by its built-in alias, "ac". -For more information, see about_Aliases. +When you pipe an object to Add-Content, the object is converted to a string before it is added to the item. +The object type determines the string format, but the format might be different than the default display of the object. +To control the string format, use the formatting parameters of the sending cmdlet. - The Add-Content cmdlet is designed to work with the data exposed by any provider. +You can also refer to Add-Content by its built-in alias, "ac". For more information, see about_Aliases. + +The Add-Content cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers. -* ## RELATED LINKS [Clear-Content](Clear-Content.md) @@ -362,4 +402,3 @@ For more information, see about_Providers. [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Management/Set-Content.md b/reference/3.0/Microsoft.PowerShell.Management/Set-Content.md index 2219dba7cc31..ea273cba13a3 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Set-Content.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Set-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -18,7 +18,7 @@ Writes or replaces the content in an item with new content. ### Path (Default) -``` +```powershell Set-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Encoding ] [-Stream ] [] @@ -26,49 +26,50 @@ Set-Content [-Value] [-PassThru] [-Path] [-Filter ### LiteralPath -``` +```powershell Set-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Encoding ] [-Stream ] [] ``` ## DESCRIPTION + The Set-Content cmdlet is a string-processing cmdlet that writes or replaces the content in the specified item, such as a file. Whereas the Add-Content cmdlet appends content to a file, Set-Content replaces the existing content. You can type the content in the command or send content through the pipeline to Set-Content. ## EXAMPLES -### Example 1 +### Example 1: Replace the contents of multiple files in a folder -``` -PS C:\> set-content -path C:\Test1\test*.txt -value "Hello, World" +```powershell +PS C:\> Set-Content -Path "C:\Test1\test*.txt" -Value "Hello, World" ``` -This command replaces the contents of all files in the Test1 directory that have names beginning with "test" with "Hello, World". +This command replaces the contents of all files in the Test1 folder that have names that start with "test" with "Hello, World". This example shows how to specify content by typing it in the command. -### Example 2 +### Example 2: Send content to a file -``` -PS C:\> get-date | set-content C:\Test1\date.csv +```powershell +PS C:\> Get-Date | Set-Content -Path "C:\Test1\date.csv" ``` This command creates a comma-separated variable-length (csv) file that contains only the current date and time. It uses the Get-Date cmdlet to get the current system date and time. The pipeline operator passes the result to Set-Content, which creates the file and writes the content. -If the Test1 directory does not exist, the command fails, but if the file does not exist, the command will create it. +If the Test1 directory does not exist, the command fails, but if the file does not exist, the command creates it. -### Example 3 +### Example 3: Replace text in a file -``` -PS C:\> (get-content Notice.txt) | foreach-object {$_ -replace "Warning", "Caution"} | set-content Notice.txt +```powershell +PS C:\> (Get-Content -Path "Notice.txt") | ForEach-Object {$_ -Replace "Warning", "Caution"} | Set-Content -Path "Notice.txt" ``` This command replaces all instances of "Warning" with "Caution" in the Notice.txt file. -It uses the Get-Content cmdlet to get the content of Notice.txt. +It uses Get-Content cmdlet to get the content of Notice.txt. The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in Get-Content. The expression uses the "$_" symbol to refer to the current item and the Replace parameter to specify the text to be replaced. @@ -103,16 +104,16 @@ The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. -This parameter is not supported by any providers installed with Windows PowerShell. +This parameter is not supported by any providers installed with PowerShell. ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: Current user +Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` @@ -123,13 +124,13 @@ Specifies the file encoding. The acceptable values for this parameter are: - **ASCII** Uses the encoding for the ASCII (7-bit) character set. -- **BigEndianUnicode** Encodes in UTF-16 format using the big-endian byte order. -- **Byte** Encodes a set of characters into a sequence of bytes. -- **String** Uses the encoding type for a string. -- **Unicode** Encodes in UTF-16 format using the little-endian byte order. +- **BigEndianUnicode** Encodes in UTF-16 format using the big-endian byte order. +- **Byte** Encodes a set of characters into a sequence of bytes. +- **String** Uses the encoding type for a string. +- **Unicode** Encodes in UTF-16 format using the little-endian byte order. - **UTF7** Encodes in UTF-7 format. -- **UTF8** Encodes in UTF-8 format. -- **Unknown** The encoding type is unknown or invalid; the data can be treated as binary. +- **UTF8** Encodes in UTF-8 format. +- **Unknown** The encoding type is unknown or invalid; the data can be treated as binary. The default value is ASCII. @@ -139,7 +140,7 @@ This parameter works only in file system drives. ```yaml Type: FileSystemCmdletProviderEncoding Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unknown, String, Unicode, Byte, BigEndianUnicode, UTF8, UTF7, UTF32, Ascii, Default, Oem Required: False @@ -159,7 +160,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -170,15 +171,17 @@ Accept wildcard characters: True ### -Filter -Specifies a filter in the provider's format or language. +Specifies a filter in the format or language of the provider. The value of this parameter qualifies the Path parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, +because the provider applies them when it is retrieving the objects, +instead of having PowerShell filter the objects after they are retrieved. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -197,11 +200,11 @@ Even using the Force parameter, the cmdlet cannot override security restrictions ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -216,7 +219,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -231,7 +234,7 @@ Specifies the path to the item that will receive the content. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -247,30 +250,30 @@ Accept wildcard characters: False ### -PassThru -Returns an object representing the content. +Returns an object that represents the content. By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Path -Specifies the path to the item that will receive the content. -Wildcards are permitted. +Specifies the path of the item that receives the content. +Wildcard characters are permitted. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True Position: 1 @@ -280,6 +283,7 @@ Accept wildcard characters: True ``` ### -Stream + Specifies an alternative data stream for content. If the stream does not exist, this cmdlet creates it. Wildcard characters are not supported. @@ -291,12 +295,12 @@ You can use the **Set-Content** cmdlet to change the content of the Zone.Identif However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -309,9 +313,7 @@ Accept wildcard characters: False Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see +For more information, see about_Transactions. ```yaml Type: SwitchParameter @@ -332,7 +334,7 @@ Specifies the new content for the item. ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 2 @@ -360,22 +362,10 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Parameter | --- | - --Debug | --ErrorAction | --ErrorVariable | --InformationAction | --InformationVariable | --OutBuffer | --OutVariable | --PipelineVariable | --Verbose | --WarningAction | --WarningVariable. | - -For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -399,7 +389,7 @@ If you pipe non-string objects to Set-Content, it converts the object to a strin To write objects to files, use Out-File. The Set-Content cmdlet is designed to work with the data exposed by any provider. -To list the providers available in your session, type "Get-PsProvider". +To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Out-File.md b/reference/3.0/Microsoft.PowerShell.Utility/Out-File.md index 6db3f3944c11..7be21e330776 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Out-File.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Out-File.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -9,68 +9,82 @@ title: Out-File --- # Out-File + ## SYNOPSIS + Sends output to a file. + ## SYNTAX ### ByPath (Default) -``` + +```powershell Out-File [-FilePath] [[-Encoding] ] [-Append] [-Force] [-NoClobber] [-Width ] [-InputObject ] [-WhatIf] [-Confirm] [] ``` ### ByLiteralPath -``` + +```powershell Out-File -LiteralPath [[-Encoding] ] [-Append] [-Force] [-NoClobber] [-Width ] [-InputObject ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The Out-File cmdlet sends output to a file. You can use this cmdlet instead of the redirection operator (\>) when you need to use its parameters. + ## EXAMPLES -### Example 1 -``` -PS C:\> get-process | out-file -filepath C:\Test1\process.txt +### Example 1: Send output to a file + +```powershell +PS C:\> Get-Process | Out-File -filepath C:\Test1\process.txt ``` This command sends a list of processes on the computer to the Process.txt file. If the file does not exist, Out-File creates it. Because the name of the FilePath parameter is optional, you can omit it and submit the equivalent command "get-process | outfile C:\Test1\process.txt". -### Example 2 -``` -PS C:\> get-process | out-file C:\Test1\process.txt -noclobber + +### Example 2: Send output to a file without overwriting + +```powershell +PS C:\> Get-Process | Out-File C:\Test1\process.txt -NoClobber Out-File : File C:\Test1\process.txt already exists and NoClobber was specified. At line:1 char:23 -+ get-process | out-file <<<< process.txt -noclobber ++ Get-Process | Out-File <<<< process.txt -NoClobber ``` This command also sends a list of processes to the Process.txt file, but it uses the NoClobber parameter, which prevents an existing file from being overwritten. The output shows the error message that appears when NoClobber is used with an existing file. -### Example 3 -``` -PS C:\> $a = get-process -PS C:\> out-file -filepath C:\Test1\process.txt -inputobject $a -encoding ASCII -width 50 + +### Example 3: Send output to a file in ASCII format + +```powershell +PS C:\> $A = Get-Process +PS C:\> Out-File -FilePath C:\Test1\process.txt -InputObject $A -Encoding ASCII -Width 50 ``` These commands send a list of processes on the computer to the Process.txt file. The text is encoded in ASCII format so that it can be read by search programs like Findstr and Grep. By default, Out-File uses Unicode format. -The first command gets the list of processes and stores them in the $a variable. +The first command gets the list of processes and stores them in the $A variable. The second command uses the Out-File cmdlet to send the list to the Process.txt file. -The command uses the InputObject parameter to specify that the input is in the $a variable. +The command uses the InputObject parameter to specify that the input is in the $A variable. It uses the Encoding parameter to convert the output to ASCII format. It uses the Width parameter to limit each line in the file to 50 characters. Because the lines of output are truncated at 50 characters, the rightmost column in the process table is omitted. -### Example 4 -``` -PS C:\> set-location hklm:\software -PS C:\> get-acl mycompany\mykey | out-file -filepath c:\ps\acl.txt -PS C:\> get-acl mycompany\mykey | out-file -filepath filesystem::acl.txt + +### Example 4: Send output from outside a file system drive + +```powershell +PS C:\> Set-Location hklm:\software +PS C:\> Get-Acl mycompany\mykey | Out-File -FilePath c:\ps\acl.txt +PS C:\> Get-Acl mycompany\mykey | Out-File -FilePath filesystem::acl.txt ``` These commands show how to use the Out-File cmdlet when you are not in a FileSystem drive. @@ -81,29 +95,60 @@ The second and third commands have the same effect. They use the Get-Acl cmdlet to get the security descriptor of the MyKey registry subkey (HKLM\Software\MyCompany\MyKey). A pipeline operator passes the result to the Out-File cmdlet, which sends it to the Acl.txt file. -Because Out-File is not supported by the Windows PowerShell Registry provider, you must specify either the file system drive name, such as "c:", or the name of the provider followed by two colons, "FileSystem::", in the value of the FilePath parameter. +Because Out-File is not supported by the PowerShell Registry provider, you must specify either the file system drive name, +such as "c:", or the name of the provider followed by two colons, "FileSystem::", in the value of the FilePath parameter. The second and third commands demonstrate these methods. + ## PARAMETERS ### -Append + Adds the output to the end of an existing file, instead of replacing the file contents. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: Replace +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Encoding + Specifies the type of character encoding used in the file. -Valid values are "Unicode", "UTF7", "UTF8", "UTF32", "ASCII", "BigEndianUnicode", "Default", and "OEM". -"Unicode" is the default. +The acceptable values for this parameter are: + +- Unknown +- String +- Unicode +- BigEndianUnicode +- UTF8 +- UTF7 +- UTF32 +- ASCII +- Default +- OEM + +Unicode is the default. "Default" uses the encoding of the system's current ANSI code page. @@ -112,7 +157,8 @@ Valid values are "Unicode", "UTF7", "UTF8", "UTF32", "ASCII", "BigEndianUnicode" ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: +Accepted values: unknown, string, unicode, bigendianunicode, utf8, utf7, utf32, ascii, default, oem Required: False Position: 2 @@ -122,12 +168,13 @@ Accept wildcard characters: False ``` ### -FilePath + Specifies the path to the output file. ```yaml Type: String Parameter Sets: ByPath -Aliases: +Aliases: Required: True Position: 1 @@ -137,29 +184,31 @@ Accept wildcard characters: False ``` ### -Force -Allows the cmdlet to overwrite an existing read-only file. + +Indicates that the cmdlet overwrites an existing read-only file. Even using the Force parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -InputObject + Specifies the objects to be written to the file. Enter a variable that contains the objects or type a command or expression that gets the objects. ```yaml Type: PSObject Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -168,47 +217,13 @@ Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` -### -NoClobber -Will not overwrite (replace the contents) of an existing file. -By default, if a file exists in the specified path, Out-File overwrites the file without warning. -If both Append and NoClobber are used, the output is appended to the existing file. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: NoOverwrite - -Required: False -Position: Named -Default value: Overwrite -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Width -Specifies the number of characters in each line of output. -Any additional characters are truncated, not wrapped. -If you omit this parameter, the width is determined by the characteristics of the host. -The default for the Windows PowerShell console is 80 (characters). - -```yaml -Type: Int32 -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: 80 -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -LiteralPath + Specifies the path to the output file. -Unlike **FilePath**, the value of the **LiteralPath** parameter is used exactly as it is typed. +Unlike *FilePath*, the value of the *LiteralPath* parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String @@ -222,22 +237,25 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -Confirm -Prompts you for confirmation before running the cmdlet. +### -NoClobber +Indicates that the cmdlet will not overwrite an existing file. +By default, if a file exists in the specified path, **Out-File** overwrites the file without warning. +If both *Append* and *NoClobber* are used, the output is appended to the existing file. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: cf +Aliases: NoOverwrite Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -253,28 +271,56 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Width +Specifies the number of characters in each line of output. +Any additional characters are truncated, not wrapped. +If you omit this parameter, the width is determined by the characteristics of the host. +The default for the Windows PowerShell console is 80 characters. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see about_CommonParameters +(http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.PSObject + You can pipe any object to Out-File. + ## OUTPUTS ### None + Out-File does not generate any output. + ## NOTES -* The Out cmdlets do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. - The Out cmdlets do not have parameters for names or file paths. -To send data to a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. +The Out cmdlets do not format objects; they just render them and send them to the specified display destination. +If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. + +The Out cmdlets do not have parameters for names or file paths. +To send data to a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a PowerShell command to the cmdlet. You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. For help, see the examples. - Out-File sends data, but it does not emit any output objects. +Out-File sends data, but it does not emit any output objects. If you pipe the output of Out-File to Get-Member, Get-Member reports that no objects have been specified. -* ## RELATED LINKS [Out-Default](../Microsoft.PowerShell.Core/Out-Default.md) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Write-Host.md b/reference/3.0/Microsoft.PowerShell.Utility/Write-Host.md index b7ef52a15770..f30679113e76 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Write-Host.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Write-Host.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -9,62 +9,95 @@ title: Write-Host --- # Write-Host + ## SYNOPSIS + Writes customized output to a host. + ## SYNTAX -``` +```powershell Write-Host [[-Object] ] [-NoNewline] [-Separator ] [-ForegroundColor ] [-BackgroundColor ] [] ``` ## DESCRIPTION + The Write-Host cmdlet customizes output. You can specify the color of text by using the ForegroundColor parameter, and you can specify the background color by using the BackgroundColor parameter. The Separator parameter lets you specify a string to use to separate displayed objects. -The particular result depends on the program that is hosting Windows PowerShell. +The particular result depends on the program that is hosting PowerShell. + ## EXAMPLES -### Example 1 -``` -PS C:\> write-host "no newline test " -nonewline +### Example 1: Write to the console without adding a new line + +```powershell +PS C:\> Write-Host "no newline test " -NoNewline no newline test PS C:\> ``` This command displays the input to the console, but because of the NoNewline parameter, the output is followed directly by the prompt. -### Example 2 -``` -PS C:\> write-host (2,4,6,8,10,12) -Separator ", +2= " + +### Example 2: Write to the console and include a separator + +```powershell +PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", +2= " 2, +2= 4, +2= 6, +2= 8, +2= 10, +2= 12 ``` This command displays the even numbers from 2 through 12. The Separator parameter is used to add the string , +2= (comma, space, +, 2, =, space). -### Example 3 -``` -PS C:\> write-host (2,4,6,8,10,12) -Separator ", -> " -foregroundcolor DarkGreen -backgroundcolor white + +### Example 3: Write with different text and background colors + +```powershell +PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", -> " -ForegroundColor DarkGreen -BackgroundColor White ``` This command displays the even numbers from 2 through 12. It uses the ForegroundColor parameter to output dark green text and the BackgroundColor parameter to display a white background. -### Example 4 -``` -PS C:\> write-host "Red on white text." -ForegroundColor red -BackgroundColor white + +### Example 4: Write with different text and background colors + +```powershell +PS C:\> Write-Host "Red on white text." -ForegroundColor red -BackgroundColor white Red on white text. ``` This command displays the string "Red on white text." The text is red, as defined by the ForegroundColor parameter. The background is white, as defined by the BackgroundColor parameter. + ## PARAMETERS ### -BackgroundColor + Specifies the background color. There is no default. +The acceptable values for this parameter are: + +- Black +- DarkBlue +- DarkGreen +- DarkCyan +- DarkRed +- DarkMagenta +- DarkYellow +- Gray +- DarkGray +- Blue +- Green +- Cyan +- Red +- Magenta +- Yellow +- White ```yaml Type: ConsoleColor Parameter Sets: (All) -Aliases: +Aliases: +Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White Required: False Position: Named @@ -74,13 +107,33 @@ Accept wildcard characters: False ``` ### -ForegroundColor + Specifies the text color. There is no default. +The acceptable values for this parameter are: + +- Black +- DarkBlue +- DarkGreen +- DarkCyan +- DarkRed +- DarkMagenta +- DarkYellow +- Gray +- DarkGray +- Blue +- Green +- Cyan +- Red +- Magenta +- Yellow +- White ```yaml Type: ConsoleColor Parameter Sets: (All) -Aliases: +Aliases: +Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White Required: False Position: Named @@ -90,12 +143,15 @@ Accept wildcard characters: False ``` ### -NoNewline -Specifies that the content displayed in the console does not end with a newline character. + +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -105,27 +161,28 @@ Accept wildcard characters: False ``` ### -Object -Objects to display in the console. + +Objects to display in the host. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` ### -Separator -String to the output between objects displayed on the console. +Specifies a separator string to insert between objects displayed by the host. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -135,17 +192,26 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Object + You can pipe objects to be written to the host. + ## OUTPUTS ### None + Write-Host sends the objects to the host. It does not return any objects. However, the host might display the objects that Write-Host sends to it. + ## NOTES ## RELATED LINKS diff --git a/reference/4.0/Microsoft.PowerShell.Management/Add-Content.md b/reference/4.0/Microsoft.PowerShell.Management/Add-Content.md index d160e385fbcb..03cf372f15d7 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Add-Content.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Add-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,40 +11,46 @@ title: Add-Content # Add-Content ## SYNOPSIS + Adds content to the specified items, such as adding words to a file. ## SYNTAX ### Path (Default) -``` + +```powershell Add-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Encoding ] [-Stream ] [] ``` ### LiteralPath -``` + +```powershell Add-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Encoding ] [-Stream ] [] ``` ## DESCRIPTION + The Add-Content cmdlet appends content to a specified item or file. You can specify the content by typing the content in the command or by specifying an object that contains the content. ## EXAMPLES -### Example 1 -``` -PS C:\> add-content -path *.txt -exclude help* -value "END" +### Example 1: Add a string to all text files with an exception + +```powershell +PS C:\> Add-Content -Path "*.txt" -Exclude "help*" -Value "END" ``` This command adds "END" to all text files in the current directory, except for those with file names that begin with "help". -### Example 2 -``` -PS C:\> add-content -Path file1.log, file2.log -Value (get-date) -passthru +### Example 2: Add a date to the end of the specified files + +```powershell +PS C:\> Add-Content -Path "file1.log", "file2.log" -Value (Get-Date) -PassThru ``` This command adds the date to the end of the File1.log and File2.log files and then displays the date at the command line. @@ -52,9 +58,10 @@ The command uses the Get-Date cmdlet to get the date, and it uses the Value para The PassThru parameter passes an object representing the added content through the pipeline. Because there is no other cmdlet to receive the passed object, it is displayed at the command line. -### Example 3 -``` -PS C:\> add-content -path monthly.txt -value (get-content c:\rec1\weekly.txt) +### Example 3: Add the contents of a specified file to another file + +```powershell +PS C:\> Add-Content -Path "monthly.txt" -Value (Get-Content "c:\rec1\weekly.txt") ``` This command adds the contents of the Weekly.txt file to the end of the Monthly.txt file. @@ -64,9 +71,10 @@ The parentheses ensure that the Get-Content command is complete before the Add-C You can also copy the content of Weekly.txt to a variable, such as $w, and then use the Value parameter to pass the variable to Add-Content. In that case, the command would be "add-content -path monthly.txt -value $w". -### Example 4 -``` -PS C:\> add-content -value (get-content test.log) -path C:\tests\test134\logs\test134.log +### Example 4: Create a new directory and file and copy content + +```powershell +PS C:\> Add-Content -Value (Get-Content "test.log") -Path "C:\tests\test134\logs\test134.log" ``` This command creates a new directory and file and copies the content of an existing file to the newly created file. @@ -83,28 +91,77 @@ Add-Content creates directories to complete a path even without the Force parame ## PARAMETERS +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. -This parameter is not supported by any providers installed with Windows PowerShell. +This parameter is not supported by any providers installed with PowerShell. ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: Current user +Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` +### -Encoding +Specifies the encoding that this cmdlet applies to the content. + +The acceptable values for this parameter are: + +- Unknown +- String +- Unicode +- Byte +- BigEndianUnicode +- UTF8 +- UTF7 +- UTF32 +- Ascii +- Default +- Oem +- BigEndianUTF32 + +```yaml +Type: FileSystemCmdletProviderEncoding +Parameter Sets: (All) +Aliases: +Accepted values: Unknown, String, Unicode, Byte, BigEndianUnicode, UTF8, UTF7, UTF32, Ascii, Default, Oem, BigEndianUTF32 + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +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". @@ -113,7 +170,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -123,15 +180,16 @@ Accept wildcard characters: True ``` ### -Filter + Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -141,21 +199,22 @@ Accept wildcard characters: True ``` ### -Force -Overrides the read-only attribute, allowing you to add content to a read-only file. +Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Include + Adds only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". @@ -164,7 +223,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -174,11 +233,12 @@ Accept wildcard characters: True ``` ### -LiteralPath + Specifies the path to the items that receive the additional content. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -192,18 +252,38 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` +### -NoNewline +Indicates that this cmdlet does not add a new line/carriage return to the content. + +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -PassThru + Returns an object representing the added content. By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -216,7 +296,7 @@ If you specify multiple paths, use commas to separate the paths. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True Position: 1 @@ -225,51 +305,28 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True ``` -### -Value -Specifies the content to be added. -Type a quoted string, such as "This data is for internal use only", or specify an object that contains content, such as the DateTime object that Get-Date generates. - -You cannot specify the contents of a file by typing its path, because the path is just a string, but you can use a Get-Content command to get the content and pass it to the Value parameter. - -```yaml -Type: Object[] -Parameter Sets: (All) -Aliases: - -Required: True -Position: 2 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Confirm -Prompts you for confirmation before running the cmdlet. +### -Stream +Specifies an alternative data stream for content. +If the stream does not exist, this cmdlet creates it. +Wildcard characters are not supported. -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf +Stream is a dynamic parameter that the FileSystem provider adds to **Add-Content**. +This parameter works only in file system drives. -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` +You can use the **Add-Content** cmdlet to change the content of the Zone.Identifier alternate data stream. +However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. +If you verify that a downloaded file is safe, use the Unblock-File cmdlet. -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +This parameter was introduced in PowerShell 3.0. ```yaml -Type: SwitchParameter +Type: String Parameter Sets: (All) -Aliases: wi +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -293,88 +350,70 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Encoding -Specifies the encoding that this cmdlet applies to the content. +### -Value -The acceptable values for this parameter are: +Specifies the content to be added. +Type a quoted string, such as "This data is for internal use only", or specify an object that contains content, such as the DateTime object that Get-Date generates. -- Unknown -- String -- Unicode -- Byte -- BigEndianUnicode -- UTF8 -- UTF7 -- UTF32 -- Ascii -- Default -- Oem -- BigEndianUTF32 +You cannot specify the contents of a file by typing its path, because the path is just a string, but you can use a Get-Content command to get the content and pass it to the Value parameter. ```yaml -Type: FileSystemCmdletProviderEncoding +Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: -Required: False -Position: Named +Required: True +Position: 2 Default value: None -Accept pipeline input: False +Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False ``` -### -Stream -Specifies an alternative data stream for content. -If the stream does not exist, this cmdlet creates it. -Wildcard characters are not supported. - -Stream is a dynamic parameter that the FileSystem provider adds to **Add-Content**. -This parameter works only in file system drives. - -You can use the **Add-Content** cmdlet to change the content of the Zone.Identifier alternate data stream. -However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. -If you verify that a downloaded file is safe, use the Unblock-File cmdlet. - -This parameter was introduced in Windows PowerShell 3.0. +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml -Type: String +Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: wi Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.Object -You can pipe the objects to be added (the Value) to Add-Content. + +You can pipe the objects to be added by Add-Content. ## OUTPUTS ### None or System.String + When you use the Passthru parameter, Add-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output. ## NOTES -* When you pipe an object to Add-Content, the object is converted to a string before it is added to the item. The object type determines the string format, but the format might be different than the default display of the object. To control the string format, use the formatting parameters of the sending cmdlet. - You can also refer to Add-Content by its built-in alias, "ac". -For more information, see about_Aliases. +When you pipe an object to Add-Content, the object is converted to a string before it is added to the item. +The object type determines the string format, but the format might be different than the default display of the object. +To control the string format, use the formatting parameters of the sending cmdlet. - The Add-Content cmdlet is designed to work with the data exposed by any provider. +You can also refer to Add-Content by its built-in alias, "ac". For more information, see about_Aliases. + +The Add-Content cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers. -* - ## RELATED LINKS [Clear-Content](Clear-Content.md) diff --git a/reference/4.0/Microsoft.PowerShell.Management/Set-Content.md b/reference/4.0/Microsoft.PowerShell.Management/Set-Content.md index 35a50044bc62..16f053567773 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Set-Content.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Set-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -18,7 +18,7 @@ Writes or replaces the content in an item with new content. ### Path (Default) -``` +```powershell Set-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Encoding ] [-Stream ] [] @@ -26,49 +26,50 @@ Set-Content [-Value] [-PassThru] [-Path] [-Filter ### LiteralPath -``` +```powershell Set-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-Encoding ] [-Stream ] [] ``` ## DESCRIPTION + The Set-Content cmdlet is a string-processing cmdlet that writes or replaces the content in the specified item, such as a file. Whereas the Add-Content cmdlet appends content to a file, Set-Content replaces the existing content. You can type the content in the command or send content through the pipeline to Set-Content. ## EXAMPLES -### Example 1 +### Example 1: Replace the contents of multiple files in a folder -``` -PS C:\> set-content -path C:\Test1\test*.txt -value "Hello, World" +```powershell +PS C:\> Set-Content -Path "C:\Test1\test*.txt" -Value "Hello, World" ``` -This command replaces the contents of all files in the Test1 directory that have names beginning with "test" with "Hello, World". +This command replaces the contents of all files in the Test1 folder that have names that start with "test" with "Hello, World". This example shows how to specify content by typing it in the command. -### Example 2 +### Example 2: Send content to a file -``` -PS C:\> get-date | set-content C:\Test1\date.csv +```powershell +PS C:\> Get-Date | Set-Content -Path "C:\Test1\date.csv" ``` This command creates a comma-separated variable-length (csv) file that contains only the current date and time. It uses the Get-Date cmdlet to get the current system date and time. The pipeline operator passes the result to Set-Content, which creates the file and writes the content. -If the Test1 directory does not exist, the command fails, but if the file does not exist, the command will create it. +If the Test1 directory does not exist, the command fails, but if the file does not exist, the command creates it. -### Example 3 +### Example 3: Replace text in a file -``` -PS C:\> (get-content Notice.txt) | foreach-object {$_ -replace "Warning", "Caution"} | set-content Notice.txt +```powershell +PS C:\> (Get-Content -Path "Notice.txt") | ForEach-Object {$_ -Replace "Warning", "Caution"} | Set-Content -Path "Notice.txt" ``` This command replaces all instances of "Warning" with "Caution" in the Notice.txt file. -It uses the Get-Content cmdlet to get the content of Notice.txt. +It uses Get-Content cmdlet to get the content of Notice.txt. The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in Get-Content. The expression uses the "$_" symbol to refer to the current item and the Replace parameter to specify the text to be replaced. @@ -103,16 +104,16 @@ The default is the current user. Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. -This parameter is not supported by any providers installed with Windows PowerShell. +This parameter is not supported by any providers installed with PowerShell. ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: Current user +Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` @@ -123,13 +124,13 @@ Specifies the file encoding. The acceptable values for this parameter are: - **ASCII** Uses the encoding for the ASCII (7-bit) character set. -- **BigEndianUnicode** Encodes in UTF-16 format using the big-endian byte order. -- **Byte** Encodes a set of characters into a sequence of bytes. -- **String** Uses the encoding type for a string. -- **Unicode** Encodes in UTF-16 format using the little-endian byte order. +- **BigEndianUnicode** Encodes in UTF-16 format using the big-endian byte order. +- **Byte** Encodes a set of characters into a sequence of bytes. +- **String** Uses the encoding type for a string. +- **Unicode** Encodes in UTF-16 format using the little-endian byte order. - **UTF7** Encodes in UTF-7 format. -- **UTF8** Encodes in UTF-8 format. -- **Unknown** The encoding type is unknown or invalid; the data can be treated as binary. +- **UTF8** Encodes in UTF-8 format. +- **Unknown** The encoding type is unknown or invalid; the data can be treated as binary. The default value is ASCII. @@ -139,7 +140,7 @@ This parameter works only in file system drives. ```yaml Type: FileSystemCmdletProviderEncoding Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unknown, String, Unicode, Byte, BigEndianUnicode, UTF8, UTF7, UTF32, Ascii, Default, Oem Required: False @@ -159,7 +160,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -170,15 +171,17 @@ Accept wildcard characters: True ### -Filter -Specifies a filter in the provider's format or language. +Specifies a filter in the format or language of the provider. The value of this parameter qualifies the Path parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, +because the provider applies them when it is retrieving the objects, +instead of having PowerShell filter the objects after they are retrieved. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -189,7 +192,7 @@ Accept wildcard characters: True ### -Force -Allows the cmdlet to set the contents of a file, even if the file is read-only. +Forces the cmdlet to set the contents of a file, even if the file is read-only. Implementation varies from provider to provider. For more information, see about_Providers. Even using the Force parameter, the cmdlet cannot override security restrictions. @@ -197,11 +200,11 @@ Even using the Force parameter, the cmdlet cannot override security restrictions ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -216,7 +219,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -231,7 +234,7 @@ Specifies the path to the item that will receive the content. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -247,30 +250,30 @@ Accept wildcard characters: False ### -PassThru -Returns an object representing the content. +Returns an object that represents the content. By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Path -Specifies the path to the item that will receive the content. -Wildcards are permitted. +Specifies the path of the item that receives the content. +Wildcard characters are permitted. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True Position: 1 @@ -280,6 +283,7 @@ Accept wildcard characters: True ``` ### -Stream + Specifies an alternative data stream for content. If the stream does not exist, this cmdlet creates it. Wildcard characters are not supported. @@ -291,12 +295,12 @@ You can use the **Set-Content** cmdlet to change the content of the Zone.Identif However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -309,9 +313,7 @@ Accept wildcard characters: False Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see +For more information, see about_Transactions. ```yaml Type: SwitchParameter @@ -332,7 +334,7 @@ Specifies the new content for the item. ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 2 @@ -360,22 +362,10 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Parameter | --- | - --Debug | --ErrorAction | --ErrorVariable | --InformationAction | --InformationVariable | --OutBuffer | --OutVariable | --PipelineVariable | --Verbose | --WarningAction | --WarningVariable. | - -For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -399,7 +389,7 @@ If you pipe non-string objects to Set-Content, it converts the object to a strin To write objects to files, use Out-File. The Set-Content cmdlet is designed to work with the data exposed by any provider. -To list the providers available in your session, type "Get-PsProvider". +To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. ## RELATED LINKS diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Out-File.md b/reference/4.0/Microsoft.PowerShell.Utility/Out-File.md index acfd92ef95ad..dc68b22f760c 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Out-File.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Out-File.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,72 +11,80 @@ title: Out-File # Out-File ## SYNOPSIS + Sends output to a file. ## SYNTAX ### ByPath (Default) -``` + +```powershell Out-File [-FilePath] [[-Encoding] ] [-Append] [-Force] [-NoClobber] [-Width ] [-InputObject ] [-WhatIf] [-Confirm] [] ``` ### ByLiteralPath -``` + +```powershell Out-File -LiteralPath [[-Encoding] ] [-Append] [-Force] [-NoClobber] [-Width ] [-InputObject ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The Out-File cmdlet sends output to a file. You can use this cmdlet instead of the redirection operator (\>) when you need to use its parameters. ## EXAMPLES -### Example 1 -``` -PS C:\> get-process | out-file -filepath C:\Test1\process.txt +### Example 1: Send output to a file + +```powershell +PS C:\> Get-Process | Out-File -filepath C:\Test1\process.txt ``` This command sends a list of processes on the computer to the Process.txt file. If the file does not exist, Out-File creates it. Because the name of the FilePath parameter is optional, you can omit it and submit the equivalent command "get-process | outfile C:\Test1\process.txt". -### Example 2 -``` -PS C:\> get-process | out-file C:\Test1\process.txt -noclobber +### Example 2: Send output to a file without overwriting + +```powershell +PS C:\> Get-Process | Out-File C:\Test1\process.txt -NoClobber Out-File : File C:\Test1\process.txt already exists and NoClobber was specified. At line:1 char:23 -+ get-process | out-file <<<< process.txt -noclobber ++ Get-Process | Out-File <<<< process.txt -NoClobber ``` This command also sends a list of processes to the Process.txt file, but it uses the NoClobber parameter, which prevents an existing file from being overwritten. The output shows the error message that appears when NoClobber is used with an existing file. -### Example 3 -``` -PS C:\> $a = get-process -PS C:\> out-file -filepath C:\Test1\process.txt -inputobject $a -encoding ASCII -width 50 +### Example 3: Send output to a file in ASCII format + +```powershell +PS C:\> $A = Get-Process +PS C:\> Out-File -FilePath C:\Test1\process.txt -InputObject $A -Encoding ASCII -Width 50 ``` These commands send a list of processes on the computer to the Process.txt file. The text is encoded in ASCII format so that it can be read by search programs like Findstr and Grep. By default, Out-File uses Unicode format. -The first command gets the list of processes and stores them in the $a variable. +The first command gets the list of processes and stores them in the $A variable. The second command uses the Out-File cmdlet to send the list to the Process.txt file. -The command uses the InputObject parameter to specify that the input is in the $a variable. +The command uses the InputObject parameter to specify that the input is in the $A variable. It uses the Encoding parameter to convert the output to ASCII format. It uses the Width parameter to limit each line in the file to 50 characters. Because the lines of output are truncated at 50 characters, the rightmost column in the process table is omitted. -### Example 4 -``` -PS C:\> set-location hklm:\software -PS C:\> get-acl mycompany\mykey | out-file -filepath c:\ps\acl.txt -PS C:\> get-acl mycompany\mykey | out-file -filepath filesystem::acl.txt +### Example 4: Send output from outside a file system drive + +```powershell +PS C:\> Set-Location hklm:\software +PS C:\> Get-Acl mycompany\mykey | Out-File -FilePath c:\ps\acl.txt +PS C:\> Get-Acl mycompany\mykey | Out-File -FilePath filesystem::acl.txt ``` These commands show how to use the Out-File cmdlet when you are not in a FileSystem drive. @@ -87,30 +95,60 @@ The second and third commands have the same effect. They use the Get-Acl cmdlet to get the security descriptor of the MyKey registry subkey (HKLM\Software\MyCompany\MyKey). A pipeline operator passes the result to the Out-File cmdlet, which sends it to the Acl.txt file. -Because Out-File is not supported by the Windows PowerShell Registry provider, you must specify either the file system drive name, such as "c:", or the name of the provider followed by two colons, "FileSystem::", in the value of the FilePath parameter. +Because Out-File is not supported by the PowerShell Registry provider, you must specify either the file system drive name, +such as "c:", or the name of the provider followed by two colons, "FileSystem::", in the value of the FilePath parameter. The second and third commands demonstrate these methods. ## PARAMETERS ### -Append + Adds the output to the end of an existing file, instead of replacing the file contents. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf Required: False Position: Named -Default value: Replace +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -Encoding + Specifies the type of character encoding used in the file. -Valid values are "Unicode", "UTF7", "UTF8", "UTF32", "ASCII", "BigEndianUnicode", "Default", and "OEM". -"Unicode" is the default. +The acceptable values for this parameter are: + +- Unknown +- String +- Unicode +- BigEndianUnicode +- UTF8 +- UTF7 +- UTF32 +- ASCII +- Default +- OEM + +Unicode is the default. "Default" uses the encoding of the system's current ANSI code page. @@ -119,7 +157,8 @@ Valid values are "Unicode", "UTF7", "UTF8", "UTF32", "ASCII", "BigEndianUnicode" ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: +Accepted values: unknown, string, unicode, bigendianunicode, utf8, utf7, utf32, ascii, default, oem Required: False Position: 2 @@ -129,12 +168,13 @@ Accept wildcard characters: False ``` ### -FilePath + Specifies the path to the output file. ```yaml Type: String Parameter Sets: ByPath -Aliases: +Aliases: Required: True Position: 1 @@ -144,29 +184,31 @@ Accept wildcard characters: False ``` ### -Force -Allows the cmdlet to overwrite an existing read-only file. + +Indicates that the cmdlet overwrites an existing read-only file. Even using the Force parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -InputObject + Specifies the objects to be written to the file. Enter a variable that contains the objects or type a command or expression that gets the objects. ```yaml Type: PSObject Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -175,47 +217,13 @@ Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` -### -NoClobber -Will not overwrite (replace the contents) of an existing file. -By default, if a file exists in the specified path, Out-File overwrites the file without warning. -If both Append and NoClobber are used, the output is appended to the existing file. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: NoOverwrite - -Required: False -Position: Named -Default value: Overwrite -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Width -Specifies the number of characters in each line of output. -Any additional characters are truncated, not wrapped. -If you omit this parameter, the width is determined by the characteristics of the host. -The default for the Windows PowerShell console is 80 (characters). - -```yaml -Type: Int32 -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: 80 -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -LiteralPath + Specifies the path to the output file. -Unlike **FilePath**, the value of the **LiteralPath** parameter is used exactly as it is typed. +Unlike *FilePath*, the value of the *LiteralPath* parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String @@ -229,22 +237,25 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -Confirm -Prompts you for confirmation before running the cmdlet. +### -NoClobber +Indicates that the cmdlet will not overwrite an existing file. +By default, if a file exists in the specified path, **Out-File** overwrites the file without warning. +If both *Append* and *NoClobber* are used, the output is appended to the existing file. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: cf +Aliases: NoOverwrite Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -260,32 +271,56 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Width +Specifies the number of characters in each line of output. +Any additional characters are truncated, not wrapped. +If you omit this parameter, the width is determined by the characteristics of the host. +The default for the Windows PowerShell console is 80 characters. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see about_CommonParameters +(http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.Management.Automation.PSObject + You can pipe any object to Out-File. ## OUTPUTS ### None + Out-File does not generate any output. ## NOTES -* The Out cmdlets do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. - The Out cmdlets do not have parameters for names or file paths. -To send data to a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. +The Out cmdlets do not format objects; they just render them and send them to the specified display destination. +If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. + +The Out cmdlets do not have parameters for names or file paths. +To send data to a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a PowerShell command to the cmdlet. You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. For help, see the examples. - Out-File sends data, but it does not emit any output objects. +Out-File sends data, but it does not emit any output objects. If you pipe the output of Out-File to Get-Member, Get-Member reports that no objects have been specified. -* - ## RELATED LINKS [Out-Default](../Microsoft.PowerShell.Core/Out-Default.md) diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Write-Host.md b/reference/4.0/Microsoft.PowerShell.Utility/Write-Host.md index bdca96854132..7d70ae62c8e3 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Write-Host.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Write-Host.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,51 +11,57 @@ title: Write-Host # Write-Host ## SYNOPSIS + Writes customized output to a host. ## SYNTAX -``` +```powershell Write-Host [[-Object] ] [-NoNewline] [-Separator ] [-ForegroundColor ] [-BackgroundColor ] [] ``` ## DESCRIPTION + The Write-Host cmdlet customizes output. You can specify the color of text by using the ForegroundColor parameter, and you can specify the background color by using the BackgroundColor parameter. The Separator parameter lets you specify a string to use to separate displayed objects. -The particular result depends on the program that is hosting Windows PowerShell. +The particular result depends on the program that is hosting PowerShell. ## EXAMPLES -### Example 1 -``` -PS C:\> write-host "no newline test " -nonewline +### Example 1: Write to the console without adding a new line + +```powershell +PS C:\> Write-Host "no newline test " -NoNewline no newline test PS C:\> ``` This command displays the input to the console, but because of the NoNewline parameter, the output is followed directly by the prompt. -### Example 2 -``` -PS C:\> write-host (2,4,6,8,10,12) -Separator ", +2= " +### Example 2: Write to the console and include a separator + +```powershell +PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", +2= " 2, +2= 4, +2= 6, +2= 8, +2= 10, +2= 12 ``` This command displays the even numbers from 2 through 12. The Separator parameter is used to add the string , +2= (comma, space, +, 2, =, space). -### Example 3 -``` -PS C:\> write-host (2,4,6,8,10,12) -Separator ", -> " -foregroundcolor DarkGreen -backgroundcolor white +### Example 3: Write with different text and background colors + +```powershell +PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", -> " -ForegroundColor DarkGreen -BackgroundColor White ``` This command displays the even numbers from 2 through 12. It uses the ForegroundColor parameter to output dark green text and the BackgroundColor parameter to display a white background. -### Example 4 -``` -PS C:\> write-host "Red on white text." -ForegroundColor red -BackgroundColor white +### Example 4: Write with different text and background colors + +```powershell +PS C:\> Write-Host "Red on white text." -ForegroundColor red -BackgroundColor white Red on white text. ``` @@ -65,13 +71,33 @@ The background is white, as defined by the BackgroundColor parameter. ## PARAMETERS ### -BackgroundColor + Specifies the background color. There is no default. +The acceptable values for this parameter are: + +- Black +- DarkBlue +- DarkGreen +- DarkCyan +- DarkRed +- DarkMagenta +- DarkYellow +- Gray +- DarkGray +- Blue +- Green +- Cyan +- Red +- Magenta +- Yellow +- White ```yaml Type: ConsoleColor Parameter Sets: (All) -Aliases: +Aliases: +Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White Required: False Position: Named @@ -81,13 +107,33 @@ Accept wildcard characters: False ``` ### -ForegroundColor + Specifies the text color. There is no default. +The acceptable values for this parameter are: + +- Black +- DarkBlue +- DarkGreen +- DarkCyan +- DarkRed +- DarkMagenta +- DarkYellow +- Gray +- DarkGray +- Blue +- Green +- Cyan +- Red +- Magenta +- Yellow +- White ```yaml Type: ConsoleColor Parameter Sets: (All) -Aliases: +Aliases: +Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White Required: False Position: Named @@ -97,12 +143,15 @@ Accept wildcard characters: False ``` ### -NoNewline -Specifies that the content displayed in the console does not end with a newline character. + +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -112,27 +161,28 @@ Accept wildcard characters: False ``` ### -Object -Objects to display in the console. + +Objects to display in the host. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` ### -Separator -String to the output between objects displayed on the console. +Specifies a separator string to insert between objects displayed by the host. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -142,16 +192,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). + +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 objects to be written to the host. ## OUTPUTS ### None + Write-Host sends the objects to the host. It does not return any objects. However, the host might display the objects that Write-Host sends to it. diff --git a/reference/5.0/Microsoft.PowerShell.Management/Add-Content.md b/reference/5.0/Microsoft.PowerShell.Management/Add-Content.md index f30807bdd31e..7d630aa82c86 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Add-Content.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Add-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,78 +11,88 @@ title: Add-Content # Add-Content ## SYNOPSIS + Adds content to the specified items, such as adding words to a file. ## SYNTAX ### Path (Default) -``` + +```powershell Add-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] ``` ### LiteralPath -``` + +```powershell Add-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] ``` ## DESCRIPTION -The **Add-Content** cmdlet appends content to a specified item or file. + +The Add-Content cmdlet appends content to a specified item or file. You can specify the content by typing the content in the command or by specifying an object that contains the content. ## EXAMPLES ### Example 1: Add a string to all text files with an exception -``` + +```powershell PS C:\> Add-Content -Path "*.txt" -Exclude "help*" -Value "END" ``` -This command adds END to all text files in the current directory, except for those with file names that begin with help. +This command adds "END" to all text files in the current directory, except for those with file names that begin with "help". ### Example 2: Add a date to the end of the specified files -``` + +```powershell PS C:\> Add-Content -Path "file1.log", "file2.log" -Value (Get-Date) -PassThru ``` This command adds the date to the end of the File1.log and File2.log files and then displays the date at the command line. -The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to **Add-Content**. -The *PassThru* parameter passes an object representing the added content through the pipeline. +The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to Add-Content. +The PassThru parameter passes an object representing the added content through the pipeline. Because there is no other cmdlet to receive the passed object, it is displayed at the command line. ### Example 3: Add the contents of a specified file to another file -``` + +```powershell PS C:\> Add-Content -Path "monthly.txt" -Value (Get-Content "c:\rec1\weekly.txt") ``` This command adds the contents of the Weekly.txt file to the end of the Monthly.txt file. -The command uses the **Get-Content** cmdlet to get the contents of the Weekly.txt file, and it uses the *Value* parameter to pass the content of weekly.txt to **Add-Content**. -The parentheses ensure that the **Get-Content** command is complete before the **Add-Content** command begins. +It uses the Get-Content cmdlet to get the contents of the Weekly.txt file, and it uses the Value parameter to pass the content of weekly.txt to Add-Content. +The parentheses ensure that the Get-Content command is complete before the Add-Content command begins. -You can also copy the content of Weekly.txt to a variable, such as $String, and then use the *Value* parameter to pass the variable to **Add-Content**. +You can also copy the content of Weekly.txt to a variable, such as $w, and then use the Value parameter to pass the variable to Add-Content. +In that case, the command would be "add-content -path monthly.txt -value $w". ### Example 4: Create a new directory and file and copy content -``` + +```powershell PS C:\> Add-Content -Value (Get-Content "test.log") -Path "C:\tests\test134\logs\test134.log" ``` This command creates a new directory and file and copies the content of an existing file to the newly created file. -This command uses the **Add-Content** cmdlet to add the content. -The value of the *Value* parameter is a **Get-Content** command that gets content from an existing file, Test.log. +This command uses the Add-Content cmdlet to add the content. +The value of the Value parameter is a Get-Content command that gets content from an existing file, Test.log. -The value of the *Path* parameter is a path that does not exist when the command runs. +The value of the path parameter is a path that does not exist when the command runs. In this example, only the C:\Tests directories exist. The command creates the remaining directories and the Test134.log file. -The *Force* parameter is not required for this command. -**Add-Content** creates directories to complete a path even without the *Force* parameter. +The Force parameter is not required for this command. +Add-Content creates directories to complete a path even without the Force parameter. ## PARAMETERS ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -98,18 +108,19 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. -This parameter is not supported by any providers installed with Windows PowerShell. +This parameter is not supported by any providers installed with PowerShell. ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -139,7 +150,7 @@ The acceptable values for this parameter are: ```yaml Type: FileSystemCmdletProviderEncoding Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unknown, String, Unicode, Byte, BigEndianUnicode, UTF8, UTF7, UTF32, Ascii, Default, Oem, BigEndianUTF32 Required: False @@ -150,39 +161,41 @@ Accept wildcard characters: False ``` ### -Exclude -Specifies, as a string array, items that this cmdlet omits. -The value of this parameter qualifies the *Path* parameter. + +Omits the specified items. +The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter + Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force @@ -191,7 +204,7 @@ Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -201,29 +214,31 @@ Accept wildcard characters: False ``` ### -Include -Specifies, as a string array, items that this cmdlet includes. -The value of this parameter qualifies the *Path* parameter. + +Adds only the specified items. +The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath + Specifies the path to the items that receive the additional content. -Unlike the *Path* parameter, the value of the *LiteralPath* parameter is used exactly as it is typed. +Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -240,15 +255,14 @@ Accept wildcard characters: False ### -NoNewline Indicates that this cmdlet does not add a new line/carriage return to the content. -Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the **Get-Credential** cmdlet. -If you type a user name, you will be prompted for a password. - -This parameter is not supported by any providers installed with Windows PowerShell. +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -258,13 +272,14 @@ Accept wildcard characters: False ``` ### -PassThru -Returns an object representing the item with which you are working. + +Returns an object representing the added content. By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -281,13 +296,13 @@ If you specify multiple paths, use commas to separate the paths. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True -Position: 0 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Stream @@ -302,12 +317,12 @@ You can use the **Add-Content** cmdlet to change the content of the Zone.Identif However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -336,6 +351,7 @@ Accept wildcard characters: False ``` ### -Value + Specifies the content to be added. Type a quoted string, such as "This data is for internal use only", or specify an object that contains content, such as the DateTime object that Get-Date generates. @@ -344,10 +360,10 @@ You cannot specify the contents of a file by typing its path, because the path i ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: True -Position: 1 +Position: 2 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False @@ -370,30 +386,33 @@ 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 the objects to be added to this cmdlet. + +You can pipe the objects to be added by Add-Content. ## OUTPUTS ### None or System.String -When you use the *Passthru* parameter, **Add-Content** generates a **System.String** object representing the content. + +When you use the Passthru parameter, Add-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output. ## NOTES -* When you pipe an object to **Add-Content**, the object is converted to a string before it is added to the item. The object type determines the string format, but the format might be different than the default display of the object. To control the string format, use the formatting parameters of the sending cmdlet. - You can also refer to **Add-Content** by its built-in alias, "ac". -For more information, see about_Aliases. +When you pipe an object to Add-Content, the object is converted to a string before it is added to the item. +The object type determines the string format, but the format might be different than the default display of the object. +To control the string format, use the formatting parameters of the sending cmdlet. - The **Add-Content** cmdlet is designed to work with the data exposed by any provider. -To list the providers available in your session, type `Get-PsProvider`. -For more information, see about_Providers. +You can also refer to Add-Content by its built-in alias, "ac". For more information, see about_Aliases. -* +The Add-Content cmdlet is designed to work with the data exposed by any provider. +To list the providers available in your session, type "Get-PsProvider". +For more information, see about_Providers. ## RELATED LINKS @@ -405,3 +424,5 @@ For more information, see about_Providers. [Set-Content](Set-Content.md) +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) + diff --git a/reference/5.0/Microsoft.PowerShell.Management/Set-Content.md b/reference/5.0/Microsoft.PowerShell.Management/Set-Content.md index a6eced7aa434..0b5954ccf2ca 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Set-Content.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Set-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -18,7 +18,7 @@ Writes or replaces the content in an item with new content. ### Path (Default) -``` +```powershell Set-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] @@ -26,7 +26,7 @@ Set-Content [-Value] [-PassThru] [-Path] [-Filter ### LiteralPath -``` +```powershell Set-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] @@ -34,15 +34,15 @@ Set-Content [-Value] [-PassThru] -LiteralPath [-Filter Set-Content -Path "C:\Test1\test*.txt" -Value "Hello, World" ``` @@ -51,32 +51,32 @@ This example shows how to specify content by typing it in the command. ### Example 2: Send content to a file -``` +```powershell PS C:\> Get-Date | Set-Content -Path "C:\Test1\date.csv" ``` -This command creates a comma separated variable length (csv) file that contains only the current date and time. +This command creates a comma-separated variable-length (csv) file that contains only the current date and time. It uses the Get-Date cmdlet to get the current system date and time. -The pipeline operator passes the result to **Set-Content**, which creates the file and writes the content. +The pipeline operator passes the result to Set-Content, which creates the file and writes the content. If the Test1 directory does not exist, the command fails, but if the file does not exist, the command creates it. ### Example 3: Replace text in a file -``` +```powershell PS C:\> (Get-Content -Path "Notice.txt") | ForEach-Object {$_ -Replace "Warning", "Caution"} | Set-Content -Path "Notice.txt" ``` -This command replaces all instances of Warning with Caution in the Notice.txt file. +This command replaces all instances of "Warning" with "Caution" in the Notice.txt file. -It uses **Get-Content** to get the content of Notice.txt. -The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in **Get-Content**. -The expression uses the $_ symbol to refer to the current item and the *Replace* parameter to specify the text to be replaced. +It uses Get-Content cmdlet to get the content of Notice.txt. +The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in Get-Content. +The expression uses the "$_" symbol to refer to the current item and the Replace parameter to specify the text to be replaced. -Another pipeline operator sends the changed content to **Set-Content** which replaces the text in Notice.txt with the new content. +Another pipeline operator sends the changed content to Set-Content which replaces the text in Notice.txt with the new content. -The parentheses around **Get-Content** make sure that the Get operation is complete before the Set operation starts. -Without them, the command fails because the two functions will be trying to access the same file. +The parentheses around the Get-Content command ensure that the Get operation is complete before the Set operation begins. +Without them, the command will fail because the two functions will be trying to access the same file. ## PARAMETERS @@ -101,15 +101,15 @@ Accept wildcard characters: False Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. -This parameter is not supported by any providers installed with Windows PowerShell. +This parameter is not supported by any providers installed with PowerShell. ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -124,15 +124,15 @@ Specifies the file encoding. The acceptable values for this parameter are: - **ASCII** Uses the encoding for the ASCII (7-bit) character set. -- **BigEndianUnicode** Encodes in UTF-16 format using the big-endian byte order. -- **BigEndianUTF32** Encodes in UTF-32 format using the big-endian byte order. +- **BigEndianUnicode** Encodes in UTF-16 format using the big-endian byte order. +- **BigEndianUTF32** Encodes in UTF-32 format using the big-endian byte order. - **Default** Encodes using the default value: ASCII. -- **Byte** Encodes a set of characters into a sequence of bytes. -- **String** Uses the encoding type for a string. -- **Unicode** Encodes in UTF-16 format using the little-endian byte order. +- **Byte** Encodes a set of characters into a sequence of bytes. +- **String** Uses the encoding type for a string. +- **Unicode** Encodes in UTF-16 format using the little-endian byte order. - **UTF7** Encodes in UTF-7 format. -- **UTF8** Encodes in UTF-8 format. -- **Unknown** The encoding type is unknown or invalid; the data can be treated as binary. +- **UTF8** Encodes in UTF-8 format. +- **Unknown** The encoding type is unknown or invalid; the data can be treated as binary. The default value is ASCII. @@ -142,55 +142,54 @@ This parameter works only in file system drives. ```yaml Type: FileSystemCmdletProviderEncoding Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unknown, String, Unicode, Byte, BigEndianUnicode, UTF8, UTF7, UTF32, Ascii, Default, Oem, BigEndianUTF32 Required: False Position: Named -Default value: None +Default value: ASCII Accept pipeline input: False Accept wildcard characters: False ``` ### -Exclude -Specifies items that this cmdlet omits. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcard characters are permitted. +Omits the specified items. +The value of this parameter qualifies the Path parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter Specifies a filter in the format or language of the provider. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcard characters, -depends on the provider. -Filters are more efficient than other parameters, -because the provider applies them when it is retrieving the objects, -instead of having Windows PowerShell filter the objects after they are retrieved. +The value of this parameter qualifies the Path parameter. +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, +because the provider applies them when it is retrieving the objects, +instead of having PowerShell filter the objects after they are retrieved. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force @@ -198,12 +197,12 @@ Accept wildcard characters: False Forces the cmdlet to set the contents of a file, even if the file is read-only. Implementation varies from provider to provider. For more information, see about_Providers. -Even using the *Force* parameter, the cmdlet cannot override security restrictions. +Even using the Force parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -214,30 +213,30 @@ Accept wildcard characters: False ### -Include -Specifies items that this cmdlet changes. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcard characters are permitted. +Changes only the specified items. +The value of this parameter qualifies the Path parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath Specifies the path of the item that receives the content. -Unlike *Path*, the value of the *LiteralPath* parameter is used exactly as it is typed. -No characters are interpreted as wildcard characters. +Unlike Path, the value of LiteralPath is used exactly as it is typed. +No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -253,12 +252,14 @@ Accept wildcard characters: False ### -NoNewline -Indicates that this cmdlet uses the no newline setting. +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -275,7 +276,7 @@ By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -292,13 +293,13 @@ Wildcard characters are permitted. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True -Position: 0 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Stream @@ -307,21 +308,19 @@ Specifies an alternative data stream for content. If the stream does not exist, this cmdlet creates it. Wildcard characters are not supported. -Stream is a dynamic parameter the FileSystem provider adds to **Set-Content**. +Stream is a dynamic parameter that the FileSystem provider adds to **Set-Content**. This parameter works only in file system drives. -You can use the Set-Content cmdlet to change the content of -the Zone.Identifier alternate data stream. -However, we do not recommend this as a way to eliminate security checks -that block files that are downloaded from the Internet. +You can use the **Set-Content** cmdlet to change the content of the Zone.Identifier alternate data stream. +However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -355,10 +354,10 @@ Specifies the new content for the item. ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: True -Position: 1 +Position: 2 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False @@ -383,49 +382,33 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Parameter | --- | - --Debug | --ErrorAction | --ErrorVariable | --InformationAction | --InformationVariable | --OutBuffer | --OutVariable | --PipelineVariable | --Verbose | --WarningAction | --WarningVariable. | - -For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.Object -You can pipe an object that contains the new value for the item to this cmdlet. +You can pipe an object that contains the new value for the item to Set-Content. ## OUTPUTS -### None, System.String +### None or System.String -This cmdlet generates a System.String object that represents the content, -if you specify the *Passthru* parameter. +When you use the Passthru parameter, Set-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output. ## NOTES -You can also refer to **Set-Content** by its built-in alias, **sc**. -For more information, see about_Aliases. +You can also refer to Set-Content by its built-in alias, "sc". For more information, see about_Aliases. -**Set-Content** is designed for string processing. -If you pipe non-string objects to this cmdlet, -it converts the object to a string before writing it. +Set-Content is designed for string processing. +If you pipe non-string objects to Set-Content, it converts the object to a string before writing it. To write objects to files, use Out-File. -**Set-Content** cmdlet is designed to work with the data exposed by any -provider. +The Set-Content cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. @@ -437,4 +420,5 @@ For more information, see about_Providers. [Get-Content](Get-Content.md) +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Out-File.md b/reference/5.0/Microsoft.PowerShell.Utility/Out-File.md index aff754882d7e..a437cef73327 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Out-File.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Out-File.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,39 +11,45 @@ title: Out-File # Out-File ## SYNOPSIS + Sends output to a file. ## SYNTAX ### ByPath (Default) -``` + +```powershell Out-File [-FilePath] [[-Encoding] ] [-Append] [-Force] [-NoClobber] [-Width ] [-NoNewline] [-InputObject ] [-WhatIf] [-Confirm] [] ``` ### ByLiteralPath -``` + +```powershell Out-File -LiteralPath [[-Encoding] ] [-Append] [-Force] [-NoClobber] [-Width ] [-NoNewline] [-InputObject ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **Out-File** cmdlet sends output to a file. + +The Out-File cmdlet sends output to a file. You can use this cmdlet instead of the redirection operator (\>) when you need to use its parameters. ## EXAMPLES ### Example 1: Send output to a file -``` + +```powershell PS C:\> Get-Process | Out-File -filepath C:\Test1\process.txt ``` This command sends a list of processes on the computer to the Process.txt file. -If the file does not exist, **Out-File** creates it. -Because the name of the *FilePath* parameter is optional, you can omit it and submit the equivalent command `Get-Process | Outfile C:\Test1\process.txt`. +If the file does not exist, Out-File creates it. +Because the name of the FilePath parameter is optional, you can omit it and submit the equivalent command "get-process | outfile C:\Test1\process.txt". ### Example 2: Send output to a file without overwriting -``` + +```powershell PS C:\> Get-Process | Out-File C:\Test1\process.txt -NoClobber Out-File : File C:\Test1\process.txt already exists and NoClobber was specified. @@ -51,54 +57,58 @@ At line:1 char:23 + Get-Process | Out-File <<<< process.txt -NoClobber ``` -This command sends a list of processes to the Process.txt file, but it uses the *NoClobber* parameter, which prevents an existing file from being overwritten. -The output shows the error message that appears when *NoClobber* is used with an existing file. +This command also sends a list of processes to the Process.txt file, but it uses the NoClobber parameter, which prevents an existing file from being overwritten. +The output shows the error message that appears when NoClobber is used with an existing file. ### Example 3: Send output to a file in ASCII format -``` + +```powershell PS C:\> $A = Get-Process PS C:\> Out-File -FilePath C:\Test1\process.txt -InputObject $A -Encoding ASCII -Width 50 ``` These commands send a list of processes on the computer to the Process.txt file. The text is encoded in ASCII format so that it can be read by search programs like Findstr and Grep. -By default, **Out-File** uses Unicode format. +By default, Out-File uses Unicode format. The first command gets the list of processes and stores them in the $A variable. -The second command uses the **Out-File** cmdlet to send the list to the Process.txt file. +The second command uses the Out-File cmdlet to send the list to the Process.txt file. -The command uses the *InputObject* parameter to specify that the input is in the $A variable. -It uses the *Encoding* parameter to convert the output to ASCII format. -It uses the *Width* parameter to limit each line in the file to 50 characters. +The command uses the InputObject parameter to specify that the input is in the $A variable. +It uses the Encoding parameter to convert the output to ASCII format. +It uses the Width parameter to limit each line in the file to 50 characters. Because the lines of output are truncated at 50 characters, the rightmost column in the process table is omitted. ### Example 4: Send output from outside a file system drive -``` + +```powershell PS C:\> Set-Location hklm:\software PS C:\> Get-Acl mycompany\mykey | Out-File -FilePath c:\ps\acl.txt PS C:\> Get-Acl mycompany\mykey | Out-File -FilePath filesystem::acl.txt ``` -These commands show how to use the **Out-File** cmdlet when you are not in a FileSystem drive. +These commands show how to use the Out-File cmdlet when you are not in a FileSystem drive. The first command sets the current location to the HKLM:\Software registry key. The second and third commands have the same effect. They use the Get-Acl cmdlet to get the security descriptor of the MyKey registry subkey (HKLM\Software\MyCompany\MyKey). -A pipeline operator passes the result to the **Out-File** cmdlet, which sends it to the Acl.txt file. +A pipeline operator passes the result to the Out-File cmdlet, which sends it to the Acl.txt file. -Because **Out-File** is not supported by the Windows PowerShell Registry provider, you must specify either the file system drive name, such as c:, or the name of the provider followed by two colons, FileSystem::, in the value of the *FilePath* parameter. +Because Out-File is not supported by the PowerShell Registry provider, you must specify either the file system drive name, +such as "c:", or the name of the provider followed by two colons, "FileSystem::", in the value of the FilePath parameter. The second and third commands demonstrate these methods. ## PARAMETERS ### -Append -Indicates that the cmdlet adds the output to the end of an existing file, instead of replacing the file contents. + +Adds the output to the end of an existing file, instead of replacing the file contents. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -123,6 +133,7 @@ Accept wildcard characters: False ``` ### -Encoding + Specifies the type of character encoding used in the file. The acceptable values for this parameter are: @@ -139,46 +150,48 @@ The acceptable values for this parameter are: Unicode is the default. -Default uses the encoding of the system's current ANSI code page. +"Default" uses the encoding of the system's current ANSI code page. -OEM uses the current original equipment manufacturer code page identifier for the operating system. +"OEM" uses the current original equipment manufacturer code page identifier for the operating system. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Accepted values: unknown, string, unicode, bigendianunicode, utf8, utf7, utf32, ascii, default, oem Required: False -Position: 1 -Default value: None +Position: 2 +Default value: Unicode Accept pipeline input: False Accept wildcard characters: False ``` ### -FilePath + Specifies the path to the output file. ```yaml Type: String Parameter Sets: ByPath -Aliases: +Aliases: Required: True -Position: 0 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Force + Indicates that the cmdlet overwrites an existing read-only file. -Even using the *Force* parameter, the cmdlet cannot override security restrictions. +Even using the Force parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -188,13 +201,14 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the objects to be written to the file. Enter a variable that contains the objects or type a command or expression that gets the objects. ```yaml Type: PSObject Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -204,11 +218,12 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies the path to the output file. Unlike *FilePath*, the value of the *LiteralPath* parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String @@ -240,7 +255,10 @@ Accept wildcard characters: False ``` ### -NoNewline -Specifies that the content displayed in the console does not end with a newline character. +Specifies that the content written to the file does not end with a newline character. +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter @@ -255,6 +273,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -289,30 +308,36 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see about_CommonParameters +(http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.Management.Automation.PSObject -You can pipe any object to this cmdlet. + +You can pipe any object to Out-File. ## OUTPUTS ### None -**Out-File** does not generate any output. + +Out-File does not generate any output. ## NOTES -* The Out cmdlets do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. - The Out cmdlets do not have parameters for names or file paths. -To send data to a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. -You can also store data in a variable and use the *InputObject* parameter to pass the data to the cmdlet. -For help, see the examples. +The Out cmdlets do not format objects; they just render them and send them to the specified display destination. +If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. - **Out-File** sends data, but it does not emit any output objects. -If you pipe the output of **Out-File** to Get-Member, **Get-Member** reports that no objects have been specified. +The Out cmdlets do not have parameters for names or file paths. +To send data to a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a PowerShell command to the cmdlet. +You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. +For help, see the examples. -* +Out-File sends data, but it does not emit any output objects. +If you pipe the output of Out-File to Get-Member, Get-Member reports that no objects have been specified. ## RELATED LINKS diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Write-Host.md b/reference/5.0/Microsoft.PowerShell.Utility/Write-Host.md index 50bc061f9527..f48605ea4f86 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Write-Host.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Write-Host.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,60 +11,67 @@ title: Write-Host # Write-Host ## SYNOPSIS + Writes customized output to a host. ## SYNTAX -``` +```powershell Write-Host [[-Object] ] [-NoNewline] [-Separator ] [-ForegroundColor ] [-BackgroundColor ] [] ``` ## DESCRIPTION -The **Write-Host** cmdlet customizes output. -You can specify the color of text by using the *ForegroundColor* parameter, and you can specify the background color by using the *BackgroundColor* parameter. -The *Separator* parameter lets you specify a string to use to separate displayed objects. -The particular result depends on the program that is hosting Windows PowerShell. + +The Write-Host cmdlet customizes output. +You can specify the color of text by using the ForegroundColor parameter, and you can specify the background color by using the BackgroundColor parameter. +The Separator parameter lets you specify a string to use to separate displayed objects. +The particular result depends on the program that is hosting PowerShell. ## EXAMPLES ### Example 1: Write to the console without adding a new line -``` + +```powershell PS C:\> Write-Host "no newline test " -NoNewline no newline test PS C:\> ``` -This command displays the input to the console, but because of the *NoNewline* parameter, the output is followed directly by the prompt. +This command displays the input to the console, but because of the NoNewline parameter, the output is followed directly by the prompt. ### Example 2: Write to the console and include a separator -``` + +```powershell PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", +2= " 2, +2= 4, +2= 6, +2= 8, +2= 10, +2= 12 ``` This command displays the even numbers from 2 through 12. -The *Separator* parameter is used to add the string ", +2= (comma, space, +, 2, =, space)". +The Separator parameter is used to add the string , +2= (comma, space, +, 2, =, space). ### Example 3: Write with different text and background colors -``` -PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", -> " -ForegroundColor DarkGreen -BackgroundColor white + +```powershell +PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", -> " -ForegroundColor DarkGreen -BackgroundColor White ``` This command displays the even numbers from 2 through 12. -It uses the *ForegroundColor* parameter to output dark green text and the *BackgroundColor* parameter to display a white background. +It uses the ForegroundColor parameter to output dark green text and the BackgroundColor parameter to display a white background. ### Example 4: Write with different text and background colors -``` + +```powershell PS C:\> Write-Host "Red on white text." -ForegroundColor red -BackgroundColor white Red on white text. ``` -This command displays the string "Red on white text." The text is red, as defined by the *ForegroundColor* parameter. -The background is white, as defined by the *BackgroundColor* parameter. +This command displays the string "Red on white text." The text is red, as defined by the ForegroundColor parameter. +The background is white, as defined by the BackgroundColor parameter. ## PARAMETERS ### -BackgroundColor + Specifies the background color. There is no default. The acceptable values for this parameter are: @@ -89,7 +96,7 @@ The acceptable values for this parameter are: ```yaml Type: ConsoleColor Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White Required: False @@ -100,6 +107,7 @@ Accept wildcard characters: False ``` ### -ForegroundColor + Specifies the text color. There is no default. The acceptable values for this parameter are: @@ -124,7 +132,7 @@ The acceptable values for this parameter are: ```yaml Type: ConsoleColor Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White Required: False @@ -135,12 +143,15 @@ Accept wildcard characters: False ``` ### -NoNewline -Specifies that the content displayed in the console does not end with a newline character. + +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -150,12 +161,13 @@ Accept wildcard characters: False ``` ### -Object -Specifies objects to display in the console. + +Objects to display in the host. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 0 @@ -165,12 +177,12 @@ Accept wildcard characters: False ``` ### -Separator -Specifies a separator string to the output between objects displayed on the console. +Specifies a separator string to insert between objects displayed by the host. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -180,19 +192,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). + +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 objects to be written to the host. ## OUTPUTS ### None -**Write-Host** sends the objects to the host. + +Write-Host sends the objects to the host. It does not return any objects. -However, the host might display the objects that **Write-Host** sends to it. +However, the host might display the objects that Write-Host sends to it. ## NOTES diff --git a/reference/5.1/Microsoft.PowerShell.Management/Add-Content.md b/reference/5.1/Microsoft.PowerShell.Management/Add-Content.md index f30807bdd31e..7d630aa82c86 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Add-Content.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Add-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,78 +11,88 @@ title: Add-Content # Add-Content ## SYNOPSIS + Adds content to the specified items, such as adding words to a file. ## SYNTAX ### Path (Default) -``` + +```powershell Add-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] ``` ### LiteralPath -``` + +```powershell Add-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] ``` ## DESCRIPTION -The **Add-Content** cmdlet appends content to a specified item or file. + +The Add-Content cmdlet appends content to a specified item or file. You can specify the content by typing the content in the command or by specifying an object that contains the content. ## EXAMPLES ### Example 1: Add a string to all text files with an exception -``` + +```powershell PS C:\> Add-Content -Path "*.txt" -Exclude "help*" -Value "END" ``` -This command adds END to all text files in the current directory, except for those with file names that begin with help. +This command adds "END" to all text files in the current directory, except for those with file names that begin with "help". ### Example 2: Add a date to the end of the specified files -``` + +```powershell PS C:\> Add-Content -Path "file1.log", "file2.log" -Value (Get-Date) -PassThru ``` This command adds the date to the end of the File1.log and File2.log files and then displays the date at the command line. -The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to **Add-Content**. -The *PassThru* parameter passes an object representing the added content through the pipeline. +The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to Add-Content. +The PassThru parameter passes an object representing the added content through the pipeline. Because there is no other cmdlet to receive the passed object, it is displayed at the command line. ### Example 3: Add the contents of a specified file to another file -``` + +```powershell PS C:\> Add-Content -Path "monthly.txt" -Value (Get-Content "c:\rec1\weekly.txt") ``` This command adds the contents of the Weekly.txt file to the end of the Monthly.txt file. -The command uses the **Get-Content** cmdlet to get the contents of the Weekly.txt file, and it uses the *Value* parameter to pass the content of weekly.txt to **Add-Content**. -The parentheses ensure that the **Get-Content** command is complete before the **Add-Content** command begins. +It uses the Get-Content cmdlet to get the contents of the Weekly.txt file, and it uses the Value parameter to pass the content of weekly.txt to Add-Content. +The parentheses ensure that the Get-Content command is complete before the Add-Content command begins. -You can also copy the content of Weekly.txt to a variable, such as $String, and then use the *Value* parameter to pass the variable to **Add-Content**. +You can also copy the content of Weekly.txt to a variable, such as $w, and then use the Value parameter to pass the variable to Add-Content. +In that case, the command would be "add-content -path monthly.txt -value $w". ### Example 4: Create a new directory and file and copy content -``` + +```powershell PS C:\> Add-Content -Value (Get-Content "test.log") -Path "C:\tests\test134\logs\test134.log" ``` This command creates a new directory and file and copies the content of an existing file to the newly created file. -This command uses the **Add-Content** cmdlet to add the content. -The value of the *Value* parameter is a **Get-Content** command that gets content from an existing file, Test.log. +This command uses the Add-Content cmdlet to add the content. +The value of the Value parameter is a Get-Content command that gets content from an existing file, Test.log. -The value of the *Path* parameter is a path that does not exist when the command runs. +The value of the path parameter is a path that does not exist when the command runs. In this example, only the C:\Tests directories exist. The command creates the remaining directories and the Test134.log file. -The *Force* parameter is not required for this command. -**Add-Content** creates directories to complete a path even without the *Force* parameter. +The Force parameter is not required for this command. +Add-Content creates directories to complete a path even without the Force parameter. ## PARAMETERS ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -98,18 +108,19 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. -This parameter is not supported by any providers installed with Windows PowerShell. +This parameter is not supported by any providers installed with PowerShell. ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -139,7 +150,7 @@ The acceptable values for this parameter are: ```yaml Type: FileSystemCmdletProviderEncoding Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unknown, String, Unicode, Byte, BigEndianUnicode, UTF8, UTF7, UTF32, Ascii, Default, Oem, BigEndianUTF32 Required: False @@ -150,39 +161,41 @@ Accept wildcard characters: False ``` ### -Exclude -Specifies, as a string array, items that this cmdlet omits. -The value of this parameter qualifies the *Path* parameter. + +Omits the specified items. +The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter + Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. +The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force @@ -191,7 +204,7 @@ Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -201,29 +214,31 @@ Accept wildcard characters: False ``` ### -Include -Specifies, as a string array, items that this cmdlet includes. -The value of this parameter qualifies the *Path* parameter. + +Adds only the specified items. +The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath + Specifies the path to the items that receive the additional content. -Unlike the *Path* parameter, the value of the *LiteralPath* parameter is used exactly as it is typed. +Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -240,15 +255,14 @@ Accept wildcard characters: False ### -NoNewline Indicates that this cmdlet does not add a new line/carriage return to the content. -Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the **Get-Credential** cmdlet. -If you type a user name, you will be prompted for a password. - -This parameter is not supported by any providers installed with Windows PowerShell. +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -258,13 +272,14 @@ Accept wildcard characters: False ``` ### -PassThru -Returns an object representing the item with which you are working. + +Returns an object representing the added content. By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -281,13 +296,13 @@ If you specify multiple paths, use commas to separate the paths. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True -Position: 0 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Stream @@ -302,12 +317,12 @@ You can use the **Add-Content** cmdlet to change the content of the Zone.Identif However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -336,6 +351,7 @@ Accept wildcard characters: False ``` ### -Value + Specifies the content to be added. Type a quoted string, such as "This data is for internal use only", or specify an object that contains content, such as the DateTime object that Get-Date generates. @@ -344,10 +360,10 @@ You cannot specify the contents of a file by typing its path, because the path i ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: True -Position: 1 +Position: 2 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False @@ -370,30 +386,33 @@ 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 the objects to be added to this cmdlet. + +You can pipe the objects to be added by Add-Content. ## OUTPUTS ### None or System.String -When you use the *Passthru* parameter, **Add-Content** generates a **System.String** object representing the content. + +When you use the Passthru parameter, Add-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output. ## NOTES -* When you pipe an object to **Add-Content**, the object is converted to a string before it is added to the item. The object type determines the string format, but the format might be different than the default display of the object. To control the string format, use the formatting parameters of the sending cmdlet. - You can also refer to **Add-Content** by its built-in alias, "ac". -For more information, see about_Aliases. +When you pipe an object to Add-Content, the object is converted to a string before it is added to the item. +The object type determines the string format, but the format might be different than the default display of the object. +To control the string format, use the formatting parameters of the sending cmdlet. - The **Add-Content** cmdlet is designed to work with the data exposed by any provider. -To list the providers available in your session, type `Get-PsProvider`. -For more information, see about_Providers. +You can also refer to Add-Content by its built-in alias, "ac". For more information, see about_Aliases. -* +The Add-Content cmdlet is designed to work with the data exposed by any provider. +To list the providers available in your session, type "Get-PsProvider". +For more information, see about_Providers. ## RELATED LINKS @@ -405,3 +424,5 @@ For more information, see about_Providers. [Set-Content](Set-Content.md) +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) + diff --git a/reference/5.1/Microsoft.PowerShell.Management/Set-Content.md b/reference/5.1/Microsoft.PowerShell.Management/Set-Content.md index a6eced7aa434..0b5954ccf2ca 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Set-Content.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Set-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -18,7 +18,7 @@ Writes or replaces the content in an item with new content. ### Path (Default) -``` +```powershell Set-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] @@ -26,7 +26,7 @@ Set-Content [-Value] [-PassThru] [-Path] [-Filter ### LiteralPath -``` +```powershell Set-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] @@ -34,15 +34,15 @@ Set-Content [-Value] [-PassThru] -LiteralPath [-Filter Set-Content -Path "C:\Test1\test*.txt" -Value "Hello, World" ``` @@ -51,32 +51,32 @@ This example shows how to specify content by typing it in the command. ### Example 2: Send content to a file -``` +```powershell PS C:\> Get-Date | Set-Content -Path "C:\Test1\date.csv" ``` -This command creates a comma separated variable length (csv) file that contains only the current date and time. +This command creates a comma-separated variable-length (csv) file that contains only the current date and time. It uses the Get-Date cmdlet to get the current system date and time. -The pipeline operator passes the result to **Set-Content**, which creates the file and writes the content. +The pipeline operator passes the result to Set-Content, which creates the file and writes the content. If the Test1 directory does not exist, the command fails, but if the file does not exist, the command creates it. ### Example 3: Replace text in a file -``` +```powershell PS C:\> (Get-Content -Path "Notice.txt") | ForEach-Object {$_ -Replace "Warning", "Caution"} | Set-Content -Path "Notice.txt" ``` -This command replaces all instances of Warning with Caution in the Notice.txt file. +This command replaces all instances of "Warning" with "Caution" in the Notice.txt file. -It uses **Get-Content** to get the content of Notice.txt. -The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in **Get-Content**. -The expression uses the $_ symbol to refer to the current item and the *Replace* parameter to specify the text to be replaced. +It uses Get-Content cmdlet to get the content of Notice.txt. +The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in Get-Content. +The expression uses the "$_" symbol to refer to the current item and the Replace parameter to specify the text to be replaced. -Another pipeline operator sends the changed content to **Set-Content** which replaces the text in Notice.txt with the new content. +Another pipeline operator sends the changed content to Set-Content which replaces the text in Notice.txt with the new content. -The parentheses around **Get-Content** make sure that the Get operation is complete before the Set operation starts. -Without them, the command fails because the two functions will be trying to access the same file. +The parentheses around the Get-Content command ensure that the Get operation is complete before the Set operation begins. +Without them, the command will fail because the two functions will be trying to access the same file. ## PARAMETERS @@ -101,15 +101,15 @@ Accept wildcard characters: False Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. -This parameter is not supported by any providers installed with Windows PowerShell. +This parameter is not supported by any providers installed with PowerShell. ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -124,15 +124,15 @@ Specifies the file encoding. The acceptable values for this parameter are: - **ASCII** Uses the encoding for the ASCII (7-bit) character set. -- **BigEndianUnicode** Encodes in UTF-16 format using the big-endian byte order. -- **BigEndianUTF32** Encodes in UTF-32 format using the big-endian byte order. +- **BigEndianUnicode** Encodes in UTF-16 format using the big-endian byte order. +- **BigEndianUTF32** Encodes in UTF-32 format using the big-endian byte order. - **Default** Encodes using the default value: ASCII. -- **Byte** Encodes a set of characters into a sequence of bytes. -- **String** Uses the encoding type for a string. -- **Unicode** Encodes in UTF-16 format using the little-endian byte order. +- **Byte** Encodes a set of characters into a sequence of bytes. +- **String** Uses the encoding type for a string. +- **Unicode** Encodes in UTF-16 format using the little-endian byte order. - **UTF7** Encodes in UTF-7 format. -- **UTF8** Encodes in UTF-8 format. -- **Unknown** The encoding type is unknown or invalid; the data can be treated as binary. +- **UTF8** Encodes in UTF-8 format. +- **Unknown** The encoding type is unknown or invalid; the data can be treated as binary. The default value is ASCII. @@ -142,55 +142,54 @@ This parameter works only in file system drives. ```yaml Type: FileSystemCmdletProviderEncoding Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unknown, String, Unicode, Byte, BigEndianUnicode, UTF8, UTF7, UTF32, Ascii, Default, Oem, BigEndianUTF32 Required: False Position: Named -Default value: None +Default value: ASCII Accept pipeline input: False Accept wildcard characters: False ``` ### -Exclude -Specifies items that this cmdlet omits. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcard characters are permitted. +Omits the specified items. +The value of this parameter qualifies the Path parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter Specifies a filter in the format or language of the provider. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcard characters, -depends on the provider. -Filters are more efficient than other parameters, -because the provider applies them when it is retrieving the objects, -instead of having Windows PowerShell filter the objects after they are retrieved. +The value of this parameter qualifies the Path parameter. +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, +because the provider applies them when it is retrieving the objects, +instead of having PowerShell filter the objects after they are retrieved. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force @@ -198,12 +197,12 @@ Accept wildcard characters: False Forces the cmdlet to set the contents of a file, even if the file is read-only. Implementation varies from provider to provider. For more information, see about_Providers. -Even using the *Force* parameter, the cmdlet cannot override security restrictions. +Even using the Force parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -214,30 +213,30 @@ Accept wildcard characters: False ### -Include -Specifies items that this cmdlet changes. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcard characters are permitted. +Changes only the specified items. +The value of this parameter qualifies the Path parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath Specifies the path of the item that receives the content. -Unlike *Path*, the value of the *LiteralPath* parameter is used exactly as it is typed. -No characters are interpreted as wildcard characters. +Unlike Path, the value of LiteralPath is used exactly as it is typed. +No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -253,12 +252,14 @@ Accept wildcard characters: False ### -NoNewline -Indicates that this cmdlet uses the no newline setting. +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -275,7 +276,7 @@ By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -292,13 +293,13 @@ Wildcard characters are permitted. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True -Position: 0 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Stream @@ -307,21 +308,19 @@ Specifies an alternative data stream for content. If the stream does not exist, this cmdlet creates it. Wildcard characters are not supported. -Stream is a dynamic parameter the FileSystem provider adds to **Set-Content**. +Stream is a dynamic parameter that the FileSystem provider adds to **Set-Content**. This parameter works only in file system drives. -You can use the Set-Content cmdlet to change the content of -the Zone.Identifier alternate data stream. -However, we do not recommend this as a way to eliminate security checks -that block files that are downloaded from the Internet. +You can use the **Set-Content** cmdlet to change the content of the Zone.Identifier alternate data stream. +However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -355,10 +354,10 @@ Specifies the new content for the item. ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: True -Position: 1 +Position: 2 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False @@ -383,49 +382,33 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Parameter | --- | - --Debug | --ErrorAction | --ErrorVariable | --InformationAction | --InformationVariable | --OutBuffer | --OutVariable | --PipelineVariable | --Verbose | --WarningAction | --WarningVariable. | - -For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.Object -You can pipe an object that contains the new value for the item to this cmdlet. +You can pipe an object that contains the new value for the item to Set-Content. ## OUTPUTS -### None, System.String +### None or System.String -This cmdlet generates a System.String object that represents the content, -if you specify the *Passthru* parameter. +When you use the Passthru parameter, Set-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output. ## NOTES -You can also refer to **Set-Content** by its built-in alias, **sc**. -For more information, see about_Aliases. +You can also refer to Set-Content by its built-in alias, "sc". For more information, see about_Aliases. -**Set-Content** is designed for string processing. -If you pipe non-string objects to this cmdlet, -it converts the object to a string before writing it. +Set-Content is designed for string processing. +If you pipe non-string objects to Set-Content, it converts the object to a string before writing it. To write objects to files, use Out-File. -**Set-Content** cmdlet is designed to work with the data exposed by any -provider. +The Set-Content cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. @@ -437,4 +420,5 @@ For more information, see about_Providers. [Get-Content](Get-Content.md) +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Out-File.md b/reference/5.1/Microsoft.PowerShell.Utility/Out-File.md index 9dbfb752cac4..a437cef73327 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Out-File.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Out-File.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,39 +11,45 @@ title: Out-File # Out-File ## SYNOPSIS + Sends output to a file. ## SYNTAX ### ByPath (Default) -``` + +```powershell Out-File [-FilePath] [[-Encoding] ] [-Append] [-Force] [-NoClobber] [-Width ] [-NoNewline] [-InputObject ] [-WhatIf] [-Confirm] [] ``` ### ByLiteralPath -``` + +```powershell Out-File -LiteralPath [[-Encoding] ] [-Append] [-Force] [-NoClobber] [-Width ] [-NoNewline] [-InputObject ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **Out-File** cmdlet sends output to a file. + +The Out-File cmdlet sends output to a file. You can use this cmdlet instead of the redirection operator (\>) when you need to use its parameters. ## EXAMPLES ### Example 1: Send output to a file -``` + +```powershell PS C:\> Get-Process | Out-File -filepath C:\Test1\process.txt ``` This command sends a list of processes on the computer to the Process.txt file. -If the file does not exist, **Out-File** creates it. -Because the name of the *FilePath* parameter is optional, you can omit it and submit the equivalent command `Get-Process | Outfile C:\Test1\process.txt`. +If the file does not exist, Out-File creates it. +Because the name of the FilePath parameter is optional, you can omit it and submit the equivalent command "get-process | outfile C:\Test1\process.txt". ### Example 2: Send output to a file without overwriting -``` + +```powershell PS C:\> Get-Process | Out-File C:\Test1\process.txt -NoClobber Out-File : File C:\Test1\process.txt already exists and NoClobber was specified. @@ -51,54 +57,58 @@ At line:1 char:23 + Get-Process | Out-File <<<< process.txt -NoClobber ``` -This command sends a list of processes to the Process.txt file, but it uses the *NoClobber* parameter, which prevents an existing file from being overwritten. -The output shows the error message that appears when *NoClobber* is used with an existing file. +This command also sends a list of processes to the Process.txt file, but it uses the NoClobber parameter, which prevents an existing file from being overwritten. +The output shows the error message that appears when NoClobber is used with an existing file. ### Example 3: Send output to a file in ASCII format -``` + +```powershell PS C:\> $A = Get-Process PS C:\> Out-File -FilePath C:\Test1\process.txt -InputObject $A -Encoding ASCII -Width 50 ``` These commands send a list of processes on the computer to the Process.txt file. The text is encoded in ASCII format so that it can be read by search programs like Findstr and Grep. -By default, **Out-File** uses Unicode format. +By default, Out-File uses Unicode format. The first command gets the list of processes and stores them in the $A variable. -The second command uses the **Out-File** cmdlet to send the list to the Process.txt file. +The second command uses the Out-File cmdlet to send the list to the Process.txt file. -The command uses the *InputObject* parameter to specify that the input is in the $A variable. -It uses the *Encoding* parameter to convert the output to ASCII format. -It uses the *Width* parameter to limit each line in the file to 50 characters. +The command uses the InputObject parameter to specify that the input is in the $A variable. +It uses the Encoding parameter to convert the output to ASCII format. +It uses the Width parameter to limit each line in the file to 50 characters. Because the lines of output are truncated at 50 characters, the rightmost column in the process table is omitted. ### Example 4: Send output from outside a file system drive -``` + +```powershell PS C:\> Set-Location hklm:\software PS C:\> Get-Acl mycompany\mykey | Out-File -FilePath c:\ps\acl.txt PS C:\> Get-Acl mycompany\mykey | Out-File -FilePath filesystem::acl.txt ``` -These commands show how to use the **Out-File** cmdlet when you are not in a FileSystem drive. +These commands show how to use the Out-File cmdlet when you are not in a FileSystem drive. The first command sets the current location to the HKLM:\Software registry key. The second and third commands have the same effect. They use the Get-Acl cmdlet to get the security descriptor of the MyKey registry subkey (HKLM\Software\MyCompany\MyKey). -A pipeline operator passes the result to the **Out-File** cmdlet, which sends it to the Acl.txt file. +A pipeline operator passes the result to the Out-File cmdlet, which sends it to the Acl.txt file. -Because **Out-File** is not supported by the Windows PowerShell Registry provider, you must specify either the file system drive name, such as c:, or the name of the provider followed by two colons, FileSystem::, in the value of the *FilePath* parameter. +Because Out-File is not supported by the PowerShell Registry provider, you must specify either the file system drive name, +such as "c:", or the name of the provider followed by two colons, "FileSystem::", in the value of the FilePath parameter. The second and third commands demonstrate these methods. ## PARAMETERS ### -Append -Indicates that the cmdlet adds the output to the end of an existing file, instead of replacing the file contents. + +Adds the output to the end of an existing file, instead of replacing the file contents. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -123,6 +133,7 @@ Accept wildcard characters: False ``` ### -Encoding + Specifies the type of character encoding used in the file. The acceptable values for this parameter are: @@ -139,46 +150,48 @@ The acceptable values for this parameter are: Unicode is the default. -Default uses the encoding of the system's current ANSI code page. +"Default" uses the encoding of the system's current ANSI code page. -OEM uses the current original equipment manufacturer code page identifier for the operating system. +"OEM" uses the current original equipment manufacturer code page identifier for the operating system. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Accepted values: unknown, string, unicode, bigendianunicode, utf8, utf7, utf32, ascii, default, oem Required: False -Position: 1 -Default value: None +Position: 2 +Default value: Unicode Accept pipeline input: False Accept wildcard characters: False ``` ### -FilePath + Specifies the path to the output file. ```yaml Type: String Parameter Sets: ByPath -Aliases: +Aliases: Required: True -Position: 0 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Force + Indicates that the cmdlet overwrites an existing read-only file. -Even using the *Force* parameter, the cmdlet cannot override security restrictions. +Even using the Force parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -188,13 +201,14 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the objects to be written to the file. Enter a variable that contains the objects or type a command or expression that gets the objects. ```yaml Type: PSObject Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -204,11 +218,12 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies the path to the output file. Unlike *FilePath*, the value of the *LiteralPath* parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String @@ -240,7 +255,10 @@ Accept wildcard characters: False ``` ### -NoNewline -Specifies that the content displayed in the console does not end with a newline character. +Specifies that the content written to the file does not end with a newline character. +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter @@ -255,6 +273,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -289,35 +308,47 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see about_CommonParameters +(http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.Management.Automation.PSObject -You can pipe any object to this cmdlet. + +You can pipe any object to Out-File. ## OUTPUTS ### None -**Out-File** does not generate any output. + +Out-File does not generate any output. ## NOTES -* The Out cmdlets do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. - The Out cmdlets do not have parameters for names or file paths. -To send data to a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. -You can also store data in a variable and use the *InputObject* parameter to pass the data to the cmdlet. -For help, see the examples. +The Out cmdlets do not format objects; they just render them and send them to the specified display destination. +If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. - **Out-File** sends data, but it does not emit any output objects. -If you pipe the output of **Out-File** to Get-Member, **Get-Member** reports that no objects have been specified. +The Out cmdlets do not have parameters for names or file paths. +To send data to a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a PowerShell command to the cmdlet. +You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. +For help, see the examples. -* +Out-File sends data, but it does not emit any output objects. +If you pipe the output of Out-File to Get-Member, Get-Member reports that no objects have been specified. ## RELATED LINKS +[Out-Default](../Microsoft.PowerShell.Core/Out-Default.md) + [Out-GridView](Out-GridView.md) +[Out-Host](../Microsoft.PowerShell.Core/Out-Host.md) + +[Out-Null](../Microsoft.PowerShell.Core/Out-Null.md) + [Out-Printer](Out-Printer.md) [Out-String](Out-String.md) diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Write-Host.md b/reference/5.1/Microsoft.PowerShell.Utility/Write-Host.md index c0dd5cbb4858..f48605ea4f86 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Write-Host.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Write-Host.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,60 +11,67 @@ title: Write-Host # Write-Host ## SYNOPSIS + Writes customized output to a host. ## SYNTAX -``` +```powershell Write-Host [[-Object] ] [-NoNewline] [-Separator ] [-ForegroundColor ] [-BackgroundColor ] [] ``` ## DESCRIPTION -The **Write-Host** cmdlet customizes output. -You can specify the color of text by using the *ForegroundColor* parameter, and you can specify the background color by using the *BackgroundColor* parameter. -The *Separator* parameter lets you specify a string to use to separate displayed objects. -The particular result depends on the program that is hosting Windows PowerShell. + +The Write-Host cmdlet customizes output. +You can specify the color of text by using the ForegroundColor parameter, and you can specify the background color by using the BackgroundColor parameter. +The Separator parameter lets you specify a string to use to separate displayed objects. +The particular result depends on the program that is hosting PowerShell. ## EXAMPLES ### Example 1: Write to the console without adding a new line -``` + +```powershell PS C:\> Write-Host "no newline test " -NoNewline no newline test PS C:\> ``` -This command displays the input to the console, but because of the *NoNewline* parameter, the output is followed directly by the prompt. +This command displays the input to the console, but because of the NoNewline parameter, the output is followed directly by the prompt. ### Example 2: Write to the console and include a separator -``` + +```powershell PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", +2= " 2, +2= 4, +2= 6, +2= 8, +2= 10, +2= 12 ``` This command displays the even numbers from 2 through 12. -The *Separator* parameter is used to add the string ", +2= (comma, space, +, 2, =, space)". +The Separator parameter is used to add the string , +2= (comma, space, +, 2, =, space). ### Example 3: Write with different text and background colors -``` -PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", -> " -ForegroundColor DarkGreen -BackgroundColor white + +```powershell +PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", -> " -ForegroundColor DarkGreen -BackgroundColor White ``` This command displays the even numbers from 2 through 12. -It uses the *ForegroundColor* parameter to output dark green text and the *BackgroundColor* parameter to display a white background. +It uses the ForegroundColor parameter to output dark green text and the BackgroundColor parameter to display a white background. ### Example 4: Write with different text and background colors -``` + +```powershell PS C:\> Write-Host "Red on white text." -ForegroundColor red -BackgroundColor white Red on white text. ``` -This command displays the string "Red on white text." The text is red, as defined by the *ForegroundColor* parameter. -The background is white, as defined by the *BackgroundColor* parameter. +This command displays the string "Red on white text." The text is red, as defined by the ForegroundColor parameter. +The background is white, as defined by the BackgroundColor parameter. ## PARAMETERS ### -BackgroundColor + Specifies the background color. There is no default. The acceptable values for this parameter are: @@ -89,7 +96,7 @@ The acceptable values for this parameter are: ```yaml Type: ConsoleColor Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White Required: False @@ -100,6 +107,7 @@ Accept wildcard characters: False ``` ### -ForegroundColor + Specifies the text color. There is no default. The acceptable values for this parameter are: @@ -124,7 +132,7 @@ The acceptable values for this parameter are: ```yaml Type: ConsoleColor Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White Required: False @@ -135,12 +143,15 @@ Accept wildcard characters: False ``` ### -NoNewline -Specifies that the content displayed in the console does not end with a newline character. + +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -150,12 +161,13 @@ Accept wildcard characters: False ``` ### -Object -Specifies objects to display in the console. + +Objects to display in the host. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 0 @@ -165,12 +177,12 @@ Accept wildcard characters: False ``` ### -Separator -Specifies a separator string to the output between objects displayed on the console. +Specifies a separator string to insert between objects displayed by the host. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -180,19 +192,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). + +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 objects to be written to the host. ## OUTPUTS ### None -**Write-Host** sends the objects to the host. + +Write-Host sends the objects to the host. It does not return any objects. -However, the host might display the objects that **Write-Host** sends to it. +However, the host might display the objects that Write-Host sends to it. ## NOTES @@ -200,6 +218,8 @@ However, the host might display the objects that **Write-Host** sends to it. [Clear-Host](../Microsoft.PowerShell.Core/Functions/Clear-Host.md) +[Out-Host](../Microsoft.PowerShell.Core/Out-Host.md) + [Write-Debug](Write-Debug.md) [Write-Error](Write-Error.md) diff --git a/reference/6/Microsoft.PowerShell.Management/Add-Content.md b/reference/6/Microsoft.PowerShell.Management/Add-Content.md index 3ff5ad6b5714..eb1328014646 100644 --- a/reference/6/Microsoft.PowerShell.Management/Add-Content.md +++ b/reference/6/Microsoft.PowerShell.Management/Add-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,12 +11,14 @@ title: Add-Content # Add-Content ## SYNOPSIS + Adds content to the specified items, such as adding words to a file. ## SYNTAX ### Path (Default) -``` + +```powershell Add-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-InformationAction ] [-InformationVariable ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] @@ -24,7 +26,8 @@ Add-Content [-Value] [-PassThru] [-Path] [-Filter ``` ### LiteralPath -``` + +```powershell Add-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-InformationAction ] [-InformationVariable ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] @@ -32,58 +35,102 @@ Add-Content [-Value] [-PassThru] -LiteralPath [-Filter Add-Content -Path "*.txt" -Exclude "help*" -Value "END" ``` -This command adds END to all text files in the current directory, except for those with file names that begin with help. +This command adds "END" to all text files in the current directory, except for those with file names that begin with "help". ### Example 2: Add a date to the end of the specified files -``` + +```powershell PS C:\> Add-Content -Path "file1.log", "file2.log" -Value (Get-Date) -PassThru ``` This command adds the date to the end of the File1.log and File2.log files and then displays the date at the command line. -The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to **Add-Content**. -The *PassThru* parameter passes an object representing the added content through the pipeline. +The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to Add-Content. +The PassThru parameter passes an object representing the added content through the pipeline. Because there is no other cmdlet to receive the passed object, it is displayed at the command line. ### Example 3: Add the contents of a specified file to another file -``` + +```powershell PS C:\> Add-Content -Path "monthly.txt" -Value (Get-Content "c:\rec1\weekly.txt") ``` This command adds the contents of the Weekly.txt file to the end of the Monthly.txt file. -The command uses the **Get-Content** cmdlet to get the contents of the Weekly.txt file, and it uses the *Value* parameter to pass the content of weekly.txt to **Add-Content**. -The parentheses ensure that the **Get-Content** command is complete before the **Add-Content** command begins. +It uses the Get-Content cmdlet to get the contents of the Weekly.txt file, and it uses the Value parameter to pass the content of weekly.txt to Add-Content. +The parentheses ensure that the Get-Content command is complete before the Add-Content command begins. -You can also copy the content of Weekly.txt to a variable, such as $String, and then use the *Value* parameter to pass the variable to **Add-Content**. +You can also copy the content of Weekly.txt to a variable, such as $w, and then use the Value parameter to pass the variable to Add-Content. +In that case, the command would be "add-content -path monthly.txt -value $w". ### Example 4: Create a new directory and file and copy content -``` + +```powershell PS C:\> Add-Content -Value (Get-Content "test.log") -Path "C:\tests\test134\logs\test134.log" ``` This command creates a new directory and file and copies the content of an existing file to the newly created file. -This command uses the **Add-Content** cmdlet to add the content. -The value of the *Value* parameter is a **Get-Content** command that gets content from an existing file, Test.log. +This command uses the Add-Content cmdlet to add the content. +The value of the Value parameter is a Get-Content command that gets content from an existing file, Test.log. -The value of the *Path* parameter is a path that does not exist when the command runs. +The value of the path parameter is a path that does not exist when the command runs. In this example, only the C:\Tests directories exist. The command creates the remaining directories and the Test134.log file. -The *Force* parameter is not required for this command. -**Add-Content** creates directories to complete a path even without the *Force* parameter. +The Force parameter is not required for this command. +Add-Content creates directories to complete a path even without the Force parameter. ## PARAMETERS +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies a user account that has permission to perform this action. +The default is the current user. + +Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. +If you type a user name, you will be prompted for a password. + +This parameter is not supported by any providers installed with PowerShell. + +```yaml +Type: PSCredential +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + ### -Encoding Specifies the encoding that this cmdlet applies to the content. @@ -102,15 +149,10 @@ The acceptable values for this parameter are: - Oem - BigEndianUTF32 -Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the **Get-Credential** cmdlet. -If you type a user name, you will be prompted for a password. - -This parameter is not supported by any providers installed with Windows PowerShell. - ```yaml Type: FileSystemCmdletProviderEncoding Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unknown, String, Unicode, Byte, BigEndianUnicode, UTF8, UTF7, UTF32, Ascii, Default, Oem, BigEndianUTF32 Required: False @@ -120,120 +162,109 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Force -Forces the command to run without asking for user confirmation. +### -Exclude + +Omits the specified items. +The value of this parameter qualifies the Path parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. ```yaml -Type: SwitchParameter +Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` -### -Stream -Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the **Get-Credential** cmdlet. -If you type a user name, you will be prompted for a password. +### -Filter -This parameter is not supported by any providers installed with Windows PowerShell. +Specifies a filter in the provider's format or language. +The value of this parameter qualifies the Path parameter. +The syntax of the filter, including the use of wildcards, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having PowerShell filter the objects after they are retrieved. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` -### -Confirm -Prompts you for confirmation before running the cmdlet. +### -Force +Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: cf +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` +### -Include -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see +Adds only the specified items. +The value of this parameter qualifies the Path parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. ```yaml -Type: SwitchParameter +Type: String[] Parameter Sets: (All) -Aliases: usetx +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` -### -Credential -Specifies a user account that has permission to perform this action. -The default is the current user. - -Type a user name, such as "User01" or "Domain01\User01", or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. -If you type a user name, you will be prompted for a password. +### -LiteralPath -This parameter is not supported by any providers installed with Windows PowerShell. +Specifies the path to the items that receive the additional content. +Unlike Path, the value of LiteralPath is used exactly as it is typed. +No characters are interpreted as wildcards. +If the path includes escape characters, enclose it in single quotation marks. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml -Type: PSCredential -Parameter Sets: (All) -Aliases: +Type: String[] +Parameter Sets: LiteralPath +Aliases: PSPath -Required: False +Required: True Position: Named Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -Exclude -Specifies, as a string array, items that this cmdlet omits. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as "*.txt". -Wildcards are permitted. +### -NoNewline +Indicates that this cmdlet does not add a new line/carriage return to the content. + +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml -Type: String[] +Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -242,16 +273,15 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +### -PassThru + +Returns an object representing the added content. +By default, this cmdlet does not generate any output. ```yaml -Type: String +Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -260,47 +290,41 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Include -Specifies, as a string array, items that this cmdlet includes. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as "*.txt". +### -Path +Specifies the path to the items that receive the additional content. Wildcards are permitted. +If you specify multiple paths, use commas to separate the paths. ```yaml Type: String[] -Parameter Sets: (All) -Aliases: +Parameter Sets: Path +Aliases: -Required: False -Position: Named +Required: True +Position: 1 Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: True ``` -### -InformationAction -Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. +### -Stream +Specifies an alternative data stream for content. +If the stream does not exist, this cmdlet creates it. +Wildcard characters are not supported. -This parameter is not supported by any providers installed with Windows PowerShell.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend +Stream is a dynamic parameter that the FileSystem provider adds to **Add-Content**. +This parameter works only in file system drives. -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` +You can use the **Add-Content** cmdlet to change the content of the Zone.Identifier alternate data stream. +However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. +If you verify that a downloaded file is safe, use the Unblock-File cmdlet. -### -InformationVariable -Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. +This parameter was introduced in PowerShell 3.0. -This parameter is not supported by any providers installed with Windows PowerShell.```yaml +```yaml Type: String Parameter Sets: (All) -Aliases: iv +Aliases: Required: False Position: Named @@ -309,58 +333,25 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -LiteralPath -Specifies the path to the items that receive the additional content. -Unlike the *Path* parameter, the value of the *LiteralPath* parameter is used exactly as it is typed. -No characters are interpreted as wildcards. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. - -```yaml -Type: String[] -Parameter Sets: LiteralPath -Aliases: PSPath - -Required: True -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -PassThru -Returns an object representing the item with which you are working. -By default, this cmdlet does not generate any output. +### -UseTransaction +Includes the command in the active transaction. +This parameter is valid only when a transaction is in progress. +For more information, see Includes the command in the active transaction. +This parameter is valid only when a transaction is in progress. +For more information, see ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: usetx Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` -### -Path -Specifies the path to the items that receive the additional content. -Wildcards are permitted. -If you specify multiple paths, use commas to separate the paths. - -```yaml -Type: String[] -Parameter Sets: Path -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - ### -Value Specifies the content to be added. Type a quoted string, such as "This data is for internal use only", or specify an object that contains content, such as the DateTime object that Get-Date generates. @@ -370,7 +361,7 @@ You cannot specify the contents of a file by typing its path, because the path i ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 2 @@ -379,46 +370,50 @@ Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False ``` -### -NoNewline -Indicates that this cmdlet does not add a new line/carriage return to the content. +### -WhatIf +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: wi Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.Object -You can pipe the objects to be added to this cmdlet. + +You can pipe the objects to be added by Add-Content. ## OUTPUTS ### None or System.String -When you use the *Passthru* parameter, **Add-Content** generates a **System.String** object representing the content. + +When you use the Passthru parameter, Add-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output. ## NOTES -* When you pipe an object to **Add-Content**, the object is converted to a string before it is added to the item. The object type determines the string format, but the format might be different than the default display of the object. To control the string format, use the formatting parameters of the sending cmdlet. - You can also refer to **Add-Content** by its built-in alias, "ac". -For more information, see about_Aliases. +When you pipe an object to Add-Content, the object is converted to a string before it is added to the item. +The object type determines the string format, but the format might be different than the default display of the object. +To control the string format, use the formatting parameters of the sending cmdlet. - The **Add-Content** cmdlet is designed to work with the data exposed by any provider. -To list the providers available in your session, type `Get-PsProvider`. -For more information, see about_Providers. +You can also refer to Add-Content by its built-in alias, "ac". For more information, see about_Aliases. -* +The Add-Content cmdlet is designed to work with the data exposed by any provider. +To list the providers available in your session, type "Get-PsProvider". +For more information, see about_Providers. ## RELATED LINKS @@ -430,3 +425,5 @@ For more information, see about_Providers. [Set-Content](Set-Content.md) +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) + diff --git a/reference/6/Microsoft.PowerShell.Management/Set-Content.md b/reference/6/Microsoft.PowerShell.Management/Set-Content.md index 57ee77bff7fe..d94a653440f6 100644 --- a/reference/6/Microsoft.PowerShell.Management/Set-Content.md +++ b/reference/6/Microsoft.PowerShell.Management/Set-Content.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -18,7 +18,7 @@ Writes or replaces the content in an item with new content. ### Path (Default) -``` +```powershell Set-Content [-Value] [-PassThru] [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] @@ -26,7 +26,7 @@ Set-Content [-Value] [-PassThru] [-Path] [-Filter ### LiteralPath -``` +```powershell Set-Content [-Value] [-PassThru] -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-WhatIf] [-Confirm] [-UseTransaction] [-NoNewline] [-Encoding ] [-Stream ] [] @@ -34,15 +34,15 @@ Set-Content [-Value] [-PassThru] -LiteralPath [-Filter Set-Content -Path "C:\Test1\test*.txt" -Value "Hello, World" ``` @@ -51,32 +51,32 @@ This example shows how to specify content by typing it in the command. ### Example 2: Send content to a file -``` +```powershell PS C:\> Get-Date | Set-Content -Path "C:\Test1\date.csv" ``` -This command creates a comma separated variable length (csv) file that contains only the current date and time. +This command creates a comma-separated variable-length (csv) file that contains only the current date and time. It uses the Get-Date cmdlet to get the current system date and time. -The pipeline operator passes the result to **Set-Content**, which creates the file and writes the content. +The pipeline operator passes the result to Set-Content, which creates the file and writes the content. If the Test1 directory does not exist, the command fails, but if the file does not exist, the command creates it. ### Example 3: Replace text in a file -``` +```powershell PS C:\> (Get-Content -Path "Notice.txt") | ForEach-Object {$_ -Replace "Warning", "Caution"} | Set-Content -Path "Notice.txt" ``` -This command replaces all instances of Warning with Caution in the Notice.txt file. +This command replaces all instances of "Warning" with "Caution" in the Notice.txt file. -It uses **Get-Content** to get the content of Notice.txt. -The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in **Get-Content**. -The expression uses the $_ symbol to refer to the current item and the *Replace* parameter to specify the text to be replaced. +It uses Get-Content cmdlet to get the content of Notice.txt. +The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in Get-Content. +The expression uses the "$_" symbol to refer to the current item and the Replace parameter to specify the text to be replaced. -Another pipeline operator sends the changed content to **Set-Content** which replaces the text in Notice.txt with the new content. +Another pipeline operator sends the changed content to Set-Content which replaces the text in Notice.txt with the new content. -The parentheses around **Get-Content** make sure that the Get operation is complete before the Set operation starts. -Without them, the command fails because the two functions will be trying to access the same file. +The parentheses around the Get-Content command ensure that the Get operation is complete before the Set operation begins. +Without them, the command will fail because the two functions will be trying to access the same file. ## PARAMETERS @@ -101,15 +101,15 @@ Accept wildcard characters: False Specifies a user account that has permission to perform this action. The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one generated by the Get-Credential cmdlet. +Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. -This parameter is not supported by any providers installed with Windows PowerShell. +This parameter is not supported by any providers installed with PowerShell. ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -124,15 +124,15 @@ Specifies the file encoding. The acceptable values for this parameter are: - **ASCII** Uses the encoding for the ASCII (7-bit) character set. -- **BigEndianUnicode** Encodes in UTF-16 format using the big-endian byte order. -- **BigEndianUTF32** Encodes in UTF-32 format using the big-endian byte order. +- **BigEndianUnicode** Encodes in UTF-16 format using the big-endian byte order. +- **BigEndianUTF32** Encodes in UTF-32 format using the big-endian byte order. - **Default** Encodes using the default value: ASCII. -- **Byte** Encodes a set of characters into a sequence of bytes. -- **String** Uses the encoding type for a string. -- **Unicode** Encodes in UTF-16 format using the little-endian byte order. +- **Byte** Encodes a set of characters into a sequence of bytes. +- **String** Uses the encoding type for a string. +- **Unicode** Encodes in UTF-16 format using the little-endian byte order. - **UTF7** Encodes in UTF-7 format. -- **UTF8** Encodes in UTF-8 format. -- **Unknown** The encoding type is unknown or invalid; the data can be treated as binary. +- **UTF8** Encodes in UTF-8 format. +- **Unknown** The encoding type is unknown or invalid; the data can be treated as binary. The default value is ASCII. @@ -142,55 +142,54 @@ This parameter works only in file system drives. ```yaml Type: FileSystemCmdletProviderEncoding Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unknown, String, Unicode, Byte, BigEndianUnicode, UTF8, UTF7, UTF32, Ascii, Default, Oem, BigEndianUTF32 Required: False Position: Named -Default value: None +Default value: ASCII Accept pipeline input: False Accept wildcard characters: False ``` ### -Exclude -Specifies items that this cmdlet omits. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcard characters are permitted. +Omits the specified items. +The value of this parameter qualifies the Path parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Filter Specifies a filter in the format or language of the provider. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcard characters, -depends on the provider. -Filters are more efficient than other parameters, -because the provider applies them when it is retrieving the objects, -instead of having Windows PowerShell filter the objects after they are retrieved. +The value of this parameter qualifies the Path parameter. +The syntax of the filter, including the use of wildcard characters, depends on the provider. +Filters are more efficient than other parameters, +because the provider applies them when it is retrieving the objects, +instead of having PowerShell filter the objects after they are retrieved. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Force @@ -198,12 +197,12 @@ Accept wildcard characters: False Forces the cmdlet to set the contents of a file, even if the file is read-only. Implementation varies from provider to provider. For more information, see about_Providers. -Even using the *Force* parameter, the cmdlet cannot override security restrictions. +Even using the Force parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -214,30 +213,30 @@ Accept wildcard characters: False ### -Include -Specifies items that this cmdlet changes. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as *.txt. -Wildcard characters are permitted. +Changes only the specified items. +The value of this parameter qualifies the Path parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -LiteralPath Specifies the path of the item that receives the content. -Unlike *Path*, the value of the *LiteralPath* parameter is used exactly as it is typed. -No characters are interpreted as wildcard characters. +Unlike Path, the value of LiteralPath is used exactly as it is typed. +No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml Type: String[] @@ -253,12 +252,14 @@ Accept wildcard characters: False ### -NoNewline -Indicates that this cmdlet uses the no newline setting. +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -275,7 +276,7 @@ By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -292,13 +293,13 @@ Wildcard characters are permitted. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True -Position: 0 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Stream @@ -307,21 +308,19 @@ Specifies an alternative data stream for content. If the stream does not exist, this cmdlet creates it. Wildcard characters are not supported. -Stream is a dynamic parameter the FileSystem provider adds to **Set-Content**. +Stream is a dynamic parameter that the FileSystem provider adds to **Set-Content**. This parameter works only in file system drives. -You can use the Set-Content cmdlet to change the content of -the Zone.Identifier alternate data stream. -However, we do not recommend this as a way to eliminate security checks -that block files that are downloaded from the Internet. +You can use the **Set-Content** cmdlet to change the content of the Zone.Identifier alternate data stream. +However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -355,10 +354,10 @@ Specifies the new content for the item. ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: True -Position: 1 +Position: 2 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False @@ -383,49 +382,33 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Parameter | --- | - --Debug | --ErrorAction | --ErrorVariable | --InformationAction | --InformationVariable | --OutBuffer | --OutVariable | --PipelineVariable | --Verbose | --WarningAction | --WarningVariable. | - -For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.Object -You can pipe an object that contains the new value for the item to this cmdlet. +You can pipe an object that contains the new value for the item to Set-Content. ## OUTPUTS -### None, System.String +### None or System.String -This cmdlet generates a System.String object that represents the content, -if you specify the *Passthru* parameter. +When you use the Passthru parameter, Set-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output. ## NOTES -You can also refer to **Set-Content** by its built-in alias, **sc**. -For more information, see about_Aliases. +You can also refer to Set-Content by its built-in alias, "sc". For more information, see about_Aliases. -**Set-Content** is designed for string processing. -If you pipe non-string objects to this cmdlet, -it converts the object to a string before writing it. +Set-Content is designed for string processing. +If you pipe non-string objects to Set-Content, it converts the object to a string before writing it. To write objects to files, use Out-File. -**Set-Content** cmdlet is designed to work with the data exposed by any -provider. +The Set-Content cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. @@ -437,4 +420,5 @@ For more information, see about_Providers. [Get-Content](Get-Content.md) +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) diff --git a/reference/6/Microsoft.PowerShell.Utility/Out-File.md b/reference/6/Microsoft.PowerShell.Utility/Out-File.md index 5b7cc06f3a6d..3b03012d81d5 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Out-File.md +++ b/reference/6/Microsoft.PowerShell.Utility/Out-File.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,41 +11,47 @@ title: Out-File # Out-File ## SYNOPSIS + Sends output to a file. ## SYNTAX ### ByPath (Default) -``` + +```powershell Out-File [-FilePath] [[-Encoding] ] [-Append] [-Force] [-NoClobber] [-Width ] [-NoNewline] [-InputObject ] [-InformationAction ] [-InformationVariable ] [-WhatIf] [-Confirm] [] ``` ### ByLiteralPath -``` + +```powershell Out-File -LiteralPath [[-Encoding] ] [-Append] [-Force] [-NoClobber] [-Width ] [-NoNewline] [-InputObject ] [-InformationAction ] [-InformationVariable ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **Out-File** cmdlet sends output to a file. + +The Out-File cmdlet sends output to a file. You can use this cmdlet instead of the redirection operator (\>) when you need to use its parameters. ## EXAMPLES ### Example 1: Send output to a file -``` + +```powershell PS C:\> Get-Process | Out-File -filepath C:\Test1\process.txt ``` This command sends a list of processes on the computer to the Process.txt file. -If the file does not exist, **Out-File** creates it. -Because the name of the *FilePath* parameter is optional, you can omit it and submit the equivalent command `Get-Process | Outfile C:\Test1\process.txt`. +If the file does not exist, Out-File creates it. +Because the name of the FilePath parameter is optional, you can omit it and submit the equivalent command "get-process | outfile C:\Test1\process.txt". ### Example 2: Send output to a file without overwriting -``` + +```powershell PS C:\> Get-Process | Out-File C:\Test1\process.txt -NoClobber Out-File : File C:\Test1\process.txt already exists and NoClobber was specified. @@ -53,54 +59,58 @@ At line:1 char:23 + Get-Process | Out-File <<<< process.txt -NoClobber ``` -This command sends a list of processes to the Process.txt file, but it uses the *NoClobber* parameter, which prevents an existing file from being overwritten. -The output shows the error message that appears when *NoClobber* is used with an existing file. +This command also sends a list of processes to the Process.txt file, but it uses the NoClobber parameter, which prevents an existing file from being overwritten. +The output shows the error message that appears when NoClobber is used with an existing file. ### Example 3: Send output to a file in ASCII format -``` + +```powershell PS C:\> $A = Get-Process PS C:\> Out-File -FilePath C:\Test1\process.txt -InputObject $A -Encoding ASCII -Width 50 ``` These commands send a list of processes on the computer to the Process.txt file. The text is encoded in ASCII format so that it can be read by search programs like Findstr and Grep. -By default, **Out-File** uses Unicode format. +By default, Out-File uses Unicode format. The first command gets the list of processes and stores them in the $A variable. -The second command uses the **Out-File** cmdlet to send the list to the Process.txt file. +The second command uses the Out-File cmdlet to send the list to the Process.txt file. -The command uses the *InputObject* parameter to specify that the input is in the $A variable. -It uses the *Encoding* parameter to convert the output to ASCII format. -It uses the *Width* parameter to limit each line in the file to 50 characters. +The command uses the InputObject parameter to specify that the input is in the $A variable. +It uses the Encoding parameter to convert the output to ASCII format. +It uses the Width parameter to limit each line in the file to 50 characters. Because the lines of output are truncated at 50 characters, the rightmost column in the process table is omitted. ### Example 4: Send output from outside a file system drive -``` + +```powershell PS C:\> Set-Location hklm:\software PS C:\> Get-Acl mycompany\mykey | Out-File -FilePath c:\ps\acl.txt PS C:\> Get-Acl mycompany\mykey | Out-File -FilePath filesystem::acl.txt ``` -These commands show how to use the **Out-File** cmdlet when you are not in a FileSystem drive. +These commands show how to use the Out-File cmdlet when you are not in a FileSystem drive. The first command sets the current location to the HKLM:\Software registry key. The second and third commands have the same effect. They use the Get-Acl cmdlet to get the security descriptor of the MyKey registry subkey (HKLM\Software\MyCompany\MyKey). -A pipeline operator passes the result to the **Out-File** cmdlet, which sends it to the Acl.txt file. +A pipeline operator passes the result to the Out-File cmdlet, which sends it to the Acl.txt file. -Because **Out-File** is not supported by the Windows PowerShell Registry provider, you must specify either the file system drive name, such as c:, or the name of the provider followed by two colons, FileSystem::, in the value of the *FilePath* parameter. +Because Out-File is not supported by the PowerShell Registry provider, you must specify either the file system drive name, +such as "c:", or the name of the provider followed by two colons, "FileSystem::", in the value of the FilePath parameter. The second and third commands demonstrate these methods. ## PARAMETERS ### -Append -Indicates that the cmdlet adds the output to the end of an existing file, instead of replacing the file contents. + +Adds the output to the end of an existing file, instead of replacing the file contents. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -109,7 +119,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -Encoding + Specifies the type of character encoding used in the file. The acceptable values for this parameter are: @@ -126,30 +152,31 @@ The acceptable values for this parameter are: Unicode is the default. -Default uses the encoding of the system's current ANSI code page. +"Default" uses the encoding of the system's current ANSI code page. -OEM uses the current original equipment manufacturer code page identifier for the operating system. +"OEM" uses the current original equipment manufacturer code page identifier for the operating system. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Accepted values: unknown, string, unicode, bigendianunicode, utf8, utf7, utf32, ascii, default, oem Required: False Position: 2 -Default value: None +Default value: Unicode Accept pipeline input: False Accept wildcard characters: False ``` ### -FilePath + Specifies the path to the output file. ```yaml Type: String Parameter Sets: ByPath -Aliases: +Aliases: Required: True Position: 1 @@ -159,13 +186,14 @@ Accept wildcard characters: False ``` ### -Force + Indicates that the cmdlet overwrites an existing read-only file. -Even using the *Force* parameter, the cmdlet cannot override security restrictions. +Even using the Force parameter, the cmdlet cannot override security restrictions. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -202,13 +230,14 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the objects to be written to the file. Enter a variable that contains the objects or type a command or expression that gets the objects. ```yaml Type: PSObject Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -217,33 +246,35 @@ Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` -### -NoClobber -Indicates that the cmdlet will not overwrite an existing file. -By default, if a file exists in the specified path, **Out-File** overwrites the file without warning. -If both *Append* and *NoClobber* are used, the output is appended to the existing file. +### -LiteralPath + +Specifies the path to the output file. +Unlike *FilePath*, the value of the *LiteralPath* parameter is used exactly as it is typed. +No characters are interpreted as wildcards. +If the path includes escape characters, enclose it in single quotation marks. +Single quotation marks tell PowerShell not to interpret any characters as escape sequences. ```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: NoOverwrite +Type: String +Parameter Sets: ByLiteralPath +Aliases: PSPath -Required: False +Required: True Position: Named Default value: None -Accept pipeline input: False +Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -Width -Specifies the number of characters in each line of output. -Any additional characters are truncated, not wrapped. -If you omit this parameter, the width is determined by the characteristics of the host. -The default for the Windows PowerShell console is 80 characters. +### -NoClobber +Indicates that the cmdlet will not overwrite an existing file. +By default, if a file exists in the specified path, **Out-File** overwrites the file without warning. +If both *Append* and *NoClobber* are used, the output is appended to the existing file. ```yaml -Type: Int32 +Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: NoOverwrite Required: False Position: Named @@ -252,41 +283,26 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -LiteralPath -Specifies the path to the output file. -Unlike *FilePath*, the value of the *LiteralPath* parameter is used exactly as it is typed. -No characters are interpreted as wildcards. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. - -```yaml -Type: String -Parameter Sets: ByLiteralPath -Aliases: PSPath - -Required: True -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -Confirm -Prompts you for confirmation before running the cmdlet. +### -NoNewline +Specifies that the content written to the file does not end with a newline character. +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: cf +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -302,11 +318,14 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -NoNewline - +### -Width +Specifies the number of characters in each line of output. +Any additional characters are truncated, not wrapped. +If you omit this parameter, the width is determined by the characteristics of the host. +The default for the Windows PowerShell console is 80 characters. ```yaml -Type: SwitchParameter +Type: Int32 Parameter Sets: (All) Aliases: @@ -318,36 +337,48 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see about_CommonParameters +(http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.Management.Automation.PSObject -You can pipe any object to this cmdlet. + +You can pipe any object to Out-File. ## OUTPUTS ### None -**Out-File** does not generate any output. + +Out-File does not generate any output. ## NOTES -* The Out cmdlets do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. - The Out cmdlets do not have parameters for names or file paths. -To send data to a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. -You can also store data in a variable and use the *InputObject* parameter to pass the data to the cmdlet. -For help, see the examples. +The Out cmdlets do not format objects; they just render them and send them to the specified display destination. +If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. - **Out-File** sends data, but it does not emit any output objects. -If you pipe the output of **Out-File** to Get-Member, **Get-Member** reports that no objects have been specified. +The Out cmdlets do not have parameters for names or file paths. +To send data to a cmdlet that contains the Out verb (an Out cmdlet), use a pipeline operator (|) to send the output of a PowerShell command to the cmdlet. +You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. +For help, see the examples. -* +Out-File sends data, but it does not emit any output objects. +If you pipe the output of Out-File to Get-Member, Get-Member reports that no objects have been specified. ## RELATED LINKS -[Out-GridView](https://msdn.microsoft.com/en-us/powershell/reference/5.1/Microsoft.PowerShell.Utility/Out-GridView) +[Out-Default](../Microsoft.PowerShell.Core/Out-Default.md) + +[Out-GridView](Out-GridView.md) + +[Out-Host](../Microsoft.PowerShell.Core/Out-Host.md) + +[Out-Null](../Microsoft.PowerShell.Core/Out-Null.md) -[Out-Printer](https://msdn.microsoft.com/en-us/powershell/reference/5.1/Microsoft.PowerShell.Utility/Out-Printer) +[Out-Printer](Out-Printer.md) [Out-String](Out-String.md) diff --git a/reference/6/Microsoft.PowerShell.Utility/Write-Host.md b/reference/6/Microsoft.PowerShell.Utility/Write-Host.md index 0b5acf3c9686..a522488a6f68 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Write-Host.md +++ b/reference/6/Microsoft.PowerShell.Utility/Write-Host.md @@ -1,9 +1,8 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-09 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=821876 external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml title: Write-Host --- @@ -11,61 +10,68 @@ title: Write-Host # Write-Host ## SYNOPSIS + Writes customized output to a host. ## SYNTAX -``` +```powershell Write-Host [[-Object] ] [-NoNewline] [-Separator ] [-ForegroundColor ] [-BackgroundColor ] [-InformationAction ] [-InformationVariable ] [] ``` ## DESCRIPTION -The **Write-Host** cmdlet customizes output. -You can specify the color of text by using the *ForegroundColor* parameter, and you can specify the background color by using the *BackgroundColor* parameter. -The *Separator* parameter lets you specify a string to use to separate displayed objects. -The particular result depends on the program that is hosting Windows PowerShell. + +The Write-Host cmdlet customizes output. +You can specify the color of text by using the ForegroundColor parameter, and you can specify the background color by using the BackgroundColor parameter. +The Separator parameter lets you specify a string to use to separate displayed objects. +The particular result depends on the program that is hosting PowerShell. ## EXAMPLES ### Example 1: Write to the console without adding a new line -``` + +```powershell PS C:\> Write-Host "no newline test " -NoNewline no newline test PS C:\> ``` -This command displays the input to the console, but because of the *NoNewline* parameter, the output is followed directly by the prompt. +This command displays the input to the console, but because of the NoNewline parameter, the output is followed directly by the prompt. ### Example 2: Write to the console and include a separator -``` + +```powershell PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", +2= " 2, +2= 4, +2= 6, +2= 8, +2= 10, +2= 12 ``` This command displays the even numbers from 2 through 12. -The *Separator* parameter is used to add the string ", +2= (comma, space, +, 2, =, space)". +The Separator parameter is used to add the string , +2= (comma, space, +, 2, =, space). ### Example 3: Write with different text and background colors -``` -PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", -> " -ForegroundColor DarkGreen -BackgroundColor white + +```powershell +PS C:\> Write-Host (2,4,6,8,10,12) -Separator ", -> " -ForegroundColor DarkGreen -BackgroundColor White ``` This command displays the even numbers from 2 through 12. -It uses the *ForegroundColor* parameter to output dark green text and the *BackgroundColor* parameter to display a white background. +It uses the ForegroundColor parameter to output dark green text and the BackgroundColor parameter to display a white background. ### Example 4: Write with different text and background colors -``` + +```powershell PS C:\> Write-Host "Red on white text." -ForegroundColor red -BackgroundColor white Red on white text. ``` -This command displays the string "Red on white text." The text is red, as defined by the *ForegroundColor* parameter. -The background is white, as defined by the *BackgroundColor* parameter. +This command displays the string "Red on white text." The text is red, as defined by the ForegroundColor parameter. +The background is white, as defined by the BackgroundColor parameter. ## PARAMETERS ### -BackgroundColor + Specifies the background color. There is no default. The acceptable values for this parameter are: @@ -90,7 +96,7 @@ The acceptable values for this parameter are: ```yaml Type: ConsoleColor Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White Required: False @@ -101,6 +107,7 @@ Accept wildcard characters: False ``` ### -ForegroundColor + Specifies the text color. There is no default. The acceptable values for this parameter are: @@ -125,7 +132,7 @@ The acceptable values for this parameter are: ```yaml Type: ConsoleColor Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White Required: False @@ -163,12 +170,15 @@ Accept wildcard characters: False ``` ### -NoNewline -Specifies that the content displayed in the console does not end with a newline character. + +The string representations of the input objects are concatenated to form the output. +No spaces or newlines are inserted between the output strings. +No newline is added after the last output string. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -178,27 +188,28 @@ Accept wildcard characters: False ``` ### -Object -Specifies objects to display in the console. + +Objects to display in the host. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` ### -Separator -Specifies a separator string to the output between objects displayed on the console. +Specifies a separator string to insert between objects displayed by the host. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -208,25 +219,33 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.Object + You can pipe objects to be written to the host. ## OUTPUTS ### None -**Write-Host** sends the objects to the host. + +Write-Host sends the objects to the host. It does not return any objects. -However, the host might display the objects that **Write-Host** sends to it. +However, the host might display the objects that Write-Host sends to it. ## NOTES ## RELATED LINKS -[Clear-Host](../microsoft.powershell.core/clear-host.md) +[Clear-Host](../Microsoft.PowerShell.Core/Functions/Clear-Host.md) + +[Out-Host](../Microsoft.PowerShell.Core/Out-Host.md) [Write-Debug](Write-Debug.md) From 2bdb9e6d4a99628983c73f68e8db7340be532398 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Fri, 10 Nov 2017 03:28:08 +0900 Subject: [PATCH 009/188] Fix the example of `Format-Table -DisplayError` (#1848) The example is a `-DisplayError` parameter example. But it uses `-ShowError` parameter. --- .../3.0/Microsoft.PowerShell.Utility/Format-Table.md | 11 +++++++---- .../4.0/Microsoft.PowerShell.Utility/Format-Table.md | 11 +++++++---- .../5.0/Microsoft.PowerShell.Utility/Format-Table.md | 9 ++++++--- .../5.1/Microsoft.PowerShell.Utility/Format-Table.md | 9 ++++++--- .../6/Microsoft.PowerShell.Utility/Format-Table.md | 9 ++++++--- 5 files changed, 32 insertions(+), 17 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Format-Table.md b/reference/3.0/Microsoft.PowerShell.Utility/Format-Table.md index c9542ce4b85f..7bdc4cfc66ef 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Format-Table.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Format-Table.md @@ -132,14 +132,17 @@ Accept wildcard characters: False ``` ### -DisplayError -Displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Table command, and the expressions do not appear to be working. -The following shows an example of the results of adding the DisplayError parameter with an expression. +Indicates that the cmdlet displays errors at the command line. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Table` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Table DayOfWeek, { $_ / $null } -DisplayError -PS \> Get-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday #ERR +``` ```yaml Type: SwitchParameter diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Format-Table.md b/reference/4.0/Microsoft.PowerShell.Utility/Format-Table.md index 1c0b53dafa5b..e8d22e7cd77a 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Format-Table.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Format-Table.md @@ -141,14 +141,17 @@ Accept wildcard characters: False ``` ### -DisplayError -Displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Table command, and the expressions do not appear to be working. -The following shows an example of the results of adding the DisplayError parameter with an expression. +Indicates that the cmdlet displays errors at the command line. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Table` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Table DayOfWeek, { $_ / $null } -DisplayError -PS \> Get-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday #ERR +``` ```yaml Type: SwitchParameter diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Format-Table.md b/reference/5.0/Microsoft.PowerShell.Utility/Format-Table.md index 539afbcb6d08..1965eb28091c 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Format-Table.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Format-Table.md @@ -142,13 +142,16 @@ Accept wildcard characters: False ### -DisplayError Indicates that the cmdlet displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Table** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the DisplayError parameter with an expression. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Table` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Table DayOfWeek, { $_ / $null } -DisplayError -PS \> Get-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday #ERR +``` ```yaml Type: SwitchParameter diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Format-Table.md b/reference/5.1/Microsoft.PowerShell.Utility/Format-Table.md index 9f9cd1d532db..fad250d7ec9e 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Format-Table.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Format-Table.md @@ -142,13 +142,16 @@ Accept wildcard characters: False ### -DisplayError Indicates that the cmdlet displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Table** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the DisplayError parameter with an expression. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Table` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Table DayOfWeek, { $_ / $null } -DisplayError -PS \> Get-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday #ERR +``` ```yaml Type: SwitchParameter diff --git a/reference/6/Microsoft.PowerShell.Utility/Format-Table.md b/reference/6/Microsoft.PowerShell.Utility/Format-Table.md index c49e5a3c9694..cd46af1d30c1 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Format-Table.md +++ b/reference/6/Microsoft.PowerShell.Utility/Format-Table.md @@ -142,13 +142,16 @@ Accept wildcard characters: False ### -DisplayError Indicates that the cmdlet displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Table** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the DisplayError parameter with an expression. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Table` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Table DayOfWeek, { $_ / $null } -DisplayError -PS \> Get-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday #ERR +``` ```yaml Type: SwitchParameter From 61cb77d74678067ae1fbd95ca78e2831bb8d5db6 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Sat, 11 Nov 2017 01:10:30 +0900 Subject: [PATCH 010/188] Fix the example of `Format-Wide -DisplayError` (#1850) --- .../Microsoft.PowerShell.Utility/Format-Wide.md | 16 +++++++++------- .../Microsoft.PowerShell.Utility/Format-Wide.md | 16 +++++++++------- .../Microsoft.PowerShell.Utility/Format-Wide.md | 16 +++++++++------- .../Microsoft.PowerShell.Utility/Format-Wide.md | 14 ++++++++------ .../Microsoft.PowerShell.Utility/Format-Wide.md | 14 ++++++++------ 5 files changed, 43 insertions(+), 33 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Format-Wide.md b/reference/3.0/Microsoft.PowerShell.Utility/Format-Wide.md index 74fd9557c740..74b467467e59 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Format-Wide.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Format-Wide.md @@ -78,14 +78,16 @@ Accept wildcard characters: False ``` ### -DisplayError -Displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Wide command, and the expressions do not appear to be working. -The following shows an example of the results of adding the DisplayError parameter with an expression. +Indicates that this cmdlet displays errors at the command line. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Wide` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. -PS \> Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday #ERR +```powershell +PS C:\> Get-Date | Format-Wide { $_ / $null } -DisplayError + + +#ERR +``` ```yaml Type: SwitchParameter diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Format-Wide.md b/reference/4.0/Microsoft.PowerShell.Utility/Format-Wide.md index 8783140f7341..54b29b78d57f 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Format-Wide.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Format-Wide.md @@ -83,14 +83,16 @@ Accept wildcard characters: False ``` ### -DisplayError -Displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Wide command, and the expressions do not appear to be working. -The following shows an example of the results of adding the DisplayError parameter with an expression. +Indicates that this cmdlet displays errors at the command line. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Wide` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. -PS \> Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday #ERR +```powershell +PS C:\> Get-Date | Format-Wide { $_ / $null } -DisplayError + + +#ERR +``` ```yaml Type: SwitchParameter diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Format-Wide.md b/reference/5.0/Microsoft.PowerShell.Utility/Format-Wide.md index adc0734866ce..5b4d2a6b5c50 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Format-Wide.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Format-Wide.md @@ -83,14 +83,16 @@ Accept wildcard characters: False ``` ### -DisplayError -Indicates that the cmdlet displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Wide** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the *DisplayError* parameter with an expression. +Indicates that this cmdlet displays errors at the command line. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Wide` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. -PS \> Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday #ERR +```powershell +PS C:\> Get-Date | Format-Wide { $_ / $null } -DisplayError + + +#ERR +``` ```yaml Type: SwitchParameter diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Format-Wide.md b/reference/5.1/Microsoft.PowerShell.Utility/Format-Wide.md index bdb999fc6ee7..0b9181c73b5f 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Format-Wide.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Format-Wide.md @@ -84,13 +84,15 @@ Accept wildcard characters: False ### -DisplayError Indicates that this cmdlet displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Wide** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the *DisplayError* parameter with an expression. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Wide` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. -PS \> Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday #ERR +```powershell +PS C:\> Get-Date | Format-Wide { $_ / $null } -DisplayError + + +#ERR +``` ```yaml Type: SwitchParameter diff --git a/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md b/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md index 2ecf27f13eac..0dcc7b2a5816 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md +++ b/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md @@ -85,13 +85,15 @@ Accept wildcard characters: False ### -DisplayError Indicates that this cmdlet displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Wide** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the *DisplayError* parameter with an expression. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Wide` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. -PS \> Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday #ERR +```powershell +PS C:\> Get-Date | Format-Wide { $_ / $null } -DisplayError + + +#ERR +``` ```yaml Type: SwitchParameter From 882b0e8a582f2854e23c4422c35efad2f37c46e5 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Sat, 11 Nov 2017 01:11:29 +0900 Subject: [PATCH 011/188] Fix the example of `Format-Custom -DisplayError` (#1849) The example is a -DisplayError parameter example. But it uses -ShowError parameter. --- .../Format-Custom.md | 21 ++++++++++++------- .../Format-Custom.md | 21 ++++++++++++------- .../Format-Custom.md | 16 ++++++++------ .../Format-Custom.md | 16 ++++++++------ .../Format-Custom.md | 16 ++++++++------ 5 files changed, 56 insertions(+), 34 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Format-Custom.md b/reference/3.0/Microsoft.PowerShell.Utility/Format-Custom.md index 02dd4734a64e..a53370370c35 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Format-Custom.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Format-Custom.md @@ -56,14 +56,19 @@ Accept wildcard characters: False ``` ### -DisplayError -Displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Custom command, and the expressions do not appear to be working. -The following shows an example of the results of adding the DisplayError parameter with an expression. - -PS \> Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday #ERR +Indicates that this cmdlet displays errors at the command line. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Custom` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Custom DayOfWeek, { $_ / $null } -DisplayError + +class DateTime +{ + DayOfWeek = Wednesday + $_ / $null = #ERR +} +``` ```yaml Type: SwitchParameter diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Format-Custom.md b/reference/4.0/Microsoft.PowerShell.Utility/Format-Custom.md index 479e88483c75..7740ff8de399 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Format-Custom.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Format-Custom.md @@ -61,14 +61,19 @@ Accept wildcard characters: False ``` ### -DisplayError -Displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Custom command, and the expressions do not appear to be working. -The following shows an example of the results of adding the DisplayError parameter with an expression. - -PS \> Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday #ERR +Indicates that this cmdlet displays errors at the command line. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Custom` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Custom DayOfWeek, { $_ / $null } -DisplayError + +class DateTime +{ + DayOfWeek = Wednesday + $_ / $null = #ERR +} +``` ```yaml Type: SwitchParameter diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Format-Custom.md b/reference/5.0/Microsoft.PowerShell.Utility/Format-Custom.md index b98818c4ba00..5efba0338d12 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Format-Custom.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Format-Custom.md @@ -62,14 +62,18 @@ Accept wildcard characters: False ### -DisplayError Indicates that this cmdlet displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Custom** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the *DisplayError* parameter with an expression. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Custom` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. -`PS \> Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -ShowError` +```powershell +PS C:\> Get-Date | Format-Custom DayOfWeek, { $_ / $null } -DisplayError -`DayOfWeek $_ / $null` -`--------- ------------` -`Wednesday #ERR` +class DateTime +{ + DayOfWeek = Wednesday + $_ / $null = #ERR +} +``` ```yaml Type: SwitchParameter diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Format-Custom.md b/reference/5.1/Microsoft.PowerShell.Utility/Format-Custom.md index 4459468606ea..3c6f9f1e5c1c 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Format-Custom.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Format-Custom.md @@ -62,14 +62,18 @@ Accept wildcard characters: False ### -DisplayError Indicates that this cmdlet displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Custom** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the *DisplayError* parameter with an expression. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Custom` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. -`PS \> Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -ShowError` +```powershell +PS C:\> Get-Date | Format-Custom DayOfWeek, { $_ / $null } -DisplayError -`DayOfWeek $_ / $null` -`--------- ------------` -`Wednesday #ERR` +class DateTime +{ + DayOfWeek = Wednesday + $_ / $null = #ERR +} +``` ```yaml Type: SwitchParameter diff --git a/reference/6/Microsoft.PowerShell.Utility/Format-Custom.md b/reference/6/Microsoft.PowerShell.Utility/Format-Custom.md index 332b3f7cda9b..7ed2ab5b3d93 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Format-Custom.md +++ b/reference/6/Microsoft.PowerShell.Utility/Format-Custom.md @@ -63,14 +63,18 @@ Accept wildcard characters: False ### -DisplayError Indicates that this cmdlet displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Custom** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the *DisplayError* parameter with an expression. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Custom` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. -`PS \> Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -ShowError` +```powershell +PS C:\> Get-Date | Format-Custom DayOfWeek, { $_ / $null } -DisplayError -`DayOfWeek $_ / $null` -`--------- ------------` -`Wednesday #ERR` +class DateTime +{ + DayOfWeek = Wednesday + $_ / $null = #ERR +} +``` ```yaml Type: SwitchParameter From 67db02a8cbf09d33f4ba8c8ef59cc154b1ca62b5 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 7 Nov 2017 15:47:05 -0800 Subject: [PATCH 012/188] updating set-acl docs per PR#901 --- .../Microsoft.PowerShell.Security/Set-Acl.md | 221 +++++++----- .../Microsoft.PowerShell.Security/Set-Acl.md | 213 ++++++----- .../Microsoft.PowerShell.Security/Set-Acl.md | 339 +++++++++-------- .../Microsoft.PowerShell.Security/Set-Acl.md | 339 +++++++++-------- .../Microsoft.PowerShell.Security/Set-Acl.md | 340 ++++++++++-------- 5 files changed, 838 insertions(+), 614 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md b/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md index a4e0470c14df..26afdbe3b464 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-07 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -9,11 +9,16 @@ title: Set-Acl --- # Set-Acl + ## SYNOPSIS -Changes the security descriptor of a specified item, such as a file or a registry key. + +Changes the security descriptor of a specified item. The ability to manage a security descriptor +can be extended to additional providers that support Powershell Objects. + ## SYNTAX ### ByPath (Default) + ``` Set-Acl [-Path] [-AclObject] [[-CentralAccessPolicy] ] [-ClearCentralAccessPolicy] [-Passthru] [-Filter ] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] @@ -21,12 +26,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,76 +41,97 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl C:\Dog.txt PS C:\> 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. -When the commands complete, the security descriptors of the Dog.txt and Cat.txt files are identical. +These commands copy the values from the security descriptor of the Dog.txt file to the security +descriptor of the Cat.txt file. When the commands complete, the security descriptors of the Dog.txt +and Cat.txt files are identical. + +The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. The +assignment operator (=) stores the security descriptor in the value of the $DogACL variable. -The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. -The assignment operator (=) stores the security descriptor in the value of the $DogACL variable. +The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in +$DogACL. -The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in $DogACL. +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. -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 + ``` PS C:\> Get-Acl 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. +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. The first command uses the **Get-Acl** cmdlet to get the security descriptor of the Dog.txt file. -The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the **Set-Acl** cmdlet. +The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the +**Set-Acl** cmdlet. The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. When the command completes, the ACLs of the Dog.txt and Cat.txt files are identical. + ### Example 3 + ``` PS C:\> $NewAcl = Get-Acl File0.txt PS C:\> Get-ChildItem 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. +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. -The first command gets the security descriptor of the File0.txt file in the current directory and uses the assignment operator (=) to store it in the $NewACL variable. +The first command gets the security descriptor of the File0.txt file in the current directory and +uses the assignment operator (=) to store it in the $NewACL variable. -The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the C:\Temp directory. -The **Recurse** parameter extends the command to all subdirectories of C:\temp. +The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the +C:\Temp directory. The **Recurse** parameter extends the command to all subdirectories of C:\temp. The **Include** parameter limits the files retrieved to those with the ".txt" file name extension. -The **Force** parameter gets hidden files, which would otherwise be excluded. -(You cannot use "c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) +The **Force** parameter gets hidden files, which would otherwise be excluded. (You cannot use +"c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) -The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in the pipeline. +The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** +cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in +the pipeline. -In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can affect more than one item. -In this case, the second command in the pipeline would be "`Set-Acl -AclObject $NewAcl -WhatIf`". -This command lists the files that would be affected by the command. +In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can +affect more than one item. In this case, the second command in the pipeline would be "`Set-Acl +-AclObject $NewAcl -WhatIf`". This command lists the files that would be affected by the command. After reviewing the result, you can run the command again without the **Whatif** parameter. + ## 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. -You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter to pass the variable, or type a Get-Acl command. +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. + +You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter +to pass the variable, or type a Get-Acl command. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 2 @@ -113,15 +141,15 @@ 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". -Wildcards are permitted. + +Omits the specified items. The value of this parameter qualifies the **Path** parameter. Enter a +path element or pattern, such as "*.txt". Wildcards are permitted. Note: Not all providers may +support this parameter. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -131,15 +159,17 @@ Accept wildcard characters: True ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the **Path** parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. + +Specifies a filter in the provider's format or language. The value of this parameter qualifies the +**Path** parameter. The syntax of the filter, including the use of wildcards, depends on the +provider. Filters are more efficient than other parameters, because the provider applies them when +retrieving the objects, rather than having Windows PowerShell filter the objects after they are +retrieved. Note: Not all providers may support this parameter. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -149,15 +179,15 @@ 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". -Wildcards are permitted. + +Changes only the specified items. The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcards are permitted. Note: Not all providers +may support this parameter. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -167,13 +197,14 @@ 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. + +Returns an object that represents the security descriptor that was changed. By default, this cmdlet +does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -183,16 +214,19 @@ 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. -If you pass a security object to **Set-Acl** (either by using the **AclObject** or **SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and you omit the **Path** parameter (name and value), **Set-Acl** uses the path that is included in the security object. +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. + +If you pass a security object to **Set-Acl** (either by using the **AclObject** or +**SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and +you omit the **Path** parameter (name and value), **Set-Acl** uses the path that is included in the +security object. ```yaml Type: String[] Parameter Sets: ByPath -Aliases: +Aliases: Required: True Position: 1 @@ -202,18 +236,20 @@ 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). +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). This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: String Parameter Sets: ByPath, ByLiteralPath -Aliases: +Aliases: Required: False Position: 3 @@ -223,17 +259,19 @@ 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). +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). This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: SwitchParameter Parameter Sets: ByPath, ByLiteralPath -Aliases: +Aliases: Required: False Position: Named @@ -243,18 +281,19 @@ 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. -You cannot pipe the object to be changed to **Set-Acl**. -Instead, use the **InputObject** parameter explicitly in the command. +Changes the security descriptor of the specified object. Enter a variable that contains the object +or a command that gets the object. + +You cannot pipe the object to be changed to **Set-Acl**. Instead, use the **InputObject** parameter +explicitly in the command. This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: PSObject Parameter Sets: ByInputObject -Aliases: +Aliases: Required: True Position: 1 @@ -264,11 +303,11 @@ 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. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. + +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. If the path includes escape characters, enclose it in single quotation marks. Single +quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. This parameter is introduced in Windows PowerShell 3.0. @@ -285,6 +324,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -300,8 +340,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -316,9 +356,9 @@ 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. + +Includes the command in the active transaction. This parameter is valid only when a transaction is +in progress. For more information, see about_Transactions. ```yaml Type: SwitchParameter @@ -333,23 +373,36 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see about_CommonParameters +(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. + +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. + ## NOTES -* The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. As such, you can use it to change the security descriptors of files, directories, and registry keys. -* -## RELATED LINKS +- The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. + As such, you can use it to change the security descriptors of files, directories, and registry + keys. -[Get-Acl](Get-Acl.md) +- There may be additional providers that also support this interface, or extend it. For example, + the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the + security descriptor extensions used by Active Directory. +## RELATED LINKS +[Get-Acl](Get-Acl.md) diff --git a/reference/4.0/Microsoft.PowerShell.Security/Set-Acl.md b/reference/4.0/Microsoft.PowerShell.Security/Set-Acl.md index e65fda487d2f..26afdbe3b464 100644 --- a/reference/4.0/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/4.0/Microsoft.PowerShell.Security/Set-Acl.md @@ -1,9 +1,9 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-07 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/p/?linkid=293939 +online version: http://go.microsoft.com/fwlink/?LinkID=113389 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Set-Acl --- @@ -11,11 +11,14 @@ title: Set-Acl # Set-Acl ## SYNOPSIS -Changes the security descriptor of a specified item, such as a file or a registry key. + +Changes the security descriptor of a specified item. The ability to manage a security descriptor +can be extended to additional providers that support Powershell Objects. ## SYNTAX ### ByPath (Default) + ``` Set-Acl [-Path] [-AclObject] [[-CentralAccessPolicy] ] [-ClearCentralAccessPolicy] [-Passthru] [-Filter ] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] @@ -23,12 +26,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 ] @@ -36,80 +41,97 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl C:\Dog.txt PS C:\> 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. -When the commands complete, the security descriptors of the Dog.txt and Cat.txt files are identical. +These commands copy the values from the security descriptor of the Dog.txt file to the security +descriptor of the Cat.txt file. When the commands complete, the security descriptors of the Dog.txt +and Cat.txt files are identical. -The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. -The assignment operator (=) stores the security descriptor in the value of the $DogACL variable. +The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. The +assignment operator (=) stores the security descriptor in the value of the $DogACL variable. -The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in $DogACL. +The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in +$DogACL. -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. +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 + ``` PS C:\> Get-Acl 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. +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. The first command uses the **Get-Acl** cmdlet to get the security descriptor of the Dog.txt file. -The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the **Set-Acl** cmdlet. +The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the +**Set-Acl** cmdlet. The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. When the command completes, the ACLs of the Dog.txt and Cat.txt files are identical. ### Example 3 + ``` PS C:\> $NewAcl = Get-Acl File0.txt PS C:\> Get-ChildItem 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. +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. -The first command gets the security descriptor of the File0.txt file in the current directory and uses the assignment operator (=) to store it in the $NewACL variable. +The first command gets the security descriptor of the File0.txt file in the current directory and +uses the assignment operator (=) to store it in the $NewACL variable. -The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the C:\Temp directory. -The **Recurse** parameter extends the command to all subdirectories of C:\temp. +The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the +C:\Temp directory. The **Recurse** parameter extends the command to all subdirectories of C:\temp. The **Include** parameter limits the files retrieved to those with the ".txt" file name extension. -The **Force** parameter gets hidden files, which would otherwise be excluded. -(You cannot use "c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) +The **Force** parameter gets hidden files, which would otherwise be excluded. (You cannot use +"c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) -The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in the pipeline. +The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** +cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in +the pipeline. -In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can affect more than one item. -In this case, the second command in the pipeline would be "`Set-Acl -AclObject $NewAcl -WhatIf`". -This command lists the files that would be affected by the command. +In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can +affect more than one item. In this case, the second command in the pipeline would be "`Set-Acl +-AclObject $NewAcl -WhatIf`". This command lists the files that would be affected by the command. After reviewing the result, you can run the command again without the **Whatif** parameter. ## 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. -You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter to pass the variable, or type a Get-Acl command. +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. + +You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter +to pass the variable, or type a Get-Acl command. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 2 @@ -119,15 +141,15 @@ 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". -Wildcards are permitted. + +Omits the specified items. The value of this parameter qualifies the **Path** parameter. Enter a +path element or pattern, such as "*.txt". Wildcards are permitted. Note: Not all providers may +support this parameter. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -137,15 +159,17 @@ Accept wildcard characters: True ``` ### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the **Path** parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. + +Specifies a filter in the provider's format or language. The value of this parameter qualifies the +**Path** parameter. The syntax of the filter, including the use of wildcards, depends on the +provider. Filters are more efficient than other parameters, because the provider applies them when +retrieving the objects, rather than having Windows PowerShell filter the objects after they are +retrieved. Note: Not all providers may support this parameter. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -155,15 +179,15 @@ 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". -Wildcards are permitted. + +Changes only the specified items. The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcards are permitted. Note: Not all providers +may support this parameter. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -173,13 +197,14 @@ 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. + +Returns an object that represents the security descriptor that was changed. By default, this cmdlet +does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -189,16 +214,19 @@ 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. -If you pass a security object to **Set-Acl** (either by using the **AclObject** or **SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and you omit the **Path** parameter (name and value), **Set-Acl** uses the path that is included in the security object. +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. + +If you pass a security object to **Set-Acl** (either by using the **AclObject** or +**SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and +you omit the **Path** parameter (name and value), **Set-Acl** uses the path that is included in the +security object. ```yaml Type: String[] Parameter Sets: ByPath -Aliases: +Aliases: Required: True Position: 1 @@ -208,18 +236,20 @@ 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). +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). This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: String Parameter Sets: ByPath, ByLiteralPath -Aliases: +Aliases: Required: False Position: 3 @@ -229,17 +259,19 @@ 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). +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). This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: SwitchParameter Parameter Sets: ByPath, ByLiteralPath -Aliases: +Aliases: Required: False Position: Named @@ -249,18 +281,19 @@ 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. -You cannot pipe the object to be changed to **Set-Acl**. -Instead, use the **InputObject** parameter explicitly in the command. +Changes the security descriptor of the specified object. Enter a variable that contains the object +or a command that gets the object. + +You cannot pipe the object to be changed to **Set-Acl**. Instead, use the **InputObject** parameter +explicitly in the command. This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: PSObject Parameter Sets: ByInputObject -Aliases: +Aliases: Required: True Position: 1 @@ -270,11 +303,11 @@ 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. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. + +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. If the path includes escape characters, enclose it in single quotation marks. Single +quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. This parameter is introduced in Windows PowerShell 3.0. @@ -291,6 +324,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -306,8 +340,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -322,9 +356,9 @@ 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. + +Includes the command in the active transaction. This parameter is valid only when a transaction is +in progress. For more information, see about_Transactions. ```yaml Type: SwitchParameter @@ -339,27 +373,36 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see about_CommonParameters +(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. + +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. ## NOTES -* The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. As such, you can use it to change the security descriptors of files, directories, and registry keys. -* +- The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. + As such, you can use it to change the security descriptors of files, directories, and registry + keys. + +- There may be additional providers that also support this interface, or extend it. For example, + the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the + security descriptor extensions used by Active Directory. ## RELATED LINKS [Get-Acl](Get-Acl.md) - - diff --git a/reference/5.0/Microsoft.PowerShell.Security/Set-Acl.md b/reference/5.0/Microsoft.PowerShell.Security/Set-Acl.md index 2d434ebbcde3..26afdbe3b464 100644 --- a/reference/5.0/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/5.0/Microsoft.PowerShell.Security/Set-Acl.md @@ -1,9 +1,9 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-07 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=821717 +online version: http://go.microsoft.com/fwlink/?LinkID=113389 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Set-Acl --- @@ -11,11 +11,14 @@ title: Set-Acl # Set-Acl ## SYNOPSIS -Changes the security descriptor of a specified item, such as a file or a registry key. + +Changes the security descriptor of a specified item. The ability to manage a security descriptor +can be extended to additional providers that support Powershell Objects. ## SYNTAX ### ByPath (Default) + ``` Set-Acl [-Path] [-AclObject] [[-CentralAccessPolicy] ] [-ClearCentralAccessPolicy] [-Passthru] [-Filter ] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] @@ -23,12 +26,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 ] @@ -36,136 +41,170 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl -Path "C:\Dog.txt" -PS C:\> Set-Acl -Path "C:\Cat.txt" -AclObject $DogACL +PS C:\> $DogACL = Get-Acl C:\Dog.txt +PS C:\> 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. -When the commands complete, the security descriptors of the Dog.txt and Cat.txt files are identical. +These commands copy the values from the security descriptor of the Dog.txt file to the security +descriptor of the Cat.txt file. When the commands complete, the security descriptors of the Dog.txt +and Cat.txt files are identical. -The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. -The assignment operator (=) stores the security descriptor in the value of the $DogACL variable. +The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. The +assignment operator (=) stores the security descriptor in the value of the $DogACL variable. -The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in $DogACL. +The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in +$DogACL. -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. +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 -### Example 2: Use the pipeline operator to pass a descriptor ``` -PS C:\> Get-Acl -Path "C:\Dog.txt" | Set-Acl -Path "C:\Cat.txt" +PS C:\> Get-Acl 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. +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. The first command uses the **Get-Acl** cmdlet to get the security descriptor of the Dog.txt file. -The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the **Set-Acl** cmdlet. +The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the +**Set-Acl** cmdlet. -The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. +The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. 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 +### Example 3 + ``` PS C:\> $NewAcl = Get-Acl File0.txt -PS C:\> Get-ChildItem -Path "C:\temp" -Recurse -Include "*.txt" -Force | Set-Acl -AclObject $NewAcl +PS C:\> Get-ChildItem 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. +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. -The first command gets the security descriptor of the File0.txt file in the current directory and uses the assignment operator (=) to store it in the $NewACL variable. +The first command gets the security descriptor of the File0.txt file in the current directory and +uses the assignment operator (=) to store it in the $NewACL variable. -The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the C:\Temp directory. -The *Recurse* parameter extends the command to all subdirectories of C:\temp. -The *Include* parameter limits the files retrieved to those with the ".txt" file name extension. -The *Force* parameter gets hidden files, which would otherwise be excluded. -(You cannot use "c:\temp\*.txt", because the *Recurse* parameter works on directories, not on files.) +The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the +C:\Temp directory. The **Recurse** parameter extends the command to all subdirectories of C:\temp. +The **Include** parameter limits the files retrieved to those with the ".txt" file name extension. +The **Force** parameter gets hidden files, which would otherwise be excluded. (You cannot use +"c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) -The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** cmdlet, which applies the security descriptor in the *AclObject* parameter to all of the files in the pipeline. +The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** +cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in +the pipeline. -In practice, it is best to use the *WhatIf* parameter with all **Set-Acl** commands that can affect more than one item. -In this case, the second command in the pipeline would be `Set-Acl -AclObject $NewAcl -WhatIf`. -This command lists the files that would be affected by the command. -After reviewing the result, you can run the command again without the *WhatIf* parameter. +In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can +affect more than one item. In this case, the second command in the pipeline would be "`Set-Acl +-AclObject $NewAcl -WhatIf`". This command lists the files that would be affected by the command. +After reviewing the result, you can run the command again without the **Whatif** parameter. ## 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. -You can save the output of a Get-Acl command in a variable and then use the *AclObject* parameter to pass the variable, or type a Get-Acl command. +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. + +You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter +to pass the variable, or type a Get-Acl command. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: True -Position: 1 +Position: 2 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` -### -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. +### -Exclude + +Omits the specified items. The value of this parameter qualifies the **Path** parameter. Enter a +path element or pattern, such as "*.txt". Wildcards are permitted. Note: Not all providers may +support this parameter. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: -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). +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: True +``` -This parameter was introduced in Windows PowerShell 3.0. +### -Filter + +Specifies a filter in the provider's format or language. The value of this parameter qualifies the +**Path** parameter. The syntax of the filter, including the use of wildcards, depends on the +provider. Filters are more efficient than other parameters, because the provider applies them when +retrieving the objects, rather than having Windows PowerShell filter the objects after they are +retrieved. Note: Not all providers may support this parameter. ```yaml Type: String -Parameter Sets: ByPath, ByLiteralPath -Aliases: +Parameter Sets: (All) +Aliases: Required: False -Position: 2 +Position: Named Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False +Accept pipeline input: False +Accept wildcard characters: True ``` -### -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). +### -Include -This parameter was introduced in Windows PowerShell 3.0. +Changes only the specified items. The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcards are permitted. Note: Not all providers +may support this parameter. ```yaml -Type: SwitchParameter -Parameter Sets: ByPath, ByLiteralPath -Aliases: +Type: String[] +Parameter Sets: (All) +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` -### -Confirm -Prompts you for confirmation before running the cmdlet. +### -Passthru + +Returns an object that represents the security descriptor that was changed. By default, this cmdlet +does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: cf +Aliases: Required: False Position: Named @@ -174,89 +213,103 @@ Accept pipeline input: False 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". -Wildcards are permitted. +### -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. + +If you pass a security object to **Set-Acl** (either by using the **AclObject** or +**SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and +you omit the **Path** parameter (name and value), **Set-Acl** uses the path that is included in the +security object. ```yaml Type: String[] -Parameter Sets: (All) -Aliases: +Parameter Sets: ByPath +Aliases: -Required: False -Position: Named +Required: True +Position: 1 Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: True ``` -### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +### -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). + +This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: String -Parameter Sets: (All) -Aliases: +Parameter Sets: ByPath, ByLiteralPath +Aliases: Required: False -Position: Named +Position: 3 Default value: None -Accept pipeline input: False +Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -Include -Changes only the specified items. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as "*.txt". -Wildcards are permitted. +### -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). + +This parameter is introduced in Windows PowerShell 3.0. ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: +Type: SwitchParameter +Parameter Sets: ByPath, ByLiteralPath +Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False 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. -You cannot pipe the object to be changed to **Set-Acl**. -Instead, use the *InputObject* parameter explicitly in the command. +Changes the security descriptor of the specified object. Enter a variable that contains the object +or a command that gets the object. + +You cannot pipe the object to be changed to **Set-Acl**. Instead, use the **InputObject** parameter +explicitly in the command. -This parameter was introduced in Windows PowerShell 3.0. +This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: PSObject Parameter Sets: ByInputObject -Aliases: +Aliases: Required: True -Position: 0 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) 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. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. -This parameter was introduced in Windows PowerShell 3.0. +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. If the path includes escape characters, enclose it in single quotation marks. Single +quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. + +This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: String[] @@ -270,14 +323,14 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -Passthru -Returns an object that represents the security descriptor that was changed. -By default, this cmdlet does not generate any output. +### -Confirm + +Prompts you for confirmation before running the cmdlet. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: cf Required: False Position: Named @@ -286,34 +339,14 @@ Accept pipeline input: False 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. +### -WhatIf -If you pass a security object to **Set-Acl** (either by using the *AclObject* or *SecurityDescriptor* parameter, or by passing a security object from Get-Acl to **Set-Acl**), and you omit the *Path* parameter (name and value), **Set-Acl** uses the path that is included in the security object. - -```yaml -Type: String[] -Parameter Sets: ByPath -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName) -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. +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: usetx +Aliases: wi Required: False Position: Named @@ -322,14 +355,15 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +### -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. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: wi +Aliases: usetx Required: False Position: Named @@ -339,27 +373,36 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see about_CommonParameters +(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. + +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. ## NOTES -* The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. As such, you can use it to change the security descriptors of files, directories, and registry keys. -* +- The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. + As such, you can use it to change the security descriptors of files, directories, and registry + keys. + +- There may be additional providers that also support this interface, or extend it. For example, + the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the + security descriptor extensions used by Active Directory. ## RELATED LINKS [Get-Acl](Get-Acl.md) - - diff --git a/reference/5.1/Microsoft.PowerShell.Security/Set-Acl.md b/reference/5.1/Microsoft.PowerShell.Security/Set-Acl.md index e617de4ce14e..26afdbe3b464 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/5.1/Microsoft.PowerShell.Security/Set-Acl.md @@ -1,9 +1,9 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-07 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=821717 +online version: http://go.microsoft.com/fwlink/?LinkID=113389 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Set-Acl --- @@ -11,11 +11,14 @@ title: Set-Acl # Set-Acl ## SYNOPSIS -Changes the security descriptor of a specified item, such as a file or a registry key. + +Changes the security descriptor of a specified item. The ability to manage a security descriptor +can be extended to additional providers that support Powershell Objects. ## SYNTAX ### ByPath (Default) + ``` Set-Acl [-Path] [-AclObject] [[-CentralAccessPolicy] ] [-ClearCentralAccessPolicy] [-Passthru] [-Filter ] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] @@ -23,12 +26,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 ] @@ -36,136 +41,170 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl -Path "C:\Dog.txt" -PS C:\> Set-Acl -Path "C:\Cat.txt" -AclObject $DogACL +PS C:\> $DogACL = Get-Acl C:\Dog.txt +PS C:\> 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. -When the commands complete, the security descriptors of the Dog.txt and Cat.txt files are identical. +These commands copy the values from the security descriptor of the Dog.txt file to the security +descriptor of the Cat.txt file. When the commands complete, the security descriptors of the Dog.txt +and Cat.txt files are identical. -The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. -The assignment operator (=) stores the security descriptor in the value of the $DogACL variable. +The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. The +assignment operator (=) stores the security descriptor in the value of the $DogACL variable. -The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in $DogACL. +The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in +$DogACL. -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. +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 -### Example 2: Use the pipeline operator to pass a descriptor ``` -PS C:\> Get-Acl -Path "C:\Dog.txt" | Set-Acl -Path "C:\Cat.txt" +PS C:\> Get-Acl 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. +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. The first command uses the **Get-Acl** cmdlet to get the security descriptor of the Dog.txt file. -The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the **Set-Acl** cmdlet. +The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the +**Set-Acl** cmdlet. -The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. +The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. 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 +### Example 3 + ``` PS C:\> $NewAcl = Get-Acl File0.txt -PS C:\> Get-ChildItem -Path "C:\temp" -Recurse -Include "*.txt" -Force | Set-Acl -AclObject $NewAcl +PS C:\> Get-ChildItem 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. +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. -The first command gets the security descriptor of the File0.txt file in the current directory and uses the assignment operator (=) to store it in the $NewACL variable. +The first command gets the security descriptor of the File0.txt file in the current directory and +uses the assignment operator (=) to store it in the $NewACL variable. -The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the C:\Temp directory. -The *Recurse* parameter extends the command to all subdirectories of C:\temp. -The *Include* parameter limits the files retrieved to those with the ".txt" file name extension. -The *Force* parameter gets hidden files, which would otherwise be excluded. -(You cannot use "c:\temp\*.txt", because the *Recurse* parameter works on directories, not on files.) +The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the +C:\Temp directory. The **Recurse** parameter extends the command to all subdirectories of C:\temp. +The **Include** parameter limits the files retrieved to those with the ".txt" file name extension. +The **Force** parameter gets hidden files, which would otherwise be excluded. (You cannot use +"c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) -The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** cmdlet, which applies the security descriptor in the *AclObject* parameter to all of the files in the pipeline. +The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** +cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in +the pipeline. -In practice, it is best to use the *WhatIf* parameter with all **Set-Acl** commands that can affect more than one item. -In this case, the second command in the pipeline would be `Set-Acl -AclObject $NewAcl -WhatIf`. -This command lists the files that would be affected by the command. -After reviewing the result, you can run the command again without the *WhatIf* parameter. +In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can +affect more than one item. In this case, the second command in the pipeline would be "`Set-Acl +-AclObject $NewAcl -WhatIf`". This command lists the files that would be affected by the command. +After reviewing the result, you can run the command again without the **Whatif** parameter. ## 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. -You can save the output of a Get-Acl command in a variable and then use the *AclObject* parameter to pass the variable, or type a Get-Acl command. +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. + +You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter +to pass the variable, or type a Get-Acl command. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: True -Position: 1 +Position: 2 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` -### -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. +### -Exclude + +Omits the specified items. The value of this parameter qualifies the **Path** parameter. Enter a +path element or pattern, such as "*.txt". Wildcards are permitted. Note: Not all providers may +support this parameter. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: -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). +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: True +``` -This parameter was introduced in Windows PowerShell 3.0. +### -Filter + +Specifies a filter in the provider's format or language. The value of this parameter qualifies the +**Path** parameter. The syntax of the filter, including the use of wildcards, depends on the +provider. Filters are more efficient than other parameters, because the provider applies them when +retrieving the objects, rather than having Windows PowerShell filter the objects after they are +retrieved. Note: Not all providers may support this parameter. ```yaml Type: String -Parameter Sets: ByPath, ByLiteralPath -Aliases: +Parameter Sets: (All) +Aliases: Required: False -Position: 2 +Position: Named Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False +Accept pipeline input: False +Accept wildcard characters: True ``` -### -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). +### -Include -This parameter was introduced in Windows PowerShell 3.0. +Changes only the specified items. The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcards are permitted. Note: Not all providers +may support this parameter. ```yaml -Type: SwitchParameter -Parameter Sets: ByPath, ByLiteralPath -Aliases: +Type: String[] +Parameter Sets: (All) +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` -### -Confirm -Prompts you for confirmation before running the cmdlet. +### -Passthru + +Returns an object that represents the security descriptor that was changed. By default, this cmdlet +does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: cf +Aliases: Required: False Position: Named @@ -174,89 +213,103 @@ Accept pipeline input: False 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". -Wildcards are permitted. +### -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. + +If you pass a security object to **Set-Acl** (either by using the **AclObject** or +**SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and +you omit the **Path** parameter (name and value), **Set-Acl** uses the path that is included in the +security object. ```yaml Type: String[] -Parameter Sets: (All) -Aliases: +Parameter Sets: ByPath +Aliases: -Required: False -Position: Named +Required: True +Position: 1 Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: True ``` -### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +### -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). + +This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: String -Parameter Sets: (All) -Aliases: +Parameter Sets: ByPath, ByLiteralPath +Aliases: Required: False -Position: Named +Position: 3 Default value: None -Accept pipeline input: False +Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -Include -Changes only the specified items. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as "*.txt". -Wildcards are permitted. +### -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). + +This parameter is introduced in Windows PowerShell 3.0. ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: +Type: SwitchParameter +Parameter Sets: ByPath, ByLiteralPath +Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False 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. -You cannot pipe the object to be changed to **Set-Acl**. -Instead, use the *InputObject* parameter explicitly in the command. +Changes the security descriptor of the specified object. Enter a variable that contains the object +or a command that gets the object. + +You cannot pipe the object to be changed to **Set-Acl**. Instead, use the **InputObject** parameter +explicitly in the command. -This parameter was introduced in Windows PowerShell 3.0. +This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: PSObject Parameter Sets: ByInputObject -Aliases: +Aliases: Required: True -Position: 0 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) 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. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. -This parameter was introduced in Windows PowerShell 3.0. +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. If the path includes escape characters, enclose it in single quotation marks. Single +quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. + +This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: String[] @@ -270,50 +323,30 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -Passthru -Returns an object that represents the security descriptor that was changed. -By default, this cmdlet does not generate any output. +### -Confirm + +Prompts you for confirmation before running the cmdlet. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: cf Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False 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. +### -WhatIf -If you pass a security object to **Set-Acl** (either by using the *AclObject* or *SecurityDescriptor* parameter, or by passing a security object from Get-Acl to **Set-Acl**), and you omit the *Path* parameter (name and value), **Set-Acl** uses the path that is included in the security object. - -```yaml -Type: String[] -Parameter Sets: ByPath -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName) -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. +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: usetx +Aliases: wi Required: False Position: Named @@ -322,14 +355,15 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +### -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. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: wi +Aliases: usetx Required: False Position: Named @@ -339,27 +373,36 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see about_CommonParameters +(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. + +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. ## NOTES -* The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. As such, you can use it to change the security descriptors of files, directories, and registry keys. -* +- The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. + As such, you can use it to change the security descriptors of files, directories, and registry + keys. + +- There may be additional providers that also support this interface, or extend it. For example, + the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the + security descriptor extensions used by Active Directory. ## RELATED LINKS [Get-Acl](Get-Acl.md) - - diff --git a/reference/6/Microsoft.PowerShell.Security/Set-Acl.md b/reference/6/Microsoft.PowerShell.Security/Set-Acl.md index a795f5ee3088..751c008f40b6 100644 --- a/reference/6/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/6/Microsoft.PowerShell.Security/Set-Acl.md @@ -1,9 +1,9 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-07 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=821717 +online version: http://go.microsoft.com/fwlink/?LinkID=113389 external help file: Microsoft.PowerShell.Security.dll-Help.xml title: Set-Acl --- @@ -11,11 +11,14 @@ title: Set-Acl # Set-Acl ## SYNOPSIS -Changes the security descriptor of a specified item, such as a file or a registry key. + +Changes the security descriptor of a specified item. The ability to manage a security descriptor +can be extended to additional providers that support Powershell Objects. ## SYNTAX ### ByPath (Default) + ``` Set-Acl [-Path] [-AclObject] [[-CentralAccessPolicy] ] [-ClearCentralAccessPolicy] [-Passthru] [-Filter ] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] @@ -23,12 +26,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 ] @@ -36,136 +41,170 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl -Path "C:\Dog.txt" -PS C:\> Set-Acl -Path "C:\Cat.txt" -AclObject $DogACL +PS C:\> $DogACL = Get-Acl C:\Dog.txt +PS C:\> 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. -When the commands complete, the security descriptors of the Dog.txt and Cat.txt files are identical. +These commands copy the values from the security descriptor of the Dog.txt file to the security +descriptor of the Cat.txt file. When the commands complete, the security descriptors of the Dog.txt +and Cat.txt files are identical. -The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. -The assignment operator (=) stores the security descriptor in the value of the $DogACL variable. +The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. The +assignment operator (=) stores the security descriptor in the value of the $DogACL variable. -The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in $DogACL. +The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in +$DogACL. -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. +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 -### Example 2: Use the pipeline operator to pass a descriptor ``` -PS C:\> Get-Acl -Path "C:\Dog.txt" | Set-Acl -Path "C:\Cat.txt" +PS C:\> Get-Acl 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. +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. The first command uses the **Get-Acl** cmdlet to get the security descriptor of the Dog.txt file. -The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the **Set-Acl** cmdlet. +The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the +**Set-Acl** cmdlet. -The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. +The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. 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 +### Example 3 + ``` PS C:\> $NewAcl = Get-Acl File0.txt -PS C:\> Get-ChildItem -Path "C:\temp" -Recurse -Include "*.txt" -Force | Set-Acl -AclObject $NewAcl +PS C:\> Get-ChildItem 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. +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. -The first command gets the security descriptor of the File0.txt file in the current directory and uses the assignment operator (=) to store it in the $NewACL variable. +The first command gets the security descriptor of the File0.txt file in the current directory and +uses the assignment operator (=) to store it in the $NewACL variable. -The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the C:\Temp directory. -The *Recurse* parameter extends the command to all subdirectories of C:\temp. -The *Include* parameter limits the files retrieved to those with the ".txt" file name extension. -The *Force* parameter gets hidden files, which would otherwise be excluded. -(You cannot use "c:\temp\*.txt", because the *Recurse* parameter works on directories, not on files.) +The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the +C:\Temp directory. The **Recurse** parameter extends the command to all subdirectories of C:\temp. +The **Include** parameter limits the files retrieved to those with the ".txt" file name extension. +The **Force** parameter gets hidden files, which would otherwise be excluded. (You cannot use +"c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) -The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** cmdlet, which applies the security descriptor in the *AclObject* parameter to all of the files in the pipeline. +The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** +cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in +the pipeline. -In practice, it is best to use the *WhatIf* parameter with all **Set-Acl** commands that can affect more than one item. -In this case, the second command in the pipeline would be `Set-Acl -AclObject $NewAcl -WhatIf`. -This command lists the files that would be affected by the command. -After reviewing the result, you can run the command again without the *WhatIf* parameter. +In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can +affect more than one item. In this case, the second command in the pipeline would be "`Set-Acl +-AclObject $NewAcl -WhatIf`". This command lists the files that would be affected by the command. +After reviewing the result, you can run the command again without the **Whatif** parameter. ## 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. -You can save the output of a Get-Acl command in a variable and then use the *AclObject* parameter to pass the variable, or type a Get-Acl command. +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. + +You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter +to pass the variable, or type a Get-Acl command. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: True -Position: 1 +Position: 2 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` -### -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. +### -Exclude + +Omits the specified items. The value of this parameter qualifies the **Path** parameter. Enter a +path element or pattern, such as "*.txt". Wildcards are permitted. Note: Not all providers may +support this parameter. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: -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). +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: True +``` -This parameter was introduced in Windows PowerShell 3.0. +### -Filter + +Specifies a filter in the provider's format or language. The value of this parameter qualifies the +**Path** parameter. The syntax of the filter, including the use of wildcards, depends on the +provider. Filters are more efficient than other parameters, because the provider applies them when +retrieving the objects, rather than having Windows PowerShell filter the objects after they are +retrieved. Note: Not all providers may support this parameter. ```yaml Type: String -Parameter Sets: ByPath, ByLiteralPath -Aliases: +Parameter Sets: (All) +Aliases: Required: False -Position: 2 +Position: Named Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False +Accept pipeline input: False +Accept wildcard characters: True ``` -### -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). +### -Include -This parameter was introduced in Windows PowerShell 3.0. +Changes only the specified items. The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". Wildcards are permitted. Note: Not all providers +may support this parameter. ```yaml -Type: SwitchParameter -Parameter Sets: ByPath, ByLiteralPath -Aliases: +Type: String[] +Parameter Sets: (All) +Aliases: Required: False Position: Named Default value: None Accept pipeline input: False -Accept wildcard characters: False +Accept wildcard characters: True ``` -### -Confirm -Prompts you for confirmation before running the cmdlet. +### -Passthru + +Returns an object that represents the security descriptor that was changed. By default, this cmdlet +does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: cf +Aliases: Required: False Position: Named @@ -174,89 +213,103 @@ Accept pipeline input: False 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". -Wildcards are permitted. +### -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. + +If you pass a security object to **Set-Acl** (either by using the **AclObject** or +**SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and +you omit the **Path** parameter (name and value), **Set-Acl** uses the path that is included in the +security object. ```yaml Type: String[] -Parameter Sets: (All) -Aliases: +Parameter Sets: ByPath +Aliases: -Required: False -Position: Named +Required: True +Position: 1 Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: True ``` -### -Filter -Specifies a filter in the provider's format or language. -The value of this parameter qualifies the *Path* parameter. -The syntax of the filter, including the use of wildcards, depends on the provider. -Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +### -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). + +This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: String -Parameter Sets: (All) -Aliases: +Parameter Sets: ByPath, ByLiteralPath +Aliases: Required: False -Position: Named +Position: 3 Default value: None -Accept pipeline input: False +Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -Include -Changes only the specified items. -The value of this parameter qualifies the *Path* parameter. -Enter a path element or pattern, such as "*.txt". -Wildcards are permitted. +### -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). + +This parameter is introduced in Windows PowerShell 3.0. ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: +Type: SwitchParameter +Parameter Sets: ByPath, ByLiteralPath +Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False 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. -You cannot pipe the object to be changed to **Set-Acl**. -Instead, use the *InputObject* parameter explicitly in the command. +Changes the security descriptor of the specified object. Enter a variable that contains the object +or a command that gets the object. -This parameter was introduced in Windows PowerShell 3.0. +You cannot pipe the object to be changed to **Set-Acl**. Instead, use the **InputObject** parameter +explicitly in the command. + +This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: PSObject Parameter Sets: ByInputObject -Aliases: +Aliases: Required: True -Position: 0 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) 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. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. -This parameter was introduced in Windows PowerShell 3.0. +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. If the path includes escape characters, enclose it in single quotation marks. Single +quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. + +This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: String[] @@ -270,52 +323,30 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` -### -Passthru -Returns an object that represents the security descriptor that was changed. -By default, this cmdlet does not generate any output. +### -Confirm + +Prompts you for confirmation before running the cmdlet. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: cf Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False 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. - -If you pass a security object to **Set-Acl** (either by using the *AclObject* or *SecurityDescriptor* parameter, or by passing a security object from Get-Acl to **Set-Acl**), and you omit the *Path* parameter (name and value), **Set-Acl** uses the path that is included in the security object. - -```yaml -Type: String[] -Parameter Sets: ByPath -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` +### -WhatIf -### -UseTransaction -Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see Includes the command in the active transaction. -This parameter is valid only when a transaction is in progress. -For more information, see +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: usetx +Aliases: wi Required: False Position: Named @@ -324,14 +355,15 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +### -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. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: wi +Aliases: usetx Required: False Position: Named @@ -341,26 +373,36 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see about_CommonParameters +(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. + +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. ## NOTES -* The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. As such, you can use it to change the security descriptors of files, directories, and registry keys. -* +- The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. + As such, you can use it to change the security descriptors of files, directories, and registry + keys. + +- There may be additional providers that also support this interface, or extend it. For example, + the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the + security descriptor extensions used by Active Directory. ## RELATED LINKS [Get-Acl](Get-Acl.md) - From 9799c2b11ba6d89e9ccc7892b222ac391014b1f8 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 10 Nov 2017 11:11:12 -0800 Subject: [PATCH 013/188] using semantic link breaks --- .../Microsoft.PowerShell.Security/Set-Acl.md | 165 +++++++++--------- .../Microsoft.PowerShell.Security/Set-Acl.md | 165 +++++++++--------- .../Microsoft.PowerShell.Security/Set-Acl.md | 165 +++++++++--------- .../Microsoft.PowerShell.Security/Set-Acl.md | 165 +++++++++--------- .../Microsoft.PowerShell.Security/Set-Acl.md | 165 +++++++++--------- 5 files changed, 390 insertions(+), 435 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md b/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md index 26afdbe3b464..27ca1b9e3071 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md @@ -12,8 +12,8 @@ title: Set-Acl ## SYNOPSIS -Changes the security descriptor of a specified item. The ability to manage a security descriptor -can be extended to additional providers that support Powershell Objects. +Changes the security descriptor of a specified item. +The ability to manage a security descriptor can be extended to additional providers that support Powershell Objects. ## SYNTAX @@ -42,15 +42,12 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl C:\Dog.txt PS C:\> 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. When the commands complete, the security descriptors of the Dog.txt -and Cat.txt files are identical. +These commands copy the values from the security descriptor of the Dog.txt file to the security descriptor of the Cat.txt file. +When the commands complete, the security descriptors of the Dog.txt and Cat.txt files are identical. -The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. The -assignment operator (=) stores the security descriptor in the value of the $DogACL variable. +The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. +The assignment operator (=) stores the security descriptor in the value of the $DogACL variable. -The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in -$DogACL. +The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in $DogACL. -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. +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 @@ -80,12 +75,10 @@ parameter is the model ACL, in this case, the ACL of Dog.txt as saved in the $Do PS C:\> Get-Acl 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. +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. The first command uses the **Get-Acl** cmdlet to get the security descriptor of the Dog.txt file. -The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the -**Set-Acl** cmdlet. +The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the **Set-Acl** cmdlet. The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. When the command completes, the ACLs of the Dog.txt and Cat.txt files are identical. @@ -97,36 +90,31 @@ PS C:\> $NewAcl = Get-Acl File0.txt PS C:\> Get-ChildItem 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. +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. -The first command gets the security descriptor of the File0.txt file in the current directory and -uses the assignment operator (=) to store it in the $NewACL variable. +The first command gets the security descriptor of the File0.txt file in the current directory and uses the assignment operator (=) to store it in the $NewACL variable. -The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the -C:\Temp directory. The **Recurse** parameter extends the command to all subdirectories of C:\temp. +The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the C:\Temp directory. +The **Recurse** parameter extends the command to all subdirectories of C:\temp. The **Include** parameter limits the files retrieved to those with the ".txt" file name extension. -The **Force** parameter gets hidden files, which would otherwise be excluded. (You cannot use -"c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) +The **Force** parameter gets hidden files, which would otherwise be excluded. +(You cannot use "c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) -The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** -cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in -the pipeline. +The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in the pipeline. -In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can -affect more than one item. In this case, the second command in the pipeline would be "`Set-Acl --AclObject $NewAcl -WhatIf`". This command lists the files that would be affected by the command. +In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can affect more than one item. +In this case, the second command in the pipeline would be "`Set-Acl -AclObject $NewAcl -WhatIf`". +This command lists the files that would be affected by the command. After reviewing the result, you can run the command again without the **Whatif** parameter. ## 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. +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. -You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter -to pass the variable, or type a Get-Acl command. +You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter to pass the variable, or type a Get-Acl command. ```yaml Type: Object @@ -142,9 +130,11 @@ 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". Wildcards are permitted. Note: Not all providers may -support this parameter. +Omits the specified items. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. +Note: Not all providers may support this parameter. ```yaml Type: String[] @@ -160,11 +150,11 @@ Accept wildcard characters: True ### -Filter -Specifies a filter in the provider's format or language. The value of this parameter qualifies the -**Path** parameter. The syntax of the filter, including the use of wildcards, depends on the -provider. Filters are more efficient than other parameters, because the provider applies them when -retrieving the objects, rather than having Windows PowerShell filter the objects after they are -retrieved. Note: Not all providers may support this parameter. +Specifies a filter in the provider's format or language. +The value of this parameter qualifies the **Path** parameter. +The syntax of the filter, including the use of wildcards, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +Note: Not all providers may support this parameter. ```yaml Type: String @@ -180,9 +170,11 @@ 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". Wildcards are permitted. Note: Not all providers -may support this parameter. +Changes only the specified items. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. +Note: Not all providers may support this parameter. ```yaml Type: String[] @@ -198,8 +190,8 @@ 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. +Returns an object that represents the security descriptor that was changed. +By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter @@ -215,8 +207,9 @@ 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. +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. If you pass a security object to **Set-Acl** (either by using the **AclObject** or **SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and @@ -237,12 +230,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. +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). +central access policies for users and groups. +For more information, see [Dynamic Access Control: Scenario Overview](http://go.microsoft.com/fwlink/?LinkId=238408). This parameter is introduced in Windows PowerShell 3.0. @@ -262,9 +255,8 @@ Accept wildcard characters: False 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). +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). This parameter is introduced in Windows PowerShell 3.0. @@ -282,11 +274,11 @@ 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. +Changes the security descriptor of the specified object. +Enter a variable that contains the object or a command that gets the object. -You cannot pipe the object to be changed to **Set-Acl**. Instead, use the **InputObject** parameter -explicitly in the command. +You cannot pipe the object to be changed to **Set-Acl**. +Instead, use the **InputObject** parameter explicitly in the command. This parameter is introduced in Windows PowerShell 3.0. @@ -304,10 +296,11 @@ 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. If the path includes escape characters, enclose it in single quotation marks. Single -quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +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. +If the path includes escape characters, enclose it in single quotation marks. +Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. This parameter is introduced in Windows PowerShell 3.0. @@ -341,7 +334,8 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter @@ -357,8 +351,9 @@ 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. +Includes the command in the active transaction. +This parameter is valid only when a transaction is in progress. +For more information, see about_Transactions. ```yaml Type: SwitchParameter @@ -374,10 +369,8 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see about_CommonParameters -(http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. +For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -389,19 +382,17 @@ You can pipe an ACL object or a security descriptor to **Set-Acl**. ### 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. +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. ## NOTES -- The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. - As such, you can use it to change the security descriptors of files, directories, and registry - keys. +The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. +As such, you can use it to change the security descriptors of files, directories, and registry keys. -- There may be additional providers that also support this interface, or extend it. For example, - the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the - security descriptor extensions used by Active Directory. +There may be additional providers that also support this interface, or extend it. +For example, the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the security descriptor extensions used by Active Directory. ## RELATED LINKS diff --git a/reference/4.0/Microsoft.PowerShell.Security/Set-Acl.md b/reference/4.0/Microsoft.PowerShell.Security/Set-Acl.md index 26afdbe3b464..27ca1b9e3071 100644 --- a/reference/4.0/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/4.0/Microsoft.PowerShell.Security/Set-Acl.md @@ -12,8 +12,8 @@ title: Set-Acl ## SYNOPSIS -Changes the security descriptor of a specified item. The ability to manage a security descriptor -can be extended to additional providers that support Powershell Objects. +Changes the security descriptor of a specified item. +The ability to manage a security descriptor can be extended to additional providers that support Powershell Objects. ## SYNTAX @@ -42,15 +42,12 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl C:\Dog.txt PS C:\> 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. When the commands complete, the security descriptors of the Dog.txt -and Cat.txt files are identical. +These commands copy the values from the security descriptor of the Dog.txt file to the security descriptor of the Cat.txt file. +When the commands complete, the security descriptors of the Dog.txt and Cat.txt files are identical. -The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. The -assignment operator (=) stores the security descriptor in the value of the $DogACL variable. +The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. +The assignment operator (=) stores the security descriptor in the value of the $DogACL variable. -The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in -$DogACL. +The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in $DogACL. -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. +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 @@ -80,12 +75,10 @@ parameter is the model ACL, in this case, the ACL of Dog.txt as saved in the $Do PS C:\> Get-Acl 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. +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. The first command uses the **Get-Acl** cmdlet to get the security descriptor of the Dog.txt file. -The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the -**Set-Acl** cmdlet. +The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the **Set-Acl** cmdlet. The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. When the command completes, the ACLs of the Dog.txt and Cat.txt files are identical. @@ -97,36 +90,31 @@ PS C:\> $NewAcl = Get-Acl File0.txt PS C:\> Get-ChildItem 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. +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. -The first command gets the security descriptor of the File0.txt file in the current directory and -uses the assignment operator (=) to store it in the $NewACL variable. +The first command gets the security descriptor of the File0.txt file in the current directory and uses the assignment operator (=) to store it in the $NewACL variable. -The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the -C:\Temp directory. The **Recurse** parameter extends the command to all subdirectories of C:\temp. +The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the C:\Temp directory. +The **Recurse** parameter extends the command to all subdirectories of C:\temp. The **Include** parameter limits the files retrieved to those with the ".txt" file name extension. -The **Force** parameter gets hidden files, which would otherwise be excluded. (You cannot use -"c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) +The **Force** parameter gets hidden files, which would otherwise be excluded. +(You cannot use "c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) -The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** -cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in -the pipeline. +The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in the pipeline. -In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can -affect more than one item. In this case, the second command in the pipeline would be "`Set-Acl --AclObject $NewAcl -WhatIf`". This command lists the files that would be affected by the command. +In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can affect more than one item. +In this case, the second command in the pipeline would be "`Set-Acl -AclObject $NewAcl -WhatIf`". +This command lists the files that would be affected by the command. After reviewing the result, you can run the command again without the **Whatif** parameter. ## 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. +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. -You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter -to pass the variable, or type a Get-Acl command. +You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter to pass the variable, or type a Get-Acl command. ```yaml Type: Object @@ -142,9 +130,11 @@ 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". Wildcards are permitted. Note: Not all providers may -support this parameter. +Omits the specified items. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. +Note: Not all providers may support this parameter. ```yaml Type: String[] @@ -160,11 +150,11 @@ Accept wildcard characters: True ### -Filter -Specifies a filter in the provider's format or language. The value of this parameter qualifies the -**Path** parameter. The syntax of the filter, including the use of wildcards, depends on the -provider. Filters are more efficient than other parameters, because the provider applies them when -retrieving the objects, rather than having Windows PowerShell filter the objects after they are -retrieved. Note: Not all providers may support this parameter. +Specifies a filter in the provider's format or language. +The value of this parameter qualifies the **Path** parameter. +The syntax of the filter, including the use of wildcards, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +Note: Not all providers may support this parameter. ```yaml Type: String @@ -180,9 +170,11 @@ 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". Wildcards are permitted. Note: Not all providers -may support this parameter. +Changes only the specified items. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. +Note: Not all providers may support this parameter. ```yaml Type: String[] @@ -198,8 +190,8 @@ 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. +Returns an object that represents the security descriptor that was changed. +By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter @@ -215,8 +207,9 @@ 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. +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. If you pass a security object to **Set-Acl** (either by using the **AclObject** or **SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and @@ -237,12 +230,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. +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). +central access policies for users and groups. +For more information, see [Dynamic Access Control: Scenario Overview](http://go.microsoft.com/fwlink/?LinkId=238408). This parameter is introduced in Windows PowerShell 3.0. @@ -262,9 +255,8 @@ Accept wildcard characters: False 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). +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). This parameter is introduced in Windows PowerShell 3.0. @@ -282,11 +274,11 @@ 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. +Changes the security descriptor of the specified object. +Enter a variable that contains the object or a command that gets the object. -You cannot pipe the object to be changed to **Set-Acl**. Instead, use the **InputObject** parameter -explicitly in the command. +You cannot pipe the object to be changed to **Set-Acl**. +Instead, use the **InputObject** parameter explicitly in the command. This parameter is introduced in Windows PowerShell 3.0. @@ -304,10 +296,11 @@ 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. If the path includes escape characters, enclose it in single quotation marks. Single -quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +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. +If the path includes escape characters, enclose it in single quotation marks. +Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. This parameter is introduced in Windows PowerShell 3.0. @@ -341,7 +334,8 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter @@ -357,8 +351,9 @@ 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. +Includes the command in the active transaction. +This parameter is valid only when a transaction is in progress. +For more information, see about_Transactions. ```yaml Type: SwitchParameter @@ -374,10 +369,8 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see about_CommonParameters -(http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. +For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -389,19 +382,17 @@ You can pipe an ACL object or a security descriptor to **Set-Acl**. ### 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. +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. ## NOTES -- The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. - As such, you can use it to change the security descriptors of files, directories, and registry - keys. +The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. +As such, you can use it to change the security descriptors of files, directories, and registry keys. -- There may be additional providers that also support this interface, or extend it. For example, - the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the - security descriptor extensions used by Active Directory. +There may be additional providers that also support this interface, or extend it. +For example, the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the security descriptor extensions used by Active Directory. ## RELATED LINKS diff --git a/reference/5.0/Microsoft.PowerShell.Security/Set-Acl.md b/reference/5.0/Microsoft.PowerShell.Security/Set-Acl.md index 26afdbe3b464..27ca1b9e3071 100644 --- a/reference/5.0/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/5.0/Microsoft.PowerShell.Security/Set-Acl.md @@ -12,8 +12,8 @@ title: Set-Acl ## SYNOPSIS -Changes the security descriptor of a specified item. The ability to manage a security descriptor -can be extended to additional providers that support Powershell Objects. +Changes the security descriptor of a specified item. +The ability to manage a security descriptor can be extended to additional providers that support Powershell Objects. ## SYNTAX @@ -42,15 +42,12 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl C:\Dog.txt PS C:\> 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. When the commands complete, the security descriptors of the Dog.txt -and Cat.txt files are identical. +These commands copy the values from the security descriptor of the Dog.txt file to the security descriptor of the Cat.txt file. +When the commands complete, the security descriptors of the Dog.txt and Cat.txt files are identical. -The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. The -assignment operator (=) stores the security descriptor in the value of the $DogACL variable. +The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. +The assignment operator (=) stores the security descriptor in the value of the $DogACL variable. -The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in -$DogACL. +The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in $DogACL. -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. +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 @@ -80,12 +75,10 @@ parameter is the model ACL, in this case, the ACL of Dog.txt as saved in the $Do PS C:\> Get-Acl 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. +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. The first command uses the **Get-Acl** cmdlet to get the security descriptor of the Dog.txt file. -The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the -**Set-Acl** cmdlet. +The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the **Set-Acl** cmdlet. The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. When the command completes, the ACLs of the Dog.txt and Cat.txt files are identical. @@ -97,36 +90,31 @@ PS C:\> $NewAcl = Get-Acl File0.txt PS C:\> Get-ChildItem 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. +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. -The first command gets the security descriptor of the File0.txt file in the current directory and -uses the assignment operator (=) to store it in the $NewACL variable. +The first command gets the security descriptor of the File0.txt file in the current directory and uses the assignment operator (=) to store it in the $NewACL variable. -The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the -C:\Temp directory. The **Recurse** parameter extends the command to all subdirectories of C:\temp. +The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the C:\Temp directory. +The **Recurse** parameter extends the command to all subdirectories of C:\temp. The **Include** parameter limits the files retrieved to those with the ".txt" file name extension. -The **Force** parameter gets hidden files, which would otherwise be excluded. (You cannot use -"c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) +The **Force** parameter gets hidden files, which would otherwise be excluded. +(You cannot use "c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) -The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** -cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in -the pipeline. +The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in the pipeline. -In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can -affect more than one item. In this case, the second command in the pipeline would be "`Set-Acl --AclObject $NewAcl -WhatIf`". This command lists the files that would be affected by the command. +In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can affect more than one item. +In this case, the second command in the pipeline would be "`Set-Acl -AclObject $NewAcl -WhatIf`". +This command lists the files that would be affected by the command. After reviewing the result, you can run the command again without the **Whatif** parameter. ## 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. +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. -You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter -to pass the variable, or type a Get-Acl command. +You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter to pass the variable, or type a Get-Acl command. ```yaml Type: Object @@ -142,9 +130,11 @@ 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". Wildcards are permitted. Note: Not all providers may -support this parameter. +Omits the specified items. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. +Note: Not all providers may support this parameter. ```yaml Type: String[] @@ -160,11 +150,11 @@ Accept wildcard characters: True ### -Filter -Specifies a filter in the provider's format or language. The value of this parameter qualifies the -**Path** parameter. The syntax of the filter, including the use of wildcards, depends on the -provider. Filters are more efficient than other parameters, because the provider applies them when -retrieving the objects, rather than having Windows PowerShell filter the objects after they are -retrieved. Note: Not all providers may support this parameter. +Specifies a filter in the provider's format or language. +The value of this parameter qualifies the **Path** parameter. +The syntax of the filter, including the use of wildcards, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +Note: Not all providers may support this parameter. ```yaml Type: String @@ -180,9 +170,11 @@ 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". Wildcards are permitted. Note: Not all providers -may support this parameter. +Changes only the specified items. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. +Note: Not all providers may support this parameter. ```yaml Type: String[] @@ -198,8 +190,8 @@ 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. +Returns an object that represents the security descriptor that was changed. +By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter @@ -215,8 +207,9 @@ 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. +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. If you pass a security object to **Set-Acl** (either by using the **AclObject** or **SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and @@ -237,12 +230,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. +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). +central access policies for users and groups. +For more information, see [Dynamic Access Control: Scenario Overview](http://go.microsoft.com/fwlink/?LinkId=238408). This parameter is introduced in Windows PowerShell 3.0. @@ -262,9 +255,8 @@ Accept wildcard characters: False 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). +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). This parameter is introduced in Windows PowerShell 3.0. @@ -282,11 +274,11 @@ 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. +Changes the security descriptor of the specified object. +Enter a variable that contains the object or a command that gets the object. -You cannot pipe the object to be changed to **Set-Acl**. Instead, use the **InputObject** parameter -explicitly in the command. +You cannot pipe the object to be changed to **Set-Acl**. +Instead, use the **InputObject** parameter explicitly in the command. This parameter is introduced in Windows PowerShell 3.0. @@ -304,10 +296,11 @@ 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. If the path includes escape characters, enclose it in single quotation marks. Single -quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +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. +If the path includes escape characters, enclose it in single quotation marks. +Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. This parameter is introduced in Windows PowerShell 3.0. @@ -341,7 +334,8 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter @@ -357,8 +351,9 @@ 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. +Includes the command in the active transaction. +This parameter is valid only when a transaction is in progress. +For more information, see about_Transactions. ```yaml Type: SwitchParameter @@ -374,10 +369,8 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see about_CommonParameters -(http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. +For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -389,19 +382,17 @@ You can pipe an ACL object or a security descriptor to **Set-Acl**. ### 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. +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. ## NOTES -- The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. - As such, you can use it to change the security descriptors of files, directories, and registry - keys. +The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. +As such, you can use it to change the security descriptors of files, directories, and registry keys. -- There may be additional providers that also support this interface, or extend it. For example, - the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the - security descriptor extensions used by Active Directory. +There may be additional providers that also support this interface, or extend it. +For example, the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the security descriptor extensions used by Active Directory. ## RELATED LINKS diff --git a/reference/5.1/Microsoft.PowerShell.Security/Set-Acl.md b/reference/5.1/Microsoft.PowerShell.Security/Set-Acl.md index 26afdbe3b464..27ca1b9e3071 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/5.1/Microsoft.PowerShell.Security/Set-Acl.md @@ -12,8 +12,8 @@ title: Set-Acl ## SYNOPSIS -Changes the security descriptor of a specified item. The ability to manage a security descriptor -can be extended to additional providers that support Powershell Objects. +Changes the security descriptor of a specified item. +The ability to manage a security descriptor can be extended to additional providers that support Powershell Objects. ## SYNTAX @@ -42,15 +42,12 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl C:\Dog.txt PS C:\> 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. When the commands complete, the security descriptors of the Dog.txt -and Cat.txt files are identical. +These commands copy the values from the security descriptor of the Dog.txt file to the security descriptor of the Cat.txt file. +When the commands complete, the security descriptors of the Dog.txt and Cat.txt files are identical. -The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. The -assignment operator (=) stores the security descriptor in the value of the $DogACL variable. +The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. +The assignment operator (=) stores the security descriptor in the value of the $DogACL variable. -The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in -$DogACL. +The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in $DogACL. -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. +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 @@ -80,12 +75,10 @@ parameter is the model ACL, in this case, the ACL of Dog.txt as saved in the $Do PS C:\> Get-Acl 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. +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. The first command uses the **Get-Acl** cmdlet to get the security descriptor of the Dog.txt file. -The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the -**Set-Acl** cmdlet. +The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the **Set-Acl** cmdlet. The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. When the command completes, the ACLs of the Dog.txt and Cat.txt files are identical. @@ -97,36 +90,31 @@ PS C:\> $NewAcl = Get-Acl File0.txt PS C:\> Get-ChildItem 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. +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. -The first command gets the security descriptor of the File0.txt file in the current directory and -uses the assignment operator (=) to store it in the $NewACL variable. +The first command gets the security descriptor of the File0.txt file in the current directory and uses the assignment operator (=) to store it in the $NewACL variable. -The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the -C:\Temp directory. The **Recurse** parameter extends the command to all subdirectories of C:\temp. +The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the C:\Temp directory. +The **Recurse** parameter extends the command to all subdirectories of C:\temp. The **Include** parameter limits the files retrieved to those with the ".txt" file name extension. -The **Force** parameter gets hidden files, which would otherwise be excluded. (You cannot use -"c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) +The **Force** parameter gets hidden files, which would otherwise be excluded. +(You cannot use "c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) -The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** -cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in -the pipeline. +The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in the pipeline. -In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can -affect more than one item. In this case, the second command in the pipeline would be "`Set-Acl --AclObject $NewAcl -WhatIf`". This command lists the files that would be affected by the command. +In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can affect more than one item. +In this case, the second command in the pipeline would be "`Set-Acl -AclObject $NewAcl -WhatIf`". +This command lists the files that would be affected by the command. After reviewing the result, you can run the command again without the **Whatif** parameter. ## 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. +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. -You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter -to pass the variable, or type a Get-Acl command. +You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter to pass the variable, or type a Get-Acl command. ```yaml Type: Object @@ -142,9 +130,11 @@ 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". Wildcards are permitted. Note: Not all providers may -support this parameter. +Omits the specified items. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. +Note: Not all providers may support this parameter. ```yaml Type: String[] @@ -160,11 +150,11 @@ Accept wildcard characters: True ### -Filter -Specifies a filter in the provider's format or language. The value of this parameter qualifies the -**Path** parameter. The syntax of the filter, including the use of wildcards, depends on the -provider. Filters are more efficient than other parameters, because the provider applies them when -retrieving the objects, rather than having Windows PowerShell filter the objects after they are -retrieved. Note: Not all providers may support this parameter. +Specifies a filter in the provider's format or language. +The value of this parameter qualifies the **Path** parameter. +The syntax of the filter, including the use of wildcards, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +Note: Not all providers may support this parameter. ```yaml Type: String @@ -180,9 +170,11 @@ 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". Wildcards are permitted. Note: Not all providers -may support this parameter. +Changes only the specified items. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. +Note: Not all providers may support this parameter. ```yaml Type: String[] @@ -198,8 +190,8 @@ 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. +Returns an object that represents the security descriptor that was changed. +By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter @@ -215,8 +207,9 @@ 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. +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. If you pass a security object to **Set-Acl** (either by using the **AclObject** or **SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and @@ -237,12 +230,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. +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). +central access policies for users and groups. +For more information, see [Dynamic Access Control: Scenario Overview](http://go.microsoft.com/fwlink/?LinkId=238408). This parameter is introduced in Windows PowerShell 3.0. @@ -262,9 +255,8 @@ Accept wildcard characters: False 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). +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). This parameter is introduced in Windows PowerShell 3.0. @@ -282,11 +274,11 @@ 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. +Changes the security descriptor of the specified object. +Enter a variable that contains the object or a command that gets the object. -You cannot pipe the object to be changed to **Set-Acl**. Instead, use the **InputObject** parameter -explicitly in the command. +You cannot pipe the object to be changed to **Set-Acl**. +Instead, use the **InputObject** parameter explicitly in the command. This parameter is introduced in Windows PowerShell 3.0. @@ -304,10 +296,11 @@ 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. If the path includes escape characters, enclose it in single quotation marks. Single -quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +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. +If the path includes escape characters, enclose it in single quotation marks. +Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. This parameter is introduced in Windows PowerShell 3.0. @@ -341,7 +334,8 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter @@ -357,8 +351,9 @@ 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. +Includes the command in the active transaction. +This parameter is valid only when a transaction is in progress. +For more information, see about_Transactions. ```yaml Type: SwitchParameter @@ -374,10 +369,8 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see about_CommonParameters -(http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. +For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -389,19 +382,17 @@ You can pipe an ACL object or a security descriptor to **Set-Acl**. ### 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. +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. ## NOTES -- The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. - As such, you can use it to change the security descriptors of files, directories, and registry - keys. +The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. +As such, you can use it to change the security descriptors of files, directories, and registry keys. -- There may be additional providers that also support this interface, or extend it. For example, - the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the - security descriptor extensions used by Active Directory. +There may be additional providers that also support this interface, or extend it. +For example, the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the security descriptor extensions used by Active Directory. ## RELATED LINKS diff --git a/reference/6/Microsoft.PowerShell.Security/Set-Acl.md b/reference/6/Microsoft.PowerShell.Security/Set-Acl.md index 751c008f40b6..609150b9dfe5 100644 --- a/reference/6/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/6/Microsoft.PowerShell.Security/Set-Acl.md @@ -12,8 +12,8 @@ title: Set-Acl ## SYNOPSIS -Changes the security descriptor of a specified item. The ability to manage a security descriptor -can be extended to additional providers that support Powershell Objects. +Changes the security descriptor of a specified item. +The ability to manage a security descriptor can be extended to additional providers that support Powershell Objects. ## SYNTAX @@ -42,15 +42,12 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl C:\Dog.txt PS C:\> 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. When the commands complete, the security descriptors of the Dog.txt -and Cat.txt files are identical. +These commands copy the values from the security descriptor of the Dog.txt file to the security descriptor of the Cat.txt file. +When the commands complete, the security descriptors of the Dog.txt and Cat.txt files are identical. -The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. The -assignment operator (=) stores the security descriptor in the value of the $DogACL variable. +The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. +The assignment operator (=) stores the security descriptor in the value of the $DogACL variable. -The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in -$DogACL. +The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in $DogACL. -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. +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 @@ -80,12 +75,10 @@ parameter is the model ACL, in this case, the ACL of Dog.txt as saved in the $Do PS C:\> Get-Acl 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. +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. The first command uses the **Get-Acl** cmdlet to get the security descriptor of the Dog.txt file. -The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the -**Set-Acl** cmdlet. +The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the **Set-Acl** cmdlet. The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. When the command completes, the ACLs of the Dog.txt and Cat.txt files are identical. @@ -97,36 +90,31 @@ PS C:\> $NewAcl = Get-Acl File0.txt PS C:\> Get-ChildItem 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. +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. -The first command gets the security descriptor of the File0.txt file in the current directory and -uses the assignment operator (=) to store it in the $NewACL variable. +The first command gets the security descriptor of the File0.txt file in the current directory and uses the assignment operator (=) to store it in the $NewACL variable. -The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the -C:\Temp directory. The **Recurse** parameter extends the command to all subdirectories of C:\temp. +The first command in the pipeline uses the Get-ChildItem cmdlet to get all of the text files in the C:\Temp directory. +The **Recurse** parameter extends the command to all subdirectories of C:\temp. The **Include** parameter limits the files retrieved to those with the ".txt" file name extension. -The **Force** parameter gets hidden files, which would otherwise be excluded. (You cannot use -"c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) +The **Force** parameter gets hidden files, which would otherwise be excluded. +(You cannot use "c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) -The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** -cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in -the pipeline. +The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in the pipeline. -In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can -affect more than one item. In this case, the second command in the pipeline would be "`Set-Acl --AclObject $NewAcl -WhatIf`". This command lists the files that would be affected by the command. +In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can affect more than one item. +In this case, the second command in the pipeline would be "`Set-Acl -AclObject $NewAcl -WhatIf`". +This command lists the files that would be affected by the command. After reviewing the result, you can run the command again without the **Whatif** parameter. ## 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. +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. -You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter -to pass the variable, or type a Get-Acl command. +You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter to pass the variable, or type a Get-Acl command. ```yaml Type: Object @@ -142,9 +130,11 @@ 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". Wildcards are permitted. Note: Not all providers may -support this parameter. +Omits the specified items. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. +Note: Not all providers may support this parameter. ```yaml Type: String[] @@ -160,11 +150,11 @@ Accept wildcard characters: True ### -Filter -Specifies a filter in the provider's format or language. The value of this parameter qualifies the -**Path** parameter. The syntax of the filter, including the use of wildcards, depends on the -provider. Filters are more efficient than other parameters, because the provider applies them when -retrieving the objects, rather than having Windows PowerShell filter the objects after they are -retrieved. Note: Not all providers may support this parameter. +Specifies a filter in the provider's format or language. +The value of this parameter qualifies the **Path** parameter. +The syntax of the filter, including the use of wildcards, depends on the provider. +Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved. +Note: Not all providers may support this parameter. ```yaml Type: String @@ -180,9 +170,11 @@ 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". Wildcards are permitted. Note: Not all providers -may support this parameter. +Changes only the specified items. +The value of this parameter qualifies the **Path** parameter. +Enter a path element or pattern, such as "*.txt". +Wildcards are permitted. +Note: Not all providers may support this parameter. ```yaml Type: String[] @@ -198,8 +190,8 @@ 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. +Returns an object that represents the security descriptor that was changed. +By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter @@ -215,8 +207,9 @@ 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. +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. If you pass a security object to **Set-Acl** (either by using the **AclObject** or **SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and @@ -237,12 +230,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. +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). +central access policies for users and groups. +For more information, see [Dynamic Access Control: Scenario Overview](http://go.microsoft.com/fwlink/?LinkId=238408). This parameter is introduced in Windows PowerShell 3.0. @@ -262,9 +255,8 @@ Accept wildcard characters: False 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). +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). This parameter is introduced in Windows PowerShell 3.0. @@ -282,11 +274,11 @@ 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. +Changes the security descriptor of the specified object. +Enter a variable that contains the object or a command that gets the object. -You cannot pipe the object to be changed to **Set-Acl**. Instead, use the **InputObject** parameter -explicitly in the command. +You cannot pipe the object to be changed to **Set-Acl**. +Instead, use the **InputObject** parameter explicitly in the command. This parameter is introduced in Windows PowerShell 3.0. @@ -304,10 +296,11 @@ 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. If the path includes escape characters, enclose it in single quotation marks. Single -quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +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. +If the path includes escape characters, enclose it in single quotation marks. +Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. This parameter is introduced in Windows PowerShell 3.0. @@ -341,7 +334,8 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter @@ -357,8 +351,9 @@ 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. +Includes the command in the active transaction. +This parameter is valid only when a transaction is in progress. +For more information, see about_Transactions. ```yaml Type: SwitchParameter @@ -374,10 +369,8 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see about_CommonParameters -(http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. +For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -389,19 +382,17 @@ You can pipe an ACL object or a security descriptor to **Set-Acl**. ### 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. +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. ## NOTES -- The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. - As such, you can use it to change the security descriptors of files, directories, and registry - keys. +The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. +As such, you can use it to change the security descriptors of files, directories, and registry keys. -- There may be additional providers that also support this interface, or extend it. For example, - the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the - security descriptor extensions used by Active Directory. +There may be additional providers that also support this interface, or extend it. +For example, the Active Directory Provider defines a new ActiveDirectoryAccessRule class to implement the security descriptor extensions used by Active Directory. ## RELATED LINKS From a5f21c5808fcff6d283a01a4d5f3793bd31eb92b Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Tue, 14 Nov 2017 01:25:59 +0900 Subject: [PATCH 014/188] Fix the example of `Format-Wide -ShowError` (#1851) --- .../Microsoft.PowerShell.Utility/Format-Wide.md | 16 ++++++++-------- .../Microsoft.PowerShell.Utility/Format-Wide.md | 16 ++++++++-------- .../Microsoft.PowerShell.Utility/Format-Wide.md | 14 +++++++------- .../Microsoft.PowerShell.Utility/Format-Wide.md | 14 +++++++------- .../Microsoft.PowerShell.Utility/Format-Wide.md | 14 +++++++------- 5 files changed, 37 insertions(+), 37 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Format-Wide.md b/reference/3.0/Microsoft.PowerShell.Utility/Format-Wide.md index 74b467467e59..9952a8efcdc1 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Format-Wide.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Format-Wide.md @@ -208,18 +208,18 @@ Accept wildcard characters: True ``` ### -ShowError -Sends errors through the pipeline. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Wide command, and the expressions do not appear to be working. -The following shows an example of the results of adding the ShowError parameter with an expression. +Indicates that the cmdlet sends errors through the pipeline. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Wide` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **ShowError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Wide { $_ / $null } -ShowError -PS \> Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday Failed to evaluate expression " $_ / $null ". - + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) \[\], RuntimeException + + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError +``` ```yaml Type: SwitchParameter diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Format-Wide.md b/reference/4.0/Microsoft.PowerShell.Utility/Format-Wide.md index 54b29b78d57f..9c8e33a81766 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Format-Wide.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Format-Wide.md @@ -213,18 +213,18 @@ Accept wildcard characters: True ``` ### -ShowError -Sends errors through the pipeline. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Wide command, and the expressions do not appear to be working. -The following shows an example of the results of adding the ShowError parameter with an expression. +Indicates that the cmdlet sends errors through the pipeline. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Wide` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **ShowError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Wide { $_ / $null } -ShowError -PS \> Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday Failed to evaluate expression " $_ / $null ". - + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) \[\], RuntimeException + + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError +``` ```yaml Type: SwitchParameter diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Format-Wide.md b/reference/5.0/Microsoft.PowerShell.Utility/Format-Wide.md index 5b4d2a6b5c50..ec9b0eba9f2b 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Format-Wide.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Format-Wide.md @@ -217,17 +217,17 @@ Accept wildcard characters: False ### -ShowError Indicates that the cmdlet sends errors through the pipeline. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Wide** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the *ShowError* parameter with an expression. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Wide` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **ShowError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Wide { $_ / $null } -ShowError -PS \> Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday Failed to evaluate expression " $_ / $null ". - + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) \[\], RuntimeException + + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError +``` ```yaml Type: SwitchParameter diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Format-Wide.md b/reference/5.1/Microsoft.PowerShell.Utility/Format-Wide.md index 0b9181c73b5f..a0930b259b7a 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Format-Wide.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Format-Wide.md @@ -217,17 +217,17 @@ Accept wildcard characters: False ### -ShowError Indicates that the cmdlet sends errors through the pipeline. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Wide** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the *ShowError* parameter with an expression. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Wide` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **ShowError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Wide { $_ / $null } -ShowError -PS \> Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday Failed to evaluate expression " $_ / $null ". - + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) \[\], RuntimeException + + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError +``` ```yaml Type: SwitchParameter diff --git a/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md b/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md index 0dcc7b2a5816..d57313b8dc33 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md +++ b/reference/6/Microsoft.PowerShell.Utility/Format-Wide.md @@ -245,17 +245,17 @@ Accept wildcard characters: False ### -ShowError Indicates that the cmdlet sends errors through the pipeline. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a **Format-Wide** command, and the expressions do not appear to be working. -The following shows an example of the results of adding the *ShowError* parameter with an expression. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Wide` command, and the expressions do not appear to be working. +The following shows an example of the results of adding the **ShowError** parameter with an expression. + +```powershell +PS C:\> Get-Date | Format-Wide { $_ / $null } -ShowError -PS \> Get-Date | Format-Wide DayOfWeek,{ $_ / $null } -ShowError -DayOfWeek $_ / $null ---------- ------------ -Wednesday Failed to evaluate expression " $_ / $null ". - + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) \[\], RuntimeException + + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) [], RuntimeException + FullyQualifiedErrorId : mshExpressionError +``` ```yaml Type: SwitchParameter From 9467262f96e7d07deeb06747c0bed9b57494ec0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alan=20P=C5=82=C3=B3cieniak?= Date: Mon, 13 Nov 2017 17:27:49 +0100 Subject: [PATCH 015/188] Fixed Test-ScriptFileInfo example (#1852) --- reference/5.1/PowershellGet/Test-ScriptFileInfo.md | 14 +++++++------- reference/6/PowerShellGet/Test-ScriptFileInfo.md | 14 +++++++------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/reference/5.1/PowershellGet/Test-ScriptFileInfo.md b/reference/5.1/PowershellGet/Test-ScriptFileInfo.md index a9d8c04f5312..22d1673e4c94 100644 --- a/reference/5.1/PowershellGet/Test-ScriptFileInfo.md +++ b/reference/5.1/PowershellGet/Test-ScriptFileInfo.md @@ -44,16 +44,16 @@ The script file includes valid metadata. ### Example 2: Test a script file that has values for all metadata properties ``` -PS C:\> Test-ScriptFileInfo -Path "D:\code\Test-Runbook.ps1 | Format-List * +PS C:\> Test-ScriptFileInfo -Path "D:\code\Test-Runbook.ps1" | Format-List * Name : Test-Runbook Path : D:\code\Test-Runbook.ps1 ScriptBase : D:\code -ReleaseNotes : {contoso script now supports following features, Feature 1, Feature 2, Feature 3...} +ReleaseNotes : {contoso script now supports following features, Feature 1, Feature 2, Feature 3...} Version : 1.0 Guid : eb246b19-17da-4392-8c89-7c280f69ad0e Author : pattif CompanyName : Microsoft Corporation -Copyright : © 2015 Microsoft Corporation. All rights reserved. +Copyright : © 2015 Microsoft Corporation. All rights reserved. Tags : {Tag1, Tag2, Tag3} LicenseUri : https://contoso.com/License ProjectUri : https://contoso.com/ @@ -63,7 +63,7 @@ RequiredScripts : {Start-WFContosoServer, Stop-ContosoServerScript} ExternalScriptDependencies : Stop-ContosoServerScript Description : Contoso Script example RequiredModules : {RequiredModule1, @{ ModuleName = 'RequiredModule2'; ModuleVersion = '1.0' }, @{ ModuleName = 'RequiredModule3'; RequiredVersion = '2.0' }, ExternalModule1} -ExportedCommands : {Test-WebUri, ValidateAndAdd-PSScriptInfoEntry, Get-PSScriptInfo, My-Workflow...} +ExportedCommands : {Test-WebUri, ValidateAndAdd-PSScriptInfoEntry, Get-PSScriptInfo, My-Workflow...} ExportedFunctions : {Test-WebUri, ValidateAndAdd-PSScriptInfoEntry, Get-PSScriptInfo, My-AdvPSCmdlet} ExportedWorkflows : My-Workflow ``` @@ -74,7 +74,7 @@ This command tests the script file Test-Runbook.ps1 and uses the pipeline operat ``` PS C:\> Test-ScriptFileInfo -Path "D:\code\Hello-World.ps1" Test-ScriptFileInfo : Script 'D:\code\Hello-World.ps1' is missing required metadata properties. Verify that the script file has Version, Description -and Author properties. You can use the Update-ScriptFileInfo or New-ScriptFileInfo cmdlet to add or update the PSScriptInfo to the script file. +and Author properties. You can use the Update-ScriptFileInfo or New-ScriptFileInfo cmdlet to add or update the PSScriptInfo to the script file. At line:1 char:1 + Test-ScriptFileInfo D:\code\Hello-World.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -97,7 +97,7 @@ Single quotation marks tell Windows PowerShell not to interpret any characters a ```yaml Type: String Parameter Sets: LiteralPathParameterSet -Aliases: +Aliases: Required: True Position: Named @@ -114,7 +114,7 @@ The default location is the current directory (.). ```yaml Type: String Parameter Sets: PathParameterSet -Aliases: +Aliases: Required: True Position: 0 diff --git a/reference/6/PowerShellGet/Test-ScriptFileInfo.md b/reference/6/PowerShellGet/Test-ScriptFileInfo.md index b589bd989d08..639c8b7c2cda 100644 --- a/reference/6/PowerShellGet/Test-ScriptFileInfo.md +++ b/reference/6/PowerShellGet/Test-ScriptFileInfo.md @@ -44,16 +44,16 @@ The script file includes valid metadata. ### Example 2: Test a script file that has values for all metadata properties ``` -PS C:\> Test-ScriptFileInfo -Path "D:\code\Test-Runbook.ps1 | Format-List * +PS C:\> Test-ScriptFileInfo -Path "D:\code\Test-Runbook.ps1" | Format-List * Name : Test-Runbook Path : D:\code\Test-Runbook.ps1 ScriptBase : D:\code -ReleaseNotes : {contoso script now supports following features, Feature 1, Feature 2, Feature 3...} +ReleaseNotes : {contoso script now supports following features, Feature 1, Feature 2, Feature 3...} Version : 1.0 Guid : eb246b19-17da-4392-8c89-7c280f69ad0e Author : pattif CompanyName : Microsoft Corporation -Copyright : © 2015 Microsoft Corporation. All rights reserved. +Copyright : © 2015 Microsoft Corporation. All rights reserved. Tags : {Tag1, Tag2, Tag3} LicenseUri : https://contoso.com/License ProjectUri : https://contoso.com/ @@ -63,7 +63,7 @@ RequiredScripts : {Start-WFContosoServer, Stop-ContosoServerScript} ExternalScriptDependencies : Stop-ContosoServerScript Description : Contoso Script example RequiredModules : {RequiredModule1, @{ ModuleName = 'RequiredModule2'; ModuleVersion = '1.0' }, @{ ModuleName = 'RequiredModule3'; RequiredVersion = '2.0' }, ExternalModule1} -ExportedCommands : {Test-WebUri, ValidateAndAdd-PSScriptInfoEntry, Get-PSScriptInfo, My-Workflow...} +ExportedCommands : {Test-WebUri, ValidateAndAdd-PSScriptInfoEntry, Get-PSScriptInfo, My-Workflow...} ExportedFunctions : {Test-WebUri, ValidateAndAdd-PSScriptInfoEntry, Get-PSScriptInfo, My-AdvPSCmdlet} ExportedWorkflows : My-Workflow ``` @@ -74,7 +74,7 @@ This command tests the script file Test-Runbook.ps1 and uses the pipeline operat ``` PS C:\> Test-ScriptFileInfo -Path "D:\code\Hello-World.ps1" Test-ScriptFileInfo : Script 'D:\code\Hello-World.ps1' is missing required metadata properties. Verify that the script file has Version, Description -and Author properties. You can use the Update-ScriptFileInfo or New-ScriptFileInfo cmdlet to add or update the PSScriptInfo to the script file. +and Author properties. You can use the Update-ScriptFileInfo or New-ScriptFileInfo cmdlet to add or update the PSScriptInfo to the script file. At line:1 char:1 + Test-ScriptFileInfo D:\code\Hello-World.ps1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -97,7 +97,7 @@ Single quotation marks tell Windows PowerShell not to interpret any characters a ```yaml Type: String Parameter Sets: LiteralPathParameterSet -Aliases: +Aliases: Required: True Position: Named @@ -114,7 +114,7 @@ The default location is the current directory (.). ```yaml Type: String Parameter Sets: PathParameterSet -Aliases: +Aliases: Required: True Position: 1 From b5d12a3476fb1b7cbf72f61795c468c83351085e Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 7 Nov 2017 14:18:25 -0800 Subject: [PATCH 016/188] fixing issue 1768 --- .../Write-Progress.md | 26 +++++++++---------- .../Write-Progress.md | 26 +++++++++---------- .../Write-Progress.md | 24 ++++++++--------- .../Write-Progress.md | 22 ++++++++-------- .../Write-Progress.md | 24 ++++++++--------- 5 files changed, 61 insertions(+), 61 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Write-Progress.md b/reference/3.0/Microsoft.PowerShell.Utility/Write-Progress.md index 25eb91d0afbc..8209bbb0b9ac 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Write-Progress.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Write-Progress.md @@ -27,7 +27,7 @@ You can select the indicators that the bar reflects and the text that appears ab ### Example 1 ``` PS C:\> for ($i = 1; $i -le 100; $i++ ) -{write-progress -activity "Search in Progress" -status "$i% Complete:" -percentcomplete $i;} +{write-progress -activity "Search in Progress" -status "$i% Complete:" -PercentComplete $i;} ``` This command displays the progress of a For loop that counts from 1 to 100. @@ -35,9 +35,9 @@ The Write-Progress command includes a status bar heading ("activity"), a status ### Example 2 ``` PS C:\> for($i = 1; $i -lt 101; $i++ ) -{write-progress -activity Updating -status 'Progress->' -percentcomplete $i -currentOperation OuterLoop; ` +{write-progress -activity Updating -status 'Progress->' -PercentComplete $i -currentOperation OuterLoop; ` for($j = 1; $j -lt 101; $j++ ) -{write-progress -id 1 -activity Updating -status 'Progress' -percentcomplete $j -currentOperation InnerLoop} } +{write-progress -id 1 -activity Updating -status 'Progress' -PercentComplete $j -currentOperation InnerLoop} } Updating Progress -> @@ -58,7 +58,7 @@ Without the Id parameter, the progress bars would be superimposed on each other PS C:\> $events = get-eventlog -logname system PS C:\> $events | foreach-object -begin {clear-host;$i=0;$out=""} ` -process {if($_.message -like "*bios*") {$out=$out + $_.Message}; $i = $i+1; -write-progress -activity "Searching Events" -status "Progress:" -percentcomplete ($i/$events.count*100)} ` +write-progress -activity "Searching Events" -status "Progress:" -PercentComplete ($i/$events.count*100)} ` -end {$out} ``` @@ -86,7 +86,7 @@ This text describes the activity whose progress is being reported. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 1 @@ -102,7 +102,7 @@ If this parameter is omitted, Write-Progress displays progress information. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -118,7 +118,7 @@ This text describes the operation that is currently taking place. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -135,7 +135,7 @@ If the progress bars do not have different IDs, they are superimposed instead of ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 3 @@ -151,7 +151,7 @@ Use the value -1 if the current activity has no parent activity. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -167,7 +167,7 @@ Use the value -1 if the percentage complete is unknown or not applicable. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -183,7 +183,7 @@ Use the value -1 if the number of seconds remaining is unknown or not applicable ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -198,7 +198,7 @@ Identifies the source of the record. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -214,7 +214,7 @@ This text describes current state of the activity. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 2 diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Write-Progress.md b/reference/4.0/Microsoft.PowerShell.Utility/Write-Progress.md index 67667aec29ad..24503f7aff94 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Write-Progress.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Write-Progress.md @@ -30,7 +30,7 @@ You can select the indicators that the bar reflects and the text that appears ab ### Example 1 ``` PS C:\> for ($i = 1; $i -le 100; $i++ ) -{write-progress -activity "Search in Progress" -status "$i% Complete:" -percentcomplete $i;} +{write-progress -activity "Search in Progress" -status "$i% Complete:" -PercentComplete $i;} ``` This command displays the progress of a For loop that counts from 1 to 100. @@ -39,9 +39,9 @@ The Write-Progress command includes a status bar heading ("activity"), a status ### Example 2 ``` PS C:\> for($i = 1; $i -lt 101; $i++ ) -{write-progress -activity Updating -status 'Progress->' -percentcomplete $i -currentOperation OuterLoop; ` +{write-progress -activity Updating -status 'Progress->' -PercentComplete $i -currentOperation OuterLoop; ` for($j = 1; $j -lt 101; $j++ ) -{write-progress -id 1 -activity Updating -status 'Progress' -percentcomplete $j -currentOperation InnerLoop} } +{write-progress -id 1 -activity Updating -status 'Progress' -PercentComplete $j -currentOperation InnerLoop} } Updating Progress -> @@ -63,7 +63,7 @@ Without the Id parameter, the progress bars would be superimposed on each other PS C:\> $events = get-eventlog -logname system PS C:\> $events | foreach-object -begin {clear-host;$i=0;$out=""} ` -process {if($_.message -like "*bios*") {$out=$out + $_.Message}; $i = $i+1; -write-progress -activity "Searching Events" -status "Progress:" -percentcomplete ($i/$events.count*100)} ` +write-progress -activity "Searching Events" -status "Progress:" -PercentComplete ($i/$events.count*100)} ` -end {$out} ``` @@ -92,7 +92,7 @@ This text describes the activity whose progress is being reported. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 1 @@ -108,7 +108,7 @@ If this parameter is omitted, Write-Progress displays progress information. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -124,7 +124,7 @@ This text describes the operation that is currently taking place. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -141,7 +141,7 @@ If the progress bars do not have different IDs, they are superimposed instead of ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 3 @@ -157,7 +157,7 @@ Use the value -1 if the current activity has no parent activity. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -173,7 +173,7 @@ Use the value -1 if the percentage complete is unknown or not applicable. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -189,7 +189,7 @@ Use the value -1 if the number of seconds remaining is unknown or not applicable ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -204,7 +204,7 @@ Identifies the source of the record. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -220,7 +220,7 @@ This text describes current state of the activity. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 2 diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Write-Progress.md b/reference/5.0/Microsoft.PowerShell.Utility/Write-Progress.md index 9817cf3c8f1b..19c02b36752e 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Write-Progress.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Write-Progress.md @@ -41,14 +41,14 @@ The **Write-Progress** command includes a status bar heading ("activity"), a sta PS C:\> for($I = 1; $I -lt 101; $I++ ) {Write-Progress -Activity Updating -Status 'Progress->' -PercentComplete $I -CurrentOperation OuterLoop; ` PS C:\> for($j = 1; $j -lt 101; $j++ ) -{Write-Progress -Id 1 -Activity Updating -Status 'Progress' - PercentComplete $j -CurrentOperation InnerLoop} } +{Write-Progress -Id 1 -Activity Updating -Status 'Progress' -PercentComplete $j -CurrentOperation InnerLoop} } Updating Progress -> - [ooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo] + [ooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo] OutsideLoop Updating Progress - [oooooooooooooooooo ] + [oooooooooooooooooo ] InnerLoop ``` @@ -91,7 +91,7 @@ This text describes the activity whose progress is being reported. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 0 @@ -107,7 +107,7 @@ If this parameter is omitted, **Write-Progress** displays progress information. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -123,7 +123,7 @@ This text describes the operation that is currently taking place. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -140,7 +140,7 @@ If the progress bars do not have different IDs, they are superimposed instead of ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 2 @@ -156,7 +156,7 @@ Use the value -1 if the current activity has no parent activity. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -172,7 +172,7 @@ Use the value -1 if the percentage complete is unknown or not applicable. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -188,7 +188,7 @@ Use the value -1 if the number of seconds remaining is unknown or not applicable ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -203,7 +203,7 @@ Specifies the source of the record. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -219,7 +219,7 @@ This text describes current state of the activity. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 1 diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Write-Progress.md b/reference/5.1/Microsoft.PowerShell.Utility/Write-Progress.md index 0591cc71b089..2d2fd97ef740 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Write-Progress.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Write-Progress.md @@ -44,11 +44,11 @@ PS C:\> for($j = 1; $j -lt 101; $j++ ) {Write-Progress -Id 1 -Activity Updating -Status 'Progress' -PercentComplete $j -CurrentOperation InnerLoop} } Updating Progress -> - [ooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo] + [ooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo] OutsideLoop Updating Progress - [oooooooooooooooooo ] + [oooooooooooooooooo ] InnerLoop ``` @@ -91,7 +91,7 @@ This text describes the activity whose progress is being reported. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 0 @@ -107,7 +107,7 @@ If this parameter is omitted, Write-Progress displays progress information. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -123,7 +123,7 @@ This text describes the operation that is currently taking place. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -140,7 +140,7 @@ If the progress bars do not have different IDs, they are superimposed instead of ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 2 @@ -156,7 +156,7 @@ Use the value -1 if the current activity has no parent activity. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -172,7 +172,7 @@ Use the value -1 if the percentage complete is unknown or not applicable. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -188,7 +188,7 @@ Use the value -1 if the number of seconds remaining is unknown or not applicable ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -203,7 +203,7 @@ Specifies the source of the record. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -219,7 +219,7 @@ This text describes current state of the activity. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 1 diff --git a/reference/6/Microsoft.PowerShell.Utility/Write-Progress.md b/reference/6/Microsoft.PowerShell.Utility/Write-Progress.md index 95c277f2d325..d42ee3bfe042 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Write-Progress.md +++ b/reference/6/Microsoft.PowerShell.Utility/Write-Progress.md @@ -41,14 +41,14 @@ The **Write-Progress** command includes a status bar heading ("activity"), a sta PS C:\> for($I = 1; $I -lt 101; $I++ ) {Write-Progress -Activity Updating -Status 'Progress->' -PercentComplete $I -CurrentOperation OuterLoop; ` PS C:\> for($j = 1; $j -lt 101; $j++ ) -{Write-Progress -Id 1 -Activity Updating -Status 'Progress' - PercentComplete $j -CurrentOperation InnerLoop} } +{Write-Progress -Id 1 -Activity Updating -Status 'Progress' -PercentComplete $j -CurrentOperation InnerLoop} } Updating Progress -> - [ooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo] + [ooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo] OutsideLoop Updating Progress - [oooooooooooooooooo ] + [oooooooooooooooooo ] InnerLoop ``` @@ -91,7 +91,7 @@ This text describes the activity whose progress is being reported. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 1 @@ -107,7 +107,7 @@ If this parameter is omitted, Write-Progress displays progress information. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -123,7 +123,7 @@ This text describes the operation that is currently taking place. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -140,7 +140,7 @@ If the progress bars do not have different IDs, they are superimposed instead of ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 3 @@ -183,7 +183,7 @@ Use the value -1 if the current activity has no parent activity. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -199,7 +199,7 @@ Use the value -1 if the percentage complete is unknown or not applicable. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -215,7 +215,7 @@ Use the value -1 if the number of seconds remaining is unknown or not applicable ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -230,7 +230,7 @@ Specifies the source of the record. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -246,7 +246,7 @@ This text describes current state of the activity. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 2 From b04197f509e8a44a97455bd6d450c1bec14f1772 Mon Sep 17 00:00:00 2001 From: Ebru Cucen Date: Mon, 13 Nov 2017 17:13:25 +0000 Subject: [PATCH 017/188] Formatting, example fix for Body parameter (#1847) 1. Replaced variable names with PascalCase convention and for consistency 2. Removed directory information [c:\] in the examples 3. Put powershell keyword for formatting examples 4. Replaced Invoke-RestMethod with Invoke-WebRequest in the Body example, added method Post 5. Removed InformationAction and InformationVariable parameters, which were mistakenly a copy of Body, included already in CommonVariables part --- .../Invoke-WebRequest.md | 158 ++++++------------ 1 file changed, 50 insertions(+), 108 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Utility/Invoke-WebRequest.md b/reference/6/Microsoft.PowerShell.Utility/Invoke-WebRequest.md index 2eb0ca48e765..3035e1d0ac8e 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Invoke-WebRequest.md +++ b/reference/6/Microsoft.PowerShell.Utility/Invoke-WebRequest.md @@ -35,9 +35,9 @@ This cmdlet was introduced in Windows PowerShell 3.0. ## EXAMPLES ### Example 1: Send a web request -``` -PS C:\> $R = Invoke-WebRequest -URI http://www.bing.com?q=how+many+feet+in+a+mile -PS C:\> $R.AllElements | where {$_.innerhtml -like "*=*"} | Sort { $_.InnerHtml.Length } | Select InnerText -First 5 +```powershell +$Response = Invoke-WebRequest -URI http://www.bing.com?q=how+many+feet+in+a+mile +$Response.AllElements | where {$_.innerhtml -like "*=*"} | Sort { $_.InnerHtml.Length } | Select InnerText -First 5 innerText---------1 =5280 feet1 mile ``` @@ -49,41 +49,41 @@ The second command gets the InnerHtml property when it includes an equal sign, s Sorting by the shortest HTML value often helps you find the most specific element that matches that text. ### Example 2: Use a stateful web service -``` -# The first command uses the **Invoke-WebRequest** cmdlet to send a sign-in request. The command specifies a value of "FB" for the value of the *SessionVariable* parameter, and saves the result in the $R variable.When the command completes, the $R variable contains an **HtmlWebResponseObject** and the $FB variable contains a **WebRequestSession** object. -PS C:\> $R=Invoke-WebRequest http://www.facebook.com/login.php -SessionVariable fb +```powershell +# The first command uses the **Invoke-WebRequest** cmdlet to send a sign-in request. The command specifies a value of "FB" for the value of the *SessionVariable* parameter, and saves the result in the $Response variable.When the command completes, the $Response variable contains an **HtmlWebResponseObject** and the $FB variable contains a **WebRequestSession** object. +$Response=Invoke-WebRequest http://www.facebook.com/login.php -SessionVariable FB # The second command shows the **WebRequestSession** object in the $FB variable. -PS C:\> $FB +$FB -# The third command gets the first form in the **Forms** property of the HTTP response object in the $R variable, and saves it in the $Form variable. -PS C:\> $Form = $R.Forms[0] +# The third command gets the first form in the **Forms** property of the HTTP response object in the $Response variable, and saves it in the $Form variable. +$Form = $Response.Forms[0] # The fourth command pipes the properties of the form in the $Form variable into a list by using the Format-List cmdlet. -PS C:\> $Form | Format-List +$Form | Format-List # The fifth command displays the keys and values in the hash table (dictionary) object in the Fields property of the form. -PS C:\> $Form.fields +$Form.fields # The sixth and seventh commands populate the values of the email and pass keys of the hash table in the **Fields** property of the form. You can replace the email and password with values that you want to use. -PS C:\> $Form.Fields["email"]="User01@Fabrikam.com" +$Form.Fields["email"]="User01@Fabrikam.com" $Form.Fields["pass"]="P@ssw0rd" -# The eighth command uses the **Invoke-WebRequest** cmdlet to sign into the Facebook web service.The value of the *Uri* parameter is the value of the **Action** property of the form. The **WebRequestSession** object in the $FB variable (the session variable specified in the first command) is now the value of the *WebSession* parameter. The value of the *Body* parameter is the hash table in the Fields property of the form and the value of the *Method* parameter is POST. The command saves the output in the $R variable. -PS C:\> $R=Invoke-WebRequest -Uri ("https://www.facebook.com" + $Form.Action) -WebSession $FB -Method POST -Body $Form.Fields +# The eighth command uses the **Invoke-WebRequest** cmdlet to sign into the Facebook web service.The value of the *Uri* parameter is the value of the **Action** property of the form. The **WebRequestSession** object in the $FB variable (the session variable specified in the first command) is now the value of the *WebSession* parameter. The value of the *Body* parameter is the hash table in the Fields property of the form and the value of the *Method* parameter is POST. The command saves the output in the $Response variable. +$Response=Invoke-WebRequest -Uri ("https://www.facebook.com" + $Form.Action) -WebSession $FB -Method POST -Body $Form.Fields # The full script, then, is as follows. -# Sends a sign-in request by running the Invoke-WebRequest cmdlet. The command specifies a value of "fb" for the SessionVariable parameter, and saves the results in the $R variable. +# Sends a sign-in request by running the Invoke-WebRequest cmdlet. The command specifies a value of "FB" for the SessionVariable parameter, and saves the results in the $Response variable. -PS C:\> $R=Invoke-WebRequest http://www.facebook.com/login.php -SessionVariable fb +$Response=Invoke-WebRequest http://www.facebook.com/login.php -SessionVariable FB # Use the session variable that you created in Example 1. Output displays values for Headers, Cookies, Credentials, etc. $FB -# Gets the first form in the Forms property of the HTTP response object in the $R variable, and saves it in the $Form variable. +# Gets the first form in the Forms property of the HTTP response object in the $Response variable, and saves it in the $Form variable. -$Form = $R.Forms[0] +$Form = $Response.Forms[0] # Pipes the form properties that are stored in the $Forms variable into the Format-List cmdlet, to display those properties in a list. @@ -100,17 +100,17 @@ $Form.Fields["pass"] = "P@ssw0rd" # The final command uses the Invoke-WebRequest cmdlet to sign in to the Facebook web service. -$R=Invoke-WebRequest -Uri ("https://www.facebook.com" + $Form.Action) -WebSession $FB -Method POST -Body $Form.Fields +$Response=Invoke-WebRequest -Uri ("https://www.facebook.com" + $Form.Action) -WebSession $FB -Method POST -Body $Form.Fields -# When the command finishes, the **StatusDescription** property of the web response object in the $R variable indicates that the user is signed in successfully. -$R.StatusDescription +# When the command finishes, the **StatusDescription** property of the web response object in the $Response variable indicates that the user is signed in successfully. +$Response.StatusDescription ``` This example shows how to use the **Invoke-WebRequest** cmdlet with a stateful web service, such as Facebook. ### Example 3: Get links from a web page -``` -PS C:\> (Invoke-WebRequest -Uri "http://msdn.microsoft.com/en-us/library/aa973757(v=vs.85).aspx").Links.Href +```powershell +(Invoke-WebRequest -Uri "http://msdn.microsoft.com/en-us/library/aa973757(v=vs.85).aspx").Links.Href ``` This command gets the links in a web page. @@ -118,10 +118,10 @@ It uses the **Invoke-WebRequest** cmdlet to get the web page content. Then it users the **Links** property of the **HtmlWebResponseObject** that **Invoke-WebRequest** returns, and the Href property of each link. ### Example 4: Writes the response content to a file using the encoding defined in the requested page. -``` -PS C:\> $response = Invoke-WebRequest -Uri "http://msdn.microsoft.com/en-us/library/aa973757(v=vs.85).aspx" -PS C:\> $stream = [System.IO.StreamWriter]::new('.\msdnpage.html', $false, $response.Encoding) -PS C:\> try {$stream.Write($response.Content)} finally {$stream.Dispose()} +```powershell +$Response = Invoke-WebRequest -Uri "http://msdn.microsoft.com/en-us/library/aa973757(v=vs.85).aspx" +$Stream = [System.IO.StreamWriter]::new('.\msdnpage.html', $false, $Response.Encoding) +try {$Stream.Write($response.Content)} finally {$Stream.Dispose()} ``` This command uses the **Invoke-WebRequest** cmdlet to retrieve the web page content of an msdn page. @@ -136,22 +136,22 @@ Note that the Encoding property will be null if the web request does not return ### Example 4: Submit a multipart/form-data file ```powershell -$filePath = 'c:\document.txt' -$fieldName = 'document' -$contentType = 'text/plain' +$FilePath = 'c:\document.txt' +$FieldName = 'document' +$ContentType = 'text/plain' -$fileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open) -$fileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data') -$fileHeader.Name = $fieldName -$fileHeader.FileName = Split-Path -leaf $filePath -$fileContent = [System.Net.Http.StreamContent]::new($fileStream) -$fileContent.Headers.ContentDisposition = $fileHeader -$fileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse($contentType) +$FileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open) +$FileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data') +$FileHeader.Name = $FieldName +$FileHeader.FileName = Split-Path -leaf $FilePath +$FileContent = [System.Net.Http.StreamContent]::new($FileStream) +$FileContent.Headers.ContentDisposition = $FileHeader +$FileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse($ContentType) -$multipartContent = [System.Net.Http.MultipartFormDataContent]::new() -$multipartContent.Add($fileContent) +$MultipartContent = [System.Net.Http.MultipartFormDataContent]::new() +$MultipartContent.Add($FileContent) -$response = Invoke-WebRequest -Body $multipartContent -Method 'POST' -uri 'https://api.contoso.com/upload' +$Response = Invoke-WebRequest -Body $MultipartContent -Method 'POST' -Uri 'https://api.contoso.com/upload' ``` This example uses the **Invoke-WebRequest** cmdlet upload a file as a `multipart/form-data` submission. The file `c:\document.txt` will be submitted as the form field `document` with the `Content-Type` of `text/plain`. @@ -218,16 +218,17 @@ For example: ```powershell -$R = Invoke-WebRequest http://website.com/login.aspx -$R.Forms[0].Name = "MyName" -$R.Forms[0].Password = "MyPassword" -Invoke-RestMethod http://website.com/service.aspx -Body $R +$Response = Invoke-WebRequest -Uri http://website.com/login.aspx +$Response.Forms[0].Name = "MyName" +$Response.Forms[0].Password = "MyPassword" ``` +```powershell +Invoke-WebRequest -Uri http://website.com/service.aspx -Body $Response -Method POST +``` or - ```powershell -Invoke-RestMethod http://website.com/service.aspx -Body $R.Forms[0] +Invoke-WebRequest -Uri http://website.com/service.aspx -Body $Response.Forms[0] -Method POST ``` The *Body* parameter may also accept a `System.Net.Http.MultipartFormDataContent` object. This will facilitate `multipart/form-data` requests. When a `MultipartFormDataContent` object is supplied for *Body*, any Content related headers supplied to the *ContentType*, *Headers*, or *WebSession* parameters will be overridden by the Content headers of the `MultipartFormDataContent` object. @@ -413,66 +414,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -The Body parameter can be used to specify a list of query parameters or specify the content of the response. - -When the input is a GET request and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other GET requests, the body is set as the value of the request body in the standard name=value format. - -When the body is a form, or it is the output of an Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields. - -For example: - -$r = Invoke-WebRequest http://website.com/login.aspx -$r.Forms[0].Name = "MyName" -$r.Forms[0].Password = "MyPassword" -Invoke-RestMethod http://website.com/service.aspx -Body $r - -- or - - -Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0] - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -The Body parameter can be used to specify a list of query parameters or specify the content of the response. - -When the input is a GET request and the body is an IDictionary (typically, a hash table), the body is added to the URI as query parameters. For other GET requests, the body is set as the value of the request body in the standard name=value format. - -When the body is a form, or it is the output of an Invoke-WebRequest call, Windows PowerShell sets the request content to the form fields. - -For example: - -$r = Invoke-WebRequest http://website.com/login.aspx -$r.Forms[0].Name = "MyName" -$r.Forms[0].Password = "MyPassword" -Invoke-RestMethod http://website.com/service.aspx -Body $r - -- or - - -Invoke-RestMethod http://website.com/service.aspx -Body $r.Forms[0] - -```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ### -MaximumRedirection Specifies how many times Windows PowerShell redirects a connection to an alternate Uniform Resource Identifier (URI) before the connection fails. @@ -817,8 +758,9 @@ To test a website with the standard user agent string that is used by most Inter For example, the following command uses the user agent string for Internet Explorer - -PS C:\> Invoke-WebRequest -Uri http://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer) +```powershell +Invoke-WebRequest -Uri http://website.com/ -UserAgent ([Microsoft.PowerShell.Commands.PSUserAgent]::InternetExplorer) +``` ```yaml Type: String From b6b156a4585aeb216791576d1b0c7294a77ef166 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 13 Nov 2017 11:53:10 -0800 Subject: [PATCH 018/188] fixing style consistency across articles --- .../Add-Content.md | 31 +-- .../Set-Content.md | 12 +- .../Microsoft.PowerShell.Security/Set-Acl.md | 75 +++---- .../Format-Custom.md | 74 ++++--- .../Format-Table.md | 197 ++++++++++-------- .../Format-Wide.md | 129 +++++++----- .../Microsoft.PowerShell.Utility/Out-File.md | 31 ++- .../Write-Host.md | 6 +- .../Write-Progress.md | 104 ++++----- .../Add-Content.md | 2 +- .../Set-Content.md | 12 +- .../Microsoft.PowerShell.Security/Set-Acl.md | 67 +++--- .../Format-Custom.md | 89 ++++---- .../Format-Table.md | 184 ++++++++-------- .../Format-Wide.md | 122 ++++++----- .../Microsoft.PowerShell.Utility/Out-File.md | 31 ++- .../Write-Host.md | 6 +- .../Write-Progress.md | 97 ++++----- .../Add-Content.md | 2 +- .../Set-Content.md | 10 +- .../Microsoft.PowerShell.Security/Set-Acl.md | 67 +++--- .../Format-Custom.md | 114 +++++----- .../Format-Table.md | 132 ++++++------ .../Format-Wide.md | 120 +++++------ .../Microsoft.PowerShell.Utility/Out-File.md | 34 +-- .../Write-Host.md | 6 +- .../Write-Progress.md | 64 +++--- .../Add-Content.md | 2 +- .../Set-Content.md | 10 +- .../Microsoft.PowerShell.Security/Set-Acl.md | 65 +++--- .../Format-Custom.md | 116 ++++++----- .../Format-Table.md | 134 ++++++------ .../Format-Wide.md | 120 +++++------ .../Microsoft.PowerShell.Utility/Out-File.md | 28 +-- .../Write-Host.md | 6 +- .../Write-Progress.md | 68 +++--- .../Add-Content.md | 13 +- .../Set-Content.md | 10 +- .../Microsoft.PowerShell.Security/Set-Acl.md | 66 +++--- .../Format-Custom.md | 146 ++++++------- .../Format-Table.md | 165 +++++++-------- .../Format-Wide.md | 148 ++++++------- .../Microsoft.PowerShell.Utility/Out-File.md | 61 ++---- .../Write-Host.md | 36 +--- .../Write-Progress.md | 89 +++----- 45 files changed, 1531 insertions(+), 1570 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Management/Add-Content.md b/reference/3.0/Microsoft.PowerShell.Management/Add-Content.md index 22a32c1345c0..ed1b89be2772 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Add-Content.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Add-Content.md @@ -39,18 +39,18 @@ You can specify the content by typing the content in the command or by specifyin ## EXAMPLES -### Example 1 +### Example 1: Add a string to all text files with an exception ```powershell -PS C:\> add-content -path *.txt -exclude help* -value "END" +PS C:\> Add-Content -Path "*.txt" -Exclude "help*" -Value "END" ``` This command adds "END" to all text files in the current directory, except for those with file names that begin with "help". -### Example 2 +### Example 2: Add a date to the end of the specified files -``` -PS C:\> add-content -Path file1.log, file2.log -Value (get-date) -passthru +```powershell +PS C:\> Add-Content -Path "file1.log", "file2.log" -Value (Get-Date) -PassThru ``` This command adds the date to the end of the File1.log and File2.log files and then displays the date at the command line. @@ -58,10 +58,10 @@ The command uses the Get-Date cmdlet to get the date, and it uses the Value para The PassThru parameter passes an object representing the added content through the pipeline. Because there is no other cmdlet to receive the passed object, it is displayed at the command line. -### Example 3 +### Example 3: Add the contents of a specified file to another file ```powershell -PS C:\> add-content -path monthly.txt -value (get-content c:\rec1\weekly.txt) +PS C:\> Add-Content -Path "monthly.txt" -Value (Get-Content "c:\rec1\weekly.txt") ``` This command adds the contents of the Weekly.txt file to the end of the Monthly.txt file. @@ -69,12 +69,12 @@ It uses the Get-Content cmdlet to get the contents of the Weekly.txt file, and i The parentheses ensure that the Get-Content command is complete before the Add-Content command begins. You can also copy the content of Weekly.txt to a variable, such as $w, and then use the Value parameter to pass the variable to Add-Content. -In that case, the command would be "add-content -path monthly.txt -value $w". +In that case, the command would be "Add-Content -Path monthly.txt -Value $w". -### Example 4 +### Example 4: Create a new directory and file and copy content ```powershell -PS C:\> add-content -value (get-content test.log) -path C:\tests\test134\logs\test134.log +PS C:\> Add-Content -Value (Get-Content "test.log") -Path "C:\tests\test134\logs\test134.log" ``` This command creates a new directory and file and copies the content of an existing file to the newly created file. @@ -140,8 +140,11 @@ Accept wildcard characters: False ### -Stream -Adds the content to the specified alternate data stream. If the stream does not yet, exist, Add-Content creates it. -Enter the stream name. Wildcards are not supported. +Adds the content to the specified alternate data stream. +If the stream does not yet, exist, Add-Content creates it. +Enter the stream name. +Wildcards are not supported. + Stream is a dynamic parameter that the FileSystem provider adds to the Add-Content cmdlet. This parameter works only in file system drives. This parameter is introduced in PowerShell 3.0. @@ -320,7 +323,7 @@ Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -369,7 +372,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.Object -You can pipe the objects to be added (the Value) to Add-Content. +You can pipe the objects to be added by Add-Content. ## OUTPUTS diff --git a/reference/3.0/Microsoft.PowerShell.Management/Set-Content.md b/reference/3.0/Microsoft.PowerShell.Management/Set-Content.md index ea273cba13a3..f0d83c19e88b 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Set-Content.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Set-Content.md @@ -192,10 +192,10 @@ Accept wildcard characters: True ### -Force -Allows the cmdlet to set the contents of a file, even if the file is read-only. +Forces the cmdlet to set the contents of a file, even if the file is read-only. Implementation varies from provider to provider. For more information, see about_Providers. -Even using the Force parameter, the cmdlet cannot override security restrictions. +Using the Force parameter does not override security restrictions. ```yaml Type: SwitchParameter @@ -288,10 +288,10 @@ Specifies an alternative data stream for content. If the stream does not exist, this cmdlet creates it. Wildcard characters are not supported. -Stream is a dynamic parameter that the FileSystem provider adds to **Set-Content**. +Stream is a dynamic parameter that the FileSystem provider adds to `Set-Content`. This parameter works only in file system drives. -You can use the **Set-Content** cmdlet to change the content of the Zone.Identifier alternate data stream. +You can use the `Set-Content` cmdlet to change the content of the Zone.Identifier alternate data stream. However, we do not recommend this as a way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. @@ -365,7 +365,7 @@ Accept wildcard characters: False 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). +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters). ## INPUTS @@ -382,7 +382,7 @@ Otherwise, this cmdlet does not generate any output. ## NOTES -You can also refer to Set-Content by its built-in alias, "sc". For more information, see about_Aliases. +You can also refer to Set-Content by its built-in alias, "sc". For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). Set-Content is designed for string processing. If you pipe non-string objects to Set-Content, it converts the object to a string before writing it. diff --git a/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md b/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md index a4e0470c14df..d5135545bee2 100644 --- a/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md +++ b/reference/3.0/Microsoft.PowerShell.Security/Set-Acl.md @@ -34,18 +34,19 @@ Set-Acl -LiteralPath [-AclObject] [[-CentralAccessPolicy] $DogACL = Get-Acl C:\Dog.txt -PS C:\> Set-Acl -Path C:\Cat.txt -AclObject $DogACL +PS C:\> $DogACL = Get-Acl -Path "C:\Dog.txt" +PS C:\> 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. @@ -54,26 +55,28 @@ When the commands complete, the security descriptors of the Dog.txt and Cat.txt The first command uses the Get-Acl cmdlet to get the security descriptor of the Dog.txt file. The assignment operator (=) stores the security descriptor in the value of the $DogACL variable. -The second command uses **Set-Acl** to change the values in the ACL of Cat.txt to the values in $DogACL. +The second command uses `Set-Acl` to change the values in the ACL of Cat.txt to the values in $DogACL. 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 + +### Example 2: Use the pipeline operator to pass a descriptor ``` -PS C:\> Get-Acl C:\Dog.txt | Set-Acl -Path C:\Cat.txt +PS C:\> 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. +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. The first command uses the **Get-Acl** cmdlet to get the security descriptor of the Dog.txt file. -The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the **Set-Acl** cmdlet. +The pipeline operator (|) passes an object that represents the Dog.txt security descriptor to the `Set-Acl` cmdlet. -The second command uses **Set-Acl** to apply the security descriptor of Dog.txt to Cat.txt. +The second command uses `Set-Acl` to apply the security descriptor of Dog.txt to Cat.txt. When the command completes, the ACLs of the Dog.txt and Cat.txt files are identical. -### Example 3 + +### Example 3: Apply a security descriptor to multiple files ``` PS C:\> $NewAcl = Get-Acl File0.txt -PS C:\> Get-ChildItem c:\temp -Recurse -Include *.txt -Force | Set-Acl -AclObject $NewAcl +PS C:\> 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. @@ -86,24 +89,25 @@ The **Include** parameter limits the files retrieved to those with the ".txt" fi The **Force** parameter gets hidden files, which would otherwise be excluded. (You cannot use "c:\temp\*.txt", because the **Recurse** parameter works on directories, not on files.) -The pipeline operator (|) sends the objects representing the retrieved files to the **Set-Acl** cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in the pipeline. +The pipeline operator (|) sends the objects representing the retrieved files to the `Set-Acl` cmdlet, which applies the security descriptor in the **AclObject** parameter to all of the files in the pipeline. -In practice, it is best to use the **Whatif** parameter with all **Set-Acl** commands that can affect more than one item. +In practice, it is best to use the **Whatif** parameter with all `Set-Acl` commands that can affect more than one item. In this case, the second command in the pipeline would be "`Set-Acl -AclObject $NewAcl -WhatIf`". This command lists the files that would be affected by the command. After reviewing the result, you can run the command again without the **Whatif** parameter. + ## 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. +`Set-Acl` changes the ACL of item specified by the **Path** or **InputObject** parameter to match the values in the specified security object. You can save the output of a Get-Acl command in a variable and then use the **AclObject** parameter to pass the variable, or type a Get-Acl command. ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 2 @@ -121,7 +125,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -139,7 +143,7 @@ Filters are more efficient than other parameters, because the provider applies t ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -157,7 +161,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -167,13 +171,13 @@ Accept wildcard characters: True ``` ### -Passthru -Returns an object that represents the security descriptor that was changed. +Returns an object that represents the security descriptor that was changed. By default, this cmdlet does not generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -187,12 +191,12 @@ 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. -If you pass a security object to **Set-Acl** (either by using the **AclObject** or **SecurityDescriptor** parameters or by passing a security object from Get-Acl to **Set-Acl**), and you omit the **Path** parameter (name and value), **Set-Acl** uses the path that is included in the security object. +If you pass a security object to `Set-Acl` (either by using the **AclObject** or **SecurityDescriptor** parameters or by passing a security object from Get-Acl to `Set-Acl`), and you omit the **Path** parameter (name and value), `Set-Acl` uses the path that is included in the security object. ```yaml Type: String[] Parameter Sets: ByPath -Aliases: +Aliases: Required: True Position: 1 @@ -213,7 +217,7 @@ This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: String Parameter Sets: ByPath, ByLiteralPath -Aliases: +Aliases: Required: False Position: 3 @@ -233,7 +237,7 @@ This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: SwitchParameter Parameter Sets: ByPath, ByLiteralPath -Aliases: +Aliases: Required: False Position: Named @@ -246,7 +250,7 @@ Accept wildcard characters: False Changes the security descriptor of the specified object. Enter a variable that contains the object or a command that gets the object. -You cannot pipe the object to be changed to **Set-Acl**. +You cannot pipe the object to be changed to `Set-Acl`. Instead, use the **InputObject** parameter explicitly in the command. This parameter is introduced in Windows PowerShell 3.0. @@ -254,7 +258,7 @@ This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: PSObject Parameter Sets: ByInputObject -Aliases: +Aliases: Required: True Position: 1 @@ -334,22 +338,23 @@ 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**. +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. +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. + ## NOTES -* The **Set-Acl** cmdlet is supported by the Windows PowerShell file system and registry providers. As such, you can use it to change the security descriptors of files, directories, and registry keys. -* + The `Set-Acl` cmdlet is supported by the Windows PowerShell file system and registry providers. As such, you can use it to change the security descriptors of files, directories, and registry keys. + ## RELATED LINKS [Get-Acl](Get-Acl.md) - - diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Format-Custom.md b/reference/3.0/Microsoft.PowerShell.Utility/Format-Custom.md index 02dd4734a64e..34356d29d590 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Format-Custom.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Format-Custom.md @@ -9,8 +9,10 @@ title: Format-Custom --- # Format-Custom + ## SYNOPSIS Uses a customized view to format the output. + ## SYNTAX ``` @@ -19,25 +21,28 @@ Format-Custom [[-Property] ] [-Depth ] [-GroupBy ] [-Vi ``` ## DESCRIPTION -The Format-Custom cmdlet formats the output of a command as defined in an alternate view. -Format-Custom is designed to display views that are not just tables or just lists. +The `Format-Custom` cmdlet formats the output of a command as defined in an alternate view. +`Format-Custom` is designed to display views that are not just tables or just lists. You can use the views defined in the *format.PS1XML files in the Windows PowerShell directory, or you can create your own views in new PS1XML files and use the Update-FormatData cmdlet to add them to Windows PowerShell. + ## EXAMPLES ### Example 1 -``` -PS C:\> get-command start-transcript | format-custom -view MyView +```powershell +PS C:\> Get-Command Start-Transcript | Format-Custom -View MyView ``` -This command formats information about the Start-Transcript cmdlet in the format defined by the MyView view, a custom view created by the user. +This command formats information about the `Start-Transcript` cmdlet in the format defined by the MyView view, a custom view created by the user. To run this command successfully, you must first create a new PS1XML file, define the MyView view, and then use the Update-FormatData command to add the PS1XML file to Windows PowerShell. + ### Example 2 -``` -PS C:\> get-process Winlogon | format-custom +```powershell +PS C:\> Get-Process Winlogon | Format-Custom ``` This command formats information about the Winlogon process in an alternate customized view. -Because the command does not use the View parameter, Format-Custom uses a default custom view to format the data. +Because the command does not use the **View** parameter, `Format-Custom` uses a default custom view to format the data. + ## PARAMETERS ### -Depth @@ -46,7 +51,7 @@ Specifies the number of columns in the display. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -58,17 +63,20 @@ Accept wildcard characters: False ### -DisplayError Displays errors at the command line. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Custom command, and the expressions do not appear to be working. -The following shows an example of the results of adding the DisplayError parameter with an expression. +The following shows an example of the results of adding the **DisplayError** parameter with an expression. + +```powershell +PS \> Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -DisplayError -PS \> Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday #ERR +``` ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -80,7 +88,7 @@ Accept wildcard characters: False ### -Expand Formats the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. -The default value is EnumOnly. +The default value is **EnumOnly**. Valid values are: @@ -91,7 +99,7 @@ Valid values are: ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -108,7 +116,7 @@ By default, when an error object is written to the error or display streams, onl ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -132,7 +140,7 @@ Valid keys are: ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -148,7 +156,7 @@ Enter a variable that contains the objects or type a command or expression that ```yaml Type: PSObject Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -175,7 +183,7 @@ Valid keys are: ```yaml Type: Object[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 1 @@ -187,8 +195,9 @@ Accept wildcard characters: False ### -ShowError Sends errors through the pipeline. This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Custom command, and the expressions do not appear to be working. -The following shows an example of the results of adding the ShowError parameter with an expression. +The following shows an example of the results of adding the **ShowError** parameter with an expression. +```powershell PS \> Get-Date | Format-Custom DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ @@ -197,11 +206,12 @@ Wednesday Failed to evaluate expression " $_ / $null ". + CategoryInfo : InvalidArgument: (10/30/2013 2:28:07 PM:PSObject) \[\], RuntimeException + FullyQualifiedErrorId : mshExpressionError +``` ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -211,13 +221,13 @@ Accept wildcard characters: False ``` ### -View -Specifies the name of an alternate format or "view." If you omit this parameter, Format-Custom uses a default custom view. +Specifies the name of an alternate format or "view." If you omit this parameter, `Format-Custom` uses a default custom view. You cannot use the Property and View parameters in the same command. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -227,24 +237,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 ### System.Management.Automation.PSObject -You can pipe any object to Format-Custom + +You can pipe any object to Format-Custom. + ## OUTPUTS ### Microsoft.PowerShell.Commands.Internal.Format + Format-Custom returns the format objects that represent the display. + ## NOTES -* Format-Custom is designed to display views that are not just tables or just lists. To display an alternate table view, use Format-Table. To display an alternate list view, use Format-List. - You can also refer to Format-Custom by its built-in alias, "fc". -For more information, see about_Aliases. +Format-Custom is designed to display views that are not just tables or just lists. To display an alternate table view, use Format-Table. To display an alternate list view, use Format-List. + +You can also refer to `Format-Custom` by its built-in alias, "fc". +For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). - The GroupBy parameter assumes that the objects are sorted. -Before using Format-Custom to group the objects, use Sort-Object to sort them. +The **GroupBy** parameter assumes that the objects are sorted. +Before using `Format-Custom` to group the objects, use `Sort-Object` to sort them. -* ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Format-Table.md b/reference/3.0/Microsoft.PowerShell.Utility/Format-Table.md index c9542ce4b85f..90e3c095f97a 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Format-Table.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Format-Table.md @@ -9,38 +9,42 @@ title: Format-Table --- # Format-Table + ## SYNOPSIS Formats the output as a table. + ## SYNTAX -``` +```powershell Format-Table [-AutoSize] [-HideTableHeaders] [-Wrap] [[-Property] ] [-GroupBy ] [-View ] [-ShowError] [-DisplayError] [-Force] [-Expand ] [-InputObject ] [] ``` ## DESCRIPTION -The Format-Table cmdlet formats the output of a command as a table with the selected properties of the object in each column. -The object type determines the default layout and properties that are displayed in each column, but you can use the Property parameter to select the properties that you want to see. +The `Format-Table` cmdlet formats the output of a command as a table with the selected properties of the object in each column. +The object type determines the default layout and properties that are displayed in each column, but you can use the **Property** parameter to select the properties that you want to see. You can also use a hash table to add calculated properties to an object before displaying it and to specify the column headings in the table. -To add a calculated property, use the Property or GroupBy parameters. +To add a calculated property, use the **Property** or **GroupBy** parameter. + ## EXAMPLES -### Example 1 -``` -PS C:\> get-pssnapin | format-table -auto +### Example 1: Format PowerShell snap-ins +```powershell +PS C:\> Get-PSSnapin | Format-Table -Auto ``` This command formats information about Windows PowerShell snap-ins in a table. By default, they are formatted in a list. The Get-PSSnapin cmdlet gets objects representing the snap-ins. -The pipeline operator (|) passes the object to the Format-Table command. -Format-Table formats the objects in a table. -The Autosize parameter adjusts the column widths to minimize truncation. -### Example 2 -``` -PS C:\> get-process | sort-object -property basepriority | format-table -groupby basepriority -wrap +The pipeline operator (|) passes the object to the `Format-Table` command. +`Format-Table` formats the objects in a table. +The **Autosize** parameter adjusts the column widths to minimize truncation. + +### Example 2: Format processes by BasePriority +```powershell +PS C:\> Get-Process | Sort-Object -Property basepriority | Format-Table -GroupBy basepriority -Wrap ``` This command displays the processes on the computer in groups with the same base priority. @@ -48,117 +52,123 @@ This command displays the processes on the computer in groups with the same base The Get-Process cmdlet gets objects representing each process on the computer. The pipeline operator (|) passes the object to the Sort-Object cmdlet, which sorts the objects in order of their base priority. -Another pipeline operator passes the results to the Format-Table cmdlet. -The GroupBy parameter arranges the data about the processes into groups based on the value of their BasePriority property. -The Wrap parameter ensures that data is not truncated. -### Example 3 -``` -PS C:\> get-process | sort-object starttime | format-table -view starttime +Another pipeline operator passes the results to the `Format-Table` cmdlet. +The **GroupBy** parameter arranges the data about the processes into groups based on the value of their BasePriority property. +The **Wrap** parameter ensures that data is not truncated. + +### Example 3: Format processes by start date +```powershell +PS C:\> Get-Process | Sort-Object starttime | Format-Table -View starttime ``` This command displays information about the processes on the computer in group based on the start date of the process. It uses the Get-Process cmdlet to get objects representing the processes on the computer. The pipeline operator (|) sends the output of Get-Process to the Sort-Object cmdlet, which sorts it based on the StartTime property. -Another pipeline operator sends the sorted results to Format-Table. +Another pipeline operator sends the sorted results to `Format-Table`. -The View parameter is used to select the StartTime view that is defined in the DotNetTypes.format.ps1xml formatting file for System.Diagnostics.Process objects, such as those returned by Get-Process. +The **View** parameter is used to select the StartTime view that is defined in the DotNetTypes.format.ps1xml formatting file for **System.Diagnostics.Process** objects, such as those returned by `Get-Process`. This view converts the StartTime of the process to a short date and then groups the processes by start date. The DotNetTypes.format.ps1xml formatting file also contains a Priority view for processes, and you can create your own format.ps1xml files with customized views. -### Example 4 -``` -PS C:\> get-service | format-table -property Name, DependentServices + +### Example 4: Format services +```powershell +PS C:\> Get-Service | Format-Table -Property Name, DependentServices ``` This command displays all of the services on the computer in a table with two columns, Name and DependentServices. The command uses the Get-Service cmdlet to get all of the services on the computer. -The pipeline operator (|) sends the results to the Format-Table cmdlet, which formats the output in a table. -The Property parameter specifies the properties that appear in the table as columns. -The name of the Property parameter is optional, so you can omit it ("format-table name, dependentservices"). +The pipeline operator (|) sends the results to the `Format-Table` cmdlet, which formats the output in a table. +The **Property** parameter specifies the properties that appear in the table as columns. +The name of the **Property** parameter is optional, so you can omit it, for example `format-table name, dependentservices`. -Property and DependentServices are just two of the properties of service objects. -To view all of the properties, type "get-service | get-member". -### Example 5 -``` -PS C:\> get-process notepad | format-table ProcessName, @{Label="TotalRunningTime"; Expression={(get-date) - $_.StartTime}} +Name and DependentServices are just two of the properties of service objects. +To view all of the properties, type `get-service | get-member`. + +### Example 5: Format a process and calculate its running time +```powershell +PS C:\> Get-Process Notepad | Format-Table ProcessName, @{Label="TotalRunningTime"; Expression={(Get-Date) - $_.StartTime}} ``` This command shows how to use a calculated property in a table. The command displays a table with the process name and total running time of all Notepad processes on the local computer. The total running time is calculated by subtracting the start time of each process from the current time. -The command uses the Get-Process cmdlet to get all processes named "Notepad" on the local computer. -The pipeline operator (|) sends the results to Format-Table, which displays a table with two columns: ProcessName, a standard property of processes, and TotalRunningTime, a calculated property. +The command uses the Get-Process cmdlet to get all processes named Notepad on the local computer. +The pipeline operator (|) sends the results to `Format-Table`, which displays a table with two columns: ProcessName, a standard property of processes, and TotalRunningTime, a calculated property. The TotalRunningTime property is specified by a hash table with two keys, Label and Expression. The name of the property is assigned to the Label key. The calculation is assigned to the Expression key. -The expression gets the StartTime property of each process object and subtracts it from the result of a Get-Date command, which gets the current date (and time). -### Example 6 -``` -PS C:\> $processes = get-wmiobject -ComputerName Server01 win32_process -filter "name='notepad.exe'" -PS C:\> $processes | format-table ProcessName, @{ Label = "Total Running Time"; Expression={(get-date) - $_.ConvertToDateTime($_.CreationDate)}} +The expression gets the StartTime property of each process object and subtracts it from the result of a `Get-Date` command, which gets the current date and time. + +### Example 6: Format Notepad processes +```powershell +PS C:\> $Processes = Get-WmiObject -ComputerName "Server01" -Class win32_process -Filter "name='notepad.exe'" +PS C:\> $Processes | Format-Table ProcessName, @{ Label = "Total Running Time"; Expression={(Get-Date) - $_.ConvertToDateTime($_.CreationDate)}} ``` These commands are similar to the previous command, except that these commands use the Get-WmiObject cmdlet and the Win32_Process class to display information about Notepad processes on a remote computer. -The first command uses the Get-WmiObject cmdlet to get instances of the Windows Management Instrumentation (WMI) Win32_Process class that describes all of the processes on the Server01 computer that are named Notepad.exe. -The command stores the process information in the $processes variable. +The first command uses the `Get-WmiObject` cmdlet to get instances of the Windows Management Instrumentation (WMI) Win32_Process class that describes all of the processes on the Server01 computer that are named Notepad.exe. +The command stores the process information in the $Processes variable. -The second command uses a pipeline operator (|) to send the process information in the $processes variable to the Format-Table cmdlet, which displays the ProcessName of each process along with a new calculated property. +The second command uses a pipeline operator (|) to send the process information in the $Processes variable to the `Format-Table` cmdlet, which displays the ProcessName of each process along with a new calculated property. The command assigns the name of the new calculated property, Total Running Time, to the Label key. The script block that is assigned to the Expression key calculates how long the process has been running by subtracting the creation date of the process from the current date. The Get-Date cmdlet gets the current date. -The ConvertToDateTime method converts the CreationDate property of the Win32_Process object from a WMI CIM_DATETIME object to a Microsoft .NET Framework DateTime object that can be compared with the output of Get-Date. +The ConvertToDateTime method converts the CreationDate property of the Win32_Process object from a WMI CIM_DATETIME object to a Microsoft .NET Framework **DateTime** object that can be compared with the output of `Get-Date`. Then, the converted creation date is subtracted from the current date. The result is the value of Total Running Time. + ## PARAMETERS ### -AutoSize -Adjusts the column size and number of columns based on the width of the data. +Indicates that the cmdlet adjusts the column size and number of columns based on the width of the data. By default, the column size and number are determined by the view. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -DisplayError -Displays errors at the command line. -This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a Format-Table command, and the expressions do not appear to be working. +Indicates that the cmdlet displays errors at the command line. +This parameter is rarely used, but can be used as a debugging aid when you are formatting expressions in a `Format-Table` command, and the expressions do not appear to be working. The following shows an example of the results of adding the DisplayError parameter with an expression. +```powershell PS \> Get-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowError DayOfWeek $_ / $null --------- ------------ Wednesday #ERR +``` ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Expand -Formats the collection object, as well as the objects in the collection. +Specifies the format of the collection object, as well as the objects in the collection. This parameter is designed to format objects that support the ICollection (System.Collections) interface. The default value is EnumOnly. - -Valid values are: +The acceptable values for this parameter are: - EnumOnly: Displays the properties of the objects in the collection. - CoreOnly: Displays the properties of the collection object. @@ -167,40 +177,41 @@ Valid values are: ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: +Accepted values: CoreOnly, EnumOnly, Both Required: False Position: Named -Default value: EnumOnly +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Force -Directs the cmdlet to display all of the error information. -Use with the DisplayError or ShowError parameters. +Indicates that the cmdlet directs the cmdlet to display all of the error information. +Use with the **DisplayError** or **ShowError** parameter. By default, when an error object is written to the error or display streams, only some of the error information is displayed. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -GroupBy -Arranges sorted output in separate tables based on a property value. -For example, you can use GroupBy to list services in separate tables based on their status. +Specifies sorted output in separate tables based on a property value. +For example, you can use **GroupBy** to list services in separate tables based on their status. Enter an expression or a property of the output. -The output must be sorted before you send it to Format-Table. +The output must be sorted before you send it to `Format-Table`. -The value of the GroupBy parameter can be a new calculated property. +The value of the **GroupBy** parameter can be a new calculated property. To create a calculated, property, use a hash table. Valid keys are: @@ -211,7 +222,7 @@ Valid keys are: ```yaml Type: Object Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -226,23 +237,23 @@ Omits the column headings from the table. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -InputObject -Specifies the objects to be formatted. +Specifies the objects to format. Enter a variable that contains the objects, or type a command or expression that gets the objects. ```yaml Type: PSObject Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -257,36 +268,37 @@ Type one or more property names (separated by commas), or use a hash table to di Wildcards are permitted. If you omit this parameter, the properties that appear in the display depend on the object being displayed. -The parameter name ("Property") is optional. -You cannot use the Property and View parameters in the same command. +The parameter name (**Property**) is optional. +You cannot use the **Property** and **View** parameters in the same command. -The value of the Property parameter can be a new calculated property. -To create a calculated, property, use a hash table. +The value of the **Property** parameter can be a new calculated property. +To create a calculated property, use a hash table. Valid keys are: - Name (or Label) \ - Expression \ or \ - - - ConvertFromDateTime - - - + System.Management.ManagementObject + + + ConvertToDateTime + + + + ConvertFromDateTime + + + ``` @@ -542,7 +547,7 @@ property of the `GetVersionInfo` static method of VersionInfo - [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) + [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) @@ -553,12 +558,12 @@ For more information, see the [Windows PowerShell Software Development Kit (SDK) in the MSDN (Microsoft Developer Network) library](http://go.microsoft.com/fwlink/?LinkId=144538). -## Update-TypeData +## `Update-TypeData` To load your Types.ps1xml files into a Windows PowerShell session, run the `Update-TypeData` cmdlet. If you want the types in your file to take precedence over types in the built-in Types.ps1xml file, add the -`PrependData` parameter of `Update-TypeData`. `Update-TypeData` affects only +PrependData parameter of `Update-TypeData`. `Update-TypeData` affects only the current session. To make the change to all future sessions, export the session, or add the `Update-TypeData` command to your Windows PowerShell profile. @@ -580,8 +585,9 @@ use method syntax. ## Signing a Types.ps1xml File -To protect users of your Types.ps1xml file, you can sign the file using -a digital signature. For more information, see `about_Signing`. +To protect users of your Types.ps1xml file, you can sign the file using a +digital signature. For more information, see +[about_Signing](about_Signing.md). # SEE ALSO @@ -598,4 +604,3 @@ a digital signature. For more information, see `about_Signing`. [Remove-TypeData](../../Microsoft.PowerShell.Utility/Remove-TypeData.md) [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md index b2ddd2ffb955..08ee68185fcb 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,86 +7,90 @@ title: about_WMI_Cmdlets --- # About WMI Cmdlets -## about_WMI_Cmdlets - ## SHORT DESCRIPTION -Provides background information about Windows Management Instrumentation (WMI) and Windows PowerShell®. +Provides background information about Windows Management Instrumentation (WMI) +and Windows PowerShell. ## LONG DESCRIPTION -This topic provides information about WMI technology, the WMI cmdlets for Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI troubleshooting. This topic also provides links to more information about WMI. +This topic provides information about WMI technology, the WMI cmdlets for +Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI +troubleshooting. This topic also provides links to more information about WMI. ### ABOUT WMI -Windows Management Instrumentation (WMI) is the Microsoft implementation of Web-Based Enterprise Management (WBEM), which is an industry initiative to develop a standard technology for accessing management information in an enterprise environment. WMI uses the Common Information Model (CIM) industry standard to represent systems, applications, networks, devices, and other managed components. CIM is developed and maintained by the Distributed Management Task Force (DMTF). You can use WMI to manage both local and remote computers. For example, you can use WMI to do the following: - --- Start a process on a remote computer. - --- Restart a computer remotely. - --- Get a list of the applications that are installed on a local or remote computer. - --- Query the Windows event logs on a local or remote computer. +Windows Management Instrumentation (WMI) is the Microsoft implementation of +Web-Based Enterprise Management (WBEM), which is an industry initiative to +develop a standard technology for accessing management information in an +enterprise environment. WMI uses the Common Information Model (CIM) industry +standard to represent systems, applications, networks, devices, and other +managed components. CIM is developed and maintained by the Distributed +Management Task Force (DMTF). You can use WMI to manage both local and remote +computers. For example, you can use WMI to do the following: + +- Start a process on a remote computer. +- Restart a computer remotely. +- Get a list of the applications that are installed on a local or remote + computer. +- Query the Windows event logs on a local or remote computer. ### THE WMI CMDLETS FOR WINDOWS POWERSHELL -Windows PowerShell implements WMI functionality through a set of cmdlets that are available in Windows PowerShell by default. You can use these cmdlets to complete the end-to-end tasks necessary to manage local and remote computers. - -The following WMI cmdlets are included. +Windows PowerShell implements WMI functionality through a set of cmdlets that +are available in Windows PowerShell by default. You can use these cmdlets to +complete the end-to-end tasks necessary to manage local and remote computers. -``` -Cmdlet Description ------------------- ---------------------------------------------- -Get-WmiObject Gets instances of WMI classes or information - about the available classes. - -Invoke-WmiMethod Calls WMI methods. - -Register-WmiEvent Subscribes to a WMI event. - -Remove-WmiObject Deletes WMI classes and instances. - -Set-WmiInstance Creates or modifies instances of WMI classes. -``` - +The following WMI cmdlets are included. +|Cmdlet |Description | +|-----------------|----------------------------------------------| +|Get-WmiObject |Gets instances of WMI classes or information | +| |about the available classes. | +|Invoke-WmiMethod |Calls WMI methods. | +|Register-WmiEvent|Subscribes to a WMI event. | +|Remove-WmiObject |Deletes WMI classes and instances. | +|Set-WmiInstance |Creates or modifies instances of WMI classes. | ### SAMPLE COMMANDS The following command displays the BIOS information for the local computer. - -``` +```powershell C:\PS> get-wmiobject win32_bios | format-list * ``` +The following command displays information about the WinRM service for three +remote computers. -The following command displays information about the WinRM service for three remote computers. - - -``` -C:\PS> get-wmiobject -query "select * from win32_service where name='WinRM'" -computername server01, server01, server03 +```powershell +$wql = "select * from win32_service where name='WinRM'" +get-wmiobject -query $wql -computername server01, server01, server03 ``` - The following more complex command exits all instances of a program. - -``` -C:\PS> notepad.exe -C:\PS> $np = get-wmiobject -query "select * from win32_process where name='notepad.exe'" +```powershell +C:\PS> notepad.exe +C:\PS> $wql = "select * from win32_process where name='notepad.exe'" +C:\PS> $np = get-wmiobject -query $wql C:\PS> $np | remove-wmiobject ``` - - ### WMI-BASED REMOTING -While the ability to manage a local system through WMI is useful, it is the remoting capabilities that make WMI a powerful administrative tool. WMI uses Microsoft's Distributed Component Object Model (DCOM) to connect to and manage systems. You might have to configure some systems to allow DCOM connections. Firewall settings and locked-down DCOM permissions can block WMI's ability to remotely manage systems. +While the ability to manage a local system through WMI is useful, it is the +remoting capabilities that make WMI a powerful administrative tool. WMI uses +Microsoft's Distributed Component Object Model (DCOM) to connect to and manage +systems. You might have to configure some systems to allow DCOM connections. +Firewall settings and locked-down DCOM permissions can block WMI's ability to +remotely manage systems. ### WMI TYPE ACCELERATORS -Windows PowerShell includes WMI type accelerators. These WMI type accelerators (shortcuts) allow more direct access to a WMI objects than a non-type accelerator approach would allow. + +Windows PowerShell includes WMI type accelerators. These WMI type accelerators +(shortcuts) allow more direct access to a WMI objects than a non-type +accelerator approach would allow. The following type accelerators are supported with WMI: @@ -96,125 +100,117 @@ The following type accelerators are supported with WMI: [WMI] - A shortcut for getting a single instance of a class. -[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can take a string constructor to create a searcher that you can then do a GET() on. +[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can +take a string constructor to create a searcher that you can then do a GET() +on. For example: +```powershell +PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' +PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto +count __PATH name +----- ------ ---- +1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... +1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe +1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe +1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE +1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe +2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe ``` -PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' -PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto - -handlecount __PATH name ------------ ------ ---- -1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... -1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe -1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe -1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE -1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe -2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe -``` - -[WMICLASS] is a type accelerator for ManagementClass. This has a string constructor that takes a local or absolute WMI path to a WMI class and returns an object that is bound to that class. +[WMICLASS] is a type accelerator for ManagementClass. This has a string +constructor that takes a local or absolute WMI path to a WMI class and returns +an object that is bound to that class. For example: - -``` -PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" -PS> $c |fl * -Name : Win32_Process -__GENUS : 1 -__CLASS : Win32_Process -__SUPERCLASS : CIM_Process -__DYNASTY : CIM_ManagedSystemElement -__RELPATH : Win32_Process -__PROPERTY_COUNT : 45 -__DERIVATION : {CIM_Process, CIM_LogicalElement, CIM_ManagedSystemElement} -__SERVER : SERVER01 -__NAMESPACE : ROOT\cimv2 +```powershell +PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" +PS> $c |fl * +Name : Win32_Process +__GENUS : 1 +__CLASS : Win32_Process +__SUPERCLASS : CIM_Process +__DYNASTY : CIM_ManagedSystemElement +__RELPATH : Win32_Process +__PROPERTY_COUNT : 45 +__DERIVATION : {CIM_Process, CIM_LogicalElement, + CIM_ManagedSystemElement} +__SERVER : SERVER01 +__NAMESPACE : ROOT\cimv2 __PATH : \\SERVER01\ROOT\cimv2:Win32_Process ``` - -[WMI] is a type accelerator for ManagementObject. This has a string constructor that takes a local or absolute WMI path to a WMI instance and returns an object that is bound to that instance. +[WMI] is a type accelerator for ManagementObject. This has a string +constructor that takes a local or absolute WMI path to a WMI instance and +returns an object that is bound to that instance. For example: - -``` -PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' -PS> $p.Name +```powershell +PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' +PS> $p.Name OUTLOOK.EXE ``` - - ### WMI TROUBLESHOOTING -The following problems are the most common problems that might occur when you try to connect to a remote computer. -Problem 1: The remote computer is not online. - -If a computer is offline, you will not be able to connect to it by using WMI. You may receive the following error message: +The following problems are the most common problems that might occur when you +try to connect to a remote computer. +Problem 1: The remote computer is not online. -``` -"Remote server machine does not exist or is unavailable" -``` +If a computer is offline, you will not be able to connect to it by using WMI. +You may receive the following error message: + Remote server machine does not exist or is unavailable -If you receive this error message, verify that the computer is online. Try to ping the remote computer. +If you receive this error message, verify that the computer is online. Try to +ping the remote computer. Problem 2: You do not have local administrator rights on the remote computer. -To use WMI remotely, you must have local administrator rights on the remote computer. If you do not, access to that computer will be denied. +To use WMI remotely, you must have local administrator rights on the remote +computer. If you do not, access to that computer will be denied. To verify namespace security: -- a. Click Start, right-click My Computer, and then click Manage. - -- b. In Computer Management, expand Services and Applications, right-click WMI Control, and then click Properties. - -- c. In the WMI Control Properties dialog box, click the Security tab. +1. Click Start, right-click My Computer, and then click Manage. +2. In Computer Management, expand Services and Applications, right-click WMI + Control, and then click Properties. +3. In the WMI Control Properties dialog box, click the Security tab. Problem 3: A firewall is blocking access to the remote computer. -WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols to traverse the network. By default, many firewalls block DCOM and RPC traffic. If your firewall is blocking these protocols, your connection will fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is configured to automatically block all unsolicited network traffic, including DCOM and WMI. In its default configuration, Windows Firewall rejects an incoming WMI request, and you receive the following error message: - - -``` -"Remote server machine does not exist or is unavailable" -``` - +WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols +to traverse the network. By default, many firewalls block DCOM and RPC +traffic. If your firewall is blocking these protocols, your connection will +fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is +configured to automatically block all unsolicited network traffic, including +DCOM and WMI. In its default configuration, Windows Firewall rejects an +incoming WMI request, and you receive the following error message: + Remote server machine does not exist or is unavailable ### MORE INFORMATION ABOUT WMI -For more information about WMI, see the following topics in the MSDN (Microsoft Developer Network) library: - -``` -"About WMI: -http://go.microsoft.com/fwlink/?LinkId=142212 - -"WMI Troubleshooting" -http://go.microsoft.com/fwlink/?LinkId=142213 -``` +For more information about WMI, see the following topics in the MSDN +(Microsoft Developer Network) library: +About WMI: http://go.microsoft.com/fwlink/?LinkId=142212 -And, see "Secrets of Windows Management Instrumentation - Troubleshooting and Tips" in the Microsoft TechNet Script Center: +WMI Troubleshooting: http://go.microsoft.com/fwlink/?LinkId=142213 +And, see "Secrets of Windows Management Instrumentation - Troubleshooting and +Tips" in the Microsoft TechNet Script Center: -``` http://go.microsoft.com/fwlink/?LinkId=142214 -``` - ## SEE ALSO -Online version: http:\/\/go.microsoft.com\/fwlink\/?LinkId\=142219 - Get-WmiObject Invoke-WmiMethod diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md index 0d9fbe39f89d..10b1d7bc00db 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -74,20 +74,24 @@ are included. Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf ``` -The second example uses hash table splatting. The first command creates -a hash table of parameter-name and parameter-value pairs and stores it -in the $HashArguments variable. The second command uses the `$HashArguments` -variable in a command with splatting. The At symbol (`@HashArguments`) -replaces the dollar sign (`$HashArguments`) in the command. +The second example uses hash table splatting. The first command creates a hash +table of parameter-name and parameter-value pairs and stores it in the +\$HashArguments variable. The second command uses the `$HashArguments` variable +in a command with splatting. The At symbol (`@HashArguments`) replaces the +dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. ```powershell -$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true } +$HashArguments = @{ + Path = "test.txt" + Destination = "test2.txt" + WhatIf = $true +} Copy-Item @HashArguments ``` -*Note: In the first command, the At symbol (@) indicates a hash table, not +Note: In the first command, the At symbol (@) indicates a hash table, not a splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* @@ -106,11 +110,12 @@ omitted. The parameter values appear in position order in the command. Copy-Item "test.txt" "test2.txt" -WhatIf ``` -The second example uses array splatting. The first command creates an array -of the parameter values and stores it in the `$ArrayArguments` variable. The +The second example uses array splatting. The first command creates an array of +the parameter values and stores it in the `$ArrayArguments` variable. The values are in position order in the array. The second command uses the `$ArrayArguments` variable in a command in splatting. The At symbol -(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the command. +(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the +command. ```powershell $ArrayArguments = "test.txt", "test2.txt" @@ -120,10 +125,10 @@ Copy-Item @ArrayArguments -WhatIf # EXAMPLES -This example shows how to re-use splatted values in different commands. -The commands in this example use the Write-Host cmdlet to write messages -to the host program console. It uses splatting to specify the foreground -and background colors. +This example shows how to re-use splatted values in different commands. The +commands in this example use the Write-Host cmdlet to write messages to the +host program console. It uses splatting to specify the foreground and +background colors. To change the colors of all commands, just change the value of the `$Colors` variable. @@ -143,7 +148,8 @@ Write-Host command. To use the `$Colors variable`, replace the dollar sign #Write a message with the colors in $Colors Write-Host "This is a test." @Colors -#Write second message with same colors. The position of splatted hash table does not matter. +#Write second message with same colors. The position of splatted +#hash table does not matter. Write-Host @Colors "This is another test." ``` @@ -193,22 +199,19 @@ Test2 -a 1 -b 2 -c 3 # SPLATTING COMMAND PARAMETERS -You can use splatting to represent the parameters of -a command. This technique is useful when you are creating -a proxy function, that is, a function that calls another -command. This feature is introduced in Windows PowerShell 3.0. +You can use splatting to represent the parameters of a command. This technique +is useful when you are creating a proxy function, that is, a function that +calls another command. This feature is introduced in Windows PowerShell 3.0. -To splat the parameters of a command, use `@Args` to represent -the command parameters. This technique is easier than -enumerating command parameters and it works without revision -even if the parameters of the called command change. +To splat the parameters of a command, use `@Args` to represent the command +parameters. This technique is easier than enumerating command parameters and +it works without revision even if the parameters of the called command change. The feature uses the `$Args` automatic variable, which contains all unassigned parameter values. -For example, the following function calls the Get-Process -cmdlet. In this function, `@Args` represents all of the parameters -of the Get-Process cmdlet. +For example, the following function calls the Get-Process cmdlet. In this +function, `@Args` represents all of the parameters of the Get-Process cmdlet. ```powershell function Get-MyProcess { Get-Process @Args } @@ -223,20 +226,18 @@ Get-MyProcess -Name PowerShell Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -463 46 225484 237196 719 15.86 3228 powershell + 463 46 225484 237196 719 15.86 3228 powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo ProductVersion FileVersion FileName -------------- ----------- -------- -6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe +6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... ``` -You can use `@Args` in a function that has explicitly -declared parameters. You can use it more than once in -a function, but all parameters that you enter are passed -to all instances of `@Args`, as shown in the following -example. +You can use `@Args` in a function that has explicitly declared parameters. You +can use it more than once in a function, but all parameters that you enter are +passed to all instances of `@Args`, as shown in the following example. ```powershell function Get-MyCommand @@ -252,9 +253,9 @@ Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Extension : .exe -Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Visibility : Public OutputType : {System.String} Name : powershell.exe @@ -265,10 +266,11 @@ RemotingCapability : PowerShell Parameters : ParameterSets : HelpUri : -FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell + \v1.0\powershell.exe InternalName: POWERSHELL OriginalFilename: PowerShell.EXE.MUI - FileVersion: 10.0.14393.0 (rs1_release.160715-1616) + FileVersion: 10.0.14393.0 (rs1_release.160715-1616 FileDescription: Windows PowerShell Product: Microsoft® Windows® Operating System ProductVersion: 10.0.14393.0 @@ -289,4 +291,3 @@ FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1. [about_Hash_Tables](about_Hash_Tables.md) [about_Parameters](about_Parameters.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md index 9154bed7ea49..98b97dd2dab7 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -19,22 +19,21 @@ The Split operator splits one or more strings into substrings. You can change the following elements of the Split operation: * Delimiter. The default is whitespace, but you can specify characters, -strings, patterns, or script blocks that specify the delimiter. The Split -operator in Windows PowerShell uses a regular expression in the delimiter, -rather than a simple character. + strings, patterns, or script blocks that specify the delimiter. The Split + operator in Windows PowerShell uses a regular expression in the delimiter, + rather than a simple character. * Maximum number of substrings. The default is to return all substrings. If -you specify a number less than the number of substrings, the remaining -substrings are concatenated in the last substring. + you specify a number less than the number of substrings, the remaining + substrings are concatenated in the last substring. * Options that specify the conditions under which the delimiter is matched, -such as SimpleMatch and Multiline. + such as SimpleMatch and Multiline. ## SYNTAX The following diagram shows the syntax for the -split operator. -The parameter names do not appear in the command. Include only the -parameter values. The values must appear in the order specified in the -syntax diagram. +The parameter names do not appear in the command. Include only the parameter +values. The values must appear in the order specified in the syntax diagram. ```powershell -Split @@ -45,17 +44,17 @@ syntax diagram. ``` You can substitute `-iSplit` or `-cSplit` for `-split` in any binary Split -statement (a Split statement that includes a delimiter or script block). -The `-iSplit` and `-split` operators are case-insensitive. The `-cSplit` -operator is case-sensitive, meaning that case is considered when the -delimiter rules are applied. +statement (a Split statement that includes a delimiter or script block). The +`-iSplit` and `-split` operators are case-insensitive. The `-cSplit` operator +is case-sensitive, meaning that case is considered when the delimiter rules +are applied. ## PARAMETERS ### \ -Specifies one or more strings to be split. If you submit multiple -strings, all the strings are split using the same delimiter rules. +Specifies one or more strings to be split. If you submit multiple strings, all +the strings are split using the same delimiter rules. Example: @@ -69,10 +68,10 @@ green ### \ -The characters that identify the end of a substring. The default delimiter -is whitespace, including spaces and non-printable characters, such as -newline (\`n) and tab (\`t). When the strings are split, the delimiter is -omitted from all the substrings. Example: +The characters that identify the end of a substring. The default delimiter is +whitespace, including spaces and non-printable characters, such as newline +(\`n) and tab (\`t). When the strings are split, the delimiter is omitted from +all the substrings. Example: ```powershell "Lastname:FirstName:Address" -split ":" @@ -81,13 +80,13 @@ FirstName Address ``` -By default, the delimiter is omitted from the results. To preserve all or -part of the delimiter, enclose in parentheses the part that you want to -preserve. If the \ parameter is added, this takes -precedence when your command splits up the collection. If you opt to -include a delimiter as part of the output, the command returns the -delimiter as part of the output; however, splitting the string to return -the delimiter as part of output does not count as a split. +By default, the delimiter is omitted from the results. To preserve all or part +of the delimiter, enclose in parentheses the part that you want to preserve. +If the \ parameter is added, this takes precedence when your +command splits up the collection. If you opt to include a delimiter as part of +the output, the command returns the delimiter as part of the output; however, +splitting the string to return the delimiter as part of output does not count +as a split. Examples: @@ -124,17 +123,16 @@ Strawberry-Blueberry ### \ -Specifies the maximum number of times that a string is split. The default -is all the substrings split by the delimiter. If there are more substrings, -they are concatenated to the final substring. If there are fewer -substrings, all the substrings are returned. A value of 0 and negative -values return all the substrings. +Specifies the maximum number of times that a string is split. The default is +all the substrings split by the delimiter. If there are more substrings, they +are concatenated to the final substring. If there are fewer substrings, all +the substrings are returned. A value of 0 and negative values return all the +substrings. Max-substrings does not specify the maximum number of objects that are -returned; its value equals the maximum number of times that a string is -split. If you submit more than one string (an array of strings) to the -Split operator , the Max-substrings limit is applied to each string -separately. +returned; its value equals the maximum number of times that a string is split. +If you submit more than one string (an array of strings) to the Split operator +, the Max-substrings limit is applied to each string separately. Example: @@ -150,9 +148,8 @@ Jupiter,Saturn,Uranus,Neptune ### \ -An expression that specifies rules for applying the delimiter. The -expression must evaluate to $true or $false. Enclose the script block in -braces. +An expression that specifies rules for applying the delimiter. The expression +must evaluate to $true or $false. Enclose the script block in braces. Example: @@ -187,63 +184,62 @@ The syntax for the Options parameter is: The SimpleMatch options are: * **SimpleMatch**: Use simple string comparison when evaluating the -delimiter. Cannot be used with RegexMatch. + delimiter. Cannot be used with RegexMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. The RegexMatch options are: * **RegexMatch**: Use regular expression matching to evaluate the -delimiter. This is the default behavior. Cannot be used with -SimpleMatch. + delimiter. This is the default behavior. Cannot be used with + SimpleMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. * **CultureInvariant**: Ignores cultural differences in language -when evaluting the delimiter. Valid only with RegexMatch. + when evaluting the delimiter. Valid only with RegexMatch. * IgnorePatternWhitespace: Ignores unescaped whitespace and -comments marked with the number sign (#). Valid only with -RegexMatch. + comments marked with the number sign (#). Valid only with + RegexMatch. * **Multiline**: Multiline mode recognizes the start and end of lines -and strings. Valid only with RegexMatch. Singleline is the default. + and strings. Valid only with RegexMatch. Singleline is the default. * **Singleline**: Singleline mode recognizes only the start and end of -strings. Valid only with RegexMatch. Singleline is the default. + strings. Valid only with RegexMatch. Singleline is the default. * **ExplicitCapture**: Ignores non-named match groups so that only -explicit capture groups are returned in the result list. Valid -only with RegexMatch. + explicit capture groups are returned in the result list. Valid + only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the -unary split operator, only the first string (before the first comma) is -split. +unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( --split ). Enclose all the strings in parentheses, or store the -strings in a variable, and then submit the variable to the split operator. +To split more than one string, use the binary split operator ( -split +). Enclose all the strings in parentheses, or store the strings in +a variable, and then submit the variable to the split operator. Consider the following example: ```powershell -PS C:\> -split "1 2", "a b" +PS > -split "1 2", "a b" 1 2 a b -PS C:\> "1 2", "a b" -split " " +PS > "1 2", "a b" -split " " 1 2 a b -PS C:\> -split ("1 2", "a b") +PS > -split ("1 2", "a b") 1 2 a b -PS C:\> $a = "1 2", "a b" -PS C:\> -split $a +PS > $a = "1 2", "a b" +PS > -split $a 1 2 a @@ -255,7 +251,7 @@ b The following statement splits the string at whitespace. ```powershell -PS C:\> -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" Windows PowerShell 2.0 @@ -268,7 +264,7 @@ remoting The following statement splits the string at any comma. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' Mercury Venus Earth @@ -282,17 +278,16 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune ``` -The following statement performs a case-sensitive split at the -letter "N". +The following statement performs a case-sensitive split at the letter "N". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -300,7 +295,7 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' M rcury,V nus, @@ -317,7 +312,8 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` + -split '[er]', 6 M cu @@ -329,7 +325,7 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS C:\> "a,b,c,d,e,f,g,h" -split ",", 3 +PS > "a,b,c,d,e,f,g,h" -split ",", 3 a b c,d,e,f,g,h @@ -339,7 +335,7 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS C:\> "a,b,c,d", "e,f,g,h" -split ",", 3 +PS > "a,b,c,d", "e,f,g,h" -split ",", 3 a b c,d @@ -352,18 +348,18 @@ The following statement splits each line in the here-string at the first digit. It uses the Multiline option to recognize the beginning of each line and string. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as Multiline, only when the Max-substrings value -is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as Multiline, only when the Max-substrings value is +specified. ```powershell -PS C:\> $a = @' +PS > $a = @' 1The first line. 2The second line. 3The third of three lines. '@ -PS C:\> $a -split "^\d", 0, "multiline" +PS > $a -split "^\d", 0, "multiline" The first line. @@ -380,12 +376,12 @@ interpreted to match any character except for a newline character. As a result, the Split statement returns a blank line for every character except newline. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as SimpleMatch, only when the Max-substrings -value is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as SimpleMatch, only when the Max-substrings value is +specified. ```powershell -PS C:\> "This.is.a.test" -split ".", 0, "simplematch" +PS > "This.is.a.test" -split ".", 0, "simplematch" This is @@ -393,13 +389,13 @@ a test ``` -The following statement splits the string at one of two delimiters, -depending on the value of a variable. +The following statement splits the string at one of two delimiters, depending +on the value of a variable. ```powershell -PS C:\> $i = 1 -PS C:\> $c = "LastName, FirstName; Address, City, State, Zip" -PS C:\> $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +PS > $i = 1 +PS > $c = "LastName, FirstName; Address, City, State, Zip" +PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} LastName, FirstName Address, City, State, Zip @@ -407,7 +403,7 @@ Address, City, State, Zip ## SEE ALSO -Split-Path +[Split-Path](../../Microsoft.PowerShell.Management/Split-Path.md) [about_Operators](about_Operators.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md index 90658fd83ff1..1bfafbe78470 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -148,13 +148,25 @@ Default clause is permitted in each Switch statement. Switch has the following parameters: -|Parameter|Description| -|---|---| -| Wildcard | Indicates that the condition is a wildcard string. If you use Wildcard, Regex and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| Exact | Indicates that the match clause, if it is a string, must match exactly. If you use Exact, Regex and Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| CaseSensitive | Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. | -| File | Takes input from a file rather than a value statement. If multiple File parameters are included, only the last one is used. Each line of the file is read and evaluated by the Switch statement. | -| Regex | Performs regular expression matching of the value to the condition. If you use Regex, Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | +|Parameter |Description | +|-------------|-----------------------------------------------------------| +|Wildcard |Indicates that the condition is a wildcard string. If you | +| |you use Wildcard, Regex and Exact are ignored. Also, if | +| |the match clause is not a string, the parameter is ignored.| +|Exact |Indicates that the match clause, if it is a string, must | +| |match exactly. Regex and Wildcard and Exact are ignored. | +| |Also, if the match clause is not a string, this parameter | +| |is ignored. | +|CaseSensitive|Performs a case-sensitive match. If the match clause is not| +| |a string, this parameter is ignored. | +|File |Takes input from a file rather than a value statement. If | +| |multiple File parameters are included, only the last one is| +| |used. Each line of the file is read and evaluated by the | +| |Switch statement. | +|Regex |Performs regular expression matching of the value to the | +| |condition. Wildcard and Exact are ignored. Also, if the | +| |match clause is not a string, this parameter is ignored. | + ```powershell Example: diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Throw.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Throw.md index 2deea43ade1b..08fe2f6e5c7e 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Throw.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Throw.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,16 +14,16 @@ Describes the Throw keyword, which generates a terminating error. ## LONG DESCRIPTION -The Throw keyword causes a terminating error. You can use the Throw keyword -to stop the processing of a command, function, or script. +The Throw keyword causes a terminating error. You can use the Throw keyword to +stop the processing of a command, function, or script. For example, you can use the Throw keyword in the script block of an If statement to respond to a condition or in the Catch block of a -Try-Catch-Finally statement. You can also use the Throw keyword in a -parameter declaration to make a function parameter mandatory. +Try-Catch-Finally statement. You can also use the Throw keyword in a parameter +declaration to make a function parameter mandatory. -The Throw keyword can throw any object, such as a user message string or -the object that caused the error. +The Throw keyword can throw any object, such as a user message string or the +object that caused the error. ## SYNTAX @@ -33,8 +33,8 @@ The syntax of the Throw keyword is as follows: throw [] ``` -The expression in the Throw syntax is optional. When the Throw statement -does not appear in a Catch block, and it does not include an expression, it +The expression in the Throw syntax is optional. When the Throw statement does +not appear in a Catch block, and it does not include an expression, it generates a ScriptHalted error. ```powershell @@ -47,13 +47,14 @@ At line:1 char:6 + FullyQualifiedErrorId : ScriptHalted ``` -If the Throw keyword is used in a Catch block without an expression, it -throws the current RuntimeException again. For more information, see +If the Throw keyword is used in a Catch block without an expression, it throws +the current RuntimeException again. For more information, see about_Try_Catch_Finally. ## THROWING A STRING -The optional expression in a Throw statement can be a string, as shown in -the following example: + +The optional expression in a Throw statement can be a string, as shown in the +following example: ```powershell C:\PS> throw "This is an error." @@ -61,7 +62,8 @@ C:\PS> throw "This is an error." This is an error. At line:1 char:6 + throw <<<< "This is an error." -+ CategoryInfo : OperationStopped: (This is an error.:String) [], RuntimeException ++ CategoryInfo : OperationStopped: (This is an error.:String) [], R +untimeException + FullyQualifiedErrorId : This is an error. ``` @@ -76,7 +78,8 @@ C:\PS> throw (get-process PowerShell) System.Diagnostics.Process (PowerShell) At line:1 char:6 + throw <<<< (get-process PowerShell) -+ CategoryInfo : OperationStopped: (System.Diagnostics.Process (PowerShell):Process) [], ++ CategoryInfo : OperationStopped: (System.Diagnostics.Process (Pow +erShell):Process) [], RuntimeException + FullyQualifiedErrorId : System.Diagnostics.Process (PowerShell) ``` @@ -105,15 +108,16 @@ One of the identified items was in an invalid format. At line:1 char:6 + throw <<<< $formatError + CategoryInfo : OperationStopped: (:) [], FormatException -+ FullyQualifiedErrorId : One of the identified items was in an invalid format. ++ FullyQualifiedErrorId : One of the identified items was in an invalid +format. ``` ## RESULTING ERROR -The Throw keyword can generate an ErrorRecord object. The Exception -property of the ErrorRecord object contains a RuntimeException object. The -remainder of the ErrorRecord object and the RuntimeException object vary -with the object that the Throw keyword throws. +The Throw keyword can generate an ErrorRecord object. The Exception property +of the ErrorRecord object contains a RuntimeException object. The remainder of +the ErrorRecord object and the RuntimeException object vary with the object +that the Throw keyword throws. The RunTimeException object is wrapped in an ErrorRecord object, and the ErrorRecord object is automatically saved in the $Error automatic variable. @@ -139,7 +143,9 @@ optional. function Get-XMLFiles { param ($path = $(throw "The Path parameter is required.")) - dir -path $path\*.xml -recurse | sort lastwritetime | ft lastwritetime, attributes, name -auto + dir -path $path\*.xml -recurse | + sort lastwritetime | + ft lastwritetime, attributes, name -auto } ``` @@ -154,4 +160,3 @@ function Get-XMLFiles [about_Trap](about_Trap.md) [about_Try_Catch_Finally](about_Try_Catch_Finally.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Trap.md index 338030fa058b..bc042324bc4b 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Trap.md @@ -130,7 +130,9 @@ statement that specifies the CommandNotFoundException type. ```powershell trap {"Other terminating error trapped" } -trap [System.Management.Automation.CommandNotFoundException] {"Command error trapped"} +trap [System.Management.Automation.CommandNotFoundException] { + "Command error trapped" +} nonsenseString ``` diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md index a94e962d87b3..531eb8a2f9da 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-091 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -26,11 +26,16 @@ fails, it returns nothing. It does not return an error. The following table lists the type operators in Windows PowerShell. -|Operator|Description|Example| -|---|---|---| -|`-is`|Returns TRUE when the input is an instance of the specified.NET Framework type.|`C:\PS> (get-date) -is [DateTime]`
`True`| -|`-isNot`|Returns TRUE when the input is not an instance of the specified.NET Framework type.|`C:\PS> (get-date) -isNot [DateTime]`
`False`| -|`-as`|Converts the input to the specified.NET Framework type.|`C:\PS> 12/31/07 -as [DateTime]`
`Monday, December 31, 2007 12:00:00 AM`| +|Operator|Description |Example | +|--------|---------------------------|---------------------------------| +|`-is` |Returns TRUE when the input|`(get-date) -is [DateTime]` | +| |is an instance of the |`True` | +| |specified .NET type. | | +|`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]` | +| |not an instance of the |`False` | +| |specified.NET type. | | +|`-as` |Converts the input to the |`"5/7/07" -as [DateTime]` | +| |specified .NET type. |`Monday, May 7, 2007 12:00:00 AM`| The syntax of the type operators is as follows: @@ -64,7 +69,7 @@ property of this method. For example, the following statement gets the type of the return value of a Get-Culture command: ```powershell -C:\PS> (get-culture).gettype().fullname +PS> (get-culture).gettype().fullname System.Globalization.CultureInfo ``` @@ -72,25 +77,25 @@ System.Globalization.CultureInfo The following examples show some uses of the Type operators: ```powershell -C:\PS> 32 -is [Float] +PS> 32 -is [Float] False -C:\PS> 32 -is "int" +PS> 32 -is "int" True -C:\PS> (get-date) -is [DateTime] +PS> (get-date) -is [DateTime] True -C:\PS> "12/31/2007" -is [DateTime] +PS> "12/31/2007" -is [DateTime] False -C:\PS> "12/31/2007" -is [String] +PS> "12/31/2007" -is [String] True -C:\PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] +PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] True -C:\PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] +PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] True ``` @@ -103,53 +108,55 @@ return System.Globalization.CultureInfo objects, a collection of these objects is a System.Object array. ```powershell -C:\PS> (get-culture) -is [System.Globalization.CultureInfo] +PS> (get-culture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-uiculture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] False -C:\PS> (get-culture), (get-uiculture) -is [Array] +PS> (get-culture), (get-uiculture) -is [Array] True -C:\PS> (get-culture), (get-uiculture) | foreach {$_ -is [System.Globalization.CultureInfo]) +PS> (get-culture), (get-uiculture) | foreach { + $_ -is [System.Globalization.CultureInfo]) +} True True -C:\PS> (get-culture), (get-uiculture) -is [Object] +PS> (get-culture), (get-uiculture) -is [Object] True ``` The following examples show how to use the -as operator. ```powershell -C:\PS> "12/31/07" -is [DateTime] +PS> "12/31/07" -is [DateTime] False -C:\PS> "12/31/07" -as [DateTime] +PS> "12/31/07" -as [DateTime] Monday, December 31, 2007 12:00:00 AM -C:\PS> $date = "12/31/07" -as [DateTime] +PS> $date = "12/31/07" -as [DateTime] C:\PS>$a -is [DateTime] True -C:\PS> 1031 -as [System.Globalization.CultureInfo] +PS> 1031 -as [System.Globalization.CultureInfo] -LCID Name DisplayName ----- ---- ----------- -1031 de-DE German (Germany) +LCID Name DisplayName +---- ---- ----------- +1031 de-DE German (Germany) ``` The following example shows that when the -as operator cannot convert the input object to the .NET Framework type, it returns nothing. ```powershell -C:\PS> 1031 -as [System.Diagnostic.Process] -C:\PS> +PS> 1031 -as [System.Diagnostic.Process] +PS> ``` ## SEE ALSO diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index 4720a9de93dc..3888516c6096 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Types.ps1xml --- # About Types.ps1xml -## about_Types.ps1xml - - # SHORT DESCRIPTION @@ -27,16 +24,16 @@ extended type data to a Windows PowerShell session. extended data for types in the current session. This topic describes Types.ps1xml files. For more information about using the -`Update-TypeData` cmdlet to add dynamic extended type data to the current session -see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). +`Update-TypeData` cmdlet to add dynamic extended type data to the current +session see +[Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). ## About Extended Type Data -Extended type data defines additional properties and methods ("members") -of object types in Windows PowerShell. You can extend any type that is -supported by Windows PowerShell and use the added properties and methods -in the same way that you use the properties that are defined on the object -types. +Extended type data defines additional properties and methods ("members") of +object types in Windows PowerShell. You can extend any type that is supported +by Windows PowerShell and use the added properties and methods in the same way +that you use the properties that are defined on the object types. For example, Windows PowerShell adds a `DateTime` property to all `System.DateTime` objects, such as the ones that the `Get-Date` cmdlet @@ -47,27 +44,27 @@ PS C:> (Get-Date).DateTime Sunday, January 29, 2012 9:43:57 AM ``` -You won't find the DateTime property in the description of the [`System.DateTime` -structure](http://msdn.microsoft.com/library/system.datetime.aspx), -because Windows PowerShell adds the property and it is visible only in -Windows PowerShell. +You won't find the `DateTime` property in the description of the +[`System.DateTime` structure](http://msdn.microsoft.com/library/system.datetime.aspx), +because Windows PowerShell adds the property and it is visible only in Windows +PowerShell. -To add the DateTime property to all Windows PowerShell sessions, Windows PowerShell -defines the DateTime property in the Types.ps1xml file in the Windows PowerShell -installation directory (`$PSHOME`). +To add the `DateTime` property to all Windows PowerShell sessions, Windows +PowerShell defines the `DateTime` property in the Types.ps1xml file in the +Windows PowerShell installation directory (`$PSHOME`). ## Adding Extended Type Data to Windows PowerShell. There are three sources of extended type data in Windows PowerShell sessions. -- The Types.ps1xml files in the Windows PowerShell installation directory -are loaded automatically into every Windows PowerShell session. +- The Types.ps1xml files in the Windows PowerShell installation directory + are loaded automatically into every Windows PowerShell session. -- The Types.ps1xml files that modules export are loaded when the module -is imported into the current session. +- The Types.ps1xml files that modules export are loaded when the module + is imported into the current session. -- Extended type data that is defined by using the `Update-TypeData` cmdlet -is added only to the current session. It is not saved in a file. +- Extended type data that is defined by using the `Update-TypeData` cmdlet + is added only to the current session. It is not saved in a file. In the session, the extended type data from the three sources is applied to objects in the same way and is available on all objects of the specified @@ -78,14 +75,12 @@ types. The following TypeData cmdlets are included in the Microsoft.PowerShell.Utility module in Windows PowerShell 3.0 and later versions of Windows PowerShell. -| | | -| --------------- | --------------------------------------------------- | -| Get-TypeData | Gets extended type data in the current session. | -| Update-TypeData | Reloads Types.ps1xml files. Adds extended type data to the current session. | -| Remove-TypeData | Removes extended type data from the current session. | +- `Get-TypeData`: Gets extended type data in the current session. +- `Update-TypeData`: Reloads Types.ps1xml files. Adds extended type data to the + current session. +- `Remove-TypeData`: Removes extended type data from the current session. -For more information about these cmdlets, see the help topic for each -cmdlet. +For more information about these cmdlets, see the help topic for each cmdlet. ## Built-in Types.ps1xml Files @@ -103,7 +98,7 @@ For example, by default, array objects (`System.Array`) have a `Length` property that lists the number of objects in the array. However, because the name "Length" does not clearly describe the property, Windows PowerShell adds an alias property named "Count" that displays the same -value. The following XML adds the `Count` property to the `System.Array` type. +value. The following XML adds the Count property to the `System.Array` type. ```xml @@ -119,8 +114,8 @@ value. The following XML adds the `Count` property to the `System.Array` type. ``` -To get the new `AliasProperty`, use a `Get-Member` command on any array, as shown -in the following example. +To get the new `AliasProperty`, use a `Get-Member` command on any array, as +shown in the following example. ```powershell Get-Member -InputObject (1,2,3,4) @@ -128,29 +123,28 @@ Get-Member -InputObject (1,2,3,4) The command returns the following results. -```powershell -Name MemberType Definition ----- ---------- ---------- -Count AliasProperty Count = Length -Address Method System.Object& Address(Int32) -Clone Method System.Object Clone() -CopyTo Method System.Void CopyTo(Array array, Int32 index): -Equals Method System.Boolean Equals(Object obj) -Get Method System.Object Get(Int32) +```output +Name MemberType Definition +---- ---------- ---------- +Count AliasProperty Count = Length +Address Method System.Object& Address(Int32) +Clone Method System.Object Clone() +CopyTo Method System.Void CopyTo(Array array, Int32 index): +Equals Method System.Boolean Equals(Object obj) +Get Method System.Object Get(Int32) # ... ``` - -As a result, you can use either the `Count` property or the `Length` property +As a result, you can use either the Count property or the Length property of arrays in Windows PowerShell. For example: ```powershell -C:\PS> (1, 2, 3, 4).Count +C:\PS> (1, 2, 3, 4).count # 4 ``` ```powershell -C:\PS> (1, 2, 3, 4).Length +C:\PS> (1, 2, 3, 4).length # 4 ``` @@ -172,12 +166,12 @@ installation directory. When you have saved the new file, use the `Update-TypeData` cmdlet to add the new file to your Windows PowerShell session. If you want your types to take precedence over the types that are defined in the built-in file, -use the `PrependData` parameter of the `Update-TypeData` cmdlet. +use the PrependData parameter of the `Update-TypeData` cmdlet. `Update-TypeData` affects only the current session. To make the change to all future sessions, export the console, or add the `Update-TypeData` command to your Windows PowerShell profile. -## Types.ps1xml and `Add-Member` +## Types.ps1xml and Add-Member The Types.ps1xml files add properties and methods to all the instances of the objects of the specified .NET Framework type in the affected @@ -188,7 +182,7 @@ For more information, see [Add-Member](../../Microsoft.PowerShell.Utility/Add-Me ## Example: Adding an `Age` Member to `FileInfo` Objects -This example shows how to add an Age property to file objects +This example shows how to add an `Age` property to file objects (`System.IO.FileInfo`). The age of a file is the difference between its creation time and the current time in days. @@ -201,7 +195,7 @@ Copy-Item Types.ps1xml MyTypes.ps1xml ``` Next, open the Types.ps1xml file in any XML or text editor, such -as Notepad. Because the Age property is calculated by using a script +as Notepad. Because the `Age` property is calculated by using a script block, find a `` tag to use as a model for the new `Age` property. @@ -257,7 +251,7 @@ information about `Update-TypeData`, see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md).) ```powershell -Update-TypeData -PrependPath $PSHOME\MyTypes.ps1xml +Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml ``` To test the change, run a `Get-ChildItem` command to get the @@ -285,11 +279,11 @@ You can also display the `Age` property of the file by using the following command. ```powershell -(Get-GhildItem $PSHOME\PowerShell.exe).Age +(Get-ChildItem $PSHOME\PowerShell.exe).Age # 16 ``` -The XML in Types.ps1xml Files +## The XML in Types.ps1xml Files The `` tag encloses all of the types that are defined in the file. There should be only one pair of `` tags. @@ -335,7 +329,7 @@ The `` tag must have a pair of `` tags that specify the name of the new method and a pair of `` tags that specify the code in which the method is defined. -For example, the Mode property of directories (System.IO.DirectoryInfo +For example, the Mode property of directories (`System.IO.DirectoryInfo` objects) is a code property defined in the Windows PowerShell FileSystem provider. @@ -346,7 +340,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -371,7 +367,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -439,7 +437,7 @@ The `` tag must have a pair of `` tags that specify the name of the new property and a pair of `` tags that specify the value of the property. -For example, the following XML creates a `Status` property for +For example, the following XML creates a Status property for directories (`System.IO.DirectoryInfo` objects). The value of the `Status` property is always "Success". @@ -474,7 +472,7 @@ properties for the default display of an object. You can identify the default displays by the value "PsStandardMembers" in the `` tag of a `` tag. -For example, the following XML creates a `Status` property for +For example, the following XML creates a Status property for directories (`System.IO.DirectoryInfo` objects). The value of the `Status` property is always "Success". @@ -496,7 +494,7 @@ property is always "Success". - + ``` ``: Defines a method whose value is the output of a script. @@ -512,21 +510,21 @@ methods of the `System.Management.ManagementDateTimeConverter` class. ```xml - System.Management.ManagementObject - - - ConvertToDateTime - - - - ConvertFromDateTime - - - + System.Management.ManagementObject + + + ConvertToDateTime + + + + ConvertFromDateTime + + + ``` @@ -549,7 +547,7 @@ property of the `GetVersionInfo` static method of VersionInfo - [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) + [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) @@ -565,7 +563,7 @@ library](http://go.microsoft.com/fwlink/?LinkId=144538). To load your Types.ps1xml files into a Windows PowerShell session, run the `Update-TypeData` cmdlet. If you want the types in your file to take precedence over types in the built-in Types.ps1xml file, add the -`PrependData` parameter of `Update-TypeData`. `Update-TypeData` affects only +PrependData parameter of `Update-TypeData`. `Update-TypeData` affects only the current session. To make the change to all future sessions, export the session, or add the `Update-TypeData` command to your Windows PowerShell profile. @@ -576,8 +574,8 @@ suppress exceptions that would occur in many common types during formatting and outputting. If you are getting .NET Framework properties, you can work around the suppression of exceptions by using method syntax instead, as shown in the following example: - - ```powershell + +```powershell "hello".get_Length() ``` @@ -587,8 +585,9 @@ use method syntax. ## Signing a Types.ps1xml File -To protect users of your Types.ps1xml file, you can sign the file using -a digital signature. For more information, see [about_Signing](about_Signing.md). +To protect users of your Types.ps1xml file, you can sign the file using a +digital signature. For more information, see +[about_Signing](about_Signing.md). # SEE ALSO @@ -605,4 +604,3 @@ a digital signature. For more information, see [about_Signing](about_Signing.md) [Remove-TypeData](../../Microsoft.PowerShell.Utility/Remove-TypeData.md) [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md index b2ddd2ffb955..08ee68185fcb 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,86 +7,90 @@ title: about_WMI_Cmdlets --- # About WMI Cmdlets -## about_WMI_Cmdlets - ## SHORT DESCRIPTION -Provides background information about Windows Management Instrumentation (WMI) and Windows PowerShell®. +Provides background information about Windows Management Instrumentation (WMI) +and Windows PowerShell. ## LONG DESCRIPTION -This topic provides information about WMI technology, the WMI cmdlets for Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI troubleshooting. This topic also provides links to more information about WMI. +This topic provides information about WMI technology, the WMI cmdlets for +Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI +troubleshooting. This topic also provides links to more information about WMI. ### ABOUT WMI -Windows Management Instrumentation (WMI) is the Microsoft implementation of Web-Based Enterprise Management (WBEM), which is an industry initiative to develop a standard technology for accessing management information in an enterprise environment. WMI uses the Common Information Model (CIM) industry standard to represent systems, applications, networks, devices, and other managed components. CIM is developed and maintained by the Distributed Management Task Force (DMTF). You can use WMI to manage both local and remote computers. For example, you can use WMI to do the following: - --- Start a process on a remote computer. - --- Restart a computer remotely. - --- Get a list of the applications that are installed on a local or remote computer. - --- Query the Windows event logs on a local or remote computer. +Windows Management Instrumentation (WMI) is the Microsoft implementation of +Web-Based Enterprise Management (WBEM), which is an industry initiative to +develop a standard technology for accessing management information in an +enterprise environment. WMI uses the Common Information Model (CIM) industry +standard to represent systems, applications, networks, devices, and other +managed components. CIM is developed and maintained by the Distributed +Management Task Force (DMTF). You can use WMI to manage both local and remote +computers. For example, you can use WMI to do the following: + +- Start a process on a remote computer. +- Restart a computer remotely. +- Get a list of the applications that are installed on a local or remote + computer. +- Query the Windows event logs on a local or remote computer. ### THE WMI CMDLETS FOR WINDOWS POWERSHELL -Windows PowerShell implements WMI functionality through a set of cmdlets that are available in Windows PowerShell by default. You can use these cmdlets to complete the end-to-end tasks necessary to manage local and remote computers. - -The following WMI cmdlets are included. +Windows PowerShell implements WMI functionality through a set of cmdlets that +are available in Windows PowerShell by default. You can use these cmdlets to +complete the end-to-end tasks necessary to manage local and remote computers. -``` -Cmdlet Description ------------------- ---------------------------------------------- -Get-WmiObject Gets instances of WMI classes or information - about the available classes. - -Invoke-WmiMethod Calls WMI methods. - -Register-WmiEvent Subscribes to a WMI event. - -Remove-WmiObject Deletes WMI classes and instances. - -Set-WmiInstance Creates or modifies instances of WMI classes. -``` - +The following WMI cmdlets are included. +|Cmdlet |Description | +|-----------------|----------------------------------------------| +|Get-WmiObject |Gets instances of WMI classes or information | +| |about the available classes. | +|Invoke-WmiMethod |Calls WMI methods. | +|Register-WmiEvent|Subscribes to a WMI event. | +|Remove-WmiObject |Deletes WMI classes and instances. | +|Set-WmiInstance |Creates or modifies instances of WMI classes. | ### SAMPLE COMMANDS The following command displays the BIOS information for the local computer. - -``` +```powershell C:\PS> get-wmiobject win32_bios | format-list * ``` +The following command displays information about the WinRM service for three +remote computers. -The following command displays information about the WinRM service for three remote computers. - - -``` -C:\PS> get-wmiobject -query "select * from win32_service where name='WinRM'" -computername server01, server01, server03 +```powershell +$wql = "select * from win32_service where name='WinRM'" +get-wmiobject -query $wql -computername server01, server01, server03 ``` - The following more complex command exits all instances of a program. - -``` -C:\PS> notepad.exe -C:\PS> $np = get-wmiobject -query "select * from win32_process where name='notepad.exe'" +```powershell +C:\PS> notepad.exe +C:\PS> $wql = "select * from win32_process where name='notepad.exe'" +C:\PS> $np = get-wmiobject -query $wql C:\PS> $np | remove-wmiobject ``` - - ### WMI-BASED REMOTING -While the ability to manage a local system through WMI is useful, it is the remoting capabilities that make WMI a powerful administrative tool. WMI uses Microsoft's Distributed Component Object Model (DCOM) to connect to and manage systems. You might have to configure some systems to allow DCOM connections. Firewall settings and locked-down DCOM permissions can block WMI's ability to remotely manage systems. +While the ability to manage a local system through WMI is useful, it is the +remoting capabilities that make WMI a powerful administrative tool. WMI uses +Microsoft's Distributed Component Object Model (DCOM) to connect to and manage +systems. You might have to configure some systems to allow DCOM connections. +Firewall settings and locked-down DCOM permissions can block WMI's ability to +remotely manage systems. ### WMI TYPE ACCELERATORS -Windows PowerShell includes WMI type accelerators. These WMI type accelerators (shortcuts) allow more direct access to a WMI objects than a non-type accelerator approach would allow. + +Windows PowerShell includes WMI type accelerators. These WMI type accelerators +(shortcuts) allow more direct access to a WMI objects than a non-type +accelerator approach would allow. The following type accelerators are supported with WMI: @@ -96,125 +100,117 @@ The following type accelerators are supported with WMI: [WMI] - A shortcut for getting a single instance of a class. -[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can take a string constructor to create a searcher that you can then do a GET() on. +[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can +take a string constructor to create a searcher that you can then do a GET() +on. For example: +```powershell +PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' +PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto +count __PATH name +----- ------ ---- +1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... +1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe +1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe +1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE +1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe +2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe ``` -PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' -PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto - -handlecount __PATH name ------------ ------ ---- -1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... -1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe -1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe -1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE -1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe -2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe -``` - -[WMICLASS] is a type accelerator for ManagementClass. This has a string constructor that takes a local or absolute WMI path to a WMI class and returns an object that is bound to that class. +[WMICLASS] is a type accelerator for ManagementClass. This has a string +constructor that takes a local or absolute WMI path to a WMI class and returns +an object that is bound to that class. For example: - -``` -PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" -PS> $c |fl * -Name : Win32_Process -__GENUS : 1 -__CLASS : Win32_Process -__SUPERCLASS : CIM_Process -__DYNASTY : CIM_ManagedSystemElement -__RELPATH : Win32_Process -__PROPERTY_COUNT : 45 -__DERIVATION : {CIM_Process, CIM_LogicalElement, CIM_ManagedSystemElement} -__SERVER : SERVER01 -__NAMESPACE : ROOT\cimv2 +```powershell +PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" +PS> $c |fl * +Name : Win32_Process +__GENUS : 1 +__CLASS : Win32_Process +__SUPERCLASS : CIM_Process +__DYNASTY : CIM_ManagedSystemElement +__RELPATH : Win32_Process +__PROPERTY_COUNT : 45 +__DERIVATION : {CIM_Process, CIM_LogicalElement, + CIM_ManagedSystemElement} +__SERVER : SERVER01 +__NAMESPACE : ROOT\cimv2 __PATH : \\SERVER01\ROOT\cimv2:Win32_Process ``` - -[WMI] is a type accelerator for ManagementObject. This has a string constructor that takes a local or absolute WMI path to a WMI instance and returns an object that is bound to that instance. +[WMI] is a type accelerator for ManagementObject. This has a string +constructor that takes a local or absolute WMI path to a WMI instance and +returns an object that is bound to that instance. For example: - -``` -PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' -PS> $p.Name +```powershell +PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' +PS> $p.Name OUTLOOK.EXE ``` - - ### WMI TROUBLESHOOTING -The following problems are the most common problems that might occur when you try to connect to a remote computer. -Problem 1: The remote computer is not online. - -If a computer is offline, you will not be able to connect to it by using WMI. You may receive the following error message: +The following problems are the most common problems that might occur when you +try to connect to a remote computer. +Problem 1: The remote computer is not online. -``` -"Remote server machine does not exist or is unavailable" -``` +If a computer is offline, you will not be able to connect to it by using WMI. +You may receive the following error message: + Remote server machine does not exist or is unavailable -If you receive this error message, verify that the computer is online. Try to ping the remote computer. +If you receive this error message, verify that the computer is online. Try to +ping the remote computer. Problem 2: You do not have local administrator rights on the remote computer. -To use WMI remotely, you must have local administrator rights on the remote computer. If you do not, access to that computer will be denied. +To use WMI remotely, you must have local administrator rights on the remote +computer. If you do not, access to that computer will be denied. To verify namespace security: -- a. Click Start, right-click My Computer, and then click Manage. - -- b. In Computer Management, expand Services and Applications, right-click WMI Control, and then click Properties. - -- c. In the WMI Control Properties dialog box, click the Security tab. +1. Click Start, right-click My Computer, and then click Manage. +2. In Computer Management, expand Services and Applications, right-click WMI + Control, and then click Properties. +3. In the WMI Control Properties dialog box, click the Security tab. Problem 3: A firewall is blocking access to the remote computer. -WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols to traverse the network. By default, many firewalls block DCOM and RPC traffic. If your firewall is blocking these protocols, your connection will fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is configured to automatically block all unsolicited network traffic, including DCOM and WMI. In its default configuration, Windows Firewall rejects an incoming WMI request, and you receive the following error message: - - -``` -"Remote server machine does not exist or is unavailable" -``` - +WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols +to traverse the network. By default, many firewalls block DCOM and RPC +traffic. If your firewall is blocking these protocols, your connection will +fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is +configured to automatically block all unsolicited network traffic, including +DCOM and WMI. In its default configuration, Windows Firewall rejects an +incoming WMI request, and you receive the following error message: + Remote server machine does not exist or is unavailable ### MORE INFORMATION ABOUT WMI -For more information about WMI, see the following topics in the MSDN (Microsoft Developer Network) library: - -``` -"About WMI: -http://go.microsoft.com/fwlink/?LinkId=142212 - -"WMI Troubleshooting" -http://go.microsoft.com/fwlink/?LinkId=142213 -``` +For more information about WMI, see the following topics in the MSDN +(Microsoft Developer Network) library: +About WMI: http://go.microsoft.com/fwlink/?LinkId=142212 -And, see "Secrets of Windows Management Instrumentation - Troubleshooting and Tips" in the Microsoft TechNet Script Center: +WMI Troubleshooting: http://go.microsoft.com/fwlink/?LinkId=142213 +And, see "Secrets of Windows Management Instrumentation - Troubleshooting and +Tips" in the Microsoft TechNet Script Center: -``` http://go.microsoft.com/fwlink/?LinkId=142214 -``` - ## SEE ALSO -Online version: http:\/\/go.microsoft.com\/fwlink\/?LinkId\=142219 - Get-WmiObject Invoke-WmiMethod diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/About_Using.md b/reference/5.0/Microsoft.PowerShell.Core/About/About_Using.md index b6abbe721641..4fbccbdc21cf 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/About_Using.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/About_Using.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,7 +7,6 @@ title: about_Using --- # About Using -## about_Using # SHORT DESCRIPTION @@ -15,47 +14,49 @@ Allows to indicate which namespaces are used in the session. # LONG DESCRIPTION - -The `using` statement allows to indicate which namespaces are used in the session. -Making easier to mention classes and members, as it requires less typing to mention them; -also, classes from modules can be referenced too. +The `using` statement allows to indicate which namespaces are used in the +session. Making easier to mention classes and members, as it requires less +typing to mention them; also, classes from modules can be referenced too. The `using` statement needs to be the first statement in the script. Syntax #1, to reference .Net Framework namespaces: + ``` using namespace <.Net-framework-namespace> ``` Syntax #2, to reference PowerShell modules: + ``` using module ``` -> **Note** The `using` statetement, for modules, is intended to surface the classes in the module. -> If the module isn't loaded, the `using` fails. +**Note**: The `using` statetement, for modules, is intended to surface the +classes in the module. If the module isn't loaded, the `using` fails. ## Example 1 The following script gets the cryptographic hash for the "Hello World" string. -Note how the `using namespace System.Text` and `using namespace System.IO` simplify -the references to `[UnicodeEncoding]` in *System.Text*; and, to `[Stream]` -and to `[MemoryStream]` in *System.IO*. - +Note how the `using namespace System.Text` and `using namespace System.IO` +simplify the references to `[UnicodeEncoding]` in *System.Text*; and, to +`[Stream]` and to `[MemoryStream]` in *System.IO*. ```powershell - using namespace System.Text - using namespace System.IO +using namespace System.Text +using namespace System.IO - [string]$string = "Hello World" - [string]$algorithm = "SHA256" ## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MACTripleDES", "MD5", "RIPEMD160" +[string]$string = "Hello World" +## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MD5" +[string]$algorithm = "SHA256" - [byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) +[byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) - [Stream]$memorystream = [MemoryStream]::new($stringbytes) - $hashfromstream = Get-FileHash -InputStream $memorystream -Algorithm $algorithm - $hashfromstream.Hash.ToString() +[Stream]$memorystream = [MemoryStream]::new($stringbytes) +$hashfromstream = Get-FileHash -InputStream $memorystream ` + -Algorithm $algorithm +$hashfromstream.Hash.ToString() ``` ## Example 2 @@ -77,4 +78,3 @@ $deck.Shuffle() [Card[]]$hand2 = $deck.Deal(5) [Card[]]$hand3 = $deck.Deal(5) ``` - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md index 0d9fbe39f89d..10b1d7bc00db 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -74,20 +74,24 @@ are included. Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf ``` -The second example uses hash table splatting. The first command creates -a hash table of parameter-name and parameter-value pairs and stores it -in the $HashArguments variable. The second command uses the `$HashArguments` -variable in a command with splatting. The At symbol (`@HashArguments`) -replaces the dollar sign (`$HashArguments`) in the command. +The second example uses hash table splatting. The first command creates a hash +table of parameter-name and parameter-value pairs and stores it in the +\$HashArguments variable. The second command uses the `$HashArguments` variable +in a command with splatting. The At symbol (`@HashArguments`) replaces the +dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. ```powershell -$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true } +$HashArguments = @{ + Path = "test.txt" + Destination = "test2.txt" + WhatIf = $true +} Copy-Item @HashArguments ``` -*Note: In the first command, the At symbol (@) indicates a hash table, not +Note: In the first command, the At symbol (@) indicates a hash table, not a splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* @@ -106,11 +110,12 @@ omitted. The parameter values appear in position order in the command. Copy-Item "test.txt" "test2.txt" -WhatIf ``` -The second example uses array splatting. The first command creates an array -of the parameter values and stores it in the `$ArrayArguments` variable. The +The second example uses array splatting. The first command creates an array of +the parameter values and stores it in the `$ArrayArguments` variable. The values are in position order in the array. The second command uses the `$ArrayArguments` variable in a command in splatting. The At symbol -(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the command. +(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the +command. ```powershell $ArrayArguments = "test.txt", "test2.txt" @@ -120,10 +125,10 @@ Copy-Item @ArrayArguments -WhatIf # EXAMPLES -This example shows how to re-use splatted values in different commands. -The commands in this example use the Write-Host cmdlet to write messages -to the host program console. It uses splatting to specify the foreground -and background colors. +This example shows how to re-use splatted values in different commands. The +commands in this example use the Write-Host cmdlet to write messages to the +host program console. It uses splatting to specify the foreground and +background colors. To change the colors of all commands, just change the value of the `$Colors` variable. @@ -143,7 +148,8 @@ Write-Host command. To use the `$Colors variable`, replace the dollar sign #Write a message with the colors in $Colors Write-Host "This is a test." @Colors -#Write second message with same colors. The position of splatted hash table does not matter. +#Write second message with same colors. The position of splatted +#hash table does not matter. Write-Host @Colors "This is another test." ``` @@ -193,22 +199,19 @@ Test2 -a 1 -b 2 -c 3 # SPLATTING COMMAND PARAMETERS -You can use splatting to represent the parameters of -a command. This technique is useful when you are creating -a proxy function, that is, a function that calls another -command. This feature is introduced in Windows PowerShell 3.0. +You can use splatting to represent the parameters of a command. This technique +is useful when you are creating a proxy function, that is, a function that +calls another command. This feature is introduced in Windows PowerShell 3.0. -To splat the parameters of a command, use `@Args` to represent -the command parameters. This technique is easier than -enumerating command parameters and it works without revision -even if the parameters of the called command change. +To splat the parameters of a command, use `@Args` to represent the command +parameters. This technique is easier than enumerating command parameters and +it works without revision even if the parameters of the called command change. The feature uses the `$Args` automatic variable, which contains all unassigned parameter values. -For example, the following function calls the Get-Process -cmdlet. In this function, `@Args` represents all of the parameters -of the Get-Process cmdlet. +For example, the following function calls the Get-Process cmdlet. In this +function, `@Args` represents all of the parameters of the Get-Process cmdlet. ```powershell function Get-MyProcess { Get-Process @Args } @@ -223,20 +226,18 @@ Get-MyProcess -Name PowerShell Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -463 46 225484 237196 719 15.86 3228 powershell + 463 46 225484 237196 719 15.86 3228 powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo ProductVersion FileVersion FileName -------------- ----------- -------- -6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe +6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... ``` -You can use `@Args` in a function that has explicitly -declared parameters. You can use it more than once in -a function, but all parameters that you enter are passed -to all instances of `@Args`, as shown in the following -example. +You can use `@Args` in a function that has explicitly declared parameters. You +can use it more than once in a function, but all parameters that you enter are +passed to all instances of `@Args`, as shown in the following example. ```powershell function Get-MyCommand @@ -252,9 +253,9 @@ Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Extension : .exe -Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Visibility : Public OutputType : {System.String} Name : powershell.exe @@ -265,10 +266,11 @@ RemotingCapability : PowerShell Parameters : ParameterSets : HelpUri : -FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell + \v1.0\powershell.exe InternalName: POWERSHELL OriginalFilename: PowerShell.EXE.MUI - FileVersion: 10.0.14393.0 (rs1_release.160715-1616) + FileVersion: 10.0.14393.0 (rs1_release.160715-1616 FileDescription: Windows PowerShell Product: Microsoft® Windows® Operating System ProductVersion: 10.0.14393.0 @@ -289,4 +291,3 @@ FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1. [about_Hash_Tables](about_Hash_Tables.md) [about_Parameters](about_Parameters.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md index 9154bed7ea49..98b97dd2dab7 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -19,22 +19,21 @@ The Split operator splits one or more strings into substrings. You can change the following elements of the Split operation: * Delimiter. The default is whitespace, but you can specify characters, -strings, patterns, or script blocks that specify the delimiter. The Split -operator in Windows PowerShell uses a regular expression in the delimiter, -rather than a simple character. + strings, patterns, or script blocks that specify the delimiter. The Split + operator in Windows PowerShell uses a regular expression in the delimiter, + rather than a simple character. * Maximum number of substrings. The default is to return all substrings. If -you specify a number less than the number of substrings, the remaining -substrings are concatenated in the last substring. + you specify a number less than the number of substrings, the remaining + substrings are concatenated in the last substring. * Options that specify the conditions under which the delimiter is matched, -such as SimpleMatch and Multiline. + such as SimpleMatch and Multiline. ## SYNTAX The following diagram shows the syntax for the -split operator. -The parameter names do not appear in the command. Include only the -parameter values. The values must appear in the order specified in the -syntax diagram. +The parameter names do not appear in the command. Include only the parameter +values. The values must appear in the order specified in the syntax diagram. ```powershell -Split @@ -45,17 +44,17 @@ syntax diagram. ``` You can substitute `-iSplit` or `-cSplit` for `-split` in any binary Split -statement (a Split statement that includes a delimiter or script block). -The `-iSplit` and `-split` operators are case-insensitive. The `-cSplit` -operator is case-sensitive, meaning that case is considered when the -delimiter rules are applied. +statement (a Split statement that includes a delimiter or script block). The +`-iSplit` and `-split` operators are case-insensitive. The `-cSplit` operator +is case-sensitive, meaning that case is considered when the delimiter rules +are applied. ## PARAMETERS ### \ -Specifies one or more strings to be split. If you submit multiple -strings, all the strings are split using the same delimiter rules. +Specifies one or more strings to be split. If you submit multiple strings, all +the strings are split using the same delimiter rules. Example: @@ -69,10 +68,10 @@ green ### \ -The characters that identify the end of a substring. The default delimiter -is whitespace, including spaces and non-printable characters, such as -newline (\`n) and tab (\`t). When the strings are split, the delimiter is -omitted from all the substrings. Example: +The characters that identify the end of a substring. The default delimiter is +whitespace, including spaces and non-printable characters, such as newline +(\`n) and tab (\`t). When the strings are split, the delimiter is omitted from +all the substrings. Example: ```powershell "Lastname:FirstName:Address" -split ":" @@ -81,13 +80,13 @@ FirstName Address ``` -By default, the delimiter is omitted from the results. To preserve all or -part of the delimiter, enclose in parentheses the part that you want to -preserve. If the \ parameter is added, this takes -precedence when your command splits up the collection. If you opt to -include a delimiter as part of the output, the command returns the -delimiter as part of the output; however, splitting the string to return -the delimiter as part of output does not count as a split. +By default, the delimiter is omitted from the results. To preserve all or part +of the delimiter, enclose in parentheses the part that you want to preserve. +If the \ parameter is added, this takes precedence when your +command splits up the collection. If you opt to include a delimiter as part of +the output, the command returns the delimiter as part of the output; however, +splitting the string to return the delimiter as part of output does not count +as a split. Examples: @@ -124,17 +123,16 @@ Strawberry-Blueberry ### \ -Specifies the maximum number of times that a string is split. The default -is all the substrings split by the delimiter. If there are more substrings, -they are concatenated to the final substring. If there are fewer -substrings, all the substrings are returned. A value of 0 and negative -values return all the substrings. +Specifies the maximum number of times that a string is split. The default is +all the substrings split by the delimiter. If there are more substrings, they +are concatenated to the final substring. If there are fewer substrings, all +the substrings are returned. A value of 0 and negative values return all the +substrings. Max-substrings does not specify the maximum number of objects that are -returned; its value equals the maximum number of times that a string is -split. If you submit more than one string (an array of strings) to the -Split operator , the Max-substrings limit is applied to each string -separately. +returned; its value equals the maximum number of times that a string is split. +If you submit more than one string (an array of strings) to the Split operator +, the Max-substrings limit is applied to each string separately. Example: @@ -150,9 +148,8 @@ Jupiter,Saturn,Uranus,Neptune ### \ -An expression that specifies rules for applying the delimiter. The -expression must evaluate to $true or $false. Enclose the script block in -braces. +An expression that specifies rules for applying the delimiter. The expression +must evaluate to $true or $false. Enclose the script block in braces. Example: @@ -187,63 +184,62 @@ The syntax for the Options parameter is: The SimpleMatch options are: * **SimpleMatch**: Use simple string comparison when evaluating the -delimiter. Cannot be used with RegexMatch. + delimiter. Cannot be used with RegexMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. The RegexMatch options are: * **RegexMatch**: Use regular expression matching to evaluate the -delimiter. This is the default behavior. Cannot be used with -SimpleMatch. + delimiter. This is the default behavior. Cannot be used with + SimpleMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. * **CultureInvariant**: Ignores cultural differences in language -when evaluting the delimiter. Valid only with RegexMatch. + when evaluting the delimiter. Valid only with RegexMatch. * IgnorePatternWhitespace: Ignores unescaped whitespace and -comments marked with the number sign (#). Valid only with -RegexMatch. + comments marked with the number sign (#). Valid only with + RegexMatch. * **Multiline**: Multiline mode recognizes the start and end of lines -and strings. Valid only with RegexMatch. Singleline is the default. + and strings. Valid only with RegexMatch. Singleline is the default. * **Singleline**: Singleline mode recognizes only the start and end of -strings. Valid only with RegexMatch. Singleline is the default. + strings. Valid only with RegexMatch. Singleline is the default. * **ExplicitCapture**: Ignores non-named match groups so that only -explicit capture groups are returned in the result list. Valid -only with RegexMatch. + explicit capture groups are returned in the result list. Valid + only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the -unary split operator, only the first string (before the first comma) is -split. +unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( --split ). Enclose all the strings in parentheses, or store the -strings in a variable, and then submit the variable to the split operator. +To split more than one string, use the binary split operator ( -split +). Enclose all the strings in parentheses, or store the strings in +a variable, and then submit the variable to the split operator. Consider the following example: ```powershell -PS C:\> -split "1 2", "a b" +PS > -split "1 2", "a b" 1 2 a b -PS C:\> "1 2", "a b" -split " " +PS > "1 2", "a b" -split " " 1 2 a b -PS C:\> -split ("1 2", "a b") +PS > -split ("1 2", "a b") 1 2 a b -PS C:\> $a = "1 2", "a b" -PS C:\> -split $a +PS > $a = "1 2", "a b" +PS > -split $a 1 2 a @@ -255,7 +251,7 @@ b The following statement splits the string at whitespace. ```powershell -PS C:\> -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" Windows PowerShell 2.0 @@ -268,7 +264,7 @@ remoting The following statement splits the string at any comma. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' Mercury Venus Earth @@ -282,17 +278,16 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune ``` -The following statement performs a case-sensitive split at the -letter "N". +The following statement performs a case-sensitive split at the letter "N". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -300,7 +295,7 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' M rcury,V nus, @@ -317,7 +312,8 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` + -split '[er]', 6 M cu @@ -329,7 +325,7 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS C:\> "a,b,c,d,e,f,g,h" -split ",", 3 +PS > "a,b,c,d,e,f,g,h" -split ",", 3 a b c,d,e,f,g,h @@ -339,7 +335,7 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS C:\> "a,b,c,d", "e,f,g,h" -split ",", 3 +PS > "a,b,c,d", "e,f,g,h" -split ",", 3 a b c,d @@ -352,18 +348,18 @@ The following statement splits each line in the here-string at the first digit. It uses the Multiline option to recognize the beginning of each line and string. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as Multiline, only when the Max-substrings value -is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as Multiline, only when the Max-substrings value is +specified. ```powershell -PS C:\> $a = @' +PS > $a = @' 1The first line. 2The second line. 3The third of three lines. '@ -PS C:\> $a -split "^\d", 0, "multiline" +PS > $a -split "^\d", 0, "multiline" The first line. @@ -380,12 +376,12 @@ interpreted to match any character except for a newline character. As a result, the Split statement returns a blank line for every character except newline. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as SimpleMatch, only when the Max-substrings -value is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as SimpleMatch, only when the Max-substrings value is +specified. ```powershell -PS C:\> "This.is.a.test" -split ".", 0, "simplematch" +PS > "This.is.a.test" -split ".", 0, "simplematch" This is @@ -393,13 +389,13 @@ a test ``` -The following statement splits the string at one of two delimiters, -depending on the value of a variable. +The following statement splits the string at one of two delimiters, depending +on the value of a variable. ```powershell -PS C:\> $i = 1 -PS C:\> $c = "LastName, FirstName; Address, City, State, Zip" -PS C:\> $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +PS > $i = 1 +PS > $c = "LastName, FirstName; Address, City, State, Zip" +PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} LastName, FirstName Address, City, State, Zip @@ -407,7 +403,7 @@ Address, City, State, Zip ## SEE ALSO -Split-Path +[Split-Path](../../Microsoft.PowerShell.Management/Split-Path.md) [about_Operators](about_Operators.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md index 90658fd83ff1..1bfafbe78470 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -148,13 +148,25 @@ Default clause is permitted in each Switch statement. Switch has the following parameters: -|Parameter|Description| -|---|---| -| Wildcard | Indicates that the condition is a wildcard string. If you use Wildcard, Regex and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| Exact | Indicates that the match clause, if it is a string, must match exactly. If you use Exact, Regex and Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| CaseSensitive | Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. | -| File | Takes input from a file rather than a value statement. If multiple File parameters are included, only the last one is used. Each line of the file is read and evaluated by the Switch statement. | -| Regex | Performs regular expression matching of the value to the condition. If you use Regex, Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | +|Parameter |Description | +|-------------|-----------------------------------------------------------| +|Wildcard |Indicates that the condition is a wildcard string. If you | +| |you use Wildcard, Regex and Exact are ignored. Also, if | +| |the match clause is not a string, the parameter is ignored.| +|Exact |Indicates that the match clause, if it is a string, must | +| |match exactly. Regex and Wildcard and Exact are ignored. | +| |Also, if the match clause is not a string, this parameter | +| |is ignored. | +|CaseSensitive|Performs a case-sensitive match. If the match clause is not| +| |a string, this parameter is ignored. | +|File |Takes input from a file rather than a value statement. If | +| |multiple File parameters are included, only the last one is| +| |used. Each line of the file is read and evaluated by the | +| |Switch statement. | +|Regex |Performs regular expression matching of the value to the | +| |condition. Wildcard and Exact are ignored. Also, if the | +| |match clause is not a string, this parameter is ignored. | + ```powershell Example: diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Throw.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Throw.md index 2deea43ade1b..08fe2f6e5c7e 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Throw.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Throw.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,16 +14,16 @@ Describes the Throw keyword, which generates a terminating error. ## LONG DESCRIPTION -The Throw keyword causes a terminating error. You can use the Throw keyword -to stop the processing of a command, function, or script. +The Throw keyword causes a terminating error. You can use the Throw keyword to +stop the processing of a command, function, or script. For example, you can use the Throw keyword in the script block of an If statement to respond to a condition or in the Catch block of a -Try-Catch-Finally statement. You can also use the Throw keyword in a -parameter declaration to make a function parameter mandatory. +Try-Catch-Finally statement. You can also use the Throw keyword in a parameter +declaration to make a function parameter mandatory. -The Throw keyword can throw any object, such as a user message string or -the object that caused the error. +The Throw keyword can throw any object, such as a user message string or the +object that caused the error. ## SYNTAX @@ -33,8 +33,8 @@ The syntax of the Throw keyword is as follows: throw [] ``` -The expression in the Throw syntax is optional. When the Throw statement -does not appear in a Catch block, and it does not include an expression, it +The expression in the Throw syntax is optional. When the Throw statement does +not appear in a Catch block, and it does not include an expression, it generates a ScriptHalted error. ```powershell @@ -47,13 +47,14 @@ At line:1 char:6 + FullyQualifiedErrorId : ScriptHalted ``` -If the Throw keyword is used in a Catch block without an expression, it -throws the current RuntimeException again. For more information, see +If the Throw keyword is used in a Catch block without an expression, it throws +the current RuntimeException again. For more information, see about_Try_Catch_Finally. ## THROWING A STRING -The optional expression in a Throw statement can be a string, as shown in -the following example: + +The optional expression in a Throw statement can be a string, as shown in the +following example: ```powershell C:\PS> throw "This is an error." @@ -61,7 +62,8 @@ C:\PS> throw "This is an error." This is an error. At line:1 char:6 + throw <<<< "This is an error." -+ CategoryInfo : OperationStopped: (This is an error.:String) [], RuntimeException ++ CategoryInfo : OperationStopped: (This is an error.:String) [], R +untimeException + FullyQualifiedErrorId : This is an error. ``` @@ -76,7 +78,8 @@ C:\PS> throw (get-process PowerShell) System.Diagnostics.Process (PowerShell) At line:1 char:6 + throw <<<< (get-process PowerShell) -+ CategoryInfo : OperationStopped: (System.Diagnostics.Process (PowerShell):Process) [], ++ CategoryInfo : OperationStopped: (System.Diagnostics.Process (Pow +erShell):Process) [], RuntimeException + FullyQualifiedErrorId : System.Diagnostics.Process (PowerShell) ``` @@ -105,15 +108,16 @@ One of the identified items was in an invalid format. At line:1 char:6 + throw <<<< $formatError + CategoryInfo : OperationStopped: (:) [], FormatException -+ FullyQualifiedErrorId : One of the identified items was in an invalid format. ++ FullyQualifiedErrorId : One of the identified items was in an invalid +format. ``` ## RESULTING ERROR -The Throw keyword can generate an ErrorRecord object. The Exception -property of the ErrorRecord object contains a RuntimeException object. The -remainder of the ErrorRecord object and the RuntimeException object vary -with the object that the Throw keyword throws. +The Throw keyword can generate an ErrorRecord object. The Exception property +of the ErrorRecord object contains a RuntimeException object. The remainder of +the ErrorRecord object and the RuntimeException object vary with the object +that the Throw keyword throws. The RunTimeException object is wrapped in an ErrorRecord object, and the ErrorRecord object is automatically saved in the $Error automatic variable. @@ -139,7 +143,9 @@ optional. function Get-XMLFiles { param ($path = $(throw "The Path parameter is required.")) - dir -path $path\*.xml -recurse | sort lastwritetime | ft lastwritetime, attributes, name -auto + dir -path $path\*.xml -recurse | + sort lastwritetime | + ft lastwritetime, attributes, name -auto } ``` @@ -154,4 +160,3 @@ function Get-XMLFiles [about_Trap](about_Trap.md) [about_Try_Catch_Finally](about_Try_Catch_Finally.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Trap.md index 338030fa058b..bc042324bc4b 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Trap.md @@ -130,7 +130,9 @@ statement that specifies the CommandNotFoundException type. ```powershell trap {"Other terminating error trapped" } -trap [System.Management.Automation.CommandNotFoundException] {"Command error trapped"} +trap [System.Management.Automation.CommandNotFoundException] { + "Command error trapped" +} nonsenseString ``` diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md index a94e962d87b3..531eb8a2f9da 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Type_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-091 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -26,11 +26,16 @@ fails, it returns nothing. It does not return an error. The following table lists the type operators in Windows PowerShell. -|Operator|Description|Example| -|---|---|---| -|`-is`|Returns TRUE when the input is an instance of the specified.NET Framework type.|`C:\PS> (get-date) -is [DateTime]`
`True`| -|`-isNot`|Returns TRUE when the input is not an instance of the specified.NET Framework type.|`C:\PS> (get-date) -isNot [DateTime]`
`False`| -|`-as`|Converts the input to the specified.NET Framework type.|`C:\PS> 12/31/07 -as [DateTime]`
`Monday, December 31, 2007 12:00:00 AM`| +|Operator|Description |Example | +|--------|---------------------------|---------------------------------| +|`-is` |Returns TRUE when the input|`(get-date) -is [DateTime]` | +| |is an instance of the |`True` | +| |specified .NET type. | | +|`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]` | +| |not an instance of the |`False` | +| |specified.NET type. | | +|`-as` |Converts the input to the |`"5/7/07" -as [DateTime]` | +| |specified .NET type. |`Monday, May 7, 2007 12:00:00 AM`| The syntax of the type operators is as follows: @@ -64,7 +69,7 @@ property of this method. For example, the following statement gets the type of the return value of a Get-Culture command: ```powershell -C:\PS> (get-culture).gettype().fullname +PS> (get-culture).gettype().fullname System.Globalization.CultureInfo ``` @@ -72,25 +77,25 @@ System.Globalization.CultureInfo The following examples show some uses of the Type operators: ```powershell -C:\PS> 32 -is [Float] +PS> 32 -is [Float] False -C:\PS> 32 -is "int" +PS> 32 -is "int" True -C:\PS> (get-date) -is [DateTime] +PS> (get-date) -is [DateTime] True -C:\PS> "12/31/2007" -is [DateTime] +PS> "12/31/2007" -is [DateTime] False -C:\PS> "12/31/2007" -is [String] +PS> "12/31/2007" -is [String] True -C:\PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] +PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] True -C:\PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] +PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] True ``` @@ -103,53 +108,55 @@ return System.Globalization.CultureInfo objects, a collection of these objects is a System.Object array. ```powershell -C:\PS> (get-culture) -is [System.Globalization.CultureInfo] +PS> (get-culture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-uiculture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] False -C:\PS> (get-culture), (get-uiculture) -is [Array] +PS> (get-culture), (get-uiculture) -is [Array] True -C:\PS> (get-culture), (get-uiculture) | foreach {$_ -is [System.Globalization.CultureInfo]) +PS> (get-culture), (get-uiculture) | foreach { + $_ -is [System.Globalization.CultureInfo]) +} True True -C:\PS> (get-culture), (get-uiculture) -is [Object] +PS> (get-culture), (get-uiculture) -is [Object] True ``` The following examples show how to use the -as operator. ```powershell -C:\PS> "12/31/07" -is [DateTime] +PS> "12/31/07" -is [DateTime] False -C:\PS> "12/31/07" -as [DateTime] +PS> "12/31/07" -as [DateTime] Monday, December 31, 2007 12:00:00 AM -C:\PS> $date = "12/31/07" -as [DateTime] +PS> $date = "12/31/07" -as [DateTime] C:\PS>$a -is [DateTime] True -C:\PS> 1031 -as [System.Globalization.CultureInfo] +PS> 1031 -as [System.Globalization.CultureInfo] -LCID Name DisplayName ----- ---- ----------- -1031 de-DE German (Germany) +LCID Name DisplayName +---- ---- ----------- +1031 de-DE German (Germany) ``` The following example shows that when the -as operator cannot convert the input object to the .NET Framework type, it returns nothing. ```powershell -C:\PS> 1031 -as [System.Diagnostic.Process] -C:\PS> +PS> 1031 -as [System.Diagnostic.Process] +PS> ``` ## SEE ALSO diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index ea2b5a898093..3888516c6096 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Types.ps1xml --- # About Types.ps1xml -## about_Types.ps1xml - - # SHORT DESCRIPTION @@ -27,16 +24,16 @@ extended type data to a Windows PowerShell session. extended data for types in the current session. This topic describes Types.ps1xml files. For more information about using the -`Update-TypeData` cmdlet to add dynamic extended type data to the current session -see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). +`Update-TypeData` cmdlet to add dynamic extended type data to the current +session see +[Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). ## About Extended Type Data -Extended type data defines additional properties and methods ("members") -of object types in Windows PowerShell. You can extend any type that is -supported by Windows PowerShell and use the added properties and methods -in the same way that you use the properties that are defined on the object -types. +Extended type data defines additional properties and methods ("members") of +object types in Windows PowerShell. You can extend any type that is supported +by Windows PowerShell and use the added properties and methods in the same way +that you use the properties that are defined on the object types. For example, Windows PowerShell adds a `DateTime` property to all `System.DateTime` objects, such as the ones that the `Get-Date` cmdlet @@ -47,27 +44,27 @@ PS C:> (Get-Date).DateTime Sunday, January 29, 2012 9:43:57 AM ``` -You won't find the `DateTime` property in the description of the [`System.DateTime` -structure](http://msdn.microsoft.com/library/system.datetime.aspx), -because Windows PowerShell adds the property and it is visible only in -Windows PowerShell. +You won't find the `DateTime` property in the description of the +[`System.DateTime` structure](http://msdn.microsoft.com/library/system.datetime.aspx), +because Windows PowerShell adds the property and it is visible only in Windows +PowerShell. -To add the `DateTime` property to all Windows PowerShell sessions, Windows PowerShell -defines the `DateTime` property in the Types.ps1xml file in the Windows PowerShell -installation directory (`$PSHOME`). +To add the `DateTime` property to all Windows PowerShell sessions, Windows +PowerShell defines the `DateTime` property in the Types.ps1xml file in the +Windows PowerShell installation directory (`$PSHOME`). ## Adding Extended Type Data to Windows PowerShell. There are three sources of extended type data in Windows PowerShell sessions. - The Types.ps1xml files in the Windows PowerShell installation directory -are loaded automatically into every Windows PowerShell session. + are loaded automatically into every Windows PowerShell session. - The Types.ps1xml files that modules export are loaded when the module -is imported into the current session. + is imported into the current session. - Extended type data that is defined by using the `Update-TypeData` cmdlet -is added only to the current session. It is not saved in a file. + is added only to the current session. It is not saved in a file. In the session, the extended type data from the three sources is applied to objects in the same way and is available on all objects of the specified @@ -78,18 +75,16 @@ types. The following TypeData cmdlets are included in the Microsoft.PowerShell.Utility module in Windows PowerShell 3.0 and later versions of Windows PowerShell. -| | | -| --------------- | ----------------------------------------------------- | -| Get-TypeData | Gets extended type data in the current session. | -| Update-TypeData | Reloads Types.ps1xml files. Adds extended type data to the current session. | -| Remove-TypeData | Removes extended type data from the current session. | +- `Get-TypeData`: Gets extended type data in the current session. +- `Update-TypeData`: Reloads Types.ps1xml files. Adds extended type data to the + current session. +- `Remove-TypeData`: Removes extended type data from the current session. -For more information about these cmdlets, see the help topic for each -cmdlet. +For more information about these cmdlets, see the help topic for each cmdlet. ## Built-in Types.ps1xml Files -The Types.ps1xml files in the $PSHOME directory are added automatically to +The Types.ps1xml files in the `$PSHOME` directory are added automatically to every session. The Types.ps1xml file in the Windows PowerShell installation directory @@ -103,7 +98,7 @@ For example, by default, array objects (`System.Array`) have a `Length` property that lists the number of objects in the array. However, because the name "Length" does not clearly describe the property, Windows PowerShell adds an alias property named "Count" that displays the same -value. The following XML adds the `Count` property to the `System.Array` type. +value. The following XML adds the Count property to the `System.Array` type. ```xml @@ -119,28 +114,28 @@ value. The following XML adds the `Count` property to the `System.Array` type. ``` -To get the new `AliasProperty`, use a `Get-Member` command on any array, as shown -in the following example. +To get the new `AliasProperty`, use a `Get-Member` command on any array, as +shown in the following example. ```powershell -Get-Member -inputobject (1,2,3,4) +Get-Member -InputObject (1,2,3,4) ``` The command returns the following results. -```powershell -Name MemberType Definition ----- ---------- ---------- -Count AliasProperty Count = Length -Address Method System.Object& Address(Int32) -Clone Method System.Object Clone() -CopyTo Method System.Void CopyTo(Array array, Int32 index): -Equals Method System.Boolean Equals(Object obj) -Get Method System.Object Get(Int32) +```output +Name MemberType Definition +---- ---------- ---------- +Count AliasProperty Count = Length +Address Method System.Object& Address(Int32) +Clone Method System.Object Clone() +CopyTo Method System.Void CopyTo(Array array, Int32 index): +Equals Method System.Boolean Equals(Object obj) +Get Method System.Object Get(Int32) # ... ``` -As a result, you can use either the `Count` property or the `Length` property +As a result, you can use either the Count property or the Length property of arrays in Windows PowerShell. For example: ```powershell @@ -171,17 +166,17 @@ installation directory. When you have saved the new file, use the `Update-TypeData` cmdlet to add the new file to your Windows PowerShell session. If you want your types to take precedence over the types that are defined in the built-in file, -use the `PrependData` parameter of the `Update-TypeData` cmdlet. +use the PrependData parameter of the `Update-TypeData` cmdlet. `Update-TypeData` affects only the current session. To make the change to all future sessions, export the console, or add the `Update-TypeData` command to your Windows PowerShell profile. -## Types.ps1xml and `Add-Member` +## Types.ps1xml and Add-Member The Types.ps1xml files add properties and methods to all the instances of the objects of the specified .NET Framework type in the affected Windows PowerShell session. However, if you need to add properties or -methods only to one instance of an object, use the Add-Member cmdlet. +methods only to one instance of an object, use the `Add-Member` cmdlet. For more information, see [Add-Member](../../Microsoft.PowerShell.Utility/Add-Member.md). @@ -193,7 +188,7 @@ its creation time and the current time in days. It is easiest to use the original Types.ps1xml file as a template for the new file. The following command copies the original file to -a file called MyTypes.ps1xml in the $PSHOME directory. +a file called MyTypes.ps1xml in the `$PSHOME` directory. ```powershell Copy-Item Types.ps1xml MyTypes.ps1xml @@ -256,13 +251,13 @@ information about `Update-TypeData`, see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md).) ```powershell -Update-TypeData -PrependPath $PSHOME\MyTypes.ps1xml +Update-Typedata -PrependPath $PSHOME\MyTypes.ps1xml ``` To test the change, run a `Get-ChildItem` command to get the PowerShell.exe file in the `$PSHOME` directory, and then pipe the file to the `Format-List` cmdlet to list all of the properties of the file. As a -result of the change, the Age property appears in the list. +result of the change, the `Age` property appears in the list. ```powershell Get-ChildItem $PSHOME\PowerShell.exe | Format-List -Property * @@ -334,7 +329,7 @@ The `` tag must have a pair of `` tags that specify the name of the new method and a pair of `` tags that specify the code in which the method is defined. -For example, the `Mode` property of directories (`System.IO.DirectoryInfo` +For example, the Mode property of directories (`System.IO.DirectoryInfo` objects) is a code property defined in the Windows PowerShell FileSystem provider. @@ -345,7 +340,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -370,7 +367,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -391,7 +390,7 @@ In Types.ps1xml files, the `` tag is used to define the default views of the .NET Framework objects in Windows PowerShell. In this case, the name of the member set (the value within the `` tags) is always "PsStandardMembers", and the names of the properties -(the value of the tag) are one of the following: +(the value of the `` tag) are one of the following: - `DefaultDisplayProperty`: A single property of an object. @@ -438,7 +437,7 @@ The `` tag must have a pair of `` tags that specify the name of the new property and a pair of `` tags that specify the value of the property. -For example, the following XML creates a `Status` property for +For example, the following XML creates a Status property for directories (`System.IO.DirectoryInfo` objects). The value of the `Status` property is always "Success". @@ -473,7 +472,7 @@ properties for the default display of an object. You can identify the default displays by the value "PsStandardMembers" in the `` tag of a `` tag. -For example, the following XML creates a `Status` property for +For example, the following XML creates a Status property for directories (`System.IO.DirectoryInfo` objects). The value of the `Status` property is always "Success". @@ -495,7 +494,7 @@ property is always "Success". - + ``` ``: Defines a method whose value is the output of a script. @@ -511,21 +510,21 @@ methods of the `System.Management.ManagementDateTimeConverter` class. ```xml - System.Management.ManagementObject - - - ConvertToDateTime - - - - ConvertFromDateTime - - - + System.Management.ManagementObject + + + ConvertToDateTime + + + + ConvertFromDateTime + + + ``` @@ -548,7 +547,7 @@ property of the `GetVersionInfo` static method of VersionInfo - [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) + [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) @@ -586,8 +585,9 @@ use method syntax. ## Signing a Types.ps1xml File -To protect users of your Types.ps1xml file, you can sign the file using -a digital signature. For more information, see [about_Signing](about_Signing.md). +To protect users of your Types.ps1xml file, you can sign the file using a +digital signature. For more information, see +[about_Signing](about_Signing.md). # SEE ALSO @@ -595,7 +595,7 @@ a digital signature. For more information, see [about_Signing](about_Signing.md) [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md) -[Copy-ItemProperty](../../Microsoft.PowerShell.Management/Copy-Item.md) +[Copy-ItemProperty](../../Microsoft.PowerShell.Management/Copy-ItemProperty.md) [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) @@ -604,4 +604,3 @@ a digital signature. For more information, see [about_Signing](about_Signing.md) [Remove-TypeData](../../Microsoft.PowerShell.Utility/Remove-TypeData.md) [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md index 85125adac7b3..08ee68185fcb 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,86 +7,90 @@ title: about_WMI_Cmdlets --- # About WMI Cmdlets -## about_WMI_Cmdlets - ## SHORT DESCRIPTION -Provides background information about Windows Management Instrumentation (WMI) and Windows PowerShell? +Provides background information about Windows Management Instrumentation (WMI) +and Windows PowerShell. ## LONG DESCRIPTION -This topic provides information about WMI technology, the WMI cmdlets for Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI troubleshooting. This topic also provides links to more information about WMI. +This topic provides information about WMI technology, the WMI cmdlets for +Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI +troubleshooting. This topic also provides links to more information about WMI. ### ABOUT WMI -Windows Management Instrumentation (WMI) is the Microsoft implementation of Web-Based Enterprise Management (WBEM), which is an industry initiative to develop a standard technology for accessing management information in an enterprise environment. WMI uses the Common Information Model (CIM) industry standard to represent systems, applications, networks, devices, and other managed components. CIM is developed and maintained by the Distributed Management Task Force (DMTF). You can use WMI to manage both local and remote computers. For example, you can use WMI to do the following: - --- Start a process on a remote computer. - --- Restart a computer remotely. - --- Get a list of the applications that are installed on a local or remote computer. - --- Query the Windows event logs on a local or remote computer. +Windows Management Instrumentation (WMI) is the Microsoft implementation of +Web-Based Enterprise Management (WBEM), which is an industry initiative to +develop a standard technology for accessing management information in an +enterprise environment. WMI uses the Common Information Model (CIM) industry +standard to represent systems, applications, networks, devices, and other +managed components. CIM is developed and maintained by the Distributed +Management Task Force (DMTF). You can use WMI to manage both local and remote +computers. For example, you can use WMI to do the following: + +- Start a process on a remote computer. +- Restart a computer remotely. +- Get a list of the applications that are installed on a local or remote + computer. +- Query the Windows event logs on a local or remote computer. ### THE WMI CMDLETS FOR WINDOWS POWERSHELL -Windows PowerShell implements WMI functionality through a set of cmdlets that are available in Windows PowerShell by default. You can use these cmdlets to complete the end-to-end tasks necessary to manage local and remote computers. - -The following WMI cmdlets are included. +Windows PowerShell implements WMI functionality through a set of cmdlets that +are available in Windows PowerShell by default. You can use these cmdlets to +complete the end-to-end tasks necessary to manage local and remote computers. -``` -Cmdlet Description ------------------- ---------------------------------------------- -Get-WmiObject Gets instances of WMI classes or information - about the available classes. - -Invoke-WmiMethod Calls WMI methods. - -Register-WmiEvent Subscribes to a WMI event. - -Remove-WmiObject Deletes WMI classes and instances. - -Set-WmiInstance Creates or modifies instances of WMI classes. -``` - +The following WMI cmdlets are included. +|Cmdlet |Description | +|-----------------|----------------------------------------------| +|Get-WmiObject |Gets instances of WMI classes or information | +| |about the available classes. | +|Invoke-WmiMethod |Calls WMI methods. | +|Register-WmiEvent|Subscribes to a WMI event. | +|Remove-WmiObject |Deletes WMI classes and instances. | +|Set-WmiInstance |Creates or modifies instances of WMI classes. | ### SAMPLE COMMANDS The following command displays the BIOS information for the local computer. - -``` +```powershell C:\PS> get-wmiobject win32_bios | format-list * ``` +The following command displays information about the WinRM service for three +remote computers. -The following command displays information about the WinRM service for three remote computers. - - -``` -C:\PS> get-wmiobject -query "select * from win32_service where name='WinRM'" -computername server01, server01, server03 +```powershell +$wql = "select * from win32_service where name='WinRM'" +get-wmiobject -query $wql -computername server01, server01, server03 ``` - The following more complex command exits all instances of a program. - -``` -C:\PS> notepad.exe -C:\PS> $np = get-wmiobject -query "select * from win32_process where name='notepad.exe'" +```powershell +C:\PS> notepad.exe +C:\PS> $wql = "select * from win32_process where name='notepad.exe'" +C:\PS> $np = get-wmiobject -query $wql C:\PS> $np | remove-wmiobject ``` - - ### WMI-BASED REMOTING -While the ability to manage a local system through WMI is useful, it is the remoting capabilities that make WMI a powerful administrative tool. WMI uses Microsoft's Distributed Component Object Model (DCOM) to connect to and manage systems. You might have to configure some systems to allow DCOM connections. Firewall settings and locked-down DCOM permissions can block WMI's ability to remotely manage systems. +While the ability to manage a local system through WMI is useful, it is the +remoting capabilities that make WMI a powerful administrative tool. WMI uses +Microsoft's Distributed Component Object Model (DCOM) to connect to and manage +systems. You might have to configure some systems to allow DCOM connections. +Firewall settings and locked-down DCOM permissions can block WMI's ability to +remotely manage systems. ### WMI TYPE ACCELERATORS -Windows PowerShell includes WMI type accelerators. These WMI type accelerators (shortcuts) allow more direct access to a WMI objects than a non-type accelerator approach would allow. + +Windows PowerShell includes WMI type accelerators. These WMI type accelerators +(shortcuts) allow more direct access to a WMI objects than a non-type +accelerator approach would allow. The following type accelerators are supported with WMI: @@ -96,125 +100,117 @@ The following type accelerators are supported with WMI: [WMI] - A shortcut for getting a single instance of a class. -[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can take a string constructor to create a searcher that you can then do a GET() on. +[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can +take a string constructor to create a searcher that you can then do a GET() +on. For example: +```powershell +PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' +PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto +count __PATH name +----- ------ ---- +1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... +1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe +1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe +1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE +1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe +2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe ``` -PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' -PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto - -handlecount __PATH name ------------ ------ ---- -1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... -1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe -1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe -1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE -1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe -2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe -``` - -[WMICLASS] is a type accelerator for ManagementClass. This has a string constructor that takes a local or absolute WMI path to a WMI class and returns an object that is bound to that class. +[WMICLASS] is a type accelerator for ManagementClass. This has a string +constructor that takes a local or absolute WMI path to a WMI class and returns +an object that is bound to that class. For example: - -``` -PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" -PS> $c |fl * -Name : Win32_Process -__GENUS : 1 -__CLASS : Win32_Process -__SUPERCLASS : CIM_Process -__DYNASTY : CIM_ManagedSystemElement -__RELPATH : Win32_Process -__PROPERTY_COUNT : 45 -__DERIVATION : {CIM_Process, CIM_LogicalElement, CIM_ManagedSystemElement} -__SERVER : SERVER01 -__NAMESPACE : ROOT\cimv2 +```powershell +PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" +PS> $c |fl * +Name : Win32_Process +__GENUS : 1 +__CLASS : Win32_Process +__SUPERCLASS : CIM_Process +__DYNASTY : CIM_ManagedSystemElement +__RELPATH : Win32_Process +__PROPERTY_COUNT : 45 +__DERIVATION : {CIM_Process, CIM_LogicalElement, + CIM_ManagedSystemElement} +__SERVER : SERVER01 +__NAMESPACE : ROOT\cimv2 __PATH : \\SERVER01\ROOT\cimv2:Win32_Process ``` - -[WMI] is a type accelerator for ManagementObject. This has a string constructor that takes a local or absolute WMI path to a WMI instance and returns an object that is bound to that instance. +[WMI] is a type accelerator for ManagementObject. This has a string +constructor that takes a local or absolute WMI path to a WMI instance and +returns an object that is bound to that instance. For example: - -``` -PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' -PS> $p.Name +```powershell +PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' +PS> $p.Name OUTLOOK.EXE ``` - - ### WMI TROUBLESHOOTING -The following problems are the most common problems that might occur when you try to connect to a remote computer. -Problem 1: The remote computer is not online. - -If a computer is offline, you will not be able to connect to it by using WMI. You may receive the following error message: +The following problems are the most common problems that might occur when you +try to connect to a remote computer. +Problem 1: The remote computer is not online. -``` -"Remote server machine does not exist or is unavailable" -``` +If a computer is offline, you will not be able to connect to it by using WMI. +You may receive the following error message: + Remote server machine does not exist or is unavailable -If you receive this error message, verify that the computer is online. Try to ping the remote computer. +If you receive this error message, verify that the computer is online. Try to +ping the remote computer. Problem 2: You do not have local administrator rights on the remote computer. -To use WMI remotely, you must have local administrator rights on the remote computer. If you do not, access to that computer will be denied. +To use WMI remotely, you must have local administrator rights on the remote +computer. If you do not, access to that computer will be denied. To verify namespace security: -- a. Click Start, right-click My Computer, and then click Manage. - -- b. In Computer Management, expand Services and Applications, right-click WMI Control, and then click Properties. - -- c. In the WMI Control Properties dialog box, click the Security tab. +1. Click Start, right-click My Computer, and then click Manage. +2. In Computer Management, expand Services and Applications, right-click WMI + Control, and then click Properties. +3. In the WMI Control Properties dialog box, click the Security tab. Problem 3: A firewall is blocking access to the remote computer. -WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols to traverse the network. By default, many firewalls block DCOM and RPC traffic. If your firewall is blocking these protocols, your connection will fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is configured to automatically block all unsolicited network traffic, including DCOM and WMI. In its default configuration, Windows Firewall rejects an incoming WMI request, and you receive the following error message: - - -``` -"Remote server machine does not exist or is unavailable" -``` - +WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols +to traverse the network. By default, many firewalls block DCOM and RPC +traffic. If your firewall is blocking these protocols, your connection will +fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is +configured to automatically block all unsolicited network traffic, including +DCOM and WMI. In its default configuration, Windows Firewall rejects an +incoming WMI request, and you receive the following error message: + Remote server machine does not exist or is unavailable ### MORE INFORMATION ABOUT WMI -For more information about WMI, see the following topics in the MSDN (Microsoft Developer Network) library: - -``` -"About WMI: -http://go.microsoft.com/fwlink/?LinkId=142212 - -"WMI Troubleshooting" -http://go.microsoft.com/fwlink/?LinkId=142213 -``` +For more information about WMI, see the following topics in the MSDN +(Microsoft Developer Network) library: +About WMI: http://go.microsoft.com/fwlink/?LinkId=142212 -And, see "Secrets of Windows Management Instrumentation - Troubleshooting and Tips" in the Microsoft TechNet Script Center: +WMI Troubleshooting: http://go.microsoft.com/fwlink/?LinkId=142213 +And, see "Secrets of Windows Management Instrumentation - Troubleshooting and +Tips" in the Microsoft TechNet Script Center: -``` http://go.microsoft.com/fwlink/?LinkId=142214 -``` - ## SEE ALSO -Online version: http://go.microsoft.com/fwlink/?LinkId=142219 - Get-WmiObject Invoke-WmiMethod diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/About_Using.md b/reference/5.1/Microsoft.PowerShell.Core/About/About_Using.md index b6abbe721641..4fbccbdc21cf 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/About_Using.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/About_Using.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,7 +7,6 @@ title: about_Using --- # About Using -## about_Using # SHORT DESCRIPTION @@ -15,47 +14,49 @@ Allows to indicate which namespaces are used in the session. # LONG DESCRIPTION - -The `using` statement allows to indicate which namespaces are used in the session. -Making easier to mention classes and members, as it requires less typing to mention them; -also, classes from modules can be referenced too. +The `using` statement allows to indicate which namespaces are used in the +session. Making easier to mention classes and members, as it requires less +typing to mention them; also, classes from modules can be referenced too. The `using` statement needs to be the first statement in the script. Syntax #1, to reference .Net Framework namespaces: + ``` using namespace <.Net-framework-namespace> ``` Syntax #2, to reference PowerShell modules: + ``` using module ``` -> **Note** The `using` statetement, for modules, is intended to surface the classes in the module. -> If the module isn't loaded, the `using` fails. +**Note**: The `using` statetement, for modules, is intended to surface the +classes in the module. If the module isn't loaded, the `using` fails. ## Example 1 The following script gets the cryptographic hash for the "Hello World" string. -Note how the `using namespace System.Text` and `using namespace System.IO` simplify -the references to `[UnicodeEncoding]` in *System.Text*; and, to `[Stream]` -and to `[MemoryStream]` in *System.IO*. - +Note how the `using namespace System.Text` and `using namespace System.IO` +simplify the references to `[UnicodeEncoding]` in *System.Text*; and, to +`[Stream]` and to `[MemoryStream]` in *System.IO*. ```powershell - using namespace System.Text - using namespace System.IO +using namespace System.Text +using namespace System.IO - [string]$string = "Hello World" - [string]$algorithm = "SHA256" ## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MACTripleDES", "MD5", "RIPEMD160" +[string]$string = "Hello World" +## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MD5" +[string]$algorithm = "SHA256" - [byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) +[byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) - [Stream]$memorystream = [MemoryStream]::new($stringbytes) - $hashfromstream = Get-FileHash -InputStream $memorystream -Algorithm $algorithm - $hashfromstream.Hash.ToString() +[Stream]$memorystream = [MemoryStream]::new($stringbytes) +$hashfromstream = Get-FileHash -InputStream $memorystream ` + -Algorithm $algorithm +$hashfromstream.Hash.ToString() ``` ## Example 2 @@ -77,4 +78,3 @@ $deck.Shuffle() [Card[]]$hand2 = $deck.Deal(5) [Card[]]$hand3 = $deck.Deal(5) ``` - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md index 0d9fbe39f89d..10b1d7bc00db 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -74,20 +74,24 @@ are included. Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf ``` -The second example uses hash table splatting. The first command creates -a hash table of parameter-name and parameter-value pairs and stores it -in the $HashArguments variable. The second command uses the `$HashArguments` -variable in a command with splatting. The At symbol (`@HashArguments`) -replaces the dollar sign (`$HashArguments`) in the command. +The second example uses hash table splatting. The first command creates a hash +table of parameter-name and parameter-value pairs and stores it in the +\$HashArguments variable. The second command uses the `$HashArguments` variable +in a command with splatting. The At symbol (`@HashArguments`) replaces the +dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. ```powershell -$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true } +$HashArguments = @{ + Path = "test.txt" + Destination = "test2.txt" + WhatIf = $true +} Copy-Item @HashArguments ``` -*Note: In the first command, the At symbol (@) indicates a hash table, not +Note: In the first command, the At symbol (@) indicates a hash table, not a splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* @@ -106,11 +110,12 @@ omitted. The parameter values appear in position order in the command. Copy-Item "test.txt" "test2.txt" -WhatIf ``` -The second example uses array splatting. The first command creates an array -of the parameter values and stores it in the `$ArrayArguments` variable. The +The second example uses array splatting. The first command creates an array of +the parameter values and stores it in the `$ArrayArguments` variable. The values are in position order in the array. The second command uses the `$ArrayArguments` variable in a command in splatting. The At symbol -(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the command. +(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the +command. ```powershell $ArrayArguments = "test.txt", "test2.txt" @@ -120,10 +125,10 @@ Copy-Item @ArrayArguments -WhatIf # EXAMPLES -This example shows how to re-use splatted values in different commands. -The commands in this example use the Write-Host cmdlet to write messages -to the host program console. It uses splatting to specify the foreground -and background colors. +This example shows how to re-use splatted values in different commands. The +commands in this example use the Write-Host cmdlet to write messages to the +host program console. It uses splatting to specify the foreground and +background colors. To change the colors of all commands, just change the value of the `$Colors` variable. @@ -143,7 +148,8 @@ Write-Host command. To use the `$Colors variable`, replace the dollar sign #Write a message with the colors in $Colors Write-Host "This is a test." @Colors -#Write second message with same colors. The position of splatted hash table does not matter. +#Write second message with same colors. The position of splatted +#hash table does not matter. Write-Host @Colors "This is another test." ``` @@ -193,22 +199,19 @@ Test2 -a 1 -b 2 -c 3 # SPLATTING COMMAND PARAMETERS -You can use splatting to represent the parameters of -a command. This technique is useful when you are creating -a proxy function, that is, a function that calls another -command. This feature is introduced in Windows PowerShell 3.0. +You can use splatting to represent the parameters of a command. This technique +is useful when you are creating a proxy function, that is, a function that +calls another command. This feature is introduced in Windows PowerShell 3.0. -To splat the parameters of a command, use `@Args` to represent -the command parameters. This technique is easier than -enumerating command parameters and it works without revision -even if the parameters of the called command change. +To splat the parameters of a command, use `@Args` to represent the command +parameters. This technique is easier than enumerating command parameters and +it works without revision even if the parameters of the called command change. The feature uses the `$Args` automatic variable, which contains all unassigned parameter values. -For example, the following function calls the Get-Process -cmdlet. In this function, `@Args` represents all of the parameters -of the Get-Process cmdlet. +For example, the following function calls the Get-Process cmdlet. In this +function, `@Args` represents all of the parameters of the Get-Process cmdlet. ```powershell function Get-MyProcess { Get-Process @Args } @@ -223,20 +226,18 @@ Get-MyProcess -Name PowerShell Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -463 46 225484 237196 719 15.86 3228 powershell + 463 46 225484 237196 719 15.86 3228 powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo ProductVersion FileVersion FileName -------------- ----------- -------- -6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe +6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... ``` -You can use `@Args` in a function that has explicitly -declared parameters. You can use it more than once in -a function, but all parameters that you enter are passed -to all instances of `@Args`, as shown in the following -example. +You can use `@Args` in a function that has explicitly declared parameters. You +can use it more than once in a function, but all parameters that you enter are +passed to all instances of `@Args`, as shown in the following example. ```powershell function Get-MyCommand @@ -252,9 +253,9 @@ Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Extension : .exe -Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Visibility : Public OutputType : {System.String} Name : powershell.exe @@ -265,10 +266,11 @@ RemotingCapability : PowerShell Parameters : ParameterSets : HelpUri : -FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell + \v1.0\powershell.exe InternalName: POWERSHELL OriginalFilename: PowerShell.EXE.MUI - FileVersion: 10.0.14393.0 (rs1_release.160715-1616) + FileVersion: 10.0.14393.0 (rs1_release.160715-1616 FileDescription: Windows PowerShell Product: Microsoft® Windows® Operating System ProductVersion: 10.0.14393.0 @@ -289,4 +291,3 @@ FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1. [about_Hash_Tables](about_Hash_Tables.md) [about_Parameters](about_Parameters.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md index 9154bed7ea49..98b97dd2dab7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -19,22 +19,21 @@ The Split operator splits one or more strings into substrings. You can change the following elements of the Split operation: * Delimiter. The default is whitespace, but you can specify characters, -strings, patterns, or script blocks that specify the delimiter. The Split -operator in Windows PowerShell uses a regular expression in the delimiter, -rather than a simple character. + strings, patterns, or script blocks that specify the delimiter. The Split + operator in Windows PowerShell uses a regular expression in the delimiter, + rather than a simple character. * Maximum number of substrings. The default is to return all substrings. If -you specify a number less than the number of substrings, the remaining -substrings are concatenated in the last substring. + you specify a number less than the number of substrings, the remaining + substrings are concatenated in the last substring. * Options that specify the conditions under which the delimiter is matched, -such as SimpleMatch and Multiline. + such as SimpleMatch and Multiline. ## SYNTAX The following diagram shows the syntax for the -split operator. -The parameter names do not appear in the command. Include only the -parameter values. The values must appear in the order specified in the -syntax diagram. +The parameter names do not appear in the command. Include only the parameter +values. The values must appear in the order specified in the syntax diagram. ```powershell -Split @@ -45,17 +44,17 @@ syntax diagram. ``` You can substitute `-iSplit` or `-cSplit` for `-split` in any binary Split -statement (a Split statement that includes a delimiter or script block). -The `-iSplit` and `-split` operators are case-insensitive. The `-cSplit` -operator is case-sensitive, meaning that case is considered when the -delimiter rules are applied. +statement (a Split statement that includes a delimiter or script block). The +`-iSplit` and `-split` operators are case-insensitive. The `-cSplit` operator +is case-sensitive, meaning that case is considered when the delimiter rules +are applied. ## PARAMETERS ### \ -Specifies one or more strings to be split. If you submit multiple -strings, all the strings are split using the same delimiter rules. +Specifies one or more strings to be split. If you submit multiple strings, all +the strings are split using the same delimiter rules. Example: @@ -69,10 +68,10 @@ green ### \ -The characters that identify the end of a substring. The default delimiter -is whitespace, including spaces and non-printable characters, such as -newline (\`n) and tab (\`t). When the strings are split, the delimiter is -omitted from all the substrings. Example: +The characters that identify the end of a substring. The default delimiter is +whitespace, including spaces and non-printable characters, such as newline +(\`n) and tab (\`t). When the strings are split, the delimiter is omitted from +all the substrings. Example: ```powershell "Lastname:FirstName:Address" -split ":" @@ -81,13 +80,13 @@ FirstName Address ``` -By default, the delimiter is omitted from the results. To preserve all or -part of the delimiter, enclose in parentheses the part that you want to -preserve. If the \ parameter is added, this takes -precedence when your command splits up the collection. If you opt to -include a delimiter as part of the output, the command returns the -delimiter as part of the output; however, splitting the string to return -the delimiter as part of output does not count as a split. +By default, the delimiter is omitted from the results. To preserve all or part +of the delimiter, enclose in parentheses the part that you want to preserve. +If the \ parameter is added, this takes precedence when your +command splits up the collection. If you opt to include a delimiter as part of +the output, the command returns the delimiter as part of the output; however, +splitting the string to return the delimiter as part of output does not count +as a split. Examples: @@ -124,17 +123,16 @@ Strawberry-Blueberry ### \ -Specifies the maximum number of times that a string is split. The default -is all the substrings split by the delimiter. If there are more substrings, -they are concatenated to the final substring. If there are fewer -substrings, all the substrings are returned. A value of 0 and negative -values return all the substrings. +Specifies the maximum number of times that a string is split. The default is +all the substrings split by the delimiter. If there are more substrings, they +are concatenated to the final substring. If there are fewer substrings, all +the substrings are returned. A value of 0 and negative values return all the +substrings. Max-substrings does not specify the maximum number of objects that are -returned; its value equals the maximum number of times that a string is -split. If you submit more than one string (an array of strings) to the -Split operator , the Max-substrings limit is applied to each string -separately. +returned; its value equals the maximum number of times that a string is split. +If you submit more than one string (an array of strings) to the Split operator +, the Max-substrings limit is applied to each string separately. Example: @@ -150,9 +148,8 @@ Jupiter,Saturn,Uranus,Neptune ### \ -An expression that specifies rules for applying the delimiter. The -expression must evaluate to $true or $false. Enclose the script block in -braces. +An expression that specifies rules for applying the delimiter. The expression +must evaluate to $true or $false. Enclose the script block in braces. Example: @@ -187,63 +184,62 @@ The syntax for the Options parameter is: The SimpleMatch options are: * **SimpleMatch**: Use simple string comparison when evaluating the -delimiter. Cannot be used with RegexMatch. + delimiter. Cannot be used with RegexMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. The RegexMatch options are: * **RegexMatch**: Use regular expression matching to evaluate the -delimiter. This is the default behavior. Cannot be used with -SimpleMatch. + delimiter. This is the default behavior. Cannot be used with + SimpleMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. * **CultureInvariant**: Ignores cultural differences in language -when evaluting the delimiter. Valid only with RegexMatch. + when evaluting the delimiter. Valid only with RegexMatch. * IgnorePatternWhitespace: Ignores unescaped whitespace and -comments marked with the number sign (#). Valid only with -RegexMatch. + comments marked with the number sign (#). Valid only with + RegexMatch. * **Multiline**: Multiline mode recognizes the start and end of lines -and strings. Valid only with RegexMatch. Singleline is the default. + and strings. Valid only with RegexMatch. Singleline is the default. * **Singleline**: Singleline mode recognizes only the start and end of -strings. Valid only with RegexMatch. Singleline is the default. + strings. Valid only with RegexMatch. Singleline is the default. * **ExplicitCapture**: Ignores non-named match groups so that only -explicit capture groups are returned in the result list. Valid -only with RegexMatch. + explicit capture groups are returned in the result list. Valid + only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the -unary split operator, only the first string (before the first comma) is -split. +unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( --split ). Enclose all the strings in parentheses, or store the -strings in a variable, and then submit the variable to the split operator. +To split more than one string, use the binary split operator ( -split +). Enclose all the strings in parentheses, or store the strings in +a variable, and then submit the variable to the split operator. Consider the following example: ```powershell -PS C:\> -split "1 2", "a b" +PS > -split "1 2", "a b" 1 2 a b -PS C:\> "1 2", "a b" -split " " +PS > "1 2", "a b" -split " " 1 2 a b -PS C:\> -split ("1 2", "a b") +PS > -split ("1 2", "a b") 1 2 a b -PS C:\> $a = "1 2", "a b" -PS C:\> -split $a +PS > $a = "1 2", "a b" +PS > -split $a 1 2 a @@ -255,7 +251,7 @@ b The following statement splits the string at whitespace. ```powershell -PS C:\> -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" Windows PowerShell 2.0 @@ -268,7 +264,7 @@ remoting The following statement splits the string at any comma. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' Mercury Venus Earth @@ -282,17 +278,16 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune ``` -The following statement performs a case-sensitive split at the -letter "N". +The following statement performs a case-sensitive split at the letter "N". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -300,7 +295,7 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' M rcury,V nus, @@ -317,7 +312,8 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` + -split '[er]', 6 M cu @@ -329,7 +325,7 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS C:\> "a,b,c,d,e,f,g,h" -split ",", 3 +PS > "a,b,c,d,e,f,g,h" -split ",", 3 a b c,d,e,f,g,h @@ -339,7 +335,7 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS C:\> "a,b,c,d", "e,f,g,h" -split ",", 3 +PS > "a,b,c,d", "e,f,g,h" -split ",", 3 a b c,d @@ -352,18 +348,18 @@ The following statement splits each line in the here-string at the first digit. It uses the Multiline option to recognize the beginning of each line and string. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as Multiline, only when the Max-substrings value -is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as Multiline, only when the Max-substrings value is +specified. ```powershell -PS C:\> $a = @' +PS > $a = @' 1The first line. 2The second line. 3The third of three lines. '@ -PS C:\> $a -split "^\d", 0, "multiline" +PS > $a -split "^\d", 0, "multiline" The first line. @@ -380,12 +376,12 @@ interpreted to match any character except for a newline character. As a result, the Split statement returns a blank line for every character except newline. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as SimpleMatch, only when the Max-substrings -value is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as SimpleMatch, only when the Max-substrings value is +specified. ```powershell -PS C:\> "This.is.a.test" -split ".", 0, "simplematch" +PS > "This.is.a.test" -split ".", 0, "simplematch" This is @@ -393,13 +389,13 @@ a test ``` -The following statement splits the string at one of two delimiters, -depending on the value of a variable. +The following statement splits the string at one of two delimiters, depending +on the value of a variable. ```powershell -PS C:\> $i = 1 -PS C:\> $c = "LastName, FirstName; Address, City, State, Zip" -PS C:\> $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +PS > $i = 1 +PS > $c = "LastName, FirstName; Address, City, State, Zip" +PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} LastName, FirstName Address, City, State, Zip @@ -407,7 +403,7 @@ Address, City, State, Zip ## SEE ALSO -Split-Path +[Split-Path](../../Microsoft.PowerShell.Management/Split-Path.md) [about_Operators](about_Operators.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md index 90658fd83ff1..1bfafbe78470 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -148,13 +148,25 @@ Default clause is permitted in each Switch statement. Switch has the following parameters: -|Parameter|Description| -|---|---| -| Wildcard | Indicates that the condition is a wildcard string. If you use Wildcard, Regex and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| Exact | Indicates that the match clause, if it is a string, must match exactly. If you use Exact, Regex and Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| CaseSensitive | Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. | -| File | Takes input from a file rather than a value statement. If multiple File parameters are included, only the last one is used. Each line of the file is read and evaluated by the Switch statement. | -| Regex | Performs regular expression matching of the value to the condition. If you use Regex, Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | +|Parameter |Description | +|-------------|-----------------------------------------------------------| +|Wildcard |Indicates that the condition is a wildcard string. If you | +| |you use Wildcard, Regex and Exact are ignored. Also, if | +| |the match clause is not a string, the parameter is ignored.| +|Exact |Indicates that the match clause, if it is a string, must | +| |match exactly. Regex and Wildcard and Exact are ignored. | +| |Also, if the match clause is not a string, this parameter | +| |is ignored. | +|CaseSensitive|Performs a case-sensitive match. If the match clause is not| +| |a string, this parameter is ignored. | +|File |Takes input from a file rather than a value statement. If | +| |multiple File parameters are included, only the last one is| +| |used. Each line of the file is read and evaluated by the | +| |Switch statement. | +|Regex |Performs regular expression matching of the value to the | +| |condition. Wildcard and Exact are ignored. Also, if the | +| |match clause is not a string, this parameter is ignored. | + ```powershell Example: diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Throw.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Throw.md index 2deea43ade1b..08fe2f6e5c7e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Throw.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Throw.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,16 +14,16 @@ Describes the Throw keyword, which generates a terminating error. ## LONG DESCRIPTION -The Throw keyword causes a terminating error. You can use the Throw keyword -to stop the processing of a command, function, or script. +The Throw keyword causes a terminating error. You can use the Throw keyword to +stop the processing of a command, function, or script. For example, you can use the Throw keyword in the script block of an If statement to respond to a condition or in the Catch block of a -Try-Catch-Finally statement. You can also use the Throw keyword in a -parameter declaration to make a function parameter mandatory. +Try-Catch-Finally statement. You can also use the Throw keyword in a parameter +declaration to make a function parameter mandatory. -The Throw keyword can throw any object, such as a user message string or -the object that caused the error. +The Throw keyword can throw any object, such as a user message string or the +object that caused the error. ## SYNTAX @@ -33,8 +33,8 @@ The syntax of the Throw keyword is as follows: throw [] ``` -The expression in the Throw syntax is optional. When the Throw statement -does not appear in a Catch block, and it does not include an expression, it +The expression in the Throw syntax is optional. When the Throw statement does +not appear in a Catch block, and it does not include an expression, it generates a ScriptHalted error. ```powershell @@ -47,13 +47,14 @@ At line:1 char:6 + FullyQualifiedErrorId : ScriptHalted ``` -If the Throw keyword is used in a Catch block without an expression, it -throws the current RuntimeException again. For more information, see +If the Throw keyword is used in a Catch block without an expression, it throws +the current RuntimeException again. For more information, see about_Try_Catch_Finally. ## THROWING A STRING -The optional expression in a Throw statement can be a string, as shown in -the following example: + +The optional expression in a Throw statement can be a string, as shown in the +following example: ```powershell C:\PS> throw "This is an error." @@ -61,7 +62,8 @@ C:\PS> throw "This is an error." This is an error. At line:1 char:6 + throw <<<< "This is an error." -+ CategoryInfo : OperationStopped: (This is an error.:String) [], RuntimeException ++ CategoryInfo : OperationStopped: (This is an error.:String) [], R +untimeException + FullyQualifiedErrorId : This is an error. ``` @@ -76,7 +78,8 @@ C:\PS> throw (get-process PowerShell) System.Diagnostics.Process (PowerShell) At line:1 char:6 + throw <<<< (get-process PowerShell) -+ CategoryInfo : OperationStopped: (System.Diagnostics.Process (PowerShell):Process) [], ++ CategoryInfo : OperationStopped: (System.Diagnostics.Process (Pow +erShell):Process) [], RuntimeException + FullyQualifiedErrorId : System.Diagnostics.Process (PowerShell) ``` @@ -105,15 +108,16 @@ One of the identified items was in an invalid format. At line:1 char:6 + throw <<<< $formatError + CategoryInfo : OperationStopped: (:) [], FormatException -+ FullyQualifiedErrorId : One of the identified items was in an invalid format. ++ FullyQualifiedErrorId : One of the identified items was in an invalid +format. ``` ## RESULTING ERROR -The Throw keyword can generate an ErrorRecord object. The Exception -property of the ErrorRecord object contains a RuntimeException object. The -remainder of the ErrorRecord object and the RuntimeException object vary -with the object that the Throw keyword throws. +The Throw keyword can generate an ErrorRecord object. The Exception property +of the ErrorRecord object contains a RuntimeException object. The remainder of +the ErrorRecord object and the RuntimeException object vary with the object +that the Throw keyword throws. The RunTimeException object is wrapped in an ErrorRecord object, and the ErrorRecord object is automatically saved in the $Error automatic variable. @@ -139,7 +143,9 @@ optional. function Get-XMLFiles { param ($path = $(throw "The Path parameter is required.")) - dir -path $path\*.xml -recurse | sort lastwritetime | ft lastwritetime, attributes, name -auto + dir -path $path\*.xml -recurse | + sort lastwritetime | + ft lastwritetime, attributes, name -auto } ``` @@ -154,4 +160,3 @@ function Get-XMLFiles [about_Trap](about_Trap.md) [about_Try_Catch_Finally](about_Try_Catch_Finally.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md index 338030fa058b..bc042324bc4b 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Trap.md @@ -130,7 +130,9 @@ statement that specifies the CommandNotFoundException type. ```powershell trap {"Other terminating error trapped" } -trap [System.Management.Automation.CommandNotFoundException] {"Command error trapped"} +trap [System.Management.Automation.CommandNotFoundException] { + "Command error trapped" +} nonsenseString ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Operators.md index a94e962d87b3..531eb8a2f9da 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Type_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-091 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -26,11 +26,16 @@ fails, it returns nothing. It does not return an error. The following table lists the type operators in Windows PowerShell. -|Operator|Description|Example| -|---|---|---| -|`-is`|Returns TRUE when the input is an instance of the specified.NET Framework type.|`C:\PS> (get-date) -is [DateTime]`
`True`| -|`-isNot`|Returns TRUE when the input is not an instance of the specified.NET Framework type.|`C:\PS> (get-date) -isNot [DateTime]`
`False`| -|`-as`|Converts the input to the specified.NET Framework type.|`C:\PS> 12/31/07 -as [DateTime]`
`Monday, December 31, 2007 12:00:00 AM`| +|Operator|Description |Example | +|--------|---------------------------|---------------------------------| +|`-is` |Returns TRUE when the input|`(get-date) -is [DateTime]` | +| |is an instance of the |`True` | +| |specified .NET type. | | +|`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]` | +| |not an instance of the |`False` | +| |specified.NET type. | | +|`-as` |Converts the input to the |`"5/7/07" -as [DateTime]` | +| |specified .NET type. |`Monday, May 7, 2007 12:00:00 AM`| The syntax of the type operators is as follows: @@ -64,7 +69,7 @@ property of this method. For example, the following statement gets the type of the return value of a Get-Culture command: ```powershell -C:\PS> (get-culture).gettype().fullname +PS> (get-culture).gettype().fullname System.Globalization.CultureInfo ``` @@ -72,25 +77,25 @@ System.Globalization.CultureInfo The following examples show some uses of the Type operators: ```powershell -C:\PS> 32 -is [Float] +PS> 32 -is [Float] False -C:\PS> 32 -is "int" +PS> 32 -is "int" True -C:\PS> (get-date) -is [DateTime] +PS> (get-date) -is [DateTime] True -C:\PS> "12/31/2007" -is [DateTime] +PS> "12/31/2007" -is [DateTime] False -C:\PS> "12/31/2007" -is [String] +PS> "12/31/2007" -is [String] True -C:\PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] +PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] True -C:\PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] +PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] True ``` @@ -103,53 +108,55 @@ return System.Globalization.CultureInfo objects, a collection of these objects is a System.Object array. ```powershell -C:\PS> (get-culture) -is [System.Globalization.CultureInfo] +PS> (get-culture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-uiculture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] False -C:\PS> (get-culture), (get-uiculture) -is [Array] +PS> (get-culture), (get-uiculture) -is [Array] True -C:\PS> (get-culture), (get-uiculture) | foreach {$_ -is [System.Globalization.CultureInfo]) +PS> (get-culture), (get-uiculture) | foreach { + $_ -is [System.Globalization.CultureInfo]) +} True True -C:\PS> (get-culture), (get-uiculture) -is [Object] +PS> (get-culture), (get-uiculture) -is [Object] True ``` The following examples show how to use the -as operator. ```powershell -C:\PS> "12/31/07" -is [DateTime] +PS> "12/31/07" -is [DateTime] False -C:\PS> "12/31/07" -as [DateTime] +PS> "12/31/07" -as [DateTime] Monday, December 31, 2007 12:00:00 AM -C:\PS> $date = "12/31/07" -as [DateTime] +PS> $date = "12/31/07" -as [DateTime] C:\PS>$a -is [DateTime] True -C:\PS> 1031 -as [System.Globalization.CultureInfo] +PS> 1031 -as [System.Globalization.CultureInfo] -LCID Name DisplayName ----- ---- ----------- -1031 de-DE German (Germany) +LCID Name DisplayName +---- ---- ----------- +1031 de-DE German (Germany) ``` The following example shows that when the -as operator cannot convert the input object to the .NET Framework type, it returns nothing. ```powershell -C:\PS> 1031 -as [System.Diagnostic.Process] -C:\PS> +PS> 1031 -as [System.Diagnostic.Process] +PS> ``` ## SEE ALSO diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index 96d2292ea00c..3888516c6096 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Types.ps1xml --- # About Types.ps1xml -## about_Types.ps1xml - - # SHORT DESCRIPTION @@ -27,16 +24,16 @@ extended type data to a Windows PowerShell session. extended data for types in the current session. This topic describes Types.ps1xml files. For more information about using the -`Update-TypeData` cmdlet to add dynamic extended type data to the current session -see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). +`Update-TypeData` cmdlet to add dynamic extended type data to the current +session see +[Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). ## About Extended Type Data -Extended type data defines additional properties and methods ("members") -of object types in Windows PowerShell. You can extend any type that is -supported by Windows PowerShell and use the added properties and methods -in the same way that you use the properties that are defined on the object -types. +Extended type data defines additional properties and methods ("members") of +object types in Windows PowerShell. You can extend any type that is supported +by Windows PowerShell and use the added properties and methods in the same way +that you use the properties that are defined on the object types. For example, Windows PowerShell adds a `DateTime` property to all `System.DateTime` objects, such as the ones that the `Get-Date` cmdlet @@ -47,27 +44,27 @@ PS C:> (Get-Date).DateTime Sunday, January 29, 2012 9:43:57 AM ``` -You won't find the `DateTime` property in the description of the [`System.DateTime` -structure](http://msdn.microsoft.com/library/system.datetime.aspx), -because Windows PowerShell adds the property and it is visible only in -Windows PowerShell. +You won't find the `DateTime` property in the description of the +[`System.DateTime` structure](http://msdn.microsoft.com/library/system.datetime.aspx), +because Windows PowerShell adds the property and it is visible only in Windows +PowerShell. -To add the `DateTime` property to all Windows PowerShell sessions, Windows PowerShell -defines the `DateTime` property in the Types.ps1xml file in the Windows PowerShell -installation directory (`$PSHOME`). +To add the `DateTime` property to all Windows PowerShell sessions, Windows +PowerShell defines the `DateTime` property in the Types.ps1xml file in the +Windows PowerShell installation directory (`$PSHOME`). ## Adding Extended Type Data to Windows PowerShell. There are three sources of extended type data in Windows PowerShell sessions. - The Types.ps1xml files in the Windows PowerShell installation directory -are loaded automatically into every Windows PowerShell session. + are loaded automatically into every Windows PowerShell session. - The Types.ps1xml files that modules export are loaded when the module -is imported into the current session. + is imported into the current session. - Extended type data that is defined by using the `Update-TypeData` cmdlet -is added only to the current session. It is not saved in a file. + is added only to the current session. It is not saved in a file. In the session, the extended type data from the three sources is applied to objects in the same way and is available on all objects of the specified @@ -78,11 +75,10 @@ types. The following TypeData cmdlets are included in the Microsoft.PowerShell.Utility module in Windows PowerShell 3.0 and later versions of Windows PowerShell. -| | | -| --------------- | --------------------------------------------------------------- | -| Get-TypeData | Gets extended type data in the current session. | -| Update-TypeData | Reloads Types.ps1xml files. Adds extended type data to the current session. | -| Remove-TypeData | Removes extended type data from the current session. +- `Get-TypeData`: Gets extended type data in the current session. +- `Update-TypeData`: Reloads Types.ps1xml files. Adds extended type data to the + current session. +- `Remove-TypeData`: Removes extended type data from the current session. For more information about these cmdlets, see the help topic for each cmdlet. @@ -118,8 +114,8 @@ value. The following XML adds the Count property to the `System.Array` type. ``` -To get the new `AliasProperty`, use a `Get-Member` command on any array, as shown -in the following example. +To get the new `AliasProperty`, use a `Get-Member` command on any array, as +shown in the following example. ```powershell Get-Member -InputObject (1,2,3,4) @@ -127,15 +123,15 @@ Get-Member -InputObject (1,2,3,4) The command returns the following results. -```powershell -Name MemberType Definition ----- ---------- ---------- -Count AliasProperty Count = Length -Address Method System.Object& Address(Int32) -Clone Method System.Object Clone() -CopyTo Method System.Void CopyTo(Array array, Int32 index): -Equals Method System.Boolean Equals(Object obj) -Get Method System.Object Get(Int32) +```output +Name MemberType Definition +---- ---------- ---------- +Count AliasProperty Count = Length +Address Method System.Object& Address(Int32) +Clone Method System.Object Clone() +CopyTo Method System.Void CopyTo(Array array, Int32 index): +Equals Method System.Boolean Equals(Object obj) +Get Method System.Object Get(Int32) # ... ``` @@ -344,7 +340,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -369,7 +367,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -510,21 +510,21 @@ methods of the `System.Management.ManagementDateTimeConverter` class. ```xml - System.Management.ManagementObject - - - ConvertToDateTime - - - - ConvertFromDateTime - - - + System.Management.ManagementObject + + + ConvertToDateTime + + + + ConvertFromDateTime + + + ``` @@ -547,7 +547,7 @@ property of the `GetVersionInfo` static method of VersionInfo - [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) + [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) @@ -585,8 +585,9 @@ use method syntax. ## Signing a Types.ps1xml File -To protect users of your Types.ps1xml file, you can sign the file using -a digital signature. For more information, see [about_Signing](about_Signing.md). +To protect users of your Types.ps1xml file, you can sign the file using a +digital signature. For more information, see +[about_Signing](about_Signing.md). # SEE ALSO @@ -603,4 +604,3 @@ a digital signature. For more information, see [about_Signing](about_Signing.md) [Remove-TypeData](../../Microsoft.PowerShell.Utility/Remove-TypeData.md) [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md index 8f2a53213e37..08ee68185fcb 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,86 +7,90 @@ title: about_WMI_Cmdlets --- # About WMI Cmdlets -## about_WMI_Cmdlets - ## SHORT DESCRIPTION -Provides background information about Windows Management Instrumentation (WMI) and Windows PowerShell. +Provides background information about Windows Management Instrumentation (WMI) +and Windows PowerShell. ## LONG DESCRIPTION -This topic provides information about WMI technology, the WMI cmdlets for Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI troubleshooting. This topic also provides links to more information about WMI. +This topic provides information about WMI technology, the WMI cmdlets for +Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI +troubleshooting. This topic also provides links to more information about WMI. ### ABOUT WMI -Windows Management Instrumentation (WMI) is the Microsoft implementation of Web-Based Enterprise Management (WBEM), which is an industry initiative to develop a standard technology for accessing management information in an enterprise environment. WMI uses the Common Information Model (CIM) industry standard to represent systems, applications, networks, devices, and other managed components. CIM is developed and maintained by the Distributed Management Task Force (DMTF). You can use WMI to manage both local and remote computers. For example, you can use WMI to do the following: - --- Start a process on a remote computer. - --- Restart a computer remotely. - --- Get a list of the applications that are installed on a local or remote computer. - --- Query the Windows event logs on a local or remote computer. +Windows Management Instrumentation (WMI) is the Microsoft implementation of +Web-Based Enterprise Management (WBEM), which is an industry initiative to +develop a standard technology for accessing management information in an +enterprise environment. WMI uses the Common Information Model (CIM) industry +standard to represent systems, applications, networks, devices, and other +managed components. CIM is developed and maintained by the Distributed +Management Task Force (DMTF). You can use WMI to manage both local and remote +computers. For example, you can use WMI to do the following: + +- Start a process on a remote computer. +- Restart a computer remotely. +- Get a list of the applications that are installed on a local or remote + computer. +- Query the Windows event logs on a local or remote computer. ### THE WMI CMDLETS FOR WINDOWS POWERSHELL -Windows PowerShell implements WMI functionality through a set of cmdlets that are available in Windows PowerShell by default. You can use these cmdlets to complete the end-to-end tasks necessary to manage local and remote computers. - -The following WMI cmdlets are included. +Windows PowerShell implements WMI functionality through a set of cmdlets that +are available in Windows PowerShell by default. You can use these cmdlets to +complete the end-to-end tasks necessary to manage local and remote computers. -``` -Cmdlet Description ------------------- ---------------------------------------------- -Get-WmiObject Gets instances of WMI classes or information - about the available classes. - -Invoke-WmiMethod Calls WMI methods. - -Register-WmiEvent Subscribes to a WMI event. - -Remove-WmiObject Deletes WMI classes and instances. - -Set-WmiInstance Creates or modifies instances of WMI classes. -``` - +The following WMI cmdlets are included. +|Cmdlet |Description | +|-----------------|----------------------------------------------| +|Get-WmiObject |Gets instances of WMI classes or information | +| |about the available classes. | +|Invoke-WmiMethod |Calls WMI methods. | +|Register-WmiEvent|Subscribes to a WMI event. | +|Remove-WmiObject |Deletes WMI classes and instances. | +|Set-WmiInstance |Creates or modifies instances of WMI classes. | ### SAMPLE COMMANDS The following command displays the BIOS information for the local computer. - -``` +```powershell C:\PS> get-wmiobject win32_bios | format-list * ``` +The following command displays information about the WinRM service for three +remote computers. -The following command displays information about the WinRM service for three remote computers. - - -``` -C:\PS> get-wmiobject -query "select * from win32_service where name='WinRM'" -computername server01, server01, server03 +```powershell +$wql = "select * from win32_service where name='WinRM'" +get-wmiobject -query $wql -computername server01, server01, server03 ``` - The following more complex command exits all instances of a program. - -``` -C:\PS> notepad.exe -C:\PS> $np = get-wmiobject -query "select * from win32_process where name='notepad.exe'" +```powershell +C:\PS> notepad.exe +C:\PS> $wql = "select * from win32_process where name='notepad.exe'" +C:\PS> $np = get-wmiobject -query $wql C:\PS> $np | remove-wmiobject ``` - - ### WMI-BASED REMOTING -While the ability to manage a local system through WMI is useful, it is the remoting capabilities that make WMI a powerful administrative tool. WMI uses Microsoft's Distributed Component Object Model (DCOM) to connect to and manage systems. You might have to configure some systems to allow DCOM connections. Firewall settings and locked-down DCOM permissions can block WMI's ability to remotely manage systems. +While the ability to manage a local system through WMI is useful, it is the +remoting capabilities that make WMI a powerful administrative tool. WMI uses +Microsoft's Distributed Component Object Model (DCOM) to connect to and manage +systems. You might have to configure some systems to allow DCOM connections. +Firewall settings and locked-down DCOM permissions can block WMI's ability to +remotely manage systems. ### WMI TYPE ACCELERATORS -Windows PowerShell includes WMI type accelerators. These WMI type accelerators (shortcuts) allow more direct access to a WMI objects than a non-type accelerator approach would allow. + +Windows PowerShell includes WMI type accelerators. These WMI type accelerators +(shortcuts) allow more direct access to a WMI objects than a non-type +accelerator approach would allow. The following type accelerators are supported with WMI: @@ -96,123 +100,116 @@ The following type accelerators are supported with WMI: [WMI] - A shortcut for getting a single instance of a class. -[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can take a string constructor to create a searcher that you can then do a GET() on. +[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can +take a string constructor to create a searcher that you can then do a GET() +on. For example: +```powershell +PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' +PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto +count __PATH name +----- ------ ---- +1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... +1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe +1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe +1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE +1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe +2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe ``` -PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' -PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto - -handlecount __PATH name ------------ ------ ---- -1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... -1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe -1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe -1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE -1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe -2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe -``` - -[WMICLASS] is a type accelerator for ManagementClass. This has a string constructor that takes a local or absolute WMI path to a WMI class and returns an object that is bound to that class. +[WMICLASS] is a type accelerator for ManagementClass. This has a string +constructor that takes a local or absolute WMI path to a WMI class and returns +an object that is bound to that class. For example: - -``` -PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" -PS> $c |fl * -Name : Win32_Process -__GENUS : 1 -__CLASS : Win32_Process -__SUPERCLASS : CIM_Process -__DYNASTY : CIM_ManagedSystemElement -__RELPATH : Win32_Process -__PROPERTY_COUNT : 45 -__DERIVATION : {CIM_Process, CIM_LogicalElement, CIM_ManagedSystemElement} -__SERVER : SERVER01 -__NAMESPACE : ROOT\cimv2 +```powershell +PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" +PS> $c |fl * +Name : Win32_Process +__GENUS : 1 +__CLASS : Win32_Process +__SUPERCLASS : CIM_Process +__DYNASTY : CIM_ManagedSystemElement +__RELPATH : Win32_Process +__PROPERTY_COUNT : 45 +__DERIVATION : {CIM_Process, CIM_LogicalElement, + CIM_ManagedSystemElement} +__SERVER : SERVER01 +__NAMESPACE : ROOT\cimv2 __PATH : \\SERVER01\ROOT\cimv2:Win32_Process ``` - -[WMI] is a type accelerator for ManagementObject. This has a string constructor that takes a local or absolute WMI path to a WMI instance and returns an object that is bound to that instance. +[WMI] is a type accelerator for ManagementObject. This has a string +constructor that takes a local or absolute WMI path to a WMI instance and +returns an object that is bound to that instance. For example: - -``` -PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' -PS> $p.Name +```powershell +PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' +PS> $p.Name OUTLOOK.EXE ``` - - ### WMI TROUBLESHOOTING -The following problems are the most common problems that might occur when you try to connect to a remote computer. -Problem 1: The remote computer is not online. - -If a computer is offline, you will not be able to connect to it by using WMI. You may receive the following error message: +The following problems are the most common problems that might occur when you +try to connect to a remote computer. +Problem 1: The remote computer is not online. -``` -"Remote server machine does not exist or is unavailable" -``` +If a computer is offline, you will not be able to connect to it by using WMI. +You may receive the following error message: + Remote server machine does not exist or is unavailable -If you receive this error message, verify that the computer is online. Try to ping the remote computer. +If you receive this error message, verify that the computer is online. Try to +ping the remote computer. Problem 2: You do not have local administrator rights on the remote computer. -To use WMI remotely, you must have local administrator rights on the remote computer. If you do not, access to that computer will be denied. +To use WMI remotely, you must have local administrator rights on the remote +computer. If you do not, access to that computer will be denied. To verify namespace security: -- a. Click Start, right-click My Computer, and then click Manage. - -- b. In Computer Management, expand Services and Applications, right-click WMI Control, and then click Properties. - -- c. In the WMI Control Properties dialog box, click the Security tab. +1. Click Start, right-click My Computer, and then click Manage. +2. In Computer Management, expand Services and Applications, right-click WMI + Control, and then click Properties. +3. In the WMI Control Properties dialog box, click the Security tab. Problem 3: A firewall is blocking access to the remote computer. -WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols to traverse the network. By default, many firewalls block DCOM and RPC traffic. If your firewall is blocking these protocols, your connection will fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is configured to automatically block all unsolicited network traffic, including DCOM and WMI. In its default configuration, Windows Firewall rejects an incoming WMI request, and you receive the following error message: - - -``` -"Remote server machine does not exist or is unavailable" -``` - +WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols +to traverse the network. By default, many firewalls block DCOM and RPC +traffic. If your firewall is blocking these protocols, your connection will +fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is +configured to automatically block all unsolicited network traffic, including +DCOM and WMI. In its default configuration, Windows Firewall rejects an +incoming WMI request, and you receive the following error message: + Remote server machine does not exist or is unavailable ### MORE INFORMATION ABOUT WMI -For more information about WMI, see the following topics in the MSDN (Microsoft Developer Network) library: +For more information about WMI, see the following topics in the MSDN +(Microsoft Developer Network) library: -``` -"About WMI: -http://go.microsoft.com/fwlink/?LinkId=142212 - -"WMI Troubleshooting" -http://go.microsoft.com/fwlink/?LinkId=142213 -``` - +About WMI: http://go.microsoft.com/fwlink/?LinkId=142212 -And, see "Secrets of Windows Management Instrumentation - Troubleshooting and Tips" in the Microsoft TechNet Script Center: +WMI Troubleshooting: http://go.microsoft.com/fwlink/?LinkId=142213 +And, see "Secrets of Windows Management Instrumentation - Troubleshooting and +Tips" in the Microsoft TechNet Script Center: -``` http://go.microsoft.com/fwlink/?LinkId=142214 -``` - ## SEE ALSO -Online version: http:\/\/go.microsoft.com\/fwlink\/?LinkId\=142219 Get-WmiObject diff --git a/reference/6/Microsoft.PowerShell.Core/About/About_Using.md b/reference/6/Microsoft.PowerShell.Core/About/About_Using.md index f834a0324955..4fbccbdc21cf 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/About_Using.md +++ b/reference/6/Microsoft.PowerShell.Core/About/About_Using.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,7 +7,6 @@ title: about_Using --- # About Using -## about_Using # SHORT DESCRIPTION @@ -15,47 +14,49 @@ Allows to indicate which namespaces are used in the session. # LONG DESCRIPTION - -The `using` statement allows to indicate which namespaces are used in the session. -Making easier to mention classes and members, as it requires less typing to mention them; -also, classes from modules can be referenced too. +The `using` statement allows to indicate which namespaces are used in the +session. Making easier to mention classes and members, as it requires less +typing to mention them; also, classes from modules can be referenced too. The `using` statement needs to be the first statement in the script. Syntax #1, to reference .Net Framework namespaces: + ``` using namespace <.Net-framework-namespace> ``` Syntax #2, to reference PowerShell modules: + ``` using module ``` -> **Note** The `using` statetement, for modules, is intended to surface the classes in the module. -> If the module isn't loaded, the `using` fails. +**Note**: The `using` statetement, for modules, is intended to surface the +classes in the module. If the module isn't loaded, the `using` fails. ## Example 1 The following script gets the cryptographic hash for the "Hello World" string. -Note how the `using namespace System.Text` and `using namespace System.IO` simplify -the references to `[UnicodeEncoding]` in *System.Text*; and, to `[Stream]` -and to `[MemoryStream]` in *System.IO*. - +Note how the `using namespace System.Text` and `using namespace System.IO` +simplify the references to `[UnicodeEncoding]` in *System.Text*; and, to +`[Stream]` and to `[MemoryStream]` in *System.IO*. ```powershell - using namespace System.Text - using namespace System.IO +using namespace System.Text +using namespace System.IO - [string]$string = "Hello World" - [string]$algorithm = "SHA256" ## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MD5" +[string]$string = "Hello World" +## Valid values are "SHA1", "SHA256", "SHA384", "SHA512", "MD5" +[string]$algorithm = "SHA256" - [byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) +[byte[]]$stringbytes = [UnicodeEncoding]::Unicode.GetBytes($string) - [Stream]$memorystream = [MemoryStream]::new($stringbytes) - $hashfromstream = Get-FileHash -InputStream $memorystream -Algorithm $algorithm - $hashfromstream.Hash.ToString() +[Stream]$memorystream = [MemoryStream]::new($stringbytes) +$hashfromstream = Get-FileHash -InputStream $memorystream ` + -Algorithm $algorithm +$hashfromstream.Hash.ToString() ``` ## Example 2 @@ -77,4 +78,3 @@ $deck.Shuffle() [Card[]]$hand2 = $deck.Deal(5) [Card[]]$hand3 = $deck.Deal(5) ``` - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md index 0d9fbe39f89d..10b1d7bc00db 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -74,20 +74,24 @@ are included. Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf ``` -The second example uses hash table splatting. The first command creates -a hash table of parameter-name and parameter-value pairs and stores it -in the $HashArguments variable. The second command uses the `$HashArguments` -variable in a command with splatting. The At symbol (`@HashArguments`) -replaces the dollar sign (`$HashArguments`) in the command. +The second example uses hash table splatting. The first command creates a hash +table of parameter-name and parameter-value pairs and stores it in the +\$HashArguments variable. The second command uses the `$HashArguments` variable +in a command with splatting. The At symbol (`@HashArguments`) replaces the +dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. ```powershell -$HashArguments = @{ Path = "test.txt"; Destination = "test2.txt"; WhatIf = $true } +$HashArguments = @{ + Path = "test.txt" + Destination = "test2.txt" + WhatIf = $true +} Copy-Item @HashArguments ``` -*Note: In the first command, the At symbol (@) indicates a hash table, not +Note: In the first command, the At symbol (@) indicates a hash table, not a splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* @@ -106,11 +110,12 @@ omitted. The parameter values appear in position order in the command. Copy-Item "test.txt" "test2.txt" -WhatIf ``` -The second example uses array splatting. The first command creates an array -of the parameter values and stores it in the `$ArrayArguments` variable. The +The second example uses array splatting. The first command creates an array of +the parameter values and stores it in the `$ArrayArguments` variable. The values are in position order in the array. The second command uses the `$ArrayArguments` variable in a command in splatting. The At symbol -(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the command. +(`@ArrayArguments`) replaces the dollar sign (`$ArrayArguments`) in the +command. ```powershell $ArrayArguments = "test.txt", "test2.txt" @@ -120,10 +125,10 @@ Copy-Item @ArrayArguments -WhatIf # EXAMPLES -This example shows how to re-use splatted values in different commands. -The commands in this example use the Write-Host cmdlet to write messages -to the host program console. It uses splatting to specify the foreground -and background colors. +This example shows how to re-use splatted values in different commands. The +commands in this example use the Write-Host cmdlet to write messages to the +host program console. It uses splatting to specify the foreground and +background colors. To change the colors of all commands, just change the value of the `$Colors` variable. @@ -143,7 +148,8 @@ Write-Host command. To use the `$Colors variable`, replace the dollar sign #Write a message with the colors in $Colors Write-Host "This is a test." @Colors -#Write second message with same colors. The position of splatted hash table does not matter. +#Write second message with same colors. The position of splatted +#hash table does not matter. Write-Host @Colors "This is another test." ``` @@ -193,22 +199,19 @@ Test2 -a 1 -b 2 -c 3 # SPLATTING COMMAND PARAMETERS -You can use splatting to represent the parameters of -a command. This technique is useful when you are creating -a proxy function, that is, a function that calls another -command. This feature is introduced in Windows PowerShell 3.0. +You can use splatting to represent the parameters of a command. This technique +is useful when you are creating a proxy function, that is, a function that +calls another command. This feature is introduced in Windows PowerShell 3.0. -To splat the parameters of a command, use `@Args` to represent -the command parameters. This technique is easier than -enumerating command parameters and it works without revision -even if the parameters of the called command change. +To splat the parameters of a command, use `@Args` to represent the command +parameters. This technique is easier than enumerating command parameters and +it works without revision even if the parameters of the called command change. The feature uses the `$Args` automatic variable, which contains all unassigned parameter values. -For example, the following function calls the Get-Process -cmdlet. In this function, `@Args` represents all of the parameters -of the Get-Process cmdlet. +For example, the following function calls the Get-Process cmdlet. In this +function, `@Args` represents all of the parameters of the Get-Process cmdlet. ```powershell function Get-MyProcess { Get-Process @Args } @@ -223,20 +226,18 @@ Get-MyProcess -Name PowerShell Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- -463 46 225484 237196 719 15.86 3228 powershell + 463 46 225484 237196 719 15.86 3228 powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo ProductVersion FileVersion FileName -------------- ----------- -------- -6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell_ISE.exe +6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... ``` -You can use `@Args` in a function that has explicitly -declared parameters. You can use it more than once in -a function, but all parameters that you enter are passed -to all instances of `@Args`, as shown in the following -example. +You can use `@Args` in a function that has explicitly declared parameters. You +can use it more than once in a function, but all parameters that you enter are +passed to all instances of `@Args`, as shown in the following example. ```powershell function Get-MyCommand @@ -252,9 +253,9 @@ Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Extension : .exe -Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Definition : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e Visibility : Public OutputType : {System.String} Name : powershell.exe @@ -265,10 +266,11 @@ RemotingCapability : PowerShell Parameters : ParameterSets : HelpUri : -FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell + \v1.0\powershell.exe InternalName: POWERSHELL OriginalFilename: PowerShell.EXE.MUI - FileVersion: 10.0.14393.0 (rs1_release.160715-1616) + FileVersion: 10.0.14393.0 (rs1_release.160715-1616 FileDescription: Windows PowerShell Product: Microsoft® Windows® Operating System ProductVersion: 10.0.14393.0 @@ -289,4 +291,3 @@ FileVersionInfo : File: C:\Windows\System32\WindowsPowerShell\v1. [about_Hash_Tables](about_Hash_Tables.md) [about_Parameters](about_Parameters.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Split.md b/reference/6/Microsoft.PowerShell.Core/About/about_Split.md index 9154bed7ea49..98b97dd2dab7 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -19,22 +19,21 @@ The Split operator splits one or more strings into substrings. You can change the following elements of the Split operation: * Delimiter. The default is whitespace, but you can specify characters, -strings, patterns, or script blocks that specify the delimiter. The Split -operator in Windows PowerShell uses a regular expression in the delimiter, -rather than a simple character. + strings, patterns, or script blocks that specify the delimiter. The Split + operator in Windows PowerShell uses a regular expression in the delimiter, + rather than a simple character. * Maximum number of substrings. The default is to return all substrings. If -you specify a number less than the number of substrings, the remaining -substrings are concatenated in the last substring. + you specify a number less than the number of substrings, the remaining + substrings are concatenated in the last substring. * Options that specify the conditions under which the delimiter is matched, -such as SimpleMatch and Multiline. + such as SimpleMatch and Multiline. ## SYNTAX The following diagram shows the syntax for the -split operator. -The parameter names do not appear in the command. Include only the -parameter values. The values must appear in the order specified in the -syntax diagram. +The parameter names do not appear in the command. Include only the parameter +values. The values must appear in the order specified in the syntax diagram. ```powershell -Split @@ -45,17 +44,17 @@ syntax diagram. ``` You can substitute `-iSplit` or `-cSplit` for `-split` in any binary Split -statement (a Split statement that includes a delimiter or script block). -The `-iSplit` and `-split` operators are case-insensitive. The `-cSplit` -operator is case-sensitive, meaning that case is considered when the -delimiter rules are applied. +statement (a Split statement that includes a delimiter or script block). The +`-iSplit` and `-split` operators are case-insensitive. The `-cSplit` operator +is case-sensitive, meaning that case is considered when the delimiter rules +are applied. ## PARAMETERS ### \ -Specifies one or more strings to be split. If you submit multiple -strings, all the strings are split using the same delimiter rules. +Specifies one or more strings to be split. If you submit multiple strings, all +the strings are split using the same delimiter rules. Example: @@ -69,10 +68,10 @@ green ### \ -The characters that identify the end of a substring. The default delimiter -is whitespace, including spaces and non-printable characters, such as -newline (\`n) and tab (\`t). When the strings are split, the delimiter is -omitted from all the substrings. Example: +The characters that identify the end of a substring. The default delimiter is +whitespace, including spaces and non-printable characters, such as newline +(\`n) and tab (\`t). When the strings are split, the delimiter is omitted from +all the substrings. Example: ```powershell "Lastname:FirstName:Address" -split ":" @@ -81,13 +80,13 @@ FirstName Address ``` -By default, the delimiter is omitted from the results. To preserve all or -part of the delimiter, enclose in parentheses the part that you want to -preserve. If the \ parameter is added, this takes -precedence when your command splits up the collection. If you opt to -include a delimiter as part of the output, the command returns the -delimiter as part of the output; however, splitting the string to return -the delimiter as part of output does not count as a split. +By default, the delimiter is omitted from the results. To preserve all or part +of the delimiter, enclose in parentheses the part that you want to preserve. +If the \ parameter is added, this takes precedence when your +command splits up the collection. If you opt to include a delimiter as part of +the output, the command returns the delimiter as part of the output; however, +splitting the string to return the delimiter as part of output does not count +as a split. Examples: @@ -124,17 +123,16 @@ Strawberry-Blueberry ### \ -Specifies the maximum number of times that a string is split. The default -is all the substrings split by the delimiter. If there are more substrings, -they are concatenated to the final substring. If there are fewer -substrings, all the substrings are returned. A value of 0 and negative -values return all the substrings. +Specifies the maximum number of times that a string is split. The default is +all the substrings split by the delimiter. If there are more substrings, they +are concatenated to the final substring. If there are fewer substrings, all +the substrings are returned. A value of 0 and negative values return all the +substrings. Max-substrings does not specify the maximum number of objects that are -returned; its value equals the maximum number of times that a string is -split. If you submit more than one string (an array of strings) to the -Split operator , the Max-substrings limit is applied to each string -separately. +returned; its value equals the maximum number of times that a string is split. +If you submit more than one string (an array of strings) to the Split operator +, the Max-substrings limit is applied to each string separately. Example: @@ -150,9 +148,8 @@ Jupiter,Saturn,Uranus,Neptune ### \ -An expression that specifies rules for applying the delimiter. The -expression must evaluate to $true or $false. Enclose the script block in -braces. +An expression that specifies rules for applying the delimiter. The expression +must evaluate to $true or $false. Enclose the script block in braces. Example: @@ -187,63 +184,62 @@ The syntax for the Options parameter is: The SimpleMatch options are: * **SimpleMatch**: Use simple string comparison when evaluating the -delimiter. Cannot be used with RegexMatch. + delimiter. Cannot be used with RegexMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. The RegexMatch options are: * **RegexMatch**: Use regular expression matching to evaluate the -delimiter. This is the default behavior. Cannot be used with -SimpleMatch. + delimiter. This is the default behavior. Cannot be used with + SimpleMatch. * **IgnoreCase**: Forces case-insensitive matching, even if the -cSplit -operator is specified. + operator is specified. * **CultureInvariant**: Ignores cultural differences in language -when evaluting the delimiter. Valid only with RegexMatch. + when evaluting the delimiter. Valid only with RegexMatch. * IgnorePatternWhitespace: Ignores unescaped whitespace and -comments marked with the number sign (#). Valid only with -RegexMatch. + comments marked with the number sign (#). Valid only with + RegexMatch. * **Multiline**: Multiline mode recognizes the start and end of lines -and strings. Valid only with RegexMatch. Singleline is the default. + and strings. Valid only with RegexMatch. Singleline is the default. * **Singleline**: Singleline mode recognizes only the start and end of -strings. Valid only with RegexMatch. Singleline is the default. + strings. Valid only with RegexMatch. Singleline is the default. * **ExplicitCapture**: Ignores non-named match groups so that only -explicit capture groups are returned in the result list. Valid -only with RegexMatch. + explicit capture groups are returned in the result list. Valid + only with RegexMatch. ## UNARY and BINARY SPLIT OPERATORS The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the -unary split operator, only the first string (before the first comma) is -split. +unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( --split ). Enclose all the strings in parentheses, or store the -strings in a variable, and then submit the variable to the split operator. +To split more than one string, use the binary split operator ( -split +). Enclose all the strings in parentheses, or store the strings in +a variable, and then submit the variable to the split operator. Consider the following example: ```powershell -PS C:\> -split "1 2", "a b" +PS > -split "1 2", "a b" 1 2 a b -PS C:\> "1 2", "a b" -split " " +PS > "1 2", "a b" -split " " 1 2 a b -PS C:\> -split ("1 2", "a b") +PS > -split ("1 2", "a b") 1 2 a b -PS C:\> $a = "1 2", "a b" -PS C:\> -split $a +PS > $a = "1 2", "a b" +PS > -split $a 1 2 a @@ -255,7 +251,7 @@ b The following statement splits the string at whitespace. ```powershell -PS C:\> -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" Windows PowerShell 2.0 @@ -268,7 +264,7 @@ remoting The following statement splits the string at any comma. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' Mercury Venus Earth @@ -282,17 +278,16 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune ``` -The following statement performs a case-sensitive split at the -letter "N". +The following statement performs a case-sensitive split at the letter "N". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -300,7 +295,7 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' M rcury,V nus, @@ -317,7 +312,8 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS C:\> "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` + -split '[er]', 6 M cu @@ -329,7 +325,7 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS C:\> "a,b,c,d,e,f,g,h" -split ",", 3 +PS > "a,b,c,d,e,f,g,h" -split ",", 3 a b c,d,e,f,g,h @@ -339,7 +335,7 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS C:\> "a,b,c,d", "e,f,g,h" -split ",", 3 +PS > "a,b,c,d", "e,f,g,h" -split ",", 3 a b c,d @@ -352,18 +348,18 @@ The following statement splits each line in the here-string at the first digit. It uses the Multiline option to recognize the beginning of each line and string. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as Multiline, only when the Max-substrings value -is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as Multiline, only when the Max-substrings value is +specified. ```powershell -PS C:\> $a = @' +PS > $a = @' 1The first line. 2The second line. 3The third of three lines. '@ -PS C:\> $a -split "^\d", 0, "multiline" +PS > $a -split "^\d", 0, "multiline" The first line. @@ -380,12 +376,12 @@ interpreted to match any character except for a newline character. As a result, the Split statement returns a blank line for every character except newline. -The 0 represents the "return all" value of the Max-substrings parameter. -You can use options, such as SimpleMatch, only when the Max-substrings -value is specified. +The 0 represents the "return all" value of the Max-substrings parameter. You +can use options, such as SimpleMatch, only when the Max-substrings value is +specified. ```powershell -PS C:\> "This.is.a.test" -split ".", 0, "simplematch" +PS > "This.is.a.test" -split ".", 0, "simplematch" This is @@ -393,13 +389,13 @@ a test ``` -The following statement splits the string at one of two delimiters, -depending on the value of a variable. +The following statement splits the string at one of two delimiters, depending +on the value of a variable. ```powershell -PS C:\> $i = 1 -PS C:\> $c = "LastName, FirstName; Address, City, State, Zip" -PS C:\> $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +PS > $i = 1 +PS > $c = "LastName, FirstName; Address, City, State, Zip" +PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} LastName, FirstName Address, City, State, Zip @@ -407,7 +403,7 @@ Address, City, State, Zip ## SEE ALSO -Split-Path +[Split-Path](../../Microsoft.PowerShell.Management/Split-Path.md) [about_Operators](about_Operators.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md index 90658fd83ff1..1bfafbe78470 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -148,13 +148,25 @@ Default clause is permitted in each Switch statement. Switch has the following parameters: -|Parameter|Description| -|---|---| -| Wildcard | Indicates that the condition is a wildcard string. If you use Wildcard, Regex and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| Exact | Indicates that the match clause, if it is a string, must match exactly. If you use Exact, Regex and Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | -| CaseSensitive | Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. | -| File | Takes input from a file rather than a value statement. If multiple File parameters are included, only the last one is used. Each line of the file is read and evaluated by the Switch statement. | -| Regex | Performs regular expression matching of the value to the condition. If you use Regex, Wildcard and Exact are ignored. Also, if the match clause is not a string, this parameter is ignored. | +|Parameter |Description | +|-------------|-----------------------------------------------------------| +|Wildcard |Indicates that the condition is a wildcard string. If you | +| |you use Wildcard, Regex and Exact are ignored. Also, if | +| |the match clause is not a string, the parameter is ignored.| +|Exact |Indicates that the match clause, if it is a string, must | +| |match exactly. Regex and Wildcard and Exact are ignored. | +| |Also, if the match clause is not a string, this parameter | +| |is ignored. | +|CaseSensitive|Performs a case-sensitive match. If the match clause is not| +| |a string, this parameter is ignored. | +|File |Takes input from a file rather than a value statement. If | +| |multiple File parameters are included, only the last one is| +| |used. Each line of the file is read and evaluated by the | +| |Switch statement. | +|Regex |Performs regular expression matching of the value to the | +| |condition. Wildcard and Exact are ignored. Also, if the | +| |match clause is not a string, this parameter is ignored. | + ```powershell Example: diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Throw.md b/reference/6/Microsoft.PowerShell.Core/About/about_Throw.md index 2deea43ade1b..08fe2f6e5c7e 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Throw.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Throw.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,16 +14,16 @@ Describes the Throw keyword, which generates a terminating error. ## LONG DESCRIPTION -The Throw keyword causes a terminating error. You can use the Throw keyword -to stop the processing of a command, function, or script. +The Throw keyword causes a terminating error. You can use the Throw keyword to +stop the processing of a command, function, or script. For example, you can use the Throw keyword in the script block of an If statement to respond to a condition or in the Catch block of a -Try-Catch-Finally statement. You can also use the Throw keyword in a -parameter declaration to make a function parameter mandatory. +Try-Catch-Finally statement. You can also use the Throw keyword in a parameter +declaration to make a function parameter mandatory. -The Throw keyword can throw any object, such as a user message string or -the object that caused the error. +The Throw keyword can throw any object, such as a user message string or the +object that caused the error. ## SYNTAX @@ -33,8 +33,8 @@ The syntax of the Throw keyword is as follows: throw [] ``` -The expression in the Throw syntax is optional. When the Throw statement -does not appear in a Catch block, and it does not include an expression, it +The expression in the Throw syntax is optional. When the Throw statement does +not appear in a Catch block, and it does not include an expression, it generates a ScriptHalted error. ```powershell @@ -47,13 +47,14 @@ At line:1 char:6 + FullyQualifiedErrorId : ScriptHalted ``` -If the Throw keyword is used in a Catch block without an expression, it -throws the current RuntimeException again. For more information, see +If the Throw keyword is used in a Catch block without an expression, it throws +the current RuntimeException again. For more information, see about_Try_Catch_Finally. ## THROWING A STRING -The optional expression in a Throw statement can be a string, as shown in -the following example: + +The optional expression in a Throw statement can be a string, as shown in the +following example: ```powershell C:\PS> throw "This is an error." @@ -61,7 +62,8 @@ C:\PS> throw "This is an error." This is an error. At line:1 char:6 + throw <<<< "This is an error." -+ CategoryInfo : OperationStopped: (This is an error.:String) [], RuntimeException ++ CategoryInfo : OperationStopped: (This is an error.:String) [], R +untimeException + FullyQualifiedErrorId : This is an error. ``` @@ -76,7 +78,8 @@ C:\PS> throw (get-process PowerShell) System.Diagnostics.Process (PowerShell) At line:1 char:6 + throw <<<< (get-process PowerShell) -+ CategoryInfo : OperationStopped: (System.Diagnostics.Process (PowerShell):Process) [], ++ CategoryInfo : OperationStopped: (System.Diagnostics.Process (Pow +erShell):Process) [], RuntimeException + FullyQualifiedErrorId : System.Diagnostics.Process (PowerShell) ``` @@ -105,15 +108,16 @@ One of the identified items was in an invalid format. At line:1 char:6 + throw <<<< $formatError + CategoryInfo : OperationStopped: (:) [], FormatException -+ FullyQualifiedErrorId : One of the identified items was in an invalid format. ++ FullyQualifiedErrorId : One of the identified items was in an invalid +format. ``` ## RESULTING ERROR -The Throw keyword can generate an ErrorRecord object. The Exception -property of the ErrorRecord object contains a RuntimeException object. The -remainder of the ErrorRecord object and the RuntimeException object vary -with the object that the Throw keyword throws. +The Throw keyword can generate an ErrorRecord object. The Exception property +of the ErrorRecord object contains a RuntimeException object. The remainder of +the ErrorRecord object and the RuntimeException object vary with the object +that the Throw keyword throws. The RunTimeException object is wrapped in an ErrorRecord object, and the ErrorRecord object is automatically saved in the $Error automatic variable. @@ -139,7 +143,9 @@ optional. function Get-XMLFiles { param ($path = $(throw "The Path parameter is required.")) - dir -path $path\*.xml -recurse | sort lastwritetime | ft lastwritetime, attributes, name -auto + dir -path $path\*.xml -recurse | + sort lastwritetime | + ft lastwritetime, attributes, name -auto } ``` @@ -154,4 +160,3 @@ function Get-XMLFiles [about_Trap](about_Trap.md) [about_Try_Catch_Finally](about_Try_Catch_Finally.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Trap.md b/reference/6/Microsoft.PowerShell.Core/About/about_Trap.md index 338030fa058b..bc042324bc4b 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Trap.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Trap.md @@ -130,7 +130,9 @@ statement that specifies the CommandNotFoundException type. ```powershell trap {"Other terminating error trapped" } -trap [System.Management.Automation.CommandNotFoundException] {"Command error trapped"} +trap [System.Management.Automation.CommandNotFoundException] { + "Command error trapped" +} nonsenseString ``` diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Type_Operators.md b/reference/6/Microsoft.PowerShell.Core/About/about_Type_Operators.md index a94e962d87b3..531eb8a2f9da 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Type_Operators.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Type_Operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-091 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -26,11 +26,16 @@ fails, it returns nothing. It does not return an error. The following table lists the type operators in Windows PowerShell. -|Operator|Description|Example| -|---|---|---| -|`-is`|Returns TRUE when the input is an instance of the specified.NET Framework type.|`C:\PS> (get-date) -is [DateTime]`
`True`| -|`-isNot`|Returns TRUE when the input is not an instance of the specified.NET Framework type.|`C:\PS> (get-date) -isNot [DateTime]`
`False`| -|`-as`|Converts the input to the specified.NET Framework type.|`C:\PS> 12/31/07 -as [DateTime]`
`Monday, December 31, 2007 12:00:00 AM`| +|Operator|Description |Example | +|--------|---------------------------|---------------------------------| +|`-is` |Returns TRUE when the input|`(get-date) -is [DateTime]` | +| |is an instance of the |`True` | +| |specified .NET type. | | +|`-isNot`|Returns TRUE when the input|`(get-date) -isNot [DateTime]` | +| |not an instance of the |`False` | +| |specified.NET type. | | +|`-as` |Converts the input to the |`"5/7/07" -as [DateTime]` | +| |specified .NET type. |`Monday, May 7, 2007 12:00:00 AM`| The syntax of the type operators is as follows: @@ -64,7 +69,7 @@ property of this method. For example, the following statement gets the type of the return value of a Get-Culture command: ```powershell -C:\PS> (get-culture).gettype().fullname +PS> (get-culture).gettype().fullname System.Globalization.CultureInfo ``` @@ -72,25 +77,25 @@ System.Globalization.CultureInfo The following examples show some uses of the Type operators: ```powershell -C:\PS> 32 -is [Float] +PS> 32 -is [Float] False -C:\PS> 32 -is "int" +PS> 32 -is "int" True -C:\PS> (get-date) -is [DateTime] +PS> (get-date) -is [DateTime] True -C:\PS> "12/31/2007" -is [DateTime] +PS> "12/31/2007" -is [DateTime] False -C:\PS> "12/31/2007" -is [String] +PS> "12/31/2007" -is [String] True -C:\PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] +PS> (get-process PowerShell)[0] -is [System.Diagnostics.Process] True -C:\PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] +PS> (get-command get-member) -is [System.Management.Automation.CmdletInfo] True ``` @@ -103,53 +108,55 @@ return System.Globalization.CultureInfo objects, a collection of these objects is a System.Object array. ```powershell -C:\PS> (get-culture) -is [System.Globalization.CultureInfo] +PS> (get-culture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-uiculture) -is [System.Globalization.CultureInfo] True -C:\PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] +PS> (get-culture), (get-uiculture) -is [System.Globalization.CultureInfo] False -C:\PS> (get-culture), (get-uiculture) -is [Array] +PS> (get-culture), (get-uiculture) -is [Array] True -C:\PS> (get-culture), (get-uiculture) | foreach {$_ -is [System.Globalization.CultureInfo]) +PS> (get-culture), (get-uiculture) | foreach { + $_ -is [System.Globalization.CultureInfo]) +} True True -C:\PS> (get-culture), (get-uiculture) -is [Object] +PS> (get-culture), (get-uiculture) -is [Object] True ``` The following examples show how to use the -as operator. ```powershell -C:\PS> "12/31/07" -is [DateTime] +PS> "12/31/07" -is [DateTime] False -C:\PS> "12/31/07" -as [DateTime] +PS> "12/31/07" -as [DateTime] Monday, December 31, 2007 12:00:00 AM -C:\PS> $date = "12/31/07" -as [DateTime] +PS> $date = "12/31/07" -as [DateTime] C:\PS>$a -is [DateTime] True -C:\PS> 1031 -as [System.Globalization.CultureInfo] +PS> 1031 -as [System.Globalization.CultureInfo] -LCID Name DisplayName ----- ---- ----------- -1031 de-DE German (Germany) +LCID Name DisplayName +---- ---- ----------- +1031 de-DE German (Germany) ``` The following example shows that when the -as operator cannot convert the input object to the .NET Framework type, it returns nothing. ```powershell -C:\PS> 1031 -as [System.Diagnostic.Process] -C:\PS> +PS> 1031 -as [System.Diagnostic.Process] +PS> ``` ## SEE ALSO diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md b/reference/6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md index 96d2292ea00c..3888516c6096 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Types.ps1xml.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,9 +7,6 @@ title: about_Types.ps1xml --- # About Types.ps1xml -## about_Types.ps1xml - - # SHORT DESCRIPTION @@ -27,16 +24,16 @@ extended type data to a Windows PowerShell session. extended data for types in the current session. This topic describes Types.ps1xml files. For more information about using the -`Update-TypeData` cmdlet to add dynamic extended type data to the current session -see [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). +`Update-TypeData` cmdlet to add dynamic extended type data to the current +session see +[Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md). ## About Extended Type Data -Extended type data defines additional properties and methods ("members") -of object types in Windows PowerShell. You can extend any type that is -supported by Windows PowerShell and use the added properties and methods -in the same way that you use the properties that are defined on the object -types. +Extended type data defines additional properties and methods ("members") of +object types in Windows PowerShell. You can extend any type that is supported +by Windows PowerShell and use the added properties and methods in the same way +that you use the properties that are defined on the object types. For example, Windows PowerShell adds a `DateTime` property to all `System.DateTime` objects, such as the ones that the `Get-Date` cmdlet @@ -47,27 +44,27 @@ PS C:> (Get-Date).DateTime Sunday, January 29, 2012 9:43:57 AM ``` -You won't find the `DateTime` property in the description of the [`System.DateTime` -structure](http://msdn.microsoft.com/library/system.datetime.aspx), -because Windows PowerShell adds the property and it is visible only in -Windows PowerShell. +You won't find the `DateTime` property in the description of the +[`System.DateTime` structure](http://msdn.microsoft.com/library/system.datetime.aspx), +because Windows PowerShell adds the property and it is visible only in Windows +PowerShell. -To add the `DateTime` property to all Windows PowerShell sessions, Windows PowerShell -defines the `DateTime` property in the Types.ps1xml file in the Windows PowerShell -installation directory (`$PSHOME`). +To add the `DateTime` property to all Windows PowerShell sessions, Windows +PowerShell defines the `DateTime` property in the Types.ps1xml file in the +Windows PowerShell installation directory (`$PSHOME`). ## Adding Extended Type Data to Windows PowerShell. There are three sources of extended type data in Windows PowerShell sessions. - The Types.ps1xml files in the Windows PowerShell installation directory -are loaded automatically into every Windows PowerShell session. + are loaded automatically into every Windows PowerShell session. - The Types.ps1xml files that modules export are loaded when the module -is imported into the current session. + is imported into the current session. - Extended type data that is defined by using the `Update-TypeData` cmdlet -is added only to the current session. It is not saved in a file. + is added only to the current session. It is not saved in a file. In the session, the extended type data from the three sources is applied to objects in the same way and is available on all objects of the specified @@ -78,11 +75,10 @@ types. The following TypeData cmdlets are included in the Microsoft.PowerShell.Utility module in Windows PowerShell 3.0 and later versions of Windows PowerShell. -| | | -| --------------- | --------------------------------------------------------------- | -| Get-TypeData | Gets extended type data in the current session. | -| Update-TypeData | Reloads Types.ps1xml files. Adds extended type data to the current session. | -| Remove-TypeData | Removes extended type data from the current session. +- `Get-TypeData`: Gets extended type data in the current session. +- `Update-TypeData`: Reloads Types.ps1xml files. Adds extended type data to the + current session. +- `Remove-TypeData`: Removes extended type data from the current session. For more information about these cmdlets, see the help topic for each cmdlet. @@ -118,8 +114,8 @@ value. The following XML adds the Count property to the `System.Array` type. ``` -To get the new `AliasProperty`, use a `Get-Member` command on any array, as shown -in the following example. +To get the new `AliasProperty`, use a `Get-Member` command on any array, as +shown in the following example. ```powershell Get-Member -InputObject (1,2,3,4) @@ -127,15 +123,15 @@ Get-Member -InputObject (1,2,3,4) The command returns the following results. -```powershell -Name MemberType Definition ----- ---------- ---------- -Count AliasProperty Count = Length -Address Method System.Object& Address(Int32) -Clone Method System.Object Clone() -CopyTo Method System.Void CopyTo(Array array, Int32 index): -Equals Method System.Boolean Equals(Object obj) -Get Method System.Object Get(Int32) +```output +Name MemberType Definition +---- ---------- ---------- +Count AliasProperty Count = Length +Address Method System.Object& Address(Int32) +Clone Method System.Object Clone() +CopyTo Method System.Void CopyTo(Array array, Int32 index): +Equals Method System.Boolean Equals(Object obj) +Get Method System.Object Get(Int32) # ... ``` @@ -344,7 +340,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -369,7 +367,9 @@ FileSystem provider. Mode - Microsoft.PowerShell.Commands.FileSystemProvider + + Microsoft.PowerShell.Commands.FileSystemProvider + Mode @@ -510,21 +510,21 @@ methods of the `System.Management.ManagementDateTimeConverter` class. ```xml - System.Management.ManagementObject - - - ConvertToDateTime - - - - ConvertFromDateTime - - - + System.Management.ManagementObject + + + ConvertToDateTime + + + + ConvertFromDateTime + + + ``` @@ -547,7 +547,7 @@ property of the `GetVersionInfo` static method of VersionInfo - [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) + [System.Diagnostics.FileVersionInfo]::GetVersionInfo($this.FullName) @@ -585,8 +585,9 @@ use method syntax. ## Signing a Types.ps1xml File -To protect users of your Types.ps1xml file, you can sign the file using -a digital signature. For more information, see [about_Signing](about_Signing.md). +To protect users of your Types.ps1xml file, you can sign the file using a +digital signature. For more information, see +[about_Signing](about_Signing.md). # SEE ALSO @@ -603,4 +604,3 @@ a digital signature. For more information, see [about_Signing](about_Signing.md) [Remove-TypeData](../../Microsoft.PowerShell.Utility/Remove-TypeData.md) [Update-TypeData](../../Microsoft.PowerShell.Utility/Update-TypeData.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md b/reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md index 8f2a53213e37..08ee68185fcb 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,86 +7,90 @@ title: about_WMI_Cmdlets --- # About WMI Cmdlets -## about_WMI_Cmdlets - ## SHORT DESCRIPTION -Provides background information about Windows Management Instrumentation (WMI) and Windows PowerShell. +Provides background information about Windows Management Instrumentation (WMI) +and Windows PowerShell. ## LONG DESCRIPTION -This topic provides information about WMI technology, the WMI cmdlets for Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI troubleshooting. This topic also provides links to more information about WMI. +This topic provides information about WMI technology, the WMI cmdlets for +Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI +troubleshooting. This topic also provides links to more information about WMI. ### ABOUT WMI -Windows Management Instrumentation (WMI) is the Microsoft implementation of Web-Based Enterprise Management (WBEM), which is an industry initiative to develop a standard technology for accessing management information in an enterprise environment. WMI uses the Common Information Model (CIM) industry standard to represent systems, applications, networks, devices, and other managed components. CIM is developed and maintained by the Distributed Management Task Force (DMTF). You can use WMI to manage both local and remote computers. For example, you can use WMI to do the following: - --- Start a process on a remote computer. - --- Restart a computer remotely. - --- Get a list of the applications that are installed on a local or remote computer. - --- Query the Windows event logs on a local or remote computer. +Windows Management Instrumentation (WMI) is the Microsoft implementation of +Web-Based Enterprise Management (WBEM), which is an industry initiative to +develop a standard technology for accessing management information in an +enterprise environment. WMI uses the Common Information Model (CIM) industry +standard to represent systems, applications, networks, devices, and other +managed components. CIM is developed and maintained by the Distributed +Management Task Force (DMTF). You can use WMI to manage both local and remote +computers. For example, you can use WMI to do the following: + +- Start a process on a remote computer. +- Restart a computer remotely. +- Get a list of the applications that are installed on a local or remote + computer. +- Query the Windows event logs on a local or remote computer. ### THE WMI CMDLETS FOR WINDOWS POWERSHELL -Windows PowerShell implements WMI functionality through a set of cmdlets that are available in Windows PowerShell by default. You can use these cmdlets to complete the end-to-end tasks necessary to manage local and remote computers. - -The following WMI cmdlets are included. +Windows PowerShell implements WMI functionality through a set of cmdlets that +are available in Windows PowerShell by default. You can use these cmdlets to +complete the end-to-end tasks necessary to manage local and remote computers. -``` -Cmdlet Description ------------------- ---------------------------------------------- -Get-WmiObject Gets instances of WMI classes or information - about the available classes. - -Invoke-WmiMethod Calls WMI methods. - -Register-WmiEvent Subscribes to a WMI event. - -Remove-WmiObject Deletes WMI classes and instances. - -Set-WmiInstance Creates or modifies instances of WMI classes. -``` - +The following WMI cmdlets are included. +|Cmdlet |Description | +|-----------------|----------------------------------------------| +|Get-WmiObject |Gets instances of WMI classes or information | +| |about the available classes. | +|Invoke-WmiMethod |Calls WMI methods. | +|Register-WmiEvent|Subscribes to a WMI event. | +|Remove-WmiObject |Deletes WMI classes and instances. | +|Set-WmiInstance |Creates or modifies instances of WMI classes. | ### SAMPLE COMMANDS The following command displays the BIOS information for the local computer. - -``` +```powershell C:\PS> get-wmiobject win32_bios | format-list * ``` +The following command displays information about the WinRM service for three +remote computers. -The following command displays information about the WinRM service for three remote computers. - - -``` -C:\PS> get-wmiobject -query "select * from win32_service where name='WinRM'" -computername server01, server01, server03 +```powershell +$wql = "select * from win32_service where name='WinRM'" +get-wmiobject -query $wql -computername server01, server01, server03 ``` - The following more complex command exits all instances of a program. - -``` -C:\PS> notepad.exe -C:\PS> $np = get-wmiobject -query "select * from win32_process where name='notepad.exe'" +```powershell +C:\PS> notepad.exe +C:\PS> $wql = "select * from win32_process where name='notepad.exe'" +C:\PS> $np = get-wmiobject -query $wql C:\PS> $np | remove-wmiobject ``` - - ### WMI-BASED REMOTING -While the ability to manage a local system through WMI is useful, it is the remoting capabilities that make WMI a powerful administrative tool. WMI uses Microsoft's Distributed Component Object Model (DCOM) to connect to and manage systems. You might have to configure some systems to allow DCOM connections. Firewall settings and locked-down DCOM permissions can block WMI's ability to remotely manage systems. +While the ability to manage a local system through WMI is useful, it is the +remoting capabilities that make WMI a powerful administrative tool. WMI uses +Microsoft's Distributed Component Object Model (DCOM) to connect to and manage +systems. You might have to configure some systems to allow DCOM connections. +Firewall settings and locked-down DCOM permissions can block WMI's ability to +remotely manage systems. ### WMI TYPE ACCELERATORS -Windows PowerShell includes WMI type accelerators. These WMI type accelerators (shortcuts) allow more direct access to a WMI objects than a non-type accelerator approach would allow. + +Windows PowerShell includes WMI type accelerators. These WMI type accelerators +(shortcuts) allow more direct access to a WMI objects than a non-type +accelerator approach would allow. The following type accelerators are supported with WMI: @@ -96,123 +100,116 @@ The following type accelerators are supported with WMI: [WMI] - A shortcut for getting a single instance of a class. -[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can take a string constructor to create a searcher that you can then do a GET() on. +[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can +take a string constructor to create a searcher that you can then do a GET() +on. For example: +```powershell +PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' +PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto +count __PATH name +----- ------ ---- +1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... +1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe +1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe +1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE +1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe +2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe ``` -PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' -PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto - -handlecount __PATH name ------------ ------ ---- -1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... -1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe -1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe -1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE -1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe -2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe -``` - -[WMICLASS] is a type accelerator for ManagementClass. This has a string constructor that takes a local or absolute WMI path to a WMI class and returns an object that is bound to that class. +[WMICLASS] is a type accelerator for ManagementClass. This has a string +constructor that takes a local or absolute WMI path to a WMI class and returns +an object that is bound to that class. For example: - -``` -PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" -PS> $c |fl * -Name : Win32_Process -__GENUS : 1 -__CLASS : Win32_Process -__SUPERCLASS : CIM_Process -__DYNASTY : CIM_ManagedSystemElement -__RELPATH : Win32_Process -__PROPERTY_COUNT : 45 -__DERIVATION : {CIM_Process, CIM_LogicalElement, CIM_ManagedSystemElement} -__SERVER : SERVER01 -__NAMESPACE : ROOT\cimv2 +```powershell +PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" +PS> $c |fl * +Name : Win32_Process +__GENUS : 1 +__CLASS : Win32_Process +__SUPERCLASS : CIM_Process +__DYNASTY : CIM_ManagedSystemElement +__RELPATH : Win32_Process +__PROPERTY_COUNT : 45 +__DERIVATION : {CIM_Process, CIM_LogicalElement, + CIM_ManagedSystemElement} +__SERVER : SERVER01 +__NAMESPACE : ROOT\cimv2 __PATH : \\SERVER01\ROOT\cimv2:Win32_Process ``` - -[WMI] is a type accelerator for ManagementObject. This has a string constructor that takes a local or absolute WMI path to a WMI instance and returns an object that is bound to that instance. +[WMI] is a type accelerator for ManagementObject. This has a string +constructor that takes a local or absolute WMI path to a WMI instance and +returns an object that is bound to that instance. For example: - -``` -PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' -PS> $p.Name +```powershell +PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' +PS> $p.Name OUTLOOK.EXE ``` - - ### WMI TROUBLESHOOTING -The following problems are the most common problems that might occur when you try to connect to a remote computer. -Problem 1: The remote computer is not online. - -If a computer is offline, you will not be able to connect to it by using WMI. You may receive the following error message: +The following problems are the most common problems that might occur when you +try to connect to a remote computer. +Problem 1: The remote computer is not online. -``` -"Remote server machine does not exist or is unavailable" -``` +If a computer is offline, you will not be able to connect to it by using WMI. +You may receive the following error message: + Remote server machine does not exist or is unavailable -If you receive this error message, verify that the computer is online. Try to ping the remote computer. +If you receive this error message, verify that the computer is online. Try to +ping the remote computer. Problem 2: You do not have local administrator rights on the remote computer. -To use WMI remotely, you must have local administrator rights on the remote computer. If you do not, access to that computer will be denied. +To use WMI remotely, you must have local administrator rights on the remote +computer. If you do not, access to that computer will be denied. To verify namespace security: -- a. Click Start, right-click My Computer, and then click Manage. - -- b. In Computer Management, expand Services and Applications, right-click WMI Control, and then click Properties. - -- c. In the WMI Control Properties dialog box, click the Security tab. +1. Click Start, right-click My Computer, and then click Manage. +2. In Computer Management, expand Services and Applications, right-click WMI + Control, and then click Properties. +3. In the WMI Control Properties dialog box, click the Security tab. Problem 3: A firewall is blocking access to the remote computer. -WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols to traverse the network. By default, many firewalls block DCOM and RPC traffic. If your firewall is blocking these protocols, your connection will fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is configured to automatically block all unsolicited network traffic, including DCOM and WMI. In its default configuration, Windows Firewall rejects an incoming WMI request, and you receive the following error message: - - -``` -"Remote server machine does not exist or is unavailable" -``` - +WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols +to traverse the network. By default, many firewalls block DCOM and RPC +traffic. If your firewall is blocking these protocols, your connection will +fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is +configured to automatically block all unsolicited network traffic, including +DCOM and WMI. In its default configuration, Windows Firewall rejects an +incoming WMI request, and you receive the following error message: + Remote server machine does not exist or is unavailable ### MORE INFORMATION ABOUT WMI -For more information about WMI, see the following topics in the MSDN (Microsoft Developer Network) library: +For more information about WMI, see the following topics in the MSDN +(Microsoft Developer Network) library: -``` -"About WMI: -http://go.microsoft.com/fwlink/?LinkId=142212 - -"WMI Troubleshooting" -http://go.microsoft.com/fwlink/?LinkId=142213 -``` - +About WMI: http://go.microsoft.com/fwlink/?LinkId=142212 -And, see "Secrets of Windows Management Instrumentation - Troubleshooting and Tips" in the Microsoft TechNet Script Center: +WMI Troubleshooting: http://go.microsoft.com/fwlink/?LinkId=142213 +And, see "Secrets of Windows Management Instrumentation - Troubleshooting and +Tips" in the Microsoft TechNet Script Center: -``` http://go.microsoft.com/fwlink/?LinkId=142214 -``` - ## SEE ALSO -Online version: http:\/\/go.microsoft.com\/fwlink\/?LinkId\=142219 Get-WmiObject diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Windows_RT.md b/reference/6/Microsoft.PowerShell.Core/About/about_Windows_RT.md deleted file mode 100644 index b58501e4a35e..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Windows_RT.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_Windows_RT ---- - -# About Windows RT -## about_Windows_RT - - -## SHORT DESCRIPTION -Explains limitations of Windows PowerShell 4.0 on Windows RT 8.1. - - -## LONG DESCRIPTION -The Windows RT 8.1 operating system is installed on computers and devices (such as Microsoft Surface 2, on which it is the operating system that ships with the computer) that use Advanced RISC Machine (ARM) processors. - -Windows PowerShell 4.0 is included in Windows RT 8.1. All cmdlets, providers, and modules, and most scripts designed for Windows PowerShell 2.0 and later releases run on Windows RT 8.1 without changes. - -Because Windows RT 8.1 does not include all Windows features, some Windows PowerShell features work differently or do not work on Windows RT-based devices. The following list explains the differences. - --- Windows PowerShell ISE is not included in and cannot run on Windows RT 8.1. Windows PowerShell ISE requires Windows Presentation Foundation, which is not included in Windows RT 8.1. - --- Windows PowerShell remoting and the WinRM service are disabled by default. To enable remoting, run the Enable-PSRemoting cmdlet. Also, run the Set-Service cmdlet to set the startup type of the WinRM service to Automatic, or Automatic (Delayed Start). - -While remoting is disabled, you can use Windows PowerShell remoting to run commands on other computers, but other computers cannot run commands on the Windows RT device. Also, implicit remoting—that is, remoting that is built in to a cmdlet or script, and not explicitly requested with added parameters—does not work in Windows PowerShell running on Windows RT 8.1. - --- Domain-joined computing and Kerberos authentication are not supported on Windows RT 8.1. You cannot use Windows PowerShell to add or manage these features. - --- Microsoft .NET Framework classes that are not supported on Windows RT 8.1 are also not supported by Windows PowerShell on Windows RT 8.1. - --- Transactions are not enabled on Windows RT 8.1. Transaction cmdlets, such as Start-Transaction, and transaction parameters, such as UseTransaction, do not work properly. - --- All Windows PowerShell sessions on Windows RT 8.1 devices use the ConstrainedLanguage language mode. ConstrainedLanguage language mode is a companion to User Mode Code Integrity (UMCI). It permits all Windows cmdlets and Windows PowerShell language elements, but restricts types to ensure that users cannot use Windows PowerShell to circumvent or violate the UMCI protections. - -For more information about ConstrainedLanguage language mode, see about_Language_Modes. - -## SEE ALSO - -[about_Language_Modes](about_Language_Modes.md) - -[about_Remote](about_Remote.md) - -about_Workflows - -Windows PowerShell System Requirements: (http://technet.microsoft.com/library/hh857337.aspx) - -## KEYWORDS -about_ARM, about_PowerShell_on_ARM, about_PowerShell_on_Surface, about_Windows_RT_8.1 about_WindowsRT - From bbe8f07b2131e4d633c7365697b7e4b8514a7da6 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 4 Dec 2017 10:43:35 -0800 Subject: [PATCH 086/188] Fixed formatting of output per issue #808 --- .../Export-Csv.md | 122 +++++++------ .../Export-Csv.md | 128 ++++++++------ .../Export-Csv.md | 96 +++++----- .../Export-Csv.md | 97 ++++++----- .../Export-Csv.md | 164 +++++++++--------- 5 files changed, 322 insertions(+), 285 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Export-Csv.md b/reference/3.0/Microsoft.PowerShell.Utility/Export-Csv.md index 66d8cbcfc72f..9b41f2e80631 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Export-Csv.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Export-Csv.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -9,8 +9,10 @@ title: Export-Csv --- # Export-Csv + ## SYNOPSIS Converts objects into a series of comma-separated (CSV) strings and saves the strings in a CSV file. + ## SYNTAX ### Delimiter (Default) @@ -48,37 +50,35 @@ This command selects a few properties of the WmiPrvse process and exports them t ### Example 2: Export processes to a comma-delimited file ```powershell Get-Process | Export-Csv -Path "processes.csv" -<# -In processes.csv: +Get-Content -Path "processes.csv" +``` +```Output #TYPE System.Diagnostics.Process -__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... -Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... +__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... +Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... - -#> ``` -This command exports objects representing the processes on the computer to the Processes.csv file in the current directory. +This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. Because it does not specify a delimiter, a comma (`,`) is used to separate the fields in the file. ### Example 3: Export processes to a semicolon-delimited file ```powershell Get-Process | Export-Csv -Path "processes.csv" -Delimiter ";" -<# - -In processes.csv: +Get-Content -Path "processes.csv" +``` +```Output #TYPE System.Diagnostics.Process -__NounName;Name;Handles;VM;WS;PM;NPM;Path;Company;CPU;FileVersion;... -Process;powershell;626;201666560;76058624;61943808;11960;C:\WINDOWS... +__NounName;Name;Handles;VM;WS;PM;NPM;Path;Company;CPU;FileVersion;... +Process;powershell;626;201666560;76058624;61943808;11960;C:\WINDOWS... Process;powershell;257;151920640;38322176;37052416;7836;C:\WINDOWS\... -#> ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-Delimiter` parameter to specify the semicolon (`;`). +It uses the **-Delimiter** parameter to specify the semicolon (`;`). As a result, the fields in the file are separated by semicolons. ### Example 4: Export using the list separator of the current culture @@ -87,23 +87,22 @@ Get-Process | Export-Csv -Path "processes.csv" -UseCulture ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-UseCulture` parameter to direct `Export-CSV` to use the delimiter specified by the ListSeparator property of the current culture. +It uses the `-UseCulture` parameter to direct `Export-CSV` to use the delimiter specified by the **ListSeparator** property of the current culture. ### Example 5: Export processes without type information ```powershell Get-Process | Export-Csv -Path "processes.csv" -NoTypeInformation -<# -In processes.csv: +Get-Content -Path "processes.csv" +``` -__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... -Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... +```Output +__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... +Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... - -#> ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-NoTypeInformation` parameter to suppress the type information in the file. +It uses the **-NoTypeInformation** parameter to suppress the type information in the file. ### Example 6: Export and append script properties ```powershell @@ -116,7 +115,7 @@ The second command uses the `Select-Object` cmdlet to select the relevant proper The third command uses a pipeline operator (`|`) to send the script file information in the `$ScriptFiles` variable to the `Export-CSV` cmdlet. The command uses the `-Path` parameter to specify the output file and the `-Append` parameter to add the new script data to the end of the output file, instead of replacing the existing file contents. -These commands add information about new Windows PowerShell scripts to a script inventory file. +These commands add information about new PowerShell scripts to a script inventory file. The first command uses the `Get-ChildItem` cmdlet to do a recursive search in the `D:` drive for files with the `.ps1` file name extension. It uses a pipeline operator to sends the results to the `Where-Object` cmdlet, which gets only files that were created after January 1, 2011, and then saves them in the `$ScriptFiles` variable. @@ -124,27 +123,31 @@ It uses a pipeline operator to sends the results to the `Where-Object` cmdlet, w ### Example 7: Select properties to export ```powershell Get-Date | Select-Object -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -NoTypeInformation -<# -In Date.csv: - -"DateTime","Day","DayOfWeek","DayOfYear""Tuesday, October 05, 2010 2:45:13 PM","5","Tuesday","278" +Get-Content -Path "Date.csv" +``` -#> +```Output +"DateTime","Day","DayOfWeek","DayOfYear" +"Tuesday, October 05, 2010 2:45:13 PM","5","Tuesday","278" +``` +```powershell Get-Date | Format-Table -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -NoTypeInformation -<# -In Date.csv: +Get-Content -Path "Date.csv" +``` +```Output "ClassId2e4f51ef21dd47e99d3c952918aff9cd","pageHeaderEntry","pageFooterEntry","autosizeInfo","shapeInfo","groupingEntry" -"033ecb2bc07a4d43b5ef94ed5a35d280",,,,"Microsoft.PowerShell.Commands.Internal.Format.TableHeaderInfo","9e210fe47d09416682b841769c78b8a3" -,,,,,"27c87ef9bbda4f709f6b4002fa4af63c",,,,,"4ec4f0187cb04f4cb6973460dfe252df",,,,,"cf522b78d86c486691226b40aa69e95c",,,,, - -#> +"033ecb2bc07a4d43b5ef94ed5a35d280",,,,"Microsoft.PowerShell.Commands.Internal.Format.TableHeaderInfo", +"9e210fe47d09416682b841769c78b8a3",,,,, +"27c87ef9bbda4f709f6b4002fa4af63c",,,,, +"4ec4f0187cb04f4cb6973460dfe252df",,,,, +"cf522b78d86c486691226b40aa69e95c",,,,, ``` The first command shows how to select properties of an object and export them to a CSV file. This command uses the `Get-Date` cmdlet to get the current date and time. It uses the `Select-Object` cmdlet to select the desired properties, and the `Export-CSV` cmdlet to export the object and its properties to the `Date.csv` file. The output shows the expected content in the `Date.csv` file. -The second command shows that when you use the `Format-Table` cmdlet to format your data before exporting it, the output is not useful. +The second command shows that when you use the `Format-Table` cmdlet to format your data before exporting it, the output is not useful. This example demonstrates one of most common problems that users encounter when using the `Export-CSV` cmdlet. It explains how to recognize and avoid this error. @@ -166,7 +169,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -199,11 +202,11 @@ To specify a semicolon (`;`), enclose it in quotation marks. ```yaml Type: Char Parameter Sets: Delimiter -Aliases: +Aliases: Required: False -Position: 2 -Default value: , (comma) +Position: 1 +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -226,22 +229,23 @@ The default value is ASCII. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: +Accepted values: Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, OEM Required: False Position: Named -Default value: ASCII +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Force -Overwrites the file specified in path without prompting. +Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -304,7 +308,8 @@ Accept wildcard characters: False ### -NoTypeInformation Indicates that this cmdlet omits the type information from the CSV file. -By default, the first line of the CSV file contains `#TYPE` followed by the fully-qualified name of the type of the object. +This is the default behavior beginning with PowerShell 6.0. +This parameter is included for backwards compatibility. ```yaml Type: SwitchParameter @@ -313,7 +318,7 @@ Aliases: NTI Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -325,30 +330,30 @@ This parameter is required. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 1 -Default value: Current location +Position: 0 +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -UseCulture -Use the list separator for the current culture as the item delimiter. -The default is a comma (,). +Indicates that this cmdlet uses the list separator for the current culture as the item delimiter. +The default is a comma (`,`). This parameter is very useful in scripts that are being distributed to users worldwide. -To find the list separator for a culture, use the following command: (Get-Culture).TextInfo.ListSeparator. +To find the list separator for a culture, use the following command: `(Get-Culture).TextInfo.ListSeparator`. ```yaml Type: SwitchParameter Parameter Sets: UseCulture -Aliases: +Aliases: Required: False Position: Named -Default value: Comma +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -383,7 +388,8 @@ You can pipe any object with an Extended Type System (ETS) adapter to `Export-CS The CSV list is sent to the file designated in the Path parameter. ## NOTES -* The `Export-CSV` cmdlet converts the objects that you submit into a series of CSV variable-length strings and saves them in the specified text file. You can use `Export-CSV` to save objects in a CSV file and then use the Import-Csv cmdlet to create objects from the text in the CSV file. +* The `Export-CSV` cmdlet converts the objects that you submit into a series of CSV variable-length strings and saves them in the specified text file. + You can use `Export-CSV` to save objects in a CSV file and then use the Import-Csv cmdlet to create objects from the text in the CSV file. In the CSV file, 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. @@ -391,8 +397,8 @@ The property values are converted to strings (by using the `ToString()` method o The format of an exported file is as follows: - - The first line of the CSV file contains the string `#TYPE` followed by the fully qualified name of the object, such as `#TYPE System.Diagnostics.Process`. -To suppress this line, use the `-NoTypeInformation` parameter. + - The first line of the CSV file contains the string #TYPE followed by the fully qualified name of the object, such as `#TYPE System.Diagnostics.Process`. +This line will not be included by default. You must specify `-IncludeTypeInformation` to include type information. - The next line of the CSV file represents the column headers. It contains a comma-separated list of the names of all the properties of the first object. @@ -415,3 +421,5 @@ It contains a comma-separated list of the names of all the properties of the fir [Select-Object](Select-Object.md) +[Where-Object](../Microsoft.PowerShell.Core/Where-Object.md) + diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Export-Csv.md b/reference/4.0/Microsoft.PowerShell.Utility/Export-Csv.md index e1f7eb42bdf8..f4b027909e92 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Export-Csv.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Export-Csv.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -50,37 +50,35 @@ This command selects a few properties of the WmiPrvse process and exports them t ### Example 2: Export processes to a comma-delimited file ```powershell Get-Process | Export-Csv -Path "processes.csv" -<# -In processes.csv: +Get-Content -Path "processes.csv" +``` +```Output #TYPE System.Diagnostics.Process -__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... -Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... +__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... +Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... - -#> ``` -This command exports objects representing the processes on the computer to the Processes.csv file in the current directory. +This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. Because it does not specify a delimiter, a comma (`,`) is used to separate the fields in the file. ### Example 3: Export processes to a semicolon-delimited file ```powershell Get-Process | Export-Csv -Path "processes.csv" -Delimiter ";" -<# - -In processes.csv: +Get-Content -Path "processes.csv" +``` +```Output #TYPE System.Diagnostics.Process -__NounName;Name;Handles;VM;WS;PM;NPM;Path;Company;CPU;FileVersion;... -Process;powershell;626;201666560;76058624;61943808;11960;C:\WINDOWS... +__NounName;Name;Handles;VM;WS;PM;NPM;Path;Company;CPU;FileVersion;... +Process;powershell;626;201666560;76058624;61943808;11960;C:\WINDOWS... Process;powershell;257;151920640;38322176;37052416;7836;C:\WINDOWS\... -#> ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-Delimiter` parameter to specify the semicolon (`;`). +It uses the **-Delimiter** parameter to specify the semicolon (`;`). As a result, the fields in the file are separated by semicolons. ### Example 4: Export using the list separator of the current culture @@ -89,23 +87,22 @@ Get-Process | Export-Csv -Path "processes.csv" -UseCulture ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-UseCulture` parameter to direct `Export-CSV` to use the delimiter specified by the ListSeparator property of the current culture. +It uses the `-UseCulture` parameter to direct `Export-CSV` to use the delimiter specified by the **ListSeparator** property of the current culture. ### Example 5: Export processes without type information ```powershell Get-Process | Export-Csv -Path "processes.csv" -NoTypeInformation -<# -In processes.csv: +Get-Content -Path "processes.csv" +``` -__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... -Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... +```Output +__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... +Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... - -#> ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-NoTypeInformation` parameter to suppress the type information in the file. +It uses the **-NoTypeInformation** parameter to suppress the type information in the file. ### Example 6: Export and append script properties ```powershell @@ -118,7 +115,7 @@ The second command uses the `Select-Object` cmdlet to select the relevant proper The third command uses a pipeline operator (`|`) to send the script file information in the `$ScriptFiles` variable to the `Export-CSV` cmdlet. The command uses the `-Path` parameter to specify the output file and the `-Append` parameter to add the new script data to the end of the output file, instead of replacing the existing file contents. -These commands add information about new Windows PowerShell scripts to a script inventory file. +These commands add information about new PowerShell scripts to a script inventory file. The first command uses the `Get-ChildItem` cmdlet to do a recursive search in the `D:` drive for files with the `.ps1` file name extension. It uses a pipeline operator to sends the results to the `Where-Object` cmdlet, which gets only files that were created after January 1, 2011, and then saves them in the `$ScriptFiles` variable. @@ -126,27 +123,31 @@ It uses a pipeline operator to sends the results to the `Where-Object` cmdlet, w ### Example 7: Select properties to export ```powershell Get-Date | Select-Object -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -NoTypeInformation -<# -In Date.csv: - -"DateTime","Day","DayOfWeek","DayOfYear""Tuesday, October 05, 2010 2:45:13 PM","5","Tuesday","278" +Get-Content -Path "Date.csv" +``` -#> +```Output +"DateTime","Day","DayOfWeek","DayOfYear" +"Tuesday, October 05, 2010 2:45:13 PM","5","Tuesday","278" +``` +```powershell Get-Date | Format-Table -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -NoTypeInformation -<# -In Date.csv: +Get-Content -Path "Date.csv" +``` +```Output "ClassId2e4f51ef21dd47e99d3c952918aff9cd","pageHeaderEntry","pageFooterEntry","autosizeInfo","shapeInfo","groupingEntry" -"033ecb2bc07a4d43b5ef94ed5a35d280",,,,"Microsoft.PowerShell.Commands.Internal.Format.TableHeaderInfo","9e210fe47d09416682b841769c78b8a3" -,,,,,"27c87ef9bbda4f709f6b4002fa4af63c",,,,,"4ec4f0187cb04f4cb6973460dfe252df",,,,,"cf522b78d86c486691226b40aa69e95c",,,,, - -#> +"033ecb2bc07a4d43b5ef94ed5a35d280",,,,"Microsoft.PowerShell.Commands.Internal.Format.TableHeaderInfo", +"9e210fe47d09416682b841769c78b8a3",,,,, +"27c87ef9bbda4f709f6b4002fa4af63c",,,,, +"4ec4f0187cb04f4cb6973460dfe252df",,,,, +"cf522b78d86c486691226b40aa69e95c",,,,, ``` The first command shows how to select properties of an object and export them to a CSV file. This command uses the `Get-Date` cmdlet to get the current date and time. It uses the `Select-Object` cmdlet to select the desired properties, and the `Export-CSV` cmdlet to export the object and its properties to the `Date.csv` file. The output shows the expected content in the `Date.csv` file. -The second command shows that when you use the `Format-Table` cmdlet to format your data before exporting it, the output is not useful. +The second command shows that when you use the `Format-Table` cmdlet to format your data before exporting it, the output is not useful. This example demonstrates one of most common problems that users encounter when using the `Export-CSV` cmdlet. It explains how to recognize and avoid this error. @@ -168,7 +169,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -201,39 +202,50 @@ To specify a semicolon (`;`), enclose it in quotation marks. ```yaml Type: Char Parameter Sets: Delimiter -Aliases: +Aliases: Required: False -Position: 2 -Default value: , (comma) +Position: 1 +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Encoding Specifies the encoding for the exported CSV file. -Valid values are Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, and OEM. -The default is ASCII. +The acceptable values for this parameter are: + +- Unicode +- UTF7 +- UTF8 +- ASCII +- UTF32 +- BigEndianUnicode +- Default +- OEM + +The default value is ASCII. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: +Accepted values: Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, OEM Required: False Position: Named -Default value: ASCII +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Force -Overwrites the file specified in path without prompting. +Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -296,7 +308,8 @@ Accept wildcard characters: False ### -NoTypeInformation Indicates that this cmdlet omits the type information from the CSV file. -By default, the first line of the CSV file contains `#TYPE` followed by the fully-qualified name of the type of the object. +This is the default behavior beginning with PowerShell 6.0. +This parameter is included for backwards compatibility. ```yaml Type: SwitchParameter @@ -305,7 +318,7 @@ Aliases: NTI Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -317,11 +330,11 @@ This parameter is required. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 1 -Default value: Current location +Position: 0 +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -336,11 +349,11 @@ To find the list separator for a culture, use the following command: `(Get-Cultu ```yaml Type: SwitchParameter Parameter Sets: UseCulture -Aliases: +Aliases: Required: False Position: Named -Default value: Comma +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -375,7 +388,8 @@ You can pipe any object with an Extended Type System (ETS) adapter to `Export-CS The CSV list is sent to the file designated in the Path parameter. ## NOTES -* The `Export-CSV` cmdlet converts the objects that you submit into a series of CSV variable-length strings and saves them in the specified text file. You can use `Export-CSV` to save objects in a CSV file and then use the Import-Csv cmdlet to create objects from the text in the CSV file. +* The `Export-CSV` cmdlet converts the objects that you submit into a series of CSV variable-length strings and saves them in the specified text file. + You can use `Export-CSV` to save objects in a CSV file and then use the Import-Csv cmdlet to create objects from the text in the CSV file. In the CSV file, 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. @@ -383,8 +397,8 @@ The property values are converted to strings (by using the `ToString()` method o The format of an exported file is as follows: - - The first line of the CSV file contains the string `#TYPE` followed by the fully qualified name of the object, such as `#TYPE System.Diagnostics.Process`. -To suppress this line, use the `-NoTypeInformation` parameter. + - The first line of the CSV file contains the string #TYPE followed by the fully qualified name of the object, such as `#TYPE System.Diagnostics.Process`. +This line will not be included by default. You must specify `-IncludeTypeInformation` to include type information. - The next line of the CSV file represents the column headers. It contains a comma-separated list of the names of all the properties of the first object. @@ -407,3 +421,5 @@ It contains a comma-separated list of the names of all the properties of the fir [Select-Object](Select-Object.md) +[Where-Object](../Microsoft.PowerShell.Core/Where-Object.md) + diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Export-Csv.md b/reference/5.0/Microsoft.PowerShell.Utility/Export-Csv.md index ccc555d2720c..f628f366c865 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Export-Csv.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Export-Csv.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -50,37 +50,35 @@ This command selects a few properties of the WmiPrvse process and exports them t ### Example 2: Export processes to a comma-delimited file ```powershell Get-Process | Export-Csv -Path "processes.csv" -<# -In processes.csv: +Get-Content -Path "processes.csv" +``` +```Output #TYPE System.Diagnostics.Process -__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... -Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... +__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... +Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... - -#> ``` -This command exports objects representing the processes on the computer to the Processes.csv file in the current directory. +This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. Because it does not specify a delimiter, a comma (`,`) is used to separate the fields in the file. ### Example 3: Export processes to a semicolon-delimited file ```powershell Get-Process | Export-Csv -Path "processes.csv" -Delimiter ";" -<# - -In processes.csv: +Get-Content -Path "processes.csv" +``` +```Output #TYPE System.Diagnostics.Process -__NounName;Name;Handles;VM;WS;PM;NPM;Path;Company;CPU;FileVersion;... -Process;powershell;626;201666560;76058624;61943808;11960;C:\WINDOWS... +__NounName;Name;Handles;VM;WS;PM;NPM;Path;Company;CPU;FileVersion;... +Process;powershell;626;201666560;76058624;61943808;11960;C:\WINDOWS... Process;powershell;257;151920640;38322176;37052416;7836;C:\WINDOWS\... -#> ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-Delimiter` parameter to specify the semicolon (`;`). +It uses the **-Delimiter** parameter to specify the semicolon (`;`). As a result, the fields in the file are separated by semicolons. ### Example 4: Export using the list separator of the current culture @@ -89,23 +87,22 @@ Get-Process | Export-Csv -Path "processes.csv" -UseCulture ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-UseCulture` parameter to direct `Export-CSV` to use the delimiter specified by the ListSeparator property of the current culture. +It uses the `-UseCulture` parameter to direct `Export-CSV` to use the delimiter specified by the **ListSeparator** property of the current culture. ### Example 5: Export processes without type information ```powershell Get-Process | Export-Csv -Path "processes.csv" -NoTypeInformation -<# -In processes.csv: +Get-Content -Path "processes.csv" +``` -__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... -Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... +```Output +__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... +Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... - -#> ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-NoTypeInformation` parameter to suppress the type information in the file. +It uses the **-NoTypeInformation** parameter to suppress the type information in the file. ### Example 6: Export and append script properties ```powershell @@ -118,7 +115,7 @@ The second command uses the `Select-Object` cmdlet to select the relevant proper The third command uses a pipeline operator (`|`) to send the script file information in the `$ScriptFiles` variable to the `Export-CSV` cmdlet. The command uses the `-Path` parameter to specify the output file and the `-Append` parameter to add the new script data to the end of the output file, instead of replacing the existing file contents. -These commands add information about new Windows PowerShell scripts to a script inventory file. +These commands add information about new PowerShell scripts to a script inventory file. The first command uses the `Get-ChildItem` cmdlet to do a recursive search in the `D:` drive for files with the `.ps1` file name extension. It uses a pipeline operator to sends the results to the `Where-Object` cmdlet, which gets only files that were created after January 1, 2011, and then saves them in the `$ScriptFiles` variable. @@ -126,27 +123,31 @@ It uses a pipeline operator to sends the results to the `Where-Object` cmdlet, w ### Example 7: Select properties to export ```powershell Get-Date | Select-Object -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -NoTypeInformation -<# -In Date.csv: - -"DateTime","Day","DayOfWeek","DayOfYear""Tuesday, October 05, 2010 2:45:13 PM","5","Tuesday","278" +Get-Content -Path "Date.csv" +``` -#> +```Output +"DateTime","Day","DayOfWeek","DayOfYear" +"Tuesday, October 05, 2010 2:45:13 PM","5","Tuesday","278" +``` +```powershell Get-Date | Format-Table -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -NoTypeInformation -<# -In Date.csv: +Get-Content -Path "Date.csv" +``` +```Output "ClassId2e4f51ef21dd47e99d3c952918aff9cd","pageHeaderEntry","pageFooterEntry","autosizeInfo","shapeInfo","groupingEntry" -"033ecb2bc07a4d43b5ef94ed5a35d280",,,,"Microsoft.PowerShell.Commands.Internal.Format.TableHeaderInfo","9e210fe47d09416682b841769c78b8a3" -,,,,,"27c87ef9bbda4f709f6b4002fa4af63c",,,,,"4ec4f0187cb04f4cb6973460dfe252df",,,,,"cf522b78d86c486691226b40aa69e95c",,,,, - -#> +"033ecb2bc07a4d43b5ef94ed5a35d280",,,,"Microsoft.PowerShell.Commands.Internal.Format.TableHeaderInfo", +"9e210fe47d09416682b841769c78b8a3",,,,, +"27c87ef9bbda4f709f6b4002fa4af63c",,,,, +"4ec4f0187cb04f4cb6973460dfe252df",,,,, +"cf522b78d86c486691226b40aa69e95c",,,,, ``` The first command shows how to select properties of an object and export them to a CSV file. This command uses the `Get-Date` cmdlet to get the current date and time. It uses the `Select-Object` cmdlet to select the desired properties, and the `Export-CSV` cmdlet to export the object and its properties to the `Date.csv` file. The output shows the expected content in the `Date.csv` file. -The second command shows that when you use the `Format-Table` cmdlet to format your data before exporting it, the output is not useful. +The second command shows that when you use the `Format-Table` cmdlet to format your data before exporting it, the output is not useful. This example demonstrates one of most common problems that users encounter when using the `Export-CSV` cmdlet. It explains how to recognize and avoid this error. @@ -168,7 +169,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -201,7 +202,7 @@ To specify a semicolon (`;`), enclose it in quotation marks. ```yaml Type: Char Parameter Sets: Delimiter -Aliases: +Aliases: Required: False Position: 1 @@ -228,7 +229,7 @@ The default value is ASCII. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, OEM Required: False @@ -244,7 +245,7 @@ Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -307,7 +308,8 @@ Accept wildcard characters: False ### -NoTypeInformation Indicates that this cmdlet omits the type information from the CSV file. -By default, the first line of the CSV file contains `#TYPE` followed by the fully-qualified name of the type of the object. +This is the default behavior beginning with PowerShell 6.0. +This parameter is included for backwards compatibility. ```yaml Type: SwitchParameter @@ -323,11 +325,12 @@ Accept wildcard characters: False ### -Path Specifies the path to the CSV output file. +This parameter is required. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 0 @@ -346,7 +349,7 @@ To find the list separator for a culture, use the following command: `(Get-Cultu ```yaml Type: SwitchParameter Parameter Sets: UseCulture -Aliases: +Aliases: Required: False Position: Named @@ -385,7 +388,8 @@ You can pipe any object with an Extended Type System (ETS) adapter to `Export-CS The CSV list is sent to the file designated in the Path parameter. ## NOTES -* The `Export-CSV` cmdlet converts the objects that you submit into a series of CSV variable-length strings and saves them in the specified text file. You can use `Export-CSV` to save objects in a CSV file and then use the Import-Csv cmdlet to create objects from the text in the CSV file. +* The `Export-CSV` cmdlet converts the objects that you submit into a series of CSV variable-length strings and saves them in the specified text file. + You can use `Export-CSV` to save objects in a CSV file and then use the Import-Csv cmdlet to create objects from the text in the CSV file. In the CSV file, 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. @@ -393,8 +397,8 @@ The property values are converted to strings (by using the `ToString()` method o The format of an exported file is as follows: - - The first line of the CSV file contains the string `#TYPE` followed by the fully qualified name of the object, such as `#TYPE System.Diagnostics.Process`. -To suppress this line, use the `-NoTypeInformation` parameter. + - The first line of the CSV file contains the string #TYPE followed by the fully qualified name of the object, such as `#TYPE System.Diagnostics.Process`. +This line will not be included by default. You must specify `-IncludeTypeInformation` to include type information. - The next line of the CSV file represents the column headers. It contains a comma-separated list of the names of all the properties of the first object. diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Export-Csv.md b/reference/5.1/Microsoft.PowerShell.Utility/Export-Csv.md index fb8faa02bb42..f628f366c865 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Export-Csv.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Export-Csv.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -50,37 +50,35 @@ This command selects a few properties of the WmiPrvse process and exports them t ### Example 2: Export processes to a comma-delimited file ```powershell Get-Process | Export-Csv -Path "processes.csv" -<# -In processes.csv: +Get-Content -Path "processes.csv" +``` +```Output #TYPE System.Diagnostics.Process -__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... -Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... +__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... +Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... - -#> ``` -This command exports objects representing the processes on the computer to the Processes.csv file in the current directory. +This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. Because it does not specify a delimiter, a comma (`,`) is used to separate the fields in the file. ### Example 3: Export processes to a semicolon-delimited file ```powershell Get-Process | Export-Csv -Path "processes.csv" -Delimiter ";" -<# - -In processes.csv: +Get-Content -Path "processes.csv" +``` +```Output #TYPE System.Diagnostics.Process -__NounName;Name;Handles;VM;WS;PM;NPM;Path;Company;CPU;FileVersion;... -Process;powershell;626;201666560;76058624;61943808;11960;C:\WINDOWS... +__NounName;Name;Handles;VM;WS;PM;NPM;Path;Company;CPU;FileVersion;... +Process;powershell;626;201666560;76058624;61943808;11960;C:\WINDOWS... Process;powershell;257;151920640;38322176;37052416;7836;C:\WINDOWS\... -#> ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-Delimiter` parameter to specify the semicolon (`;`). +It uses the **-Delimiter** parameter to specify the semicolon (`;`). As a result, the fields in the file are separated by semicolons. ### Example 4: Export using the list separator of the current culture @@ -89,23 +87,22 @@ Get-Process | Export-Csv -Path "processes.csv" -UseCulture ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-UseCulture` parameter to direct `Export-CSV` to use the delimiter specified by the ListSeparator property of the current culture. +It uses the `-UseCulture` parameter to direct `Export-CSV` to use the delimiter specified by the **ListSeparator** property of the current culture. ### Example 5: Export processes without type information ```powershell Get-Process | Export-Csv -Path "processes.csv" -NoTypeInformation -<# -In processes.csv: +Get-Content -Path "processes.csv" +``` -__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... -Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... +```Output +__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... +Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... - -#> ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-NoTypeInformation` parameter to suppress the type information in the file. +It uses the **-NoTypeInformation** parameter to suppress the type information in the file. ### Example 6: Export and append script properties ```powershell @@ -118,7 +115,7 @@ The second command uses the `Select-Object` cmdlet to select the relevant proper The third command uses a pipeline operator (`|`) to send the script file information in the `$ScriptFiles` variable to the `Export-CSV` cmdlet. The command uses the `-Path` parameter to specify the output file and the `-Append` parameter to add the new script data to the end of the output file, instead of replacing the existing file contents. -These commands add information about new Windows PowerShell scripts to a script inventory file. +These commands add information about new PowerShell scripts to a script inventory file. The first command uses the `Get-ChildItem` cmdlet to do a recursive search in the `D:` drive for files with the `.ps1` file name extension. It uses a pipeline operator to sends the results to the `Where-Object` cmdlet, which gets only files that were created after January 1, 2011, and then saves them in the `$ScriptFiles` variable. @@ -126,27 +123,31 @@ It uses a pipeline operator to sends the results to the `Where-Object` cmdlet, w ### Example 7: Select properties to export ```powershell Get-Date | Select-Object -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -NoTypeInformation -<# -In Date.csv: - -"DateTime","Day","DayOfWeek","DayOfYear""Tuesday, October 05, 2010 2:45:13 PM","5","Tuesday","278" +Get-Content -Path "Date.csv" +``` -#> +```Output +"DateTime","Day","DayOfWeek","DayOfYear" +"Tuesday, October 05, 2010 2:45:13 PM","5","Tuesday","278" +``` +```powershell Get-Date | Format-Table -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -NoTypeInformation -<# -In Date.csv: +Get-Content -Path "Date.csv" +``` +```Output "ClassId2e4f51ef21dd47e99d3c952918aff9cd","pageHeaderEntry","pageFooterEntry","autosizeInfo","shapeInfo","groupingEntry" -"033ecb2bc07a4d43b5ef94ed5a35d280",,,,"Microsoft.PowerShell.Commands.Internal.Format.TableHeaderInfo","9e210fe47d09416682b841769c78b8a3" -,,,,,"27c87ef9bbda4f709f6b4002fa4af63c",,,,,"4ec4f0187cb04f4cb6973460dfe252df",,,,,"cf522b78d86c486691226b40aa69e95c",,,,, - -#> +"033ecb2bc07a4d43b5ef94ed5a35d280",,,,"Microsoft.PowerShell.Commands.Internal.Format.TableHeaderInfo", +"9e210fe47d09416682b841769c78b8a3",,,,, +"27c87ef9bbda4f709f6b4002fa4af63c",,,,, +"4ec4f0187cb04f4cb6973460dfe252df",,,,, +"cf522b78d86c486691226b40aa69e95c",,,,, ``` The first command shows how to select properties of an object and export them to a CSV file. This command uses the `Get-Date` cmdlet to get the current date and time. It uses the `Select-Object` cmdlet to select the desired properties, and the `Export-CSV` cmdlet to export the object and its properties to the `Date.csv` file. The output shows the expected content in the `Date.csv` file. -The second command shows that when you use the `Format-Table` cmdlet to format your data before exporting it, the output is not useful. +The second command shows that when you use the `Format-Table` cmdlet to format your data before exporting it, the output is not useful. This example demonstrates one of most common problems that users encounter when using the `Export-CSV` cmdlet. It explains how to recognize and avoid this error. @@ -168,7 +169,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -201,7 +202,7 @@ To specify a semicolon (`;`), enclose it in quotation marks. ```yaml Type: Char Parameter Sets: Delimiter -Aliases: +Aliases: Required: False Position: 1 @@ -228,7 +229,7 @@ The default value is ASCII. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, OEM Required: False @@ -244,7 +245,7 @@ Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -307,7 +308,8 @@ Accept wildcard characters: False ### -NoTypeInformation Indicates that this cmdlet omits the type information from the CSV file. -By default, the first line of the CSV file contains `#TYPE` followed by the fully-qualified name of the type of the object. +This is the default behavior beginning with PowerShell 6.0. +This parameter is included for backwards compatibility. ```yaml Type: SwitchParameter @@ -328,7 +330,7 @@ This parameter is required. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: 0 @@ -347,7 +349,7 @@ To find the list separator for a culture, use the following command: `(Get-Cultu ```yaml Type: SwitchParameter Parameter Sets: UseCulture -Aliases: +Aliases: Required: False Position: Named @@ -386,7 +388,8 @@ You can pipe any object with an Extended Type System (ETS) adapter to `Export-CS The CSV list is sent to the file designated in the Path parameter. ## NOTES -* The `Export-CSV` cmdlet converts the objects that you submit into a series of CSV variable-length strings and saves them in the specified text file. You can use `Export-CSV` to save objects in a CSV file and then use the Import-Csv cmdlet to create objects from the text in the CSV file. +* The `Export-CSV` cmdlet converts the objects that you submit into a series of CSV variable-length strings and saves them in the specified text file. + You can use `Export-CSV` to save objects in a CSV file and then use the Import-Csv cmdlet to create objects from the text in the CSV file. In the CSV file, 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. @@ -394,8 +397,8 @@ The property values are converted to strings (by using the `ToString()` method o The format of an exported file is as follows: - - The first line of the CSV file contains the string `#TYPE` followed by the fully qualified name of the object, such as `#TYPE System.Diagnostics.Process`. -To suppress this line, use the `-NoTypeInformation` parameter. + - The first line of the CSV file contains the string #TYPE followed by the fully qualified name of the object, such as `#TYPE System.Diagnostics.Process`. +This line will not be included by default. You must specify `-IncludeTypeInformation` to include type information. - The next line of the CSV file represents the column headers. It contains a comma-separated list of the names of all the properties of the first object. @@ -418,3 +421,5 @@ It contains a comma-separated list of the names of all the properties of the fir [Select-Object](Select-Object.md) +[Where-Object](../Microsoft.PowerShell.Core/Where-Object.md) + diff --git a/reference/6/Microsoft.PowerShell.Utility/Export-Csv.md b/reference/6/Microsoft.PowerShell.Utility/Export-Csv.md index 6ee5c4d96817..339d69c93d9d 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Export-Csv.md +++ b/reference/6/Microsoft.PowerShell.Utility/Export-Csv.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -51,14 +51,13 @@ This command selects a few properties of the WmiPrvse process and exports them t ### Example 2: Export processes to a comma-delimited file ```powershell Get-Process | Export-Csv -Path "processes.csv" -<# -In processes.csv: +Get-Content -Path "processes.csv" +``` -__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... -Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... +```Output +__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... +Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... - -#> ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. @@ -67,18 +66,18 @@ Because it does not specify a delimiter, a comma (`,`) is used to separate the f ### Example 3: Export processes to a semicolon-delimited file ```powershell Get-Process | Export-Csv -Path "processes.csv" -Delimiter ";" -<# -In processes.csv: +Get-Content -Path "processes.csv" +``` -__NounName;Name;Handles;VM;WS;PM;NPM;Path;Company;CPU;FileVersion;... -Process;powershell;626;201666560;76058624;61943808;11960;C:\WINDOWS... +```Output +__NounName;Name;Handles;VM;WS;PM;NPM;Path;Company;CPU;FileVersion;... +Process;powershell;626;201666560;76058624;61943808;11960;C:\WINDOWS... Process;powershell;257;151920640;38322176;37052416;7836;C:\WINDOWS\... -#> ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-Delimiter` parameter to specify the semicolon `;`. +It uses the **-Delimiter** parameter to specify the semicolon (`;`). As a result, the fields in the file are separated by semicolons. ### Example 4: Export using the list separator of the current culture @@ -87,24 +86,23 @@ Get-Process | Export-Csv -Path "processes.csv" -UseCulture ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-UseCulture` parameter to direct `Export-CSV` to use the delimiter specified by the `ListSeparator` property of the current culture. +It uses the `-UseCulture` parameter to direct `Export-CSV` to use the delimiter specified by the **ListSeparator** property of the current culture. ### Example 5: Export processes with type information ```powershell Get-Process | Export-Csv -Path "processes.csv" -IncludeTypeInformation -<# -In processes.csv: +Get-Content -Path "processes.csv" +``` +```Output #TYPE System.Diagnostics.Process -__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... -Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... +__NounName,Name,Handles,VM,WS,PM,NPM,Path,Company,CPU,FileVersion,... +Process,powershell,626,201666560,76058624,61943808,11960,C:\WINDOWS... Process,powershell,257,151920640,38322176,37052416,7836,C:\WINDOWS\... - -#> ``` This command exports objects representing the processes on the computer to the `processes.csv` file in the current directory. -It uses the `-IncludeTypeInformation` parameter to include the type information in the file. +It uses the **-NoTypeInformation** parameter to suppress the type information in the file. ### Example 6: Export and append script properties ```powershell @@ -124,28 +122,32 @@ It uses a pipeline operator to sends the results to the `Where-Object` cmdlet, w ### Example 7: Select properties to export ```powershell -Get-Date | Select-Object -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -<# -In Date.csv: - -"DateTime","Day","DayOfWeek","DayOfYear""Tuesday, October 05, 2010 2:45:13 PM","5","Tuesday","278" +Get-Date | Select-Object -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -NoTypeInformation +Get-Content -Path "Date.csv" +``` -#> +```Output +"DateTime","Day","DayOfWeek","DayOfYear" +"Tuesday, October 05, 2010 2:45:13 PM","5","Tuesday","278" +``` -Get-Date | Format-Table -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -<# -In Date.csv: +```powershell +Get-Date | Format-Table -Property DateTime, Day, DayOfWeek, DayOfYear | Export-Csv -Path Date.csv -NoTypeInformation +Get-Content -Path "Date.csv" +``` +```Output "ClassId2e4f51ef21dd47e99d3c952918aff9cd","pageHeaderEntry","pageFooterEntry","autosizeInfo","shapeInfo","groupingEntry" -"033ecb2bc07a4d43b5ef94ed5a35d280",,,,"Microsoft.PowerShell.Commands.Internal.Format.TableHeaderInfo","9e210fe47d09416682b841769c78b8a3" -,,,,,"27c87ef9bbda4f709f6b4002fa4af63c",,,,,"4ec4f0187cb04f4cb6973460dfe252df",,,,,"cf522b78d86c486691226b40aa69e95c",,,,, - -#> +"033ecb2bc07a4d43b5ef94ed5a35d280",,,,"Microsoft.PowerShell.Commands.Internal.Format.TableHeaderInfo", +"9e210fe47d09416682b841769c78b8a3",,,,, +"27c87ef9bbda4f709f6b4002fa4af63c",,,,, +"4ec4f0187cb04f4cb6973460dfe252df",,,,, +"cf522b78d86c486691226b40aa69e95c",,,,, ``` The first command shows how to select properties of an object and export them to a CSV file. This command uses the `Get-Date` cmdlet to get the current date and time. It uses the `Select-Object` cmdlet to select the desired properties, and the `Export-CSV` cmdlet to export the object and its properties to the `Date.csv` file. The output shows the expected content in the `Date.csv` file. -The second command shows that when you use the `Format-Table` cmdlet to format your data before exporting it, the output is not useful. +The second command shows that when you use the `Format-Table` cmdlet to format your data before exporting it, the output is not useful. This example demonstrates one of most common problems that users encounter when using the `Export-CSV` cmdlet. It explains how to recognize and avoid this error. @@ -167,7 +169,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -176,6 +178,21 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -Delimiter Specifies a delimiter to separate the property values. The default is a comma (`,`). @@ -185,10 +202,10 @@ To specify a semicolon (`;`), enclose it in quotation marks. ```yaml Type: Char Parameter Sets: Delimiter -Aliases: +Aliases: Required: False -Position: 2 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -212,7 +229,7 @@ The default value is ASCII. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, OEM Required: False @@ -228,7 +245,7 @@ Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -264,7 +281,7 @@ You can also pipe objects to `Export-CSV`. ```yaml Type: PSObject Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: Named @@ -273,6 +290,25 @@ Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False ``` +### -LiteralPath +Specifies the path to the CSV output file. +Unlike `-Path`, the value of the `-LiteralPath` parameter is used exactly as it is typed. +No characters are interpreted as wildcards. +If the path includes escape characters, enclose it in single quotation marks. +Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: PSPath + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -NoClobber Indicates that this cmdlet does not overwrite of an existing file. By default, if a file exists in the specified path, `Export-CSV` overwrites the file without warning. @@ -291,7 +327,8 @@ Accept wildcard characters: False ### -NoTypeInformation Indicates that this cmdlet omits the type information from the CSV file. -This behavior is default beginning with PowerShell 6.0. This parameter is included for backwards compatibility. +This is the default behavior beginning with PowerShell 6.0. +This parameter is included for backwards compatibility. ```yaml Type: SwitchParameter @@ -312,10 +349,10 @@ This parameter is required. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -331,7 +368,7 @@ To find the list separator for a culture, use the following command: `(Get-Cultu ```yaml Type: SwitchParameter Parameter Sets: UseCulture -Aliases: +Aliases: Required: False Position: Named @@ -340,40 +377,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -LiteralPath -Specifies the path to the CSV output file. -Unlike `-Path`, the value of the `-LiteralPath` parameter is used exactly as it is typed. -No characters are interpreted as wildcards. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell PowerShell not to interpret any characters as escape sequences. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: PSPath - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -WhatIf Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -404,7 +407,8 @@ You can pipe any object with an Extended Type System (ETS) adapter to `Export-CS The CSV list is sent to the file designated in the Path parameter. ## NOTES -* The `Export-CSV` cmdlet converts the objects that you submit into a series of CSV variable-length strings and saves them in the specified text file. You can use `Export-CSV -IncludeTypeInformation` to save objects in a CSV file and then use the `Import-Csv` cmdlet to create objects from the text in the CSV file. +* The `Export-CSV` cmdlet converts the objects that you submit into a series of CSV variable-length strings and saves them in the specified text file. + You can use `Export-CSV -IncludeTypeInformation` to save objects in a CSV file and then use the `Import-Csv` cmdlet to create objects from the text in the CSV file. In the CSV file, 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. From 6976ff46ac07cc417dcd8738df9a7e224c452d83 Mon Sep 17 00:00:00 2001 From: Pete DiSalvo Date: Wed, 6 Dec 2017 09:36:35 -0600 Subject: [PATCH 087/188] Fix typo in syntax description (#1931) --- reference/5.1/Microsoft.PowerShell.Core/About/about_For.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_For.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_For.md index c8343e7483e3..5c8f723bb156 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_For.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_For.md @@ -25,7 +25,7 @@ all the values in an array, consider using a Foreach statement. The following shows the For statement syntax. ```powershell -for (>init>; ; ) +for (; ; ) {} ``` From 6712f85223a7f9763f0edd93085fa5653464302b Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Thu, 7 Dec 2017 00:45:43 +0900 Subject: [PATCH 088/188] Fix parameter's position in ConvertTo-Xml.md (#1929) --- .../ConvertTo-Xml.md | 8 ++-- .../ConvertTo-Xml.md | 8 ++-- .../ConvertTo-Xml.md | 6 +-- .../ConvertTo-Xml.md | 6 +-- .../ConvertTo-Xml.md | 47 ++----------------- 5 files changed, 18 insertions(+), 57 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md index 4fe62732be0a..5816d9b32571 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md @@ -13,9 +13,9 @@ title: ConvertTo-Xml Creates an XML-based representation of an object. ## SYNTAX -``` -ConvertTo-Xml [-Depth ] [-InputObject] [-NoTypeInformation] [-As ] - [] +```powershell +ConvertTo-Xml [-InputObject] [-Depth ] [-NoTypeInformation] + [-As ] [] ``` ## DESCRIPTION @@ -97,7 +97,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: True diff --git a/reference/4.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md b/reference/4.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md index 7f95fdce91cc..6eca43ab5af2 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md @@ -15,9 +15,9 @@ Creates an XML-based representation of an object. ## SYNTAX -``` -ConvertTo-Xml [-Depth ] [-InputObject] [-NoTypeInformation] [-As ] - [] +```powershell +ConvertTo-Xml [-InputObject] [-Depth ] [-NoTypeInformation] + [-As ] [] ``` ## DESCRIPTION @@ -102,7 +102,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: True diff --git a/reference/5.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md b/reference/5.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md index f51e7a3c3c11..b47236614682 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md @@ -15,9 +15,9 @@ Creates an XML-based representation of an object. ## SYNTAX -``` -ConvertTo-Xml [-Depth ] [-InputObject] [-NoTypeInformation] [-As ] - [] +```powershell +ConvertTo-Xml [-InputObject] [-Depth ] [-NoTypeInformation] + [-As ] [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Utility/ConvertTo-Xml.md b/reference/5.1/Microsoft.PowerShell.Utility/ConvertTo-Xml.md index 35d59e5290ec..aa71466398ef 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/ConvertTo-Xml.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/ConvertTo-Xml.md @@ -15,9 +15,9 @@ Creates an XML-based representation of an object. ## SYNTAX -``` -ConvertTo-Xml [-Depth ] [-InputObject] [-NoTypeInformation] [-As ] - [] +```powershell +ConvertTo-Xml [-InputObject] [-Depth ] [-NoTypeInformation] + [-As ] [] ``` ## DESCRIPTION diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Xml.md b/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Xml.md index 4c23cb83c792..aa71466398ef 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Xml.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Xml.md @@ -15,9 +15,9 @@ Creates an XML-based representation of an object. ## SYNTAX -``` -ConvertTo-Xml [-Depth ] [-InputObject] [-NoTypeInformation] [-As ] - [-InformationAction ] [-InformationVariable ] [] +```powershell +ConvertTo-Xml [-InputObject] [-Depth ] [-NoTypeInformation] + [-As ] [] ``` ## DESCRIPTION @@ -95,45 +95,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction --- String: Returns a single string. - --- Stream: Returns an array of strings. - --- Document: Returns an XmlDocument object. - -The default is Document.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable --- String: Returns a single string. - --- Stream: Returns an array of strings. - --- Document: Returns an XmlDocument object. - -The default is Document.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -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. @@ -145,7 +106,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False From 6686c2345de19f4a1dcc20484e24e921836a6c1f Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Thu, 7 Dec 2017 00:46:16 +0900 Subject: [PATCH 089/188] Remove descriptions about ComputerName parameter in Get-Process.md v6.0 (#1928) --- .../Get-Process.md | 79 +++---------------- 1 file changed, 10 insertions(+), 69 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Management/Get-Process.md b/reference/6/Microsoft.PowerShell.Management/Get-Process.md index 89bb191d56a4..b74e7c647d37 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-Process.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-Process.md @@ -11,48 +11,44 @@ title: Get-Process # Get-Process ## SYNOPSIS -Gets the processes that are running on the local computer or a remote computer. +Gets the processes that are running on the local computer. ## SYNTAX ### Name (Default) ``` -Get-Process [[-Name] ] [-ComputerName ] [-Module] [-FileVersionInfo] - [-InformationAction ] [-InformationVariable ] [] +Get-Process [[-Name] ] [-Module] [-FileVersionInfo] + [] ``` ### NameWithUserName ``` -Get-Process [[-Name] ] [-IncludeUserName] [-InformationAction ] - [-InformationVariable ] [] +Get-Process [[-Name] ] [-IncludeUserName] [] ``` ### Id ``` -Get-Process -Id [-ComputerName ] [-Module] [-FileVersionInfo] - [-InformationAction ] [-InformationVariable ] [] +Get-Process -Id [-Module] [-FileVersionInfo] [] ``` ### IdWithUserName ``` -Get-Process -Id [-IncludeUserName] [-InformationAction ] - [-InformationVariable ] [] +Get-Process -Id [-IncludeUserName] [] ``` ### InputObject ``` -Get-Process -InputObject [-ComputerName ] [-Module] [-FileVersionInfo] - [-InformationAction ] [-InformationVariable ] [] +Get-Process -InputObject [-Module] [-FileVersionInfo] + [] ``` ### InputObjectWithUserName ``` -Get-Process -InputObject [-IncludeUserName] [-InformationAction ] - [-InformationVariable ] [] +Get-Process -InputObject [-IncludeUserName] [] ``` ## DESCRIPTION -The **Get-Process** cmdlet gets the processes on a local or remote computer. +The **Get-Process** cmdlet gets the processes on a local computer. Without parameters, this cmdlet gets all of the processes on the local computer. You can also specify a particular process by process name or process ID (PID) or pass a process object through the pipeline to this cmdlet. @@ -201,34 +197,11 @@ To view all of the properties, pipe the results of a **Get-Process** command to ## PARAMETERS -### -ComputerName -Specifies the computers for which this cmdlet gets active processes. -The default is the local computer. - -Type the NetBIOS name, an IP address, or a fully qualified domain name (FQDN) of one or more computers. -To specify the local computer, type the computer name, a dot (.), or localhost. - -This parameter does not rely on Windows PowerShell remoting. -You can use the *ComputerName* parameter of this cmdlet even if your computer is not configured to run remote commands. - -```yaml -Type: String[] -Parameter Sets: Name, Id, InputObject -Aliases: Cn - -Required: False -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - ### -FileVersionInfo Indicates that this cmdlet gets the file version information for the program that runs in the process. On Windows Vista and later versions of Windows, you must open Windows PowerShell with the Run as administrator option to use this parameter on processes that you do not own. -You cannot use the *FileVersionInfo* and *ComputerName* parameters of the **Get-Process** cmdlet in the same command. To get file version information for a process on a remote computer, use the Invoke-Command cmdlet. Using this parameter is equivalent to getting the **MainModule.FileVersionInfo** property of each process object. @@ -279,37 +252,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -Type the NetBIOS name, an IP address, or a fully qualified domain name of one or more computers. To specify the local computer, type the computer name, a dot (.), or "localhost". - -This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Get-Process even if your computer is not configured to run remote commands.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -Type the NetBIOS name, an IP address, or a fully qualified domain name of one or more computers. To specify the local computer, type the computer name, a dot (.), or "localhost". - -This parameter does not rely on Windows PowerShell remoting. You can use the ComputerName parameter of Get-Process even if your computer is not configured to run remote commands.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -InputObject Specifies one or more process objects. Enter a variable that contains the objects, or type a command or expression that gets the objects. @@ -331,7 +273,6 @@ Indicates that this cmdlet gets the modules that have been loaded by the process On Windows Vista and later versions of Windows, you must open Windows PowerShell with the Run as administrator option to use this parameter on processes that you do not own. -You cannot use the *Module* and *ComputerName* parameters of the **Get-Process** cmdlet in the same command. To get the modules that have been loaded by a process on a remote computer, use the **Invoke-Command** cmdlet. This parameter is equivalent to getting the Modules property of each process object. From a0b25021a24aab37a778ed29fb046e35a5cb5ec1 Mon Sep 17 00:00:00 2001 From: Yuriy Samorodov Date: Wed, 6 Dec 2017 19:54:53 +0300 Subject: [PATCH 090/188] Line 192 Single Quote Breaks Example (#1930) * Line 192 Single Quote Breaks Example * clarified the example for -Regex --- .../About/about_Switch.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md index 1bfafbe78470..cf7500531b40 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2017-12-06 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -167,9 +167,9 @@ Switch has the following parameters: | |condition. Wildcard and Exact are ignored. Also, if the | | |match clause is not a string, this parameter is ignored. | +In this example, there is no matching case so there is no output. ```powershell -Example: PS> switch ("fourteen") { 1 {"It is one."; Break} @@ -179,7 +179,12 @@ Example: 3 {"Three again."; Break} "fo*" {"That's too many."} } +``` + +For the word "fourteen" to match a case you must use the **-Wildcard** or +**-Regex** parameter. +```powershell PS> switch -Regex ("fourteen") { 1 {"It is one."; Break} @@ -189,6 +194,11 @@ Example: 3 {"Three again."; Break} "fo*" {"That's too many."} } + ``` + + Result: + + ```Output That's too many. ``` From 00a26753530f2b1df8eb13c213db6ce8874408ea Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Fri, 8 Dec 2017 00:29:32 +0900 Subject: [PATCH 091/188] Update Example 2 in Get-Alias.md (ineffective Exclude) (#1935) `-Exclude Get-*` is ineffective because there are no aliases that begin with `Get-`. --- reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md | 7 ++++--- reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md | 6 +++--- reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md | 6 +++--- reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md | 6 +++--- reference/6/Microsoft.PowerShell.Utility/Get-Alias.md | 6 +++--- 5 files changed, 16 insertions(+), 15 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md index 7758497fdfb1..d5cc83616c44 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md @@ -66,11 +66,12 @@ This command gets all aliases in the current session. The output shows the "\ -\> \" format that was introduced in Windows PowerShell 3.0. This format is used only for aliases that do not include hyphens, because aliases with hyphens are typically preferred names for cmdlets and functions, rather than nicknames. ### Example 2 +```powershell +Get-Alias -Name gp*, sp* -Exclude *ps ``` -PS C:\> Get-Alias -Name g*, s* -Exclude Get-* -``` -This command gets all aliases that begin with "g" or "s", except for aliases that begin with "get-". +This command gets all aliases that begin with gp or sp, except for aliases that end with ps. + ### Example 3 ``` PS C:\> Get-Alias -Definition Get-ChildItem diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md index 614f1c824b52..32666d375c1e 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md @@ -70,11 +70,11 @@ The output shows the "\ -\> \" format that was introduced i This format is used only for aliases that do not include hyphens, because aliases with hyphens are typically preferred names for cmdlets and functions, rather than nicknames. ### Example 2 -``` -PS C:\> Get-Alias -Name g*, s* -Exclude Get-* +```powershell +Get-Alias -Name gp*, sp* -Exclude *ps ``` -This command gets all aliases that begin with "g" or "s", except for aliases that begin with "get-". +This command gets all aliases that begin with gp or sp, except for aliases that end with ps. ### Example 3 ``` diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md index baa2ea6a5e33..b98e54e4a55d 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md @@ -70,11 +70,11 @@ The output shows the \ -\> \ format that was introduced in This format is used only for aliases that do not include hyphens, because aliases with hyphens are typically preferred names for cmdlets and functions, rather than nicknames. ### Example 2: Get aliases by name -``` -PS C:\> Get-Alias -Name g*, s* -Exclude Get-* +```powershell +Get-Alias -Name gp*, sp* -Exclude *ps ``` -This command gets all aliases that begin with g or s, except for aliases that begin with Get-. +This command gets all aliases that begin with gp or sp, except for aliases that end with ps. ### Example 3: Get aliases for a cmdlet ``` diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md index 900d5cb3a0e7..dbdaf6e0741b 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md @@ -59,11 +59,11 @@ The output shows the \ -\> \ format that was introduced in This format is used only for aliases that do not include hyphens, because aliases with hyphens are typically preferred names for cmdlets and functions, rather than nicknames. ### Example 2: Get aliases by name -``` -PS C:\> Get-Alias -Name g*, s* -Exclude Get-* +```powershell +Get-Alias -Name gp*, sp* -Exclude *ps ``` -This command gets all aliases that begin with g or s, except for aliases that begin with Get-. +This command gets all aliases that begin with gp or sp, except for aliases that end with ps. ### Example 3: Get aliases for a cmdlet ``` diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md index abff6fe42c9d..7747dc402bdc 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md @@ -61,11 +61,11 @@ The output shows the \ -\> \ format that was introduced in This format is used only for aliases that do not include hyphens, because aliases with hyphens are typically preferred names for cmdlets and functions, rather than nicknames. ### Example 2: Get aliases by name -``` -PS C:\> Get-Alias -Name g*, s* -Exclude Get-* +```powershell +Get-Alias -Name gp*, sp* -Exclude *ps ``` -This command gets all aliases that begin with g or s, except for aliases that begin with Get-. +This command gets all aliases that begin with gp or sp, except for aliases that end with ps. ### Example 3: Get aliases for a cmdlet ``` From 010d9e508f8586245534713d50bdf7306411e9c3 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Fri, 8 Dec 2017 00:30:37 +0900 Subject: [PATCH 092/188] Fix formatting: DESCRIPTION section in ConvertTo-Xml.md (#1934) --- .../3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md | 11 ++++++----- .../4.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md | 10 +++++----- .../5.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md | 10 +++++----- .../5.1/Microsoft.PowerShell.Utility/ConvertTo-Xml.md | 10 +++++----- .../6/Microsoft.PowerShell.Utility/ConvertTo-Xml.md | 10 +++++----- 5 files changed, 26 insertions(+), 25 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md index 5816d9b32571..9c5fdbd01416 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md @@ -19,13 +19,14 @@ ConvertTo-Xml [-InputObject] [-Depth ] [-NoTypeInformation] ``` ## 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. +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. -When you pipe multiple objects to ConvertTo-XML or use the InputObject parameter to submit multiple objects, ConvertTo-XML returns a single XML document that includes representations of all of the objects. +When you pipe multiple objects to `ConvertTo-Xml` or use the **InputObject** parameter to submit multiple objects, `ConvertTo-Xml` returns a single XML document that includes representations of all of the objects. + +This cmdlet is similar to `Export-Clixml` except that `Export-Clixml` stores the resulting XML in a file. +`ConvertTo-Xml` returns the XML, so you can continue to process it in PowerShell. -This cmdlet is similar to Export-Clixml except that Export-Clixml stores the resulting XML in a file. -ConvertTo-XML returns the XML, so you can continue to process it in Windows PowerShell. ## EXAMPLES ### Example 1 diff --git a/reference/4.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md b/reference/4.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md index 6eca43ab5af2..7264fe0a4fcb 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md @@ -21,13 +21,13 @@ ConvertTo-Xml [-InputObject] [-Depth ] [-NoTypeInformation] ``` ## 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. +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. -When you pipe multiple objects to ConvertTo-XML or use the InputObject parameter to submit multiple objects, ConvertTo-XML returns a single XML document that includes representations of all of the objects. +When you pipe multiple objects to `ConvertTo-Xml` or use the **InputObject** parameter to submit multiple objects, `ConvertTo-Xml` returns a single XML document that includes representations of all of the objects. -This cmdlet is similar to Export-Clixml except that Export-Clixml stores the resulting XML in a file. -ConvertTo-XML returns the XML, so you can continue to process it in Windows PowerShell. +This cmdlet is similar to `Export-Clixml` except that `Export-Clixml` stores the resulting XML in a file. +`ConvertTo-Xml` returns the XML, so you can continue to process it in PowerShell. ## EXAMPLES diff --git a/reference/5.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md b/reference/5.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md index b47236614682..d50c8bc36cc8 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/ConvertTo-Xml.md @@ -21,13 +21,13 @@ ConvertTo-Xml [-InputObject] [-Depth ] [-NoTypeInformation] ``` ## 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. +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. -When you pipe multiple objects to **ConvertTo-XML** or use the *InputObject* parameter to submit multiple objects, **ConvertTo-XML** returns a single XML document that includes representations of all of the objects. +When you pipe multiple objects to `ConvertTo-Xml` or use the **InputObject** parameter to submit multiple objects, `ConvertTo-Xml` returns a single XML document that includes representations of all of the objects. -This cmdlet is similar to Export-Clixml except that **Export-Clixml** stores the resulting XML in a file**. -ConvertTo-XML** returns the XML, so you can continue to process it in Windows PowerShell. +This cmdlet is similar to `Export-Clixml` except that `Export-Clixml` stores the resulting XML in a file. +`ConvertTo-Xml` returns the XML, so you can continue to process it in PowerShell. ## EXAMPLES diff --git a/reference/5.1/Microsoft.PowerShell.Utility/ConvertTo-Xml.md b/reference/5.1/Microsoft.PowerShell.Utility/ConvertTo-Xml.md index aa71466398ef..0ca7799ae25c 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/ConvertTo-Xml.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/ConvertTo-Xml.md @@ -21,13 +21,13 @@ ConvertTo-Xml [-InputObject] [-Depth ] [-NoTypeInformation] ``` ## 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. +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. -When you pipe multiple objects to **ConvertTo-XML** or use the *InputObject* parameter to submit multiple objects, **ConvertTo-XML** returns a single XML document that includes representations of all of the objects. +When you pipe multiple objects to `ConvertTo-Xml` or use the **InputObject** parameter to submit multiple objects, `ConvertTo-Xml` returns a single XML document that includes representations of all of the objects. -This cmdlet is similar to Export-Clixml except that **Export-Clixml** stores the resulting XML in a file**. -ConvertTo-XML** returns the XML, so you can continue to process it in Windows PowerShell. +This cmdlet is similar to `Export-Clixml` except that `Export-Clixml` stores the resulting XML in a file. +`ConvertTo-Xml` returns the XML, so you can continue to process it in PowerShell. ## EXAMPLES diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Xml.md b/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Xml.md index aa71466398ef..0ca7799ae25c 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Xml.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Xml.md @@ -21,13 +21,13 @@ ConvertTo-Xml [-InputObject] [-Depth ] [-NoTypeInformation] ``` ## 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. +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. -When you pipe multiple objects to **ConvertTo-XML** or use the *InputObject* parameter to submit multiple objects, **ConvertTo-XML** returns a single XML document that includes representations of all of the objects. +When you pipe multiple objects to `ConvertTo-Xml` or use the **InputObject** parameter to submit multiple objects, `ConvertTo-Xml` returns a single XML document that includes representations of all of the objects. -This cmdlet is similar to Export-Clixml except that **Export-Clixml** stores the resulting XML in a file**. -ConvertTo-XML** returns the XML, so you can continue to process it in Windows PowerShell. +This cmdlet is similar to `Export-Clixml` except that `Export-Clixml` stores the resulting XML in a file. +`ConvertTo-Xml` returns the XML, so you can continue to process it in PowerShell. ## EXAMPLES From 89de81359c5545f7ae3f30478781a9bb605bddd3 Mon Sep 17 00:00:00 2001 From: Wemyss Date: Fri, 8 Dec 2017 02:31:57 +1100 Subject: [PATCH 093/188] Fix typo in Unregister-ScheduledJob (#1932) * Update Unregister-ScheduledJob.md * Update Unregister-ScheduledJob.md * Update Unregister-ScheduledJob.md * Update Unregister-ScheduledJob.md --- reference/3.0/PSScheduledJob/Unregister-ScheduledJob.md | 2 +- reference/4.0/PSScheduledJob/Unregister-ScheduledJob.md | 2 +- reference/5.0/PSScheduledJob/Unregister-ScheduledJob.md | 2 +- reference/5.1/PSScheduledJob/Unregister-ScheduledJob.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/reference/3.0/PSScheduledJob/Unregister-ScheduledJob.md b/reference/3.0/PSScheduledJob/Unregister-ScheduledJob.md index 016ef1ae0e8b..4d15ed82f883 100644 --- a/reference/3.0/PSScheduledJob/Unregister-ScheduledJob.md +++ b/reference/3.0/PSScheduledJob/Unregister-ScheduledJob.md @@ -59,7 +59,7 @@ This command deletes the TestJob scheduled job on the local computer. PS C:\> Get-ScheduledJob | Unregister-ScheduledJob -Force -PS C:\> Unregistered-ScheduledJob -Name * -Force +PS C:\> Unregister-ScheduledJob -Name * -Force ``` This examples shows two different commands that delete all scheduled jobs on the local computer. diff --git a/reference/4.0/PSScheduledJob/Unregister-ScheduledJob.md b/reference/4.0/PSScheduledJob/Unregister-ScheduledJob.md index 56a1d064a7fb..03152e950ccf 100644 --- a/reference/4.0/PSScheduledJob/Unregister-ScheduledJob.md +++ b/reference/4.0/PSScheduledJob/Unregister-ScheduledJob.md @@ -63,7 +63,7 @@ This command deletes the TestJob scheduled job on the local computer. PS C:\> Get-ScheduledJob | Unregister-ScheduledJob -Force -PS C:\> Unregistered-ScheduledJob -Name * -Force +PS C:\> Unregister-ScheduledJob -Name * -Force ``` This examples shows two different commands that delete all scheduled jobs on the local computer. diff --git a/reference/5.0/PSScheduledJob/Unregister-ScheduledJob.md b/reference/5.0/PSScheduledJob/Unregister-ScheduledJob.md index 59d72e80aaab..21db69497205 100644 --- a/reference/5.0/PSScheduledJob/Unregister-ScheduledJob.md +++ b/reference/5.0/PSScheduledJob/Unregister-ScheduledJob.md @@ -61,7 +61,7 @@ This command deletes the TestJob scheduled job on the local computer. ### Example 2: Delete all scheduled jobs ``` PS C:\> Get-ScheduledJob | Unregister-ScheduledJob -Force -PS C:\> Unregistered-ScheduledJob -Name "*" -Force +PS C:\> Unregister-ScheduledJob -Name "*" -Force ``` This example shows two different commands that delete all scheduled jobs on the local computer. diff --git a/reference/5.1/PSScheduledJob/Unregister-ScheduledJob.md b/reference/5.1/PSScheduledJob/Unregister-ScheduledJob.md index 387329625fa2..3a53902864d6 100644 --- a/reference/5.1/PSScheduledJob/Unregister-ScheduledJob.md +++ b/reference/5.1/PSScheduledJob/Unregister-ScheduledJob.md @@ -61,7 +61,7 @@ This command deletes the TestJob scheduled job on the local computer. ### Example 2: Delete all scheduled jobs ``` PS C:\> Get-ScheduledJob | Unregister-ScheduledJob -Force -PS C:\> Unregistered-ScheduledJob -Name "*" -Force +PS C:\> Unregister-ScheduledJob -Name "*" -Force ``` This example shows two different commands that delete all scheduled jobs on the local computer. From 59ff97e0f5981e9413464e47edc35e8227a51ca4 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Sat, 9 Dec 2017 02:35:51 +0900 Subject: [PATCH 094/188] Fix parameter's position in ConvertFrom-Csv.md (#1937) --- .../ConvertFrom-Csv.md | 14 +++--- .../ConvertFrom-Csv.md | 14 +++--- .../ConvertFrom-Csv.md | 10 +++-- .../ConvertFrom-Csv.md | 10 +++-- .../ConvertFrom-Csv.md | 43 ++++--------------- 5 files changed, 36 insertions(+), 55 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md index 1a219adb9539..94b116ae16a3 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md @@ -14,13 +14,15 @@ Converts object properties in comma-separated value (CSV) format into CSV versio ## SYNTAX ### Delimiter (Default) -``` -ConvertFrom-Csv [[-Delimiter] ] [-InputObject] [-Header ] [] +```powershell +ConvertFrom-Csv [-InputObject] [[-Delimiter] ] + [-Header ] [] ``` ### UseCulture -``` -ConvertFrom-Csv [-UseCulture] [-InputObject] [-Header ] [] +```powershell +ConvertFrom-Csv [-InputObject] -UseCulture + [-Header ] [] ``` ## DESCRIPTION @@ -136,7 +138,7 @@ Parameter Sets: Delimiter Aliases: Required: False -Position: 2 +Position: 1 Default value: "," (comma) Accept pipeline input: False Accept wildcard characters: False @@ -178,7 +180,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md b/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md index 6b5806726c56..d9e96d8d198c 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md @@ -16,13 +16,15 @@ Converts object properties in comma-separated value (CSV) format into CSV versio ## SYNTAX ### Delimiter (Default) -``` -ConvertFrom-Csv [[-Delimiter] ] [-InputObject] [-Header ] [] +```powershell +ConvertFrom-Csv [-InputObject] [[-Delimiter] ] + [-Header ] [] ``` ### UseCulture -``` -ConvertFrom-Csv [-UseCulture] [-InputObject] [-Header ] [] +```powershell +ConvertFrom-Csv [-InputObject] -UseCulture + [-Header ] [] ``` ## DESCRIPTION @@ -143,7 +145,7 @@ Parameter Sets: Delimiter Aliases: Required: False -Position: 2 +Position: 1 Default value: "," (comma) Accept pipeline input: False Accept wildcard characters: False @@ -185,7 +187,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md b/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md index e4100ace0887..d1b32e448c41 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md @@ -16,13 +16,15 @@ Converts object properties in comma-separated value (CSV) format into CSV versio ## SYNTAX ### Delimiter (Default) -``` -ConvertFrom-Csv [[-Delimiter] ] [-InputObject] [-Header ] [] +```powershell +ConvertFrom-Csv [-InputObject] [[-Delimiter] ] + [-Header ] [] ``` ### UseCulture -``` -ConvertFrom-Csv [-UseCulture] [-InputObject] [-Header ] [] +```powershell +ConvertFrom-Csv [-InputObject] -UseCulture + [-Header ] [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md b/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md index 2b203caae1e3..5be5d45052e9 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md @@ -16,13 +16,15 @@ Converts object properties in comma-separated value (CSV) format into CSV versio ## SYNTAX ### Delimiter (Default) -``` -ConvertFrom-Csv [[-Delimiter] ] [-InputObject] [-Header ] [] +```powershell +ConvertFrom-Csv [-InputObject] [[-Delimiter] ] + [-Header ] [] ``` ### UseCulture -``` -ConvertFrom-Csv [-UseCulture] [-InputObject] [-Header ] [] +```powershell +ConvertFrom-Csv [-InputObject] -UseCulture + [-Header ] [] ``` ## DESCRIPTION diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md index 53c663e892be..5be5d45052e9 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Csv.md @@ -16,15 +16,15 @@ Converts object properties in comma-separated value (CSV) format into CSV versio ## SYNTAX ### Delimiter (Default) -``` -ConvertFrom-Csv [[-Delimiter] ] [-InputObject] [-Header ] - [-InformationAction ] [-InformationVariable ] [] +```powershell +ConvertFrom-Csv [-InputObject] [[-Delimiter] ] + [-Header ] [] ``` ### UseCulture -``` -ConvertFrom-Csv [-UseCulture] [-InputObject] [-Header ] - [-InformationAction ] [-InformationVariable ] [] +```powershell +ConvertFrom-Csv [-InputObject] -UseCulture + [-Header ] [] ``` ## DESCRIPTION @@ -144,7 +144,7 @@ Parameter Sets: Delimiter Aliases: Required: False -Position: 2 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -175,33 +175,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -If you specify a character other than the delimiter used in the CSV strings, ConvertFrom-CSV cannot create objects from the CSV strings. Instead, it returns the strings.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -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. @@ -213,7 +186,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False From d4289869a3b0b460110cce09f9810cd315b04889 Mon Sep 17 00:00:00 2001 From: DaniSQL Date: Fri, 8 Dec 2017 12:36:54 -0500 Subject: [PATCH 095/188] fix typo on metaConfig.md (#1936) fixed typo --- dsc/metaConfig.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dsc/metaConfig.md b/dsc/metaConfig.md index 561b7a423003..6992810d6307 100644 --- a/dsc/metaConfig.md +++ b/dsc/metaConfig.md @@ -77,7 +77,7 @@ The following properties are available in a **Settings** block. | Property | Type | Description | |----------- |------- |--------------- | -| ActionAfterReboot| string| Specifies what happens after a reboot during the application of a configuration. The possible values are __"ContinueConfiguration"__ and __"StopConfiguration"__.
  • __ContinueConfiguration__: Continue applying the current configuration after machine reboot. This is the default falue
  • __StopConfiguration__: Stop the current configuration after machine reboot.
| +| ActionAfterReboot| string| Specifies what happens after a reboot during the application of a configuration. The possible values are __"ContinueConfiguration"__ and __"StopConfiguration"__.
  • __ContinueConfiguration__: Continue applying the current configuration after machine reboot. This is the default value
  • __StopConfiguration__: Stop the current configuration after machine reboot.
| | AllowModuleOverwrite| bool| __$TRUE__ if new configurations downloaded from the pull service are allowed to overwrite the old ones on the target node. Otherwise, $FALSE.| | CertificateID| string| The thumbprint of a certificate used to secure credentials passed in a configuration. For more information see [Want to secure credentials in Windows PowerShell Desired State Configuration](http://blogs.msdn.com/b/powershell/archive/2014/01/31/want-to-secure-credentials-in-windows-powershell-desired-state-configuration.aspx)?.
__Note:__ this is managed automatically if using Azure Automation DSC pull service.| | ConfigurationDownloadManagers| CimInstance[]| Obsolete. Use __ConfigurationRepositoryWeb__ and __ConfigurationRepositoryShare__ blocks to define configuration pull service endpoints.| From c070f79bb40f42564cf7f80a6859491015e73ec6 Mon Sep 17 00:00:00 2001 From: "J. Keith Bankston [MSFT]" Date: Fri, 8 Dec 2017 12:39:51 -0800 Subject: [PATCH 096/188] Quick edits (#1938) * Changed required PSGet version to 1.6.0 * Fixes to PSGet TOC and WMF 5.1 compat page --- gallery/TOC.md | 3 ++- wmf/5.1/productincompat.md | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/gallery/TOC.md b/gallery/TOC.md index dadea276e34c..27e3168f84e9 100644 --- a/gallery/TOC.md +++ b/gallery/TOC.md @@ -39,6 +39,7 @@ ### [Publish](psget/module/psget_publish-module.md) ### [Modules with PSEditions](psget/module/modulewithpseditionsupport.md) ### [Modules Requiring License Acceptance](psget/module/RequireLicenseAcceptance.md) +### [Prerelease Versions](psget/module/PreReleaseModule.md) ### [Troubleshooting](psget/psget_cmdlets_troubleshooting.md) ## Script @@ -54,7 +55,7 @@ ### [Publish](psget/script/psget_publish-script.md) ### [Scripts with PSEditions](psget/script/scriptwithpseditionsupport.md) ### [Require License Acceptance for Scripts](psget/script/script_RequireLicenseAcceptance.md) - +### [Prerelease Versions](psget/script/PreReleaseScript.md) ## Repository management ### [Bootstrapping NuGet provider and NuGet.exe](psget/repository/bootstrapping_nuget_proivder_and_exe.md) ### [Registering repository](psget/repository/psget_register-psrepository.md) diff --git a/wmf/5.1/productincompat.md b/wmf/5.1/productincompat.md index c5aa832dca9a..fd1154a578ae 100644 --- a/wmf/5.1/productincompat.md +++ b/wmf/5.1/productincompat.md @@ -11,10 +11,12 @@ keywords: wmf,powershell,setup > Systems that are running the following server applications **can run** Windows Management Framework 5.1: - Microsoft SharePoint Server 2013 -- Skype for Business Server 2015 +- Skype for Business Server 2015 (_See Note_) - Microsoft Lync Server 2013 - System Center 2012 Configuration Manager +_Note: Skype for Business Server 2015 compatibility with WMF 5.1 has been tested only with Windows Server 2012 R2._ + ## Not Tested: > Systems that are running the following server applications **have not tested** against Windows Management Framework 5.1: From 5119bdaf6f02a588623a4272b697ade221c134e4 Mon Sep 17 00:00:00 2001 From: skycommand Date: Mon, 11 Dec 2017 19:45:46 +0330 Subject: [PATCH 097/188] Update Get-Item.md (#1942) Proof-read some of the examples. The first two were wrong entirely: The user must be in the ps-test folder for the result shown to happen. --- .../Get-Item.md | 136 ++++++++++++++---- 1 file changed, 108 insertions(+), 28 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Get-Item.md b/reference/5.1/Microsoft.PowerShell.Management/Get-Item.md index a3c15c3316aa..28e1eed37e7f 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Get-Item.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Get-Item.md @@ -16,13 +16,13 @@ Gets the item at the specified location. ## SYNTAX ### Path (Default) -``` +```powershell Get-Item [-Path] [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-UseTransaction] [-Stream ] [] ``` ### LiteralPath -``` +```powershell Get-Item -LiteralPath [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] [-UseTransaction] [-Stream ] [] ``` @@ -37,16 +37,14 @@ This cmdlet is used by Windows PowerShell providers to navigate through differen ### Example 1: Get the current directory ``` -PS C:\> Get-Item . - +PS C:\ps-test> Get-Item . + Directory: C:\ - -Directory: C:\ Mode LastWriteTime Length Name ---- ------------- ------ ---- -d---- 7/26/2006 10:01 AM ps-test +d----- 7/26/2006 10:01 AM ps-test ``` This command gets the current directory. @@ -54,27 +52,19 @@ The dot (.) represents the item at the current location (not its contents). ### Example 2: Get all the items in the current directory ``` -PS C:\> Get-Item * - - - - - - - - +PS C:\ps-test> Get-Item * + Directory: C:\ps-test -Directory: C:\ps-test Mode LastWriteTime Length Name ---- ------------- ------ ---- -d---- 7/26/2006 9:29 AM Logs -d---- 7/26/2006 9:26 AM Recs --a--- 7/26/2006 9:28 AM 80 date.csv --a--- 7/26/2006 10:01 AM 30 filenoext --a--- 7/26/2006 9:30 AM 11472 process.doc --a--- 7/14/2006 10:47 AM 30 test.txt +d----- 7/26/2006 9:29 AM Logs +d----- 7/26/2006 9:26 AM Recs +-a---- 7/26/2006 9:28 AM 80 date.csv +-a---- 7/26/2006 10:01 AM 30 filenoext +-a---- 7/26/2006 9:30 AM 11472 process.doc +-a---- 7/14/2006 10:47 AM 30 test.txt ``` This command gets all the items in the current directory. @@ -82,15 +72,35 @@ The wildcard character (*) represents all the contents of the current item. ### Example 3: Get the current directory of a drive ``` -PS C:\> Get-Item C:\ +PS C:\ps-test> Get-Item C:\ + + + Directory: + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +d--hs- 12/10/2017 1:16 PM C:\ ``` This command gets the current directory of the C: drive. The object that is retrieved represents only the directory, not its contents. -### Example 4: Get items in the specified drive +### Example 4: Get items in the specified drive root ``` -PS C:\> Get-Item C:\* +PS C:\ps-test> Get-Item C:\* + + + Directory: C:\ + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +d----- 3/19/2017 12:33 AM PerfLogs +d-r--- 11/29/2017 2:36 PM Program Files +d-r--- 11/29/2017 2:14 PM Program Files (x86) +d-r--- 7/16/2017 4:03 PM Users +d----- 12/10/2017 1:16 PM Windows ``` This command gets the items in the C: drive. @@ -102,6 +112,8 @@ The format is interpreted literally, so *.* would not retrieve directories or fi ### Example 5: Get a property in the specified directory ``` PS C:\> (Get-Item C:\Windows).LastAccessTime + +Sunday, December 10, 2017 1:16:45 PM ``` This command gets the LastAccessTime property of the C:\Windows directory. @@ -110,15 +122,83 @@ To see all of the properties of a directory, type `(Get-Item \) ### Example 6: Show the contents of a registry key ``` -PS C:\> Get-Item hklm:\software\microsoft\powershell\1\shellids\microsoft.powershell\* +PS C:\Windows> Get-Item "hklm:\Software\Microsoft\Windows NT\*" + + + Hive: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT + + +Name Property +---- -------- +CurrentVersion SystemRoot : C:\WINDOWS + BuildBranch : rs2_release + BuildGUID : ffffffff-ffff-ffff-ffff-ffffffffffff + BuildLab : 15063.rs2_release.170317-1834 + BuildLabEx : 15063.0.amd64fre.rs2_release.170317-1834 + CompositionEditionID : Enterprise + CurrentBuild : 15063 + CurrentBuildNumber : 15063 + CurrentMajorVersionNumber : 10 + CurrentMinorVersionNumber : 0 + CurrentType : Multiprocessor Free + CurrentVersion : 6.3 + EditionID : Enterprise + EditionSubstring : + InstallationType : Client + InstallDate : 1495262485 + ProductName : Windows 10 Enterprise + ReleaseId : 1703 + SoftwareType : System + UBR : 726 + PathName : C:\WINDOWS + DigitalProductId : {164, 0, 0, 0...} + DigitalProductId4 : {248, 4, 0, 0...} + ProductId : 00329-00000-00003-AA840 + RegisteredOrganization : + RegisteredOwner : + InstallTime : 131397360853701614 ``` -This command shows the contents of the Microsoft.PowerShell registry key. +This command shows the contents of the "Windows NT" registry key. You can use this cmdlet with the Windows PowerShell Registry provider to get registry keys and subkeys, but you must use the **Get-ItemProperty** cmdlet to get the registry values and data. ### Example 7: Get items in a directory that have an exclusion ``` PS C:\> Get-Item c:\Windows\*.* -exclude "w*" + + + Directory: C:\Windows + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +d-r--- 12/11/2017 10:25 AM Microsoft.NET +d----- 4/5/2017 4:34 PM SoftwareDistribution.bak +-a---- 5/20/2017 10:54 AM 0 ativpsrm.bin +-a---- 8/25/2008 10:31 PM 292352 atprs.exe +-a---- 6/3/2017 1:21 PM 64512 bfsvc.exe +-a--s- 12/11/2017 1:10 PM 67584 bootstat.dat +-a---- 10/30/2015 10:48 AM 31816 CoreSingleLanguage.xml +-a---- 10/8/2016 9:45 PM 232960 DfsrAdmin.exe +-a---- 5/22/2017 10:24 AM 1315 DfsrAdmin.exe.config +-a---- 12/10/2017 1:21 PM 1908 diagerr.xml +-a---- 12/10/2017 1:21 PM 1908 diagwrn.xml +-a---- 3/19/2017 12:29 AM 34774 Enterprise.xml +-a---- 10/7/2015 2:11 AM 2238152 ETDUninst.dll +-a---- 9/30/2017 9:12 AM 4848952 explorer.exe +-a---- 6/3/2017 1:29 PM 975360 HelpPane.exe +-a---- 3/19/2017 12:27 AM 18432 hh.exe +-a---- 12/14/2016 10:57 AM 0 HPMProp.INI +-a---- 3/19/2017 12:27 AM 43131 mib.bin +-a---- 4/9/2008 6:00 PM 53478 mvtcpui.ini +-a---- 3/19/2017 12:28 AM 246784 notepad.exe +-a---- 11/29/2017 4:23 PM 686 PFRO.log +-a---- 3/19/2017 12:27 AM 321024 regedit.exe +-a---- 12/10/2017 1:21 PM 445 setupact.log +-a---- 12/10/2017 1:16 PM 0 setuperr.log +-a---- 3/19/2017 12:28 AM 130560 splwow64.exe +-a---- 10/30/2015 10:51 AM 219 system.ini +-a---- 3/19/2017 12:28 AM 65536 twain_32.dll ``` This command gets items in the Windows directory with names that include a dot (.), but do not begin with w*. From 54a3de477dc100f31756957aff37986d18ccc0f4 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Tue, 12 Dec 2017 01:17:43 +0900 Subject: [PATCH 098/188] Add description about Format-Hex -InputObject (#1939) --- reference/5.0/Microsoft.PowerShell.Utility/Format-Hex.md | 3 ++- reference/5.1/Microsoft.PowerShell.Utility/Format-Hex.md | 3 ++- reference/6/Microsoft.PowerShell.Utility/Format-Hex.md | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Format-Hex.md b/reference/5.0/Microsoft.PowerShell.Utility/Format-Hex.md index 01584c491eb8..f65cde9915c1 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Format-Hex.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Format-Hex.md @@ -92,7 +92,8 @@ Accept wildcard characters: False ``` ### -InputObject -Specifies the objects to be formatted. Enter a variable that contains the objects or type a command or expression that gets the objects. +Specifies the objects to be formatted. +Enter a variable that contains the objects or type a command or expression that gets the objects. ```yaml Type: Object diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Format-Hex.md b/reference/5.1/Microsoft.PowerShell.Utility/Format-Hex.md index 125545cb9096..191040e1ad45 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Format-Hex.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Format-Hex.md @@ -92,7 +92,8 @@ Accept wildcard characters: False ``` ### -InputObject -{{Fill InputObject Description}} +Specifies the objects to be formatted. +Enter a variable that contains the objects or type a command or expression that gets the objects. ```yaml Type: Object diff --git a/reference/6/Microsoft.PowerShell.Utility/Format-Hex.md b/reference/6/Microsoft.PowerShell.Utility/Format-Hex.md index 125545cb9096..191040e1ad45 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Format-Hex.md +++ b/reference/6/Microsoft.PowerShell.Utility/Format-Hex.md @@ -92,7 +92,8 @@ Accept wildcard characters: False ``` ### -InputObject -{{Fill InputObject Description}} +Specifies the objects to be formatted. +Enter a variable that contains the objects or type a command or expression that gets the objects. ```yaml Type: Object From 4e663d65bb8d60d7129fdd944ca999a14fef4c4d Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Wed, 13 Dec 2017 00:45:53 +0900 Subject: [PATCH 099/188] Fix parameter's position in Add-Member.md (#1946) --- .../Add-Member.md | 45 ++++++------ .../Add-Member.md | 69 ++++++++++--------- .../Add-Member.md | 27 +++++--- .../Add-Member.md | 27 +++++--- .../Add-Member.md | 68 ++++++------------ 5 files changed, 115 insertions(+), 121 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md b/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md index 0ac7eec0ffc1..6546d97278e6 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Add-Member.md @@ -14,26 +14,31 @@ Adds custom properties and methods to an instance of a Windows PowerShell object ## SYNTAX ### TypeNameSet (Default) -``` -Add-Member -InputObject -TypeName [-PassThru] [] +```powershell +Add-Member -InputObject -TypeName [-PassThru] + [] ``` -### NotePropertyMultiMemberSet -``` -Add-Member -InputObject [-TypeName ] [-Force] [-PassThru] - [-NotePropertyMembers] [] +### MemberSet +```powershell +Add-Member [-MemberType] [-Name] + [[-Value] ] [[-SecondValue] ] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` ### NotePropertySingleMemberSet -``` -Add-Member -InputObject [-TypeName ] [-Force] [-PassThru] [-NotePropertyName] - [-NotePropertyValue] [] +```powershell +Add-Member [-NotePropertyName] [-NotePropertyValue] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` -### MemberSet -``` -Add-Member -InputObject [-MemberType] [-Name] [[-Value] ] - [[-SecondValue] ] [-TypeName ] [-Force] [-PassThru] [] +### NotePropertyMultiMemberSet +```powershell +Add-Member [-NotePropertyMembers] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` ## DESCRIPTION @@ -281,7 +286,7 @@ Parameter Sets: MemberSet Aliases: Type Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: True @@ -296,7 +301,7 @@ Parameter Sets: MemberSet Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -341,7 +346,7 @@ Parameter Sets: MemberSet Aliases: Required: False -Position: 4 +Position: 3 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -357,7 +362,7 @@ Parameter Sets: MemberSet Aliases: Required: False -Position: 3 +Position: 2 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -377,7 +382,7 @@ Parameter Sets: NotePropertyMultiMemberSet Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -397,7 +402,7 @@ Parameter Sets: NotePropertySingleMemberSet Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -417,7 +422,7 @@ Parameter Sets: NotePropertySingleMemberSet Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md b/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md index f684ead84333..66f4ef5e109e 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Add-Member.md @@ -15,27 +15,32 @@ Adds custom properties and methods to an instance of a Windows PowerShell object ## SYNTAX -### UNNAMED_PARAMETER_SET_1 -``` -Add-Member [-PassThru] -InputObject -TypeName +### TypeNameSet (Default) +```powershell +Add-Member -InputObject -TypeName [-PassThru] + [] ``` -### UNNAMED_PARAMETER_SET_2 -``` -Add-Member [-NotePropertyName] [-NotePropertyValue] [-Force] [-PassThru] [-TypeName ] - -InputObject +### MemberSet +```powershell +Add-Member [-MemberType] [-Name] + [[-Value] ] [[-SecondValue] ] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` -### UNNAMED_PARAMETER_SET_3 -``` -Add-Member [-NotePropertyMembers] [-Force] [-PassThru] [-TypeName ] - -InputObject +### NotePropertySingleMemberSet +```powershell +Add-Member [-NotePropertyName] [-NotePropertyValue] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` -### UNNAMED_PARAMETER_SET_4 -``` -Add-Member [-MemberType] [-Name] [[-Value] ] [[-SecondValue] ] - [-Force] [-PassThru] [-TypeName ] -InputObject +### NotePropertyMultiMemberSet +```powershell +Add-Member [-NotePropertyMembers] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` ## DESCRIPTION @@ -245,7 +250,7 @@ You cannot use **the** Force parameter to replace a standard member of a type. ```yaml Type: SwitchParameter -Parameter Sets: UNNAMED_PARAMETER_SET_2, UNNAMED_PARAMETER_SET_3, UNNAMED_PARAMETER_SET_4 +Parameter Sets: MemberSet, NotePropertySingleMemberSet, NotePropertyMultiMemberSet Aliases: Required: False @@ -284,11 +289,11 @@ If you specify a member type that the object does not have, Windows PowerShell r ```yaml Type: PSMemberTypes -Parameter Sets: UNNAMED_PARAMETER_SET_4 +Parameter Sets: MemberSet Aliases: Type Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -299,11 +304,11 @@ Specifies the name of the member to be added. ```yaml Type: String -Parameter Sets: UNNAMED_PARAMETER_SET_4 +Parameter Sets: MemberSet Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -344,11 +349,11 @@ The second ScriptBlock, specified in the SecondValue parameter, is used to set t ```yaml Type: Object -Parameter Sets: UNNAMED_PARAMETER_SET_4 +Parameter Sets: MemberSet Aliases: Required: False -Position: 4 +Position: 3 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -360,11 +365,11 @@ If you add an **AliasProperty**, **CodeProperty**, **ScriptProperty** or **CodeM ```yaml Type: Object -Parameter Sets: UNNAMED_PARAMETER_SET_4 +Parameter Sets: MemberSet Aliases: Required: False -Position: 3 +Position: 2 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -380,11 +385,11 @@ This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: IDictionary -Parameter Sets: UNNAMED_PARAMETER_SET_3 +Parameter Sets: NotePropertyMultiMemberSet Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -400,11 +405,11 @@ This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: String -Parameter Sets: UNNAMED_PARAMETER_SET_2 +Parameter Sets: NotePropertySingleMemberSet Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -420,11 +425,11 @@ This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: Object -Parameter Sets: UNNAMED_PARAMETER_SET_2 +Parameter Sets: NotePropertySingleMemberSet Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -441,7 +446,7 @@ This parameter is introduced in Windows PowerShell 3.0. ```yaml Type: String -Parameter Sets: UNNAMED_PARAMETER_SET_1 +Parameter Sets: TypeNameSet Aliases: Required: True @@ -453,7 +458,7 @@ Accept wildcard characters: False ```yaml Type: String -Parameter Sets: UNNAMED_PARAMETER_SET_2, UNNAMED_PARAMETER_SET_3, UNNAMED_PARAMETER_SET_4 +Parameter Sets: MemberSet, NotePropertySingleMemberSet, NotePropertyMultiMemberSet Aliases: Required: False diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md b/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md index c5cfe0e04e70..ac32f312e12f 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Add-Member.md @@ -16,26 +16,31 @@ Adds custom properties and methods to an instance of a Windows PowerShell object ## SYNTAX ### TypeNameSet (Default) -``` -Add-Member -InputObject -TypeName [-PassThru] [] +```powershell +Add-Member -InputObject -TypeName [-PassThru] + [] ``` ### MemberSet -``` -Add-Member -InputObject [-MemberType] [-Name] [[-Value] ] - [[-SecondValue] ] [-TypeName ] [-Force] [-PassThru] [] +```powershell +Add-Member [-MemberType] [-Name] + [[-Value] ] [[-SecondValue] ] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` ### NotePropertySingleMemberSet -``` -Add-Member -InputObject [-TypeName ] [-Force] [-PassThru] [-NotePropertyName] - [-NotePropertyValue] [] +```powershell +Add-Member [-NotePropertyName] [-NotePropertyValue] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` ### NotePropertyMultiMemberSet -``` -Add-Member -InputObject [-TypeName ] [-Force] [-PassThru] - [-NotePropertyMembers] [] +```powershell +Add-Member [-NotePropertyMembers] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md b/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md index 0c54c380010e..a799760f2a88 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Add-Member.md @@ -16,26 +16,31 @@ Adds custom properties and methods to an instance of a Windows PowerShell object ## SYNTAX ### TypeNameSet (Default) -``` -Add-Member -InputObject -TypeName [-PassThru] [] +```powershell +Add-Member -InputObject -TypeName [-PassThru] + [] ``` ### MemberSet -``` -Add-Member -InputObject [-MemberType] [-Name] [[-Value] ] - [[-SecondValue] ] [-TypeName ] [-Force] [-PassThru] [] +```powershell +Add-Member [-MemberType] [-Name] + [[-Value] ] [[-SecondValue] ] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` ### NotePropertySingleMemberSet -``` -Add-Member -InputObject [-TypeName ] [-Force] [-PassThru] [-NotePropertyName] - [-NotePropertyValue] [] +```powershell +Add-Member [-NotePropertyName] [-NotePropertyValue] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` ### NotePropertyMultiMemberSet -``` -Add-Member -InputObject [-TypeName ] [-Force] [-PassThru] - [-NotePropertyMembers] [] +```powershell +Add-Member [-NotePropertyMembers] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` ## DESCRIPTION diff --git a/reference/6/Microsoft.PowerShell.Utility/Add-Member.md b/reference/6/Microsoft.PowerShell.Utility/Add-Member.md index d119a02b4ece..d81088e3732a 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/6/Microsoft.PowerShell.Utility/Add-Member.md @@ -16,29 +16,30 @@ Adds custom properties and methods to an instance of a Windows PowerShell object ## SYNTAX ### TypeNameSet (Default) -``` -Add-Member -InputObject -TypeName [-PassThru] [-InformationAction ] - [-InformationVariable ] [] +```powershell +Add-Member -InputObject -TypeName [-PassThru] + [] ``` ### MemberSet -``` -Add-Member -InputObject [-MemberType] [-Name] [[-Value] ] - [[-SecondValue] ] [-TypeName ] [-Force] [-PassThru] [-InformationAction ] - [-InformationVariable ] [] +```powershell +Add-Member [-MemberType] [-Name] + [[-Value] ] [[-SecondValue] ] + -InputObject [-TypeName ] [-Force] [-PassThru] + [] ``` ### NotePropertySingleMemberSet -``` -Add-Member -InputObject [-TypeName ] [-Force] [-PassThru] [-NotePropertyName] - [-NotePropertyValue] [-InformationAction ] [-InformationVariable ] +```powershell +Add-Member [-NotePropertyName] [-NotePropertyValue] + -InputObject [-TypeName ] [-Force] [-PassThru] [] ``` ### NotePropertyMultiMemberSet -``` -Add-Member -InputObject [-TypeName ] [-Force] [-PassThru] - [-NotePropertyMembers] [-InformationAction ] [-InformationVariable ] +```powershell +Add-Member [-NotePropertyMembers] + -InputObject [-TypeName ] [-Force] [-PassThru] [] ``` @@ -261,33 +262,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -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. @@ -328,7 +302,7 @@ Aliases: Type Accepted values: AliasProperty, CodeProperty, Property, NoteProperty, ScriptProperty, Properties, PropertySet, Method, CodeMethod, ScriptMethod, Methods, ParameterizedProperty, MemberSet, Event, Dynamic, All Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -343,7 +317,7 @@ Parameter Sets: MemberSet Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -388,7 +362,7 @@ Parameter Sets: MemberSet Aliases: Required: False -Position: 4 +Position: 3 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -404,7 +378,7 @@ Parameter Sets: MemberSet Aliases: Required: False -Position: 3 +Position: 2 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -424,7 +398,7 @@ Parameter Sets: NotePropertyMultiMemberSet Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -444,7 +418,7 @@ Parameter Sets: NotePropertySingleMemberSet Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -464,7 +438,7 @@ Parameter Sets: NotePropertySingleMemberSet Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False From 2342a7ebae2d45899b6e65c6402a2a8f2fb7cafc Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Wed, 13 Dec 2017 00:46:43 +0900 Subject: [PATCH 100/188] Fix parameter's position in Select-Object.md (#1945) --- .../Select-Object.md | 15 ++--- .../Select-Object.md | 15 ++--- .../Select-Object.md | 20 +++--- .../Select-Object.md | 20 +++--- .../Select-Object.md | 61 ++++--------------- 5 files changed, 49 insertions(+), 82 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Select-Object.md b/reference/3.0/Microsoft.PowerShell.Utility/Select-Object.md index dba09329960f..b75ff792c7d5 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Select-Object.md @@ -14,15 +14,16 @@ Selects objects or object properties. ## SYNTAX ### DefaultParameter (Default) -``` -Select-Object [-InputObject ] [[-Property] ] [-ExcludeProperty ] - [-ExpandProperty ] [-Unique] [-Last ] [-First ] [-Skip ] [-Wait] - [] +```powershell +Select-Object [[-Property] ] [-InputObject ] + [-ExcludeProperty ] [-ExpandProperty ] [-Unique] + [-Last ] [-First ] [-Skip ] [-Wait] [] ``` ### IndexParameter -``` -Select-Object [-InputObject ] [-Unique] [-Wait] [-Index ] [] +```powershell +Select-Object [-InputObject ] [-Unique] [-Wait] [-Index ] + [] ``` ## DESCRIPTION @@ -279,7 +280,7 @@ Parameter Sets: DefaultParameter Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: True diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Select-Object.md b/reference/4.0/Microsoft.PowerShell.Utility/Select-Object.md index cabef927b5ee..0254695f3498 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Select-Object.md @@ -16,15 +16,16 @@ Selects objects or object properties. ## SYNTAX ### DefaultParameter (Default) -``` -Select-Object [-InputObject ] [[-Property] ] [-ExcludeProperty ] - [-ExpandProperty ] [-Unique] [-Last ] [-First ] [-Skip ] [-Wait] - [] +```powershell +Select-Object [[-Property] ] [-InputObject ] + [-ExcludeProperty ] [-ExpandProperty ] [-Unique] + [-Last ] [-First ] [-Skip ] [-Wait] [] ``` ### IndexParameter -``` -Select-Object [-InputObject ] [-Unique] [-Wait] [-Index ] [] +```powershell +Select-Object [-InputObject ] [-Unique] [-Wait] [-Index ] + [] ``` ## DESCRIPTION @@ -290,7 +291,7 @@ Parameter Sets: DefaultParameter Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: True diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Select-Object.md b/reference/5.0/Microsoft.PowerShell.Utility/Select-Object.md index a4c27a971c6a..2241889e3840 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Select-Object.md @@ -16,21 +16,23 @@ Selects objects or object properties. ## SYNTAX ### DefaultParameter (Default) -``` -Select-Object [-InputObject ] [[-Property] ] [-ExcludeProperty ] - [-ExpandProperty ] [-Unique] [-Last ] [-First ] [-Skip ] [-Wait] - [] +```powershell +Select-Object [[-Property] ] [-InputObject ] + [-ExcludeProperty ] [-ExpandProperty ] [-Unique] + [-Last ] [-First ] [-Skip ] [-Wait] [] ``` ### SkipLastParameter -``` -Select-Object [-InputObject ] [[-Property] ] [-ExcludeProperty ] - [-ExpandProperty ] [-Unique] [-SkipLast ] [] +```powershell +Select-Object [[-Property] ] [-InputObject ] + [-ExcludeProperty ] [-ExpandProperty ] [-Unique] + [-SkipLast ] [] ``` ### IndexParameter -``` -Select-Object [-InputObject ] [-Unique] [-Wait] [-Index ] [] +```powershell +Select-Object [-InputObject ] [-Unique] [-Wait] [-Index ] + [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md b/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md index 2b7b70b965e6..7d72e4b53e8e 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Select-Object.md @@ -16,21 +16,23 @@ Selects objects or object properties. ## SYNTAX ### DefaultParameter (Default) -``` -Select-Object [-InputObject ] [[-Property] ] [-ExcludeProperty ] - [-ExpandProperty ] [-Unique] [-Last ] [-First ] [-Skip ] [-Wait] - [] +```powershell +Select-Object [[-Property] ] [-InputObject ] + [-ExcludeProperty ] [-ExpandProperty ] [-Unique] + [-Last ] [-First ] [-Skip ] [-Wait] [] ``` ### SkipLastParameter -``` -Select-Object [-InputObject ] [[-Property] ] [-ExcludeProperty ] - [-ExpandProperty ] [-Unique] [-SkipLast ] [] +```powershell +Select-Object [[-Property] ] [-InputObject ] + [-ExcludeProperty ] [-ExpandProperty ] [-Unique] + [-SkipLast ] [] ``` ### IndexParameter -``` -Select-Object [-InputObject ] [-Unique] [-Wait] [-Index ] [] +```powershell +Select-Object [-InputObject ] [-Unique] [-Wait] [-Index ] + [] ``` ## DESCRIPTION diff --git a/reference/6/Microsoft.PowerShell.Utility/Select-Object.md b/reference/6/Microsoft.PowerShell.Utility/Select-Object.md index b20a15a7fcca..57c67d3a2dae 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Select-Object.md +++ b/reference/6/Microsoft.PowerShell.Utility/Select-Object.md @@ -16,23 +16,23 @@ Selects objects or object properties. ## SYNTAX ### DefaultParameter (Default) -``` -Select-Object [-InputObject ] [[-Property] ] [-ExcludeProperty ] - [-ExpandProperty ] [-Unique] [-Last ] [-First ] [-Skip ] [-Wait] - [-InformationAction ] [-InformationVariable ] [] +```powershell +Select-Object [[-Property] ] [-InputObject ] + [-ExcludeProperty ] [-ExpandProperty ] [-Unique] + [-Last ] [-First ] [-Skip ] [-Wait] [] ``` ### SkipLastParameter -``` -Select-Object [-InputObject ] [[-Property] ] [-ExcludeProperty ] - [-ExpandProperty ] [-Unique] [-SkipLast ] [-InformationAction ] - [-InformationVariable ] [] +```powershell +Select-Object [[-Property] ] [-InputObject ] + [-ExcludeProperty ] [-ExpandProperty ] [-Unique] + [-SkipLast ] [] ``` ### IndexParameter -``` +```powershell Select-Object [-InputObject ] [-Unique] [-Wait] [-Index ] - [-InformationAction ] [-InformationVariable ] [] + [] ``` ## DESCRIPTION @@ -225,45 +225,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are: - --- Name or Label - --- Expression or - -For more information, see the examples.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -The value of the property parameter can be a calculated property, which is a hash table that specifies a name and calculates a value for the property display. Valid keys are: - --- Name or Label - --- Expression or - -For more information, see the examples.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -InputObject Specifies objects to send to the cmdlet through the pipeline. This parameter enables you to pipe objects to **Select-Object**. @@ -315,7 +276,7 @@ Parameter Sets: DefaultParameter, SkipLastParameter Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False From 7e23ff9298c23554ace2af0ca43161ef8e5b0a80 Mon Sep 17 00:00:00 2001 From: Derek Robinson Date: Tue, 12 Dec 2017 09:47:20 -0600 Subject: [PATCH 101/188] Correcting add to hash table example (#1944) * Update about_Hash_Tables.md corrected add to hash table example in 3.0 * Update about_Hash_Tables.md corrected add to hash table examples in 4.0 * Update about_Hash_Tables.md corrected add to hash table example in 5.0 * Update about_Hash_Tables.md corrected add to hash table example in 5.1 * Update about_Hash_Tables.md corrected add to hash table example in 6 --- .../3.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md | 2 +- .../4.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md | 2 +- .../5.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md | 2 +- .../5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md | 2 +- .../6/Microsoft.PowerShell.Core/About/about_Hash_Tables.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 174cf4dd2d6a..d13ac50fe00f 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -245,7 +245,7 @@ For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. ```powershell -$hash = $hash.Add("Time", "Now") +$hash.Add("Time", "Now") ``` And, you can add keys and values to a hash table by using the addition diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 174cf4dd2d6a..d13ac50fe00f 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -245,7 +245,7 @@ For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. ```powershell -$hash = $hash.Add("Time", "Now") +$hash.Add("Time", "Now") ``` And, you can add keys and values to a hash table by using the addition diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 174cf4dd2d6a..d13ac50fe00f 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -245,7 +245,7 @@ For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. ```powershell -$hash = $hash.Add("Time", "Now") +$hash.Add("Time", "Now") ``` And, you can add keys and values to a hash table by using the addition diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 174cf4dd2d6a..d13ac50fe00f 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -245,7 +245,7 @@ For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. ```powershell -$hash = $hash.Add("Time", "Now") +$hash.Add("Time", "Now") ``` And, you can add keys and values to a hash table by using the addition diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 174cf4dd2d6a..d13ac50fe00f 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -245,7 +245,7 @@ For example, to add a "Time" key with a value of "Now" to the hash table, use the following statement format. ```powershell -$hash = $hash.Add("Time", "Now") +$hash.Add("Time", "Now") ``` And, you can add keys and values to a hash table by using the addition From 4e99941819ca50a31c47831d4f2caa131d2f0782 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Thu, 14 Dec 2017 00:43:59 +0900 Subject: [PATCH 102/188] Fix Set-TraceSource -ListenerOption parameter (#1949) * Fixed the value of "Accepted values:" * Fixed minor differences in formatting and wording --- .../Set-TraceSource.md | 20 ++++++++++++++----- .../Set-TraceSource.md | 20 ++++++++++++++----- .../Set-TraceSource.md | 4 ++-- .../Set-TraceSource.md | 3 ++- .../Set-TraceSource.md | 7 ++++--- 5 files changed, 38 insertions(+), 16 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Set-TraceSource.md b/reference/3.0/Microsoft.PowerShell.Utility/Set-TraceSource.md index a9445e46eb7d..56ed0a2a9ac6 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Set-TraceSource.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Set-TraceSource.md @@ -102,20 +102,30 @@ Accept wildcard characters: False ``` ### -ListenerOption -Adds optional data to the prefix of each trace message in the output. -The valid values are "None", "LogicalOperationStack", "DateTime", "Timestamp", "ProcessId", "ThreadId", and "Callstack". -"None" is the default. +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: + +- None +- LogicalOperationStack +- DateTime +- Timestamp +- ProcessId +- ThreadId +- Callstack + +None is the default. To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID". ```yaml Type: TraceOptions Parameter Sets: optionsSet -Aliases: +Aliases: +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named -Default value: "None" +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Set-TraceSource.md b/reference/4.0/Microsoft.PowerShell.Utility/Set-TraceSource.md index e2dc620f9ae1..32c4b0f0cf4a 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Set-TraceSource.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Set-TraceSource.md @@ -107,20 +107,30 @@ Accept wildcard characters: False ``` ### -ListenerOption -Adds optional data to the prefix of each trace message in the output. -The valid values are "None", "LogicalOperationStack", "DateTime", "Timestamp", "ProcessId", "ThreadId", and "Callstack". -"None" is the default. +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: + +- None +- LogicalOperationStack +- DateTime +- Timestamp +- ProcessId +- ThreadId +- Callstack + +None is the default. To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID". ```yaml Type: TraceOptions Parameter Sets: optionsSet -Aliases: +Aliases: +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named -Default value: "None" +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Set-TraceSource.md b/reference/5.0/Microsoft.PowerShell.Utility/Set-TraceSource.md index 85e2f7b1414a..eebe12d65260 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Set-TraceSource.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Set-TraceSource.md @@ -107,7 +107,7 @@ Accept wildcard characters: False ``` ### -ListenerOption -Specifies optional data to add to the prefix of each trace message in the output. +Specifies optional data to the prefix of each trace message in the output. The acceptable values for this parameter are: - None @@ -125,7 +125,7 @@ To specify multiple options, separate them with commas, but with no spaces, and ```yaml Type: TraceOptions Parameter Sets: optionsSet -Aliases: +Aliases: Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Set-TraceSource.md b/reference/5.1/Microsoft.PowerShell.Utility/Set-TraceSource.md index 3a159fa67a1a..12a086c65715 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Set-TraceSource.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Set-TraceSource.md @@ -107,7 +107,8 @@ Accept wildcard characters: False ``` ### -ListenerOption -Specifies optional data to add to the prefix of each trace message in the output.The acceptable values for this parameter are: +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: - None - LogicalOperationStack diff --git a/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md b/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md index 2b255f16c570..d6850b719466 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md +++ b/reference/6/Microsoft.PowerShell.Utility/Set-TraceSource.md @@ -137,7 +137,8 @@ Accept wildcard characters: False ``` ### -ListenerOption -Specifies optional data to add to the prefix of each trace message in the output.The acceptable values for this parameter are: +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: - None - LogicalOperationStack @@ -154,8 +155,8 @@ To specify multiple options, separate them with commas, but with no spaces, and ```yaml Type: TraceOptions Parameter Sets: optionsSet -Aliases: -Accepted values: None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All +Aliases: +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named From 85a3adb57f82cff480d65dfa36a0a990779532c0 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Thu, 14 Dec 2017 00:44:46 +0900 Subject: [PATCH 103/188] Fix Trace-Command -ListenerOption parameter (#1948) * Fixed the value of "Accepted values:" * Fixed minor differences in formatting and wording --- .../Trace-Command.md | 16 +++++++++++++--- .../Trace-Command.md | 16 +++++++++++++--- .../Trace-Command.md | 3 ++- .../Trace-Command.md | 5 +++-- 4 files changed, 31 insertions(+), 9 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Trace-Command.md b/reference/3.0/Microsoft.PowerShell.Utility/Trace-Command.md index 9435adfbd072..4721f2eaf9af 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Trace-Command.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Trace-Command.md @@ -178,9 +178,18 @@ Accept wildcard characters: False ``` ### -ListenerOption -Adds optional data to the prefix of each trace message in the output. -The valid values are None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, and Callstack. -"None" is the default. +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: + +- None +- LogicalOperationStack +- DateTime +- Timestamp +- ProcessId +- ThreadId +- Callstack + +None is the default. To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID". @@ -188,6 +197,7 @@ To specify multiple options, separate them with commas, but with no spaces, and Type: TraceOptions Parameter Sets: (All) Aliases: +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Trace-Command.md b/reference/4.0/Microsoft.PowerShell.Utility/Trace-Command.md index 3feca7361691..4afcacb5117d 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Trace-Command.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Trace-Command.md @@ -183,9 +183,18 @@ Accept wildcard characters: False ``` ### -ListenerOption -Adds optional data to the prefix of each trace message in the output. -The valid values are None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, and Callstack. -"None" is the default. +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: + +- None +- LogicalOperationStack +- DateTime +- Timestamp +- ProcessId +- ThreadId +- Callstack + +None is the default. To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID". @@ -193,6 +202,7 @@ To specify multiple options, separate them with commas, but with no spaces, and Type: TraceOptions Parameter Sets: (All) Aliases: +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Trace-Command.md b/reference/5.1/Microsoft.PowerShell.Utility/Trace-Command.md index a61abffdee59..a2a243e10d0b 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Trace-Command.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Trace-Command.md @@ -183,7 +183,8 @@ Accept wildcard characters: False ``` ### -ListenerOption -Specifies optional data to the prefix of each trace message in the output.The acceptable values for this parameter are: +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: - None - LogicalOperationStack diff --git a/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md b/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md index cb751988bf9c..f4db42f35e2a 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md +++ b/reference/6/Microsoft.PowerShell.Utility/Trace-Command.md @@ -183,7 +183,8 @@ Accept wildcard characters: False ``` ### -ListenerOption -Specifies optional data to the prefix of each trace message in the output.The acceptable values for this parameter are: +Specifies optional data to the prefix of each trace message in the output. +The acceptable values for this parameter are: - None - LogicalOperationStack @@ -201,7 +202,7 @@ To specify multiple options, separate them with commas, but with no spaces, and Type: TraceOptions Parameter Sets: (All) Aliases: -Accepted values: None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All +Accepted values: None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack Required: False Position: Named From ba3ae323d9640a69fc206509a683394517ee0c1b Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Fri, 15 Dec 2017 01:11:47 +0900 Subject: [PATCH 104/188] Fix parameter's position in Select-Xml.md (#1953) --- .../Select-Xml.md | 26 +++++---- .../Select-Xml.md | 26 +++++---- .../Select-Xml.md | 20 ++++--- .../Select-Xml.md | 20 ++++--- .../Select-Xml.md | 57 +++++-------------- 5 files changed, 69 insertions(+), 80 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Select-Xml.md b/reference/3.0/Microsoft.PowerShell.Utility/Select-Xml.md index 1a383fcb6644..30edc8f4ddf8 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Select-Xml.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Select-Xml.md @@ -14,23 +14,27 @@ Finds text in an XML string or document. ## SYNTAX ### Xml (Default) -``` -Select-Xml [-Xml] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Xml] [-Namespace ] + [] ``` ### Path -``` -Select-Xml [-Path] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Path] [-Namespace ] + [] ``` ### LiteralPath -``` -Select-Xml -LiteralPath [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -LiteralPath [-Namespace ] + [] ``` ### Content -``` -Select-Xml -Content [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -Content [-Namespace ] + [] ``` ## DESCRIPTION @@ -214,7 +218,7 @@ Parameter Sets: Path Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True @@ -231,7 +235,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -249,7 +253,7 @@ Parameter Sets: Xml Aliases: Node Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Select-Xml.md b/reference/4.0/Microsoft.PowerShell.Utility/Select-Xml.md index 27dd86a4e05c..5d88cc4b07f2 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Select-Xml.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Select-Xml.md @@ -16,23 +16,27 @@ Finds text in an XML string or document. ## SYNTAX ### Xml (Default) -``` -Select-Xml [-Xml] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Xml] [-Namespace ] + [] ``` ### Path -``` -Select-Xml [-Path] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Path] [-Namespace ] + [] ``` ### LiteralPath -``` -Select-Xml -LiteralPath [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -LiteralPath [-Namespace ] + [] ``` ### Content -``` -Select-Xml -Content [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -Content [-Namespace ] + [] ``` ## DESCRIPTION @@ -222,7 +226,7 @@ Parameter Sets: Path Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True @@ -239,7 +243,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -257,7 +261,7 @@ Parameter Sets: Xml Aliases: Node Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Select-Xml.md b/reference/5.0/Microsoft.PowerShell.Utility/Select-Xml.md index d148c2dee109..1ed9f4cbf757 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Select-Xml.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Select-Xml.md @@ -16,23 +16,27 @@ Finds text in an XML string or document. ## SYNTAX ### Xml (Default) -``` -Select-Xml [-Xml] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Xml] [-Namespace ] + [] ``` ### Path -``` -Select-Xml [-Path] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Path] [-Namespace ] + [] ``` ### LiteralPath -``` -Select-Xml -LiteralPath [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -LiteralPath [-Namespace ] + [] ``` ### Content -``` -Select-Xml -Content [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -Content [-Namespace ] + [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Select-Xml.md b/reference/5.1/Microsoft.PowerShell.Utility/Select-Xml.md index d148c2dee109..1ed9f4cbf757 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Select-Xml.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Select-Xml.md @@ -16,23 +16,27 @@ Finds text in an XML string or document. ## SYNTAX ### Xml (Default) -``` -Select-Xml [-Xml] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Xml] [-Namespace ] + [] ``` ### Path -``` -Select-Xml [-Path] [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] [-Path] [-Namespace ] + [] ``` ### LiteralPath -``` -Select-Xml -LiteralPath [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -LiteralPath [-Namespace ] + [] ``` ### Content -``` -Select-Xml -Content [-XPath] [-Namespace ] [] +```powershell +Select-Xml [-XPath] -Content [-Namespace ] + [] ``` ## DESCRIPTION diff --git a/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md b/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md index 049b264b4022..68018279e772 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md +++ b/reference/6/Microsoft.PowerShell.Utility/Select-Xml.md @@ -16,27 +16,27 @@ Finds text in an XML string or document. ## SYNTAX ### Xml (Default) -``` -Select-Xml [-Xml] [-XPath] [-Namespace ] - [-InformationAction ] [-InformationVariable ] [] +```powershell +Select-Xml [-XPath] [-Xml] [-Namespace ] + [] ``` ### Path -``` -Select-Xml [-Path] [-XPath] [-Namespace ] - [-InformationAction ] [-InformationVariable ] [] +```powershell +Select-Xml [-XPath] [-Path] [-Namespace ] + [] ``` ### LiteralPath -``` -Select-Xml -LiteralPath [-XPath] [-Namespace ] - [-InformationAction ] [-InformationVariable ] [] +```powershell +Select-Xml [-XPath] -LiteralPath [-Namespace ] + [] ``` ### Content -``` -Select-Xml -Content [-XPath] [-Namespace ] - [-InformationAction ] [-InformationVariable ] [] +```powershell +Select-Xml [-XPath] -Content [-Namespace ] + [] ``` ## DESCRIPTION @@ -203,33 +203,6 @@ Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` -### -InformationAction -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Namespace Specifies a hash table of the namespaces used in the XML. Use the format @{\ = \}. @@ -260,7 +233,7 @@ Parameter Sets: Path Aliases: Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False @@ -277,7 +250,7 @@ Parameter Sets: (All) Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -295,7 +268,7 @@ Parameter Sets: Xml Aliases: Node Required: True -Position: 2 +Position: 1 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False From e9721d208e9e42f7967675b976bb1c1f6c80afa9 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Fri, 15 Dec 2017 01:13:16 +0900 Subject: [PATCH 105/188] Fix Get-Alias -Name parameter (#1952) * Position: 0 * Default value: All aliases * Accept wildcard characters: True * Fixed minor differences in formatting and wording And also removed InformationAction/InformationVariable in v6.0. --- .../Microsoft.PowerShell.Utility/Get-Alias.md | 22 ++++---- .../Microsoft.PowerShell.Utility/Get-Alias.md | 22 ++++---- .../Microsoft.PowerShell.Utility/Get-Alias.md | 22 ++++---- .../Microsoft.PowerShell.Utility/Get-Alias.md | 22 ++++---- .../Microsoft.PowerShell.Utility/Get-Alias.md | 51 +++++-------------- 5 files changed, 60 insertions(+), 79 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md index d5cc83616c44..0d3b2fa3b993 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Get-Alias.md @@ -14,13 +14,15 @@ Gets the aliases for the current session. ## SYNTAX ### Default (Default) -``` -Get-Alias [[-Name] ] [-Exclude ] [-Scope ] [] +```powershell +Get-Alias [[-Name] ] [-Exclude ] [-Scope ] + [] ``` ### Definition -``` -Get-Alias [-Exclude ] [-Scope ] [-Definition ] [] +```powershell +Get-Alias [-Exclude ] [-Scope ] [-Definition ] + [] ``` ## DESCRIPTION @@ -139,19 +141,19 @@ Accept wildcard characters: True ``` ### -Name -Specifies the aliases to retrieve. +Specifies the aliases that this cmdlet gets. Wildcards are permitted. -By default, Get-Alias retrieves all aliases defined for the current session. -The parameter name ("Name") is optional. -You can also pipe alias names to Get-Alias. +By default, `Get-Alias` retrieves all aliases defined for the current session. +The parameter name **Name** is optional. +You can also pipe alias names to `Get-Alias`. ```yaml Type: String[] Parameter Sets: Default -Aliases: +Aliases: Required: False -Position: 1 +Position: 0 Default value: All aliases Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: True diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md index 32666d375c1e..33741ff3cc8a 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Get-Alias.md @@ -16,13 +16,15 @@ Gets the aliases for the current session. ## SYNTAX ### Default (Default) -``` -Get-Alias [[-Name] ] [-Exclude ] [-Scope ] [] +```powershell +Get-Alias [[-Name] ] [-Exclude ] [-Scope ] + [] ``` ### Definition -``` -Get-Alias [-Exclude ] [-Scope ] [-Definition ] [] +```powershell +Get-Alias [-Exclude ] [-Scope ] [-Definition ] + [] ``` ## DESCRIPTION @@ -146,19 +148,19 @@ Accept wildcard characters: True ``` ### -Name -Specifies the aliases to retrieve. +Specifies the aliases that this cmdlet gets. Wildcards are permitted. -By default, Get-Alias retrieves all aliases defined for the current session. -The parameter name ("Name") is optional. -You can also pipe alias names to Get-Alias. +By default, `Get-Alias` retrieves all aliases defined for the current session. +The parameter name **Name** is optional. +You can also pipe alias names to `Get-Alias`. ```yaml Type: String[] Parameter Sets: Default -Aliases: +Aliases: Required: False -Position: 1 +Position: 0 Default value: All aliases Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: True diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md index b98e54e4a55d..3a0dfb2d541b 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Get-Alias.md @@ -16,13 +16,15 @@ Gets the aliases for the current session. ## SYNTAX ### Default (Default) -``` -Get-Alias [[-Name] ] [-Exclude ] [-Scope ] [] +```powershell +Get-Alias [[-Name] ] [-Exclude ] [-Scope ] + [] ``` ### Definition -``` -Get-Alias [-Exclude ] [-Scope ] [-Definition ] [] +```powershell +Get-Alias [-Exclude ] [-Scope ] [-Definition ] + [] ``` ## DESCRIPTION @@ -148,20 +150,20 @@ Accept wildcard characters: False ### -Name Specifies the aliases that this cmdlet gets. Wildcards are permitted. -By default, **Get-Alias** retrieves all aliases defined for the current session. -The parameter name *Name* is optional. -You can also pipe alias names to **Get-Alias**. +By default, `Get-Alias` retrieves all aliases defined for the current session. +The parameter name **Name** is optional. +You can also pipe alias names to `Get-Alias`. ```yaml Type: String[] Parameter Sets: Default -Aliases: +Aliases: Required: False Position: 0 -Default value: None +Default value: All aliases Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Scope diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md index dbdaf6e0741b..9b7cea698f66 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Get-Alias.md @@ -16,13 +16,15 @@ Gets the aliases for the current session. ## SYNTAX ### Default (Default) -``` -Get-Alias [[-Name] ] [-Exclude ] [-Scope ] [] +```powershell +Get-Alias [[-Name] ] [-Exclude ] [-Scope ] + [] ``` ### Definition -``` -Get-Alias [-Exclude ] [-Scope ] [-Definition ] [] +```powershell +Get-Alias [-Exclude ] [-Scope ] [-Definition ] + [] ``` ## DESCRIPTION @@ -137,20 +139,20 @@ Accept wildcard characters: False ### -Name Specifies the aliases that this cmdlet gets. Wildcards are permitted. -By default, **Get-Alias** retrieves all aliases defined for the current session. -The parameter name *Name* is optional. -You can also pipe alias names to **Get-Alias**. +By default, `Get-Alias` retrieves all aliases defined for the current session. +The parameter name **Name** is optional. +You can also pipe alias names to `Get-Alias`. ```yaml Type: String[] Parameter Sets: Default -Aliases: +Aliases: Required: False Position: 0 -Default value: None +Default value: All aliases Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Scope diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md b/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md index 7747dc402bdc..9b7cea698f66 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-Alias.md @@ -16,15 +16,15 @@ Gets the aliases for the current session. ## SYNTAX ### Default (Default) -``` -Get-Alias [[-Name] ] [-Exclude ] [-Scope ] [-InformationAction ] - [-InformationVariable ] [] +```powershell +Get-Alias [[-Name] ] [-Exclude ] [-Scope ] + [] ``` ### Definition -``` +```powershell Get-Alias [-Exclude ] [-Scope ] [-Definition ] - [-InformationAction ] [-InformationVariable ] [] + [] ``` ## DESCRIPTION @@ -136,50 +136,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -This parameter is called Definition, because it searches for the item name in the Definition property of the alias object.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Name Specifies the aliases that this cmdlet gets. Wildcards are permitted. -By default, **Get-Alias** retrieves all aliases defined for the current session. -The parameter name *Name* is optional. -You can also pipe alias names to **Get-Alias**. +By default, `Get-Alias` retrieves all aliases defined for the current session. +The parameter name **Name** is optional. +You can also pipe alias names to `Get-Alias`. ```yaml Type: String[] Parameter Sets: Default -Aliases: +Aliases: Required: False -Position: 1 -Default value: None +Position: 0 +Default value: All aliases Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Scope From 41dc145eed06a733743c5ec766a7fca1f65f54db Mon Sep 17 00:00:00 2001 From: "J. Keith Bankston [MSFT]" Date: Thu, 14 Dec 2017 08:22:14 -0800 Subject: [PATCH 106/188] Wmf 5.1 cleanup (#1950) * Changed required PSGet version to 1.6.0 * Fixes to PSGet TOC and WMF 5.1 compat page * Add note explaining WMF does not ship in Windows --- wmf/5.1/compatibility.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/wmf/5.1/compatibility.md b/wmf/5.1/compatibility.md index e3225df9033b..4f5fdc3cbec4 100644 --- a/wmf/5.1/compatibility.md +++ b/wmf/5.1/compatibility.md @@ -32,3 +32,7 @@ The features of WMF 5.1 were included in Windows Server 2016 and Windows 10 Anni WMF 5.1 is not applicable for these operating system versions, as the updates are provided via Windows Update. +One thing to note is that WMF does not ship in Windows. +WMF is an upgrade package that provides a set of Windows features to previously released Windows versions. +This can make an important difference when seeking assistance for any of those features, as the version of those components will not match what shipped in the original operating system. + From c11cc97183d8b4e41eef05bae64fceca0e72932b Mon Sep 17 00:00:00 2001 From: Finn Ellis Date: Thu, 14 Dec 2017 08:45:05 -0800 Subject: [PATCH 107/188] Typo fix ("you will are not" -> "you will not"). (#1951) * Typo fix ("you will are not" -> "you will not"). * Changed from passive voice to active voice --- reference/5.1/Microsoft.PowerShell.Management/Stop-Process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Stop-Process.md b/reference/5.1/Microsoft.PowerShell.Management/Stop-Process.md index db23cdff05dc..bc67d80cd668 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Stop-Process.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Stop-Process.md @@ -36,7 +36,7 @@ You can specify a process by process name or process ID (PID), or pass a process **Stop-Process** works only on processes running on the local computer. On Windows Vista and later versions of the Windows operating system, to stop a process that is not owned by the current user, you must start Windows PowerShell by using the Run as administrator option. -Also, you are will not be prompted for confirmation unless you specify the *Confirm* parameter. +Also, you are not prompted for confirmation unless you specify the *Confirm* parameter. ## EXAMPLES From 8be92ec3673ebedf30f75f7e86511711c8f0dd53 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 14 Dec 2017 09:57:36 -0800 Subject: [PATCH 108/188] added article about formatting code samples --- CONTRIBUTING.md | 1 + contributing/FORAMTTING-CODE.md | 169 ++++++++++++++++++++++++++++++++ contributing/STYLE.md | 43 +------- 3 files changed, 175 insertions(+), 38 deletions(-) create mode 100644 contributing/FORAMTTING-CODE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf075f5c0f25..cd24fefc9385 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,3 +7,4 @@ The following topics explain how to contribute to the PowerShell documentation. 1. [Get started](./contributing/GETSTARTED.md) 2. [Writing PowerShell documentation](./contributing/WRITING.md) 3. [Style Guide](./contributing/STYLE.md) +4. [Formatting code blocks](./contributing/FORMATTING-CODE.md). diff --git a/contributing/FORAMTTING-CODE.md b/contributing/FORAMTTING-CODE.md new file mode 100644 index 000000000000..113995fc6d67 --- /dev/null +++ b/contributing/FORAMTTING-CODE.md @@ -0,0 +1,169 @@ +# Formatting code blocks + +We want to adopt a consistent style for PowerShell code blocks and output in our documentation. +The existing documentation has uses multiple styles and the formatting rules have changed multiple times. +The current Open Publishing System (OPS) we use has a syntax highlighting feature that support many languages. +OPS also adds a **Copy** button that copies the contents of the code block to the clipboard. +This allows you to quickly paste the code into a script for testing the code example. +However, not all examples in our documentation are intended to be run. +Some code blocks are simple illustrations of a PowerShell concept. + +We are defining two scenarios for code blocks: + +1. Illustrative examples +2. Executable examples + +## Formatting illustrative examples + +Illustrative examples are used to explain a PowerShell concept. +They are not meant to be copied to the clipboard for execution. +These are most commonly used for simple examples that are easy to type. +They are also used for syntax examples where you are illustrating the syntax of a command. + +Illustrative examples use a "naked" code fence to mark the beginning and end of the code block. +The code block may contain example output from the command being illustrated. + +### Syntax block + +Here is an example of a syntax block: + + ``` + Get-Command [-Verb ] [-Noun ] [-Module ] + [-FullyQualifiedModule ] [-TotalCount ] [-Syntax] [-ShowCommandInfo] + [[-ArgumentList] ] [-All] [-ListImported] [-ParameterName ] + [-ParameterType ] [] + ``` + +This is example is illustrating all of the possible parameters of the `Get-Command` cmdlet. + +Here is another syntax example that is describing the `for` statement in general terms: + + ``` + for (>init>; ; ) + {} + ``` + +### Simple illustration example + +Here is an example illustrating PowerShell comparison operators: + + ``` + PS> 2 -eq 2 + True + + PS> 2 -eq 3 + False + + PS> 1,2,3 -eq 2 + 2 + + PS> "abc" -eq "abc" + True + + PS> "abc" -eq "abc", "def" + False + + PS> "abc", "def" -eq "abc" + abc + ``` + +Note that this example has the simplified PowerShell prompt and shows the resulting output. +In this case, we don't intend the reader to copy this example and try to run the copied code. + +## Formatting executable examples + +More complex examples or examples that would be useful to copy and execute should use \`\`\`powershell … \`\`\` code fence markers. +Output emitted by PowerShell commands should be enclosed in a **Output** code block to prevent syntax highlighting. + + For example: + + ```powershell + Get-Command -Module Microsoft.PowerShell.Security + ``` + + ```Output + CommandType Name Version Source + ----------- ---- ------- ------ + Cmdlet ConvertFrom-SecureString 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet ConvertTo-SecureString 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-Acl 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-Credential 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Get-PfxCertificate 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet New-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Protect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Set-Acl 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Set-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Set-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Test-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security + Cmdlet Unprotect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security + ``` + +The **Output** code label is not an official "language" supported by the syntax highlighting system. +However, this label is useful because OPS adds the "Output" label to the code box on the web page. +And this "Output" code box has no syntax highlighting. + +## Understanding the COPY button + +OPS also adds a **Copy** button that copies the contents of the code block to the clipboard. +This allows you to quickly paste the code into a script for testing the code example. +The **Copy** button also removes PowerShell prompts from the text before copying it to the clipboard. +The **Copy** button uses the following javascript code to remove the prompts. + +```javascript +if (language === 'powershell') { + text = text.replace(/\bPS [a-z]:\\>\s?/gi, ''); +} +``` + +Note that the regex used only matches simple prompts like "`PS C:\>`". +Prompts that include subdirectories or paths from other PSDrive providers will not be removed. +See the general guidelines, in the next section, for the appropriate use of prompts in examples. + +## General guidelines + +- Code fences + + Markdown allows for indentation to signal code block, however, all code blocks should be contained in a code fence. + A code fence is a block of code surrounded by \`\`\` strings. + The code fence markers must be on their own line before and after the code sample. + The marker at the start of the code block may have an optional language label. + See the previous discussion about illustrative and executable examples for the proper use of language labels. + +- Line continuation in code samples + + Avoid using line continuation characters (\`) in PowerShell code examples. + These are a hard to see and can cause problems if there are extra spaces on the end of the line. + Use PowerShell splatting to reduce line length for cmdlets that have a lot of parameters. + Take advantage of PowerShell's natural line break opportunities, like after pipe (\|) characters and opening braces, parentheses, and brackets. + +- PowerShell prompts in examples + + PowerShell prompts should only be used in illustrative examples (as defined previously). + For most of these examples, the prompt string should be "`PS>`". + This prompt is independent of OS-specific indicators. + Use of the prompt string is discouraged and should be limited to scenarios that are meant to illustrate command line usage. + More complex prompt strings are required for examples that illustrate commands that alter the prompt + or when the path displayed is significant to the scenario being illustrated. + The following example illustrate how the prompt changes when using the Registry provider. + + ``` + PS C:\> cd HKCU:\System\ + PS HKEY_CURRENT_USER\System\> dir + + + Hive: HKEY_CURRENT_USER\System + + + Name Property + ---- -------- + CurrentControlSet + GameConfigStore GameDVR_Enabled : 1 + GameDVR_FSEBehaviorMode : 2 + Win32_AutoGameModeDefaultProfile : {2, 0, 1, 0...} + Win32_GameModeRelatedProcesses : {1, 0, 1, 0...} + GameDVR_HonorUserFSEBehaviorMode : 0 + GameDVR_DXGIHonorFSEWindowsCompatible : 0 + ``` diff --git a/contributing/STYLE.md b/contributing/STYLE.md index cef7671966eb..c17e3e0562a8 100644 --- a/contributing/STYLE.md +++ b/contributing/STYLE.md @@ -6,7 +6,7 @@ There are several variants of PowerShell. This table defines some of the different terms used to discuss PowerShell. | Terminology | Definition | -| ----- | -----| +| ----- | ----- | | PowerShell | This is the default. We are shipping PowerShell. The term PowerShell can be legitimately used to indicate any of the particular editions. This can be used to refer to the language, framework and default cmdlets, etc. | | PowerShell Core (PSCore) | PowerShell built on .NET Core Common Language Runtime (CoreCLR) for any of the platforms. | | Windows PowerShell | PowerShell built on .NET Common Language Runtime (CLR). Windows PowerShell ships only on Windows and requires the complete CLR. | @@ -84,43 +84,6 @@ Adding or removing H2 causes a build break. This [`Write-Host`](..\reference\6\Microsoft.PowerShell.Utility\Write-Host.md) cmdlet uses the **-Object** parameter to ... -## Formatting code blocks - -* All PowerShell syntax blocks should use \`\`\`powershell … \`\`\` code fence markers. - -* Do **NOT** start PowerShell commands with the PowerShell prompt ("`PS C:\>`"). - -* Avoid using line continuation characters (\`) in PowerShell code examples. - These are a hard to see and can cause problems if there are extra spaces on the end of the line. - -* Output emitted by PowerShell commands should be enclosed in a naked code block to prevent it from recieving syntax highlighting. - - For example: - - ```powershell - Get-Command -Module Microsoft.PowerShell.Security - ``` - - ``` - CommandType Name Version Source - ----------- ---- ------- ------ - Cmdlet ConvertFrom-SecureString 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet ConvertTo-SecureString 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-Acl 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-Credential 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Get-PfxCertificate 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet New-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Protect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Set-Acl 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Set-AuthenticodeSignature 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Set-ExecutionPolicy 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Test-FileCatalog 3.0.0.0 Microsoft.PowerShell.Security - Cmdlet Unprotect-CmsMessage 3.0.0.0 Microsoft.PowerShell.Security - ``` - ## Lists * Do not end list items with a period (unless they contain multiple sentences) @@ -162,6 +125,10 @@ There are special rules for linking to reference topics from conceptual topics. \[TO DO\] - document special rules +## Next steps + +See [Formatting code blocks](FORMATTING-CODE.md). + [pascal-case]: https://en.wikipedia.org/wiki/PascalCase [issue1806]: https://github.com/PowerShell/PowerShell-Docs/issues/1806 From 52c3d1d3291f977d13974267055a8e8c43417820 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 14 Dec 2017 10:10:25 -0800 Subject: [PATCH 109/188] fixing typos --- contributing/FORAMTTING-CODE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/contributing/FORAMTTING-CODE.md b/contributing/FORAMTTING-CODE.md index 113995fc6d67..c7f261f04df5 100644 --- a/contributing/FORAMTTING-CODE.md +++ b/contributing/FORAMTTING-CODE.md @@ -1,8 +1,8 @@ # Formatting code blocks +The existing documentation has used multiple styles, over time, and the formatting rules have changed multiple times. We want to adopt a consistent style for PowerShell code blocks and output in our documentation. -The existing documentation has uses multiple styles and the formatting rules have changed multiple times. -The current Open Publishing System (OPS) we use has a syntax highlighting feature that support many languages. +The current Open Publishing System (OPS) we use has a syntax highlighting feature that supports many languages. OPS also adds a **Copy** button that copies the contents of the code block to the clipboard. This allows you to quickly paste the code into a script for testing the code example. However, not all examples in our documentation are intended to be run. @@ -141,7 +141,8 @@ See the general guidelines, in the next section, for the appropriate use of prom - PowerShell prompts in examples - PowerShell prompts should only be used in illustrative examples (as defined previously). + PowerShell prompts should only be used in illustrative examples. + Prompts should **NOT** be used in executable examples. For most of these examples, the prompt string should be "`PS>`". This prompt is independent of OS-specific indicators. Use of the prompt string is discouraged and should be limited to scenarios that are meant to illustrate command line usage. From da136b5c4e3db391a6a49f8e5ea516bb2845fda9 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 14 Dec 2017 10:39:29 -0800 Subject: [PATCH 110/188] fixed typos and incorporated feedback --- contributing/FORAMTTING-CODE.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/contributing/FORAMTTING-CODE.md b/contributing/FORAMTTING-CODE.md index c7f261f04df5..2a3c43e6ff88 100644 --- a/contributing/FORAMTTING-CODE.md +++ b/contributing/FORAMTTING-CODE.md @@ -34,12 +34,12 @@ Here is an example of a syntax block: [-ParameterType ] [] ``` -This is example is illustrating all of the possible parameters of the `Get-Command` cmdlet. +This example illustrates all of the possible parameters of the `Get-Command` cmdlet. -Here is another syntax example that is describing the `for` statement in general terms: +Here is another syntax example describing the `for` statement in generalized terms: ``` - for (>init>; ; ) + for (; ; ) {} ``` @@ -126,7 +126,8 @@ See the general guidelines, in the next section, for the appropriate use of prom - Code fences - Markdown allows for indentation to signal code block, however, all code blocks should be contained in a code fence. + Markdown allows for indentation to signify a code block, but this pattern can be problematic and should be avoided. + All code blocks should be contained in a code fence. A code fence is a block of code surrounded by \`\`\` strings. The code fence markers must be on their own line before and after the code sample. The marker at the start of the code block may have an optional language label. @@ -135,7 +136,7 @@ See the general guidelines, in the next section, for the appropriate use of prom - Line continuation in code samples Avoid using line continuation characters (\`) in PowerShell code examples. - These are a hard to see and can cause problems if there are extra spaces on the end of the line. + These are hard to see and can cause problems if there are extra spaces on the end of the line. Use PowerShell splatting to reduce line length for cmdlets that have a lot of parameters. Take advantage of PowerShell's natural line break opportunities, like after pipe (\|) characters and opening braces, parentheses, and brackets. From 7f1bfb61282994c74a2f4e20d5d7935638113c3d Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 14 Dec 2017 11:48:45 -0800 Subject: [PATCH 111/188] updating metadata tags in docfx.json --- dsc/docfx.json | 2 +- gallery/docfx.json | 4 ++-- jea/docfx.json | 2 +- reference/docfx.json | 4 ++-- reference/docs-conceptual/docfx.json | 4 ++-- wmf/docfx.json | 4 ++-- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/dsc/docfx.json b/dsc/docfx.json index 6efaf25b9e83..723ddcc7b52b 100644 --- a/dsc/docfx.json +++ b/dsc/docfx.json @@ -20,7 +20,7 @@ "manager": "carmonm", "ms.devlang": "powershell", "ms.tgt_pltfr": "windows", - "ms.author": "eslesar" + "ms.author": "sewhee" }, "resource": [ { diff --git a/gallery/docfx.json b/gallery/docfx.json index 3b4663cfff20..7015d17719f4 100644 --- a/gallery/docfx.json +++ b/gallery/docfx.json @@ -18,8 +18,8 @@ "manager": "carmonm", "ms.devlang": "powershell", "ms.tgt_pltfr": "windows, macos, linux", - "author": "juanpablojofre", - "ms.author": "jpjofre" + "author": "JKeithB", + "ms.author": "keithb" }, "resource": [ { diff --git a/jea/docfx.json b/jea/docfx.json index eab8a2008c19..431b86b21360 100644 --- a/jea/docfx.json +++ b/jea/docfx.json @@ -18,7 +18,7 @@ "manager": "carmonm", "ms.devlang": "powershell", "ms.tgt_pltfr": "windows", - "ms.author": "jpjofre" + "ms.author": "sewhee" }, "resource": [ { diff --git a/reference/docfx.json b/reference/docfx.json index 681ad61f080d..a8365f764236 100644 --- a/reference/docfx.json +++ b/reference/docfx.json @@ -238,8 +238,8 @@ "ms.topic": "reference", "manager": "carmonm", "ms.tgt_pltfr": "windows, macos, linux", - "author": "juanpablojofre", - "ms.author": "jpjofre" + "author": "sdwheeler", + "ms.author": "sewhee" }, "fileMetadata": {}, "template": [], diff --git a/reference/docs-conceptual/docfx.json b/reference/docs-conceptual/docfx.json index a95f0da40d0b..a557e8d563cb 100644 --- a/reference/docs-conceptual/docfx.json +++ b/reference/docs-conceptual/docfx.json @@ -16,8 +16,8 @@ "manager": "carmonm", "ms.devlang": "powershell", "ms.tgt_pltfr": "windows, macos, linux", - "author": "juanpablojofre", - "ms.author": "jpjofre" + "author": "sdwheeler", + "ms.author": "sewhee" }, "resource": [ { diff --git a/wmf/docfx.json b/wmf/docfx.json index a372afa1f7b3..baf309eb2474 100644 --- a/wmf/docfx.json +++ b/wmf/docfx.json @@ -14,11 +14,11 @@ "uhfHeaderId": "MSDocsHeader-Powershell", "ROBOTS": "INDEX, FOLLOW", "ms.prod": "powershell", - "ms.technology": "wmf", + "ms.technology": "", "manager": "carmonm", "ms.devlang": "powershell", "ms.tgt_pltfr": "windows", - "ms.author": "jpjofre" + "ms.author": "keithb" }, "resource": [ { From d0b75bba3f769ad5599932d468d3fc75ada28a30 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 14 Dec 2017 15:24:56 -0800 Subject: [PATCH 112/188] fixing filename spelling --- contributing/{FORAMTTING-CODE.md => FORMATTING-CODE.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename contributing/{FORAMTTING-CODE.md => FORMATTING-CODE.md} (100%) diff --git a/contributing/FORAMTTING-CODE.md b/contributing/FORMATTING-CODE.md similarity index 100% rename from contributing/FORAMTTING-CODE.md rename to contributing/FORMATTING-CODE.md From 8c303f12a48e360e6c15e54da6727c0e19a40a00 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Sat, 16 Dec 2017 01:58:19 +0900 Subject: [PATCH 113/188] Fix parameter's position in Get-Content.md (#1959) --- .../Get-Content.md | 24 ++++---- .../Get-Content.md | 24 ++++---- .../Get-Content.md | 22 +++++--- .../Get-Content.md | 22 +++++--- .../Get-Content.md | 55 +++++-------------- 5 files changed, 67 insertions(+), 80 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md b/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md index 04238e93f1d4..8d68eac2331a 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md @@ -14,19 +14,23 @@ Gets the content of the item at the specified location. ## SYNTAX ### Path (Default) -``` -Get-Content [-ReadCount ] [-TotalCount ] [-Tail ] [-Path] [-Filter ] - [-Include ] [-Exclude ] [-Force] [-Credential ] [-UseTransaction] - [-Delimiter ] [-Wait] [-Raw] [-Encoding ] [-Stream ] +```powershell +Get-Content [-Path] [-ReadCount ] [-TotalCount ] + [-Tail ] [-Filter ] [-Include ] [-Exclude ] + [-Force] [-Credential ] [-UseTransaction] + [-Delimiter ] [-Wait] [-Raw] + [-Encoding ] [-Stream ] [] ``` ### LiteralPath -``` -Get-Content [-ReadCount ] [-TotalCount ] [-Tail ] -LiteralPath - [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] - [-UseTransaction] [-Delimiter ] [-Wait] [-Raw] [-Encoding ] - [-Stream ] [] +```powershell +Get-Content -LiteralPath [-ReadCount ] [-TotalCount ] + [-Tail ] [-Filter ] [-Include ] [-Exclude ] + [-Force] [-Credential ] [-UseTransaction] + [-Delimiter ] [-Wait] [-Raw] + [-Encoding ] [-Stream ] + [] ``` ## DESCRIPTION @@ -311,7 +315,7 @@ Parameter Sets: Path Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True diff --git a/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md b/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md index f800a5413a72..f68c52f161b7 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md @@ -16,19 +16,23 @@ Gets the content of the item at the specified location. ## SYNTAX ### Path (Default) -``` -Get-Content [-ReadCount ] [-TotalCount ] [-Tail ] [-Path] [-Filter ] - [-Include ] [-Exclude ] [-Force] [-Credential ] [-UseTransaction] - [-Delimiter ] [-Wait] [-Raw] [-Encoding ] [-Stream ] +```powershell +Get-Content [-Path] [-ReadCount ] [-TotalCount ] + [-Tail ] [-Filter ] [-Include ] [-Exclude ] + [-Force] [-Credential ] [-UseTransaction] + [-Delimiter ] [-Wait] [-Raw] + [-Encoding ] [-Stream ] [] ``` ### LiteralPath -``` -Get-Content [-ReadCount ] [-TotalCount ] [-Tail ] -LiteralPath - [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] - [-UseTransaction] [-Delimiter ] [-Wait] [-Raw] [-Encoding ] - [-Stream ] [] +```powershell +Get-Content -LiteralPath [-ReadCount ] [-TotalCount ] + [-Tail ] [-Filter ] [-Include ] [-Exclude ] + [-Force] [-Credential ] [-UseTransaction] + [-Delimiter ] [-Wait] [-Raw] + [-Encoding ] [-Stream ] + [] ``` ## DESCRIPTION @@ -198,7 +202,7 @@ Parameter Sets: Path Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: True diff --git a/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md b/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md index 2e35c6b18336..3c363fae179e 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md @@ -16,19 +16,23 @@ Gets the content of the item at the specified location. ## SYNTAX ### Path (Default) -``` -Get-Content [-ReadCount ] [-TotalCount ] [-Tail ] [-Path] [-Filter ] - [-Include ] [-Exclude ] [-Force] [-Credential ] [-UseTransaction] - [-Delimiter ] [-Wait] [-Raw] [-Encoding ] [-Stream ] +```powershell +Get-Content [-Path] [-ReadCount ] [-TotalCount ] + [-Tail ] [-Filter ] [-Include ] [-Exclude ] + [-Force] [-Credential ] [-UseTransaction] + [-Delimiter ] [-Wait] [-Raw] + [-Encoding ] [-Stream ] [] ``` ### LiteralPath -``` -Get-Content [-ReadCount ] [-TotalCount ] [-Tail ] -LiteralPath - [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] - [-UseTransaction] [-Delimiter ] [-Wait] [-Raw] [-Encoding ] - [-Stream ] [] +```powershell +Get-Content -LiteralPath [-ReadCount ] [-TotalCount ] + [-Tail ] [-Filter ] [-Include ] [-Exclude ] + [-Force] [-Credential ] [-UseTransaction] + [-Delimiter ] [-Wait] [-Raw] + [-Encoding ] [-Stream ] + [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Management/Get-Content.md b/reference/5.1/Microsoft.PowerShell.Management/Get-Content.md index 2e35c6b18336..3c363fae179e 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Get-Content.md @@ -16,19 +16,23 @@ Gets the content of the item at the specified location. ## SYNTAX ### Path (Default) -``` -Get-Content [-ReadCount ] [-TotalCount ] [-Tail ] [-Path] [-Filter ] - [-Include ] [-Exclude ] [-Force] [-Credential ] [-UseTransaction] - [-Delimiter ] [-Wait] [-Raw] [-Encoding ] [-Stream ] +```powershell +Get-Content [-Path] [-ReadCount ] [-TotalCount ] + [-Tail ] [-Filter ] [-Include ] [-Exclude ] + [-Force] [-Credential ] [-UseTransaction] + [-Delimiter ] [-Wait] [-Raw] + [-Encoding ] [-Stream ] [] ``` ### LiteralPath -``` -Get-Content [-ReadCount ] [-TotalCount ] [-Tail ] -LiteralPath - [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] - [-UseTransaction] [-Delimiter ] [-Wait] [-Raw] [-Encoding ] - [-Stream ] [] +```powershell +Get-Content -LiteralPath [-ReadCount ] [-TotalCount ] + [-Tail ] [-Filter ] [-Include ] [-Exclude ] + [-Force] [-Credential ] [-UseTransaction] + [-Delimiter ] [-Wait] [-Raw] + [-Encoding ] [-Stream ] + [] ``` ## DESCRIPTION diff --git a/reference/6/Microsoft.PowerShell.Management/Get-Content.md b/reference/6/Microsoft.PowerShell.Management/Get-Content.md index 3d791cf66471..a1e2150bf7b4 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-Content.md @@ -16,20 +16,22 @@ Gets the content of the item at the specified location. ## SYNTAX ### Path (Default) -``` -Get-Content [-ReadCount ] [-TotalCount ] [-Tail ] [-Path] [-Filter ] - [-Include ] [-Exclude ] [-Force] [-Credential ] - [-InformationAction ] [-InformationVariable ] [-UseTransaction] - [-Delimiter ] [-Wait] [-Raw] [-Encoding ] [-Stream ] +```powershell +Get-Content [-Path] [-ReadCount ] [-TotalCount ] + [-Tail ] [-Filter ] [-Include ] [-Exclude ] + [-Force] [-Credential ] [-UseTransaction] + [-Delimiter ] [-Wait] [-Raw] + [-Encoding ] [-Stream ] [] ``` ### LiteralPath -``` -Get-Content [-ReadCount ] [-TotalCount ] [-Tail ] -LiteralPath - [-Filter ] [-Include ] [-Exclude ] [-Force] [-Credential ] - [-InformationAction ] [-InformationVariable ] [-UseTransaction] - [-Delimiter ] [-Wait] [-Raw] [-Encoding ] [-Stream ] +```powershell +Get-Content -LiteralPath [-ReadCount ] [-TotalCount ] + [-Tail ] [-Filter ] [-Include ] [-Exclude ] + [-Force] [-Credential ] [-UseTransaction] + [-Delimiter ] [-Wait] [-Raw] + [-Encoding ] [-Stream ] [] ``` @@ -263,37 +265,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. - -This parameter is not supported by any providers that are installed with Windows PowerShell.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. - -This parameter is not supported by any providers that are installed with Windows PowerShell.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -LiteralPath Specifies the path to an item. Unlike the *Path* parameter, the value of *LiteralPath* is used exactly as it is typed. @@ -324,7 +295,7 @@ Parameter Sets: Path Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False From 2dffaffcd703baebde205c6a08e2b4a222552205 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Sat, 16 Dec 2017 02:00:55 +0900 Subject: [PATCH 114/188] Fix parameter's position in Get-Member.md (#1958) --- .../Get-Member.md | 9 +-- .../Get-Member.md | 9 +-- .../Get-Member.md | 7 ++- .../Get-Member.md | 7 ++- .../Get-Member.md | 57 ++----------------- 5 files changed, 23 insertions(+), 66 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Get-Member.md b/reference/3.0/Microsoft.PowerShell.Utility/Get-Member.md index 954078f45989..d364f15c5e28 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Get-Member.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Get-Member.md @@ -13,9 +13,10 @@ title: Get-Member Gets the properties and methods of objects. ## SYNTAX -``` -Get-Member [-InputObject ] [[-Name] ] [-MemberType ] - [-View ] [-Static] [-Force] [] +```powershell +Get-Member [[-Name] ] [-InputObject ] + [-MemberType ] [-View ] [-Static] [-Force] + [] ``` ## DESCRIPTION @@ -332,7 +333,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Get-Member.md b/reference/4.0/Microsoft.PowerShell.Utility/Get-Member.md index 48eb34b9689e..03013d53f605 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Get-Member.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Get-Member.md @@ -15,9 +15,10 @@ Gets the properties and methods of objects. ## SYNTAX -``` -Get-Member [-InputObject ] [[-Name] ] [-MemberType ] - [-View ] [-Static] [-Force] [] +```powershell +Get-Member [[-Name] ] [-InputObject ] + [-MemberType ] [-View ] [-Static] [-Force] + [] ``` ## DESCRIPTION @@ -342,7 +343,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Get-Member.md b/reference/5.0/Microsoft.PowerShell.Utility/Get-Member.md index 420debf1684a..fc77c370bcb4 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Get-Member.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Get-Member.md @@ -15,9 +15,10 @@ Gets the properties and methods of objects. ## SYNTAX -``` -Get-Member [-InputObject ] [[-Name] ] [-MemberType ] - [-View ] [-Static] [-Force] [] +```powershell +Get-Member [[-Name] ] [-InputObject ] + [-MemberType ] [-View ] [-Static] [-Force] + [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Get-Member.md b/reference/5.1/Microsoft.PowerShell.Utility/Get-Member.md index d2e853f4466e..04e3bdb0df2b 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Get-Member.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Get-Member.md @@ -15,9 +15,10 @@ Gets the properties and methods of objects. ## SYNTAX -``` -Get-Member [-InputObject ] [[-Name] ] [-MemberType ] - [-View ] [-Static] [-Force] [] +```powershell +Get-Member [[-Name] ] [-InputObject ] + [-MemberType ] [-View ] [-Static] [-Force] + [] ``` ## DESCRIPTION diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-Member.md b/reference/6/Microsoft.PowerShell.Utility/Get-Member.md index 81731190de48..04e3bdb0df2b 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-Member.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-Member.md @@ -15,10 +15,10 @@ Gets the properties and methods of objects. ## SYNTAX -``` -Get-Member [-InputObject ] [[-Name] ] [-MemberType ] - [-View ] [-Static] [-Force] [-InformationAction ] - [-InformationVariable ] [] +```powershell +Get-Member [[-Name] ] [-InputObject ] + [-MemberType ] [-View ] [-Static] [-Force] + [] ``` ## DESCRIPTION @@ -267,53 +267,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -The following list describes the properties that are added when you use the Force parameter: - --- PSBase: The original properties of the .NET Framework object without extension or adaptation. These are the properties defined for the object class and listed in MSDN. - --- PSAdapted: The properties and methods defined in the Windows PowerShell extended type system. - --- PSExtended: The properties and methods that were added in the Types.ps1xml files or by using the Add-Member cmdlet. - --- PSObject: The adapter that converts the base object to a Windows PowerShell PSObject object. - --- PSTypeNames: A list of object types that describe the object, in order of specificity. When formatting the object, Windows PowerShell searches for the types in the Format.ps1xml files in the Windows PowerShell installation directory ($pshome). It uses the formatting definition for the first type that it finds.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -The following list describes the properties that are added when you use the Force parameter: - --- PSBase: The original properties of the .NET Framework object without extension or adaptation. These are the properties defined for the object class and listed in MSDN. - --- PSAdapted: The properties and methods defined in the Windows PowerShell extended type system. - --- PSExtended: The properties and methods that were added in the Types.ps1xml files or by using the Add-Member cmdlet. - --- PSObject: The adapter that converts the base object to a Windows PowerShell PSObject object. - --- PSTypeNames: A list of object types that describe the object, in order of specificity. When formatting the object, Windows PowerShell searches for the types in the Format.ps1xml files in the Windows PowerShell installation directory ($pshome). It uses the formatting definition for the first type that it finds.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -InputObject Specifies the object whose members are retrieved. @@ -393,7 +346,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False From fa5064be89bdfd036ebcdc53ef9e9a6b418423f5 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Sat, 16 Dec 2017 02:02:30 +0900 Subject: [PATCH 115/188] Update PSGallery "Items Tab" (for the new prerelease feature) (#1957) --- gallery/psgallery/psgallery_items_tab.md | 64 ++++++++++++++---------- 1 file changed, 37 insertions(+), 27 deletions(-) diff --git a/gallery/psgallery/psgallery_items_tab.md b/gallery/psgallery/psgallery_items_tab.md index 427fd211948d..e72a6326ef7d 100644 --- a/gallery/psgallery/psgallery_items_tab.md +++ b/gallery/psgallery/psgallery_items_tab.md @@ -6,40 +6,50 @@ keywords: gallery,powershell,cmdlet,psgallery title: psgallery_items_tab --- -Items Tab -========== +# Items Tab -The Items Tab displays all available items in the PowerShell Gallery. - -To see only Modules in the PowerShell Gallery, click Modules in the Items Tab drop down. Similarly, to see only Scripts in the PowerShell Gallery, click Scripts in the Items Tab drop down. +The [Items tab](https://www.powershellgallery.com/items) displays all available items in the PowerShell Gallery. +There are several ways to filter, sort, and search the items. To see more details about a particular item, click the item. -There are several ways to sort the items: +## Filter By + +The drop-down under "Filter By" allows users to filter the results by: +* Include Prerelease +* Stable Only + +For information about "Prerelease" and "Stable", see [Prerelease Versioning Added to PowerShellGet and PowerShell Gallery](https://blogs.msdn.microsoft.com/powershell/2017/12/05/prerelease-versioning-added-to-powershellget-and-powershell-gallery/) in the PowerShell Team Blog. + +The checkboxes under the drop-down allow users to filter the results by: +* Item Types + - Module + - Script +* Categories + - Cmdlet + - DSC Resource + - Function + - Role Capability + - Workflow -##Filter By## -The Filter By section allows users to filter the results by: -* Item Type: - * Modules - * Scripts -* Category: - * Cmdlet - * DSC Resource - * Function - * Workflow +To see only modules in the PowerShell Gallery, check Module in the Item Types. +Similarly, to see only scripts in the PowerShell Gallery, check Script in the Item Types. -Note: Filters are inclusive. -Example: An item containing both Cmdlets and Functions will appear if either Cmdlet or Function (or both) are checked. If neither are selected, the item will not appear. -Similarly, if all categories are selected, only items containing one of those categories will appear. **Items that do not belong to any of those categories will not appear.** +> [!NOTE] +> Filters are inclusive. +> Example: An item containing both cmdlets and functions will appear if either Cmdlet or Function (or both) are checked. +> If neither are selected, the item will not appear. +> Similarly, if all categories are selected, only items containing one of those categories will appear. +> **Items that do not belong to any of those categories will not appear.** -##Sort By## -The Sort By drop down allows users to sort the results by: -* Popularity - Popularity is determined by Download Count. -* A-Z - Alphabetically by item name. -* Recent - Items appear in order of publish date. +## Sort By +The Sort By drop-down allows users to sort the results by: +* Popularity - Popularity is determined by Download Count +* A-Z - Alphabetically by item name +* Recent - Items appear in order of publish date -##Search Box## -The Search Box allows users to search the items on keywords. -See [Search Syntax](./psgallery_search_syntax.md) for more details. +## Search Box +The Search Box allows users to search the items on keywords. +For more information, see [Gallery Search Syntax](psgallery_search_syntax.md). From 8190bfc1d01341ea866cd661db16955324a9ef58 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Tue, 19 Dec 2017 00:28:21 +0900 Subject: [PATCH 116/188] Fix link for about_WorkflowCommonParameters in New-PSWorkflowExecutionOption.md (#1962) --- reference/3.0/PSWorkflow/New-PSWorkflowExecutionOption.md | 2 +- reference/4.0/PSWorkflow/New-PSWorkflowExecutionOption.md | 2 +- reference/5.0/PSWorkflow/New-PSWorkflowExecutionOption.md | 2 +- reference/5.1/PSWorkflow/New-PSWorkflowExecutionOption.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/reference/3.0/PSWorkflow/New-PSWorkflowExecutionOption.md b/reference/3.0/PSWorkflow/New-PSWorkflowExecutionOption.md index 32ef132f0e59..a2303245b219 100644 --- a/reference/3.0/PSWorkflow/New-PSWorkflowExecutionOption.md +++ b/reference/3.0/PSWorkflow/New-PSWorkflowExecutionOption.md @@ -34,7 +34,7 @@ If you omit a parameter, the cmdlet creates the object with a default value for The **New-PSWorkflowExecutionOption** cmdlet is part of the Windows PowerShell Workflow feature. You can also add workflow common parameters to this command. -For more information about workflow common parameters, see about_WorkflowCommonParametershttp://technet.microsoft.com/library/jj129719(v=wps.620).aspx. +For more information about workflow common parameters, see [about_WorkflowCommonParameters](About/about_WorkflowCommonParameters.md). This cmdlet is introduced in Windows PowerShell 3.0. ## EXAMPLES diff --git a/reference/4.0/PSWorkflow/New-PSWorkflowExecutionOption.md b/reference/4.0/PSWorkflow/New-PSWorkflowExecutionOption.md index 5af451b1aa8d..aed6220891ee 100644 --- a/reference/4.0/PSWorkflow/New-PSWorkflowExecutionOption.md +++ b/reference/4.0/PSWorkflow/New-PSWorkflowExecutionOption.md @@ -36,7 +36,7 @@ If you omit a parameter, the cmdlet creates the object with a default value for The **New-PSWorkflowExecutionOption** cmdlet is part of the Windows PowerShell Workflow feature. You can also add workflow common parameters to this command. -For more information about workflow common parameters, see about_WorkflowCommonParametershttp://technet.microsoft.com/library/jj129719(v=wps.630).aspx. +For more information about workflow common parameters, see [about_WorkflowCommonParameters](About/about_WorkflowCommonParameters.md). This cmdlet is introduced in Windows PowerShell 3.0. diff --git a/reference/5.0/PSWorkflow/New-PSWorkflowExecutionOption.md b/reference/5.0/PSWorkflow/New-PSWorkflowExecutionOption.md index 706681305c09..8ac686ea2fa5 100644 --- a/reference/5.0/PSWorkflow/New-PSWorkflowExecutionOption.md +++ b/reference/5.0/PSWorkflow/New-PSWorkflowExecutionOption.md @@ -36,7 +36,7 @@ If you do not specify a parameter, the cmdlet creates the object that has a defa The **New-PSWorkflowExecutionOption** cmdlet is part of the Windows PowerShell Workflow feature. You can also add workflow common parameters to this command. -For more information about workflow common parameters, see about_WorkflowCommonParameters. +For more information about workflow common parameters, see [about_WorkflowCommonParameters](About/about_WorkflowCommonParameters.md). This cmdlet was introduced in Windows PowerShell 3.0. diff --git a/reference/5.1/PSWorkflow/New-PSWorkflowExecutionOption.md b/reference/5.1/PSWorkflow/New-PSWorkflowExecutionOption.md index f05b67d76beb..121ff390a00a 100644 --- a/reference/5.1/PSWorkflow/New-PSWorkflowExecutionOption.md +++ b/reference/5.1/PSWorkflow/New-PSWorkflowExecutionOption.md @@ -36,7 +36,7 @@ If you do not specify a parameter, the cmdlet creates the object that has a defa The **New-PSWorkflowExecutionOption** cmdlet is part of the Windows PowerShell Workflow feature. You can also add workflow common parameters to this command. -For more information about workflow common parameters, see about_WorkflowCommonParameters. +For more information about workflow common parameters, see [about_WorkflowCommonParameters](About/about_WorkflowCommonParameters.md). This cmdlet was introduced in Windows PowerShell 3.0. From 9cfd38ab5f72a7fdffd98216ed211a6df6308925 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Tue, 19 Dec 2017 00:29:05 +0900 Subject: [PATCH 117/188] Fix link for about_Types.ps1xml in Update-TypeData.md (#1961) --- reference/3.0/Microsoft.PowerShell.Utility/Update-TypeData.md | 3 ++- reference/4.0/Microsoft.PowerShell.Utility/Update-TypeData.md | 2 +- reference/5.0/Microsoft.PowerShell.Utility/Update-TypeData.md | 2 +- reference/5.1/Microsoft.PowerShell.Utility/Update-TypeData.md | 2 +- reference/6/Microsoft.PowerShell.Utility/Update-TypeData.md | 2 +- 5 files changed, 6 insertions(+), 5 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Update-TypeData.md b/reference/3.0/Microsoft.PowerShell.Utility/Update-TypeData.md index 844cffefac78..c1ecd88f89ad 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Update-TypeData.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Update-TypeData.md @@ -59,7 +59,8 @@ If you are getting .NET Framework properties, you can work around the suppressio Note that method syntax can only be used with .NET Framework properties. Properties that are added by running the Update-TypeData cmdlet cannot use method syntax. -For more information about the *types.ps1xml files in Windows PowerShell, see about_Types.ps1xml (http://go.microsoft.com/fwlink/?LinkID=113274). +For more information about the *types.ps1xml files in PowerShell, see [about_Types.ps1xml](../Microsoft.PowerShell.Core/About/about_Types.ps1xml.md). + ## EXAMPLES ### Example 1 diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Update-TypeData.md b/reference/4.0/Microsoft.PowerShell.Utility/Update-TypeData.md index 2feec400b9c5..04dc761b9bd0 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Update-TypeData.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Update-TypeData.md @@ -61,7 +61,7 @@ If you are getting .NET Framework properties, you can work around the suppressio Note that method syntax can only be used with .NET Framework properties. Properties that are added by running the Update-TypeData cmdlet cannot use method syntax. -For more information about the *types.ps1xml files in Windows PowerShell, see about_Types.ps1xml (..\Microsoft.PowerShell.Core\About\about_Types.ps1xml.md). +For more information about the *types.ps1xml files in PowerShell, see [about_Types.ps1xml](../Microsoft.PowerShell.Core/About/about_Types.ps1xml.md). ## EXAMPLES diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Update-TypeData.md b/reference/5.0/Microsoft.PowerShell.Utility/Update-TypeData.md index b9277d09b46b..0e3c0ac548db 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Update-TypeData.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Update-TypeData.md @@ -61,7 +61,7 @@ If you are getting .NET Framework properties, you can work around the suppressio Note that method syntax can only be used with .NET Framework properties. Properties that are added by running the **Update-TypeData** cmdlet cannot use method syntax. -For more information about the *types.ps1xml files in Windows PowerShell, see about_Types.ps1xml (..\Microsoft.PowerShell.Core\About\about_Types.ps1xml.md). +For more information about the *types.ps1xml files in PowerShell, see [about_Types.ps1xml](../Microsoft.PowerShell.Core/About/about_Types.ps1xml.md). ## EXAMPLES diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Update-TypeData.md b/reference/5.1/Microsoft.PowerShell.Utility/Update-TypeData.md index b9277d09b46b..0e3c0ac548db 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Update-TypeData.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Update-TypeData.md @@ -61,7 +61,7 @@ If you are getting .NET Framework properties, you can work around the suppressio Note that method syntax can only be used with .NET Framework properties. Properties that are added by running the **Update-TypeData** cmdlet cannot use method syntax. -For more information about the *types.ps1xml files in Windows PowerShell, see about_Types.ps1xml (..\Microsoft.PowerShell.Core\About\about_Types.ps1xml.md). +For more information about the *types.ps1xml files in PowerShell, see [about_Types.ps1xml](../Microsoft.PowerShell.Core/About/about_Types.ps1xml.md). ## EXAMPLES diff --git a/reference/6/Microsoft.PowerShell.Utility/Update-TypeData.md b/reference/6/Microsoft.PowerShell.Utility/Update-TypeData.md index da6b69eeec7e..745f56fea75a 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Update-TypeData.md +++ b/reference/6/Microsoft.PowerShell.Utility/Update-TypeData.md @@ -64,7 +64,7 @@ If you are getting .NET Framework properties, you can work around the suppressio Note that method syntax can only be used with .NET Framework properties. Properties that are added by running the **Update-TypeData** cmdlet cannot use method syntax. -For more information about the *types.ps1xml files in Windows PowerShell, see about_Types.ps1xml (..\Microsoft.PowerShell.Core\About\about_Types.ps1xml.md). +For more information about the *types.ps1xml files in PowerShell, see [about_Types.ps1xml](../Microsoft.PowerShell.Core/About/about_Types.ps1xml.md). ## EXAMPLES From 219e848e8e2582eba9d505d409e43d706a017689 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Wed, 20 Dec 2017 03:31:21 +0900 Subject: [PATCH 118/188] Fix parameter's position in Group-Object.md (#1966) --- .../Group-Object.md | 8 +++-- .../Group-Object.md | 7 ++-- .../Group-Object.md | 5 +-- .../Group-Object.md | 5 +-- .../Group-Object.md | 33 ++----------------- 5 files changed, 18 insertions(+), 40 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md b/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md index 21ab7f95fcd4..a9b3bf78c886 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Group-Object.md @@ -11,11 +11,13 @@ title: Group-Object # Group-Object ## SYNOPSIS Groups objects that contain the same value for specified properties. + ## SYNTAX ``` -Group-Object [-NoElement] [-AsHashTable] [-AsString] [-InputObject ] [[-Property] ] - [-Culture ] [-CaseSensitive] [] +Group-Object [[-Property] ] [-NoElement] [-AsHashTable] [-AsString] + [-InputObject ] [-Culture ] [-CaseSensitive] + [] ``` ## DESCRIPTION @@ -325,7 +327,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Group-Object.md b/reference/4.0/Microsoft.PowerShell.Utility/Group-Object.md index d504fce222a0..e5225ee55e0e 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Group-Object.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Group-Object.md @@ -16,8 +16,9 @@ Groups objects that contain the same value for specified properties. ## SYNTAX ``` -Group-Object [-NoElement] [-AsHashTable] [-AsString] [-InputObject ] [[-Property] ] - [-Culture ] [-CaseSensitive] [] +Group-Object [[-Property] ] [-NoElement] [-AsHashTable] [-AsString] + [-InputObject ] [-Culture ] [-CaseSensitive] + [] ``` ## DESCRIPTION @@ -337,7 +338,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Group-Object.md b/reference/5.0/Microsoft.PowerShell.Utility/Group-Object.md index 1dc7b6a684c2..a3bde2c8b12c 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Group-Object.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Group-Object.md @@ -16,8 +16,9 @@ Groups objects that contain the same value for specified properties. ## SYNTAX ``` -Group-Object [-NoElement] [-AsHashTable] [-AsString] [-InputObject ] [[-Property] ] - [-Culture ] [-CaseSensitive] [] +Group-Object [[-Property] ] [-NoElement] [-AsHashTable] [-AsString] + [-InputObject ] [-Culture ] [-CaseSensitive] + [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Group-Object.md b/reference/5.1/Microsoft.PowerShell.Utility/Group-Object.md index 454e3d84d85b..70a564b10018 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Group-Object.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Group-Object.md @@ -16,8 +16,9 @@ Groups objects that contain the same value for specified properties. ## SYNTAX ``` -Group-Object [-NoElement] [-AsHashTable] [-AsString] [-InputObject ] [[-Property] ] - [-Culture ] [-CaseSensitive] [] +Group-Object [[-Property] ] [-NoElement] [-AsHashTable] [-AsString] + [-InputObject ] [-Culture ] [-CaseSensitive] + [] ``` ## DESCRIPTION diff --git a/reference/6/Microsoft.PowerShell.Utility/Group-Object.md b/reference/6/Microsoft.PowerShell.Utility/Group-Object.md index 9f93095351f9..70a564b10018 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Group-Object.md +++ b/reference/6/Microsoft.PowerShell.Utility/Group-Object.md @@ -16,8 +16,8 @@ Groups objects that contain the same value for specified properties. ## SYNTAX ``` -Group-Object [-NoElement] [-AsHashTable] [-AsString] [-InputObject ] [[-Property] ] - [-Culture ] [-CaseSensitive] [-InformationAction ] [-InformationVariable ] +Group-Object [[-Property] ] [-NoElement] [-AsHashTable] [-AsString] + [-InputObject ] [-Culture ] [-CaseSensitive] [] ``` @@ -277,33 +277,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -By itself, the AsHashTable parameter returns each hash table in which each key is an instance of the grouped object. When used with the AsString parameter, the keys in the hash table are strings.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -By itself, the AsHashTable parameter returns each hash table in which each key is an instance of the grouped object. When used with the AsString parameter, the keys in the hash table are strings.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -InputObject Specifies the objects to group. Enter a variable that contains the objects, or type a command or expression that gets the objects. @@ -353,7 +326,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False From 91a778ceae0f4c5c2c9ca693c42fec172b8e93fa Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Wed, 20 Dec 2017 03:32:18 +0900 Subject: [PATCH 119/188] Fix hex values in about_Arithmetic_Operators.md (#1965) --- .../About/about_Arithmetic_Operators.md | 4 ++-- .../About/about_Arithmetic_Operators.md | 4 ++-- .../About/about_Arithmetic_Operators.md | 4 ++-- .../About/about_Arithmetic_Operators.md | 4 ++-- .../About/about_Arithmetic_Operators.md | 4 ++-- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index a08a495cb977..e43e89a58ad6 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -501,8 +501,8 @@ right operand determine how many bits of the left operand are shifted. |`21 -shr 31` | 0 | 0000 0000 | 0x00 | |`21 -shr 32` | 21 | 0001 0101 | 0x15 | |`21 -shr 64` | 21 | 0001 0101 | 0x15 | -|`21 -shr 65` | 10 | 0000 1010 | 0x15 | -|`21 -shr 66` | 5 | 0000 0101 | 0x15 | +|`21 -shr 65` | 10 | 0000 1010 | 0x0A | +|`21 -shr 66` | 5 | 0000 0101 | 0x05 | |`[int]::MaxValue -shr 1`| 1073741823 | | 0x3FFFFFFF | |`[int]::MinValue -shr 1`| -1073741824| | 0xC0000000 | |`-1 -shr 1` | -1 | | 0xFFFFFFFF | diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index a08a495cb977..e43e89a58ad6 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -501,8 +501,8 @@ right operand determine how many bits of the left operand are shifted. |`21 -shr 31` | 0 | 0000 0000 | 0x00 | |`21 -shr 32` | 21 | 0001 0101 | 0x15 | |`21 -shr 64` | 21 | 0001 0101 | 0x15 | -|`21 -shr 65` | 10 | 0000 1010 | 0x15 | -|`21 -shr 66` | 5 | 0000 0101 | 0x15 | +|`21 -shr 65` | 10 | 0000 1010 | 0x0A | +|`21 -shr 66` | 5 | 0000 0101 | 0x05 | |`[int]::MaxValue -shr 1`| 1073741823 | | 0x3FFFFFFF | |`[int]::MinValue -shr 1`| -1073741824| | 0xC0000000 | |`-1 -shr 1` | -1 | | 0xFFFFFFFF | diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index a08a495cb977..e43e89a58ad6 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -501,8 +501,8 @@ right operand determine how many bits of the left operand are shifted. |`21 -shr 31` | 0 | 0000 0000 | 0x00 | |`21 -shr 32` | 21 | 0001 0101 | 0x15 | |`21 -shr 64` | 21 | 0001 0101 | 0x15 | -|`21 -shr 65` | 10 | 0000 1010 | 0x15 | -|`21 -shr 66` | 5 | 0000 0101 | 0x15 | +|`21 -shr 65` | 10 | 0000 1010 | 0x0A | +|`21 -shr 66` | 5 | 0000 0101 | 0x05 | |`[int]::MaxValue -shr 1`| 1073741823 | | 0x3FFFFFFF | |`[int]::MinValue -shr 1`| -1073741824| | 0xC0000000 | |`-1 -shr 1` | -1 | | 0xFFFFFFFF | diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index a08a495cb977..e43e89a58ad6 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -501,8 +501,8 @@ right operand determine how many bits of the left operand are shifted. |`21 -shr 31` | 0 | 0000 0000 | 0x00 | |`21 -shr 32` | 21 | 0001 0101 | 0x15 | |`21 -shr 64` | 21 | 0001 0101 | 0x15 | -|`21 -shr 65` | 10 | 0000 1010 | 0x15 | -|`21 -shr 66` | 5 | 0000 0101 | 0x15 | +|`21 -shr 65` | 10 | 0000 1010 | 0x0A | +|`21 -shr 66` | 5 | 0000 0101 | 0x05 | |`[int]::MaxValue -shr 1`| 1073741823 | | 0x3FFFFFFF | |`[int]::MinValue -shr 1`| -1073741824| | 0xC0000000 | |`-1 -shr 1` | -1 | | 0xFFFFFFFF | diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md b/reference/6/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md index a08a495cb977..e43e89a58ad6 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Arithmetic_Operators.md @@ -501,8 +501,8 @@ right operand determine how many bits of the left operand are shifted. |`21 -shr 31` | 0 | 0000 0000 | 0x00 | |`21 -shr 32` | 21 | 0001 0101 | 0x15 | |`21 -shr 64` | 21 | 0001 0101 | 0x15 | -|`21 -shr 65` | 10 | 0000 1010 | 0x15 | -|`21 -shr 66` | 5 | 0000 0101 | 0x15 | +|`21 -shr 65` | 10 | 0000 1010 | 0x0A | +|`21 -shr 66` | 5 | 0000 0101 | 0x05 | |`[int]::MaxValue -shr 1`| 1073741823 | | 0x3FFFFFFF | |`[int]::MinValue -shr 1`| -1073741824| | 0xC0000000 | |`-1 -shr 1` | -1 | | 0xFFFFFFFF | From 7569a34aa0fcde47211465335563f0f02bf14a52 Mon Sep 17 00:00:00 2001 From: Taylor Mansfield Date: Tue, 19 Dec 2017 13:01:11 -0800 Subject: [PATCH 120/188] Indent headers as subheaders (#1967) --- reference/docs-conceptual/setup/PS-remoting-second-hop.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/docs-conceptual/setup/PS-remoting-second-hop.md b/reference/docs-conceptual/setup/PS-remoting-second-hop.md index c790cd80dc1f..937b7e20e5a8 100644 --- a/reference/docs-conceptual/setup/PS-remoting-second-hop.md +++ b/reference/docs-conceptual/setup/PS-remoting-second-hop.md @@ -271,12 +271,12 @@ You can pass credentials inside the **ScriptBlock** parameter of a call to the - Does not require special server configuration. - Works on any server running WMF 2.0 or later. -## Cons +### Cons - Requires an awkward code technique. - If running WMF 2.0, requires different syntax for passing arguments to a remote session. -## Example +### Example The following example shows how to pass credentials in an **Invoke-Command** script block: From a6c39a2411a254516b37e6be61d40bb3832d35e4 Mon Sep 17 00:00:00 2001 From: DannyMeister Date: Tue, 19 Dec 2017 17:03:33 -0600 Subject: [PATCH 121/188] Update minor typo in Limit-EventLog.md (#1968) --- reference/5.1/Microsoft.PowerShell.Management/Limit-EventLog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Limit-EventLog.md b/reference/5.1/Microsoft.PowerShell.Management/Limit-EventLog.md index 4a7f9c81226b..e91d68026643 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Limit-EventLog.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Limit-EventLog.md @@ -208,7 +208,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS ### None -You cannot pip input to this cmdlet. +You cannot pipe input to this cmdlet. ## OUTPUTS From 4dfa90f973d0ed8887e9268e98b268bfc173a7c9 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Thu, 21 Dec 2017 00:27:39 +0900 Subject: [PATCH 122/188] Update Example 3 in Get-FileHash.md (#1969) --- .../Get-FileHash.md | 64 +++++++++---------- .../Get-FileHash.md | 64 +++++++++---------- .../Get-FileHash.md | 64 +++++++++---------- .../Get-FileHash.md | 57 ++++++++--------- 4 files changed, 121 insertions(+), 128 deletions(-) diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Get-FileHash.md b/reference/4.0/Microsoft.PowerShell.Utility/Get-FileHash.md index 63d52939a386..76ec8806cbff 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Get-FileHash.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Get-FileHash.md @@ -75,46 +75,44 @@ The output is piped to the Format-List cmdlet to format the output as a list. ### Example 3: Compute the hash value of a stream and compare the procedure with getting the hash from the file directly ```powershell -PS C:> $testfile = "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" - -## open $testfile as a stream -$testfilestream = [System.IO.File]::Open( - $testfile, - [System.IO.FileMode]::Open, - [System.IO.FileAccess]::Read) - -$hashFromStream = Get-FileHash -InputStream $testfilestream -Algorithm MD5 - -$testfilestream.Close() - -$hashFromFile = Get-FileHash -Path $testfile -Algorithm MD5 - -## check both hashes are the same -if(($hashFromStream.Hash) -ne ($hashFromFile.Hash)) { - Write-Error "Get-FileHash results are inconsistent!!" -} -else { - Write-Output "Results from File:" - Write-Output "==================" - $hashFromFile | Format-List - Write-Output " " - Write-Output "Results from Stream:" - Write-Output "====================" - $hashFromStream | Format-List +# Path of Microsoft.PowerShell.Utility.psd1 +$file = (Get-Module Microsoft.PowerShell.Utility).Path + +$hashFromFile = Get-FileHash -Path $file -Algorithm MD5 + +# Open $file as a stream +$stream = [System.IO.File]::OpenRead($file) +$hashFromStream = Get-FileHash -InputStream $stream -Algorithm MD5 +$stream.Close() + +Write-Host '### Hash from File ###' -NoNewline +$hashFromFile | Format-List +Write-Host '### Hash from Stream ###' -NoNewline +$hashFromStream | Format-List + +# Check both hashes are the same +if ($hashFromFile.Hash -eq $hashFromStream.Hash) { + Write-Host 'Get-FileHash results are consistent' -ForegroundColor Green +} else { + Write-Host 'Get-FileHash results are inconsistent!!' -ForegroundColor Red } +``` +```output +### Hash from File ### -Results from File: -================== Algorithm : MD5 -Hash : 097CE5761C89434367598B34FE32893B -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Hash : 593D6592BD9B7F9174711AB136F5E751 +Path : C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\Microsoft.Powe + rShell.Utility\Microsoft.PowerShell.Utility.psd1 + +### Hash from Stream ### -Results from Stream: -==================== Algorithm : MD5 -Hash : 097CE5761C89434367598B34FE32893B +Hash : 593D6592BD9B7F9174711AB136F5E751 Path : + +Get-FileHash results are consistent ``` ## PARAMETERS diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Get-FileHash.md b/reference/5.0/Microsoft.PowerShell.Utility/Get-FileHash.md index 0dd967722ecb..8723a9cab1dd 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Get-FileHash.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Get-FileHash.md @@ -74,46 +74,44 @@ The output is piped to the Format-List cmdlet to format the output as a list. ### Example 3: Compute the hash value of a stream and compare the procedure with getting the hash from the file directly ```powershell -PS C:\> $testfile = "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" - -## open $testfile as a stream -$testfilestream = [System.IO.File]::Open( - $testfile, - [System.IO.FileMode]::Open, - [System.IO.FileAccess]::Read) - -$hashFromStream = Get-FileHash -InputStream $testfilestream -Algorithm MD5 - -$testfilestream.Close() - -$hashFromFile = Get-FileHash -Path $testfile -Algorithm MD5 - -## check both hashes are the same -if(($hashFromStream.Hash) -ne ($hashFromFile.Hash)) { - Write-Error "Get-FileHash results are inconsistent!!" -} -else { - Write-Output "Results from File:" - Write-Output "==================" - $hashFromFile | Format-List - Write-Output " " - Write-Output "Results from Stream:" - Write-Output "====================" - $hashFromStream | Format-List +# Path of Microsoft.PowerShell.Utility.psd1 +$file = (Get-Module Microsoft.PowerShell.Utility).Path + +$hashFromFile = Get-FileHash -Path $file -Algorithm MD5 + +# Open $file as a stream +$stream = [System.IO.File]::OpenRead($file) +$hashFromStream = Get-FileHash -InputStream $stream -Algorithm MD5 +$stream.Close() + +Write-Host '### Hash from File ###' -NoNewline +$hashFromFile | Format-List +Write-Host '### Hash from Stream ###' -NoNewline +$hashFromStream | Format-List + +# Check both hashes are the same +if ($hashFromFile.Hash -eq $hashFromStream.Hash) { + Write-Host 'Get-FileHash results are consistent' -ForegroundColor Green +} else { + Write-Host 'Get-FileHash results are inconsistent!!' -ForegroundColor Red } +``` +```output +### Hash from File ### -Results from File: -================== Algorithm : MD5 -Hash : 097CE5761C89434367598B34FE32893B -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Hash : 593D6592BD9B7F9174711AB136F5E751 +Path : C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\Microsoft.Powe + rShell.Utility\Microsoft.PowerShell.Utility.psd1 + +### Hash from Stream ### -Results from Stream: -==================== Algorithm : MD5 -Hash : 097CE5761C89434367598B34FE32893B +Hash : 593D6592BD9B7F9174711AB136F5E751 Path : + +Get-FileHash results are consistent ``` ## PARAMETERS diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Get-FileHash.md b/reference/5.1/Microsoft.PowerShell.Utility/Get-FileHash.md index adc69dc47b80..963bd48fb96a 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Get-FileHash.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Get-FileHash.md @@ -74,46 +74,44 @@ The output is piped to the Format-List cmdlet to format the output as a list. ### Example 3: Compute the hash value of a stream and compare the procedure with getting the hash from the file directly ```powershell -PS C:\> $testfile = "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" - -## open $testfile as a stream -$testfilestream = [System.IO.File]::Open( - $testfile, - [System.IO.FileMode]::Open, - [System.IO.FileAccess]::Read) - -$hashFromStream = Get-FileHash -InputStream $testfilestream -Algorithm MD5 - -$testfilestream.Close() - -$hashFromFile = Get-FileHash -Path $testfile -Algorithm MD5 - -## check both hashes are the same -if(($hashFromStream.Hash) -ne ($hashFromFile.Hash)) { - Write-Error "Get-FileHash results are inconsistent!!" -} -else { - Write-Output "Results from File:" - Write-Output "==================" - $hashFromFile | Format-List - Write-Output " " - Write-Output "Results from Stream:" - Write-Output "====================" - $hashFromStream | Format-List +# Path of Microsoft.PowerShell.Utility.psd1 +$file = (Get-Module Microsoft.PowerShell.Utility).Path + +$hashFromFile = Get-FileHash -Path $file -Algorithm MD5 + +# Open $file as a stream +$stream = [System.IO.File]::OpenRead($file) +$hashFromStream = Get-FileHash -InputStream $stream -Algorithm MD5 +$stream.Close() + +Write-Host '### Hash from File ###' -NoNewline +$hashFromFile | Format-List +Write-Host '### Hash from Stream ###' -NoNewline +$hashFromStream | Format-List + +# Check both hashes are the same +if ($hashFromFile.Hash -eq $hashFromStream.Hash) { + Write-Host 'Get-FileHash results are consistent' -ForegroundColor Green +} else { + Write-Host 'Get-FileHash results are inconsistent!!' -ForegroundColor Red } +``` +```output +### Hash from File ### -Results from File: -================== Algorithm : MD5 -Hash : 097CE5761C89434367598B34FE32893B -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Hash : 593D6592BD9B7F9174711AB136F5E751 +Path : C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\Microsoft.Powe + rShell.Utility\Microsoft.PowerShell.Utility.psd1 + +### Hash from Stream ### -Results from Stream: -==================== Algorithm : MD5 -Hash : 097CE5761C89434367598B34FE32893B +Hash : 593D6592BD9B7F9174711AB136F5E751 Path : + +Get-FileHash results are consistent ``` ## PARAMETERS diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-FileHash.md b/reference/6/Microsoft.PowerShell.Utility/Get-FileHash.md index 4abb81aaa9f7..86bdfc3cdcc2 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-FileHash.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-FileHash.md @@ -72,47 +72,46 @@ This command uses the **Get-FileHash** cmdlet and the SHA384 algorithm to comput The output is piped to the Format-List cmdlet to format the output as a list. ### Example 3: Compute the hash value of a stream and compare the procedure with getting the hash from the file directly -``` -PS C:\> $testfile = "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" -## open $testfile as a stream -$testfilestream = [System.IO.File]::Open( - $testfile, - [System.IO.FileMode]::Open, - [System.IO.FileAccess]::Read) +```powershell +# Path of Microsoft.PowerShell.Utility.psd1 +$file = (Get-Module Microsoft.PowerShell.Utility).Path -$hashFromStream = Get-FileHash -InputStream $testfilestream -Algorithm MD5 +$hashFromFile = Get-FileHash -Path $file -Algorithm MD5 -$testfilestream.Close() +# Open $file as a stream +$stream = [System.IO.File]::OpenRead($file) +$hashFromStream = Get-FileHash -InputStream $stream -Algorithm MD5 +$stream.Close() -$hashFromFile = Get-FileHash -Path $testfile -Algorithm MD5 +Write-Host '### Hash from File ###' -NoNewline +$hashFromFile | Format-List +Write-Host '### Hash from Stream ###' -NoNewline +$hashFromStream | Format-List -## check both hashes are the same -if(($hashFromStream.Hash) -ne ($hashFromFile.Hash)) { - Write-Error "Get-FileHash results are inconsistent!!" -} -else { - Write-Output "Results from File:" - Write-Output "==================" - $hashFromFile | Format-List - Write-Output " " - Write-Output "Results from Stream:" - Write-Output "====================" - $hashFromStream | Format-List +# Check both hashes are the same +if ($hashFromFile.Hash -eq $hashFromStream.Hash) { + Write-Host 'Get-FileHash results are consistent' -ForegroundColor Green +} else { + Write-Host 'Get-FileHash results are inconsistent!!' -ForegroundColor Red } +``` +```output +### Hash from File ### -Results from File: -================== Algorithm : MD5 -Hash : 097CE5761C89434367598B34FE32893B -Path : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe +Hash : 593D6592BD9B7F9174711AB136F5E751 +Path : C:\Program Files\PowerShell\6.0.0\Modules\Microsoft.Powe + rShell.Utility\Microsoft.PowerShell.Utility.psd1 + +### Hash from Stream ### -Results from Stream: -==================== Algorithm : MD5 -Hash : 097CE5761C89434367598B34FE32893B +Hash : 593D6592BD9B7F9174711AB136F5E751 Path : + +Get-FileHash results are consistent ``` ## PARAMETERS From 9603e0f80b4fd5edffa83f06ee9d41128c83bacc Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Thu, 21 Dec 2017 00:37:11 +0900 Subject: [PATCH 123/188] Fix parameter's position in Tee-Object.md (#1970) --- .../Tee-Object.md | 11 +++-- .../Tee-Object.md | 11 +++-- .../Tee-Object.md | 9 ++-- .../Tee-Object.md | 9 ++-- .../Tee-Object.md | 41 ++++--------------- 5 files changed, 33 insertions(+), 48 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Tee-Object.md b/reference/3.0/Microsoft.PowerShell.Utility/Tee-Object.md index b6ed18f3dece..2001579b157d 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Tee-Object.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Tee-Object.md @@ -15,17 +15,20 @@ Saves command output in a file or variable and also sends it down the pipeline. ### File (Default) ``` -Tee-Object [-InputObject ] [-FilePath] [-Append] [] +Tee-Object [-FilePath] [-InputObject ] [-Append] + [] ``` ### LiteralFile ``` -Tee-Object [-InputObject ] -LiteralPath [] +Tee-Object -LiteralPath [-InputObject ] + [] ``` ### Variable ``` -Tee-Object [-InputObject ] -Variable [] +Tee-Object -Variable [-InputObject ] + [] ``` ## DESCRIPTION @@ -103,7 +106,7 @@ Parameter Sets: File Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: True diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Tee-Object.md b/reference/4.0/Microsoft.PowerShell.Utility/Tee-Object.md index 10f7c6aa5b9e..9c8de6ab12bd 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Tee-Object.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Tee-Object.md @@ -17,17 +17,20 @@ Saves command output in a file or variable and also sends it down the pipeline. ### File (Default) ``` -Tee-Object [-InputObject ] [-FilePath] [-Append] [] +Tee-Object [-FilePath] [-InputObject ] [-Append] + [] ``` ### LiteralFile ``` -Tee-Object [-InputObject ] -LiteralPath [] +Tee-Object -LiteralPath [-InputObject ] + [] ``` ### Variable ``` -Tee-Object [-InputObject ] -Variable [] +Tee-Object -Variable [-InputObject ] + [] ``` ## DESCRIPTION @@ -109,7 +112,7 @@ Parameter Sets: File Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: True diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Tee-Object.md b/reference/5.0/Microsoft.PowerShell.Utility/Tee-Object.md index 64bd44ead3ba..772546e26984 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Tee-Object.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Tee-Object.md @@ -17,17 +17,20 @@ Saves command output in a file or variable and also sends it down the pipeline. ### File (Default) ``` -Tee-Object [-InputObject ] [-FilePath] [-Append] [] +Tee-Object [-FilePath] [-InputObject ] [-Append] + [] ``` ### LiteralFile ``` -Tee-Object [-InputObject ] -LiteralPath [] +Tee-Object -LiteralPath [-InputObject ] + [] ``` ### Variable ``` -Tee-Object [-InputObject ] -Variable [] +Tee-Object -Variable [-InputObject ] + [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Tee-Object.md b/reference/5.1/Microsoft.PowerShell.Utility/Tee-Object.md index 203ded45ea4d..423a05416065 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Tee-Object.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Tee-Object.md @@ -17,17 +17,20 @@ Saves command output in a file or variable and also sends it down the pipeline. ### File (Default) ``` -Tee-Object [-InputObject ] [-FilePath] [-Append] [] +Tee-Object [-FilePath] [-InputObject ] [-Append] + [] ``` ### LiteralFile ``` -Tee-Object [-InputObject ] -LiteralPath [] +Tee-Object -LiteralPath [-InputObject ] + [] ``` ### Variable ``` -Tee-Object [-InputObject ] -Variable [] +Tee-Object -Variable [-InputObject ] + [] ``` ## DESCRIPTION diff --git a/reference/6/Microsoft.PowerShell.Utility/Tee-Object.md b/reference/6/Microsoft.PowerShell.Utility/Tee-Object.md index fdc489c66eab..0fd469983c2f 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Tee-Object.md +++ b/reference/6/Microsoft.PowerShell.Utility/Tee-Object.md @@ -17,20 +17,20 @@ Saves command output in a file or variable and also sends it down the pipeline. ### File (Default) ``` -Tee-Object [-InputObject ] [-FilePath] [-Append] [-InformationAction ] - [-InformationVariable ] [] +Tee-Object [-FilePath] [-InputObject ] [-Append] + [] ``` ### LiteralFile ``` -Tee-Object [-InputObject ] -LiteralPath [-InformationAction ] - [-InformationVariable ] [] +Tee-Object -LiteralPath [-InputObject ] + [] ``` ### Variable ``` -Tee-Object [-InputObject ] -Variable [-InformationAction ] - [-InformationVariable ] [] +Tee-Object -Variable [-InputObject ] + [] ``` ## DESCRIPTION @@ -109,34 +109,7 @@ Parameter Sets: File Aliases: Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationAction -This parameter is introduced in Windows PowerShell 3.0.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -This parameter is introduced in Windows PowerShell 3.0.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False From 45517f9e2280e7055ca8177f4505dad2bd770e41 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 20 Dec 2017 10:09:14 -0800 Subject: [PATCH 124/188] fixing output example per issue 1933 --- reference/3.0/Microsoft.PowerShell.Core/About/about_Arrays.md | 4 ++-- reference/4.0/Microsoft.PowerShell.Core/About/about_Arrays.md | 4 ++-- reference/5.0/Microsoft.PowerShell.Core/About/about_Arrays.md | 4 ++-- reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md | 4 ++-- reference/6/Microsoft.PowerShell.Core/About/about_Arrays.md | 4 ++-- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Arrays.md index ae4224cc1336..385ad7e9e732 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -617,8 +617,8 @@ $a[-1] ``` ```output -0 -0 +1 +1 4 4 ``` diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Arrays.md index ae4224cc1336..385ad7e9e732 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -617,8 +617,8 @@ $a[-1] ``` ```output -0 -0 +1 +1 4 4 ``` diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Arrays.md index ae4224cc1336..385ad7e9e732 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -617,8 +617,8 @@ $a[-1] ``` ```output -0 -0 +1 +1 4 4 ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md index ae4224cc1336..385ad7e9e732 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -617,8 +617,8 @@ $a[-1] ``` ```output -0 -0 +1 +1 4 4 ``` diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Arrays.md b/reference/6/Microsoft.PowerShell.Core/About/about_Arrays.md index ae4224cc1336..385ad7e9e732 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -617,8 +617,8 @@ $a[-1] ``` ```output -0 -0 +1 +1 4 4 ``` From 4c8ad5c74f3d51cf5bbbc6a2e6529e0c84ac0b97 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 20 Dec 2017 10:38:28 -0800 Subject: [PATCH 125/188] fix -Path metadata to reflect wildcard support --- .../Get-Item.md | 18 +++++----- .../Get-Item.md | 16 ++++----- .../Get-Item.md | 34 +++++-------------- .../Get-Item.md | 20 +++++------ .../Get-Item.md | 34 ++++++------------- 5 files changed, 44 insertions(+), 78 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Management/Get-Item.md b/reference/3.0/Microsoft.PowerShell.Management/Get-Item.md index 0c5f056c8b0f..959e487fd07f 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Get-Item.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Get-Item.md @@ -107,10 +107,11 @@ Gets the specified alternate NTFS file stream from the file. Enter the stream na Stream is a dynamic parameter that the FileSystem provider adds to the Get-Item cmdlet. This parameter works only in file system drives. -This parameter is introduced in Windows PowerShell 3.0.```yaml +This parameter is introduced in Windows PowerShell 3.0. +```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -131,7 +132,7 @@ This parameter is not supported by any providers installed with Windows PowerShe ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -151,7 +152,7 @@ The Exclude parameter is effective only when the command includes the contents o ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -169,7 +170,7 @@ Filters are more efficient than other parameters, because the provider applies t ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -187,7 +188,7 @@ Even using the Force parameter, the cmdlet cannot override security restrictions ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -207,7 +208,7 @@ The Include parameter is effective only when the command includes the contents o ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -247,7 +248,7 @@ Use the wildcard character (*) to specify all the items in the current location. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True Position: 1 @@ -297,7 +298,6 @@ The registry values are considered to be properties of the registry key. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers. -* ## RELATED LINKS [Clear-Item](Clear-Item.md) diff --git a/reference/4.0/Microsoft.PowerShell.Management/Get-Item.md b/reference/4.0/Microsoft.PowerShell.Management/Get-Item.md index 236073b41147..d42b12ee02bb 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Get-Item.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Get-Item.md @@ -124,7 +124,7 @@ This parameter is not supported by any providers installed with Windows PowerShe ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -144,7 +144,7 @@ The Exclude parameter is effective only when the command includes the contents o ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -162,7 +162,7 @@ Filters are more efficient than other parameters, because the provider applies t ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -180,7 +180,7 @@ Even using the Force parameter, the cmdlet cannot override security restrictions ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -200,7 +200,7 @@ The Include parameter is effective only when the command includes the contents o ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -240,7 +240,7 @@ Use the wildcard character (*) to specify all the items in the current location. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True Position: 1 @@ -288,7 +288,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -324,8 +324,6 @@ The registry values are considered to be properties of the registry key. To list the providers available in your session, type "Get-PsProvider". For more information, see about_Providers. -* - ## RELATED LINKS [Clear-Item](Clear-Item.md) diff --git a/reference/5.0/Microsoft.PowerShell.Management/Get-Item.md b/reference/5.0/Microsoft.PowerShell.Management/Get-Item.md index a3c15c3316aa..1964d31f0ac9 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Get-Item.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Get-Item.md @@ -39,11 +39,7 @@ This cmdlet is used by Windows PowerShell providers to navigate through differen ``` PS C:\> Get-Item . - - - - -Directory: C:\ +Directory: C:\ Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 7/26/2006 10:01 AM ps-test @@ -56,16 +52,6 @@ The dot (.) represents the item at the current location (not its contents). ``` PS C:\> Get-Item * - - - - - - - - - - Directory: C:\ps-test Mode LastWriteTime Length Name ---- ------------- ------ ---- @@ -138,7 +124,7 @@ This parameter is not supported by any providers installed with Windows PowerShe ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -158,7 +144,7 @@ The *Exclude* parameter is effective only when the command includes the contents ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -176,7 +162,7 @@ Filters are more efficient than other parameters, because the provider applies t ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -194,7 +180,7 @@ Even using the *Force* parameter, the cmdlet cannot override security restrictio ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -214,7 +200,7 @@ The *Include* parameter is effective only when the command includes the contents ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -254,13 +240,13 @@ Use the wildcard character (*) to specify all the items in the current location. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Stream @@ -283,7 +269,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -338,8 +324,6 @@ The registry values are considered to be properties of the registry key. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. -* - ## RELATED LINKS [Clear-Item](Clear-Item.md) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Get-Item.md b/reference/5.1/Microsoft.PowerShell.Management/Get-Item.md index 28e1eed37e7f..2f635f18d85b 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Get-Item.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Get-Item.md @@ -39,7 +39,7 @@ This cmdlet is used by Windows PowerShell providers to navigate through differen ``` PS C:\ps-test> Get-Item . - Directory: C:\ + Directory: C:\ Mode LastWriteTime Length Name @@ -218,7 +218,7 @@ This parameter is not supported by any providers installed with Windows PowerShe ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -238,7 +238,7 @@ The *Exclude* parameter is effective only when the command includes the contents ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -256,7 +256,7 @@ Filters are more efficient than other parameters, because the provider applies t ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -274,7 +274,7 @@ Even using the *Force* parameter, the cmdlet cannot override security restrictio ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -294,7 +294,7 @@ The *Include* parameter is effective only when the command includes the contents ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -334,13 +334,13 @@ Use the wildcard character (*) to specify all the items in the current location. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -Stream @@ -363,7 +363,7 @@ This parameter was introduced in Windows PowerShell 3.0. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -418,8 +418,6 @@ The registry values are considered to be properties of the registry key. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. -* - ## RELATED LINKS [Clear-Item](Clear-Item.md) diff --git a/reference/6/Microsoft.PowerShell.Management/Get-Item.md b/reference/6/Microsoft.PowerShell.Management/Get-Item.md index af028cf5812e..ceae93923bf6 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-Item.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-Item.md @@ -39,11 +39,8 @@ This cmdlet is used by Windows PowerShell providers to navigate through differen ``` PS C:\> Get-Item . +Directory: C:\ - - - -Directory: C:\ Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 7/26/2006 10:01 AM ps-test @@ -56,17 +53,8 @@ The dot (.) represents the item at the current location (not its contents). ``` PS C:\> Get-Item * - - - - - - - - - - Directory: C:\ps-test + Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 7/26/2006 9:29 AM Logs @@ -132,7 +120,7 @@ This parameter is not supported by any providers installed with Windows PowerShe ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -153,7 +141,7 @@ This parameter is not supported by any providers installed with Windows PowerShe ```yaml Type: PSCredential Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -173,7 +161,7 @@ The *Exclude* parameter is effective only when the command includes the contents ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -191,7 +179,7 @@ Filters are more efficient than other parameters, because the provider applies t ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -209,7 +197,7 @@ Even using the *Force* parameter, the cmdlet cannot override security restrictio ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -229,7 +217,7 @@ The *Include* parameter is effective only when the command includes the contents ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -269,13 +257,13 @@ Use the wildcard character (*) to specify all the items in the current location. ```yaml Type: String[] Parameter Sets: Path -Aliases: +Aliases: Required: True Position: 1 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False +Accept wildcard characters: True ``` ### -UseTransaction @@ -324,8 +312,6 @@ The registry values are considered to be properties of the registry key. To list the providers available in your session, type `Get-PsProvider`. For more information, see about_Providers. -* - ## RELATED LINKS [Clear-Item](Clear-Item.md) From 7f07ed27b8248bcfb1b16096a8f13e9e17f5c2ae Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 20 Dec 2017 12:29:03 -0800 Subject: [PATCH 126/188] fixing issue 1640 --- .../About/about_Split.md | 94 +++++++++++++------ .../About/about_Split.md | 94 +++++++++++++------ .../About/about_Split.md | 94 +++++++++++++------ .../About/about_Split.md | 94 +++++++++++++------ .../About/about_Split.md | 94 +++++++++++++------ 5 files changed, 330 insertions(+), 140 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Split.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Split.md index 98b97dd2dab7..523bd6d4e3cd 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2017-12-20 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -35,11 +35,10 @@ The following diagram shows the syntax for the -split operator. The parameter names do not appear in the command. Include only the parameter values. The values must appear in the order specified in the syntax diagram. -```powershell +``` -Split - +-Split () -Split [,[,""]] - -Split {} [,] ``` @@ -51,14 +50,14 @@ are applied. ## PARAMETERS -### \ +### \ or \ Specifies one or more strings to be split. If you submit multiple strings, all the strings are split using the same delimiter rules. Example: -```powershell +``` -split "red yellow blue green" red yellow @@ -73,7 +72,7 @@ whitespace, including spaces and non-printable characters, such as newline (\`n) and tab (\`t). When the strings are split, the delimiter is omitted from all the substrings. Example: -```powershell +``` "Lastname:FirstName:Address" -split ":" Lastname FirstName @@ -90,7 +89,7 @@ as a split. Examples: -```powershell +``` "Lastname:FirstName:Address" -split "(:)" Lastname : @@ -139,6 +138,9 @@ Example: ```powershell $c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" $c -split ",", 5 +``` + +```Output Mercury Venus Earth @@ -156,6 +158,9 @@ Example: ```powershell $c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" $c -split {$_ -eq "e" -or $_ -eq "p"} +``` + +```Output M rcury,V nus, @@ -173,7 +178,7 @@ Enclose the option name in quotation marks. Options are valid only when the The syntax for the Options parameter is: -```powershell +``` "SimpleMatch [,IgnoreCase]" "[RegexMatch] [,IgnoreCase] [,CultureInvariant] @@ -214,13 +219,16 @@ The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( -split -). Enclose all the strings in parentheses, or store the strings in -a variable, and then submit the variable to the split operator. +Use one of the following patterns to split more than one string: + +- Use the binary split operator (\ -split \) +- Enclose all the strings in parentheses +- Store the strings in a variable then submit the variable to the split + operator Consider the following example: -```powershell +``` PS > -split "1 2", "a b" 1 2 @@ -251,7 +259,11 @@ b The following statement splits the string at whitespace. ```powershell -PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +-split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +``` + +```Output + Windows PowerShell 2.0 @@ -264,7 +276,10 @@ remoting The following statement splits the string at any comma. ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +``` + +```Output Mercury Venus Earth @@ -278,7 +293,10 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +``` + +```Output M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune @@ -287,7 +305,10 @@ cury,Venus,Earth,Mars,Jupit The following statement performs a case-sensitive split at the letter "N". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +``` + +```Output Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -295,7 +316,10 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +``` + +```Output M rcury,V nus, @@ -312,8 +336,10 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` - -split '[er]', 6 +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +``` + +```Output M cu @@ -325,7 +351,10 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS > "a,b,c,d,e,f,g,h" -split ",", 3 +"a,b,c,d,e,f,g,h" -split ",", 3 +``` + +```Output a b c,d,e,f,g,h @@ -335,7 +364,10 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS > "a,b,c,d", "e,f,g,h" -split ",", 3 +"a,b,c,d", "e,f,g,h" -split ",", 3 +``` + +```Output a b c,d @@ -353,13 +385,15 @@ can use options, such as Multiline, only when the Max-substrings value is specified. ```powershell -PS > $a = @' +$a = @' 1The first line. 2The second line. 3The third of three lines. '@ +$a -split "^\d", 0, "multiline" +``` -PS > $a -split "^\d", 0, "multiline" +```Output The first line. @@ -381,8 +415,10 @@ can use options, such as SimpleMatch, only when the Max-substrings value is specified. ```powershell -PS > "This.is.a.test" -split ".", 0, "simplematch" +"This.is.a.test" -split ".", 0, "simplematch" +``` +```Output This is a @@ -393,10 +429,12 @@ The following statement splits the string at one of two delimiters, depending on the value of a variable. ```powershell -PS > $i = 1 -PS > $c = "LastName, FirstName; Address, City, State, Zip" -PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +$i = 1 +$c = "LastName, FirstName; Address, City, State, Zip" +$c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +``` +```Output LastName, FirstName Address, City, State, Zip ``` diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md index 98b97dd2dab7..523bd6d4e3cd 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2017-12-20 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -35,11 +35,10 @@ The following diagram shows the syntax for the -split operator. The parameter names do not appear in the command. Include only the parameter values. The values must appear in the order specified in the syntax diagram. -```powershell +``` -Split - +-Split () -Split [,[,""]] - -Split {} [,] ``` @@ -51,14 +50,14 @@ are applied. ## PARAMETERS -### \ +### \ or \ Specifies one or more strings to be split. If you submit multiple strings, all the strings are split using the same delimiter rules. Example: -```powershell +``` -split "red yellow blue green" red yellow @@ -73,7 +72,7 @@ whitespace, including spaces and non-printable characters, such as newline (\`n) and tab (\`t). When the strings are split, the delimiter is omitted from all the substrings. Example: -```powershell +``` "Lastname:FirstName:Address" -split ":" Lastname FirstName @@ -90,7 +89,7 @@ as a split. Examples: -```powershell +``` "Lastname:FirstName:Address" -split "(:)" Lastname : @@ -139,6 +138,9 @@ Example: ```powershell $c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" $c -split ",", 5 +``` + +```Output Mercury Venus Earth @@ -156,6 +158,9 @@ Example: ```powershell $c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" $c -split {$_ -eq "e" -or $_ -eq "p"} +``` + +```Output M rcury,V nus, @@ -173,7 +178,7 @@ Enclose the option name in quotation marks. Options are valid only when the The syntax for the Options parameter is: -```powershell +``` "SimpleMatch [,IgnoreCase]" "[RegexMatch] [,IgnoreCase] [,CultureInvariant] @@ -214,13 +219,16 @@ The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( -split -). Enclose all the strings in parentheses, or store the strings in -a variable, and then submit the variable to the split operator. +Use one of the following patterns to split more than one string: + +- Use the binary split operator (\ -split \) +- Enclose all the strings in parentheses +- Store the strings in a variable then submit the variable to the split + operator Consider the following example: -```powershell +``` PS > -split "1 2", "a b" 1 2 @@ -251,7 +259,11 @@ b The following statement splits the string at whitespace. ```powershell -PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +-split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +``` + +```Output + Windows PowerShell 2.0 @@ -264,7 +276,10 @@ remoting The following statement splits the string at any comma. ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +``` + +```Output Mercury Venus Earth @@ -278,7 +293,10 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +``` + +```Output M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune @@ -287,7 +305,10 @@ cury,Venus,Earth,Mars,Jupit The following statement performs a case-sensitive split at the letter "N". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +``` + +```Output Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -295,7 +316,10 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +``` + +```Output M rcury,V nus, @@ -312,8 +336,10 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` - -split '[er]', 6 +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +``` + +```Output M cu @@ -325,7 +351,10 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS > "a,b,c,d,e,f,g,h" -split ",", 3 +"a,b,c,d,e,f,g,h" -split ",", 3 +``` + +```Output a b c,d,e,f,g,h @@ -335,7 +364,10 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS > "a,b,c,d", "e,f,g,h" -split ",", 3 +"a,b,c,d", "e,f,g,h" -split ",", 3 +``` + +```Output a b c,d @@ -353,13 +385,15 @@ can use options, such as Multiline, only when the Max-substrings value is specified. ```powershell -PS > $a = @' +$a = @' 1The first line. 2The second line. 3The third of three lines. '@ +$a -split "^\d", 0, "multiline" +``` -PS > $a -split "^\d", 0, "multiline" +```Output The first line. @@ -381,8 +415,10 @@ can use options, such as SimpleMatch, only when the Max-substrings value is specified. ```powershell -PS > "This.is.a.test" -split ".", 0, "simplematch" +"This.is.a.test" -split ".", 0, "simplematch" +``` +```Output This is a @@ -393,10 +429,12 @@ The following statement splits the string at one of two delimiters, depending on the value of a variable. ```powershell -PS > $i = 1 -PS > $c = "LastName, FirstName; Address, City, State, Zip" -PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +$i = 1 +$c = "LastName, FirstName; Address, City, State, Zip" +$c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +``` +```Output LastName, FirstName Address, City, State, Zip ``` diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md index 98b97dd2dab7..523bd6d4e3cd 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2017-12-20 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -35,11 +35,10 @@ The following diagram shows the syntax for the -split operator. The parameter names do not appear in the command. Include only the parameter values. The values must appear in the order specified in the syntax diagram. -```powershell +``` -Split - +-Split () -Split [,[,""]] - -Split {} [,] ``` @@ -51,14 +50,14 @@ are applied. ## PARAMETERS -### \ +### \ or \ Specifies one or more strings to be split. If you submit multiple strings, all the strings are split using the same delimiter rules. Example: -```powershell +``` -split "red yellow blue green" red yellow @@ -73,7 +72,7 @@ whitespace, including spaces and non-printable characters, such as newline (\`n) and tab (\`t). When the strings are split, the delimiter is omitted from all the substrings. Example: -```powershell +``` "Lastname:FirstName:Address" -split ":" Lastname FirstName @@ -90,7 +89,7 @@ as a split. Examples: -```powershell +``` "Lastname:FirstName:Address" -split "(:)" Lastname : @@ -139,6 +138,9 @@ Example: ```powershell $c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" $c -split ",", 5 +``` + +```Output Mercury Venus Earth @@ -156,6 +158,9 @@ Example: ```powershell $c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" $c -split {$_ -eq "e" -or $_ -eq "p"} +``` + +```Output M rcury,V nus, @@ -173,7 +178,7 @@ Enclose the option name in quotation marks. Options are valid only when the The syntax for the Options parameter is: -```powershell +``` "SimpleMatch [,IgnoreCase]" "[RegexMatch] [,IgnoreCase] [,CultureInvariant] @@ -214,13 +219,16 @@ The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( -split -). Enclose all the strings in parentheses, or store the strings in -a variable, and then submit the variable to the split operator. +Use one of the following patterns to split more than one string: + +- Use the binary split operator (\ -split \) +- Enclose all the strings in parentheses +- Store the strings in a variable then submit the variable to the split + operator Consider the following example: -```powershell +``` PS > -split "1 2", "a b" 1 2 @@ -251,7 +259,11 @@ b The following statement splits the string at whitespace. ```powershell -PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +-split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +``` + +```Output + Windows PowerShell 2.0 @@ -264,7 +276,10 @@ remoting The following statement splits the string at any comma. ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +``` + +```Output Mercury Venus Earth @@ -278,7 +293,10 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +``` + +```Output M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune @@ -287,7 +305,10 @@ cury,Venus,Earth,Mars,Jupit The following statement performs a case-sensitive split at the letter "N". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +``` + +```Output Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -295,7 +316,10 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +``` + +```Output M rcury,V nus, @@ -312,8 +336,10 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` - -split '[er]', 6 +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +``` + +```Output M cu @@ -325,7 +351,10 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS > "a,b,c,d,e,f,g,h" -split ",", 3 +"a,b,c,d,e,f,g,h" -split ",", 3 +``` + +```Output a b c,d,e,f,g,h @@ -335,7 +364,10 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS > "a,b,c,d", "e,f,g,h" -split ",", 3 +"a,b,c,d", "e,f,g,h" -split ",", 3 +``` + +```Output a b c,d @@ -353,13 +385,15 @@ can use options, such as Multiline, only when the Max-substrings value is specified. ```powershell -PS > $a = @' +$a = @' 1The first line. 2The second line. 3The third of three lines. '@ +$a -split "^\d", 0, "multiline" +``` -PS > $a -split "^\d", 0, "multiline" +```Output The first line. @@ -381,8 +415,10 @@ can use options, such as SimpleMatch, only when the Max-substrings value is specified. ```powershell -PS > "This.is.a.test" -split ".", 0, "simplematch" +"This.is.a.test" -split ".", 0, "simplematch" +``` +```Output This is a @@ -393,10 +429,12 @@ The following statement splits the string at one of two delimiters, depending on the value of a variable. ```powershell -PS > $i = 1 -PS > $c = "LastName, FirstName; Address, City, State, Zip" -PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +$i = 1 +$c = "LastName, FirstName; Address, City, State, Zip" +$c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +``` +```Output LastName, FirstName Address, City, State, Zip ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md index 98b97dd2dab7..523bd6d4e3cd 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2017-12-20 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -35,11 +35,10 @@ The following diagram shows the syntax for the -split operator. The parameter names do not appear in the command. Include only the parameter values. The values must appear in the order specified in the syntax diagram. -```powershell +``` -Split - +-Split () -Split [,[,""]] - -Split {} [,] ``` @@ -51,14 +50,14 @@ are applied. ## PARAMETERS -### \ +### \ or \ Specifies one or more strings to be split. If you submit multiple strings, all the strings are split using the same delimiter rules. Example: -```powershell +``` -split "red yellow blue green" red yellow @@ -73,7 +72,7 @@ whitespace, including spaces and non-printable characters, such as newline (\`n) and tab (\`t). When the strings are split, the delimiter is omitted from all the substrings. Example: -```powershell +``` "Lastname:FirstName:Address" -split ":" Lastname FirstName @@ -90,7 +89,7 @@ as a split. Examples: -```powershell +``` "Lastname:FirstName:Address" -split "(:)" Lastname : @@ -139,6 +138,9 @@ Example: ```powershell $c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" $c -split ",", 5 +``` + +```Output Mercury Venus Earth @@ -156,6 +158,9 @@ Example: ```powershell $c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" $c -split {$_ -eq "e" -or $_ -eq "p"} +``` + +```Output M rcury,V nus, @@ -173,7 +178,7 @@ Enclose the option name in quotation marks. Options are valid only when the The syntax for the Options parameter is: -```powershell +``` "SimpleMatch [,IgnoreCase]" "[RegexMatch] [,IgnoreCase] [,CultureInvariant] @@ -214,13 +219,16 @@ The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( -split -). Enclose all the strings in parentheses, or store the strings in -a variable, and then submit the variable to the split operator. +Use one of the following patterns to split more than one string: + +- Use the binary split operator (\ -split \) +- Enclose all the strings in parentheses +- Store the strings in a variable then submit the variable to the split + operator Consider the following example: -```powershell +``` PS > -split "1 2", "a b" 1 2 @@ -251,7 +259,11 @@ b The following statement splits the string at whitespace. ```powershell -PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +-split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +``` + +```Output + Windows PowerShell 2.0 @@ -264,7 +276,10 @@ remoting The following statement splits the string at any comma. ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +``` + +```Output Mercury Venus Earth @@ -278,7 +293,10 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +``` + +```Output M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune @@ -287,7 +305,10 @@ cury,Venus,Earth,Mars,Jupit The following statement performs a case-sensitive split at the letter "N". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +``` + +```Output Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -295,7 +316,10 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +``` + +```Output M rcury,V nus, @@ -312,8 +336,10 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` - -split '[er]', 6 +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +``` + +```Output M cu @@ -325,7 +351,10 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS > "a,b,c,d,e,f,g,h" -split ",", 3 +"a,b,c,d,e,f,g,h" -split ",", 3 +``` + +```Output a b c,d,e,f,g,h @@ -335,7 +364,10 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS > "a,b,c,d", "e,f,g,h" -split ",", 3 +"a,b,c,d", "e,f,g,h" -split ",", 3 +``` + +```Output a b c,d @@ -353,13 +385,15 @@ can use options, such as Multiline, only when the Max-substrings value is specified. ```powershell -PS > $a = @' +$a = @' 1The first line. 2The second line. 3The third of three lines. '@ +$a -split "^\d", 0, "multiline" +``` -PS > $a -split "^\d", 0, "multiline" +```Output The first line. @@ -381,8 +415,10 @@ can use options, such as SimpleMatch, only when the Max-substrings value is specified. ```powershell -PS > "This.is.a.test" -split ".", 0, "simplematch" +"This.is.a.test" -split ".", 0, "simplematch" +``` +```Output This is a @@ -393,10 +429,12 @@ The following statement splits the string at one of two delimiters, depending on the value of a variable. ```powershell -PS > $i = 1 -PS > $c = "LastName, FirstName; Address, City, State, Zip" -PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +$i = 1 +$c = "LastName, FirstName; Address, City, State, Zip" +$c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +``` +```Output LastName, FirstName Address, City, State, Zip ``` diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Split.md b/reference/6/Microsoft.PowerShell.Core/About/about_Split.md index 98b97dd2dab7..523bd6d4e3cd 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Split.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Split.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2017-12-20 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -35,11 +35,10 @@ The following diagram shows the syntax for the -split operator. The parameter names do not appear in the command. Include only the parameter values. The values must appear in the order specified in the syntax diagram. -```powershell +``` -Split - +-Split () -Split [,[,""]] - -Split {} [,] ``` @@ -51,14 +50,14 @@ are applied. ## PARAMETERS -### \ +### \ or \ Specifies one or more strings to be split. If you submit multiple strings, all the strings are split using the same delimiter rules. Example: -```powershell +``` -split "red yellow blue green" red yellow @@ -73,7 +72,7 @@ whitespace, including spaces and non-printable characters, such as newline (\`n) and tab (\`t). When the strings are split, the delimiter is omitted from all the substrings. Example: -```powershell +``` "Lastname:FirstName:Address" -split ":" Lastname FirstName @@ -90,7 +89,7 @@ as a split. Examples: -```powershell +``` "Lastname:FirstName:Address" -split "(:)" Lastname : @@ -139,6 +138,9 @@ Example: ```powershell $c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" $c -split ",", 5 +``` + +```Output Mercury Venus Earth @@ -156,6 +158,9 @@ Example: ```powershell $c = "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" $c -split {$_ -eq "e" -or $_ -eq "p"} +``` + +```Output M rcury,V nus, @@ -173,7 +178,7 @@ Enclose the option name in quotation marks. Options are valid only when the The syntax for the Options parameter is: -```powershell +``` "SimpleMatch [,IgnoreCase]" "[RegexMatch] [,IgnoreCase] [,CultureInvariant] @@ -214,13 +219,16 @@ The unary split operator (`-split `) has higher precedence than a comma. As a result, if you submit a comma-separated list of strings to the unary split operator, only the first string (before the first comma) is split. -To split more than one string, use the binary split operator ( -split -). Enclose all the strings in parentheses, or store the strings in -a variable, and then submit the variable to the split operator. +Use one of the following patterns to split more than one string: + +- Use the binary split operator (\ -split \) +- Enclose all the strings in parentheses +- Store the strings in a variable then submit the variable to the split + operator Consider the following example: -```powershell +``` PS > -split "1 2", "a b" 1 2 @@ -251,7 +259,11 @@ b The following statement splits the string at whitespace. ```powershell -PS > -split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +-split "Windows PowerShell 2.0`nWindows PowerShell with remoting" +``` + +```Output + Windows PowerShell 2.0 @@ -264,7 +276,10 @@ remoting The following statement splits the string at any comma. ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split ',' +``` + +```Output Mercury Venus Earth @@ -278,7 +293,10 @@ Neptune The following statement splits the string at the pattern "er". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split 'er' +``` + +```Output M cury,Venus,Earth,Mars,Jupit ,Saturn,Uranus,Neptune @@ -287,7 +305,10 @@ cury,Venus,Earth,Mars,Jupit The following statement performs a case-sensitive split at the letter "N". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -cSplit 'N' +``` + +```Output Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus, eptune ``` @@ -295,7 +316,10 @@ eptune The following statement splits the string at "e" and "t". ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[et]' +``` + +```Output M rcury,V nus, @@ -312,8 +336,10 @@ The following statement splits the string at "e" and "r", but limits the resulting substrings to six substrings. ```powershell -PS > "Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" ` - -split '[er]', 6 +"Mercury,Venus,Earth,Mars,Jupiter,Saturn,Uranus,Neptune" -split '[er]', 6 +``` + +```Output M cu @@ -325,7 +351,10 @@ arth,Mars,Jupiter,Saturn,Uranus,Neptune The following statement splits a string into three substrings. ```powershell -PS > "a,b,c,d,e,f,g,h" -split ",", 3 +"a,b,c,d,e,f,g,h" -split ",", 3 +``` + +```Output a b c,d,e,f,g,h @@ -335,7 +364,10 @@ The following statement splits two strings into three substrings. (The limit is applied to each string independently.) ```powershell -PS > "a,b,c,d", "e,f,g,h" -split ",", 3 +"a,b,c,d", "e,f,g,h" -split ",", 3 +``` + +```Output a b c,d @@ -353,13 +385,15 @@ can use options, such as Multiline, only when the Max-substrings value is specified. ```powershell -PS > $a = @' +$a = @' 1The first line. 2The second line. 3The third of three lines. '@ +$a -split "^\d", 0, "multiline" +``` -PS > $a -split "^\d", 0, "multiline" +```Output The first line. @@ -381,8 +415,10 @@ can use options, such as SimpleMatch, only when the Max-substrings value is specified. ```powershell -PS > "This.is.a.test" -split ".", 0, "simplematch" +"This.is.a.test" -split ".", 0, "simplematch" +``` +```Output This is a @@ -393,10 +429,12 @@ The following statement splits the string at one of two delimiters, depending on the value of a variable. ```powershell -PS > $i = 1 -PS > $c = "LastName, FirstName; Address, City, State, Zip" -PS > $c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +$i = 1 +$c = "LastName, FirstName; Address, City, State, Zip" +$c -split {if ($i -lt 1) {$-eq ","} else {$-eq ";"}} +``` +```Output LastName, FirstName Address, City, State, Zip ``` From e3d2746990926a07eea424c6ecde3af7a39ff89a Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 20 Dec 2017 12:47:41 -0800 Subject: [PATCH 127/188] fixing issue 1651 --- .../Select-String.md | 28 +++++++++---------- .../Select-String.md | 28 +++++++++---------- .../Select-String.md | 28 +++++++++---------- .../Select-String.md | 28 +++++++++---------- .../Select-String.md | 28 +++++++++---------- 5 files changed, 70 insertions(+), 70 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Select-String.md b/reference/3.0/Microsoft.PowerShell.Utility/Select-String.md index 9852bad4959d..0934d20f8654 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Select-String.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Select-String.md @@ -192,7 +192,7 @@ When Select-String finds more than one match in a line of text, it still emits o ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -208,7 +208,7 @@ By default, matches are not case-sensitive. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -239,7 +239,7 @@ When the context includes a match, the MatchInfo object for each match includes ```yaml Type: Int32[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -259,7 +259,7 @@ Valid values are "UTF7", "UTF8", "UTF32", "ASCII", "Unicode", "BigEndianUnicode" ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -277,7 +277,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -295,7 +295,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -317,7 +317,7 @@ The differences are as follows: ```yaml Type: PSObject Parameter Sets: Object -Aliases: +Aliases: Required: True Position: Named @@ -333,7 +333,7 @@ By default, Select-String returns a MatchInfo object for each match it finds. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -348,7 +348,7 @@ Finds text that does not match the specified pattern. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -368,7 +368,7 @@ If you specify only a directory, the command fails. ```yaml Type: String[] Parameter Sets: File -Aliases: +Aliases: Required: True Position: 2 @@ -387,7 +387,7 @@ To learn about regular expressions, see about_Regular_Expressions. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 1 @@ -403,7 +403,7 @@ The value is "true" if the pattern is found; otherwise, the value is "false". ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -420,7 +420,7 @@ It does not interpret the value of the Pattern parameter as a regular expression ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -461,7 +461,7 @@ By default, the output is a set of MatchInfo objects, one for each match found. If you use the Quiet parameter, the output is a Boolean value indicating whether the pattern was found. ## NOTES * Select-String is like the Grep command in UNIX and the FindStr command in Windows. -* The "sst" alias for the Select-String cmdlet was introduced in Windows PowerShell 3.0. +* The **sst** alias for the Select-String cmdlet was introduced in Windows PowerShell 3.0. * To use Select-String, type the text that you want to find as the value of the Pattern parameter. To specify the text to be searched, do the following: diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Select-String.md b/reference/4.0/Microsoft.PowerShell.Utility/Select-String.md index c1b6c5b49ab6..099569e2c325 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Select-String.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Select-String.md @@ -204,7 +204,7 @@ When Select-String finds more than one match in a line of text, it still emits o ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -220,7 +220,7 @@ By default, matches are not case-sensitive. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -251,7 +251,7 @@ When the context includes a match, the MatchInfo object for each match includes ```yaml Type: Int32[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -271,7 +271,7 @@ Valid values are "UTF7", "UTF8", "UTF32", "ASCII", "Unicode", "BigEndianUnicode" ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -289,7 +289,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -307,7 +307,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -329,7 +329,7 @@ The differences are as follows: ```yaml Type: PSObject Parameter Sets: Object -Aliases: +Aliases: Required: True Position: Named @@ -345,7 +345,7 @@ By default, Select-String returns a MatchInfo object for each match it finds. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -360,7 +360,7 @@ Finds text that does not match the specified pattern. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -380,7 +380,7 @@ If you specify only a directory, the command fails. ```yaml Type: String[] Parameter Sets: File -Aliases: +Aliases: Required: True Position: 2 @@ -399,7 +399,7 @@ To learn about regular expressions, see about_Regular_Expressions. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 1 @@ -415,7 +415,7 @@ The value is "true" if the pattern is found; otherwise, the value is "false". ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -432,7 +432,7 @@ It does not interpret the value of the Pattern parameter as a regular expression ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -476,7 +476,7 @@ If you use the Quiet parameter, the output is a Boolean value indicating whether ## NOTES * Select-String is like the Grep command in UNIX and the FindStr command in Windows. -* The "sst" alias for the Select-String cmdlet was introduced in Windows PowerShell 3.0. +* The **sst** alias for the Select-String cmdlet was introduced in Windows PowerShell 3.0. * To use Select-String, type the text that you want to find as the value of the Pattern parameter. To specify the text to be searched, do the following: diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Select-String.md b/reference/5.0/Microsoft.PowerShell.Utility/Select-String.md index e255f4c64a7a..ffdfd934d2c1 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Select-String.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Select-String.md @@ -200,7 +200,7 @@ When **Select-String** finds more than one match in a line of text, it still emi ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -216,7 +216,7 @@ By default, matches are not case-sensitive. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -247,7 +247,7 @@ When the context includes a match, the **MatchInfo** object for each match inclu ```yaml Type: Int32[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -277,7 +277,7 @@ OEM is the current original equipment manufacturer code page identifier for the ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Accepted values: unicode, utf7, utf8, utf32, ascii, bigendianunicode, default, oem Required: False @@ -296,7 +296,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -314,7 +314,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -336,7 +336,7 @@ The differences are as follows: ```yaml Type: PSObject Parameter Sets: Object -Aliases: +Aliases: Required: True Position: Named @@ -352,7 +352,7 @@ By default, **Select-String** returns a **MatchInfo** object for each match it f ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -386,7 +386,7 @@ Indicates that the cmdlet finds text that does not match the specified pattern. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -406,7 +406,7 @@ If you specify only a directory, the command fails. ```yaml Type: String[] Parameter Sets: File -Aliases: +Aliases: Required: True Position: 1 @@ -425,7 +425,7 @@ To learn about regular expressions, see about_Regular_Expressions. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 0 @@ -441,7 +441,7 @@ The value is True if the pattern is found; otherwise, the value is False. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -458,7 +458,7 @@ It does not interpret the value of the *Pattern* parameter as a regular expressi ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -483,7 +483,7 @@ If you use the *Quiet* parameter, the output is a Boolean value indicating wheth ## NOTES * **Select-String** is like the Grep command in UNIX and the FindStr command in Windows. -* The **sst** alias for the **Select-String** cmdlet was introduced in Windows PowerShell 3.0. +* The **sls** alias for the **Select-String** cmdlet was introduced in Windows PowerShell 3.0. * To use **Select-String**, type the text that you want to find as the value of the *Pattern* parameter. To specify the text to be searched, do the following: diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Select-String.md b/reference/5.1/Microsoft.PowerShell.Utility/Select-String.md index f8f5a9a09bbc..94270f8604cd 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Select-String.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Select-String.md @@ -200,7 +200,7 @@ When **Select-String** finds more than one match in a line of text, it still emi ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -216,7 +216,7 @@ By default, matches are not case-sensitive. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -247,7 +247,7 @@ When the context includes a match, the **MatchInfo** object for each match inclu ```yaml Type: Int32[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -277,7 +277,7 @@ OEM is the current original equipment manufacturer code page identifier for the ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Accepted values: unicode, utf7, utf8, utf32, ascii, bigendianunicode, default, oem Required: False @@ -296,7 +296,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -314,7 +314,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -336,7 +336,7 @@ The differences are as follows: ```yaml Type: PSObject Parameter Sets: Object -Aliases: +Aliases: Required: True Position: Named @@ -352,7 +352,7 @@ By default, **Select-String** returns a **MatchInfo** object for each match it f ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -386,7 +386,7 @@ Indicates that the cmdlet finds text that does not match the specified pattern. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -406,7 +406,7 @@ If you specify only a directory, the command fails. ```yaml Type: String[] Parameter Sets: File -Aliases: +Aliases: Required: True Position: 1 @@ -425,7 +425,7 @@ To learn about regular expressions, see about_Regular_Expressions. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 0 @@ -441,7 +441,7 @@ The value is True if the pattern is found; otherwise, the value is False. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -458,7 +458,7 @@ It does not interpret the value of the *Pattern* parameter as a regular expressi ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -483,7 +483,7 @@ If you use the *Quiet* parameter, the output is a Boolean value indicating wheth ## NOTES * **Select-String** is like the Grep command in UNIX and the FindStr command in Windows. -* The **sst** alias for the **Select-String** cmdlet was introduced in Windows PowerShell 3.0. +* The **sls** alias for the **Select-String** cmdlet was introduced in Windows PowerShell 3.0. * To use **Select-String**, type the text that you want to find as the value of the *Pattern* parameter. To specify the text to be searched, do the following: diff --git a/reference/6/Microsoft.PowerShell.Utility/Select-String.md b/reference/6/Microsoft.PowerShell.Utility/Select-String.md index a6dfd436257e..d77c8cef990a 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Select-String.md +++ b/reference/6/Microsoft.PowerShell.Utility/Select-String.md @@ -203,7 +203,7 @@ When **Select-String** finds more than one match in a line of text, it still emi ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -219,7 +219,7 @@ By default, matches are not case-sensitive. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -250,7 +250,7 @@ When the context includes a match, the **MatchInfo** object for each match inclu ```yaml Type: Int32[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -280,7 +280,7 @@ OEM is the current original equipment manufacturer code page identifier for the ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Accepted values: unicode, utf7, utf8, utf32, ascii, bigendianunicode, default, oem Required: False @@ -299,7 +299,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -317,7 +317,7 @@ Wildcards are permitted. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -366,7 +366,7 @@ The differences are as follows: ```yaml Type: PSObject Parameter Sets: Object -Aliases: +Aliases: Required: True Position: Named @@ -382,7 +382,7 @@ By default, **Select-String** returns a **MatchInfo** object for each match it f ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -397,7 +397,7 @@ Indicates that the cmdlet finds text that does not match the specified pattern. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -417,7 +417,7 @@ If you specify only a directory, the command fails. ```yaml Type: String[] Parameter Sets: File -Aliases: +Aliases: Required: True Position: 2 @@ -436,7 +436,7 @@ To learn about regular expressions, see about_Regular_Expressions. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: True Position: 1 @@ -452,7 +452,7 @@ The value is True if the pattern is found; otherwise, the value is False. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -469,7 +469,7 @@ It does not interpret the value of the *Pattern* parameter as a regular expressi ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -513,7 +513,7 @@ If you use the *Quiet* parameter, the output is a Boolean value indicating wheth ## NOTES * **Select-String** is like the Grep command in UNIX and the FindStr command in Windows. -* The **sst** alias for the **Select-String** cmdlet was introduced in Windows PowerShell 3.0. +* The **sls** alias for the **Select-String** cmdlet was introduced in Windows PowerShell 3.0. * To use **Select-String**, type the text that you want to find as the value of the *Pattern* parameter. To specify the text to be searched, do the following: From 22470853a60e8b1e2b7ee2c6c6eb37915b5a3b8e Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Fri, 22 Dec 2017 01:13:25 +0900 Subject: [PATCH 128/188] Fix link for about_Remote_Requirements (#1976) --- reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md | 2 +- .../3.0/Microsoft.PowerShell.Management/Restart-Computer.md | 2 +- reference/3.0/Microsoft.PowerShell.Management/Stop-Computer.md | 2 +- reference/4.0/Microsoft.PowerShell.Core/New-PSSession.md | 2 +- .../4.0/Microsoft.PowerShell.Management/Restart-Computer.md | 2 +- reference/4.0/Microsoft.PowerShell.Management/Stop-Computer.md | 2 +- reference/5.0/Microsoft.PowerShell.Core/New-PSSession.md | 2 +- .../5.0/Microsoft.PowerShell.Management/Restart-Computer.md | 2 +- reference/5.0/PSDesiredStateConfiguration/Disable-DscDebug.md | 2 +- reference/5.0/PSDesiredStateConfiguration/Enable-DscDebug.md | 2 +- .../5.0/PSDesiredStateConfiguration/Get-DscConfiguration.md | 2 +- .../PSDesiredStateConfiguration/Get-DscConfigurationStatus.md | 2 +- .../Get-DscLocalConfigurationManager.md | 2 +- .../Remove-DscConfigurationDocument.md | 2 +- .../5.0/PSDesiredStateConfiguration/Restore-DscConfiguration.md | 2 +- .../5.0/PSDesiredStateConfiguration/Stop-DscConfiguration.md | 2 +- .../5.0/PSDesiredStateConfiguration/Test-DscConfiguration.md | 2 +- reference/5.1/Microsoft.PowerShell.Core/New-PSSession.md | 2 +- .../5.1/Microsoft.PowerShell.Management/Restart-Computer.md | 2 +- .../5.1/PSDesiredStateConfiguration/Test-DscConfiguration.md | 2 +- reference/6/Microsoft.PowerShell.Core/New-PSSession.md | 2 +- reference/6/Microsoft.PowerShell.Management/Restart-Computer.md | 2 +- 22 files changed, 22 insertions(+), 22 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md index 13d86433fef5..0bc93758b2c5 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md @@ -541,7 +541,7 @@ You can pipe a computer name (string), ConnectionURI (URI), or session (PSSessio ### System.Management.Automation.Runspaces.PSSession ## NOTES -* This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any remote computers must be configured for Windows PowerShell remoting. For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkID=135187). +* This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any remote computers must be configured for Windows PowerShell remoting. For more information, see [about_Remote_Requirements](About/about_Remote_Requirements.md). * To create a PSSession on the local computer, start Windows PowerShell with the "Run as administrator" option. * When you are finished with the PSSession, use the Remove-PSSession cmdlet to delete the PSSession and release its resources. diff --git a/reference/3.0/Microsoft.PowerShell.Management/Restart-Computer.md b/reference/3.0/Microsoft.PowerShell.Management/Restart-Computer.md index 8a1fc41671dd..ddc7cdee315d 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Restart-Computer.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Restart-Computer.md @@ -110,7 +110,7 @@ These settings are designed for enterprises in which DCOM-based restarts fail be Runs the command as a background job. Note: To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of Windows, you must open Windows PowerShell with the "Run as administrator" option. -For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkID=135187). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). When you use the **AsJob** parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job completes. diff --git a/reference/3.0/Microsoft.PowerShell.Management/Stop-Computer.md b/reference/3.0/Microsoft.PowerShell.Management/Stop-Computer.md index 0ee9543c18f1..9d19e39af832 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Stop-Computer.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Stop-Computer.md @@ -87,7 +87,7 @@ It also uses the ThrottleLimit parameter to limit the command to 10 concurrent c Runs the command as a background job. Note: To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of Windows, you must open Windows PowerShell with the "Run as administrator" option. -For more information, see about_Remote_Requirements". +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). When you use the AsJob parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job completes. diff --git a/reference/4.0/Microsoft.PowerShell.Core/New-PSSession.md b/reference/4.0/Microsoft.PowerShell.Core/New-PSSession.md index 2668bd38063c..9fa265db2749 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/4.0/Microsoft.PowerShell.Core/New-PSSession.md @@ -557,7 +557,7 @@ You can pipe a computer name (string), ConnectionURI (URI), or session (PSSessio ### System.Management.Automation.Runspaces.PSSession ## NOTES -* This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any remote computers must be configured for Windows PowerShell remoting. For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkID=135187). +* This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any remote computers must be configured for Windows PowerShell remoting. For more information, see [about_Remote_Requirements](About/about_Remote_Requirements.md). * To create a PSSession on the local computer, start Windows PowerShell with the "Run as administrator" option. * When you are finished with the PSSession, use the Remove-PSSession cmdlet to delete the PSSession and release its resources. diff --git a/reference/4.0/Microsoft.PowerShell.Management/Restart-Computer.md b/reference/4.0/Microsoft.PowerShell.Management/Restart-Computer.md index 2a8c51709c7e..3f3082be3057 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Restart-Computer.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Restart-Computer.md @@ -120,7 +120,7 @@ These settings are designed for enterprises in which DCOM-based restarts fail be Runs the command as a background job. Note: To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of Windows, you must open Windows PowerShell with the "Run as administrator" option. -For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkID=135187). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). When you use the **AsJob** parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job completes. diff --git a/reference/4.0/Microsoft.PowerShell.Management/Stop-Computer.md b/reference/4.0/Microsoft.PowerShell.Management/Stop-Computer.md index 59e473c19536..b6a19dea2805 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Stop-Computer.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Stop-Computer.md @@ -95,7 +95,7 @@ It also uses the ThrottleLimit parameter to limit the command to 10 concurrent c Runs the command as a background job. Note: To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of Windows, you must open Windows PowerShell with the "Run as administrator" option. -For more information, see about_Remote_Requirements". +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). When you use the AsJob parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job completes. diff --git a/reference/5.0/Microsoft.PowerShell.Core/New-PSSession.md b/reference/5.0/Microsoft.PowerShell.Core/New-PSSession.md index 3e114fc85451..d9783d2476d3 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/5.0/Microsoft.PowerShell.Core/New-PSSession.md @@ -567,7 +567,7 @@ You can pipe a string, URI, or session object to this cmdlet. ### System.Management.Automation.Runspaces.PSSession ## NOTES -* This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any remote computers must be configured for Windows PowerShell remoting. For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkID=135187). +* This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any remote computers must be configured for Windows PowerShell remoting. For more information, see [about_Remote_Requirements](About/about_Remote_Requirements.md). * To create a **PSSession** on the local computer, start Windows PowerShell with the Run as administrator option. * When you are finished with the **PSSession**, use the Remove-PSSession cmdlet to delete the **PSSession** and release its resources. diff --git a/reference/5.0/Microsoft.PowerShell.Management/Restart-Computer.md b/reference/5.0/Microsoft.PowerShell.Management/Restart-Computer.md index 01e756d47fde..0fa793265e8c 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Restart-Computer.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Restart-Computer.md @@ -119,7 +119,7 @@ These settings are designed for enterprises in which DCOM-based restarts fail be Indicates that this cmdlet runs as a background job. To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell by using the Run as administrator option. -For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkID=135187). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). When you specify the *AsJob* parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job finishes. diff --git a/reference/5.0/PSDesiredStateConfiguration/Disable-DscDebug.md b/reference/5.0/PSDesiredStateConfiguration/Disable-DscDebug.md index b07bfe49f555..e4b413daf3aa 100644 --- a/reference/5.0/PSDesiredStateConfiguration/Disable-DscDebug.md +++ b/reference/5.0/PSDesiredStateConfiguration/Disable-DscDebug.md @@ -52,7 +52,7 @@ To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet. To use this parameter, the local and remote computers must be configured for remoting, and on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell with the Run as administrator option. -For more information, see about_Remote_Requirementshttp://go.microsoft.com/fwlink/?LinkId=623526 (http://go.microsoft.com/fwlink/?LinkId=623526). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). For more information about Windows PowerShell background jobs, see [about_Jobs](../Microsoft.PowerShell.Core/About/about_Jobs.md) and [about_Remote_Jobs](../Microsoft.PowerShell.Core/About/about_Remote_Jobs.md). diff --git a/reference/5.0/PSDesiredStateConfiguration/Enable-DscDebug.md b/reference/5.0/PSDesiredStateConfiguration/Enable-DscDebug.md index 9519c1bfa181..4c15d38e03a0 100644 --- a/reference/5.0/PSDesiredStateConfiguration/Enable-DscDebug.md +++ b/reference/5.0/PSDesiredStateConfiguration/Enable-DscDebug.md @@ -53,7 +53,7 @@ To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet. To use this parameter, the local and remote computers must be configured for remoting, and on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell with the Run as administrator option. -For more information, see about_Remote_Requirementshttp://go.microsoft.com/fwlink/?LinkId=623526 (http://go.microsoft.com/fwlink/?LinkId=623526). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). For more information about Windows PowerShell background jobs, see [about_Jobs](../Microsoft.PowerShell.Core/About/about_Jobs.md) and [about_Remote_Jobs](../Microsoft.PowerShell.Core/About/about_Remote_Jobs.md). diff --git a/reference/5.0/PSDesiredStateConfiguration/Get-DscConfiguration.md b/reference/5.0/PSDesiredStateConfiguration/Get-DscConfiguration.md index 2a7b24fee892..d394eaab616a 100644 --- a/reference/5.0/PSDesiredStateConfiguration/Get-DscConfiguration.md +++ b/reference/5.0/PSDesiredStateConfiguration/Get-DscConfiguration.md @@ -61,7 +61,7 @@ To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet. To use this parameter, the local and remote computers must be configured for remoting, and on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell with the Run as administrator option. -For more information, see about_Remote_Requirementshttp://go.microsoft.com/fwlink/?LinkId=623526 (http://go.microsoft.com/fwlink/?LinkId=623526). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). For more information about Windows PowerShell background jobs, see [about_Jobs](../Microsoft.PowerShell.Core/About/about_Jobs.md) and [about_Remote_Jobs](../Microsoft.PowerShell.Core/About/about_Remote_Jobs.md). diff --git a/reference/5.0/PSDesiredStateConfiguration/Get-DscConfigurationStatus.md b/reference/5.0/PSDesiredStateConfiguration/Get-DscConfigurationStatus.md index d05b7d341421..57af1f96c59f 100644 --- a/reference/5.0/PSDesiredStateConfiguration/Get-DscConfigurationStatus.md +++ b/reference/5.0/PSDesiredStateConfiguration/Get-DscConfigurationStatus.md @@ -76,7 +76,7 @@ To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet. To use this parameter, the local and remote computers must be configured for remoting, and on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell with the Run as administrator option. -For more information, see about_Remote_Requirementshttp://go.microsoft.com/fwlink/?LinkId=623526 (http://go.microsoft.com/fwlink/?LinkId=623526). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). For more information about Windows PowerShell background jobs, see [about_Jobs](../Microsoft.PowerShell.Core/About/about_Jobs.md) and [about_Remote_Jobs](../Microsoft.PowerShell.Core/About/about_Remote_Jobs.md). diff --git a/reference/5.0/PSDesiredStateConfiguration/Get-DscLocalConfigurationManager.md b/reference/5.0/PSDesiredStateConfiguration/Get-DscLocalConfigurationManager.md index fab2e62d3f9b..cff12ebd393d 100644 --- a/reference/5.0/PSDesiredStateConfiguration/Get-DscLocalConfigurationManager.md +++ b/reference/5.0/PSDesiredStateConfiguration/Get-DscLocalConfigurationManager.md @@ -62,7 +62,7 @@ To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet. To use this parameter, the local and remote computers must be configured for remoting, and on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell with the Run as administrator option. -For more information, see about_Remote_Requirementshttp://go.microsoft.com/fwlink/?LinkId=623526 (http://go.microsoft.com/fwlink/?LinkId=623526). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). For more information about Windows PowerShell background jobs, see [about_Jobs](../Microsoft.PowerShell.Core/About/about_Jobs.md) and [about_Remote_Jobs](../Microsoft.PowerShell.Core/About/about_Remote_Jobs.md). diff --git a/reference/5.0/PSDesiredStateConfiguration/Remove-DscConfigurationDocument.md b/reference/5.0/PSDesiredStateConfiguration/Remove-DscConfigurationDocument.md index ba5274ed6aa5..1f384839360e 100644 --- a/reference/5.0/PSDesiredStateConfiguration/Remove-DscConfigurationDocument.md +++ b/reference/5.0/PSDesiredStateConfiguration/Remove-DscConfigurationDocument.md @@ -54,7 +54,7 @@ To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet. To use this parameter, the local and remote computers must be configured for remoting, and on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell with the Run as administrator option. -For more information, see about_Remote_Requirementshttp://go.microsoft.com/fwlink/?LinkId=623526 (http://go.microsoft.com/fwlink/?LinkId=623526). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). For more information about Windows PowerShell background jobs, see [about_Jobs](../Microsoft.PowerShell.Core/About/about_Jobs.md) and [about_Remote_Jobs](../Microsoft.PowerShell.Core/About/about_Remote_Jobs.md). diff --git a/reference/5.0/PSDesiredStateConfiguration/Restore-DscConfiguration.md b/reference/5.0/PSDesiredStateConfiguration/Restore-DscConfiguration.md index 98babda9bb03..c9f7f29c0eae 100644 --- a/reference/5.0/PSDesiredStateConfiguration/Restore-DscConfiguration.md +++ b/reference/5.0/PSDesiredStateConfiguration/Restore-DscConfiguration.md @@ -65,7 +65,7 @@ To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet. To use this parameter, the local and remote computers must be configured for remoting, and on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell with the Run as administrator option. -For more information, see about_Remote_Requirementshttp://go.microsoft.com/fwlink/?LinkId=623526 (http://go.microsoft.com/fwlink/?LinkId=623526). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). For more information about Windows PowerShell background jobs, see [about_Jobs](../Microsoft.PowerShell.Core/About/about_Jobs.md) and [about_Remote_Jobs](../Microsoft.PowerShell.Core/About/about_Remote_Jobs.md). diff --git a/reference/5.0/PSDesiredStateConfiguration/Stop-DscConfiguration.md b/reference/5.0/PSDesiredStateConfiguration/Stop-DscConfiguration.md index fff26c6b5a22..22f5ad386761 100644 --- a/reference/5.0/PSDesiredStateConfiguration/Stop-DscConfiguration.md +++ b/reference/5.0/PSDesiredStateConfiguration/Stop-DscConfiguration.md @@ -56,7 +56,7 @@ To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet. To use this parameter, the local and remote computers must be configured for remoting, and on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell with the Run as administrator option. -For more information, see about_Remote_Requirementshttp://go.microsoft.com/fwlink/?LinkId=623526 (http://go.microsoft.com/fwlink/?LinkId=623526). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). For more information about Windows PowerShell background jobs, see [about_Jobs](../Microsoft.PowerShell.Core/About/about_Jobs.md) and [about_Remote_Jobs](../Microsoft.PowerShell.Core/About/about_Remote_Jobs.md). diff --git a/reference/5.0/PSDesiredStateConfiguration/Test-DscConfiguration.md b/reference/5.0/PSDesiredStateConfiguration/Test-DscConfiguration.md index 4fa7dbdfa609..e0ce6c4455ca 100644 --- a/reference/5.0/PSDesiredStateConfiguration/Test-DscConfiguration.md +++ b/reference/5.0/PSDesiredStateConfiguration/Test-DscConfiguration.md @@ -118,7 +118,7 @@ To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet. To use this parameter, the local and remote computers must be configured for remoting, and on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell with the Run as administrator option. -For more information, see about_Remote_Requirementshttp://go.microsoft.com/fwlink/?LinkId=623526 (http://go.microsoft.com/fwlink/?LinkId=623526). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). For more information about Windows PowerShell background jobs, see [about_Jobs](../Microsoft.PowerShell.Core/About/about_Jobs.md) and [about_Remote_Jobs](../Microsoft.PowerShell.Core/About/about_Remote_Jobs.md). diff --git a/reference/5.1/Microsoft.PowerShell.Core/New-PSSession.md b/reference/5.1/Microsoft.PowerShell.Core/New-PSSession.md index 89fa4d35645b..0bf5a767f4c6 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/5.1/Microsoft.PowerShell.Core/New-PSSession.md @@ -665,7 +665,7 @@ You can pipe a string, URI, or session object to this cmdlet. ### System.Management.Automation.Runspaces.PSSession ## NOTES -* This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any remote computers must be configured for Windows PowerShell remoting. For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkID=135187). +* This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any remote computers must be configured for Windows PowerShell remoting. For more information, see [about_Remote_Requirements](About/about_Remote_Requirements.md). * To create a **PSSession** on the local computer, start Windows PowerShell with the Run as administrator option. * When you are finished with the **PSSession**, use the Remove-PSSession cmdlet to delete the **PSSession** and release its resources. diff --git a/reference/5.1/Microsoft.PowerShell.Management/Restart-Computer.md b/reference/5.1/Microsoft.PowerShell.Management/Restart-Computer.md index 01e756d47fde..0fa793265e8c 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Restart-Computer.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Restart-Computer.md @@ -119,7 +119,7 @@ These settings are designed for enterprises in which DCOM-based restarts fail be Indicates that this cmdlet runs as a background job. To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell by using the Run as administrator option. -For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkID=135187). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). When you specify the *AsJob* parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job finishes. diff --git a/reference/5.1/PSDesiredStateConfiguration/Test-DscConfiguration.md b/reference/5.1/PSDesiredStateConfiguration/Test-DscConfiguration.md index 418a44a0df63..bad7ab68910b 100644 --- a/reference/5.1/PSDesiredStateConfiguration/Test-DscConfiguration.md +++ b/reference/5.1/PSDesiredStateConfiguration/Test-DscConfiguration.md @@ -118,7 +118,7 @@ To manage the job, use the Job cmdlets. To get the job results, use the Receive-Job cmdlet. To use this parameter, the local and remote computers must be configured for remoting, and on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell with the Run as administrator option. -For more information, see about_Remote_Requirementshttp://go.microsoft.com/fwlink/?LinkId=623526 (http://go.microsoft.com/fwlink/?LinkId=623526). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). For more information about Windows PowerShell background jobs, see [about_Jobs](../Microsoft.PowerShell.Core/About/about_Jobs.md) and [about_Remote_Jobs](../Microsoft.PowerShell.Core/About/about_Remote_Jobs.md). diff --git a/reference/6/Microsoft.PowerShell.Core/New-PSSession.md b/reference/6/Microsoft.PowerShell.Core/New-PSSession.md index 22b6b5083c43..fb7d4e88e06d 100644 --- a/reference/6/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/6/Microsoft.PowerShell.Core/New-PSSession.md @@ -803,7 +803,7 @@ You can pipe a string, URI, or session object to this cmdlet. ### System.Management.Automation.Runspaces.PSSession ## NOTES -* This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any remote computers must be configured for Windows PowerShell remoting. For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkID=135187). +* This cmdlet uses the Windows PowerShell remoting infrastructure. To use this cmdlet, the local computer and any remote computers must be configured for Windows PowerShell remoting. For more information, see [about_Remote_Requirements](About/about_Remote_Requirements.md). * To create a **PSSession** on the local computer, start Windows PowerShell with the Run as administrator option. * When you are finished with the **PSSession**, use the Remove-PSSession cmdlet to delete the **PSSession** and release its resources. * The **HostName** and **SSHConnection** parameter sets were included starting with PowerShell 6.0. They were added to provide PowerShell remoting based on Secure Shell (SSH). Both SSH and PowerShell are supported on multiple platforms (Windows, Linux, macOS) and PowerShell remoting will work over these platforms where PowerShell and SSH are installed and configured. This is separate from the previous Windows only remoting that is based on WinRM and much of the WinRM specific features and limitations do not apply. For example WinRM based quotas, session options, custom endpoint configuration, and disconnect/reconnect features are currently not supported. diff --git a/reference/6/Microsoft.PowerShell.Management/Restart-Computer.md b/reference/6/Microsoft.PowerShell.Management/Restart-Computer.md index e05ecb6aca49..f314824de1c7 100644 --- a/reference/6/Microsoft.PowerShell.Management/Restart-Computer.md +++ b/reference/6/Microsoft.PowerShell.Management/Restart-Computer.md @@ -119,7 +119,7 @@ These settings are designed for enterprises in which DCOM-based restarts fail be Indicates that this cmdlet runs as a background job. To use this parameter, the local and remote computers must be configured for remoting and, on Windows Vista and later versions of the Windows operating system, you must open Windows PowerShell by using the Run as administrator option. -For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkID=135187). +For more information, see [about_Remote_Requirements](../Microsoft.PowerShell.Core/About/about_Remote_Requirements.md). When you specify the *AsJob* parameter, the command immediately returns an object that represents the background job. You can continue to work in the session while the job finishes. From 2f7bd316a139a37dddc4c414d19d66ee7a5519b7 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Fri, 22 Dec 2017 01:14:06 +0900 Subject: [PATCH 129/188] Split parameter set in Sort-Object.md v6.0 (#1975) Since v6.0, Sort-Object cmdlet has two parameter sets, "Default" and "Bottom". --- .../Sort-Object.md | 47 ++++++------------- 1 file changed, 14 insertions(+), 33 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Utility/Sort-Object.md b/reference/6/Microsoft.PowerShell.Utility/Sort-Object.md index e2a718aab1d4..8d1dfa5b1d00 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Sort-Object.md +++ b/reference/6/Microsoft.PowerShell.Utility/Sort-Object.md @@ -15,10 +15,18 @@ Sorts objects by property values. ## SYNTAX +### Default ``` -Sort-Object [-Descending] [-Unique] [-InputObject ] [[-Property] ] [-Culture ] - [-CaseSensitive] [-InformationAction ] [-InformationVariable ] [] - [-Top ] [-Bottom ] +Sort-Object [[-Property] ] [-Descending] [-Unique] [-Top ] + [-InputObject ] [-Culture ] [-CaseSensitive] + [] +``` + +### Bottom +``` +Sort-Object [[-Property] ] -Bottom [-Descending] [-Unique] + [-InputObject ] [-Culture ] [-CaseSensitive] + [] ``` ## DESCRIPTION @@ -182,7 +190,7 @@ Specifies the number of objects to get from the end of the sorted object array. ```yaml Type: Int32 -Parameter Sets: (All) +Parameter Sets: Bottom Aliases: Required: False @@ -242,33 +250,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -InputObject Specifies the objects to sort. @@ -315,7 +296,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -326,7 +307,7 @@ Specifies the number of objects to get from the start of the sorted object array ```yaml Type: Int32 -Parameter Sets: (All) +Parameter Sets: Default Aliases: Required: False From 1854c4d5729599c7ba1404700d8b10c88324ed76 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Sat, 23 Dec 2017 01:25:40 +0900 Subject: [PATCH 130/188] Fix link for about_Preference_Variables (#1982) http://... -> relative path --- .../3.0/Microsoft.PowerShell.Core/About/about_History.md | 2 +- .../3.0/Microsoft.PowerShell.Core/Connect-PSSession.md | 2 +- .../3.0/Microsoft.PowerShell.Core/Enter-PSSession.md | 2 +- reference/3.0/Microsoft.PowerShell.Core/Get-Command.md | 6 +++--- reference/3.0/Microsoft.PowerShell.Core/Get-History.md | 2 +- reference/3.0/Microsoft.PowerShell.Core/Get-PSSession.md | 2 +- .../Get-PSSessionConfiguration.md | 2 +- reference/3.0/Microsoft.PowerShell.Core/Import-Module.md | 2 +- reference/3.0/Microsoft.PowerShell.Core/Invoke-Command.md | 4 ++-- reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md | 6 +++--- .../3.0/Microsoft.PowerShell.Core/New-PSSessionOption.md | 6 +++--- .../3.0/Microsoft.PowerShell.Core/Receive-PSSession.md | 2 +- .../3.0/Microsoft.PowerShell.Utility/Write-Verbose.md | 2 +- .../PSWorkflow/About/about_ActivityCommonParameters.md | 6 ++---- .../PSWorkflow/About/about_WorkflowCommonParameters.md | 8 ++++---- reference/3.0/PSWorkflow/New-PSWorkflowSession.md | 2 +- .../4.0/Microsoft.PowerShell.Core/About/about_History.md | 2 +- .../4.0/Microsoft.PowerShell.Core/Connect-PSSession.md | 2 +- .../4.0/Microsoft.PowerShell.Core/Enter-PSSession.md | 2 +- reference/4.0/Microsoft.PowerShell.Core/Get-Command.md | 6 +++--- reference/4.0/Microsoft.PowerShell.Core/Get-History.md | 2 +- reference/4.0/Microsoft.PowerShell.Core/Get-PSSession.md | 2 +- .../Get-PSSessionConfiguration.md | 2 +- reference/4.0/Microsoft.PowerShell.Core/Import-Module.md | 2 +- reference/4.0/Microsoft.PowerShell.Core/Invoke-Command.md | 4 ++-- reference/4.0/Microsoft.PowerShell.Core/New-PSSession.md | 6 +++--- .../4.0/Microsoft.PowerShell.Core/New-PSSessionOption.md | 6 +++--- .../4.0/Microsoft.PowerShell.Core/Receive-PSSession.md | 2 +- .../4.0/Microsoft.PowerShell.Utility/Write-Verbose.md | 2 +- .../PSWorkflow/About/about_ActivityCommonParameters.md | 6 ++---- .../PSWorkflow/About/about_WorkflowCommonParameters.md | 8 ++++---- reference/4.0/PSWorkflow/New-PSWorkflowSession.md | 2 +- .../5.0/Microsoft.PowerShell.Core/About/about_History.md | 2 +- .../5.0/Microsoft.PowerShell.Core/Connect-PSSession.md | 2 +- .../5.0/Microsoft.PowerShell.Core/Enter-PSSession.md | 2 +- reference/5.0/Microsoft.PowerShell.Core/Get-Command.md | 2 +- reference/5.0/Microsoft.PowerShell.Core/Get-History.md | 2 +- reference/5.0/Microsoft.PowerShell.Core/Get-PSSession.md | 2 +- .../Get-PSSessionConfiguration.md | 2 +- reference/5.0/Microsoft.PowerShell.Core/Import-Module.md | 2 +- reference/5.0/Microsoft.PowerShell.Core/Invoke-Command.md | 4 ++-- reference/5.0/Microsoft.PowerShell.Core/New-PSSession.md | 6 +++--- .../5.0/Microsoft.PowerShell.Core/New-PSSessionOption.md | 6 +++--- .../5.0/Microsoft.PowerShell.Core/Receive-PSSession.md | 2 +- .../5.0/Microsoft.PowerShell.Utility/Write-Verbose.md | 2 +- .../PSWorkflow/About/about_ActivityCommonParameters.md | 6 ++---- .../PSWorkflow/About/about_WorkflowCommonParameters.md | 8 ++++---- .../5.1/Microsoft.PowerShell.Core/About/about_History.md | 2 +- .../5.1/Microsoft.PowerShell.Core/Connect-PSSession.md | 2 +- .../5.1/Microsoft.PowerShell.Core/Enter-PSSession.md | 2 +- reference/5.1/Microsoft.PowerShell.Core/Get-Command.md | 2 +- reference/5.1/Microsoft.PowerShell.Core/Get-History.md | 2 +- reference/5.1/Microsoft.PowerShell.Core/Get-PSSession.md | 2 +- .../Get-PSSessionConfiguration.md | 2 +- reference/5.1/Microsoft.PowerShell.Core/Import-Module.md | 2 +- reference/5.1/Microsoft.PowerShell.Core/Invoke-Command.md | 4 ++-- reference/5.1/Microsoft.PowerShell.Core/New-PSSession.md | 6 +++--- .../5.1/Microsoft.PowerShell.Core/New-PSSessionOption.md | 6 +++--- .../5.1/Microsoft.PowerShell.Core/Receive-PSSession.md | 2 +- .../5.1/Microsoft.PowerShell.Utility/Write-Verbose.md | 2 +- .../PSWorkflow/About/about_ActivityCommonParameters.md | 6 ++---- .../PSWorkflow/About/about_WorkflowCommonParameters.md | 8 ++++---- .../6/Microsoft.PowerShell.Core/About/about_History.md | 2 +- .../6/Microsoft.PowerShell.Core/Connect-PSSession.md | 2 +- reference/6/Microsoft.PowerShell.Core/Enter-PSSession.md | 2 +- reference/6/Microsoft.PowerShell.Core/Get-Command.md | 2 +- reference/6/Microsoft.PowerShell.Core/Get-History.md | 2 +- reference/6/Microsoft.PowerShell.Core/Get-PSSession.md | 2 +- .../Get-PSSessionConfiguration.md | 2 +- reference/6/Microsoft.PowerShell.Core/Import-Module.md | 2 +- reference/6/Microsoft.PowerShell.Core/Invoke-Command.md | 4 ++-- reference/6/Microsoft.PowerShell.Core/New-PSSession.md | 6 +++--- .../6/Microsoft.PowerShell.Core/New-PSSessionOption.md | 6 +++--- .../6/Microsoft.PowerShell.Core/Receive-PSSession.md | 2 +- reference/6/Microsoft.PowerShell.Utility/Write-Verbose.md | 2 +- 75 files changed, 120 insertions(+), 128 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_History.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_History.md index 0a87bd50a2bb..4dca4b6a353c 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_History.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_History.md @@ -71,7 +71,7 @@ about profiles, see [about_Profiles](http://go.microsoft.com/fwlink/?LinkID=113729). For more information about the $MaximumHistoryCount preference variable, see -[about_Preference_Variables](http://go.microsoft.com/fwlink/?LinkID=113248). +[about_Preference_Variables](about_Preference_Variables.md). NOTE: In Windows PowerShell 2.0, the default value of the `$MaximumHistoryCount` preference variable is 64. diff --git a/reference/3.0/Microsoft.PowerShell.Core/Connect-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Connect-PSSession.md index fa46b8b0ae86..3dba36e90315 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Connect-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Connect-PSSession.md @@ -392,7 +392,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/3.0/Microsoft.PowerShell.Core/Enter-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Enter-PSSession.md index 7f628df1b996..6b22e21e5b03 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Enter-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Enter-PSSession.md @@ -471,7 +471,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md b/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md index 417d60238345..5865aed69a30 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md @@ -37,7 +37,7 @@ A "`Get-Command *`" command gets all types of commands, including all of the non A **Get-Command** command that uses the exact name of the command (without wildcard characters) automatically imports the module that contains the command so you can use the command immediately. To enable, disable, and configure automatic importing of modules, use the **$PSModuleAutoLoadingPreference** preference variable. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). **Get-Command** gets its data directly from the command code, unlike Get-Help, which gets its information from help topics. @@ -82,7 +82,7 @@ It also imports the **AppLocker** module, which adds all of the commands in the When a module is imported automatically, the effect is the same as using the Import-Module cmdlet. The module can add commands, types and formatting files, and run scripts in the session. To enable, disable, and configuration automatic importing of modules, use the **$PSModuleAutoLoadingPreference** preference variable. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). ### Example 6 ``` PS C:\> Get-Command Get-Childitem -Args Cert: -Syntax @@ -471,7 +471,7 @@ Represents functions and filters ## NOTES * When more than one command with the same name is available to the session, **Get-Command** returns the command that runs when you type the command name. To get commands with the same name (listed in execution order), use the **All** parameter. For more information, see about_Command_Precedence. -* When a module is imported automatically, the effect is the same as using the Import-Module cmdlet. The module can add commands, types and formatting files, and run scripts in the session. To enable, disable, and configuration automatic importing of modules, use the **$PSModuleAutoLoadingPreference** preference variable. For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* When a module is imported automatically, the effect is the same as using the Import-Module cmdlet. The module can add commands, types and formatting files, and run scripts in the session. To enable, disable, and configuration automatic importing of modules, use the **$PSModuleAutoLoadingPreference** preference variable. For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). ## RELATED LINKS [Export-PSSession](../Microsoft.PowerShell.Utility/Export-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-History.md b/reference/3.0/Microsoft.PowerShell.Core/Get-History.md index 15f083f55d56..95b4f7dc9783 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-History.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-History.md @@ -119,7 +119,7 @@ You can pipe a history ID to Get-History. Get-History returns a history object for each history item that it gets. ## NOTES * The session history is a list of the commands entered during the session. The session history represents the order of execution, the status, and the start and end times of the command. As you enter each command, Windows PowerShell adds it to the history so that you can reuse it. For more information about the command history, see about_History (http://go.microsoft.com/fwlink/?LinkID=113233). -* Beginning in Windows PowerShell 3.0, the default value of the **$MaximumHistoryCount** preference variable is 4096. In Windows PowerShell 2.0, the default value is 64. For more information about the **$MaximumHistoryCount** variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* Beginning in Windows PowerShell 3.0, the default value of the **$MaximumHistoryCount** preference variable is 4096. In Windows PowerShell 2.0, the default value is 64. For more information about the **$MaximumHistoryCount** variable, see [about_Preference_Variables](About/about_Preference_Variables.md). ## RELATED LINKS [Add-History](Add-History.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Get-PSSession.md index c01877c4f91d..df58ce0d7558 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-PSSession.md @@ -563,7 +563,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md b/reference/3.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md index 4a64295b8603..eeedfddd454e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md @@ -316,7 +316,7 @@ This command is useful when setting the value of the $PSSessionConfigurationName The $PSSessionConfiguationName variable specifies the default configuration that is used when you create a session. This variable is set on the local computer, but it specifies a configuration on the remote computer. -For more information about the $PSSessionConfiguration variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the $PSSessionConfiguration variable, see [about_Preference_Variables](About/about_Preference_Variables.md). ## PARAMETERS ### -Name diff --git a/reference/3.0/Microsoft.PowerShell.Core/Import-Module.md b/reference/3.0/Microsoft.PowerShell.Core/Import-Module.md index a4440b82e3c4..dd3ceb7c4a68 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Import-Module.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Import-Module.md @@ -58,7 +58,7 @@ The modules that you import must be installed on the local computer or a remote Beginning in Windows PowerShell 3.0, installed modules are automatically imported to the session when you use any commands or providers in the module. However, you can still use the **Import-Module** command to import a module and you can enable and disable automatic module importing by using the **$PSModuleAutoloadingPreference** preference variable. For more information about modules, see about_Modules (http://go.microsoft.com/fwlink/?LinkID=144311). -For more information about the **$PSModuleAutoloadingPreference** variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the **$PSModuleAutoloadingPreference** variable, see [about_Preference_Variables](About/about_Preference_Variables.md). A module is a package that contains members (such as cmdlets, providers, scripts, functions, variables, and other tools and files) that can be used in Windows PowerShell. After a module is imported, you can use the module members in your session. diff --git a/reference/3.0/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/3.0/Microsoft.PowerShell.Core/Invoke-Command.md index 3fe3afe57883..18ff23e19daa 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Invoke-Command.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Invoke-Command.md @@ -430,7 +430,7 @@ Use this parameter to specify the application name when you are not using the ** The default value is the value of the **$PSSessionApplicationName** preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the **URLPrefix** property of a listener on the remote computer. @@ -880,7 +880,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md index 0bc93758b2c5..3dd020df36df 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md @@ -199,7 +199,7 @@ Use this parameter to specify the application name when you are not using the ** The default value is the value of the **$PSSessionApplicationName** preference variable on the local computer. If this preference variable is not defined, the default value is "WSMAN". This value is appropriate for most uses. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the **URLPrefix** property of a listener on the remote computer. @@ -299,7 +299,7 @@ If the specified session configuration does not exist on the remote computer, th The default value is the value of the **$PSSessionConfigurationName** preference variable on the local computer. If this preference variable is not set, the default is Microsoft.PowerShell. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). ```yaml Type: String @@ -476,7 +476,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionOption.md b/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionOption.md index 38cfae610515..e95fde89f559 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionOption.md +++ b/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionOption.md @@ -33,7 +33,7 @@ Because all of the properties can be edited, you can use the resulting object as You can also save a session option object in the **$PSSessionOption** preference variable. The values of this variable establish new default values for the session options. They effective when no session options are set for the session and they take precedence over options set in the session configuration, but you can override them by specifying session options or a session option object in a cmdlet that creates a session. -For more information about the **$PSSessionOption** preference variable, see **about_Preference_Variables** (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). When you use a session option object in a cmdlet that creates a session, the session option values take precedence over default values for sessions set in the **$PSSessionOption** preference variable and in the session configuration. However, they do not take precedence over maximum values, quotas or limits set in the session configuration. @@ -155,7 +155,7 @@ When the **$PSSessionOption** preference variable exists in the session, it esta To make the **$PSSessionOption** variable available in all sessions, add it to your Windows PowerShell session and to your Windows PowerShell profile. -For more information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about profiles, see about_Profiles (http://go.microsoft.com/fwlink/?LinkID=113729). ### Example 6 ``` @@ -660,7 +660,7 @@ You cannot pipe input to this cmdlet. ### System.Management.Automation.Remoting.PSSessionOption ## NOTES -* If the **SessionOption** parameter is not used in a command to create a PSSession, the session options are determined by the property values of the **$PSSessionOption** preference variable, if it is set. For more information about the $PSSessionOption variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* If the **SessionOption** parameter is not used in a command to create a PSSession, the session options are determined by the property values of the **$PSSessionOption** preference variable, if it is set. For more information about the $PSSessionOption variable, see [about_Preference_Variables](About/about_Preference_Variables.md). * The properties of a session configuration object vary with the options set for the session configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties. ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Core/Receive-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Receive-PSSession.md index ca4e43989bb1..0a7d6b673a10 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Receive-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Receive-PSSession.md @@ -631,7 +631,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/3.0/Microsoft.PowerShell.Utility/Write-Verbose.md b/reference/3.0/Microsoft.PowerShell.Utility/Write-Verbose.md index 5d49f57119ea..c335e1077c38 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/Write-Verbose.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/Write-Verbose.md @@ -77,7 +77,7 @@ You can pipe a string that contains the message to **Write-Verbose**. **Write-Verbose** writes only to the verbose message stream. ## NOTES * Verbose messages are returned only when the command uses the **Verbose** common parameter. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). -* In Windows PowerShell background jobs and remote commands, the **$VerbosePreference** variable in the job session and remote session determine whether the verbose message is displayed by default. For more information about the **$VerbosePreference** variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* In Windows PowerShell background jobs and remote commands, the **$VerbosePreference** variable in the job session and remote session determine whether the verbose message is displayed by default. For more information about the **$VerbosePreference** variable, see [about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). ## RELATED LINKS [Write-Error](Write-Error.md) diff --git a/reference/3.0/PSWorkflow/About/about_ActivityCommonParameters.md b/reference/3.0/PSWorkflow/About/about_ActivityCommonParameters.md index a184ba546a8b..a5afd6a87bf7 100644 --- a/reference/3.0/PSWorkflow/About/about_ActivityCommonParameters.md +++ b/reference/3.0/PSWorkflow/About/about_ActivityCommonParameters.md @@ -204,8 +204,7 @@ The default value is the value of the $PSSessionApplicationName preference variable on the target computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. For more information, see -about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +[about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of @@ -522,8 +521,7 @@ New-PSSessionOption cmdlet (http://go.microsoft.com/fwlink/?LinkID=144305). For more information about the $PSSessionOption -preference variable, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +preference variable, see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). -PSUseSSL A value of $True uses the Secure Sockets Layer (SSL) diff --git a/reference/3.0/PSWorkflow/About/about_WorkflowCommonParameters.md b/reference/3.0/PSWorkflow/About/about_WorkflowCommonParameters.md index b8e5aa5562a3..7536a06b0445 100644 --- a/reference/3.0/PSWorkflow/About/about_WorkflowCommonParameters.md +++ b/reference/3.0/PSWorkflow/About/about_WorkflowCommonParameters.md @@ -93,8 +93,7 @@ command. The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. For -more information, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +more information, see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value @@ -307,8 +306,9 @@ session uses the values specified in the session configuration. For a description of the session options, including the default values, see the help topic for the New-PSSessionOption cmdlet -(http://go.microsoft.com/fwlink/?LinkID=144305). For information about the $PSSessionOption preference variable, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +(http://go.microsoft.com/fwlink/?LinkID=144305). +For information about the $PSSessionOption preference variable, +see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). -PSUseSSL Uses the Secure Sockets Layer (SSL) protocol to establish a connection diff --git a/reference/3.0/PSWorkflow/New-PSWorkflowSession.md b/reference/3.0/PSWorkflow/New-PSWorkflowSession.md index 6bf8136ebd0a..e80631a95050 100644 --- a/reference/3.0/PSWorkflow/New-PSWorkflowSession.md +++ b/reference/3.0/PSWorkflow/New-PSWorkflowSession.md @@ -260,7 +260,7 @@ However, they do not take precedence over maximum values, quotas or limits set i For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). For a description of the session options, including the default values, see **New-PSSessionOption**. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). ```yaml Type: PSSessionOption diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_History.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_History.md index 0a87bd50a2bb..4dca4b6a353c 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_History.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_History.md @@ -71,7 +71,7 @@ about profiles, see [about_Profiles](http://go.microsoft.com/fwlink/?LinkID=113729). For more information about the $MaximumHistoryCount preference variable, see -[about_Preference_Variables](http://go.microsoft.com/fwlink/?LinkID=113248). +[about_Preference_Variables](about_Preference_Variables.md). NOTE: In Windows PowerShell 2.0, the default value of the `$MaximumHistoryCount` preference variable is 64. diff --git a/reference/4.0/Microsoft.PowerShell.Core/Connect-PSSession.md b/reference/4.0/Microsoft.PowerShell.Core/Connect-PSSession.md index ef073d90d6e2..d82e947eca8e 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Connect-PSSession.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Connect-PSSession.md @@ -514,7 +514,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/4.0/Microsoft.PowerShell.Core/Enter-PSSession.md b/reference/4.0/Microsoft.PowerShell.Core/Enter-PSSession.md index 92f6d57fb19a..842a484f1644 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Enter-PSSession.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Enter-PSSession.md @@ -480,7 +480,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/4.0/Microsoft.PowerShell.Core/Get-Command.md b/reference/4.0/Microsoft.PowerShell.Core/Get-Command.md index b62fdb95da32..373697a4fcfc 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Get-Command.md @@ -39,7 +39,7 @@ A "`Get-Command *`" command gets all types of commands, including all of the non A **Get-Command** command that uses the exact name of the command (without wildcard characters) automatically imports the module that contains the command so you can use the command immediately. To enable, disable, and configure automatic importing of modules, use the **$PSModuleAutoLoadingPreference** preference variable. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). **Get-Command** gets its data directly from the command code, unlike Get-Help, which gets its information from help topics. @@ -89,7 +89,7 @@ It also imports the **AppLocker** module, which adds all of the commands in the When a module is imported automatically, the effect is the same as using the Import-Module cmdlet. The module can add commands, types and formatting files, and run scripts in the session. To enable, disable, and configuration automatic importing of modules, use the **$PSModuleAutoLoadingPreference** preference variable. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). ### Example 6 ``` @@ -496,7 +496,7 @@ Represents functions and filters ## NOTES * When more than one command with the same name is available to the session, **Get-Command** returns the command that runs when you type the command name. To get commands with the same name (listed in execution order), use the **All** parameter. For more information, see about_Command_Precedence. -* When a module is imported automatically, the effect is the same as using the Import-Module cmdlet. The module can add commands, types and formatting files, and run scripts in the session. To enable, disable, and configuration automatic importing of modules, use the **$PSModuleAutoLoadingPreference** preference variable. For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* When a module is imported automatically, the effect is the same as using the Import-Module cmdlet. The module can add commands, types and formatting files, and run scripts in the session. To enable, disable, and configuration automatic importing of modules, use the **$PSModuleAutoLoadingPreference** preference variable. For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). ## RELATED LINKS diff --git a/reference/4.0/Microsoft.PowerShell.Core/Get-History.md b/reference/4.0/Microsoft.PowerShell.Core/Get-History.md index 0e5407ffbd8e..d4f15c828e71 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Get-History.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Get-History.md @@ -130,7 +130,7 @@ Get-History returns a history object for each history item that it gets. ## NOTES * The session history is a list of the commands entered during the session. The session history represents the order of execution, the status, and the start and end times of the command. As you enter each command, Windows PowerShell adds it to the history so that you can reuse it. For more information about the command history, see about_History (http://go.microsoft.com/fwlink/?LinkID=113233). -* Beginning in Windows PowerShell 3.0, the default value of the **$MaximumHistoryCount** preference variable is 4096. In Windows PowerShell 2.0, the default value is 64. For more information about the **$MaximumHistoryCount** variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* Beginning in Windows PowerShell 3.0, the default value of the **$MaximumHistoryCount** preference variable is 4096. In Windows PowerShell 2.0, the default value is 64. For more information about the **$MaximumHistoryCount** variable, see [about_Preference_Variables](About/about_Preference_Variables.md). ## RELATED LINKS diff --git a/reference/4.0/Microsoft.PowerShell.Core/Get-PSSession.md b/reference/4.0/Microsoft.PowerShell.Core/Get-PSSession.md index 09a6f6c6f675..fc57ead477bf 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Get-PSSession.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Get-PSSession.md @@ -510,7 +510,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/4.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md b/reference/4.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md index f9e53f0ae09f..cd9c60139404 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md @@ -326,7 +326,7 @@ This command is useful when setting the value of the $PSSessionConfigurationName The $PSSessionConfiguationName variable specifies the default configuration that is used when you create a session. This variable is set on the local computer, but it specifies a configuration on the remote computer. -For more information about the $PSSessionConfiguration variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the $PSSessionConfiguration variable, see [about_Preference_Variables](About/about_Preference_Variables.md). ## PARAMETERS diff --git a/reference/4.0/Microsoft.PowerShell.Core/Import-Module.md b/reference/4.0/Microsoft.PowerShell.Core/Import-Module.md index e12e532e1143..6a39d337e91a 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Import-Module.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Import-Module.md @@ -60,7 +60,7 @@ The modules that you import must be installed on the local computer or a remote Beginning in Windows PowerShell 3.0, installed modules are automatically imported to the session when you use any commands or providers in the module. However, you can still use the **Import-Module** command to import a module and you can enable and disable automatic module importing by using the **$PSModuleAutoloadingPreference** preference variable. For more information about modules, see about_Modules (http://go.microsoft.com/fwlink/?LinkID=144311). -For more information about the **$PSModuleAutoloadingPreference** variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the **$PSModuleAutoloadingPreference** variable, see [about_Preference_Variables](About/about_Preference_Variables.md). A module is a package that contains members (such as cmdlets, providers, scripts, functions, variables, and other tools and files) that can be used in Windows PowerShell. After a module is imported, you can use the module members in your session. diff --git a/reference/4.0/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/4.0/Microsoft.PowerShell.Core/Invoke-Command.md index a832903cf883..382a3458728c 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Invoke-Command.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Invoke-Command.md @@ -449,7 +449,7 @@ Use this parameter to specify the application name when you are not using the ** The default value is the value of the **$PSSessionApplicationName** preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the **URLPrefix** property of a listener on the remote computer. @@ -939,7 +939,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/4.0/Microsoft.PowerShell.Core/New-PSSession.md b/reference/4.0/Microsoft.PowerShell.Core/New-PSSession.md index 9fa265db2749..5f911d11a368 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/4.0/Microsoft.PowerShell.Core/New-PSSession.md @@ -212,7 +212,7 @@ Use this parameter to specify the application name when you are not using the ** The default value is the value of the **$PSSessionApplicationName** preference variable on the local computer. If this preference variable is not defined, the default value is "WSMAN". This value is appropriate for most uses. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the **URLPrefix** property of a listener on the remote computer. @@ -313,7 +313,7 @@ If the specified session configuration does not exist on the remote computer, th The default value is the value of the **$PSSessionConfigurationName** preference variable on the local computer. If this preference variable is not set, the default is Microsoft.PowerShell. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). ```yaml Type: String @@ -490,7 +490,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/4.0/Microsoft.PowerShell.Core/New-PSSessionOption.md b/reference/4.0/Microsoft.PowerShell.Core/New-PSSessionOption.md index 8a709e5e78d6..6172b316d6ee 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/New-PSSessionOption.md +++ b/reference/4.0/Microsoft.PowerShell.Core/New-PSSessionOption.md @@ -35,7 +35,7 @@ Because all of the properties can be edited, you can use the resulting object as You can also save a session option object in the **$PSSessionOption** preference variable. The values of this variable establish new default values for the session options. They effective when no session options are set for the session and they take precedence over options set in the session configuration, but you can override them by specifying session options or a session option object in a cmdlet that creates a session. -For more information about the **$PSSessionOption** preference variable, see **about_Preference_Variables** (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). When you use a session option object in a cmdlet that creates a session, the session option values take precedence over default values for sessions set in the **$PSSessionOption** preference variable and in the session configuration. However, they do not take precedence over maximum values, quotas or limits set in the session configuration. @@ -162,7 +162,7 @@ When the **$PSSessionOption** preference variable exists in the session, it esta To make the **$PSSessionOption** variable available in all sessions, add it to your Windows PowerShell session and to your Windows PowerShell profile. -For more information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about profiles, see about_Profiles (http://go.microsoft.com/fwlink/?LinkID=113729). ### Example 6 @@ -675,7 +675,7 @@ You cannot pipe input to this cmdlet. ### System.Management.Automation.Remoting.PSSessionOption ## NOTES -* If the **SessionOption** parameter is not used in a command to create a PSSession, the session options are determined by the property values of the **$PSSessionOption** preference variable, if it is set. For more information about the $PSSessionOption variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* If the **SessionOption** parameter is not used in a command to create a PSSession, the session options are determined by the property values of the **$PSSessionOption** preference variable, if it is set. For more information about the $PSSessionOption variable, see [about_Preference_Variables](About/about_Preference_Variables.md). * The properties of a session configuration object vary with the options set for the session configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties. ## RELATED LINKS diff --git a/reference/4.0/Microsoft.PowerShell.Core/Receive-PSSession.md b/reference/4.0/Microsoft.PowerShell.Core/Receive-PSSession.md index 2bc5422c53ce..fc89bc7c3aea 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Receive-PSSession.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Receive-PSSession.md @@ -635,7 +635,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/4.0/Microsoft.PowerShell.Utility/Write-Verbose.md b/reference/4.0/Microsoft.PowerShell.Utility/Write-Verbose.md index c4b00d05e6a3..a317e58a7fa0 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/Write-Verbose.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/Write-Verbose.md @@ -85,7 +85,7 @@ You can pipe a string that contains the message to **Write-Verbose**. ## NOTES * Verbose messages are returned only when the command uses the **Verbose** common parameter. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). -* In Windows PowerShell background jobs and remote commands, the **$VerbosePreference** variable in the job session and remote session determine whether the verbose message is displayed by default. For more information about the **$VerbosePreference** variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* In Windows PowerShell background jobs and remote commands, the **$VerbosePreference** variable in the job session and remote session determine whether the verbose message is displayed by default. For more information about the **$VerbosePreference** variable, see [about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). ## RELATED LINKS diff --git a/reference/4.0/PSWorkflow/About/about_ActivityCommonParameters.md b/reference/4.0/PSWorkflow/About/about_ActivityCommonParameters.md index a184ba546a8b..a5afd6a87bf7 100644 --- a/reference/4.0/PSWorkflow/About/about_ActivityCommonParameters.md +++ b/reference/4.0/PSWorkflow/About/about_ActivityCommonParameters.md @@ -204,8 +204,7 @@ The default value is the value of the $PSSessionApplicationName preference variable on the target computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. For more information, see -about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +[about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of @@ -522,8 +521,7 @@ New-PSSessionOption cmdlet (http://go.microsoft.com/fwlink/?LinkID=144305). For more information about the $PSSessionOption -preference variable, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +preference variable, see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). -PSUseSSL A value of $True uses the Secure Sockets Layer (SSL) diff --git a/reference/4.0/PSWorkflow/About/about_WorkflowCommonParameters.md b/reference/4.0/PSWorkflow/About/about_WorkflowCommonParameters.md index b8e5aa5562a3..7536a06b0445 100644 --- a/reference/4.0/PSWorkflow/About/about_WorkflowCommonParameters.md +++ b/reference/4.0/PSWorkflow/About/about_WorkflowCommonParameters.md @@ -93,8 +93,7 @@ command. The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. For -more information, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +more information, see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value @@ -307,8 +306,9 @@ session uses the values specified in the session configuration. For a description of the session options, including the default values, see the help topic for the New-PSSessionOption cmdlet -(http://go.microsoft.com/fwlink/?LinkID=144305). For information about the $PSSessionOption preference variable, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +(http://go.microsoft.com/fwlink/?LinkID=144305). +For information about the $PSSessionOption preference variable, +see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). -PSUseSSL Uses the Secure Sockets Layer (SSL) protocol to establish a connection diff --git a/reference/4.0/PSWorkflow/New-PSWorkflowSession.md b/reference/4.0/PSWorkflow/New-PSWorkflowSession.md index 2f7d27bb59aa..b30f325f2483 100644 --- a/reference/4.0/PSWorkflow/New-PSWorkflowSession.md +++ b/reference/4.0/PSWorkflow/New-PSWorkflowSession.md @@ -265,7 +265,7 @@ However, they do not take precedence over maximum values, quotas or limits set i For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). For a description of the session options, including the default values, see **New-PSSessionOption**. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). ```yaml Type: PSSessionOption diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_History.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_History.md index 0a87bd50a2bb..4dca4b6a353c 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_History.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_History.md @@ -71,7 +71,7 @@ about profiles, see [about_Profiles](http://go.microsoft.com/fwlink/?LinkID=113729). For more information about the $MaximumHistoryCount preference variable, see -[about_Preference_Variables](http://go.microsoft.com/fwlink/?LinkID=113248). +[about_Preference_Variables](about_Preference_Variables.md). NOTE: In Windows PowerShell 2.0, the default value of the `$MaximumHistoryCount` preference variable is 64. diff --git a/reference/5.0/Microsoft.PowerShell.Core/Connect-PSSession.md b/reference/5.0/Microsoft.PowerShell.Core/Connect-PSSession.md index 9f624460f91f..6cead487d5ec 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Connect-PSSession.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Connect-PSSession.md @@ -526,7 +526,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.0/Microsoft.PowerShell.Core/Enter-PSSession.md b/reference/5.0/Microsoft.PowerShell.Core/Enter-PSSession.md index 377348f7561e..14642847cb61 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Enter-PSSession.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Enter-PSSession.md @@ -512,7 +512,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see **New-PSSessionOption**. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.0/Microsoft.PowerShell.Core/Get-Command.md b/reference/5.0/Microsoft.PowerShell.Core/Get-Command.md index 6984eda02619..885947657a4a 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Get-Command.md @@ -40,7 +40,7 @@ A `Get-Command *` command gets all types of commands, including all of the non-W A **Get-Command** command that uses the exact name of the command, without wildcard characters, automatically imports the module that contains the command so that you can use the command immediately. To enable, disable, and configure automatic importing of modules, use the $PSModuleAutoLoadingPreference preference variable. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248) in the Microsoft TechNet library. +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md) in the Microsoft TechNet library. **Get-Command** gets its data directly from the command code, unlike Get-Help, which gets its information from help topics. diff --git a/reference/5.0/Microsoft.PowerShell.Core/Get-History.md b/reference/5.0/Microsoft.PowerShell.Core/Get-History.md index 9330096be881..33a94081d97f 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Get-History.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Get-History.md @@ -133,7 +133,7 @@ This cmdlet returns a history object for each history item that it gets. ## NOTES * The session history is a list of the commands entered during the session. The session history represents the run order, the status, and the start and end times of the command. As you enter each command, Windows PowerShell adds it to the history so that you can reuse it. For more information about the command history, see about_History. -* Starting in Windows PowerShell 3.0, the default value of the $MaximumHistoryCount preference variable is 4096. In Windows PowerShell 2.0, the default value is 64. For more information about the $MaximumHistoryCount variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248) in the TechNet library. +* Starting in Windows PowerShell 3.0, the default value of the $MaximumHistoryCount preference variable is 4096. In Windows PowerShell 2.0, the default value is 64. For more information about the $MaximumHistoryCount variable, see [about_Preference_Variables](About/about_Preference_Variables.md) in the TechNet library. ## RELATED LINKS diff --git a/reference/5.0/Microsoft.PowerShell.Core/Get-PSSession.md b/reference/5.0/Microsoft.PowerShell.Core/Get-PSSession.md index fa05262fac99..29a20d8bf5c9 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Get-PSSession.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Get-PSSession.md @@ -527,7 +527,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248) in the Microsoft TechNet library. +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md) in the Microsoft TechNet library. For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md b/reference/5.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md index 1e7b5d5afb80..782ca0e73e77 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md @@ -272,7 +272,7 @@ This command is useful when you set the value of the $PSSessionConfigurationName The $PSSessionConfiguationName variable specifies the default configuration that is used when you create a session. This variable is set on the local computer, but it specifies a configuration on the remote computer. -For more information about the $PSSessionConfiguration variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the $PSSessionConfiguration variable, see [about_Preference_Variables](About/about_Preference_Variables.md). ## PARAMETERS diff --git a/reference/5.0/Microsoft.PowerShell.Core/Import-Module.md b/reference/5.0/Microsoft.PowerShell.Core/Import-Module.md index 13dce5003615..ac236e7ea1da 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Import-Module.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Import-Module.md @@ -75,7 +75,7 @@ The modules that you import must be installed on the local computer or a remote Starting in Windows PowerShell 3.0, installed modules are automatically imported to the session when you use any commands or providers in the module. However, you can still use the **Import-Module** command to import a module and you can enable and disable automatic module importing by using the $PSModuleAutoloadingPreference preference variable. For more information about modules, see about_Modules (http://go.microsoft.com/fwlink/?LinkID=144311). -For more information about the $PSModuleAutoloadingPreference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the $PSModuleAutoloadingPreference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). A module is a package that contains members that can be used in Windows PowerShell. Members include cmdlets, providers, scripts, functions, variables, and other tools and files. diff --git a/reference/5.0/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/5.0/Microsoft.PowerShell.Core/Invoke-Command.md index 47c4ed4e8764..67bfedc2e1d2 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Invoke-Command.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Invoke-Command.md @@ -478,7 +478,7 @@ Use this parameter to specify the application name when you are not using the *C The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the **URLPrefix** property of a listener on the remote computer. @@ -988,7 +988,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see **New-PSSessionOption**. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.0/Microsoft.PowerShell.Core/New-PSSession.md b/reference/5.0/Microsoft.PowerShell.Core/New-PSSession.md index d9783d2476d3..d4350e421533 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/5.0/Microsoft.PowerShell.Core/New-PSSession.md @@ -212,7 +212,7 @@ Use this parameter to specify the application name when you are not using the *C The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the **URLPrefix** property of a listener on the remote computer. @@ -323,7 +323,7 @@ If the specified session configuration does not exist on the remote computer, th The default value is the value of the $PSSessionConfigurationName preference variable on the local computer. If this preference variable is not set, the default is Microsoft.PowerShell. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). ```yaml Type: String @@ -500,7 +500,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see New-PSSessionOption. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.0/Microsoft.PowerShell.Core/New-PSSessionOption.md b/reference/5.0/Microsoft.PowerShell.Core/New-PSSessionOption.md index 9104938557b6..cf625d218b25 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/New-PSSessionOption.md +++ b/reference/5.0/Microsoft.PowerShell.Core/New-PSSessionOption.md @@ -35,7 +35,7 @@ Because all of the properties can be edited, you can use the resulting object as You can also save a session option object in the **$PSSessionOption** preference variable. The values of this variable establish new default values for the session options. They effective when no session options are set for the session and they take precedence over options set in the session configuration, but you can override them by specifying session options or a session option object in a cmdlet that creates a session. -For more information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). When you use a session option object in a cmdlet that creates a session, the session option values take precedence over default values for sessions set in the $PSSessionOption preference variable and in the session configuration. However, they do not take precedence over maximum values, quotas or limits set in the session configuration. @@ -161,7 +161,7 @@ When the $PSSessionOption preference variable occurs in the session, it establis To make the $PSSessionOption variable available in all sessions, add it to your Windows PowerShell session and to your Windows PowerShell profile. -For more information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about profiles, see about_Profiles (http://go.microsoft.com/fwlink/?LinkID=113729). ### Example 6: Fulfill the requirements for a remote session configuration @@ -703,7 +703,7 @@ You cannot pipe input to this cmdlet. ### System.Management.Automation.Remoting.PSSessionOption ## NOTES -* If the *SessionOption* parameter is not used in a command to create a **PSSession**, the session options are determined by the property values of the $PSSessionOption preference variable, if it is set. For more information about the $PSSessionOption variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* If the *SessionOption* parameter is not used in a command to create a **PSSession**, the session options are determined by the property values of the $PSSessionOption preference variable, if it is set. For more information about the $PSSessionOption variable, see [about_Preference_Variables](About/about_Preference_Variables.md). * The properties of a session configuration object vary with the options set for the session configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties. ## RELATED LINKS diff --git a/reference/5.0/Microsoft.PowerShell.Core/Receive-PSSession.md b/reference/5.0/Microsoft.PowerShell.Core/Receive-PSSession.md index 9d1daa8c276a..5eb8c8a89b39 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Receive-PSSession.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Receive-PSSession.md @@ -653,7 +653,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.0/Microsoft.PowerShell.Utility/Write-Verbose.md b/reference/5.0/Microsoft.PowerShell.Utility/Write-Verbose.md index d768f6e75df2..9d70aa987c3b 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/Write-Verbose.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/Write-Verbose.md @@ -85,7 +85,7 @@ You can pipe a string that contains the message to **Write-Verbose**. ## NOTES * Verbose messages are returned only when the command uses the **Verbose** common parameter. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). -* In Windows PowerShell background jobs and remote commands, the **$VerbosePreference** variable in the job session and remote session determine whether the verbose message is displayed by default. For more information about the **$VerbosePreference** variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* In Windows PowerShell background jobs and remote commands, the **$VerbosePreference** variable in the job session and remote session determine whether the verbose message is displayed by default. For more information about the **$VerbosePreference** variable, see [about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). ## RELATED LINKS diff --git a/reference/5.0/PSWorkflow/About/about_ActivityCommonParameters.md b/reference/5.0/PSWorkflow/About/about_ActivityCommonParameters.md index a184ba546a8b..a5afd6a87bf7 100644 --- a/reference/5.0/PSWorkflow/About/about_ActivityCommonParameters.md +++ b/reference/5.0/PSWorkflow/About/about_ActivityCommonParameters.md @@ -204,8 +204,7 @@ The default value is the value of the $PSSessionApplicationName preference variable on the target computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. For more information, see -about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +[about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of @@ -522,8 +521,7 @@ New-PSSessionOption cmdlet (http://go.microsoft.com/fwlink/?LinkID=144305). For more information about the $PSSessionOption -preference variable, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +preference variable, see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). -PSUseSSL A value of $True uses the Secure Sockets Layer (SSL) diff --git a/reference/5.0/PSWorkflow/About/about_WorkflowCommonParameters.md b/reference/5.0/PSWorkflow/About/about_WorkflowCommonParameters.md index e60988afbdf2..31bc58f9e1f3 100644 --- a/reference/5.0/PSWorkflow/About/about_WorkflowCommonParameters.md +++ b/reference/5.0/PSWorkflow/About/about_WorkflowCommonParameters.md @@ -93,8 +93,7 @@ command. The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. For -more information, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +more information, see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value @@ -307,8 +306,9 @@ session uses the values specified in the session configuration. For a description of the session options, including the default values, see the help topic for the New-PSSessionOption cmdlet -(http://go.microsoft.com/fwlink/?LinkID=144305). For information about the $PSSessionOption preference variable, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +(http://go.microsoft.com/fwlink/?LinkID=144305). +For information about the $PSSessionOption preference variable, +see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). -PSUseSSL Uses the Secure Sockets Layer (SSL) protocol to establish a connection diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_History.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_History.md index 0a87bd50a2bb..4dca4b6a353c 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_History.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_History.md @@ -71,7 +71,7 @@ about profiles, see [about_Profiles](http://go.microsoft.com/fwlink/?LinkID=113729). For more information about the $MaximumHistoryCount preference variable, see -[about_Preference_Variables](http://go.microsoft.com/fwlink/?LinkID=113248). +[about_Preference_Variables](about_Preference_Variables.md). NOTE: In Windows PowerShell 2.0, the default value of the `$MaximumHistoryCount` preference variable is 64. diff --git a/reference/5.1/Microsoft.PowerShell.Core/Connect-PSSession.md b/reference/5.1/Microsoft.PowerShell.Core/Connect-PSSession.md index 0845e69c8853..df284abb6b7c 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Connect-PSSession.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Connect-PSSession.md @@ -526,7 +526,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.1/Microsoft.PowerShell.Core/Enter-PSSession.md b/reference/5.1/Microsoft.PowerShell.Core/Enter-PSSession.md index 98509b2fc525..75c53682c98f 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Enter-PSSession.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Enter-PSSession.md @@ -551,7 +551,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see **New-PSSessionOption**. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.1/Microsoft.PowerShell.Core/Get-Command.md b/reference/5.1/Microsoft.PowerShell.Core/Get-Command.md index 8d69c3ff3dab..f34d0e1f36c7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Get-Command.md @@ -40,7 +40,7 @@ A `Get-Command *` command gets all types of commands, including all of the non-W A **Get-Command** command that uses the exact name of the command, without wildcard characters, automatically imports the module that contains the command so that you can use the command immediately. To enable, disable, and configure automatic importing of modules, use the $PSModuleAutoLoadingPreference preference variable. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248) in the Microsoft TechNet library. +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md) in the Microsoft TechNet library. **Get-Command** gets its data directly from the command code, unlike Get-Help, which gets its information from help topics. diff --git a/reference/5.1/Microsoft.PowerShell.Core/Get-History.md b/reference/5.1/Microsoft.PowerShell.Core/Get-History.md index 629d27a84e30..4e61be889c52 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Get-History.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Get-History.md @@ -133,7 +133,7 @@ This cmdlet returns a history object for each history item that it gets. ## NOTES * The session history is a list of the commands entered during the session. The session history represents the run order, the status, and the start and end times of the command. As you enter each command, Windows PowerShell adds it to the history so that you can reuse it. For more information about the command history, see about_History. -* Starting in Windows PowerShell 3.0, the default value of the $MaximumHistoryCount preference variable is 4096. In Windows PowerShell 2.0, the default value is 64. For more information about the $MaximumHistoryCount variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248) in the TechNet library. +* Starting in Windows PowerShell 3.0, the default value of the $MaximumHistoryCount preference variable is 4096. In Windows PowerShell 2.0, the default value is 64. For more information about the $MaximumHistoryCount variable, see [about_Preference_Variables](About/about_Preference_Variables.md) in the TechNet library. ## RELATED LINKS diff --git a/reference/5.1/Microsoft.PowerShell.Core/Get-PSSession.md b/reference/5.1/Microsoft.PowerShell.Core/Get-PSSession.md index b3c32584cbbc..d9e274204bc7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Get-PSSession.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Get-PSSession.md @@ -580,7 +580,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248) in the Microsoft TechNet library. +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md) in the Microsoft TechNet library. For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.1/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md b/reference/5.1/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md index b963fc10683b..cb8e57ed1bd3 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md @@ -272,7 +272,7 @@ This command is useful when you set the value of the $PSSessionConfigurationName The $PSSessionConfiguationName variable specifies the default configuration that is used when you create a session. This variable is set on the local computer, but it specifies a configuration on the remote computer. -For more information about the $PSSessionConfiguration variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the $PSSessionConfiguration variable, see [about_Preference_Variables](About/about_Preference_Variables.md). ## PARAMETERS diff --git a/reference/5.1/Microsoft.PowerShell.Core/Import-Module.md b/reference/5.1/Microsoft.PowerShell.Core/Import-Module.md index ea8ab4e9e121..78ecbfa24009 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Import-Module.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Import-Module.md @@ -76,7 +76,7 @@ The modules that you import must be installed on the local computer or a remote Starting in Windows PowerShell 3.0, installed modules are automatically imported to the session when you use any commands or providers in the module. However, you can still use the **Import-Module** command to import a module and you can enable and disable automatic module importing by using the $PSModuleAutoloadingPreference preference variable. For more information about modules, see about_Modules (http://go.microsoft.com/fwlink/?LinkID=144311). -For more information about the $PSModuleAutoloadingPreference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the $PSModuleAutoloadingPreference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). A module is a package that contains members that can be used in Windows PowerShell. Members include cmdlets, providers, scripts, functions, variables, and other tools and files. diff --git a/reference/5.1/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/5.1/Microsoft.PowerShell.Core/Invoke-Command.md index 4f0097460ecd..6e918c3be7f4 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Invoke-Command.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Invoke-Command.md @@ -492,7 +492,7 @@ Use this parameter to specify the application name when you are not using the *C The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the **URLPrefix** property of a listener on the remote computer. @@ -1032,7 +1032,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see **New-PSSessionOption**. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.1/Microsoft.PowerShell.Core/New-PSSession.md b/reference/5.1/Microsoft.PowerShell.Core/New-PSSession.md index 0bf5a767f4c6..55b47d1bc5ae 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/5.1/Microsoft.PowerShell.Core/New-PSSession.md @@ -230,7 +230,7 @@ Use this parameter to specify the application name when you are not using the *C The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the **URLPrefix** property of a listener on the remote computer. @@ -341,7 +341,7 @@ If the specified session configuration does not exist on the remote computer, th The default value is the value of the $PSSessionConfigurationName preference variable on the local computer. If this preference variable is not set, the default is Microsoft.PowerShell. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). ```yaml Type: String @@ -562,7 +562,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see New-PSSessionOption. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.1/Microsoft.PowerShell.Core/New-PSSessionOption.md b/reference/5.1/Microsoft.PowerShell.Core/New-PSSessionOption.md index 9104938557b6..cf625d218b25 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/New-PSSessionOption.md +++ b/reference/5.1/Microsoft.PowerShell.Core/New-PSSessionOption.md @@ -35,7 +35,7 @@ Because all of the properties can be edited, you can use the resulting object as You can also save a session option object in the **$PSSessionOption** preference variable. The values of this variable establish new default values for the session options. They effective when no session options are set for the session and they take precedence over options set in the session configuration, but you can override them by specifying session options or a session option object in a cmdlet that creates a session. -For more information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). When you use a session option object in a cmdlet that creates a session, the session option values take precedence over default values for sessions set in the $PSSessionOption preference variable and in the session configuration. However, they do not take precedence over maximum values, quotas or limits set in the session configuration. @@ -161,7 +161,7 @@ When the $PSSessionOption preference variable occurs in the session, it establis To make the $PSSessionOption variable available in all sessions, add it to your Windows PowerShell session and to your Windows PowerShell profile. -For more information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about profiles, see about_Profiles (http://go.microsoft.com/fwlink/?LinkID=113729). ### Example 6: Fulfill the requirements for a remote session configuration @@ -703,7 +703,7 @@ You cannot pipe input to this cmdlet. ### System.Management.Automation.Remoting.PSSessionOption ## NOTES -* If the *SessionOption* parameter is not used in a command to create a **PSSession**, the session options are determined by the property values of the $PSSessionOption preference variable, if it is set. For more information about the $PSSessionOption variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* If the *SessionOption* parameter is not used in a command to create a **PSSession**, the session options are determined by the property values of the $PSSessionOption preference variable, if it is set. For more information about the $PSSessionOption variable, see [about_Preference_Variables](About/about_Preference_Variables.md). * The properties of a session configuration object vary with the options set for the session configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties. ## RELATED LINKS diff --git a/reference/5.1/Microsoft.PowerShell.Core/Receive-PSSession.md b/reference/5.1/Microsoft.PowerShell.Core/Receive-PSSession.md index 4e5dbb1b2245..a88787afc9c6 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Receive-PSSession.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Receive-PSSession.md @@ -653,7 +653,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Write-Verbose.md b/reference/5.1/Microsoft.PowerShell.Utility/Write-Verbose.md index 1c9ed20b5d80..478227dbcd1f 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Write-Verbose.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Write-Verbose.md @@ -85,7 +85,7 @@ You can pipe a string that contains the message to **Write-Verbose**. ## NOTES * Verbose messages are returned only when the command uses the **Verbose** common parameter. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). -* In Windows PowerShell background jobs and remote commands, the **$VerbosePreference** variable in the job session and remote session determine whether the verbose message is displayed by default. For more information about the **$VerbosePreference** variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* In Windows PowerShell background jobs and remote commands, the **$VerbosePreference** variable in the job session and remote session determine whether the verbose message is displayed by default. For more information about the **$VerbosePreference** variable, see [about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). ## RELATED LINKS diff --git a/reference/5.1/PSWorkflow/About/about_ActivityCommonParameters.md b/reference/5.1/PSWorkflow/About/about_ActivityCommonParameters.md index a184ba546a8b..a5afd6a87bf7 100644 --- a/reference/5.1/PSWorkflow/About/about_ActivityCommonParameters.md +++ b/reference/5.1/PSWorkflow/About/about_ActivityCommonParameters.md @@ -204,8 +204,7 @@ The default value is the value of the $PSSessionApplicationName preference variable on the target computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. For more information, see -about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +[about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of @@ -522,8 +521,7 @@ New-PSSessionOption cmdlet (http://go.microsoft.com/fwlink/?LinkID=144305). For more information about the $PSSessionOption -preference variable, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +preference variable, see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). -PSUseSSL A value of $True uses the Secure Sockets Layer (SSL) diff --git a/reference/5.1/PSWorkflow/About/about_WorkflowCommonParameters.md b/reference/5.1/PSWorkflow/About/about_WorkflowCommonParameters.md index e60988afbdf2..31bc58f9e1f3 100644 --- a/reference/5.1/PSWorkflow/About/about_WorkflowCommonParameters.md +++ b/reference/5.1/PSWorkflow/About/about_WorkflowCommonParameters.md @@ -93,8 +93,7 @@ command. The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. For -more information, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +more information, see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value @@ -307,8 +306,9 @@ session uses the values specified in the session configuration. For a description of the session options, including the default values, see the help topic for the New-PSSessionOption cmdlet -(http://go.microsoft.com/fwlink/?LinkID=144305). For information about the $PSSessionOption preference variable, see about_Preference_Variables -(http://go.microsoft.com/fwlink/?LinkID=113248). +(http://go.microsoft.com/fwlink/?LinkID=144305). +For information about the $PSSessionOption preference variable, +see [about_Preference_Variables](../../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). -PSUseSSL Uses the Secure Sockets Layer (SSL) protocol to establish a connection diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_History.md b/reference/6/Microsoft.PowerShell.Core/About/about_History.md index 0a87bd50a2bb..4dca4b6a353c 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_History.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_History.md @@ -71,7 +71,7 @@ about profiles, see [about_Profiles](http://go.microsoft.com/fwlink/?LinkID=113729). For more information about the $MaximumHistoryCount preference variable, see -[about_Preference_Variables](http://go.microsoft.com/fwlink/?LinkID=113248). +[about_Preference_Variables](about_Preference_Variables.md). NOTE: In Windows PowerShell 2.0, the default value of the `$MaximumHistoryCount` preference variable is 64. diff --git a/reference/6/Microsoft.PowerShell.Core/Connect-PSSession.md b/reference/6/Microsoft.PowerShell.Core/Connect-PSSession.md index 69d91a6e36ee..4b5ccc8a5b13 100644 --- a/reference/6/Microsoft.PowerShell.Core/Connect-PSSession.md +++ b/reference/6/Microsoft.PowerShell.Core/Connect-PSSession.md @@ -526,7 +526,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/6/Microsoft.PowerShell.Core/Enter-PSSession.md b/reference/6/Microsoft.PowerShell.Core/Enter-PSSession.md index db76eea92545..41e210857b3f 100644 --- a/reference/6/Microsoft.PowerShell.Core/Enter-PSSession.md +++ b/reference/6/Microsoft.PowerShell.Core/Enter-PSSession.md @@ -587,7 +587,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see **New-PSSessionOption**. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/6/Microsoft.PowerShell.Core/Get-Command.md b/reference/6/Microsoft.PowerShell.Core/Get-Command.md index 8d69c3ff3dab..f34d0e1f36c7 100644 --- a/reference/6/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/6/Microsoft.PowerShell.Core/Get-Command.md @@ -40,7 +40,7 @@ A `Get-Command *` command gets all types of commands, including all of the non-W A **Get-Command** command that uses the exact name of the command, without wildcard characters, automatically imports the module that contains the command so that you can use the command immediately. To enable, disable, and configure automatic importing of modules, use the $PSModuleAutoLoadingPreference preference variable. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248) in the Microsoft TechNet library. +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md) in the Microsoft TechNet library. **Get-Command** gets its data directly from the command code, unlike Get-Help, which gets its information from help topics. diff --git a/reference/6/Microsoft.PowerShell.Core/Get-History.md b/reference/6/Microsoft.PowerShell.Core/Get-History.md index 629d27a84e30..4e61be889c52 100644 --- a/reference/6/Microsoft.PowerShell.Core/Get-History.md +++ b/reference/6/Microsoft.PowerShell.Core/Get-History.md @@ -133,7 +133,7 @@ This cmdlet returns a history object for each history item that it gets. ## NOTES * The session history is a list of the commands entered during the session. The session history represents the run order, the status, and the start and end times of the command. As you enter each command, Windows PowerShell adds it to the history so that you can reuse it. For more information about the command history, see about_History. -* Starting in Windows PowerShell 3.0, the default value of the $MaximumHistoryCount preference variable is 4096. In Windows PowerShell 2.0, the default value is 64. For more information about the $MaximumHistoryCount variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248) in the TechNet library. +* Starting in Windows PowerShell 3.0, the default value of the $MaximumHistoryCount preference variable is 4096. In Windows PowerShell 2.0, the default value is 64. For more information about the $MaximumHistoryCount variable, see [about_Preference_Variables](About/about_Preference_Variables.md) in the TechNet library. ## RELATED LINKS diff --git a/reference/6/Microsoft.PowerShell.Core/Get-PSSession.md b/reference/6/Microsoft.PowerShell.Core/Get-PSSession.md index cfe41bf57621..d54df38b65ab 100644 --- a/reference/6/Microsoft.PowerShell.Core/Get-PSSession.md +++ b/reference/6/Microsoft.PowerShell.Core/Get-PSSession.md @@ -563,7 +563,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options, including the default values, see New-PSSessionOption. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248) in the Microsoft TechNet library. +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md) in the Microsoft TechNet library. For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/6/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md b/reference/6/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md index b963fc10683b..cb8e57ed1bd3 100644 --- a/reference/6/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md +++ b/reference/6/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md @@ -272,7 +272,7 @@ This command is useful when you set the value of the $PSSessionConfigurationName The $PSSessionConfiguationName variable specifies the default configuration that is used when you create a session. This variable is set on the local computer, but it specifies a configuration on the remote computer. -For more information about the $PSSessionConfiguration variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the $PSSessionConfiguration variable, see [about_Preference_Variables](About/about_Preference_Variables.md). ## PARAMETERS diff --git a/reference/6/Microsoft.PowerShell.Core/Import-Module.md b/reference/6/Microsoft.PowerShell.Core/Import-Module.md index 55770a38af65..2c245881ce7d 100644 --- a/reference/6/Microsoft.PowerShell.Core/Import-Module.md +++ b/reference/6/Microsoft.PowerShell.Core/Import-Module.md @@ -76,7 +76,7 @@ The modules that you import must be installed on the local computer or a remote Starting in Windows PowerShell 3.0, installed modules are automatically imported to the session when you use any commands or providers in the module. However, you can still use the **Import-Module** command to import a module and you can enable and disable automatic module importing by using the $PSModuleAutoloadingPreference preference variable. For more information about modules, see about_Modules (http://go.microsoft.com/fwlink/?LinkID=144311). -For more information about the $PSModuleAutoloadingPreference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the $PSModuleAutoloadingPreference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). A module is a package that contains members that can be used in Windows PowerShell. Members include cmdlets, providers, scripts, functions, variables, and other tools and files. diff --git a/reference/6/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/6/Microsoft.PowerShell.Core/Invoke-Command.md index 4831882d74fe..11e44169a255 100644 --- a/reference/6/Microsoft.PowerShell.Core/Invoke-Command.md +++ b/reference/6/Microsoft.PowerShell.Core/Invoke-Command.md @@ -542,7 +542,7 @@ Use this parameter to specify the application name when you are not using the *C The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the **URLPrefix** property of a listener on the remote computer. @@ -1052,7 +1052,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see **New-PSSessionOption**. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/6/Microsoft.PowerShell.Core/New-PSSession.md b/reference/6/Microsoft.PowerShell.Core/New-PSSession.md index fb7d4e88e06d..b0c4db6eb5f0 100644 --- a/reference/6/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/6/Microsoft.PowerShell.Core/New-PSSession.md @@ -261,7 +261,7 @@ Use this parameter to specify the application name when you are not using the *C The default value is the value of the $PSSessionApplicationName preference variable on the local computer. If this preference variable is not defined, the default value is WSMAN. This value is appropriate for most uses. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). The WinRM service uses the application name to select a listener to service the connection request. The value of this parameter should match the value of the **URLPrefix** property of a listener on the remote computer. @@ -372,7 +372,7 @@ If the specified session configuration does not exist on the remote computer, th The default value is the value of the $PSSessionConfigurationName preference variable on the local computer. If this preference variable is not set, the default is Microsoft.PowerShell. -For more information, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information, see [about_Preference_Variables](About/about_Preference_Variables.md). ```yaml Type: String @@ -569,7 +569,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see New-PSSessionOption. -For information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/6/Microsoft.PowerShell.Core/New-PSSessionOption.md b/reference/6/Microsoft.PowerShell.Core/New-PSSessionOption.md index 9104938557b6..cf625d218b25 100644 --- a/reference/6/Microsoft.PowerShell.Core/New-PSSessionOption.md +++ b/reference/6/Microsoft.PowerShell.Core/New-PSSessionOption.md @@ -35,7 +35,7 @@ Because all of the properties can be edited, you can use the resulting object as You can also save a session option object in the **$PSSessionOption** preference variable. The values of this variable establish new default values for the session options. They effective when no session options are set for the session and they take precedence over options set in the session configuration, but you can override them by specifying session options or a session option object in a cmdlet that creates a session. -For more information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). When you use a session option object in a cmdlet that creates a session, the session option values take precedence over default values for sessions set in the $PSSessionOption preference variable and in the session configuration. However, they do not take precedence over maximum values, quotas or limits set in the session configuration. @@ -161,7 +161,7 @@ When the $PSSessionOption preference variable occurs in the session, it establis To make the $PSSessionOption variable available in all sessions, add it to your Windows PowerShell session and to your Windows PowerShell profile. -For more information about the $PSSessionOption preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For more information about the $PSSessionOption preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about profiles, see about_Profiles (http://go.microsoft.com/fwlink/?LinkID=113729). ### Example 6: Fulfill the requirements for a remote session configuration @@ -703,7 +703,7 @@ You cannot pipe input to this cmdlet. ### System.Management.Automation.Remoting.PSSessionOption ## NOTES -* If the *SessionOption* parameter is not used in a command to create a **PSSession**, the session options are determined by the property values of the $PSSessionOption preference variable, if it is set. For more information about the $PSSessionOption variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* If the *SessionOption* parameter is not used in a command to create a **PSSession**, the session options are determined by the property values of the $PSSessionOption preference variable, if it is set. For more information about the $PSSessionOption variable, see [about_Preference_Variables](About/about_Preference_Variables.md). * The properties of a session configuration object vary with the options set for the session configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties. ## RELATED LINKS diff --git a/reference/6/Microsoft.PowerShell.Core/Receive-PSSession.md b/reference/6/Microsoft.PowerShell.Core/Receive-PSSession.md index fa13ac6f209d..12cfd7e0e6b5 100644 --- a/reference/6/Microsoft.PowerShell.Core/Receive-PSSession.md +++ b/reference/6/Microsoft.PowerShell.Core/Receive-PSSession.md @@ -653,7 +653,7 @@ The session option values take precedence over default values for sessions set i However, they do not take precedence over maximum values, quotas or limits set in the session configuration. For a description of the session options that includes the default values, see New-PSSessionOption. -For information about the **$PSSessionOption** preference variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +For information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). ```yaml diff --git a/reference/6/Microsoft.PowerShell.Utility/Write-Verbose.md b/reference/6/Microsoft.PowerShell.Utility/Write-Verbose.md index d484fba5cdcb..5197197c370c 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Write-Verbose.md +++ b/reference/6/Microsoft.PowerShell.Utility/Write-Verbose.md @@ -113,7 +113,7 @@ You can pipe a string that contains the message to **Write-Verbose**. ## NOTES * Verbose messages are returned only when the command uses the **Verbose** common parameter. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). -* In Windows PowerShell background jobs and remote commands, the **$VerbosePreference** variable in the job session and remote session determine whether the verbose message is displayed by default. For more information about the **$VerbosePreference** variable, see about_Preference_Variables (http://go.microsoft.com/fwlink/?LinkID=113248). +* In Windows PowerShell background jobs and remote commands, the **$VerbosePreference** variable in the job session and remote session determine whether the verbose message is displayed by default. For more information about the **$VerbosePreference** variable, see [about_Preference_Variables](../Microsoft.PowerShell.Core/About/about_Preference_Variables.md). ## RELATED LINKS From 34e0059f54d982b253e757ef35bd53c0a2868b72 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Sat, 23 Dec 2017 01:26:18 +0900 Subject: [PATCH 131/188] Fix broken headers in Get-CimSession.md v6.0 (#1981) --- reference/6/CimCmdlets/Get-CimSession.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/6/CimCmdlets/Get-CimSession.md b/reference/6/CimCmdlets/Get-CimSession.md index 8cae0b6b7256..fa5a742c06e4 100644 --- a/reference/6/CimCmdlets/Get-CimSession.md +++ b/reference/6/CimCmdlets/Get-CimSession.md @@ -43,7 +43,7 @@ For more information about wps_2 sessions, see about_CimSessions ## EXAMPLES -### -------------------------- EXAMPLExample 1: Get CIM sessions from the current wps_2 session. --------------------------xample: Get CIM sessions from the current wps_2 session. +### Example 1: Get CIM sessions from the current wps_2 session ``` By default, Get-CimSession only gets information about the CIM sessions that exist in the current wps_2 session. Get-CimSession does not get CIM sessions that were created in other wps_2 sessions or that were created on other computers. PS C:\> New-CimSession -ComputerName Server01,Server02 @@ -84,7 +84,7 @@ Protocol : WSMAN This command first creates CIM sessions by using New-CimSession, and then gets the CIM sessions by using Get-CimSession. -### -------------------------- EXAMPLE xample 2: Get the CIM sessions from a specific computer --------------------------xample : Get the CIM sessions from a specific computer +### Example 2: Get the CIM sessions from a specific computer ``` PS C:\>Get-CimSession -ComputerName Server02 Id : 2 @@ -104,14 +104,14 @@ Protocol : WSMAN This command gets the CIM sessions that are connected to the computer named Server02. -### -------------------------- EXAMPLE xample 3: Get a list of CIM sessions and then format the list --------------------------xample : Get a list of CIM sessions and then format the list +### Example 3: Get a list of CIM sessions and then format the list ``` PS C:\>Get-CimSession | Format-Table -Property ComputerName,InstanceID ``` This command gets all of the CIM sessions in the current wps_2 session, and then formats the list in a table containing only the ComputerName and InstanceID parameters. -### -------------------------- EXAMPLExample 4: Get all the CIM sessions that have specific names --------------------------xample: Get all the CIM sessions that have specific names +### Example 4: Get all the CIM sessions that have specific names ``` PS C:\>Get-CimSession -ComputerName Serv* Id : 1 @@ -145,7 +145,7 @@ Protocol : WSMAN This command gets all of the CIM sessions that have names that begin with the characters serv. -### -------------------------- EXAMPLExample 5: Get a specific CIM session --------------------------xample: Get a specific CIM session +### Example 5: Get a specific CIM session ``` PS C:\>Get-CimSession -ID 2 ``` From bd76183893ad6225a169d4de58179510e678e862 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Sat, 23 Dec 2017 01:27:06 +0900 Subject: [PATCH 132/188] Update Example 1 in Import-Counter.md (#1980) --- .../3.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md | 7 ++++--- .../4.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md | 6 +++--- .../5.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md | 4 ++-- .../5.1/Microsoft.PowerShell.Diagnostics/Import-Counter.md | 6 +++--- .../6/Microsoft.PowerShell.Diagnostics/Import-Counter.md | 6 +++--- 5 files changed, 15 insertions(+), 14 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md b/reference/3.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md index 39d90e193f2a..b097e100219f 100644 --- a/reference/3.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md +++ b/reference/3.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md @@ -41,11 +41,12 @@ Along with Get-Counter and Export-Counter, this feature lets you collect, export ## EXAMPLES ### Example 1 +```powershell +$Data = Import-Counter -Path ProcessorData.csv ``` -PS C:\> $Data = Import-Counter -Path ProcessorData.csv -``` -This command imports all of the counter data from the ProcessorData.csv file into the $Data variable. +This command imports all counter data from the ProcessorData.csv file into the $Data variable. + ### Example 2 ``` PS C:\> $i = Import-Counter -Path ProcessorData.blg -Counter "\\SERVER01\Processor(_Total)\Interrupts/sec" diff --git a/reference/4.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md b/reference/4.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md index 8c01170b5809..872e3ed26800 100644 --- a/reference/4.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md +++ b/reference/4.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md @@ -44,11 +44,11 @@ Along with Get-Counter and Export-Counter, this feature lets you collect, export ## EXAMPLES ### Example 1 -``` -PS C:\> $Data = Import-Counter -Path ProcessorData.csv +```powershell +$Data = Import-Counter -Path ProcessorData.csv ``` -This command imports all of the counter data from the ProcessorData.csv file into the $Data variable. +This command imports all counter data from the ProcessorData.csv file into the $Data variable. ### Example 2 ``` diff --git a/reference/5.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md b/reference/5.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md index 4d431bfe87d4..d18d0b3c71be 100644 --- a/reference/5.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md +++ b/reference/5.0/Microsoft.PowerShell.Diagnostics/Import-Counter.md @@ -44,8 +44,8 @@ Along with the Get-Counter and Export-Counter cmdlets, this feature lets you col ## EXAMPLES ### Example 1: Import all counter data from a file -``` -PS C:\> $Data = Import-Counter -Path ProcessorData.csv +```powershell +$Data = Import-Counter -Path ProcessorData.csv ``` This command imports all counter data from the ProcessorData.csv file into the $Data variable. diff --git a/reference/5.1/Microsoft.PowerShell.Diagnostics/Import-Counter.md b/reference/5.1/Microsoft.PowerShell.Diagnostics/Import-Counter.md index 6001182cf4fb..484d70c16efc 100644 --- a/reference/5.1/Microsoft.PowerShell.Diagnostics/Import-Counter.md +++ b/reference/5.1/Microsoft.PowerShell.Diagnostics/Import-Counter.md @@ -43,9 +43,9 @@ Along with the Get-Counter and Export-Counter cmdlets, this feature lets you col ## EXAMPLES -### -------------------------- EXAMPLE xample 1: Import all counter data from a file --------------------------xample : Import all counter data from a file -``` -PS C:\> $Data = Import-Counter -Path ProcessorData.csv +### Example 1: Import all counter data from a file +```powershell +$Data = Import-Counter -Path ProcessorData.csv ``` This command imports all counter data from the ProcessorData.csv file into the $Data variable. diff --git a/reference/6/Microsoft.PowerShell.Diagnostics/Import-Counter.md b/reference/6/Microsoft.PowerShell.Diagnostics/Import-Counter.md index bfbd861f7302..02a80bca1c0b 100644 --- a/reference/6/Microsoft.PowerShell.Diagnostics/Import-Counter.md +++ b/reference/6/Microsoft.PowerShell.Diagnostics/Import-Counter.md @@ -43,9 +43,9 @@ Along with the Get-Counter and Export-Counter cmdlets, this feature lets you col ## EXAMPLES -### -------------------------- EXAMPLE xample 1: Import all counter data from a file --------------------------xample : Import all counter data from a file -``` -PS C:\> $Data = Import-Counter -Path ProcessorData.csv +### Example 1: Import all counter data from a file +```powershell +$Data = Import-Counter -Path ProcessorData.csv ``` This command imports all counter data from the ProcessorData.csv file into the $Data variable. From ce0b7c1089e5b8c90b6b26ac35e2a0e8ea4c91f6 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 22 Dec 2017 08:28:25 -0800 Subject: [PATCH 133/188] move $OFS to prefs article added note about read-only (#1978) --- .../About/about_Automatic_Variables.md | 49 ++----------------- .../About/about_Preference_Variables.md | 42 +++++++++++++++- .../About/about_Automatic_Variables.md | 49 ++----------------- .../About/about_Preference_Variables.md | 42 +++++++++++++++- .../About/about_Automatic_Variables.md | 49 ++----------------- .../About/about_Preference_Variables.md | 42 +++++++++++++++- .../About/about_Automatic_Variables.md | 49 ++----------------- .../About/about_Preference_Variables.md | 42 +++++++++++++++- .../About/about_Automatic_Variables.md | 49 ++----------------- .../About/about_Preference_Variables.md | 42 +++++++++++++++- 10 files changed, 220 insertions(+), 235 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md index 0fe7b2fae3a1..8a1c7aa5898b 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-11-27 +ms.date: 2017-12-21 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -15,6 +15,9 @@ variables are created and maintained by PowerShell. ## LONG DESCRIPTION +Conceptually, these variables are considered to be read-only. +Even though they **can** be written to, for backward compatibility they **should not** be written to. + Here is a list of the automatic variables in PowerShell: ### $$ @@ -270,50 +273,6 @@ Appointment on Tuesday: Meeting Appointment on Friday: Team lunch ``` -### $OFS - -$OFS is a special variable that stores a string that you want to use as an -output field separator. Use this variable when you are converting an array -to a string. By default, the value of $OFS is " ", but you can change the -value of $OFS in your session, by typing `$OFS=""`. If you are -expecting the default value of " " in your script, module, or configuration -output, be careful that the $OFS default value has not been changed -elsewhere in your code. - -For example: - -```powershell -$a="1","2","3","4" -$a -[string]$a -$OFS="" -[string]$a -$OFS="," -[string]$a -$OFS="--PowerShellRocks--"; -[string]$a -$OFS="`n`n"; -[string]$a -``` - -```output -1 -2 -3 -4 -1 2 3 4 -1234 -1,2,3,4 -1--PowerShellRocks--2--PowerShellRocks--3--PowerShellRocks--4 -1 - -2 - -3 - -4 -``` - ### $PID Contains the process identifier (PID) of the process that is hosting the diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 906dc159fb8a..d52a4d7a090c 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-05 +ms.date: 2017-12-21 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -835,7 +835,45 @@ Valid values: Any string. Default: Space By default, the \$OFS variable does not exist and the output file separator is -a space, but you can add this variable and set it to any string. +a space, but you can add this variable and set it to any string. You can change +the value of $OFS in your session, by typing `$OFS=""`. If you are +expecting the default value of " " in your script, module, or configuration +output, be careful that the $OFS default value has not been changed elsewhere +in your code. + +For example: + +```powershell +$a="1","2","3","4" +$a +[string]$a +$OFS="" +[string]$a +$OFS="," +[string]$a +$OFS="--PowerShellRocks--"; +[string]$a +$OFS="`n`n"; +[string]$a +``` + +```output +1 +2 +3 +4 +1 2 3 4 +1234 +1,2,3,4 +1--PowerShellRocks--2--PowerShellRocks--3--PowerShellRocks--4 +1 + +2 + +3 + +4 +``` ##### EXAMPLES diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md index 0fe7b2fae3a1..8a1c7aa5898b 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-11-27 +ms.date: 2017-12-21 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -15,6 +15,9 @@ variables are created and maintained by PowerShell. ## LONG DESCRIPTION +Conceptually, these variables are considered to be read-only. +Even though they **can** be written to, for backward compatibility they **should not** be written to. + Here is a list of the automatic variables in PowerShell: ### $$ @@ -270,50 +273,6 @@ Appointment on Tuesday: Meeting Appointment on Friday: Team lunch ``` -### $OFS - -$OFS is a special variable that stores a string that you want to use as an -output field separator. Use this variable when you are converting an array -to a string. By default, the value of $OFS is " ", but you can change the -value of $OFS in your session, by typing `$OFS=""`. If you are -expecting the default value of " " in your script, module, or configuration -output, be careful that the $OFS default value has not been changed -elsewhere in your code. - -For example: - -```powershell -$a="1","2","3","4" -$a -[string]$a -$OFS="" -[string]$a -$OFS="," -[string]$a -$OFS="--PowerShellRocks--"; -[string]$a -$OFS="`n`n"; -[string]$a -``` - -```output -1 -2 -3 -4 -1 2 3 4 -1234 -1,2,3,4 -1--PowerShellRocks--2--PowerShellRocks--3--PowerShellRocks--4 -1 - -2 - -3 - -4 -``` - ### $PID Contains the process identifier (PID) of the process that is hosting the diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 906dc159fb8a..d52a4d7a090c 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-05 +ms.date: 2017-12-21 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -835,7 +835,45 @@ Valid values: Any string. Default: Space By default, the \$OFS variable does not exist and the output file separator is -a space, but you can add this variable and set it to any string. +a space, but you can add this variable and set it to any string. You can change +the value of $OFS in your session, by typing `$OFS=""`. If you are +expecting the default value of " " in your script, module, or configuration +output, be careful that the $OFS default value has not been changed elsewhere +in your code. + +For example: + +```powershell +$a="1","2","3","4" +$a +[string]$a +$OFS="" +[string]$a +$OFS="," +[string]$a +$OFS="--PowerShellRocks--"; +[string]$a +$OFS="`n`n"; +[string]$a +``` + +```output +1 +2 +3 +4 +1 2 3 4 +1234 +1,2,3,4 +1--PowerShellRocks--2--PowerShellRocks--3--PowerShellRocks--4 +1 + +2 + +3 + +4 +``` ##### EXAMPLES diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md index 0fe7b2fae3a1..8a1c7aa5898b 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-11-27 +ms.date: 2017-12-21 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -15,6 +15,9 @@ variables are created and maintained by PowerShell. ## LONG DESCRIPTION +Conceptually, these variables are considered to be read-only. +Even though they **can** be written to, for backward compatibility they **should not** be written to. + Here is a list of the automatic variables in PowerShell: ### $$ @@ -270,50 +273,6 @@ Appointment on Tuesday: Meeting Appointment on Friday: Team lunch ``` -### $OFS - -$OFS is a special variable that stores a string that you want to use as an -output field separator. Use this variable when you are converting an array -to a string. By default, the value of $OFS is " ", but you can change the -value of $OFS in your session, by typing `$OFS=""`. If you are -expecting the default value of " " in your script, module, or configuration -output, be careful that the $OFS default value has not been changed -elsewhere in your code. - -For example: - -```powershell -$a="1","2","3","4" -$a -[string]$a -$OFS="" -[string]$a -$OFS="," -[string]$a -$OFS="--PowerShellRocks--"; -[string]$a -$OFS="`n`n"; -[string]$a -``` - -```output -1 -2 -3 -4 -1 2 3 4 -1234 -1,2,3,4 -1--PowerShellRocks--2--PowerShellRocks--3--PowerShellRocks--4 -1 - -2 - -3 - -4 -``` - ### $PID Contains the process identifier (PID) of the process that is hosting the diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 906dc159fb8a..d52a4d7a090c 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-05 +ms.date: 2017-12-21 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -835,7 +835,45 @@ Valid values: Any string. Default: Space By default, the \$OFS variable does not exist and the output file separator is -a space, but you can add this variable and set it to any string. +a space, but you can add this variable and set it to any string. You can change +the value of $OFS in your session, by typing `$OFS=""`. If you are +expecting the default value of " " in your script, module, or configuration +output, be careful that the $OFS default value has not been changed elsewhere +in your code. + +For example: + +```powershell +$a="1","2","3","4" +$a +[string]$a +$OFS="" +[string]$a +$OFS="," +[string]$a +$OFS="--PowerShellRocks--"; +[string]$a +$OFS="`n`n"; +[string]$a +``` + +```output +1 +2 +3 +4 +1 2 3 4 +1234 +1,2,3,4 +1--PowerShellRocks--2--PowerShellRocks--3--PowerShellRocks--4 +1 + +2 + +3 + +4 +``` ##### EXAMPLES diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md index 0fe7b2fae3a1..8a1c7aa5898b 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-11-27 +ms.date: 2017-12-21 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -15,6 +15,9 @@ variables are created and maintained by PowerShell. ## LONG DESCRIPTION +Conceptually, these variables are considered to be read-only. +Even though they **can** be written to, for backward compatibility they **should not** be written to. + Here is a list of the automatic variables in PowerShell: ### $$ @@ -270,50 +273,6 @@ Appointment on Tuesday: Meeting Appointment on Friday: Team lunch ``` -### $OFS - -$OFS is a special variable that stores a string that you want to use as an -output field separator. Use this variable when you are converting an array -to a string. By default, the value of $OFS is " ", but you can change the -value of $OFS in your session, by typing `$OFS=""`. If you are -expecting the default value of " " in your script, module, or configuration -output, be careful that the $OFS default value has not been changed -elsewhere in your code. - -For example: - -```powershell -$a="1","2","3","4" -$a -[string]$a -$OFS="" -[string]$a -$OFS="," -[string]$a -$OFS="--PowerShellRocks--"; -[string]$a -$OFS="`n`n"; -[string]$a -``` - -```output -1 -2 -3 -4 -1 2 3 4 -1234 -1,2,3,4 -1--PowerShellRocks--2--PowerShellRocks--3--PowerShellRocks--4 -1 - -2 - -3 - -4 -``` - ### $PID Contains the process identifier (PID) of the process that is hosting the diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 906dc159fb8a..d52a4d7a090c 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-05 +ms.date: 2017-12-21 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -835,7 +835,45 @@ Valid values: Any string. Default: Space By default, the \$OFS variable does not exist and the output file separator is -a space, but you can add this variable and set it to any string. +a space, but you can add this variable and set it to any string. You can change +the value of $OFS in your session, by typing `$OFS=""`. If you are +expecting the default value of " " in your script, module, or configuration +output, be careful that the $OFS default value has not been changed elsewhere +in your code. + +For example: + +```powershell +$a="1","2","3","4" +$a +[string]$a +$OFS="" +[string]$a +$OFS="," +[string]$a +$OFS="--PowerShellRocks--"; +[string]$a +$OFS="`n`n"; +[string]$a +``` + +```output +1 +2 +3 +4 +1 2 3 4 +1234 +1,2,3,4 +1--PowerShellRocks--2--PowerShellRocks--3--PowerShellRocks--4 +1 + +2 + +3 + +4 +``` ##### EXAMPLES diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md index 0fe7b2fae3a1..8a1c7aa5898b 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-11-27 +ms.date: 2017-12-21 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -15,6 +15,9 @@ variables are created and maintained by PowerShell. ## LONG DESCRIPTION +Conceptually, these variables are considered to be read-only. +Even though they **can** be written to, for backward compatibility they **should not** be written to. + Here is a list of the automatic variables in PowerShell: ### $$ @@ -270,50 +273,6 @@ Appointment on Tuesday: Meeting Appointment on Friday: Team lunch ``` -### $OFS - -$OFS is a special variable that stores a string that you want to use as an -output field separator. Use this variable when you are converting an array -to a string. By default, the value of $OFS is " ", but you can change the -value of $OFS in your session, by typing `$OFS=""`. If you are -expecting the default value of " " in your script, module, or configuration -output, be careful that the $OFS default value has not been changed -elsewhere in your code. - -For example: - -```powershell -$a="1","2","3","4" -$a -[string]$a -$OFS="" -[string]$a -$OFS="," -[string]$a -$OFS="--PowerShellRocks--"; -[string]$a -$OFS="`n`n"; -[string]$a -``` - -```output -1 -2 -3 -4 -1 2 3 4 -1234 -1,2,3,4 -1--PowerShellRocks--2--PowerShellRocks--3--PowerShellRocks--4 -1 - -2 - -3 - -4 -``` - ### $PID Contains the process identifier (PID) of the process that is hosting the diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 906dc159fb8a..d52a4d7a090c 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-05 +ms.date: 2017-12-21 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -835,7 +835,45 @@ Valid values: Any string. Default: Space By default, the \$OFS variable does not exist and the output file separator is -a space, but you can add this variable and set it to any string. +a space, but you can add this variable and set it to any string. You can change +the value of $OFS in your session, by typing `$OFS=""`. If you are +expecting the default value of " " in your script, module, or configuration +output, be careful that the $OFS default value has not been changed elsewhere +in your code. + +For example: + +```powershell +$a="1","2","3","4" +$a +[string]$a +$OFS="" +[string]$a +$OFS="," +[string]$a +$OFS="--PowerShellRocks--"; +[string]$a +$OFS="`n`n"; +[string]$a +``` + +```output +1 +2 +3 +4 +1 2 3 4 +1234 +1,2,3,4 +1--PowerShellRocks--2--PowerShellRocks--3--PowerShellRocks--4 +1 + +2 + +3 + +4 +``` ##### EXAMPLES From 62d8b8ae43da9eb649d9bfd27a57400362422db9 Mon Sep 17 00:00:00 2001 From: rockygiglio Date: Fri, 29 Dec 2017 22:33:55 -0500 Subject: [PATCH 134/188] Update decisionMaker.md (#1984) Slight, but critical corrections to the definition of DevOps. --- dsc/decisionMaker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dsc/decisionMaker.md b/dsc/decisionMaker.md index a21a1eaa57e5..4698a44a2d1d 100644 --- a/dsc/decisionMaker.md +++ b/dsc/decisionMaker.md @@ -37,7 +37,7 @@ Configurations are also shareable via the [PowerShell Gallery](https://powershel ## Desired State Configuration and DevOps [DevOps](http://blogs.technet.com/b/ashleymcglone/archive/2015/11/20/devops-for-n00bs-ie-windows-people.aspx) is a combination of people, -technologies, and culture that allow for rapid deployment and iteration. +process, and tools that allow for rapid deployment and iteration focused on delivering value to end users whether internal or external. DSC was designed with DevOps in mind. Having a single configuration define an environment means that developers can encode their requirements into a configuration, check that configuration into source control, and operations teams can easily deploy code without having to go through error-prone manual processes. From 6a1218ac142125195ec1fad02298daeed82a751b Mon Sep 17 00:00:00 2001 From: Brad Hards Date: Sat, 30 Dec 2017 14:34:20 +1100 Subject: [PATCH 135/188] Update configurations.md (#1985) --- dsc/configurations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dsc/configurations.md b/dsc/configurations.md index fd8a6ef94543..a8f86877b180 100644 --- a/dsc/configurations.md +++ b/dsc/configurations.md @@ -65,7 +65,7 @@ MyDscConfiguration ``` -In this example, you specify the name of the node by passing it as the **ComputerName** parameter when you compile the configuraton. The name defaults to "localhost". +In this example, you specify the name of the node by passing it as the **ComputerName** parameter when you compile the configuration. The name defaults to "localhost". ## Compiling the configuration From ccb1710b88a7bd01faea96f51eff3bb18cf0b3fe Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Wed, 3 Jan 2018 01:18:32 +0900 Subject: [PATCH 136/188] Fix parameter's position in Restart-Service.md (#1993) --- .../Restart-Service.md | 19 ++++--- .../Restart-Service.md | 17 ++++--- .../Restart-Service.md | 13 +++-- .../Restart-Service.md | 13 +++-- .../Restart-Service.md | 49 +++++-------------- 5 files changed, 49 insertions(+), 62 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Management/Restart-Service.md b/reference/3.0/Microsoft.PowerShell.Management/Restart-Service.md index 53dbed74a82a..bf7d8644dd48 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Restart-Service.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Restart-Service.md @@ -9,25 +9,30 @@ title: Restart-Service --- # Restart-Service + ## SYNOPSIS Stops and then starts one or more services. + ## SYNTAX ### InputObject (Default) ``` -Restart-Service [-Force] [-InputObject] [-PassThru] [-Include ] - [-Exclude ] [-WhatIf] [-Confirm] [] +Restart-Service [-InputObject] + [-Force] [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### Default ``` -Restart-Service [-Force] [-Name] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] - [-Confirm] [] +Restart-Service [-Name] + [-Force] [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### DisplayName ``` -Restart-Service [-Force] [-PassThru] -DisplayName [-Include ] [-Exclude ] +Restart-Service -DisplayName + [-Force] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] [] ``` @@ -138,7 +143,7 @@ Parameter Sets: InputObject Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False @@ -153,7 +158,7 @@ Parameter Sets: Default Aliases: ServiceName Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/4.0/Microsoft.PowerShell.Management/Restart-Service.md b/reference/4.0/Microsoft.PowerShell.Management/Restart-Service.md index c5bb1893694c..1ceee103a877 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Restart-Service.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Restart-Service.md @@ -17,19 +17,22 @@ Stops and then starts one or more services. ### InputObject (Default) ``` -Restart-Service [-Force] [-InputObject] [-PassThru] [-Include ] - [-Exclude ] [-WhatIf] [-Confirm] [] +Restart-Service [-InputObject] + [-Force] [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### Default ``` -Restart-Service [-Force] [-Name] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] - [-Confirm] [] +Restart-Service [-Name] + [-Force] [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### DisplayName ``` -Restart-Service [-Force] [-PassThru] -DisplayName [-Include ] [-Exclude ] +Restart-Service -DisplayName + [-Force] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] [] ``` @@ -144,7 +147,7 @@ Parameter Sets: InputObject Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False @@ -159,7 +162,7 @@ Parameter Sets: Default Aliases: ServiceName Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/5.0/Microsoft.PowerShell.Management/Restart-Service.md b/reference/5.0/Microsoft.PowerShell.Management/Restart-Service.md index 058cf5c8df33..a30b808150a7 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Restart-Service.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Restart-Service.md @@ -17,19 +17,22 @@ Stops and then starts one or more services. ### InputObject (Default) ``` -Restart-Service [-Force] [-InputObject] [-PassThru] [-Include ] - [-Exclude ] [-WhatIf] [-Confirm] [] +Restart-Service [-InputObject] + [-Force] [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### Default ``` -Restart-Service [-Force] [-Name] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] - [-Confirm] [] +Restart-Service [-Name] + [-Force] [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### DisplayName ``` -Restart-Service [-Force] [-PassThru] -DisplayName [-Include ] [-Exclude ] +Restart-Service -DisplayName + [-Force] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] [] ``` diff --git a/reference/5.1/Microsoft.PowerShell.Management/Restart-Service.md b/reference/5.1/Microsoft.PowerShell.Management/Restart-Service.md index 5acef419a0e0..1a7270212f3d 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Restart-Service.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Restart-Service.md @@ -17,19 +17,22 @@ Stops and then starts one or more services. ### InputObject (Default) ``` -Restart-Service [-Force] [-InputObject] [-PassThru] [-Include ] - [-Exclude ] [-WhatIf] [-Confirm] [] +Restart-Service [-InputObject] + [-Force] [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### Default ``` -Restart-Service [-Force] [-Name] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] - [-Confirm] [] +Restart-Service [-Name] + [-Force] [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### DisplayName ``` -Restart-Service [-Force] [-PassThru] -DisplayName [-Include ] [-Exclude ] +Restart-Service -DisplayName + [-Force] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] [] ``` diff --git a/reference/6/Microsoft.PowerShell.Management/Restart-Service.md b/reference/6/Microsoft.PowerShell.Management/Restart-Service.md index 4961451a4a8d..a1b5533651eb 100644 --- a/reference/6/Microsoft.PowerShell.Management/Restart-Service.md +++ b/reference/6/Microsoft.PowerShell.Management/Restart-Service.md @@ -17,23 +17,23 @@ Stops and then starts one or more services. ### InputObject (Default) ``` -Restart-Service [-Force] [-InputObject] [-PassThru] [-Include ] - [-Exclude ] [-InformationAction ] [-InformationVariable ] [-WhatIf] - [-Confirm] [] +Restart-Service [-InputObject] + [-Force] [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### Default ``` -Restart-Service [-Force] [-Name] [-PassThru] [-Include ] [-Exclude ] - [-InformationAction ] [-InformationVariable ] [-WhatIf] [-Confirm] - [] +Restart-Service [-Name] + [-Force] [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### DisplayName ``` -Restart-Service [-Force] [-PassThru] -DisplayName [-Include ] [-Exclude ] - [-InformationAction ] [-InformationVariable ] [-WhatIf] [-Confirm] - [] +Restart-Service -DisplayName + [-Force] [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -139,33 +139,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -InputObject Specifies **ServiceController** objects that represent the services to restart. Enter a variable that contains the objects, or type a command or expression that gets the objects. @@ -176,7 +149,7 @@ Parameter Sets: InputObject Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False @@ -191,7 +164,7 @@ Parameter Sets: Default Aliases: ServiceName Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False From 8eca7bcab860ac429774555090a2e3777580e74d Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Wed, 3 Jan 2018 01:19:24 +0900 Subject: [PATCH 137/188] Fix link for logical operators in about_Operator_Precedence.md (#1992) --- .../About/about_Operator_Precedence.md | 2 +- .../About/about_Operator_Precedence.md | 2 +- .../About/about_Operator_Precedence.md | 2 +- .../About/about_Operator_Precedence.md | 2 +- .../About/about_Operator_Precedence.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 01d129ccc4bb..de68aea9a86c 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -77,7 +77,7 @@ order: |OPERATOR |REFERENCE| |--------------------------|---------| |`-band -bor -bxor` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`-and -or -xor` |[about_comparison_operators](about_comparison_operators.md)| +|`-and -or -xor` |[about_Logical_Operators](about_logical_operators.md)| |`.` (dot-source) |[about_Scopes](about_Scopes.md)| |`&` (call) |[about_Operators](about_Operators.md)| || (pipeline operator)|[about_Operators](about_Operators.md)| diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 01d129ccc4bb..de68aea9a86c 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -77,7 +77,7 @@ order: |OPERATOR |REFERENCE| |--------------------------|---------| |`-band -bor -bxor` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`-and -or -xor` |[about_comparison_operators](about_comparison_operators.md)| +|`-and -or -xor` |[about_Logical_Operators](about_logical_operators.md)| |`.` (dot-source) |[about_Scopes](about_Scopes.md)| |`&` (call) |[about_Operators](about_Operators.md)| || (pipeline operator)|[about_Operators](about_Operators.md)| diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 01d129ccc4bb..de68aea9a86c 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -77,7 +77,7 @@ order: |OPERATOR |REFERENCE| |--------------------------|---------| |`-band -bor -bxor` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`-and -or -xor` |[about_comparison_operators](about_comparison_operators.md)| +|`-and -or -xor` |[about_Logical_Operators](about_logical_operators.md)| |`.` (dot-source) |[about_Scopes](about_Scopes.md)| |`&` (call) |[about_Operators](about_Operators.md)| || (pipeline operator)|[about_Operators](about_Operators.md)| diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 01d129ccc4bb..de68aea9a86c 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -77,7 +77,7 @@ order: |OPERATOR |REFERENCE| |--------------------------|---------| |`-band -bor -bxor` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`-and -or -xor` |[about_comparison_operators](about_comparison_operators.md)| +|`-and -or -xor` |[about_Logical_Operators](about_logical_operators.md)| |`.` (dot-source) |[about_Scopes](about_Scopes.md)| |`&` (call) |[about_Operators](about_Operators.md)| || (pipeline operator)|[about_Operators](about_Operators.md)| diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md b/reference/6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md index 01d129ccc4bb..de68aea9a86c 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md @@ -77,7 +77,7 @@ order: |OPERATOR |REFERENCE| |--------------------------|---------| |`-band -bor -bxor` |[about_Arithmetic_Operators](about_Arithmetic_Operators.md)| -|`-and -or -xor` |[about_comparison_operators](about_comparison_operators.md)| +|`-and -or -xor` |[about_Logical_Operators](about_logical_operators.md)| |`.` (dot-source) |[about_Scopes](about_Scopes.md)| |`&` (call) |[about_Operators](about_Operators.md)| || (pipeline operator)|[about_Operators](about_Operators.md)| From 272aa18e11c91a401c6a5041cefb1d6f473ee974 Mon Sep 17 00:00:00 2001 From: Brad Hards Date: Wed, 3 Jan 2018 04:03:12 +1100 Subject: [PATCH 138/188] Update scriptResource.md (#1986) Match specified GetScript rule --- dsc/scriptResource.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dsc/scriptResource.md b/dsc/scriptResource.md index 4640c8156e34..1adb5ff7a676 100644 --- a/dsc/scriptResource.md +++ b/dsc/scriptResource.md @@ -79,13 +79,13 @@ Configuration ScriptTest { GetScript = { $currentVersion = Get-Content (Join-Path -Path $env:SYSTEMDRIVE -ChildPath 'version.txt') - return @{ 'Version' = "$currentVersion" } + return @{ 'Result' = "$currentVersion" } } TestScript = { $state = $GetScript - if( $state['Version'] -eq $using:version ) + if( $state['Result'] -eq $using:version ) { - Write-Verbose -Message ('{0} -eq {1}' -f $state['Version'],$using:version) + Write-Verbose -Message ('{0} -eq {1}' -f $state['Result'],$using:version) return $true } Write-Verbose -Message ('Version up-to-date: {0}' -f $using:version) From c454e5dca161b64f22dfcf10a1bc2966894e0be0 Mon Sep 17 00:00:00 2001 From: Luc FULLENWARTH Date: Tue, 2 Jan 2018 19:07:20 +0100 Subject: [PATCH 139/188] Bad link (#1988) The link "http://go.microsoft.com/fwlink/?LinkId=119096" is supposed to point to a page or a document about "Code-Signing Best Practices". However, it points to a video about "Understanding Extension INFs and Component INFs". I watched the whole video and there is nothing inside about "Code-Signing Best Practices". The best match I have found is the following one: http://download.microsoft.com/download/a/f/7/af7777e5-7dcd-4800-8a0a-b18336565f5b/best_practices.doc It would be a very good idea to make a web page from this document. Pieces of advice it contains are still accurate. --- reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md index e5836ac5ec8e..72d6fcce99a7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md @@ -103,7 +103,7 @@ from other sources. Before you sign any script, examine each command to verify that it is safe to run. For best practices about code signing, see "Code-Signing -Best Practices" at http://go.microsoft.com/fwlink/?LinkId=119096. +Best Practices" at http://download.microsoft.com/download/a/f/7/af7777e5-7dcd-4800-8a0a-b18336565f5b/best_practices.doc. For more information about how to sign a script file, see Set-AuthenticodeSignature. From cb095ea8cf6f6021e4d0a88b7f342e4b6ae25f00 Mon Sep 17 00:00:00 2001 From: David Jones Date: Tue, 2 Jan 2018 12:08:47 -0600 Subject: [PATCH 140/188] Update Example 1 of Protect-CmsMessage (#1987) The existing example did not specify you needed to create the INF. This not only says so but does so using a script block piped to out-file --- .../Microsoft.PowerShell.Security/Protect-CmsMessage.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Security/Protect-CmsMessage.md b/reference/5.1/Microsoft.PowerShell.Security/Protect-CmsMessage.md index 894045645d19..b34df921d9ca 100644 --- a/reference/5.1/Microsoft.PowerShell.Security/Protect-CmsMessage.md +++ b/reference/5.1/Microsoft.PowerShell.Security/Protect-CmsMessage.md @@ -50,7 +50,9 @@ For an example of a certificate that would work for document encryption, see Exa ### Example 1: Create a certificate for encrypting content ``` -PS C:\> [Version] +PS C:\> # Create .INF file for certreq + +PS C:\> {[Version] Signature = "$Windows NT$" [Strings] @@ -71,8 +73,9 @@ ValidityPeriodUnits = "1000" [Extensions] %szOID_ENHANCED_KEY_USAGE% = "{text}%szOID_DOCUMENT_ENCRYPTION%" +} | Out-File -FilePath DocumentEncryption.inf -After you have created your certificate file, run the following command to add the certificate file to the certificate store.Now you are ready to encrypt and decrypt content with the next two examples. +# After you have created your certificate file, run the following command to add the certificate file to the certificate store.Now you are ready to encrypt and decrypt content with the next two examples. PS C:\> Certreq -new DocumentEncryption.inf DocumentEncryption.cer ``` From 8d405c1a2425dac99e1d4eb3394a4b9b7e07a00b Mon Sep 17 00:00:00 2001 From: Brett Hinton Date: Tue, 2 Jan 2018 11:09:11 -0700 Subject: [PATCH 141/188] Small edits for mispellings (#1989) --- dsc/configData.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dsc/configData.md b/dsc/configData.md index 6c9bbf104959..62bcd1520241 100644 --- a/dsc/configData.md +++ b/dsc/configData.md @@ -159,7 +159,7 @@ For example, you could create a file named `MyData.psd1` with the following cont ## Compiling a configuration with configuration data -To compile a configuration for which you have defined configuration data, you pass the cofiguration data as the value of the **ConfigurationData** parameter. +To compile a configuration for which you have defined configuration data, you pass the configuration data as the value of the **ConfigurationData** parameter. This will create a MOF file for each entry in the **AllNodes** array. Each MOF file will be named with the `NodeName` property of the corresponding array entry. @@ -196,8 +196,8 @@ DSC provides three special variables that can be used in a configuration script: ## Using non-node data As we've seen in previous examples, the **ConfigurationData** hashtable can have one or more keys in addition to the required **AllNodes** key. -In the examples in this topic, we have used only a single addiontal node, and named it `NonNodeData`. -However, you can define any number of addiontal keys, and name them anything you want. +In the examples in this topic, we have used only a single additional node, and named it `NonNodeData`. +However, you can define any number of additional keys, and name them anything you want. For an example of using non-node data, see [Separating configuration and environment data](separatingEnvData.md). From e777b8392c7debb21818ed7a1dd7f1b29314b36d Mon Sep 17 00:00:00 2001 From: SwarfegaGit Date: Tue, 2 Jan 2018 18:09:24 +0000 Subject: [PATCH 142/188] Corrected command (#1990) The CanPauseAndContinue property is a boolean so the correct comparison to use is $true rather than "True". --- .../5.1/Microsoft.PowerShell.Management/Suspend-Service.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Suspend-Service.md b/reference/5.1/Microsoft.PowerShell.Management/Suspend-Service.md index 021f265adbe5..56de319378ef 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Suspend-Service.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Suspend-Service.md @@ -226,7 +226,7 @@ Otherwise, this cmdlet does not generate any output. ## NOTES * **Suspend-Service** can control services only when the current user has permission to do this. If a command does not work correctly, you might not have the required permissions. -* **Suspend-Service** can suspend only services that support being suspended and resumed. To determine whether a particular service can be suspended, use the Get-Service cmdlet together with the **CanPauseAndContinue** property. For example, `Get-Service wmi | Format-List Name, CanPauseAndContinue`. To find all services on the computer that can be suspended, type `Get-Service | Where-Object {$_.CanPauseAndContinue -eq "True"}`. +* **Suspend-Service** can suspend only services that support being suspended and resumed. To determine whether a particular service can be suspended, use the Get-Service cmdlet together with the **CanPauseAndContinue** property. For example, `Get-Service wmi | Format-List Name, CanPauseAndContinue`. To find all services on the computer that can be suspended, type `Get-Service | Where-Object {$_.CanPauseAndContinue -eq $true}`. * To find the service names and display names of the services on your system, type **Get-Service**. The service names appear in the **Name** column, and the display names appear in the **DisplayName** column. ## RELATED LINKS From d0b6eb88886ed0ae51a2f8aee8eb11d145f8d93d Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 2 Jan 2018 14:32:28 -0800 Subject: [PATCH 143/188] removing module ref for modules that do not ship in v6-rc2 (#1996) --- .../Add-LocalGroupMember.md | 179 --------- .../Disable-LocalUser.md | 170 --------- .../Enable-LocalUser.md | 170 --------- .../Get-LocalGroup.md | 110 ------ .../Get-LocalGroupMember.md | 147 -------- .../Get-LocalUser.md | 134 ------- .../Microsoft.PowerShell.LocalAccounts.md | 75 ---- .../New-LocalGroup.md | 131 ------- .../New-LocalUser.md | 315 ---------------- .../Remove-LocalGroup.md | 181 --------- .../Remove-LocalGroupMember.md | 176 --------- .../Remove-LocalUser.md | 160 -------- .../Rename-LocalGroup.md | 171 --------- .../Rename-LocalUser.md | 175 --------- .../Set-LocalGroup.md | 172 --------- .../Set-LocalUser.md | 297 --------------- reference/6/Pester/AfterAll.md | 46 --- reference/6/Pester/AfterEach.md | 49 --- reference/6/Pester/Assert-MockCalled.md | 272 -------------- reference/6/Pester/Assert-VerifiableMocks.md | 66 ---- reference/6/Pester/BeforeAll.md | 46 --- reference/6/Pester/BeforeEach.md | 49 --- reference/6/Pester/Context.md | 110 ------ reference/6/Pester/Describe.md | 134 ------- .../6/Pester/Get-MockDynamicParameters.md | 124 ------ reference/6/Pester/Get-TestDriveItem.md | 61 --- reference/6/Pester/In.md | 75 ---- reference/6/Pester/InModuleScope.md | 109 ------ reference/6/Pester/Invoke-Mock.md | 164 -------- reference/6/Pester/Invoke-Pester.md | 353 ------------------ reference/6/Pester/It.md | 209 ----------- reference/6/Pester/Mock.md | 287 -------------- reference/6/Pester/New-Fixture.md | 115 ------ reference/6/Pester/Pester.md | 75 ---- .../6/Pester/Set-DynamicParameterVariables.md | 88 ----- reference/6/Pester/Setup.md | 121 ------ reference/6/Pester/Should.md | 46 --- 37 files changed, 5362 deletions(-) delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Add-LocalGroupMember.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Disable-LocalUser.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Enable-LocalUser.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalGroup.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalGroupMember.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalUser.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Microsoft.PowerShell.LocalAccounts.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/New-LocalGroup.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/New-LocalUser.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalGroup.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalGroupMember.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalUser.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Rename-LocalGroup.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Rename-LocalUser.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Set-LocalGroup.md delete mode 100644 reference/6/Microsoft.PowerShell.LocalAccounts/Set-LocalUser.md delete mode 100644 reference/6/Pester/AfterAll.md delete mode 100644 reference/6/Pester/AfterEach.md delete mode 100644 reference/6/Pester/Assert-MockCalled.md delete mode 100644 reference/6/Pester/Assert-VerifiableMocks.md delete mode 100644 reference/6/Pester/BeforeAll.md delete mode 100644 reference/6/Pester/BeforeEach.md delete mode 100644 reference/6/Pester/Context.md delete mode 100644 reference/6/Pester/Describe.md delete mode 100644 reference/6/Pester/Get-MockDynamicParameters.md delete mode 100644 reference/6/Pester/Get-TestDriveItem.md delete mode 100644 reference/6/Pester/In.md delete mode 100644 reference/6/Pester/InModuleScope.md delete mode 100644 reference/6/Pester/Invoke-Mock.md delete mode 100644 reference/6/Pester/Invoke-Pester.md delete mode 100644 reference/6/Pester/It.md delete mode 100644 reference/6/Pester/Mock.md delete mode 100644 reference/6/Pester/New-Fixture.md delete mode 100644 reference/6/Pester/Pester.md delete mode 100644 reference/6/Pester/Set-DynamicParameterVariables.md delete mode 100644 reference/6/Pester/Setup.md delete mode 100644 reference/6/Pester/Should.md diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Add-LocalGroupMember.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Add-LocalGroupMember.md deleted file mode 100644 index 5a12c590c3fa..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Add-LocalGroupMember.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822507 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Add-LocalGroupMember ---- - -# Add-LocalGroupMember - -## SYNOPSIS -Adds members to a local group. - -## SYNTAX - -### Group -``` -Add-LocalGroupMember [-Group] [-Member] [-WhatIf] [-Confirm] - [] -``` - -### Default -``` -Add-LocalGroupMember [-Member] [-Name] [-WhatIf] [-Confirm] [] -``` - -### SecurityIdentifier -``` -Add-LocalGroupMember [-Member] [-SID] [-WhatIf] [-Confirm] - [] -``` - -## DESCRIPTION -The **Add-LocalGroupMember** cmdlet adds users or groups to a local security group. -All the rights and permissions that are assigned to a group are assigned to all members of that group. - -Members of the Administrators group on a local computer have Full Control permissions on that computer. -Limit the number of users in the Administrators group. - -If the computer is joined to a domain, you can add user accounts, computer accounts, and group accounts from that domain and from trusted domains to a local group. - -## EXAMPLES - -### Example 1: Add members to the Administrators group -``` -PS C:\> Add-LocalGroupMember -Group "Administrators" -Member "Admin02", "MicrosoftAccount\username@Outlook.com", "AzureAD\DavidChew@contoso.com", "CONTOSO\Domain Admins" -``` - -This command adds several members to the local Administrators group. -The new members include a local user account, a Microsoft account, an Azure Active Directory account, and a domain group. -This example uses a placeholder value for the user name of an account at Outlook.com. - -## PARAMETERS - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Group -Specifies the security group to which this cmdlet adds members. - -```yaml -Type: LocalGroup -Parameter Sets: Group -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Member -Specifies an array of users or groups that this cmdlet adds to a security group. -You can specify users or groups by name, security ID (SID), or **LocalPrincipal** objects. - -```yaml -Type: LocalPrincipal[] -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Name -Specifies the name of the security group to which this cmdlet adds members. - -```yaml -Type: String -Parameter Sets: Default -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -SID -Specifies the security ID of the security group to which this cmdlet adds members. - -```yaml -Type: SecurityIdentifier -Parameter Sets: SecurityIdentifier -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalGroup, System.String, System.Security.Principal.SecurityIdentifier -You can pipe a local principal, a string, or a SID to this cmdlet. - -## OUTPUTS - -### None -This cmdlet does not generate any output. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Get-LocalGroupMember](Get-LocalGroupMember.md) - -[New-LocalGroup](New-LocalGroup.md) - -[Remove-LocalGroupMember](Remove-LocalGroupMember.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Disable-LocalUser.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Disable-LocalUser.md deleted file mode 100644 index 8199883c16c3..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Disable-LocalUser.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822508 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Disable-LocalUser ---- - -# Disable-LocalUser - -## SYNOPSIS -Disables a local user account. - -## SYNTAX - -### InputObject -``` -Disable-LocalUser [-InputObject] [-WhatIf] [-Confirm] [] -``` - -### Default -``` -Disable-LocalUser [-Name] [-WhatIf] [-Confirm] [] -``` - -### SecurityIdentifier -``` -Disable-LocalUser [-SID] [-WhatIf] [-Confirm] [] -``` - -## DESCRIPTION -The **Disable-LocalUser** cmdlet disables local user accounts. -When a user account is disabled, the user cannot log on. -When a user account is enabled, the user can log on. - -## EXAMPLES - -### Example 1: Disable an account by specifying a name -``` -PS C:\> Disable-LocalUser -Name "Admin02" -``` - -This command disables the user account named Admin02. - -### Example 2: Disable an account by using the pipeline -``` -PS C:\> Get-LocalUser Guest | Disable-LocalUser -``` - -This command gets the built-in Guest account by using **Get-LocalUser**, and then passes it to the current cmdlet by using the pipeline operator. -That cmdlet disables that account. - -## PARAMETERS - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InputObject -Specifies an array of user accounts that this cmdlet disables. -To obtain a user account, use the Get-LocalUser cmdlet. - -```yaml -Type: LocalUser[] -Parameter Sets: InputObject -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Name -Specifies an array of names of the user accounts that this cmdlet disables. - -```yaml -Type: String[] -Parameter Sets: Default -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -SID -Specifies an array of user accounts that this cmdlet disables. - -```yaml -Type: SecurityIdentifier[] -Parameter Sets: SecurityIdentifier -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalUser, System.String, System.Security.Principal.SecurityIdentifier -You can pipe a local user, a string, or a SID to this cmdlet. - -## OUTPUTS - -### None -This cmdlet does not generate any output. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Enable-LocalUser](Enable-LocalUser.md) - -[Get-LocalUser](Get-LocalUser.md) - -[New-LocalUser](New-LocalUser.md) - -[Remove-LocalUser](Remove-LocalUser.md) - -[Rename-LocalUser](Rename-LocalUser.md) - -[Set-LocalUser](Set-LocalUser.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Enable-LocalUser.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Enable-LocalUser.md deleted file mode 100644 index 513afc222907..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Enable-LocalUser.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822510 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Enable-LocalUser ---- - -# Enable-LocalUser - -## SYNOPSIS -Enables a local user account. - -## SYNTAX - -### InputObject -``` -Enable-LocalUser [-InputObject] [-WhatIf] [-Confirm] [] -``` - -### Default -``` -Enable-LocalUser [-Name] [-WhatIf] [-Confirm] [] -``` - -### SecurityIdentifier -``` -Enable-LocalUser [-SID] [-WhatIf] [-Confirm] [] -``` - -## DESCRIPTION -The **Enable-LocalUser** cmdlet enables local user accounts. -When a user account is disabled, the user cannot log on. -When a user account is enabled, the user can log on. - -## EXAMPLES - -### Example 1: Enable an account by specifying a name -``` -PS C:\> Enable-LocalUser -Name "Admin02" -``` - -This command enables the user account named Admin02. - -### Example 2: Enable an account by using the pipeline -``` -PS C:\> Get-LocalUser -Name "Administrator" | Enable-LocalUser -``` - -This command gets the built-in Administrator account by using **Get-LocalUser**, and then passes it to the current cmdlet by using the pipeline operator. -That cmdlet enables that account. - -## PARAMETERS - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InputObject -Specifies an array of user accounts that this cmdlet enables. -To obtain a user account, use the Get-LocalUser cmdlet. - -```yaml -Type: LocalUser[] -Parameter Sets: InputObject -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Name -Specifies an array of names of the user accounts that this cmdlet enables. - -```yaml -Type: String[] -Parameter Sets: Default -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -SID -Specifies an array of user accounts that this cmdlet enables. - -```yaml -Type: SecurityIdentifier[] -Parameter Sets: SecurityIdentifier -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalUser, System.String, System.Security.Principal.SecurityIdentifier -You can pipe a local user, a string, or a SID to this cmdlet. - -## OUTPUTS - -### None -This cmdlet does not generate any output. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Disable-LocalUser](Disable-LocalUser.md) - -[Get-LocalUser](Get-LocalUser.md) - -[New-LocalUser](New-LocalUser.md) - -[Remove-LocalUser](Remove-LocalUser.md) - -[Rename-LocalUser](Rename-LocalUser.md) - -[Set-LocalUser](Set-LocalUser.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalGroup.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalGroup.md deleted file mode 100644 index 4f33f8d9a6fb..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalGroup.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822511 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Get-LocalGroup ---- - -# Get-LocalGroup - -## SYNOPSIS -Gets the local security groups. - -## SYNTAX - -### Default (Default) -``` -Get-LocalGroup [[-Name] ] [] -``` - -### SecurityIdentifier -``` -Get-LocalGroup [[-SID] ] [] -``` - -## DESCRIPTION -The **Get-LocalGroup** cmdlet gets local security groups in Security Account Manager. -This cmdlet gets default built-in groups and local security groups that you create. - -## EXAMPLES - -### Example 1: Get the Administrators group -``` -PS C:\> Get-LocalGroup -Name "Administrators" -Name Description ----- ----------- -Administrators Administrators have complete and unrestricted access to the computer/domain -``` - -This command gets the local Administrators group. -The command displays properties of the group in the console. - -## PARAMETERS - -### -Name -Specifies an array of names of security groups that this cmdlet gets. -You can use the wildcard character. - -```yaml -Type: String[] -Parameter Sets: Default -Aliases: - -Required: False -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -SID -Specifies an array of security IDs (SIDs) of security groups that this cmdlet gets. - -```yaml -Type: SecurityIdentifier[] -Parameter Sets: SecurityIdentifier -Aliases: - -Required: False -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -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, System.Security.Principal.SecurityIdentifier -You can pipe a string or a SID to this cmdlet. - -## OUTPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalGroup -This cmdlet returns a local group. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[New-LocalGroup](New-LocalGroup.md) - -[Remove-LocalGroup](Remove-LocalGroup.md) - -[Rename-LocalGroup](Rename-LocalGroup.md) - -[Set-LocalGroup](Set-LocalGroup.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalGroupMember.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalGroupMember.md deleted file mode 100644 index 05f3ead03de3..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalGroupMember.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822512 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Get-LocalGroupMember ---- - -# Get-LocalGroupMember - -## SYNOPSIS -Gets members from a local group. - -## SYNTAX - -### Default (Default) -``` -Get-LocalGroupMember [[-Member] ] [-Name] [] -``` - -### Group -``` -Get-LocalGroupMember [-Group] [[-Member] ] [] -``` - -### SecurityIdentifier -``` -Get-LocalGroupMember [[-Member] ] [-SID] [] -``` - -## DESCRIPTION -The **Get-LocalGroupMember** cmdlet gets members from a local group. - -## EXAMPLES - -### Example 1: Get all members of the Administrators group -``` -PS C:\> Get-LocalGroupMember -Group "Administrators" -ObjectClass Name PrincipalSource ------------ ---- --------------- -User CONTOSOPC\Administrator Local -User CONTOSOPC\LocalAdmin Local -``` - -This command gets all the members of the local Administrators group. - -## PARAMETERS - -### -Group -Specifies the security group from which this cmdlet gets members. - -```yaml -Type: LocalGroup -Parameter Sets: Group -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Member -Specifies a user or group that this cmdlet gets from a security group. -You can specify users or groups by name or security ID (SID). -Specify SID strings in S-R-I-S-S . -. . -format. -You can use wildcard characters. -If you do not specify this parameter, the cmdlet gets all members of the group. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Name -Specifies the name of the security group from which this cmdlet gets members. - -```yaml -Type: String -Parameter Sets: Default -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -SID -Specifies the security ID of the security group from which this cmdlet gets members. - -```yaml -Type: SecurityIdentifier -Parameter Sets: SecurityIdentifier -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -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.SecurityAccountsManager.LocalGroup, System.String, System.Security.Principal.SecurityIdentifier -You can pipe a local group, a string, or a SID to this cmdlet. - -## OUTPUTS - -### Microsoft.SecurityAccountsManager.LocalPrincipal -This cmdlet returns local principals. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Add-LocalGroupMember](Add-LocalGroupMember.md) - -[New-LocalGroup](New-LocalGroup.md) - -[Remove-LocalGroupMember](Remove-LocalGroupMember.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalUser.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalUser.md deleted file mode 100644 index a07c2f4dc537..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Get-LocalUser.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822514 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Get-LocalUser ---- - -# Get-LocalUser - -## SYNOPSIS -Gets local user accounts. - -## SYNTAX - -### Default (Default) -``` -Get-LocalUser [[-Name] ] [] -``` - -### SecurityIdentifier -``` -Get-LocalUser [[-SID] ] [] -``` - -## DESCRIPTION -The **Get-LocalUser** cmdlet gets local user accounts. -This cmdlet gets default built-in user accounts, local user accounts that you created, and local accounts that you connected to Microsoft accounts. - -## EXAMPLES - -### Example 1: Get an account by using its name -``` -PS C:\> Get-LocalUser -Name "AdminContoso02" -Name Enabled Description ----- ------- ----------- -AdminContoso02 True Description of this account. -``` - -This command gets a user account named AdminContoso02. - -### Example 2: Get an account that is connected to a Microsoft account -``` -PS C:\> Get-LocalUser -Name "MicrosoftAccount\username@Outlook.com" -Name Enabled Description ----- ------- ----------- -MicrosoftAccount\user name@outlook.com True Description of this account. -``` - -This command gets a user account that is connected to a Microsoft account. -This example uses a placeholder value for the user name of an account at Outlook.com. - -### Example 3: Get an account that is connected to a Microsoft account -``` -PS C:\> Get-LocalUser -SecurityIdentifier "S-1-5-2" -Name Enabled Description ----- ------- ----------- -MicrosoftAccount\user name@contoso.com True Description of this account. -``` - -This command gets a local user account that has the specified SID. - -## PARAMETERS - -### -Name -Specifies an array of names of user accounts that this cmdlet gets. -You can use the wildcard character. - -```yaml -Type: String[] -Parameter Sets: Default -Aliases: - -Required: False -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -SID -Specifies an array of security IDs (SIDs) of user accounts that this cmdlet gets. - -```yaml -Type: SecurityIdentifier[] -Parameter Sets: SecurityIdentifier -Aliases: - -Required: False -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -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, System.Security.Principal.SecurityIdentifier -You can pipe a string or SID to this cmdlet. - -## OUTPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalUser[] -This cmdlet returns local user accounts. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Disable-LocalUser](Disable-LocalUser.md) - -[Enable-LocalUser](Enable-LocalUser.md) - -[New-LocalUser](New-LocalUser.md) - -[Remove-LocalUser](Remove-LocalUser.md) - -[Rename-LocalUser](Rename-LocalUser.md) - -[Set-LocalUser](Set-LocalUser.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Microsoft.PowerShell.LocalAccounts.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Microsoft.PowerShell.LocalAccounts.md deleted file mode 100644 index 69f69afe3e2f..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Microsoft.PowerShell.LocalAccounts.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-US -keywords: powershell,cmdlet -Help Version: 6.0 -Download Help Link: http://Please-enter-FwLink-manually -Module Guid: 8e362604-2c0b-448f-a414-a6a690a644e2 -title: Microsoft.PowerShell.LocalAccounts -Module Name: Microsoft.PowerShell.LocalAccounts ---- - -# Microsoft.PowerShell.LocalAccounts Module -## Description -This section contains the help topics for the Local Accounts cmdlets in Windows PowerShell. - -## Microsoft.PowerShell.LocalAccounts Cmdlets -### [Add-LocalGroupMember](Add-LocalGroupMember.md) -Adds members to a local group. - - -### [Disable-LocalUser](Disable-LocalUser.md) -Disables a local user account. - - -### [Enable-LocalUser](Enable-LocalUser.md) -Enables a local user account. - - -### [Get-LocalGroup](Get-LocalGroup.md) -Gets the local security groups. - - -### [Get-LocalGroupMember](Get-LocalGroupMember.md) -Gets members from a local group. - - -### [Get-LocalUser](Get-LocalUser.md) -Gets local user accounts. - - -### [New-LocalGroup](New-LocalGroup.md) -Creates a local security group. - - -### [New-LocalUser](New-LocalUser.md) -Creates a local user account. - - -### [Remove-LocalGroup](Remove-LocalGroup.md) -Deletes local security groups. - - -### [Remove-LocalGroupMember](Remove-LocalGroupMember.md) -Removes members from a local group. - - -### [Remove-LocalUser](Remove-LocalUser.md) -Deletes local user accounts. - - -### [Rename-LocalGroup](Rename-LocalGroup.md) -Renames a local security group. - - -### [Rename-LocalUser](Rename-LocalUser.md) -Renames a local user account. - - -### [Set-LocalGroup](Set-LocalGroup.md) -Changes a local security group. - - -### [Set-LocalUser](Set-LocalUser.md) -Modifies a local user account. diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/New-LocalGroup.md b/reference/6/Microsoft.PowerShell.LocalAccounts/New-LocalGroup.md deleted file mode 100644 index a43f56baa414..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/New-LocalGroup.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822515 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: New-LocalGroup ---- - -# New-LocalGroup - -## SYNOPSIS -Creates a local security group. - -## SYNTAX - -``` -New-LocalGroup [-Description ] [-Name] [-WhatIf] [-Confirm] [] -``` - -## DESCRIPTION -The **New-LocalGroup** cmdlet creates a local security group in the Security Account Manager. - -## EXAMPLES - -### Example 1: Create a security group -``` -PS C:\> New-LocalGroup -Name "SecurityGroup04" -``` - -This command creates a group named SecurityGroup04. - -## PARAMETERS - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Description -Specifies a comment for the group. -The maximum length is 48 characters. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -Name -Specifies a name for the group. -The maximum length is 256 characters. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String -You can pipe a string to this cmdlet. - -## OUTPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalGroup -This cmdlet returns a security group. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Get-LocalGroup](Get-LocalGroup.md) - -[Remove-LocalGroup](Remove-LocalGroup.md) - -[Rename-LocalGroup](Rename-LocalGroup.md) - -[Set-LocalGroup](Set-LocalGroup.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/New-LocalUser.md b/reference/6/Microsoft.PowerShell.LocalAccounts/New-LocalUser.md deleted file mode 100644 index d3a89f15fea1..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/New-LocalUser.md +++ /dev/null @@ -1,315 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822516 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: New-LocalUser ---- - -# New-LocalUser - -## SYNOPSIS -Creates a local user account. - -## SYNTAX - -### Password (Default) -``` -New-LocalUser [-AccountExpires ] [-AccountNeverExpires] [-Description ] [-Disabled] - [-FullName ] [-Name] -Password [-PasswordNeverExpires] - [-UserMayNotChangePassword] [-WhatIf] [-Confirm] [] -``` - -### NoPassword -``` -New-LocalUser [-AccountExpires ] [-AccountNeverExpires] [-Description ] [-Disabled] - [-FullName ] [-Name] [-NoPassword] [-UserMayNotChangePassword] [-WhatIf] [-Confirm] - [] -``` - -## DESCRIPTION -The **New-LocalUser** cmdlet creates a local user account. -This cmdlet creates a local user account or a local user account that is connected to a Microsoft account. - -## EXAMPLES - -### Example 1: Create a user account -``` -PS C:\> New-LocalUser -Name "User02" -Description "Description of this account." -NoPassword -Name Enabled Description ----- ------- ----------- -User02 True Description of this account. -``` - -This command creates a local user account. -The command does not specify the *AccountExpires* parameter. -Therefore, the account does not expire. - -### Example 2: Create a user account that has a password -``` -PS C:\> $Password = Read-Host -AsSecureString -PS C:\> New-LocalUser "User03" -Password $Password -FullName "Third User" -Description "Description of this account." -Name Enabled Description ----- ------- ----------- -User03 True Description of this account. -``` - -The first command prompts you for a password by using the Read-Host cmdlet. -The command stores the password as a secure string in the $Password variable. - -The second command creates a local user account by using the password stored in $Password. -The command specifies a user name, full name, and description for the user account. - -### Example 3: Create a user account that is connected to a Microsoft account -``` -PS C:\> New-LocalUser -Name "MicrosoftAccount\usr name@Outlook.com" -Description "Description of this account." -``` - -This command creates a local user account that is connected to a Microsoft account. -This example uses a placeholder value for the user name of an account at Outlook.com. -Because the account is connected to a Microsoft account, do not specify a password. - -## PARAMETERS - -### -AccountExpires -Specifies when the user account expires. -To obtain a **DateTime** object, use the Get-Date cmdlet. -If you do not specify this parameter, the account does not expire. - -```yaml -Type: DateTime -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -AccountNeverExpires -Indicates that the account does not expire. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Description -Specifies a comment for the user account. -The maximum length is 48 characters. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -Disabled -Indicates that this cmdlet creates the user account as disabled. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -FullName -Specifies the full name for the user account. -The full name differs from the user name of the user account. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -Name -Specifies the user name for the user account. - -If you create a local user account that is connected to a Microsoft account, specify the user name in the following format: `MicrosoftAccount\\`\@`Outlook.com` for a user of a Microsoft account on Outlook.com. - -If you create a local user account for the local system, the user name can contain up to 20 uppercase characters or lowercase characters. -A user name cannot contain the following characters: - -" / \ \[ \] : ; | = , + * ? -\< \> @ - -A user name cannot consist only of periods (.) or spaces. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -NoPassword -Indicates that the user account does not have a password. - -```yaml -Type: SwitchParameter -Parameter Sets: NoPassword -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -Password -Specifies a password for the user account. -You can use `Read-Host -GetCredential`, Get-Credential, or ConvertTo-SecureString to create a **SecureString** object for the password. - -If you omit the *Password* and *NoPassword* parameters, **New-LocalUser** prompts you for the new user's password. - -```yaml -Type: SecureString -Parameter Sets: Password -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -PasswordNeverExpires -Indicates whether the password expires. - -```yaml -Type: SwitchParameter -Parameter Sets: Password -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -UserMayNotChangePassword -Indicates that the user cannot change the password on the user account. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: True (ByPropertyName) -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String, System.DateTime, System.Boolean, System.Security.SecureString -You can pipe a string, a **DateTime** object, a **Boolean** value, or a secure string to this cmdlet. - -## OUTPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalUser -This cmdlet returns a **LocalUser** object. -This object provides information about the user account. - -## NOTES -* A user name cannot be identical to any other user name or group name on the computer. A user name cannot consist only of periods (.) or spaces. A user name can contain up to 20 uppercase characters or lowercase characters. A user name cannot contain the following characters: - -" / \ \[ \] : ; | = , + * ? \< \> @ -* A password can contain up to 127 characters. -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Disable-LocalUser](Disable-LocalUser.md) - -[Enable-LocalUser](Enable-LocalUser.md) - -[Get-LocalUser](Get-LocalUser.md) - -[Remove-LocalUser](Remove-LocalUser.md) - -[Rename-LocalUser](Rename-LocalUser.md) - -[Set-LocalUser](Set-LocalUser.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalGroup.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalGroup.md deleted file mode 100644 index afd958333f2e..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalGroup.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822517 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Remove-LocalGroup ---- - -# Remove-LocalGroup - -## SYNOPSIS -Deletes local security groups. - -## SYNTAX - -### InputObject -``` -Remove-LocalGroup [-InputObject] [-WhatIf] [-Confirm] [] -``` - -### Default -``` -Remove-LocalGroup [-Name] [-WhatIf] [-Confirm] [] -``` - -### SecurityIdentifier -``` -Remove-LocalGroup [-SID] [-WhatIf] [-Confirm] [] -``` - -## DESCRIPTION -The **Remove-LocalGroup** cmdlet deletes local security groups. -This cmdlet deletes only a local group. -It does not delete the user accounts, computer accounts, or group accounts that belong to that group. -You cannot recover a deleted group. - -If you delete a group and then create another group that has the same group name, you must set new permissions for the new group. -The new group does not inherit the permissions that were assigned to the group. - -## EXAMPLES - -### Example 1: Delete a security group -``` -PS C:\> Remove-LocalGroup -Name "SecurityGroup04" -``` - -This command deletes the group named SecurityGroup04. - -## PARAMETERS - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InputObject -Specifies an array of security groups that this cmdlet deletes. -To obtain groups, use the Get-LocalGroup cmdlet. - -```yaml -Type: LocalGroup[] -Parameter Sets: InputObject -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Name -Specifies an array of names of the security groups that this cmdlet deletes. - -```yaml -Type: String[] -Parameter Sets: Default -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -SID -Specifies an array of security IDs (SIDs) of security groups that this cmdlet deletes. - -```yaml -Type: SecurityIdentifier[] -Parameter Sets: SecurityIdentifier -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalGroup, System.String, System.Security.Principal.SecurityIdentifier -You can pipe a security group, a string, or a SID to this cmdlet. - -## OUTPUTS - -### None -This cmdlet does not generate any output. - -## NOTES -* This cmdlet cannot delete the following default groups: - -- Administrators -- Backup Operators -- Cryptographic Operators -- Distributed COM Users -- Event Log Readers -- Guests -- Hyper-V Administrators -- IIS_IUSRS -- Network Configuration Operators -- Performance Log Users -- Performance Monitor Users -- Power Users -- Remote Desktop Users -- Remote Management Users -- Replicator -- Users -- WinRMRemoteWMIUsers__ -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Get-LocalGroup](Get-LocalGroup.md) - -[New-LocalGroup](New-LocalGroup.md) - -[Rename-LocalGroup](Rename-LocalGroup.md) - -[Set-LocalGroup](Set-LocalGroup.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalGroupMember.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalGroupMember.md deleted file mode 100644 index b14a7ae141db..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalGroupMember.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822518 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Remove-LocalGroupMember ---- - -# Remove-LocalGroupMember - -## SYNOPSIS -Removes members from a local group. - -## SYNTAX - -### Group -``` -Remove-LocalGroupMember [-Group] [-Member] [-WhatIf] [-Confirm] - [] -``` - -### Default -``` -Remove-LocalGroupMember [-Member] [-Name] [-WhatIf] [-Confirm] [] -``` - -### SecurityIdentifier -``` -Remove-LocalGroupMember [-Member] [-SID] [-WhatIf] [-Confirm] - [] -``` - -## DESCRIPTION -The **Remove-LocalGroupMember** cmdlet removes users or groups from a local group. - -## EXAMPLES - -### Example 1: Remove members from the Administrators group -``` -PS C:\> Remove-LocalGroupMember -Group "Administrators" -Member "Admin02", "MicrosoftAccount\username@Outlook.com", "AzureAD\DavidChew@contoso.com", "CONTOSO\Domain Admins" -``` - -This command removes several members from the local Administrators group. -The members that this cmdlet removes include a local user account, a Microsoft account, an Azure Active Directory account, and a domain group. -This example uses a placeholder value for the user name of an account at Outlook.com. - -## PARAMETERS - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Group -Specifies the security group from which this cmdlet removes members. - -```yaml -Type: LocalGroup -Parameter Sets: Group -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Member -Specifies an array of users or groups that this cmdlet removes from a security group. -You can specify users or groups by name, security ID (SID), or **LocalPrincipal** objects. -Specify SID strings in S-R-I-S-S . -. . -format. - -```yaml -Type: LocalPrincipal[] -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Name -Specifies the name of the security group from which this cmdlet removes members. - -```yaml -Type: String -Parameter Sets: Default -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -SID -Specifies the security ID of the security group from which this cmdlet removes members. - -```yaml -Type: SecurityIdentifier -Parameter Sets: SecurityIdentifier -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalPrincipal, System.String, System.Security.Principal.SecurityIdentifier -You can pipe a local principal, a string, or a SID to this cmdlet. - -## OUTPUTS - -### None -This cmdlet does not generate any output. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Add-LocalGroupMember](Add-LocalGroupMember.md) - -[Get-LocalGroupMember](Get-LocalGroupMember.md) - -[New-LocalGroup](New-LocalGroup.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalUser.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalUser.md deleted file mode 100644 index 7ef7bbc5fccb..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Remove-LocalUser.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822519 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Remove-LocalUser ---- - -# Remove-LocalUser - -## SYNOPSIS -Deletes local user accounts. - -## SYNTAX - -### InputObject -``` -Remove-LocalUser [-InputObject] [-WhatIf] [-Confirm] [] -``` - -### Default -``` -Remove-LocalUser [-Name] [-WhatIf] [-Confirm] [] -``` - -### SecurityIdentifier -``` -Remove-LocalUser [-SID] [-WhatIf] [-Confirm] [] -``` - -## DESCRIPTION -The **Remove-LocalUser** cmdlet deletes local user accounts. - -## EXAMPLES - -### Example 1: Delete a user account -``` -PS C:\> Remove-LocalUser -Name "AdminContoso02" -``` - -This command deletes the user account named AdminContoso02. - -## PARAMETERS - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InputObject -Specifies an array of user accounts that this cmdlet deletes. -To obtain a user account, use the Get-LocalUser cmdlet. - -```yaml -Type: LocalUser[] -Parameter Sets: InputObject -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Name -Specifies an array of names of the user accounts that this cmdlet deletes. - -```yaml -Type: String[] -Parameter Sets: Default -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -SID -Specifies an array of security IDs (SIDs) of user accounts that this cmdlet deletes. - -```yaml -Type: SecurityIdentifier[] -Parameter Sets: SecurityIdentifier -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalUser, System.String, System.Security.Principal.SecurityIdentifier -You can pipe a local user, a string, or a SID to this cmdlet. - -## OUTPUTS - -### None -This cmdlet does not generate any output. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Disable-LocalUser](Disable-LocalUser.md) - -[Enable-LocalUser](Enable-LocalUser.md) - -[Get-LocalUser](Get-LocalUser.md) - -[New-LocalUser](New-LocalUser.md) - -[Rename-LocalUser](Rename-LocalUser.md) - -[Set-LocalUser](Set-LocalUser.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Rename-LocalGroup.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Rename-LocalGroup.md deleted file mode 100644 index 0d88c9795788..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Rename-LocalGroup.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822520 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Rename-LocalGroup ---- - -# Rename-LocalGroup - -## SYNOPSIS -Renames a local security group. - -## SYNTAX - -### InputObject -``` -Rename-LocalGroup [-InputObject] [-NewName] [-WhatIf] [-Confirm] [] -``` - -### Default -``` -Rename-LocalGroup [-Name] [-NewName] [-WhatIf] [-Confirm] [] -``` - -### SecurityIdentifier -``` -Rename-LocalGroup [-NewName] [-SID] [-WhatIf] [-Confirm] [] -``` - -## DESCRIPTION -The **Rename-LocalGroup** cmdlet renames a local security group. - -## EXAMPLES - -### Example 1: Change the name of a group -``` -PS C:\> Rename-LocalGroup -Name "SecurityGroup" -NewName "SecurityGroup04" -``` - -This command renames a security group named SecurityGroup. - -## PARAMETERS - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InputObject -Specifies the security group that this cmdlet renames. -To obtain a security group, use the Get-LocalGroup cmdlet. - -```yaml -Type: LocalGroup -Parameter Sets: InputObject -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Name -Specifies the name of the security group that this cmdlet renames. - -```yaml -Type: String -Parameter Sets: Default -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -NewName -Specifies a new name for the security group. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -SID -Specifies the security ID (SID) of a security group that this cmdlet renames. - -```yaml -Type: SecurityIdentifier -Parameter Sets: SecurityIdentifier -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalGroup, System.String, System.Security.Principal.SecurityIdentifier -You can pipe a security group, a string, or a SID to this cmdlet. - -## OUTPUTS - -### None -This cmdlet does not generate any output. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Get-LocalGroup](Get-LocalGroup.md) - -[New-LocalGroup](New-LocalGroup.md) - -[Remove-LocalGroup](Remove-LocalGroup.md) - -[Set-LocalGroup](Set-LocalGroup.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Rename-LocalUser.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Rename-LocalUser.md deleted file mode 100644 index fced244875f7..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Rename-LocalUser.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822521 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Rename-LocalUser ---- - -# Rename-LocalUser - -## SYNOPSIS -Renames a local user account. - -## SYNTAX - -### InputObject -``` -Rename-LocalUser [-InputObject] [-NewName] [-WhatIf] [-Confirm] [] -``` - -### Default -``` -Rename-LocalUser [-Name] [-NewName] [-WhatIf] [-Confirm] [] -``` - -### SecurityIdentifier -``` -Rename-LocalUser [-NewName] [-SID] [-WhatIf] [-Confirm] [] -``` - -## DESCRIPTION -The **Rename-LocalUser** cmdlet renames a local user account. - -## EXAMPLES - -### Example 1: Rename a user account -``` -PS C:\> Rename-LocalUser -Name "Admin02" -NewName "AdminContoso02" -``` - -This command renames the user account named Admin02. - -## PARAMETERS - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InputObject -Specifies the user account that this cmdlet renames. -To obtain a user account, use the Get-LocalUser cmdlet. - -```yaml -Type: LocalUser -Parameter Sets: InputObject -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Name -Specifies the name of the user account that this cmdlet renames. - -```yaml -Type: String -Parameter Sets: Default -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -NewName -Specifies a new name for the user account. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -SID -Specifies the security ID (SID) of a user accounts that this cmdlet renames. - -```yaml -Type: SecurityIdentifier -Parameter Sets: SecurityIdentifier -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalUser, System.String, System.Security.Principal.SecurityIdentifier -You can pipe a local user, a string, or a SID to this cmdlet. - -## OUTPUTS - -### None -This cmdlet does not generate any output. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Disable-LocalUser](Disable-LocalUser.md) - -[Enable-LocalUser](Enable-LocalUser.md) - -[Get-LocalUser](Get-LocalUser.md) - -[New-LocalUser](New-LocalUser.md) - -[Remove-LocalUser](Remove-LocalUser.md) - -[Set-LocalUser](Set-LocalUser.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Set-LocalGroup.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Set-LocalGroup.md deleted file mode 100644 index 238d5bd6a331..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Set-LocalGroup.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822522 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Set-LocalGroup ---- - -# Set-LocalGroup - -## SYNOPSIS -Changes a local security group. - -## SYNTAX - -### InputObject -``` -Set-LocalGroup -Description [-InputObject] [-WhatIf] [-Confirm] [] -``` - -### Default -``` -Set-LocalGroup -Description [-Name] [-WhatIf] [-Confirm] [] -``` - -### SecurityIdentifier -``` -Set-LocalGroup -Description [-SID] [-WhatIf] [-Confirm] [] -``` - -## DESCRIPTION -The **Set-LocalGroup** cmdlet changes a local security group. - -## EXAMPLES - -### Example 1: Change a group description -``` -PS C:\> Set-LocalGroup -Name "SecurityGroup04" -Description "This is a sample description." -``` - -This command changes the description of a local group. - -## PARAMETERS - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Description -Specifies a comment for the group. -The maximum length is 48 characters. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InputObject -Specifies the security group that this cmdlet changes. -To obtain a security group, use the Get-LocalGroup cmdlet. - -```yaml -Type: LocalGroup -Parameter Sets: InputObject -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Name -Specifies the name of the security group that this cmdlet changes. - -```yaml -Type: String -Parameter Sets: Default -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -SID -Specifies the security ID (SID) of the security group that this cmdlet changes. - -```yaml -Type: SecurityIdentifier -Parameter Sets: SecurityIdentifier -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalGroup, System.String, System.Security.Principal.SecurityIdentifier -You can pipe a security group, a string, or a SID to this cmdlet. - -## OUTPUTS - -### None -This cmdlet does not generate any output. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Get-LocalGroup](Get-LocalGroup.md) - -[New-LocalGroup](New-LocalGroup.md) - -[Remove-LocalGroup](Remove-LocalGroup.md) - -[Rename-LocalGroup](Rename-LocalGroup.md) - diff --git a/reference/6/Microsoft.PowerShell.LocalAccounts/Set-LocalUser.md b/reference/6/Microsoft.PowerShell.LocalAccounts/Set-LocalUser.md deleted file mode 100644 index f04f6453896c..000000000000 --- a/reference/6/Microsoft.PowerShell.LocalAccounts/Set-LocalUser.md +++ /dev/null @@ -1,297 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -online version: http://go.microsoft.com/fwlink/?LinkId=822523 -external help file: Microsoft.Powershell.LocalAccounts.dll-Help.xml -title: Set-LocalUser ---- - -# Set-LocalUser - -## SYNOPSIS -Modifies a local user account. - -## SYNTAX - -### Name (Default) -``` -Set-LocalUser [-AccountExpires ] [-AccountNeverExpires] [-Description ] [-FullName ] - [-Name] [-Password ] [-PasswordNeverExpires ] - [-UserMayChangePassword ] [-WhatIf] [-Confirm] [] -``` - -### InputObject -``` -Set-LocalUser [-AccountExpires ] [-AccountNeverExpires] [-Description ] [-FullName ] - [-InputObject] [-Password ] [-PasswordNeverExpires ] - [-UserMayChangePassword ] [-WhatIf] [-Confirm] [] -``` - -### SecurityIdentifier -``` -Set-LocalUser [-AccountExpires ] [-AccountNeverExpires] [-Description ] [-FullName ] - [-Password ] [-PasswordNeverExpires ] [-SID] - [-UserMayChangePassword ] [-WhatIf] [-Confirm] [] -``` - -## DESCRIPTION -The **Set-LocalUser** cmdlet modifies a local user account. -This cmdlet can reset the password of a local user account. - -## EXAMPLES - -### Example 1: Change a description of a user account -``` -PS C:\> Set-LocalUser -Name "Admin07" -Description "Description of this account." -``` - -This command changes the description of a user account named Admin07. - -### Example 2: Change the password on an account -``` -PS C:\> $Password = Read-Host -AsSecureString -PS C:\> $UserAccount = Get-LocalUser -Name "User02" -PS C:\> $UserAccount | Set-LocalUser -Password $Password -``` - -The first command prompts you for a password by using the Read-Host cmdlet. -The command stores the password as a secure string in the $Password variable. - -The second command gets a user account named User02 by using **Get-LocalUser**. -The command stores the account in the $UserAccount variable. - -The third command sets the new password on the user account stored in $UserAccount. - -## PARAMETERS - -### -AccountExpires -Specifies when the user account expires. -To obtain a **DateTime** object, use the Get-Date cmdlet. - -If you do not want the account to expire, specify the *AccountNeverExpires* parameter. - -```yaml -Type: DateTime -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -AccountNeverExpires -Indicates that the account does not expire. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Confirm -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Description -Specifies a comment for the user account. -The maximum length is 48 characters. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -FullName -Specifies the full name for the user account. -The full name differs from the user name of the user account. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InputObject -Specifies the user account that this cmdlet changes. -To obtain a user account, use the Get-LocalUser cmdlet. - -```yaml -Type: LocalUser -Parameter Sets: InputObject -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Name -Specifies the name of the user account that this cmdlet changes. - -```yaml -Type: String -Parameter Sets: Name -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -Password -Specifies a password for the user account. -If the user account is connected to a Microsoft account, do not set a password. - -You can use `Read-Host -GetCredential`, Get-Credential, or ConvertTo-SecureString to create a **SecureString** object for the password. - -If you omit the *Password* and *NoPassword* parameters, **Set-LocalUser** prompts you for the user's password. - -```yaml -Type: SecureString -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -PasswordNeverExpires -Indicates whether the password expires. - -```yaml -Type: Boolean -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -SID -Specifies the security ID (SID) of the user account that this cmdlet changes. - -```yaml -Type: SecurityIdentifier -Parameter Sets: SecurityIdentifier -Aliases: - -Required: True -Position: 0 -Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: False -``` - -### -UserMayChangePassword -Indicates that the user can change the password on the user account. - -```yaml -Type: Boolean -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: wi - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.SecurityAccountsManager.LocalUser, System.String, System.Security.Principal.SecurityIdentifier -You can pipe a local user, a string, or a SID to this cmdlet. - -## OUTPUTS - -### None -This cmdlet does not generate any output. - -## NOTES -* The **PrincipalSource** property is a property on **LocalUser**, **LocalGroup**, and **LocalPrincipal** objects that describes the source of the object. The possible sources are as follows: - -- Local -- Active Directory -- Azure Active Directory group -- Microsoft Account - -**PrincipalSource** is supported only by Windows 10, Windows Server 2016, and later versions of the Windows operating system. For earlier versions, the property is blank. - -## RELATED LINKS - -[Disable-LocalUser](Disable-LocalUser.md) - -[Enable-LocalUser](Enable-LocalUser.md) - -[Get-LocalUser](Get-LocalUser.md) - -[New-LocalUser](New-LocalUser.md) - -[Remove-LocalUser](Remove-LocalUser.md) - -[Rename-LocalUser](Rename-LocalUser.md) - diff --git a/reference/6/Pester/AfterAll.md b/reference/6/Pester/AfterAll.md deleted file mode 100644 index 01b5b6e83bac..000000000000 --- a/reference/6/Pester/AfterAll.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# AfterAll - -## SYNOPSIS -Defines a series of steps to perform at the end of every It block within -the current Context or Describe block. - -## SYNTAX - -``` -AfterAll -``` - -## DESCRIPTION -BeforeEach, AfterEach, BeforeAll, and AfterAll are unique in that they apply -to the entire Context or Describe block, regardless of the order of the -statements in the Context or Describe. - -## EXAMPLES - -### Example 1 -``` -PS C:\> {{ Add example code here }} -``` - -{{ Add example description here }} - -## PARAMETERS - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[about_BeforeEach_AfterEach]() - diff --git a/reference/6/Pester/AfterEach.md b/reference/6/Pester/AfterEach.md deleted file mode 100644 index 8ba9f6673413..000000000000 --- a/reference/6/Pester/AfterEach.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# AfterEach - -## SYNOPSIS -Defines a series of steps to perform at the end of every It block within -the current Context or Describe block. - -## SYNTAX - -``` -AfterEach -``` - -## DESCRIPTION -BeforeEach, AfterEach, BeforeAll, and AfterAll are unique in that they apply -to the entire Context or Describe block, regardless of the order of the -statements in the Context or Describe. -For a full description of this -behavior, as well as how multiple BeforeEach or AfterEach blocks interact -with each other, please refer to the about_BeforeEach_AfterEach help file. - -## EXAMPLES - -### Example 1 -``` -PS C:\> {{ Add example code here }} -``` - -{{ Add example description here }} - -## PARAMETERS - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[about_BeforeEach_AfterEach]() - diff --git a/reference/6/Pester/Assert-MockCalled.md b/reference/6/Pester/Assert-MockCalled.md deleted file mode 100644 index f59cd0ef26dc..000000000000 --- a/reference/6/Pester/Assert-MockCalled.md +++ /dev/null @@ -1,272 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Assert-MockCalled - -## SYNOPSIS -Checks if a Mocked command has been called a certain number of times -and throws an exception if it has not. - -## SYNTAX - -### ParameterFilter (Default) -``` -Assert-MockCalled [-CommandName] [[-Times] ] [[-ParameterFilter] ] - [[-ModuleName] ] [[-Scope] ] [-Exactly] -``` - -### ExclusiveFilter -``` -Assert-MockCalled [-CommandName] [[-Times] ] -ExclusiveFilter - [[-ModuleName] ] [[-Scope] ] [-Exactly] -``` - -## DESCRIPTION -This command verifies that a mocked command has been called a certain number -of times. -If the call history of the mocked command does not match the parameters -passed to Assert-MockCalled, Assert-MockCalled will throw an exception. - -## EXAMPLES - -### -------------------------- EXAMPLE 1 -------------------------- -``` -Mock Set-Content {} -``` - -{... -Some Code ...} - -C:\PS\>Assert-MockCalled Set-Content - -This will throw an exception and cause the test to fail if Set-Content is not called in Some Code. - -### -------------------------- EXAMPLE 2 -------------------------- -``` -Mock Set-Content -parameterFilter {$path.StartsWith("$env:temp\")} -``` - -{... -Some Code ...} - -C:\PS\>Assert-MockCalled Set-Content 2 { $path -eq "$env:temp\test.txt" } - -This will throw an exception if some code calls Set-Content on $path=$env:temp\test.txt less than 2 times - -### -------------------------- EXAMPLE 3 -------------------------- -``` -Mock Set-Content {} -``` - -{... -Some Code ...} - -C:\PS\>Assert-MockCalled Set-Content 0 - -This will throw an exception if some code calls Set-Content at all - -### -------------------------- EXAMPLE 4 -------------------------- -``` -Mock Set-Content {} -``` - -{... -Some Code ...} - -C:\PS\>Assert-MockCalled Set-Content -Exactly 2 - -This will throw an exception if some code does not call Set-Content Exactly two times. - -### -------------------------- EXAMPLE 5 -------------------------- -``` -Describe 'Assert-MockCalled Scope behavior' { -``` - -Mock Set-Content { } - - It 'Calls Set-Content at least once in the It block' { - {... -Some Code ...} - - Assert-MockCalled Set-Content -Exactly 0 -Scope It - } -} - -Checks for calls only within the current It block. - -### -------------------------- EXAMPLE 6 -------------------------- -``` -Describe 'Describe' { -``` - -Mock -ModuleName SomeModule Set-Content { } - - {... -Some Code ...} - - It 'Calls Set-Content at least once in the Describe block' { - Assert-MockCalled -ModuleName SomeModule Set-Content - } -} - -Checks for calls to the mock within the SomeModule module. -Note that both the Mock -and Assert-MockCalled commands use the same module name. - -### -------------------------- EXAMPLE 7 -------------------------- -``` -Assert-MockCalled Get-ChildItem -ExclusiveFilter { $Path -eq 'C:\' } -``` - -Checks to make sure that Get-ChildItem was called at least one time with -the -Path parameter set to 'C:\', and that it was not called at all with -the -Path parameter set to any other value. - -## PARAMETERS - -### -CommandName -The mocked command whose call history should be checked. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Times -The number of times that the mock must be called to avoid an exception -from throwing. - -```yaml -Type: Int32 -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: 1 -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ParameterFilter -An optional filter to qualify wich calls should be counted. -Only those -calls to the mock whose parameters cause this filter to return true -will be counted. - -```yaml -Type: ScriptBlock -Parameter Sets: ParameterFilter -Aliases: - -Required: False -Position: 3 -Default value: {$True} -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ExclusiveFilter -{{Fill ExclusiveFilter Description}} - -```yaml -Type: ScriptBlock -Parameter Sets: ExclusiveFilter -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ModuleName -The module where the mock being checked was injected. -This is optional, -and must match the ModuleName that was used when setting up the Mock. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 4 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Scope -An optional parameter specifying the Pester scope in which to check for -calls to the mocked command. -By default, Assert-MockCalled will find -all calls to the mocked command in the current Context block (if present), -or the current Describe block (if there is no active Context.) Valid -values are Describe, Context and It. -If you use a scope of Describe or -Context, the command will identify all calls to the mocked command in the -current Describe / Context block, as well as all child scopes of that block. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 5 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Exactly -If this switch is present, the number specified in Times must match -exactly the number of times the mock has been called. -Otherwise it -must match "at least" the number of times specified. -If the value -passed to the Times parameter is zero, the Exactly switch is implied. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES -The parameter filter passed to Assert-MockCalled does not necessarily have to match the parameter filter -(if any) which was used to create the Mock. -Assert-MockCalled will find any entry in the command history -which matches its parameter filter, regardless of how the Mock was created. -However, if any calls to the -mocked command are made which did not match any mock's parameter filter (resulting in the original command -being executed instead of a mock), these calls to the original command are not tracked in the call history. -In other words, Assert-MockCalled can only be used to check for calls to the mocked implementation, not -to the original. - -## RELATED LINKS - diff --git a/reference/6/Pester/Assert-VerifiableMocks.md b/reference/6/Pester/Assert-VerifiableMocks.md deleted file mode 100644 index a3de168d7cda..000000000000 --- a/reference/6/Pester/Assert-VerifiableMocks.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Assert-VerifiableMocks - -## SYNOPSIS -Checks if any Verifiable Mock has not been invoked. -If so, this will throw an exception. - -## SYNTAX - -``` -Assert-VerifiableMocks -``` - -## DESCRIPTION -This can be used in tandem with the -Verifiable switch of the Mock -function. -Mock can be used to mock the behavior of an existing command -and optionally take a -Verifiable switch. -When Assert-VerifiableMocks -is called, it checks to see if any Mock marked Verifiable has not been -invoked. -If any mocks have been found that specified -Verifiable and -have not been invoked, an exception will be thrown. - -## EXAMPLES - -### -------------------------- EXAMPLE 1 -------------------------- -``` -Mock Set-Content {} -Verifiable -ParameterFilter {$Path -eq "some_path" -and $Value -eq "Expected Value"} -``` - -{ ...some code that never calls Set-Content some_path -Value "Expected Value"... -} - -Assert-VerifiableMocks - -This will throw an exception and cause the test to fail. - -### -------------------------- EXAMPLE 2 -------------------------- -``` -Mock Set-Content {} -Verifiable -ParameterFilter {$Path -eq "some_path" -and $Value -eq "Expected Value"} -``` - -Set-Content some_path -Value "Expected Value" - -Assert-VerifiableMocks - -This will not throw an exception because the mock was invoked. - -## PARAMETERS - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - diff --git a/reference/6/Pester/BeforeAll.md b/reference/6/Pester/BeforeAll.md deleted file mode 100644 index da60bd35ef36..000000000000 --- a/reference/6/Pester/BeforeAll.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# BeforeAll - -## SYNOPSIS -Defines a series of steps to perform at the beginning of the current Context -or Describe block. - -## SYNTAX - -``` -BeforeAll -``` - -## DESCRIPTION -BeforeEach, AfterEach, BeforeAll, and AfterAll are unique in that they apply -to the entire Context or Describe block, regardless of the order of the -statements in the Context or Describe. - -## EXAMPLES - -### Example 1 -``` -PS C:\> {{ Add example code here }} -``` - -{{ Add example description here }} - -## PARAMETERS - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[about_BeforeEach_AfterEach]() - diff --git a/reference/6/Pester/BeforeEach.md b/reference/6/Pester/BeforeEach.md deleted file mode 100644 index aba5f9c4e3a7..000000000000 --- a/reference/6/Pester/BeforeEach.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# BeforeEach - -## SYNOPSIS -Defines a series of steps to perform at the beginning of every It block within -the current Context or Describe block. - -## SYNTAX - -``` -BeforeEach -``` - -## DESCRIPTION -BeforeEach, AfterEach, BeforeAll, and AfterAll are unique in that they apply -to the entire Context or Describe block, regardless of the order of the -statements in the Context or Describe. -For a full description of this -behavior, as well as how multiple BeforeEach or AfterEach blocks interact -with each other, please refer to the about_BeforeEach_AfterEach help file. - -## EXAMPLES - -### Example 1 -``` -PS C:\> {{ Add example code here }} -``` - -{{ Add example description here }} - -## PARAMETERS - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[about_BeforeEach_AfterEach]() - diff --git a/reference/6/Pester/Context.md b/reference/6/Pester/Context.md deleted file mode 100644 index f38e433771c6..000000000000 --- a/reference/6/Pester/Context.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Context - -## SYNOPSIS -Provides logical grouping of It blocks within a single Describe block. -Any Mocks defined -inside a Context are removed at the end of the Context scope, as are any files or folders -added to the TestDrive during the Context block's execution. -Any BeforeEach or AfterEach -blocks defined inside a Context also only apply to tests within that Context . - -## SYNTAX - -``` -Context [-Name] [[-Fixture] ] -``` - -## DESCRIPTION -{{Fill in the Description}} - -## EXAMPLES - -### -------------------------- EXAMPLE 1 -------------------------- -``` -function Add-Numbers($a, $b) { -``` - -return $a + $b -} - -Describe "Add-Numbers" { - - Context "when root does not exist" { - It "..." { ... -} - } - - Context "when root does exist" { - It "..." { ... -} - It "..." { ... -} - It "..." { ... -} - } -} - -## PARAMETERS - -### -Name -The name of the Context. -This is a phrase describing a set of tests within a describe. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Fixture -Script that is executed. -This may include setup specific to the context and one or more It -blocks that validate the expected outcomes. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: $(Throw "No test script block is provided. (Have you put the open curly brace on the next line?)") -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[Describe](Describe.md) - -[It](It.md) - -[BeforeEach](BeforeEach.md) - -[AfterEach](AfterEach.md) - -[about_Should]() - -[about_Mocking]() - -[about_TestDrive]() \ No newline at end of file diff --git a/reference/6/Pester/Describe.md b/reference/6/Pester/Describe.md deleted file mode 100644 index 977c50108716..000000000000 --- a/reference/6/Pester/Describe.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Describe - -## SYNOPSIS -Creates a logical group of tests. -All Mocks and TestDrive contents -defined within a Describe block are scoped to that Describe; they -will no longer be present when the Describe block exits. -A Describe -block may contain any number of Context and It blocks. - -## SYNTAX - -``` -Describe [-Name] [-Tags ] [[-Fixture] ] -``` - -## DESCRIPTION -{{Fill in the Description}} - -## EXAMPLES - -### -------------------------- EXAMPLE 1 -------------------------- -``` -function Add-Numbers($a, $b) { -``` - -return $a + $b -} - -Describe "Add-Numbers" { - It "adds positive numbers" { - $sum = Add-Numbers 2 3 - $sum | Should Be 5 - } - - It "adds negative numbers" { - $sum = Add-Numbers (-2) (-2) - $sum | Should Be (-4) - } - - It "adds one negative number to positive number" { - $sum = Add-Numbers (-2) 2 - $sum | Should Be 0 - } - - It "concatenates strings if given strings" { - $sum = Add-Numbers two three - $sum | Should Be "twothree" - } -} - -## PARAMETERS - -### -Name -The name of the test group. -This is often an expressive phrase describing the scenario being tested. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Tags -Optional parameter containing an array of strings. -When calling Invoke-Pester, it is possible to -specify a -Tag parameter which will only execute Describe blocks containing the same Tag. - -```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: @() -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Fixture -The actual test script. -If you are following the AAA pattern (Arrange-Act-Assert), this -typically holds the arrange and act sections. -The Asserts will also lie in this block but are -typically nested each in its own It block. -Assertions are typically performed by the Should -command within the It blocks. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: $(Throw "No test script block is provided. (Have you put the open curly brace on the next line?)") -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[It](It.md) - -[Context](Context.md) - -[Invoke-Pester](Invoke-Pester.md) - -[about_Should]() - -[about_Mocking]() - -[about_TestDrive]() diff --git a/reference/6/Pester/Get-MockDynamicParameters.md b/reference/6/Pester/Get-MockDynamicParameters.md deleted file mode 100644 index 1940d0fffa79..000000000000 --- a/reference/6/Pester/Get-MockDynamicParameters.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Get-MockDynamicParameters - -## SYNOPSIS -This command is used by Pester's Mocking framework. -You do not need to call it directly. - -## SYNTAX - -### Cmdlet -``` -Get-MockDynamicParameters -CmdletName [-Parameters ] [-Cmdlet ] -``` - -### Function -``` -Get-MockDynamicParameters -FunctionName [-ModuleName ] [-Parameters ] - [-Cmdlet ] -``` - -## DESCRIPTION -{{Fill in the Description}} - -## EXAMPLES - -### Example 1 -``` -PS C:\> {{ Add example code here }} -``` - -{{ Add example description here }} - -## PARAMETERS - -### -CmdletName -{{Fill CmdletName Description}} - -```yaml -Type: String -Parameter Sets: Cmdlet -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -FunctionName -{{Fill FunctionName Description}} - -```yaml -Type: String -Parameter Sets: Function -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ModuleName -{{Fill ModuleName Description}} - -```yaml -Type: String -Parameter Sets: Function -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Parameters -{{Fill Parameters Description}} - -```yaml -Type: Hashtable -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Cmdlet -{{Fill Cmdlet Description}} - -```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - diff --git a/reference/6/Pester/Get-TestDriveItem.md b/reference/6/Pester/Get-TestDriveItem.md deleted file mode 100644 index 8efd4be3c273..000000000000 --- a/reference/6/Pester/Get-TestDriveItem.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Get-TestDriveItem - -## SYNOPSIS -{{Fill in the Synopsis}} - -## SYNTAX - -``` -Get-TestDriveItem [[-Path] ] -``` - -## DESCRIPTION -{{Fill in the Description}} - -## EXAMPLES - -### Example 1 -``` -PS C:\> {{ Add example code here }} -``` - -{{ Add example description here }} - -## PARAMETERS - -### -Path -{{Fill Path Description}} - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -### None - - -## OUTPUTS - -### System.Object - -## NOTES - -## RELATED LINKS - diff --git a/reference/6/Pester/In.md b/reference/6/Pester/In.md deleted file mode 100644 index 4df24be3c78d..000000000000 --- a/reference/6/Pester/In.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# In - -## SYNOPSIS -A convenience function that executes a script from a specified path. - -## SYNTAX - -``` -In [[-path] ] [[-execute] ] -``` - -## DESCRIPTION -Before the script block passed to the execute parameter is invoked, -the current location is set to the path specified. -Once the script -block has been executed, the location will be reset to the location -the script was in prior to calling In. - -## EXAMPLES - -### Example 1 -``` -PS C:\> {{ Add example code here }} -``` - -{{ Add example description here }} - -## PARAMETERS - -### -path -The path that the execute block will be executed in. - -```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -execute -The script to be executed in the path provided. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - diff --git a/reference/6/Pester/InModuleScope.md b/reference/6/Pester/InModuleScope.md deleted file mode 100644 index d30844361fc8..000000000000 --- a/reference/6/Pester/InModuleScope.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# InModuleScope - -## SYNOPSIS -Allows you to execute parts of a test script within the -scope of a PowerShell script module. - -## SYNTAX - -``` -InModuleScope [-ModuleName] [-ScriptBlock] -``` - -## DESCRIPTION -By injecting some test code into the scope of a PowerShell -script module, you can use non-exported functions, aliases -and variables inside that module, to perform unit tests on -its internal implementation. - -InModuleScope may be used anywhere inside a Pester script, -either inside or outside a Describe block. - -## EXAMPLES - -### -------------------------- EXAMPLE 1 -------------------------- -``` -# The script module: -``` - -function PublicFunction -{ - # Does something -} - -function PrivateFunction -{ - return $true -} - -Export-ModuleMember -Function PublicFunction - -The test script: - -Import-Module MyModule - -InModuleScope MyModule { - Describe 'Testing MyModule' { - It 'Tests the Private function' { - PrivateFunction | Should Be $true - } - } -} - -Normally you would not be able to access "PrivateFunction" from -the powershell session, because the module only exported -"PublicFunction". -Using InModuleScope allowed this call to -"PrivateFunction" to work successfully. - -## PARAMETERS - -### -ModuleName -The name of the module into which the test code should be -injected. -This module must already be loaded into the current -PowerShell session. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ScriptBlock -The code to be executed within the script module. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 2 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - diff --git a/reference/6/Pester/Invoke-Mock.md b/reference/6/Pester/Invoke-Mock.md deleted file mode 100644 index 733d4d2ada47..000000000000 --- a/reference/6/Pester/Invoke-Mock.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Invoke-Mock - -## SYNOPSIS -This command is used by Pester's Mocking framework. -You do not need to call it directly. - -## SYNTAX - -``` -Invoke-Mock [-CommandName] [-MockCallState] [[-ModuleName] ] - [[-BoundParameters] ] [[-ArgumentList] ] [[-CallerSessionState] ] - [[-FromBlock] ] [[-InputObject] ] -``` - -## DESCRIPTION -{{Fill in the Description}} - -## EXAMPLES - -### Example 1 -``` -PS C:\> {{ Add example code here }} -``` - -{{ Add example description here }} - -## PARAMETERS - -### -CommandName -{{Fill CommandName Description}} - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -MockCallState -{{Fill MockCallState Description}} - -```yaml -Type: Hashtable -Parameter Sets: (All) -Aliases: - -Required: True -Position: 2 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ModuleName -{{Fill ModuleName Description}} - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 3 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -BoundParameters -{{Fill BoundParameters Description}} - -```yaml -Type: Hashtable -Parameter Sets: (All) -Aliases: - -Required: False -Position: 4 -Default value: @{} -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ArgumentList -{{Fill ArgumentList Description}} - -```yaml -Type: Object[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: 5 -Default value: @() -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -CallerSessionState -{{Fill CallerSessionState Description}} - -```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: False -Position: 6 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -FromBlock -{{Fill FromBlock Description}} - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 7 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InputObject -{{Fill InputObject Description}} - -```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: False -Position: 8 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - diff --git a/reference/6/Pester/Invoke-Pester.md b/reference/6/Pester/Invoke-Pester.md deleted file mode 100644 index d0d84146ea1b..000000000000 --- a/reference/6/Pester/Invoke-Pester.md +++ /dev/null @@ -1,353 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Invoke-Pester - -## SYNOPSIS -Invokes Pester to run all tests (files containing *.Tests.ps1) recursively under the Path - -## SYNTAX - -### LegacyOutputXml (Default) -``` -Invoke-Pester [[-Script] ] [[-TestName] ] [-EnableExit] [[-OutputXml] ] - [[-Tag] ] [-ExcludeTag ] [-PassThru] [-CodeCoverage ] [-Strict] [-Quiet] - [-PesterOption ] -``` - -### NewOutputSet -``` -Invoke-Pester [[-Script] ] [[-TestName] ] [-EnableExit] [[-Tag] ] - [-ExcludeTag ] [-PassThru] [-CodeCoverage ] [-Strict] -OutputFile - -OutputFormat [-Quiet] [-PesterOption ] -``` - -## DESCRIPTION -Upon calling Invoke-Pester, all files that have a name containing -"*.Tests.ps1" will have the tests defined in their Describe blocks -executed. -Invoke-Pester begins at the location of Path and -runs recursively through each sub directory looking for -"*.Tests.ps1" files containing tests. -If a TestName is provided, -Invoke-Pester will only run tests that have a describe block with a -matching name. -By default, Invoke-Pester will end the test run with a -simple report of the number of tests passed and failed output to the -console. -One may want pester to "fail a build" in the event that any -tests fail. -To accomodate this, Invoke-Pester will return an exit -code equal to the number of failed tests if the EnableExit switch is -set. -Invoke-Pester will also write a NUnit style log of test results -if the OutputXml parameter is provided. -In these cases, Invoke-Pester -will write the result log to the path provided in the OutputXml -parameter. - -Optionally, Pester can generate a report of how much code is covered -by the tests, and information about any commands which were not -executed. - -## EXAMPLES - -### -------------------------- EXAMPLE 1 -------------------------- -``` -Invoke-Pester -``` - -This will find all *.Tests.ps1 files and run their tests. -No exit code will be returned and no log file will be saved. - -### -------------------------- EXAMPLE 2 -------------------------- -``` -Invoke-Pester -Script ./tests/Utils* -``` - -This will run all tests in files under ./Tests that begin with Utils and alsocontains .Tests. - -### -------------------------- EXAMPLE 3 -------------------------- -``` -Invoke-Pester -Script @{ Path = './tests/Utils*'; Parameters = @{ NamedParameter = 'Passed By Name' }; Arguments = @('Passed by position') } -``` - -Executes the same tests as in Example 1, but will run them with the equivalent of the following command line: & $testScriptPath -NamedParameter 'Passed By Name' 'Passed by position' - -### -------------------------- EXAMPLE 4 -------------------------- -``` -Invoke-Pester -TestName "Add Numbers" -``` - -This will only run the Describe block named "Add Numbers" - -### -------------------------- EXAMPLE 5 -------------------------- -``` -Invoke-Pester -EnableExit -OutputXml "./artifacts/TestResults.xml" -``` - -This runs all tests from the current directory downwards and writes the results according to the NUnit schema to artifacts/TestResults.xml just below the current directory. -The test run will return an exit code equal to the number of test failures. - -### -------------------------- EXAMPLE 6 -------------------------- -``` -Invoke-Pester -EnableExit -OutputFile "./artifacts/TestResults.xml" -OutputFormat NUnitxml -``` - -This runs all tests from the current directory downwards and writes the results to an output file and NUnitxml output format - -### -------------------------- EXAMPLE 7 -------------------------- -``` -Invoke-Pester -CodeCoverage 'ScriptUnderTest.ps1' -``` - -Runs all *.Tests.ps1 scripts in the current directory, and generates a coverage report for all commands in the "ScriptUnderTest.ps1" file. - -### -------------------------- EXAMPLE 8 -------------------------- -``` -Invoke-Pester -CodeCoverage @{ Path = 'ScriptUnderTest.ps1'; Function = 'FunctionUnderTest' } -``` - -Runs all *.Tests.ps1 scripts in the current directory, and generates a coverage report for all commands in the "FunctionUnderTest" function in the "ScriptUnderTest.ps1" file. - -### -------------------------- EXAMPLE 9 -------------------------- -``` -Invoke-Pester -CodeCoverage @{ Path = 'ScriptUnderTest.ps1'; StartLine = 10; EndLine = 20 } -``` - -Runs all *.Tests.ps1 scripts in the current directory, and generates a coverage report for all commands on lines 10 through 20 in the "ScriptUnderTest.ps1" file. - -## PARAMETERS - -### -Script -This parameter indicates which test scripts should be run. -This parameter may be passed simple strings (wildcards are allowed), or hashtables containing Path, Arguments and Parameters keys. -If hashtables are used, the Parameters key must refer to a hashtable, and the Arguments key must refer to an array; these will be splatted to the test script(s) indicated in the Path key. - -Note: If the path contains any wildcards, or if it refers to a directory, then Pester will search for and execute all test scripts named *.Tests.ps1 in the target path; the search is recursive. -If the path contains no wildcards and refers to a file, Pester will just try to execute that file regardless of its name. - -Aliased to 'Path' and 'relative_path' for backwards compatibility. - -```yaml -Type: Object[] -Parameter Sets: (All) -Aliases: Path, relative_path - -Required: False -Position: 1 -Default value: . -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -TestName -Informs Invoke-Pester to only run Describe blocks that match this name. - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: Name - -Required: False -Position: 2 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -EnableExit -Will cause Invoke-Pester to exit with a exit code equal to the number of failed tests once all tests have been run. -Use this to "fail" a build when any tests fail. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: 3 -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -OutputXml -The path where Invoke-Pester will save a NUnit formatted test results log file. -If this path is not provided, no log will be generated. - -```yaml -Type: String -Parameter Sets: LegacyOutputXml -Aliases: - -Required: False -Position: 4 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Tag -Informs Invoke-Pester to only run Describe blocks tagged with the tags specified. -Aliased 'Tags' for backwards compatibility. - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: Tags - -Required: False -Position: 5 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ExcludeTag -Informs Invoke-Pester to not run blocks tagged with the tags specified. - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -PassThru -Returns a Pester result object containing the information about the whole test run, and each test. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -CodeCoverage -Instructs Pester to generate a code coverage report in addition to running tests. -You may pass either hashtables or strings to this parameter. -If strings are used, they must be paths (wildcards allowed) to source files, and all commands in the files are analyzed for code coverage. -By passing hashtables instead, you can limit the analysis to specific lines or functions within a file. -Hashtables must contain a Path key (which can be abbreviated to just "P"), and may contain Function (or "F"), StartLine (or "S"), and EndLine ("E") keys to narrow down the commands to be analyzed. -If Function is specified, StartLine and EndLine are ignored. -If only StartLine is defined, the entire script file starting with StartLine is analyzed. -If only EndLine is present, all lines in the script file up to and including EndLine are analyzed. -Both Function and Path (as well as simple strings passed instead of hashtables) may contain wildcards. - -```yaml -Type: Object[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: @() -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Strict -Makes Pending and Skipped tests to Failed tests. -Useful for continuous integration where you need to make sure all tests passed. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -OutputFile -{{Fill OutputFile Description}} - -```yaml -Type: String -Parameter Sets: NewOutputSet -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -OutputFormat -{{Fill OutputFormat Description}} - -```yaml -Type: String -Parameter Sets: NewOutputSet -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Quiet -Disables the output Pester writes to screen. -No other output is generated unless you specify PassThru, or one of the Output parameters. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -PesterOption -Sets advanced options for the test execution. -Enter a PesterOption object, such as one that you create by using the New-PesterOption cmdlet, or a hash table in which the keys are option names and the values are option values. -For more information on the options available, see the help for New-PesterOption. - -```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[Describe](describe.md) - diff --git a/reference/6/Pester/It.md b/reference/6/Pester/It.md deleted file mode 100644 index 23d8439bee6b..000000000000 --- a/reference/6/Pester/It.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# It - -## SYNOPSIS -Validates the results of a test inside of a Describe block. - -## SYNTAX - -### Normal (Default) -``` -It [-name] [[-test] ] [-TestCases ] -``` - -### Pending -``` -It [-name] [[-test] ] [-TestCases ] [-Pending] -``` - -### Skip -``` -It [-name] [[-test] ] [-TestCases ] [-Skip] -``` - -## DESCRIPTION -The It command is intended to be used inside of a Describe or Context Block. -If you are familiar with the AAA pattern (Arrange-Act-Assert), the body of -the It block is the appropriate location for an assert. -The convention is to -assert a single expectation for each It block. -The code inside of the It block -should throw a terminating error if the expectation of the test is not met and -thus cause the test to fail. -The name of the It block should expressively state -the expectation of the test. - -In addition to using your own logic to test expectations and throw exceptions, -you may also use Pester's Should command to perform assertions in plain language. - -## EXAMPLES - -### -------------------------- EXAMPLE 1 -------------------------- -``` -function Add-Numbers($a, $b) { -``` - -return $a + $b -} - -Describe "Add-Numbers" { - It "adds positive numbers" { - $sum = Add-Numbers 2 3 - $sum | Should Be 5 - } - - It "adds negative numbers" { - $sum = Add-Numbers (-2) (-2) - $sum | Should Be (-4) - } - - It "adds one negative number to positive number" { - $sum = Add-Numbers (-2) 2 - $sum | Should Be 0 - } - - It "concatenates strings if given strings" { - $sum = Add-Numbers two three - $sum | Should Be "twothree" - } -} - -### -------------------------- EXAMPLE 2 -------------------------- -``` -function Add-Numbers($a, $b) { -``` - -return $a + $b -} - -Describe "Add-Numbers" { - $testCases = @( - @{ a = 2; b = 3; expectedResult = 5 } - @{ a = -2; b = -2; expectedResult = -4 } - @{ a = -2; b = 2; expectedResult = 0 } - @{ a = 'two'; b = 'three'; expectedResult = 'twothree' } - ) - - It 'Correctly adds \ and \ to get \' -TestCases $testCases { - param ($a, $b, $expectedResult) - - $sum = Add-Numbers $a $b - $sum | Should Be $expectedResult - } -} - -## PARAMETERS - -### -name -An expressive phsae describing the expected test outcome. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -test -The script block that should throw an exception if the -expectation of the test is not met.If you are following the -AAA pattern (Arrange-Act-Assert), this typically holds the -Assert. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: {} -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -TestCases -Optional array of hashtable (or any IDictionary) objects. -If this parameter is used, -Pester will call the test script block once for each table in the TestCases array, -splatting the dictionary to the test script block as input. -If you want the name of -the test to appear differently for each test case, you can embed tokens into the Name -parameter with the syntax 'Adds numbers \ and \' (assuming you have keys named A and B -in your TestCases hashtables.) - -```yaml -Type: IDictionary[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Pending -Use this parameter to explicitly mark the test as work-in-progress/not implemented/pending when you -need to distinguish a test that fails because it is not finished yet from a tests -that fail as a result of changes being made in the code base. -An empty test, that is a -test that contains nothing except whitespace or comments is marked as Pending by default. - -```yaml -Type: SwitchParameter -Parameter Sets: Pending -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Skip -Use this parameter to explicitly mark the test to be skipped. -This is preferable to temporarily -commenting out a test, because the test remains listed in the output. -Use the Strict parameter -of Invoke-Pester to force all skipped tests to fail. - -```yaml -Type: SwitchParameter -Parameter Sets: Skip -Aliases: Ignore - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[Describe](Describe.md) - -[Context](Context.md) - -[about_Should]() diff --git a/reference/6/Pester/Mock.md b/reference/6/Pester/Mock.md deleted file mode 100644 index 674ec8770136..000000000000 --- a/reference/6/Pester/Mock.md +++ /dev/null @@ -1,287 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Mock - -## SYNOPSIS -Mocks the behavior of an existing command with an alternate -implementation. - -## SYNTAX - -``` -Mock [[-CommandName] ] [[-MockWith] ] [-Verifiable] [[-ParameterFilter] ] - [[-ModuleName] ] -``` - -## DESCRIPTION -This creates new behavior for any existing command within the scope of a -Describe or Context block. -The function allows you to specify a script block -that will become the command's new behavior. - -Optionally, you may create a Parameter Filter which will examine the -parameters passed to the mocked command and will invoke the mocked -behavior only if the values of the parameter values pass the filter. -If -they do not, the original command implementation will be invoked instead -of a mock. - -You may create multiple mocks for the same command, each using a different -ParameterFilter. -ParameterFilters will be evaluated in reverse order of -their creation. -The last one created will be the first to be evaluated. -The mock of the first filter to pass will be used. -The exception to this -rule are Mocks with no filters. -They will always be evaluated last since -they will act as a "catch all" mock. - -Mocks can be marked Verifiable. -If so, the Assert-VerifiableMocks command -can be used to check if all Verifiable mocks were actually called. -If any -verifiable mock is not called, Assert-VerifiableMocks will throw an -exception and indicate all mocks not called. - -If you wish to mock commands that are called from inside a script module, -you can do so by using the -ModuleName parameter to the Mock command. -This -injects the mock into the specified module. -If you do not specify a -module name, the mock will be created in the same scope as the test script. -You may mock the same command multiple times, in different scopes, as needed. -Each module's mock maintains a separate call history and verified status. - -## EXAMPLES - -### -------------------------- EXAMPLE 1 -------------------------- -``` -Mock Get-ChildItem { return @{FullName = "A_File.TXT"} } -``` - -Using this Mock, all calls to Get-ChildItem will return a hashtable with a -FullName property returning "A_File.TXT" - -### -------------------------- EXAMPLE 2 -------------------------- -``` -Mock Get-ChildItem { return @{FullName = "A_File.TXT"} } -ParameterFilter { $Path -and $Path.StartsWith($env:temp) } -``` - -This Mock will only be applied to Get-ChildItem calls within the user's temp directory. - -### -------------------------- EXAMPLE 3 -------------------------- -``` -Mock Set-Content {} -Verifiable -ParameterFilter { $Path -eq "some_path" -and $Value -eq "Expected Value" } -``` - -When this mock is used, if the Mock is never invoked and Assert-VerifiableMocks is called, an exception will be thrown. -The command behavior will do nothing since the ScriptBlock is empty. - -### -------------------------- EXAMPLE 4 -------------------------- -``` -Mock Get-ChildItem { return @{FullName = "A_File.TXT"} } -ParameterFilter { $Path -and $Path.StartsWith($env:temp\1) } -``` - -Mock Get-ChildItem { return @{FullName = "B_File.TXT"} } -ParameterFilter { $Path -and $Path.StartsWith($env:temp\2) } -Mock Get-ChildItem { return @{FullName = "C_File.TXT"} } -ParameterFilter { $Path -and $Path.StartsWith($env:temp\3) } - -Multiple mocks of the same command may be used. -The parameter filter determines which is invoked. -Here, if Get-ChildItem is called on the "2" directory of the temp folder, then B_File.txt will be returned. - -### -------------------------- EXAMPLE 5 -------------------------- -``` -Mock Get-ChildItem { return @{FullName="B_File.TXT"} } -ParameterFilter { $Path -eq "$env:temp\me" } -``` - -Mock Get-ChildItem { return @{FullName="A_File.TXT"} } -ParameterFilter { $Path -and $Path.StartsWith($env:temp) } - -Get-ChildItem $env:temp\me - -Here, both mocks could apply since both filters will pass. -A_File.TXT will be returned because it was the most recent Mock created. - -### -------------------------- EXAMPLE 6 -------------------------- -``` -Mock Get-ChildItem { return @{FullName = "B_File.TXT"} } -ParameterFilter { $Path -eq "$env:temp\me" } -``` - -Mock Get-ChildItem { return @{FullName = "A_File.TXT"} } - -Get-ChildItem c:\windows - -Here, A_File.TXT will be returned. -Since no filter was specified, it will apply to any call to Get-ChildItem that does not pass another filter. - -### -------------------------- EXAMPLE 7 -------------------------- -``` -Mock Get-ChildItem { return @{FullName = "B_File.TXT"} } -ParameterFilter { $Path -eq "$env:temp\me" } -``` - -Mock Get-ChildItem { return @{FullName = "A_File.TXT"} } - -Get-ChildItem $env:temp\me - -Here, B_File.TXT will be returned. -Even though the filterless mock was created more recently. -This illustrates that filterless Mocks are always evaluated last regardlss of their creation order. - -### -------------------------- EXAMPLE 8 -------------------------- -``` -Mock Get-ChildItem { return @{FullName = "A_File.TXT"} } -ModuleName MyTestModule -``` - -Using this Mock, all calls to Get-ChildItem from within the MyTestModule module -will return a hashtable with a FullName property returning "A_File.TXT" - -### -------------------------- EXAMPLE 9 -------------------------- -``` -Get-Module -Name ModuleMockExample | Remove-Module -``` - -New-Module -Name ModuleMockExample -ScriptBlock { - function Hidden { "Internal Module Function" } - function Exported { Hidden } - - Export-ModuleMember -Function Exported -} | Import-Module -Force - -Describe "ModuleMockExample" { - - It "Hidden function is not directly accessible outside the module" { - { Hidden } | Should Throw - } - - It "Original Hidden function is called" { - Exported | Should Be "Internal Module Function" - } - - It "Hidden is replaced with our implementation" { - Mock Hidden { "Mocked" } -ModuleName ModuleMockExample - Exported | Should Be "Mocked" - } -} - -This example shows how calls to commands made from inside a module can be -mocked by using the -ModuleName parameter. - -## PARAMETERS - -### -CommandName -The name of the command to be mocked. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -MockWith -A ScriptBlock specifying the behvior that will be used to mock CommandName. -The default is an empty ScriptBlock. -NOTE: Do not specify param or dynamicparam blocks in this script block. -These will be injected automatically based on the signature of the command -being mocked, and the MockWith script block can contain references to the -mocked commands parameter variables. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: {} -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Verifiable -When this is set, the mock will be checked when Assert-VerifiableMocks is -called. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ParameterFilter -An optional filter to limit mocking behavior only to usages of -CommandName where the values of the parameters passed to the command -pass the filter. - -This ScriptBlock must return a boolean value. -See examples for usage. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: False -Position: 3 -Default value: {$True} -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ModuleName -Optional string specifying the name of the module where this command -is to be mocked. -This should be a module that _calls_ the mocked -command; it doesn't necessarily have to be the same module which -originally implemented the command. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 4 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[Assert-MockCalled](Assert-MockCalled.md) - -[Assert-VerifiableMocks](Assert-VerifiableMocks.md) - -[Describe](Describe.md) - -[Context](Context.md) - -[It](It.md) - -[about_Should]() - -[about_Mocking]() diff --git a/reference/6/Pester/New-Fixture.md b/reference/6/Pester/New-Fixture.md deleted file mode 100644 index 3453128a1bf4..000000000000 --- a/reference/6/Pester/New-Fixture.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# New-Fixture - -## SYNOPSIS -This function generates two scripts, one that defines a function -and another one that contains its tests. - -## SYNTAX - -``` -New-Fixture [[-Path] ] [-Name] -``` - -## DESCRIPTION -This function generates two scripts, one that defines a function -and another one that contains its tests. -The files are by default -placed in the current directory and are called and populated as such: - - -The script defining the function: .\Clean.ps1: - -function Clean { - -} - -The script containg the example test .\Clean.Tests.ps1: - -$here = Split-Path -Parent $MyInvocation.MyCommand.Path -$sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path).Replace(".Tests.", ".") -. -"$here\$sut" - -Describe "Clean" { - - It "does something useful" { - $false | Should Be $true - } -} - -## EXAMPLES - -### -------------------------- EXAMPLE 1 -------------------------- -``` -New-Fixture -Name Clean -``` - -Creates the scripts in the current directory. - -### -------------------------- EXAMPLE 2 -------------------------- -``` -New-Fixture C:\Projects\Cleaner Clean -``` - -Creates the scripts in the C:\Projects\Cleaner directory. - -### -------------------------- EXAMPLE 3 -------------------------- -``` -New-Fixture Cleaner Clean -``` - -Creates a new folder named Cleaner in the current directory and creates the scripts in it. - -## PARAMETERS - -### -Path -Defines path where the test and the function should be created, you can use full or relative path. -If the parameter is not specified the scripts are created in the current directory. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 1 -Default value: $PWD -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Name -Defines the name of the function and the name of the test to be created. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 2 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[about_Pester](https://github.com/pester/Pester/blob/master/en-US/about_Pester.help.txt) - -[about_Should](https://github.com/pester/Pester/blob/master/en-US/about_Should.help.txt) - diff --git a/reference/6/Pester/Pester.md b/reference/6/Pester/Pester.md deleted file mode 100644 index 3f1e6ee9b3d6..000000000000 --- a/reference/6/Pester/Pester.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-US -keywords: powershell,cmdlet -Help Version: 6.0 -Download Help Link: http://Please-enter-FwLink-manually -Module Guid: a699dea5-2c73-4616-a270-1f7abb777e71 -Module Name: Pester ---- - -# Pester Module -## Description -{{Manually Enter Description Here}} - -## Pester Cmdlets -### [AfterAll](AfterAll.md) -{{Manually Enter AfterAll Description Here}} - -### [AfterEach](AfterEach.md) -{{Manually Enter AfterEach Description Here}} - -### [Assert-MockCalled](Assert-MockCalled.md) -{{Manually Enter Assert-MockCalled Description Here}} - -### [Assert-VerifiableMocks](Assert-VerifiableMocks.md) -{{Manually Enter Assert-VerifiableMocks Description Here}} - -### [BeforeAll](BeforeAll.md) -{{Manually Enter BeforeAll Description Here}} - -### [BeforeEach](BeforeEach.md) -{{Manually Enter BeforeEach Description Here}} - -### [Context](Context.md) -{{Manually Enter Context Description Here}} - -### [Describe](Describe.md) -{{Manually Enter Describe Description Here}} - -### [Get-MockDynamicParameters](Get-MockDynamicParameters.md) -{{Manually Enter Get-MockDynamicParameters Description Here}} - -### [Get-TestDriveItem](Get-TestDriveItem.md) -{{Manually Enter Get-TestDriveItem Description Here}} - -### [In](In.md) -{{Manually Enter In Description Here}} - -### [InModuleScope](InModuleScope.md) -{{Manually Enter InModuleScope Description Here}} - -### [Invoke-Mock](Invoke-Mock.md) -{{Manually Enter Invoke-Mock Description Here}} - -### [Invoke-Pester](Invoke-Pester.md) -{{Manually Enter Invoke-Pester Description Here}} - -### [It](It.md) -{{Manually Enter It Description Here}} - -### [Mock](Mock.md) -{{Manually Enter Mock Description Here}} - -### [New-Fixture](New-Fixture.md) -{{Manually Enter New-Fixture Description Here}} - -### [Set-DynamicParameterVariables](Set-DynamicParameterVariables.md) -{{Manually Enter Set-DynamicParameterVariables Description Here}} - -### [Setup](Setup.md) -{{Manually Enter Setup Description Here}} - -### [Should](Should.md) -{{Manually Enter Should Description Here}} diff --git a/reference/6/Pester/Set-DynamicParameterVariables.md b/reference/6/Pester/Set-DynamicParameterVariables.md deleted file mode 100644 index 4a21e44ff096..000000000000 --- a/reference/6/Pester/Set-DynamicParameterVariables.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Set-DynamicParameterVariables - -## SYNOPSIS -This command is used by Pester's Mocking framework. -You do not need to call it directly. - -## SYNTAX - -``` -Set-DynamicParameterVariables [-SessionState] [[-Parameters] ] - [[-Metadata] ] -``` - -## DESCRIPTION -{{Fill in the Description}} - -## EXAMPLES - -### Example 1 -``` -PS C:\> {{ Add example code here }} -``` - -{{ Add example description here }} - -## PARAMETERS - -### -SessionState -{{Fill SessionState Description}} - -```yaml -Type: SessionState -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Parameters -{{Fill Parameters Description}} - -```yaml -Type: Hashtable -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Metadata -{{Fill Metadata Description}} - -```yaml -Type: CommandMetadata -Parameter Sets: (All) -Aliases: - -Required: False -Position: 3 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - diff --git a/reference/6/Pester/Setup.md b/reference/6/Pester/Setup.md deleted file mode 100644 index bcaeb69b3c38..000000000000 --- a/reference/6/Pester/Setup.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Setup - -## SYNOPSIS -{{Fill in the Synopsis}} - -## SYNTAX - -``` -Setup [-Dir] [-File] [[-Path] ] [[-Content] ] [-PassThru] -``` - -## DESCRIPTION -{{Fill in the Description}} - -## EXAMPLES - -### Example 1 -``` -PS C:\> {{ Add example code here }} -``` - -{{ Add example description here }} - -## PARAMETERS - -### -Content -{{Fill Content Description}} - -```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Dir -{{Fill Dir Description}} - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -File -{{Fill File Description}} - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -PassThru -{{Fill PassThru Description}} - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Path -{{Fill Path Description}} - -```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: False -Position: 0 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -## INPUTS - -### None - - -## OUTPUTS - -### System.Object - -## NOTES - -## RELATED LINKS - diff --git a/reference/6/Pester/Should.md b/reference/6/Pester/Should.md deleted file mode 100644 index eecaa08574ea..000000000000 --- a/reference/6/Pester/Should.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -external help file: Pester-help.xml ---- - -# Should - -## SYNOPSIS -{{Fill in the Synopsis}} - -## SYNTAX - -``` -Should -``` - -## DESCRIPTION -{{Fill in the Description}} - -## EXAMPLES - -### Example 1 -``` -PS C:\> {{ Add example code here }} -``` - -{{ Add example description here }} - -## PARAMETERS - -## INPUTS - -### None - - -## OUTPUTS - -### System.Object - -## NOTES - -## RELATED LINKS - From 160ba5e3d11c2adec4eca559e6ca3af631aeab32 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Thu, 4 Jan 2018 00:22:22 +0900 Subject: [PATCH 144/188] Fix parameter's position in Resume-Service.md (#1998) --- .../Resume-Service.md | 17 ++++--- .../Resume-Service.md | 17 ++++--- .../Resume-Service.md | 13 +++-- .../Resume-Service.md | 13 +++-- .../Resume-Service.md | 49 +++++-------------- 5 files changed, 47 insertions(+), 62 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Management/Resume-Service.md b/reference/3.0/Microsoft.PowerShell.Management/Resume-Service.md index 3f87445c0af4..c5e046d3136b 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Resume-Service.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Resume-Service.md @@ -15,20 +15,23 @@ Resumes one or more suspended (paused) services. ### InputObject (Default) ``` -Resume-Service [-InputObject] [-PassThru] [-Include ] [-Exclude ] +Resume-Service [-InputObject] + [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] [] ``` ### Default ``` -Resume-Service [-Name] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] - [] +Resume-Service [-Name] + [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### DisplayName ``` -Resume-Service [-PassThru] -DisplayName [-Include ] [-Exclude ] [-WhatIf] - [-Confirm] [] +Resume-Service -DisplayName + [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -120,7 +123,7 @@ Parameter Sets: InputObject Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False @@ -138,7 +141,7 @@ Parameter Sets: Default Aliases: ServiceName Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/4.0/Microsoft.PowerShell.Management/Resume-Service.md b/reference/4.0/Microsoft.PowerShell.Management/Resume-Service.md index cbe185b557aa..4d54cba85312 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Resume-Service.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Resume-Service.md @@ -17,20 +17,23 @@ Resumes one or more suspended (paused) services. ### InputObject (Default) ``` -Resume-Service [-InputObject] [-PassThru] [-Include ] [-Exclude ] +Resume-Service [-InputObject] + [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] [] ``` ### Default ``` -Resume-Service [-Name] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] - [] +Resume-Service [-Name] + [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### DisplayName ``` -Resume-Service [-PassThru] -DisplayName [-Include ] [-Exclude ] [-WhatIf] - [-Confirm] [] +Resume-Service -DisplayName + [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -125,7 +128,7 @@ Parameter Sets: InputObject Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False @@ -143,7 +146,7 @@ Parameter Sets: Default Aliases: ServiceName Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False diff --git a/reference/5.0/Microsoft.PowerShell.Management/Resume-Service.md b/reference/5.0/Microsoft.PowerShell.Management/Resume-Service.md index 6e2a3001e068..aed2fe434e88 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Resume-Service.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Resume-Service.md @@ -17,20 +17,23 @@ Resumes one or more suspended (paused) services. ### InputObject (Default) ``` -Resume-Service [-InputObject] [-PassThru] [-Include ] [-Exclude ] +Resume-Service [-InputObject] + [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] [] ``` ### Default ``` -Resume-Service [-Name] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] - [] +Resume-Service [-Name] + [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### DisplayName ``` -Resume-Service [-PassThru] -DisplayName [-Include ] [-Exclude ] [-WhatIf] - [-Confirm] [] +Resume-Service -DisplayName + [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION diff --git a/reference/5.1/Microsoft.PowerShell.Management/Resume-Service.md b/reference/5.1/Microsoft.PowerShell.Management/Resume-Service.md index 6e2a3001e068..aed2fe434e88 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Resume-Service.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Resume-Service.md @@ -17,20 +17,23 @@ Resumes one or more suspended (paused) services. ### InputObject (Default) ``` -Resume-Service [-InputObject] [-PassThru] [-Include ] [-Exclude ] +Resume-Service [-InputObject] + [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] [] ``` ### Default ``` -Resume-Service [-Name] [-PassThru] [-Include ] [-Exclude ] [-WhatIf] [-Confirm] - [] +Resume-Service [-Name] + [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### DisplayName ``` -Resume-Service [-PassThru] -DisplayName [-Include ] [-Exclude ] [-WhatIf] - [-Confirm] [] +Resume-Service -DisplayName + [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION diff --git a/reference/6/Microsoft.PowerShell.Management/Resume-Service.md b/reference/6/Microsoft.PowerShell.Management/Resume-Service.md index 1a021d3214c5..408680262b4a 100644 --- a/reference/6/Microsoft.PowerShell.Management/Resume-Service.md +++ b/reference/6/Microsoft.PowerShell.Management/Resume-Service.md @@ -17,23 +17,23 @@ Resumes one or more suspended (paused) services. ### InputObject (Default) ``` -Resume-Service [-InputObject] [-PassThru] [-Include ] [-Exclude ] - [-InformationAction ] [-InformationVariable ] [-WhatIf] [-Confirm] - [] +Resume-Service [-InputObject] + [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### Default ``` -Resume-Service [-Name] [-PassThru] [-Include ] [-Exclude ] - [-InformationAction ] [-InformationVariable ] [-WhatIf] [-Confirm] - [] +Resume-Service [-Name] + [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ### DisplayName ``` -Resume-Service [-PassThru] -DisplayName [-Include ] [-Exclude ] - [-InformationAction ] [-InformationVariable ] [-WhatIf] [-Confirm] - [] +Resume-Service -DisplayName + [-PassThru] [-Include ] [-Exclude ] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -119,33 +119,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -InputObject Specifies **ServiceController** objects that represent the services to resumed. Enter a variable that contains the objects, or type a command or expression that gets the objects. @@ -156,7 +129,7 @@ Parameter Sets: InputObject Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False @@ -171,7 +144,7 @@ Parameter Sets: Default Aliases: ServiceName Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: True (ByPropertyName, ByValue) Accept wildcard characters: False From 0e1efd4888e1cb2e74602dd7f28e6eb7b3ce7f24 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Thu, 4 Jan 2018 00:23:05 +0900 Subject: [PATCH 145/188] Fix link for about_Providers (#1999) --- reference/3.0/Microsoft.PowerShell.Core/Get-Command.md | 2 +- reference/3.0/Microsoft.PowerShell.Core/Get-Help.md | 2 +- reference/3.0/Microsoft.PowerShell.Management/Get-Content.md | 2 +- reference/3.0/Microsoft.PowerShell.Management/Get-PSDrive.md | 2 +- reference/3.0/Microsoft.PowerShell.Management/New-PSDrive.md | 2 +- reference/3.0/Microsoft.PowerShell.Management/Remove-PSDrive.md | 2 +- reference/4.0/Microsoft.PowerShell.Core/Get-Command.md | 2 +- reference/4.0/Microsoft.PowerShell.Core/Get-Help.md | 2 +- reference/4.0/Microsoft.PowerShell.Management/Get-Content.md | 2 +- reference/4.0/Microsoft.PowerShell.Management/Get-PSDrive.md | 2 +- reference/4.0/Microsoft.PowerShell.Management/New-PSDrive.md | 2 +- reference/4.0/Microsoft.PowerShell.Management/Remove-PSDrive.md | 2 +- reference/5.0/Microsoft.PowerShell.Core/Get-Command.md | 2 +- reference/5.0/Microsoft.PowerShell.Core/Get-Help.md | 2 +- reference/5.0/Microsoft.PowerShell.Management/Get-Content.md | 2 +- reference/5.0/Microsoft.PowerShell.Management/Get-PSDrive.md | 2 +- reference/5.0/Microsoft.PowerShell.Management/New-PSDrive.md | 2 +- reference/5.0/Microsoft.PowerShell.Management/Remove-PSDrive.md | 2 +- reference/5.1/Microsoft.PowerShell.Core/Get-Command.md | 2 +- reference/5.1/Microsoft.PowerShell.Core/Get-Help.md | 2 +- reference/5.1/Microsoft.PowerShell.Management/Get-Content.md | 2 +- reference/5.1/Microsoft.PowerShell.Management/Get-PSDrive.md | 2 +- reference/5.1/Microsoft.PowerShell.Management/New-PSDrive.md | 2 +- reference/5.1/Microsoft.PowerShell.Management/Remove-PSDrive.md | 2 +- reference/6/Microsoft.PowerShell.Core/Get-Command.md | 2 +- reference/6/Microsoft.PowerShell.Core/Get-Help.md | 2 +- reference/6/Microsoft.PowerShell.Core/help.md | 2 +- reference/6/Microsoft.PowerShell.Management/Get-Content.md | 2 +- reference/6/Microsoft.PowerShell.Management/Get-PSDrive.md | 2 +- reference/6/Microsoft.PowerShell.Management/New-PSDrive.md | 2 +- reference/6/Microsoft.PowerShell.Management/Remove-PSDrive.md | 2 +- 31 files changed, 31 insertions(+), 31 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md b/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md index 5865aed69a30..5b011161f813 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md @@ -232,7 +232,7 @@ To detect dynamic parameters that are available only when certain other paramete To detect the dynamic parameters that a provider adds to a cmdlet, set the value of the **ArgumentList** parameter to a path in the provider drive, such as "WSMan:", "HKLM:" or "Cert:". When the command is a Windows PowerShell provider cmdlet, enter only one path in each command; the provider cmdlets return only the dynamic parameters for the first path the value of **ArgumentList**. -For information about the provider cmdlets, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +For information about the provider cmdlets, see [about_Providers](About/about_Providers.md). ```yaml Type: Object[] diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-Help.md b/reference/3.0/Microsoft.PowerShell.Core/Get-Help.md index 0b102d43b26e..8cc6b01cfac6 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-Help.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-Help.md @@ -474,7 +474,7 @@ To see the custom cmdlet help for a provider path, go to the provider path locat You can also find custom cmdlet help online in the provider help section of the help topics. For example, you can find help for the **New-Item** cmdlet in the Wsman:\*\ClientCertificate path (http://go.microsoft.com/fwlink/?LinkID=158676). -For more information about Windows PowerShell providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +For more information about Windows PowerShell providers, see [about_Providers](About/about_Providers.md). ```yaml Type: String diff --git a/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md b/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md index 8d68eac2331a..a459dc0acb9c 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Get-Content.md @@ -391,7 +391,7 @@ You cannot pipe input to **Get-Content**. **Get-Content** returns strings or bytes. The output type depends upon the content that it gets. ## NOTES -* The **Get-Content** cmdlet is designed to work with the data exposed by any provider. To get the providers in your session, use the **Get-PsProvider** cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* The **Get-Content** cmdlet is designed to work with the data exposed by any provider. To get the providers in your session, use the **Get-PsProvider** cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Management/Get-PSDrive.md b/reference/3.0/Microsoft.PowerShell.Management/Get-PSDrive.md index 7a6ab17b723f..d4406cc39af1 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Get-PSDrive.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Get-PSDrive.md @@ -300,7 +300,7 @@ You cannot pipe objects to **Get-PSDrive**. ### System.Management.Automation.PSDriveInfo **Get-PSDrive** returns objects that represent the drives in the session. ## NOTES -* The **Get-PSDrive** cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* The **Get-PSDrive** cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * Mapped network drives that are created by using the **Persist** parameter of the New-PSDrive cmdlet are specific to a user account. Mapped network drives that you create in sessions that are started with the "Run as administrator" option or with the credentials of another user are not visible in sessions that are started without explicit credentials or with the credentials of the current user. ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Management/New-PSDrive.md b/reference/3.0/Microsoft.PowerShell.Management/New-PSDrive.md index 691727712599..413678992d94 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/New-PSDrive.md +++ b/reference/3.0/Microsoft.PowerShell.Management/New-PSDrive.md @@ -366,7 +366,7 @@ You cannot pipe input to this cmdlet. ### System.Management.Automation.PSDriveInfo ## NOTES -* The **New-PSDrive** cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information about providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* The **New-PSDrive** cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information about providers, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * Mapped network drives are specific to a user account. Mapped network drives that you create in sessions that are started with the "Run as administrator" option or with the credential of another user are not visible in session that started without explicit credentials or with the credentials of the current user. ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Management/Remove-PSDrive.md b/reference/3.0/Microsoft.PowerShell.Management/Remove-PSDrive.md index 626f1214e115..1bd142d20a5c 100644 --- a/reference/3.0/Microsoft.PowerShell.Management/Remove-PSDrive.md +++ b/reference/3.0/Microsoft.PowerShell.Management/Remove-PSDrive.md @@ -193,7 +193,7 @@ You can pipe a drive object, such as one from the Get-PSDrive cmdlet, to the **R ### None This cmdlet does not return any output. ## NOTES -* The **Remove-PSDrive** cmdlet is designed to work with the data exposed by any Windows PowerShell provider. To list the providers in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* The **Remove-PSDrive** cmdlet is designed to work with the data exposed by any Windows PowerShell provider. To list the providers in your session, use the Get-PSProvider cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * ## RELATED LINKS diff --git a/reference/4.0/Microsoft.PowerShell.Core/Get-Command.md b/reference/4.0/Microsoft.PowerShell.Core/Get-Command.md index 373697a4fcfc..791d66ee6be9 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Get-Command.md @@ -249,7 +249,7 @@ To detect dynamic parameters that are available only when certain other paramete To detect the dynamic parameters that a provider adds to a cmdlet, set the value of the **ArgumentList** parameter to a path in the provider drive, such as "WSMan:", "HKLM:" or "Cert:". When the command is a Windows PowerShell provider cmdlet, enter only one path in each command; the provider cmdlets return only the dynamic parameters for the first path the value of **ArgumentList**. -For information about the provider cmdlets, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +For information about the provider cmdlets, see [about_Providers](About/about_Providers.md). ```yaml Type: Object[] diff --git a/reference/4.0/Microsoft.PowerShell.Core/Get-Help.md b/reference/4.0/Microsoft.PowerShell.Core/Get-Help.md index 7504ee559b8b..48e6773649a4 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Get-Help.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Get-Help.md @@ -492,7 +492,7 @@ To see the custom cmdlet help for a provider path, go to the provider path locat You can also find custom cmdlet help online in the provider help section of the help topics. For example, you can find help for the **New-Item** cmdlet in the Wsman:\*\ClientCertificate path (http://go.microsoft.com/fwlink/?LinkID=158676). -For more information about Windows PowerShell providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +For more information about Windows PowerShell providers, see [about_Providers](About/about_Providers.md). ```yaml Type: String diff --git a/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md b/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md index f68c52f161b7..505e9c9a32ed 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Get-Content.md @@ -373,7 +373,7 @@ You cannot pipe input to **Get-Content**. The output type depends upon the content that it gets. ## NOTES -* The **Get-Content** cmdlet is designed to work with the data exposed by any provider. To get the providers in your session, use the **Get-PsProvider** cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* The **Get-Content** cmdlet is designed to work with the data exposed by any provider. To get the providers in your session, use the **Get-PsProvider** cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * diff --git a/reference/4.0/Microsoft.PowerShell.Management/Get-PSDrive.md b/reference/4.0/Microsoft.PowerShell.Management/Get-PSDrive.md index ce4073b3e3cc..b776579bb65c 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Get-PSDrive.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Get-PSDrive.md @@ -306,7 +306,7 @@ You cannot pipe objects to **Get-PSDrive**. **Get-PSDrive** returns objects that represent the drives in the session. ## NOTES -* The **Get-PSDrive** cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* The **Get-PSDrive** cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * Mapped network drives that are created by using the **Persist** parameter of the New-PSDrive cmdlet are specific to a user account. Mapped network drives that you create in sessions that are started with the "Run as administrator" option or with the credentials of another user are not visible in sessions that are started without explicit credentials or with the credentials of the current user. ## RELATED LINKS diff --git a/reference/4.0/Microsoft.PowerShell.Management/New-PSDrive.md b/reference/4.0/Microsoft.PowerShell.Management/New-PSDrive.md index 64b77e48bb25..31a9648a18e4 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/New-PSDrive.md +++ b/reference/4.0/Microsoft.PowerShell.Management/New-PSDrive.md @@ -376,7 +376,7 @@ You cannot pipe input to this cmdlet. ### System.Management.Automation.PSDriveInfo ## NOTES -* The **New-PSDrive** cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information about providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* The **New-PSDrive** cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information about providers, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * Mapped network drives are specific to a user account. Mapped network drives that you create in sessions that are started with the "Run as administrator" option or with the credential of another user are not visible in a session that you started without explicit credentials, or with the credentials of the current user. ## RELATED LINKS diff --git a/reference/4.0/Microsoft.PowerShell.Management/Remove-PSDrive.md b/reference/4.0/Microsoft.PowerShell.Management/Remove-PSDrive.md index 9c9065eeeec0..0aa3683b0e99 100644 --- a/reference/4.0/Microsoft.PowerShell.Management/Remove-PSDrive.md +++ b/reference/4.0/Microsoft.PowerShell.Management/Remove-PSDrive.md @@ -201,7 +201,7 @@ You can pipe a drive object, such as one from the Get-PSDrive cmdlet, to the **R This cmdlet does not return any output. ## NOTES -* The **Remove-PSDrive** cmdlet is designed to work with the data exposed by any Windows PowerShell provider. To list the providers in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* The **Remove-PSDrive** cmdlet is designed to work with the data exposed by any Windows PowerShell provider. To list the providers in your session, use the Get-PSProvider cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * diff --git a/reference/5.0/Microsoft.PowerShell.Core/Get-Command.md b/reference/5.0/Microsoft.PowerShell.Core/Get-Command.md index 885947657a4a..f3d28f586d14 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Get-Command.md @@ -255,7 +255,7 @@ To detect dynamic parameters that are available only when certain other paramete To detect the dynamic parameters that a provider adds to a cmdlet, set the value of the *ArgumentList* parameter to a path in the provider drive, such as WSMan:, HKLM:, or Cert:. When the command is a Windows PowerShell provider cmdlet, enter only one path in each command. The provider cmdlets return only the dynamic parameters for the first path the value of *ArgumentList*. -For information about the provider cmdlets, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250) in the TechNet library. +For information about the provider cmdlets, see [about_Providers](About/about_Providers.md). ```yaml Type: Object[] diff --git a/reference/5.0/Microsoft.PowerShell.Core/Get-Help.md b/reference/5.0/Microsoft.PowerShell.Core/Get-Help.md index 9d00e202db9a..c7b869056476 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Get-Help.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Get-Help.md @@ -513,7 +513,7 @@ To see the custom cmdlet help for a provider path, go to the provider path locat You can also find custom cmdlet help online in the provider help section of the help topics. For example, you can find help for the **New-Item** cmdlet in the Wsman:\*\ClientCertificate path (http://go.microsoft.com/fwlink/?LinkID=158676). -For more information about Windows PowerShell providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250) in the TechNet library. +For more information about Windows PowerShell providers, see [about_Providers](About/about_Providers.md). ```yaml Type: String diff --git a/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md b/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md index 3c363fae179e..a60d62e83ce7 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Get-Content.md @@ -372,7 +372,7 @@ This cmdlet returns strings or bytes. The output type depends upon the content that it gets. ## NOTES -* This cmdlet is designed to work with the data exposed by any provider. To get the providers in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers(http://go.microsoft.com/fwlink/?LinkID=113250). +* This cmdlet is designed to work with the data exposed by any provider. To get the providers in your session, use the Get-PSProvider cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) * diff --git a/reference/5.0/Microsoft.PowerShell.Management/Get-PSDrive.md b/reference/5.0/Microsoft.PowerShell.Management/Get-PSDrive.md index 316fd31d18a7..ffbf081e61a7 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Get-PSDrive.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Get-PSDrive.md @@ -313,7 +313,7 @@ You cannot pipe objects to this cmdlet. This cmdlet returns objects that represent the drives in the session. ## NOTES -* This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the Get-PSProvider cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * Mapped network drives that are created by using the *Persist* parameter of the New-PSDrive cmdlet are specific to a user account. Mapped network drives that you create in sessions that are started with the Run as administrator option or with the credentials of another user are not visible in sessions that are started without explicit credentials or with the credentials of the current user. ## RELATED LINKS diff --git a/reference/5.0/Microsoft.PowerShell.Management/New-PSDrive.md b/reference/5.0/Microsoft.PowerShell.Management/New-PSDrive.md index 128108975eef..c4a1cf5882e9 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/New-PSDrive.md +++ b/reference/5.0/Microsoft.PowerShell.Management/New-PSDrive.md @@ -391,7 +391,7 @@ You cannot pipe input to this cmdlet. ### System.Management.Automation.PSDriveInfo ## NOTES -* **New-PSDrive** is designed to work with the data exposed by any provider. To list the providers available in your session, use **Get-PSProvider**. For more information about providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* **New-PSDrive** is designed to work with the data exposed by any provider. To list the providers available in your session, use **Get-PSProvider**. For more information about providers, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * Mapped network drives are specific to a user account. Mapped network drives that you create in sessions that are started by using the Run as administrator option or by using the credential of another user are not visible in a session that was started without explicit credentials, or by using the credentials of the current user. ## RELATED LINKS diff --git a/reference/5.0/Microsoft.PowerShell.Management/Remove-PSDrive.md b/reference/5.0/Microsoft.PowerShell.Management/Remove-PSDrive.md index 052d8763b2a6..71f832d53297 100644 --- a/reference/5.0/Microsoft.PowerShell.Management/Remove-PSDrive.md +++ b/reference/5.0/Microsoft.PowerShell.Management/Remove-PSDrive.md @@ -202,7 +202,7 @@ You can pipe a drive object, such as one from the Get-PSDrive cmdlet, to the thi This cmdlet does not return any output. ## NOTES -* **Remove-PSDrive** is designed to work with the data exposed by any Windows PowerShell provider. To list the providers in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* **Remove-PSDrive** is designed to work with the data exposed by any Windows PowerShell provider. To list the providers in your session, use the Get-PSProvider cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * diff --git a/reference/5.1/Microsoft.PowerShell.Core/Get-Command.md b/reference/5.1/Microsoft.PowerShell.Core/Get-Command.md index f34d0e1f36c7..d67e4cdcafb0 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Get-Command.md @@ -255,7 +255,7 @@ To detect dynamic parameters that are available only when certain other paramete To detect the dynamic parameters that a provider adds to a cmdlet, set the value of the *ArgumentList* parameter to a path in the provider drive, such as WSMan:, HKLM:, or Cert:. When the command is a Windows PowerShell provider cmdlet, enter only one path in each command. The provider cmdlets return only the dynamic parameters for the first path the value of *ArgumentList*. -For information about the provider cmdlets, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250) in the TechNet library. +For information about the provider cmdlets, see [about_Providers](About/about_Providers.md). ```yaml Type: Object[] diff --git a/reference/5.1/Microsoft.PowerShell.Core/Get-Help.md b/reference/5.1/Microsoft.PowerShell.Core/Get-Help.md index 5dfe0c30b82b..7288c23a4907 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Get-Help.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Get-Help.md @@ -513,7 +513,7 @@ To see the custom cmdlet help for a provider path, go to the provider path locat You can also find custom cmdlet help online in the provider help section of the help topics. For example, you can find help for the **New-Item** cmdlet in the Wsman:\*\ClientCertificate path (http://go.microsoft.com/fwlink/?LinkID=158676). -For more information about Windows PowerShell providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250) in the TechNet library. +For more information about Windows PowerShell providers, see [about_Providers](About/about_Providers.md). ```yaml Type: String diff --git a/reference/5.1/Microsoft.PowerShell.Management/Get-Content.md b/reference/5.1/Microsoft.PowerShell.Management/Get-Content.md index 3c363fae179e..a60d62e83ce7 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Get-Content.md @@ -372,7 +372,7 @@ This cmdlet returns strings or bytes. The output type depends upon the content that it gets. ## NOTES -* This cmdlet is designed to work with the data exposed by any provider. To get the providers in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers(http://go.microsoft.com/fwlink/?LinkID=113250). +* This cmdlet is designed to work with the data exposed by any provider. To get the providers in your session, use the Get-PSProvider cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) * diff --git a/reference/5.1/Microsoft.PowerShell.Management/Get-PSDrive.md b/reference/5.1/Microsoft.PowerShell.Management/Get-PSDrive.md index dc537a246bb8..c9c81390aa87 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Get-PSDrive.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Get-PSDrive.md @@ -278,7 +278,7 @@ You cannot pipe objects to this cmdlet. This cmdlet returns objects that represent the drives in the session. ## NOTES -* This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the **Get-PSProvider** cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the **Get-PSProvider** cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * Mapped network drives that are created by using the *Persist* parameter of the New-PSDrive cmdlet are specific to a user account. Mapped network drives that you create in sessions that are started with the Run as administrator option or with the credentials of another user are not visible in sessions that are started without explicit credentials or with the credentials of the current user. ## RELATED LINKS diff --git a/reference/5.1/Microsoft.PowerShell.Management/New-PSDrive.md b/reference/5.1/Microsoft.PowerShell.Management/New-PSDrive.md index 128108975eef..c4a1cf5882e9 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/New-PSDrive.md +++ b/reference/5.1/Microsoft.PowerShell.Management/New-PSDrive.md @@ -391,7 +391,7 @@ You cannot pipe input to this cmdlet. ### System.Management.Automation.PSDriveInfo ## NOTES -* **New-PSDrive** is designed to work with the data exposed by any provider. To list the providers available in your session, use **Get-PSProvider**. For more information about providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* **New-PSDrive** is designed to work with the data exposed by any provider. To list the providers available in your session, use **Get-PSProvider**. For more information about providers, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * Mapped network drives are specific to a user account. Mapped network drives that you create in sessions that are started by using the Run as administrator option or by using the credential of another user are not visible in a session that was started without explicit credentials, or by using the credentials of the current user. ## RELATED LINKS diff --git a/reference/5.1/Microsoft.PowerShell.Management/Remove-PSDrive.md b/reference/5.1/Microsoft.PowerShell.Management/Remove-PSDrive.md index 052d8763b2a6..71f832d53297 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Remove-PSDrive.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Remove-PSDrive.md @@ -202,7 +202,7 @@ You can pipe a drive object, such as one from the Get-PSDrive cmdlet, to the thi This cmdlet does not return any output. ## NOTES -* **Remove-PSDrive** is designed to work with the data exposed by any Windows PowerShell provider. To list the providers in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* **Remove-PSDrive** is designed to work with the data exposed by any Windows PowerShell provider. To list the providers in your session, use the Get-PSProvider cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * diff --git a/reference/6/Microsoft.PowerShell.Core/Get-Command.md b/reference/6/Microsoft.PowerShell.Core/Get-Command.md index f34d0e1f36c7..d67e4cdcafb0 100644 --- a/reference/6/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/6/Microsoft.PowerShell.Core/Get-Command.md @@ -255,7 +255,7 @@ To detect dynamic parameters that are available only when certain other paramete To detect the dynamic parameters that a provider adds to a cmdlet, set the value of the *ArgumentList* parameter to a path in the provider drive, such as WSMan:, HKLM:, or Cert:. When the command is a Windows PowerShell provider cmdlet, enter only one path in each command. The provider cmdlets return only the dynamic parameters for the first path the value of *ArgumentList*. -For information about the provider cmdlets, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250) in the TechNet library. +For information about the provider cmdlets, see [about_Providers](About/about_Providers.md). ```yaml Type: Object[] diff --git a/reference/6/Microsoft.PowerShell.Core/Get-Help.md b/reference/6/Microsoft.PowerShell.Core/Get-Help.md index a72f63506721..f6ee740efbf4 100644 --- a/reference/6/Microsoft.PowerShell.Core/Get-Help.md +++ b/reference/6/Microsoft.PowerShell.Core/Get-Help.md @@ -507,7 +507,7 @@ To see the custom cmdlet help for a provider path, go to the provider path locat You can also find custom cmdlet help online in the provider help section of the help topics. For example, you can find help for the **New-Item** cmdlet in the Wsman:\*\ClientCertificate path (http://go.microsoft.com/fwlink/?LinkID=158676). -For more information about Windows PowerShell providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250) in the TechNet library. +For more information about Windows PowerShell providers, see [about_Providers](About/about_Providers.md). ```yaml Type: String diff --git a/reference/6/Microsoft.PowerShell.Core/help.md b/reference/6/Microsoft.PowerShell.Core/help.md index e39ef257f13b..538caecdec98 100644 --- a/reference/6/Microsoft.PowerShell.Core/help.md +++ b/reference/6/Microsoft.PowerShell.Core/help.md @@ -510,7 +510,7 @@ To see the custom cmdlet help for a provider path, go to the provider path locat You can also find custom cmdlet help online in the provider help section of the help topics. For example, you can find help for the New-Item cmdlet in the Wsman:\*\ClientCertificate path (http://go.microsoft.com/fwlink/?LinkID=158676). -For more information about Windows PowerShell providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250) in the TechNet library. +For more information about Windows PowerShell providers, see [about_Providers](About/about_Providers.md). ```yaml Type: String diff --git a/reference/6/Microsoft.PowerShell.Management/Get-Content.md b/reference/6/Microsoft.PowerShell.Management/Get-Content.md index a1e2150bf7b4..5fae0eb88ea1 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-Content.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-Content.md @@ -374,7 +374,7 @@ This cmdlet returns strings or bytes. The output type depends upon the content that it gets. ## NOTES -* This cmdlet is designed to work with the data exposed by any provider. To get the providers in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers(http://go.microsoft.com/fwlink/?LinkID=113250). +* This cmdlet is designed to work with the data exposed by any provider. To get the providers in your session, use the Get-PSProvider cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md) * diff --git a/reference/6/Microsoft.PowerShell.Management/Get-PSDrive.md b/reference/6/Microsoft.PowerShell.Management/Get-PSDrive.md index 19b35c93e94a..2514c905e2c4 100644 --- a/reference/6/Microsoft.PowerShell.Management/Get-PSDrive.md +++ b/reference/6/Microsoft.PowerShell.Management/Get-PSDrive.md @@ -306,7 +306,7 @@ You cannot pipe objects to this cmdlet. This cmdlet returns objects that represent the drives in the session. ## NOTES -* This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the **Get-PSProvider** cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* This cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, use the **Get-PSProvider** cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * Mapped network drives that are created by using the *Persist* parameter of the New-PSDrive cmdlet are specific to a user account. Mapped network drives that you create in sessions that are started with the Run as administrator option or with the credentials of another user are not visible in sessions that are started without explicit credentials or with the credentials of the current user. ## RELATED LINKS diff --git a/reference/6/Microsoft.PowerShell.Management/New-PSDrive.md b/reference/6/Microsoft.PowerShell.Management/New-PSDrive.md index 619815f569eb..0dd28f558cce 100644 --- a/reference/6/Microsoft.PowerShell.Management/New-PSDrive.md +++ b/reference/6/Microsoft.PowerShell.Management/New-PSDrive.md @@ -425,7 +425,7 @@ You cannot pipe input to this cmdlet. ### System.Management.Automation.PSDriveInfo ## NOTES -* **New-PSDrive** is designed to work with the data exposed by any provider. To list the providers available in your session, use **Get-PSProvider**. For more information about providers, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* **New-PSDrive** is designed to work with the data exposed by any provider. To list the providers available in your session, use **Get-PSProvider**. For more information about providers, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * Mapped network drives are specific to a user account. Mapped network drives that you create in sessions that are started by using the Run as administrator option or by using the credential of another user are not visible in a session that was started without explicit credentials, or by using the credentials of the current user. ## RELATED LINKS diff --git a/reference/6/Microsoft.PowerShell.Management/Remove-PSDrive.md b/reference/6/Microsoft.PowerShell.Management/Remove-PSDrive.md index 3b9ce5609e23..505bc609a602 100644 --- a/reference/6/Microsoft.PowerShell.Management/Remove-PSDrive.md +++ b/reference/6/Microsoft.PowerShell.Management/Remove-PSDrive.md @@ -233,7 +233,7 @@ You can pipe a drive object, such as one from the Get-PSDrive cmdlet, to the thi This cmdlet does not return any output. ## NOTES -* **Remove-PSDrive** is designed to work with the data exposed by any Windows PowerShell provider. To list the providers in your session, use the Get-PSProvider cmdlet. For more information, see about_Providers (http://go.microsoft.com/fwlink/?LinkID=113250). +* **Remove-PSDrive** is designed to work with the data exposed by any Windows PowerShell provider. To list the providers in your session, use the Get-PSProvider cmdlet. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). * From b1a95ce6c2e273cf9911a6fcae9ea19805dc85ce Mon Sep 17 00:00:00 2001 From: PRASOON KARUNAN V Date: Thu, 4 Jan 2018 01:27:58 +0530 Subject: [PATCH 146/188] Help doc enhancement for ConvertFrom-StringData cmdlet (#2002) * Help doc correction Removed an unwanted * from Notes section Corrected intenting for last example Removed unwanted ... from example 2 * Help doc wnhancements in all versions for ConvertFrom-StringData Removed an unwanted * from Notes section Corrected intenting for last example Removed unwanted ... from example 2 --- .../ConvertFrom-StringData.md | 7 +++---- .../ConvertFrom-StringData.md | 7 +++---- .../ConvertFrom-StringData.md | 8 ++++---- .../ConvertFrom-StringData.md | 8 ++++---- .../ConvertFrom-StringData.md | 8 ++++---- 5 files changed, 18 insertions(+), 20 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md index 8b77d5081fd9..d0e26d8caecc 100644 --- a/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md +++ b/reference/3.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md @@ -66,7 +66,7 @@ TypeName: System.String Name MemberType Definition ---- ---------- ---------- Clone Method System.Object Clone() -... + PS C:\> $hash = convertfrom-stringdata -stringdata $p PS C:\> $hash | get-member TypeName: System.Collections.Hashtable @@ -74,7 +74,7 @@ TypeName: System.Collections.Hashtable Name MemberType Definition ---- ---------- ---------- Add Method System.Void Add(Object key, Object -... + ``` These commands demonstrate that ConvertFrom-StringData actually converts a here-string to a hash table. @@ -246,9 +246,8 @@ ConvertFrom-StringData returns a hash table that it creates from the key/value p * 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. + 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. -* ## RELATED LINKS [about_Quoting_Rules](../Microsoft.PowerShell.Core/About/about_Quoting_Rules.md) diff --git a/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md b/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md index 0ff4ddf17f0a..4503480cd63e 100644 --- a/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md +++ b/reference/4.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md @@ -69,7 +69,7 @@ TypeName: System.String Name MemberType Definition ---- ---------- ---------- Clone Method System.Object Clone() -... + PS C:\> $hash = convertfrom-stringdata -stringdata $p PS C:\> $hash | get-member TypeName: System.Collections.Hashtable @@ -77,7 +77,7 @@ TypeName: System.Collections.Hashtable Name MemberType Definition ---- ---------- ---------- Add Method System.Void Add(Object key, Object -... + ``` These commands demonstrate that ConvertFrom-StringData actually converts a here-string to a hash table. @@ -259,9 +259,8 @@ ConvertFrom-StringData returns a hash table that it creates from the key/value p * 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. + 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. -* ## RELATED LINKS diff --git a/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md b/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md index cde192d770e5..9b7be61d5e7b 100644 --- a/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md +++ b/reference/5.0/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md @@ -68,13 +68,14 @@ TypeName: System.String Name MemberType Definition ---- ---------- ---------- Clone Method System.Object Clone() -... PS C:\> $Hash = ConvertFrom-StringData -StringData $P + +PS C:\> $Hash = ConvertFrom-StringData -StringData $P PS C:\> $Hash | Get-Member TypeName: System.Collections.Hashtable Name MemberType Definition ---- ---------- ---------- Add Method System.Void Add(Object key, Object -... + ``` These commands demonstrate that **ConvertFrom-StringData** actually converts a here-string to a hash table. @@ -251,9 +252,8 @@ This cmdlet returns a hash table that it creates from the key/value pairs. * A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. This cmdlet 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. + 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. -* ## RELATED LINKS diff --git a/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md b/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md index a1b6f1fa36ba..4a52dfe0f0a8 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md @@ -69,13 +69,14 @@ TypeName: System.String Name MemberType Definition ---- ---------- ---------- Clone Method System.Object Clone() -... PS C:\> $Hash = ConvertFrom-StringData -StringData $P + +PS C:\> $Hash = ConvertFrom-StringData -StringData $P PS C:\> $Hash | Get-Member TypeName: System.Collections.Hashtable Name MemberType Definition ---- ---------- ---------- Add Method System.Void Add(Object key, Object -... + ``` These commands demonstrate that **ConvertFrom-StringData** actually converts a here-string to a hash table. @@ -252,9 +253,8 @@ This cmdlet returns a hash table that it creates from the key/value pairs. * A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. This cmdlet 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. + 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. -* ## RELATED LINKS diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md index 33cee464f251..af8f1330fc97 100644 --- a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-StringData.md @@ -70,13 +70,14 @@ TypeName: System.String Name MemberType Definition ---- ---------- ---------- Clone Method System.Object Clone() -... PS C:\> $Hash = ConvertFrom-StringData -StringData $P + +PS C:\> $Hash = ConvertFrom-StringData -StringData $P PS C:\> $Hash | Get-Member TypeName: System.Collections.Hashtable Name MemberType Definition ---- ---------- ---------- Add Method System.Void Add(Object key, Object -... + ``` These commands demonstrate that **ConvertFrom-StringData** actually converts a here-string to a hash table. @@ -288,9 +289,8 @@ This cmdlet returns a hash table that it creates from the key/value pairs. * A here-string is a string consisting of one or more lines within which quotation marks are interpreted literally. This cmdlet 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. + 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. -* ## RELATED LINKS From fa96dbb687661423f8e73037dc2a72b1104e524b Mon Sep 17 00:00:00 2001 From: Dan Travison Date: Wed, 3 Jan 2018 13:16:39 -0800 Subject: [PATCH 147/188] PowerShell 6 logging on Windows, Linux, and MacOS (#1922) * First draft of PowerShell 6 logging * Fix style guideline issues. * Document logging settings in PowerShellProperties.json * Address PR Feedback Limit lines to 80 columns, when possible Insert
in selected locations to improve readability of rendered markdown. * Reformatted tables Reformatted tables to work with new processing of About_* topics --- .../About/about_Logging.md | 203 ++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_Logging.md diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md new file mode 100644 index 000000000000..f22df57b0193 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md @@ -0,0 +1,203 @@ +--- +ms.date: 2017-12-04 +schema: 2.0.0 +locale: en-us +keywords: powershell +title: about_Logging +--- + +# About Logging + +## Short Description + +PowerShell logs internal operations from the engine, providers, and +cmdlets. + + +## Long Description + +PowerShell logs details of PowerShell operations, such as starting +and stopping the engine and starting and stopping providers. It will +also log details about PowerShell commands. + +The location of PowerShell logs is dependent on the target platform. +On Windows, PowerShell logs to the event log, on Linux, PowerShell logs +to syslog, and on MacOS, the os_log logging system is used. + +## Viewing the PowerShell event log on Windows + +PowerShell logs can be viewed using the Event Viewer. The event log is +located in the Application and Services Logs group and is named PowerShellCore. +The associated ETW provider guid is `{f90714a8-5509-434a-bf6d-b1624c8a19a2}` + +### Registering the PowerShell event provider on Windows + +Unlike Linux or MacOS, Windows requires the event provider to be registered +before logged events can appear in the event log. For PowerShell, this is +accomplished by running the `RegisterManifest.ps1` from an elevated +PowerShell prompt. + +The script is located in the the $PSHOME directory and should be run from +that location. + +### Unregistering the PowerShell event provider on Windows + +Registering an event provider places a lock in the binary containing the data +needed to decode events. To update this binary, the provider must first be +unregistered to release this lock. + +To unregister the PowerShell provider, run the `RegisterManifest.ps1` from an +elevated PowerShell prompt and specify the `-Unregister` switch. Once the +upgrade of PowerShell has completed, run `RegisterManifest.ps1` a second time +to register the updated ETW provider. + +## Viewing PowerShell log output on Linux + +PowerShell logs to syslog on Linux and any of the tools commonly used to view +syslog contents may be used. + +The format of the log entries uses the following template: + +``` +TIMESTAMP MACHINENAME powershell[PID]: (COMMITID:TID:CID) + [EVENTID:TASK.OPCODE.LEVEL] MESSAGE +``` + +|Field |Description | +|-------------|--------------------------------------------------------| +|`TIMESTAMP` |A date/time when the log entry was produced. | +|`MACHINENAME`|The name of the system where the log was produced. | +|`PID` |The process id of the process that wrote the log entry. | +|`COMMITID` |The git commit id or tag used to produce the build. | +|`TID` |The thread id of the thread that wrote the log entry. | +|`CID` |The hex channel identifier of the log entry. | +| |10 = Operational, 11 = Analytic | +|`EVENTID` |The event identifier of the log entry. | +|`TASK` |The task identifier for the event entry | +|`OPCODE` |The opcode for the event entry | +|`LEVEL` |The log level for the event entry | +|`MESSAGE` |The message associated with the event entry | + +* NOTE: EVENTID, TASK, OPCODE, and LEVEL are the same values as used when +logging to the windows event log. + +### Filtering PowerShell log entries using rsyslog + +By default, PowerShell log entries are written to the default location/file +for syslog. However, it is possible to redirect the entries to a custom +file. + +* Create a conf for PowerShell log configuration and provide a number that +is less than 50 (for `50-default.conf`), such as `40-powershell.conf`. The +file should be placed under `/etc/rsyslog.d`. + +* Add the following entry to the file +``` +:syslogtag, contains, "powershell[" /var/log/powershell.log +& stop +``` +* Ensure `/etc/rsyslog.conf` includes the new file. Often, it will have +a generic include statement that looks like following: + +`$IncludeCnofig /etc/rsyslog.d/*.conf` + +If it does not, you will need to add an include statement manually. + +* Ensure attributes and permissions are set appropriately + +``` +-rw-r--r-- 1 root root 67 Nov 28 12:51 40-powershell.conf +``` +- Set ownership to root +``` +chown root:root /etc/rsyslog.d/40-powershell.conf +``` +- Set access permissions - root has read/write, users have read. +``` +chmod 644 /etc/rsyslog.d/40-powershell.conf +``` + +## Viewing PowerShell log output on MacOS + +The easiest method for viewing PowerShell log output on MacOS is using the +Console application. + +* Search for the Console application and launch it +* Select the Machine name under Devices +* In the Search field, entry 'pwsh'; the PowerShell main binary. +* Change search filter from 'Any' to 'Process' +* Peform the operations +* Optionally save the search for future use. + +To filter on a specific process instance of PowerShell in the Console, the +variable $pid contains the process id. +* Enter the pid (Process Id) in the Search field. +* Change search filter PID +* Perform the operations + +### Viewing PowerShell log output from a command-line + +The `log` command can be used to view PowerShell log entries from the +command-line. + +``` +sudo log stream --predicate 'process == "pwsh"' --info +``` + +## Configuring Logging on non-Windows systems + +On Windows, logging is configured by creating ETW trace listeners or by using +the Event Viewer to enable Analytic logging. On Linux and MacOS, logging is +configured using the file `PowerShellProperties.json`. The rest of this section +will discuss configuring PowerShell logging on non-Windows system. + +By default, PowerShell enables informational logging to the operational +channel. What this means is any log output produced by PowerShell that is +marked as operational and has a log (trace) level greater then informational +will be logged. Occasionally, diagnoses may require additional log output, +such as verbose log output or enabling analytic log output. + +The file `PowerShellProperties.json` is a JSON formatted file residing in the +PowerShell $PSHOME directory. Each installation of PowerShell uses it's own +copy of this file. For normal operation, this file is left unchanged but it +can be useful for diagnosis or for distinguishing between multiple PowerShell +versions on the same system or even multiple copies of the same version +(See LogIdentity in the table below). + +The properties for configuring PowerShell logging are listed in the following +table. +Values marked with an asterick, such as `Operational*`, indicate the default +value when no value is provided in the file. + +|Property |Values |Description | +|-----------|--------------|---------------------------------------------| +|LogIdentity|(string name) |The name to use when logging. By default, | +| |powershell* |powershell is the identity. This value can be| +| | |used to distinguish between two instances of | +| | |a PowerShell installation, such as a release | +| | |and beta version. This value is also used to | +| | |redirect log output to a separate file on | +| | |Linux. See the discussion of rsyslog above. | +|LogChannels|Operational* |The channels to enable. Seperate the values | +| |Analytic |with a comma when specifying more than one. | +|LogLevel |Always |Specify a single value. The value enables | +| |Critical |itself as well as all values above it in the | +| |Error |list to the left. | +| |Warning | | +| |Informational*| | +| |Verbose | | +| |Debug | | +|LogKeywords|Runspace |Keywords provide the ability to limit logging| +| |Pipeline |to specific components within PowerShell. By | +| |Protocol |default, all keywords are enabled and change | +| |Transport |this value is generaly only useful for very | +| |Host |specialized trouble shooting. | +| |Cmdlets | | +| |Serializer | | +| |Session | | +| |ManagedPlugin | | + +## SEE ALSO +- syslog and rsyslog.conf man pages. +- os_log developer documentation +- Event Viewer From 1ed352f37bb003eaba3a4460728d488498542cc0 Mon Sep 17 00:00:00 2001 From: Mariah Date: Wed, 3 Jan 2018 13:16:59 -0800 Subject: [PATCH 148/188] Adding calling the ComputerName parameter to the example (#1964) * Adding calling the ComputerName parameter to the example * Changing quotes to brackets --- dsc/configurations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dsc/configurations.md b/dsc/configurations.md index a8f86877b180..d30cde9ba65b 100644 --- a/dsc/configurations.md +++ b/dsc/configurations.md @@ -61,7 +61,7 @@ Configuration MyDscConfiguration { } } } -MyDscConfiguration +MyDscConfiguration -ComputerName ``` From 43ba68fb5d57cf1aedd026b62136ebe327eecc36 Mon Sep 17 00:00:00 2001 From: SwarfegaGit Date: Thu, 4 Jan 2018 15:45:05 +0000 Subject: [PATCH 149/188] Removed unused variable in Example 1 (#2004) The variable was declared but not used. It also appears in the same place in Example 2 but is used later on. --- dsc/scriptResource.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/dsc/scriptResource.md b/dsc/scriptResource.md index 1adb5ff7a676..57d83484638f 100644 --- a/dsc/scriptResource.md +++ b/dsc/scriptResource.md @@ -47,8 +47,6 @@ Script [string] #ResourceName ## Example 1 ```powershell -$version = Get-Content 'version.txt' - Configuration ScriptTest { Import-DscResource –ModuleName 'PSDesiredStateConfiguration' From 308c233315b17cf365483891c9afa2cec3a30424 Mon Sep 17 00:00:00 2001 From: regexaurus Date: Thu, 4 Jan 2018 10:53:52 -0500 Subject: [PATCH 150/188] Made surrounding text agree with sample code. (#2003) --- .../Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md | 2 +- .../Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md | 2 +- .../Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md | 2 +- .../Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md | 2 +- .../Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md index 22ed5738b480..6703a314a1e3 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md @@ -129,7 +129,7 @@ block. ### USING MULTIPLE CATCH STATEMENTS A Try statement can have any number of Catch blocks. For example, the -following script has a Try block that downloads MyFile.doc, and it contains +following script has a Try block that downloads MyDoc.doc, and it contains two Catch blocks: ```powershell diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md index 22ed5738b480..6703a314a1e3 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md @@ -129,7 +129,7 @@ block. ### USING MULTIPLE CATCH STATEMENTS A Try statement can have any number of Catch blocks. For example, the -following script has a Try block that downloads MyFile.doc, and it contains +following script has a Try block that downloads MyDoc.doc, and it contains two Catch blocks: ```powershell diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md index 22ed5738b480..6703a314a1e3 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md @@ -129,7 +129,7 @@ block. ### USING MULTIPLE CATCH STATEMENTS A Try statement can have any number of Catch blocks. For example, the -following script has a Try block that downloads MyFile.doc, and it contains +following script has a Try block that downloads MyDoc.doc, and it contains two Catch blocks: ```powershell diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md index 22ed5738b480..6703a314a1e3 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md @@ -129,7 +129,7 @@ block. ### USING MULTIPLE CATCH STATEMENTS A Try statement can have any number of Catch blocks. For example, the -following script has a Try block that downloads MyFile.doc, and it contains +following script has a Try block that downloads MyDoc.doc, and it contains two Catch blocks: ```powershell diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md b/reference/6/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md index 22ed5738b480..6703a314a1e3 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Try_Catch_Finally.md @@ -129,7 +129,7 @@ block. ### USING MULTIPLE CATCH STATEMENTS A Try statement can have any number of Catch blocks. For example, the -following script has a Try block that downloads MyFile.doc, and it contains +following script has a Try block that downloads MyDoc.doc, and it contains two Catch blocks: ```powershell From a2607ed03208c844bd1828d21133eefdcfbc19d8 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 4 Jan 2018 12:27:20 -0800 Subject: [PATCH 151/188] Reformatting v4 About_ topics missed in first pass (#2006) * v4 about scrub missed files * fixing broken links * fix broken link --- .../About/about_Debuggers.md | 663 +++++++------ .../About/about_Functions_Advanced_Methods.md | 270 +++--- .../about_Functions_OutputTypeAttribute.md | 118 ++- .../About/about_PSSessions.md | 189 ++-- .../About/about_PSSnapins.md | 188 ++-- .../About/about_Parameters.md | 237 +++-- .../About/about_PowerShell_exe.md | 254 ++--- .../About/about_Providers.md | 269 +++--- .../About/about_Quoting_Rules.md | 257 +++-- .../About/about_Remote.md | 238 ++--- .../About/about_Remote_Requirements.md | 244 +++-- .../About/about_Remote_Variables.md | 148 +-- .../About/about_Requires.md | 5 +- .../About/about_Reserved_Words.md | 2 +- .../About/about_Return.md | 107 +-- .../About/about_Run_With_PowerShell.md | 68 +- .../about_Script_Internationalization.md | 179 ++-- .../about_Session_Configuration_Files.md | 506 +++++----- .../About/about_Signing.md | 326 +++---- .../About/about_Splatting.md | 137 ++- .../About/about_Transactions.md | 847 +++++++++-------- .../About/about_Updatable_Help.md | 664 +++++++------ .../About/about_WMI.md | 100 +- .../About/about_WQL.md | 892 +++++++++--------- .../About/about_Windows_PowerShell_ISE.md | 271 +++--- .../About/about_Windows_RT.md | 70 +- .../About/about_logical_operators.md | 63 +- .../About/about_scopes.md | 598 ++++++------ 28 files changed, 4092 insertions(+), 3818 deletions(-) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Debuggers.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Debuggers.md index 1ae634fbee9d..c7b464110d8d 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Debuggers.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Debuggers.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,64 +7,55 @@ title: about_Debuggers --- # About Debuggers -## about_Debuggers - - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes the Windows PowerShell debugger. -# LONG DESCRIPTION - -Debugging is the process of examining a script while it is running to -identify and correct errors in the script instructions. The -Windows PowerShell debugger can help you examine and identify -errors and inefficiencies in your scripts, functions, commands, Windows -PowerShell workflows, Windows PowerShell Desired State Configuration (DSC) -configurations, or expressions. - -Starting in Windows PowerShell 5.0, the Windows PowerShell debugger has been updated -to debug scripts, functions, workflows, commands, configurations, or expressions that are -running in either the console or Windows PowerShell ISE on remote computers. -You can run Enter-PSSession to start an interactive remote PowerShell session -in which you can set breakpoints and debug script files and commands on the -remote computer. Enter-PSSession functionality has been updated to let you -reconnect to and enter a disconnected session that is running a script or -command on a remote computer. If the running script hits a breakpoint, -your client session automatically starts the debugger. If the disconnected -session that is running a script has already hit a breakpoint, and is stopped -at the breakpoint, Enter-PSSession automatically starts the command-line -debugger, after you reconnect to the session. - -The Windows PowerShell debugger can also be used to debug Windows -PowerShell workflows, in either the Windows PowerShell console, or in -Windows PowerShell ISE. Starting in Windows PowerShell 5.0, you can debug -within running jobs or processes, either locally or remotely. +## LONG DESCRIPTION + +Debugging is the process of examining a script while it is running to identify +and correct errors in the script instructions. The Windows PowerShell debugger +can help you examine and identify errors and inefficiencies in your scripts, +functions, commands, Windows PowerShell workflows, Windows PowerShell Desired +State Configuration (DSC) configurations, or expressions. + +Starting in Windows PowerShell 5.0, the Windows PowerShell debugger has been +updated to debug scripts, functions, workflows, commands, configurations, or +expressions that are running in either the console or Windows PowerShell ISE +on remote computers. You can run Enter-PSSession to start an interactive +remote PowerShell session in which you can set breakpoints and debug script +files and commands on the remote computer. Enter-PSSession functionality has +been updated to let you reconnect to and enter a disconnected session that is +running a script or command on a remote computer. If the running script hits a +breakpoint, your client session automatically starts the debugger. If the +disconnected session that is running a script has already hit a breakpoint, +and is stopped at the breakpoint, Enter-PSSession automatically starts the +command-line debugger, after you reconnect to the session. + +The Windows PowerShell debugger can also be used to debug Windows PowerShell +workflows, in either the Windows PowerShell console, or in Windows PowerShell +ISE. Starting in Windows PowerShell 5.0, you can debug within running jobs or +processes, either locally or remotely. You can use the features of the Windows PowerShell debugger to examine a -Windows PowerShell script, function, command, workflow, or expression -while it is running. The Windows PowerShell debugger includes a set of -cmdlets that let you set breakpoints, manage breakpoints, and view the call -stack. - -Debugger Cmdlets -The Windows PowerShell debugger includes the following set of cmdlets: +Windows PowerShell script, function, command, workflow, or expression while it +is running. The Windows PowerShell debugger includes a set of cmdlets that let +you set breakpoints, manage breakpoints, and view the call stack. -Set-PsBreakpoint: Sets breakpoints on lines, variables, and -commands. +## Debugger Cmdlets -Get-PsBreakpoint: Gets breakpoints in the current session. - -Disable-PsBreakpoint: Turns off breakpoints in the current session. - -Enable-PsBreakpoint: Re-enables breakpoints in the current session. +The Windows PowerShell debugger includes the following set of cmdlets: -Remove-PsBreakpoint: Deletes breakpoints from the current session. +- `Set-PsBreakpoint`: Sets breakpoints on lines, variables, and commands. +- `Get-PsBreakpoint`: Gets breakpoints in the current session. +- `Disable-PsBreakpoint`: Turns off breakpoints in the current session. +- `Enable-PsBreakpoint`: Re-enables breakpoints in the current session. +- `Remove-PsBreakpoint`: Deletes breakpoints from the current session. +- `Get-PsCallStack`: Displays the current call stack. -Get-PsCallStack: Displays the current call stack. +## Starting and Stopping the Debugger -Starting and Stopping the Debugger To start the debugger, set one or more breakpoints. Then, run the script, command, or function that you want to debug. @@ -72,89 +63,85 @@ When you reach a breakpoint, execution stops, and control is turned over to the debugger. To stop the debugger, run the script, command, or function until it is -complete. Or, type "stop" or "t". +complete. Or, type `stop` or `t`. -Debugger Commands -When you use the debugger in the Windows PowerShell console, use the -following commands to control the execution. In Windows PowerShell ISE, -use commands on the Debug menu. +### Debugger Commands + +When you use the debugger in the Windows PowerShell console, use the following +commands to control the execution. In Windows PowerShell ISE, use commands on +the Debug menu. Note: For information about how to use the debugger in other host applications, see the host application documentation. -s, Step-into Executes the next statement and then stops. +- `s`, `StepInto`: Executes the next statement and then stops. -v, Step-over Executes the next statement, but skips functions -and invocations. The skipped statements are -executed, but not stepped through. +- `v`, `StepOver`: Executes the next statement, but skips functions and + invocations. The skipped statements are executed, but not stepped through. -Ctrl+Break -(Break All in ISE) Breaks into a running script within either the -Windows PowerShell console, or Windows PowerShell ISE. -Note that Ctrl+Break in Windows PowerShell 2.0, 3.0, -and 4.0 closes the program. Break All works on both -local and remote interactively-running scripts. +- `Ctrl+Break`: (Break All in ISE) Breaks into a running script within either + the Windows PowerShell console, or Windows PowerShell ISE. Note that + Ctrl+Break in Windows PowerShell 2.0, 3.0, and 4.0 closes the program. Break + All works on both local and remote interactively-running scripts. -o, Step-out Steps out of the current function; up one level -if nested. If in the main body, it continues to -the end or the next breakpoint. The skipped -statements are executed, but not stepped through. +- `o`, `StepOut`: Steps out of the current function; up one level if nested. + If in the main body, it continues to the end or the next breakpoint. The + skipped statements are executed, but not stepped through. -c, Continue Continues to run until the script is complete or -until the next breakpoint is reached. The skipped -statements are executed, but not stepped through. +- `c`, `Continue`: Continues to run until the script is complete or until the + next breakpoint is reached. The skipped statements are executed, but not + stepped through. -l, List Displays the part of the script that is executing. -By default, it displays the current line, five -previous lines, and 10 subsequent lines. To continue -listing the script, press ENTER. +- `l`, `List`: Displays the part of the script that is executing. By default, + it displays the current line, five previous lines, and 10 subsequent lines. + To continue listing the script, press ENTER. -l , List Displays 16 lines of the script beginning with the -line number specified by . +- `l `, `List`: Displays 16 lines of the script beginning with the line + number specified by ``. -l , List Displays lines of the script, beginning with the -line number specified by . +- `l `, `List`: Displays `` lines of the script, beginning with the + line number specified by ``. -q, Stop, Exit Stops executing the script, and exits the debugger. If you -are debugging a job by running the Debug-Job cmdlet, the Exit -command detaches the debugger, and allows the job to continue -running. +- `q`, `Stop`, `Exit`: Stops executing the script, and exits the debugger. If + you are debugging a job by running the Debug-Job cmdlet, the Exit command + detaches the debugger, and allows the job to continue running. -k, Get-PsCallStack Displays the current call stack. +- `k`, `Get-PsCallStack`: Displays the current call stack. - Repeats the last command if it was Step (s), -Step-over (v), or List (l). Otherwise, represents a -submit action. +- ``: Repeats the last command if it was Step (s), StepOver (v), or + List (l). Otherwise, represents a submit action. -?, h Displays the debugger command Help. +- `?`, `h`: Displays the debugger command Help. To exit the debugger, you can use Stop (q). + Starting in Windows PowerShell 5.0, you can run the Exit command to exit a nested debugging session that you started by running either Debug-Job or Debug-Runspace. -By using these debugger commands, you can run a script, stop on a point -of concern, examine the values of variables and the state of the system, -and continue running the script until you have identified a problem. +By using these debugger commands, you can run a script, stop on a point of +concern, examine the values of variables and the state of the system, and +continue running the script until you have identified a problem. -NOTE: If you step into a statement with a redirection operator, -such as ">", the Windows PowerShell debugger steps over all -remaining statements in the script. +NOTE: If you step into a statement with a redirection operator, such as ">", +the Windows PowerShell debugger steps over all remaining statements in the +script. Displaying the Values of script Variables -While you are in the debugger, you can also enter commands, display the -value of variables, use cmdlets, and run scripts at the command line. +While you are in the debugger, you can also enter commands, display the value +of variables, use cmdlets, and run scripts at the command line. -You can display the current value of all variables in the script that is -being debugged, except for the following automatic variables: - -# $_ +You can display the current value of all variables in the script that is being +debugged, except for the following automatic variables: +```powershell +$_ $Args $Input $MyInvocation $PSBoundParameters +``` If you try to display the value of any of these variables, you get the value of that variable for in an internal pipeline the debugger uses, not @@ -166,15 +153,20 @@ Then you can display the value of the new variable. For example, +```powershell $scriptArgs = $Args $scriptArgs +``` In the example in this topic, the value of the $MyInvocation variable is reassigned as follows: +```powershell $scriptname = $MyInvocation.MyCommand.Path +``` + +## The Debugger Environment -The Debugger Environment When you reach a breakpoint, you enter the debugger environment. The command prompt changes so that it begins with "[DBG]:". If you are debugging a workflow, the prompt is "[WFDBG]". You can customize @@ -189,87 +181,98 @@ command prompt. For example, the following is the default debugging prompt in the Windows PowerShell console: +``` [DBG]: PS (get-location)>>> +``` -You can find the nesting level by using the $NestedPromptLevel +You can find the nesting level by using the \$NestedPromptLevel automatic variable. -Additionally, an automatic variable, $PSDebugContext, is defined in -the local scope. You can use the presence of the $PsDebugContext +Additionally, an automatic variable, \$PSDebugContext, is defined in +the local scope. You can use the presence of the \$PsDebugContext variable to determine whether you are in the debugger. For example: +```powershell if ($psdebugcontext) {"Debugging"} else {"Not Debugging"} +``` -You can use the value of the $PSDebugContext variable in your +You can use the value of the \$PSDebugContext variable in your debugging. +``` [DBG]: PS>>> $psdebugcontext.invocationinfo Name CommandLineParameters UnboundArguments Location ---- --------------------- ---------------- -------- = {} {} C:\ps-test\vote.ps1 (1) +``` + +## Debugging and Scope -Debugging and Scope -Breaking into the debugger does not change the scope in which -you are operating, but when you reach a breakpoint in a script, -you move into the script scope. The script scope is a child -of the scope in which you ran the debugger. +Breaking into the debugger does not change the scope in which you are +operating, but when you reach a breakpoint in a script, you move into the +script scope. The script scope is a child of the scope in which you ran the +debugger. -To find the variables and aliases that are defined in the -script scope, use the Scope parameter of the Get-Alias or -Get-Variable cmdlets. +To find the variables and aliases that are defined in the script scope, use +the Scope parameter of the Get-Alias or Get-Variable cmdlets. -For example, the following command gets the variables in the -local (script) scope: +For example, the following command gets the variables in the local (script) +scope: +```powershell get-variable -scope 0 +``` You can abbreviate the command as: +```powershell gv -s 0 +``` -This is a useful way to see only the variables that you defined in the -script and that you defined while debugging. +This is a useful way to see only the variables that you defined in the script +and that you defined while debugging. Debugging at the Command Line -When you set a variable breakpoint or a command breakpoint, you can set -the breakpoint only in a script file. However, by default, the breakpoint -is set on anything that runs in the current session. - -For example, if you set a breakpoint on the $name variable, the debugger -breaks on any $name variable in any script, command, function, script -cmdlet or expression that you run until you disable or remove the -breakpoint. - -This allows you to debug your scripts in a more realistic context in -which they might be affected by functions, variables, and other scripts -in the session and in the user's profile. - -Line breakpoints are specific to script files, so they are set only in -script files. - -Debugging Workflows -The Windows PowerShell 4.0 debugger can be used to debug Windows -PowerShell workflows, either in the Windows PowerShell console, or in -Windows PowerShell ISE. There are some limitations with using -the Windows PowerShell debugger to debug workflows. - --- You can view workflow variables while you are in the debugger, but -setting workflow variables from within the debugger is not supported. --- Tab completion when stopped in the workflow debugger is not -available. --- Workflow debugging works only with synchronous running of workflows from -a Windows PowerShell script. You cannot debug workflows if they are -running as a job (with the -AsJob parameter). --- Other nested debugging scenarios--such as a workflow calling another -workflow, or a workflow calling a script--are not implemented. - -The following example demonstrates debugging a workflow. Note that when -the debugger steps into the workflow function, the debugger prompt changes -to [WFDBG]. +When you set a variable breakpoint or a command breakpoint, you can set the +breakpoint only in a script file. However, by default, the breakpoint is set +on anything that runs in the current session. + +For example, if you set a breakpoint on the \$name variable, the debugger +breaks on any \$name variable in any script, command, function, script cmdlet +or expression that you run until you disable or remove the breakpoint. + +This allows you to debug your scripts in a more realistic context in which +they might be affected by functions, variables, and other scripts in the +session and in the user's profile. + +Line breakpoints are specific to script files, so they are set only in script +files. + +## Debugging Workflows + +The Windows PowerShell 4.0 debugger can be used to debug Windows PowerShell +workflows, either in the Windows PowerShell console, or in Windows PowerShell +ISE. There are some limitations with using the Windows PowerShell debugger to +debug workflows. + +- You can view workflow variables while you are in the debugger, but setting + workflow variables from within the debugger is not supported. +- Tab completion when stopped in the workflow debugger is not available. +- Workflow debugging works only with synchronous running of workflows from a + Windows PowerShell script. You cannot debug workflows if they are running as a + job (with the **-AsJob** parameter). +- Other nested debugging scenarios--such as a workflow calling another + workflow, or a workflow calling a script--are not implemented. + +The following example demonstrates debugging a workflow. Note that when the +debugger steps into the workflow function, the debugger prompt changes to +[WFDBG]. + +```powershell PS C:> Set-PSBreakpoint -Script C:\TestWFDemo1.ps1 -Line 8 ID Script Line Command Variable Action @@ -350,32 +353,32 @@ At C:\TestWFDemo1.ps1:11 char:5 [WFDBG:localhost]: PS C:>> stepOut Get PowerShell process: -Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName PSComputerName -------- ------ ----- ----- ----- ------ -- ----------- -------------- -433 35 106688 128392 726 2.67 7124 powershell localhost -499 44 134244 172096 787 2.79 7452 powershell localhost +Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName +------- ------ ----- ----- ----- ------ -- ----------- + 433 35 106688 128392 726 2.67 7124 powershell + 499 44 134244 172096 787 2.79 7452 powershell + Workflow function complete. +``` + +## Debugging Functions -Debugging Functions When you set a breakpoint on a function that has Begin, Process, and End sections, the debugger breaks at the first line of each section. For example: -function test-cmdlet -{ -begin -{ -write-output "Begin" -} -process -{ -write-output "Process" -} -end -{ -write-output "End" -} +```powershell +function test-cmdlet { + begin { + write-output "Begin" + } + process { + write-output "Process" + } + end { + write-output "End" + } } C:\PS> set-psbreakpoint -command test-cmdlet @@ -406,20 +409,24 @@ Hit Command breakpoint on 'prompt:test-cmdlet' test-cmdlet # [DBG]: C:\PS> +``` +## Debugging Remote Scripts -Debugging Remote Scripts -Starting in Windows PowerShell 5.0, you can run the Windows PowerShell debugger in -a remote session, in either the console, or Windows PowerShell ISE. Enter-PSSession -functionality has been updated to let you reconnect to and enter a disconnected -session that is running on a remote computer, and currently running a script. -If the running script hits a breakpoint, your client session automatically -starts the debugger. The following is an example that shows how this works, -with breakpoints set in a script at lines 6, 11, 22, and 25. Note that in the -example, when the debugger starts, there are two identifying prompts: the -name of the computer on which the session is running, and the DBG prompt that -lets you know you are in debugging mode. +Starting in Windows PowerShell 5.0, you can run the Windows PowerShell +debugger in a remote session, in either the console, or Windows PowerShell +ISE. Enter-PSSession functionality has been updated to let you reconnect to +and enter a disconnected session that is running on a remote computer, and +currently running a script. If the running script hits a breakpoint, your +client session automatically starts the debugger. +The following is an example that shows how this works, with breakpoints set in +a script at lines 6, 11, 22, and 25. Note that in the example, when the +debugger starts, there are two identifying prompts: the name of the computer +on which the session is running, and the DBG prompt that lets you know you are +in debugging mode. + +```powershell Enter-Pssession -Cn localhost [localhost]: PS C:\psscripts> Set-PSBreakpoint .\ttest19.ps1 6,11,22,25 @@ -468,45 +475,54 @@ At C:\psscripts\ttest19.ps1:12 char:1 [localhost]: [DBG]: PS C:\psscripts>> quit [localhost]: PS C:\psscripts> Exit-PSSession PS C:\psscripts> +``` + +## Examples -Examples This test script detects the version of the operating system and displays a system-appropriate message. It includes a function, a function call, and a variable. The following command displays the contents of the test script file: +```powershell c:>\PS-test> get-content test.ps1 function psversion { -"Windows PowerShell " + $psversiontable.psversion -if ($psversiontable.psversion.major -lt 2) { -"Upgrade to Windows PowerShell 2.0!" -} -else { -"Have you run a background job today (start-job)?" -} + "Windows PowerShell " + $psversiontable.psversion + if ($psversiontable.psversion.major -lt 6) { + "Upgrade to Windows PowerShell 6.0!" + } + else { + "Have you run a background job today (start-job)?" + } } $scriptname = $MyInvocation.MyCommand.Path psversion "Done $scriptname." +``` -To start, set a breakpoint at a point of interest in the script, such -as a line, command, variable, or function. +To start, set a breakpoint at a point of interest in the script, such as a +line, command, variable, or function. -Start by creating a line breakpoint on the first line of the Test.ps1 -script in the current directory. +Start by creating a line breakpoint on the first line of the Test.ps1 script +in the current directory. +```powershell PS C:\ps-test> set-psbreakpoint -line 1 -script test.ps1 +``` You can abbreviate this command as: +```powershell PS C:\ps-test> spb 1 -s test.ps1 +``` The command returns a line-breakpoint object (System.Management.Automation.LineBreakpoint). +``` Column : 0 Line : 1 Action : @@ -515,193 +531,232 @@ HitCount : 0 Id : 0 Script : C:\ps-test\test.ps1 ScriptName : C:\ps-test\test.ps1 +``` Now, start the script. +```powershell PS C:\ps-test> .\test.ps1 +``` -When the script reaches the first breakpoint, the breakpoint message -indicates that the debugger is active. It describes the breakpoint and -previews the first line of the script, which is a function declaration. -The command prompt also changes to indicate that the debugger has -control. +When the script reaches the first breakpoint, the breakpoint message indicates +that the debugger is active. It describes the breakpoint and previews the +first line of the script, which is a function declaration. The command prompt +also changes to indicate that the debugger has control. -The preview line includes the script name and the line number of the -previewed command. +The preview line includes the script name and the line number of the previewed +command. +```powershell Entering debug mode. Use h or ? for help. Hit Line breakpoint on 'C:\ps-test\test.ps1:1' test.ps1:1 function psversion { # DBG> +``` +Use the Step command (s) to execute the first statement in the script and to +preview the next statement. The next statement uses the $MyInvocation +automatic variable to set the value of the $ScriptName variable to the path +and file name of the script file. -Use the Step command (s) to execute the first statement in the script -and to preview the next statement. The next statement uses the -$MyInvocation automatic variable to set the value of the $ScriptName -variable to the path and file name of the script file. - +```powershell DBG> s test.ps1:11 $scriptname = $MyInvocation.MyCommand.Path +``` -At this point, the $ScriptName variable is not populated, but you can +At this point, the \$ScriptName variable is not populated, but you can verify the value of the variable by displaying its value. In this case, -the value is $null. +the value is \$null. +```powershell DBG> $scriptname # DBG> - +``` Use another Step command (s) to execute the current statement and to preview the next statement in the script. The next statement calls the PsVersion function. +```powershell DBG> s test.ps1:12 psversion +``` At this point, the $ScriptName variable is populated, but you verify the value of the variable by displaying its value. In this case, the value is set to the script path. +```powershell DBG> $scriptname C:\ps-test\test.ps1 +``` Use another Step command to execute the function call. Press ENTER, or type "s" for Step. +```powershell DBG> s test.ps1:2 "Windows PowerShell " + $psversiontable.psversion +``` -The debug message includes a preview of the statement in the function. -To execute this statement and to preview the next statement in the -function, you can use a Step command. But, in this case, use a Step-Out -command (o). It completes the execution of the function (unless it -reaches a breakpoint) and steps to the next statement in the script. +The debug message includes a preview of the statement in the function. To +execute this statement and to preview the next statement in the function, you +can use a Step command. But, in this case, use a StepOut command (o). It +completes the execution of the function (unless it reaches a breakpoint) and +steps to the next statement in the script. +```powershell DBG> o Windows PowerShell 2.0 Have you run a background job today (start-job)? test.ps1:13 "Done $scriptname" +``` -Because we are on the last statement in the script, the Step, Step-Out, -and Continue commands have the same effect. In this case, use -Step-Out (o). +Because we are on the last statement in the script, the Step, StepOut, and +Continue commands have the same effect. In this case, use StepOut (o). +```powershell Done C:\ps-test\test.ps1 PS C:\ps-test> +``` -The Step-Out command executes the last command. The standard command -prompt indicates that the debugger has exited and returned control to the -command processor. +The StepOut command executes the last command. The standard command prompt +indicates that the debugger has exited and returned control to the command +processor. -Now, run the debugger again. First, to delete the current -breakpoint, use the Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. -(If you think you might reuse the breakpoint, use the -Disable-PsBreakpoint cmdlet instead of Remove-PsBreakpoint.) +Now, run the debugger again. First, to delete the current breakpoint, use the +Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. (If you think you might +reuse the breakpoint, use the Disable-PsBreakpoint cmdlet instead of +Remove-PsBreakpoint.) +```powershell PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint +``` You can abbreviate this command as: +```powershell PS C:\ps-test> gbp | rbp +``` Or, run the command by writing a function, such as the following function: +```powershell function delbr { gbp | rbp } +``` -Now, create a breakpoint on the $scriptname variable. +Now, create a breakpoint on the \$scriptname variable. +```powershell PS C:\ps-test> set-psbreakpoint -variable scriptname -script test.ps1 +``` You can abbreviate the command as: +```powershell PS C:\ps-test> sbp -v scriptname -s test.ps1 +``` Now, start the script. The script reaches the variable breakpoint. The default mode is Write, so execution stops just before the statement that changes the value of the variable. +```powershell PS C:\ps-test> .\test.ps1 Hit Variable breakpoint on 'C:\ps-test\test.ps1:$scriptname' (Write access) test.ps1:11 $scriptname = $MyInvocation.mycommand.path # DBG> +``` +Display the current value of the \$scriptname variable, which is \$null. -Display the current value of the $scriptname variable, which -is $null. - +```powershell DBG> $scriptname # DBG> +``` +Use a Step command (s) to execute the statement that populates the variable. +Then, display the new value of the \$scriptname variable. -Use a Step command (s) to execute the statement that populates -the variable. Then, display the new value of the $scriptname -variable. - +```powershell DBG> $scriptname C:\ps-test\test.ps1 +```powershell Use a Step command (s) to preview the next statement in the script. +```powershell DBG> s test.ps1:12 psversion +``` -The next statement is a call to the PsVersion function. To skip the -function but still execute it, use a Step-Over command (v). If you are -already in the function when you use Step-Over, it is not effective. The -function call is displayed, but it is not executed. +The next statement is a call to the PsVersion function. To skip the function +but still execute it, use a StepOver command (v). If you are already in the +function when you use StepOver, it is not effective. The function call is +displayed, but it is not executed. +```powershell DBG> v Windows PowerShell 2.0 Have you run a background job today (start-job)? test.ps1:13 "Done $scriptname" +``` -The Step-Over command executes the function, and it previews the next +The StepOver command executes the function, and it previews the next statement in the script, which prints the final line. Use a Stop command (t) to exit the debugger. The command prompt reverts to the standard command prompt. +```powershell C:\ps-test> +``` To delete the breakpoints, use the Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. +```powershell PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint +``` Create a new command breakpoint on the PsVersion function. +```powershell PS C:\ps-test> Set-PsBreakpoint -command psversion -script test.ps1 +``` You can abbreviate this command to: +```powershell PS C:\ps-test> sbp -c psversion -s test.ps1 +``` Now, run the script. +```powershell PS C:\ps-test> .\test.ps1 Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion' test.ps1:12 psversion # DBG> +``` - -The script reaches the breakpoint at the function call. At this point, -the function has not yet been called. This gives you the opportunity -to use the Action parameter of Set-PsBreakpoint to set conditions for -the execution of the breakpoint or to perform preparatory or diagnostic -tasks, such as starting a log or invoking a diagnostic or security -script. +The script reaches the breakpoint at the function call. At this point, the +function has not yet been called. This gives you the opportunity to use the +Action parameter of Set-PsBreakpoint to set conditions for the execution of +the breakpoint or to perform preparatory or diagnostic tasks, such as starting +a log or invoking a diagnostic or security script. To set an action, use a Continue command (c) to exit the script, and a -Remove-PsBreakpoint command to delete the current breakpoint. -(Breakpoints are read-only, so you cannot add an action to the current -breakpoint.) +Remove-PsBreakpoint command to delete the current breakpoint. (Breakpoints are +read-only, so you cannot add an action to the current breakpoint.) +```powershell DBG> c Windows PowerShell 2.0 Have you run a background job today (start-job)? @@ -709,104 +764,102 @@ Done C:\ps-test\test.ps1 PS C:\ps-test> get-psbreakpoint | remove-psbreakpoint PS C:\ps-test> +``` -Now, create a new command breakpoint with an action. The following -command sets a command breakpoint with an action that logs the value -of the $scriptname variable when the function is called. Because the -Break keyword is not used in the action, execution does not stop. (The -backtick (`) is the line-continuation character.) +Now, create a new command breakpoint with an action. The following command +sets a command breakpoint with an action that logs the value of the +\$scriptname variable when the function is called. Because the Break keyword is +not used in the action, execution does not stop. (The backtick (`) is the +line-continuation character.) +```powershell PS C:\ps-test> set-psbreakpoint -command psversion -script test.ps1 ` -action { add-content "The value of `$scriptname is $scriptname." ` -path action.log} +``` -You can also add actions that set conditions for the breakpoint. In -the following command, the command breakpoint is executed only if the -execution policy is set to RemoteSigned, the most restrictive policy -that still permits you to run scripts. (The backtick (`) is the -continuation character.) +You can also add actions that set conditions for the breakpoint. In the +following command, the command breakpoint is executed only if the execution +policy is set to RemoteSigned, the most restrictive policy that still permits +you to run scripts. (The backtick (`) is the continuation character.) +```powershell PS C:\ps-test> set-psbreakpoint -script test.ps1 -command psversion ` -action { if ((get-executionpolicy) -eq "RemoteSigned") { break }} +``` The Break keyword in the action directs the debugger to execute the -breakpoint. You can also use the Continue keyword to direct the debugger -to execute without breaking. Because the default keyword is Continue, -you must specify Break to stop execution. +breakpoint. You can also use the Continue keyword to direct the debugger to +execute without breaking. Because the default keyword is Continue, you must +specify Break to stop execution. Now, run the script. +```powershell PS C:\ps-test> .\test.ps1 Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion' test.ps1:12 psversion +```powershell Because the execution policy is set to RemoteSigned, execution stops at the function call. -At this point, you might want to check the call stack. Use the -Get-PsCallStack cmdlet or the Get-PsCallStack debugger command (k). -The following command gets the current call stack. +At this point, you might want to check the call stack. Use the Get-PsCallStack +cmdlet or the Get-PsCallStack debugger command (k). The following command gets +the current call stack. +```powershell DBG> k 2: prompt 1: .\test.ps1: $args=[] 0: prompt: $args=[] +``` This example demonstrates just a few of the many ways to use the Windows PowerShell debugger. -For more information about the debugger cmdlets, type the following -command: +For more information about the debugger cmdlets, type the following command: +```powershell help -full +``` For example, type: +```powershell help set-psbreakpoint -full +``` -Other Debugging Features in Windows PowerShell +## Other Debugging Features in Windows PowerShell In addition to the Windows PowerShell debugger, Windows PowerShell includes several other features that you can use to debug scripts and functions. --- Windows PowerShell Integrated Scripting Environment (ISE) includes -an interactive graphical debugger. For more information, start Windows -PowerShell ISE and press F1. - --- The Set-PSDebug cmdlet offers very basic script debugging features, -including stepping and tracing. - --- Use the Set-StrictMode cmdlet to detect references to -uninitialized variables, to references to non-existent properties -of an object, and to function syntax that is not valid. - --- Add diagnostic statements to a script, such as statements that -display the value of variables, statements that read input from -the command line, or statements that report the current -instruction. Use the cmdlets that contain the Write verb for -this task, such as Write-Host, Write-Debug, Write-Warning, and -Write-Verbose. - -# SEE ALSO - -Disable-PsBreakpoint - -Enable-PsBreakpoint - -Get-PsBreakpoint - -Get-PsCallStack - -Remove-PsBreakpoint - -Set-PsBreakpoint - -Set-PsDebug - -Set-Strictmode - -Write-Debug - -Write-Verbose - +- Windows PowerShell Integrated Scripting Environment (ISE) includes an + interactive graphical debugger. For more information, start PowerShell ISE + and press F1. + +- The Set-PSDebug cmdlet offers very basic script debugging features, + including stepping and tracing. + +- Use the Set-StrictMode cmdlet to detect references to uninitialized + variables, to references to non-existent properties of an object, and to + function syntax that is not valid. + +- Add diagnostic statements to a script, such as statements that display the + value of variables, statements that read input from the command line, or + statements that report the current instruction. Use the cmdlets that contain + the Write verb for this task, such as Write-Host, Write-Debug, Write-Warning, + and Write-Verbose. + +## SEE ALSO + +- [Disable-PsBreakpoint](../../Microsoft.PowerShell.Utility/Disable-PsBreakpoint.md) +- [Enable-PsBreakpoint](../../Microsoft.PowerShell.Utility/Enable-PsBreakpoint.md) +- [Get-PsBreakpoint](../../Microsoft.PowerShell.Utility/Get-PsBreakpoint.md) +- [Get-PsCallStack](../../Microsoft.PowerShell.Utility/Get-PsCallStack.md) +- [Remove-PsBreakpoint](../../Microsoft.PowerShell.Utility/Remove-PsBreakpoint.md) +- [Set-PsBreakpoint](../../Microsoft.PowerShell.Utility/Set-PsBreakpoint.md) +- [Write-Debug](../../Microsoft.PowerShell.Utility/Write-Debug.md) +- [Write-Verbose](../../Microsoft.PowerShell.Utility/Write-Verbose.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md index 3e4a5424b207..fbcfc30ca802 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,77 +7,72 @@ title: about_Functions_Advanced_Methods --- # About Functions Advanced Methods -## about_Functions_Advanced_Methods +## SHORT DESCRIPTION -# SHORT DESCRIPTION - -Describes how functions that specify the `CmdletBinding` attribute can use -the methods and properties that are available to compiled cmdlets. +Describes how functions that specify the `CmdletBinding` attribute can use the +methods and properties that are available to compiled cmdlets. # LONG DESCRIPTION Functions that specify the `CmdletBinding` attribute can access a number of -methods and properties through the `$pscmdlet` variable. These methods -include the following methods: +methods and properties through the `$pscmdlet` variable. These methods include +the following methods: - Input-processing methods that compiled cmdlets use to do their work. - - The `ShouldProcess` and `ShouldContinue` methods that are used to get -user feedback before an action is performed. - + user feedback before an action is performed. - The `ThrowTerminatingError` method for generating error records. - - Several Write methods that return different types of output. All the methods and properties of the `PSCmdlet` class are available to -advanced functions. For more information about these methods and -properties, see `System.Management.Automation.PSCmdlet` in the MSDN -(Microsoft Developer Network) library at -http://go.microsoft.com/fwlink/?LinkId=142139. - -# Input Processing Methods - -The methods described in this section are referred to as the input -processing methods. For functions, these three methods are represented -by the `Begin`, `Process`, and `End` blocks of the function. Each function -must include one or more of these blocks. The Windows PowerShell runtime -uses the code within these blocks when it is running a function. (These -blocks are also available to functions that do not use the `CmdletBinding` -attribute.) - -## Begin +advanced functions. For more information about these methods and properties, +see `System.Management.Automation.PSCmdlet` in the MSDN (Microsoft Developer +Network) library at http://go.microsoft.com/fwlink/?LinkId=142139. + +### Input Processing Methods + +The methods described in this section are referred to as the input processing +methods. For functions, these three methods are represented by the `Begin`, +`Process`, and `End` blocks of the function. Each function must include one or +more of these blocks. The Windows PowerShell runtime uses the code within +these blocks when it is running a function. (These blocks are also available +to functions that do not use the `CmdletBinding` attribute.) + +#### Begin + This block is used to provide optional one-time preprocessing for the -function. The Windows PowerShell runtime uses the code in this block one -time for each instance of the function in the pipeline. - -## Process -This block is used to provide record-by-record processing for the -function. This block might be used any number of times, or not at all, -depending on the input to the function. For example, if the function is -the first command in the pipeline, the `Process` block will be used one -time. If the function is not the first command in the pipeline, the -`Process` block is used one time for every input that the function -receives from the pipeline. If there is no pipeline input, the `Process` -block is not used. - -This block must be defined if a function parameter is set to accept -pipeline input. If this block is not defined and the parameter accepts -input from the pipeline, the function will miss the values that are -passed to the function through the pipeline. +function. The Windows PowerShell runtime uses the code in this block one time +for each instance of the function in the pipeline. + +#### Process + +This block is used to provide record-by-record processing for the function. +This block might be used any number of times, or not at all, depending on the +input to the function. For example, if the function is the first command in +the pipeline, the `Process` block will be used one time. If the function is +not the first command in the pipeline, the `Process` block is used one time +for every input that the function receives from the pipeline. If there is no +pipeline input, the `Process` block is not used. + +This block must be defined if a function parameter is set to accept pipeline +input. If this block is not defined and the parameter accepts input from the +pipeline, the function will miss the values that are passed to the function +through the pipeline. Also, when the function supports confirmation requests (when the `SupportsShouldProcess` parameter of the Parameter attribute is set to -`$True`), the call to the `ShouldProcess` method must be made from within -the Process block. +`$True`), the call to the `ShouldProcess` method must be made from within the +Process block. + +#### End -## End -This block is used to provide optional one-time post-processing for -the function. +This block is used to provide optional one-time post-processing for the +function. -The following example shows the outline of a function that contains a -`Begin` block for one-time preprocessing, a `Process` block for multiple -record processing, and an `End` block for one-time post-processing. +The following example shows the outline of a function that contains a `Begin` +block for one-time preprocessing, a `Process` block for multiple record +processing, and an `End` block for one-time post-processing. ```powershell Function Test-ScriptCmdlet @@ -90,119 +85,125 @@ Function Test-ScriptCmdlet } ``` -# Confirmation Methods +### Confirmation Methods + +#### ShouldProcess -## ShouldProcess This method is called to request confirmation from the user before the -function performs an action that would change the system. The function -can continue based on the Boolean value returned by the method. This -method can be called only from within the `Process{}` block of the -function. And, the `CmdletBinding` attribute must declare that the -function supports `ShouldProcess` (as shown in the previous example). +function performs an action that would change the system. The function can +continue based on the Boolean value returned by the method. This method can be +called only from within the `Process{}` block of the function. And, the +`CmdletBinding` attribute must declare that the function supports +`ShouldProcess` (as shown in the previous example). For more information about this method, see -`System.Management.Automation.Cmdlet.ShouldProcess` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142142. +[`System.Management.Automation.Cmdlet.ShouldProcess`](http://go.microsoft.com/fwlink/?LinkId=142142) +in the MSDN library. For more information about how to request confirmation, see -"Requesting Confirmation" in the MSDN library at -http://go.microsoft.com/fwlink/?LinkID=136658. +[Requesting Confirmation](http://go.microsoft.com/fwlink/?LinkID=136658) +in the MSDN library. + +#### ShouldContinue -## ShouldContinue -This method is called to request a second confirmation message. It -should be called when the `ShouldProcess` method returns `$true`. For more -information about this method, see -`System.Management.Automation.Cmdlet.ShouldContinue` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142143. +This method is called to request a second confirmation message. It should be +called when the `ShouldProcess` method returns `$true`. For more information +about this method, see `System.Management.Automation.Cmdlet.ShouldContinue` in +the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142143. -# Error Methods +### Error Methods Functions can call two different methods when errors occur. When a -nonterminating error occurs, the function should call the `WriteError` -method, which is described in the "Write Methods" section. When a -terminating error occurs and the function cannot continue, it should call -the `ThrowTerminatingError` method. You can also use the `Throw` statement for +nonterminating error occurs, the function should call the `WriteError` method, +which is described in the "Write Methods" section. When a terminating error +occurs and the function cannot continue, it should call the +`ThrowTerminatingError` method. You can also use the `Throw` statement for terminating errors and the `Write-Error` cmdlet for nonterminating errors. -For more information, see `System.Management.Automation.Cmdlet.ThrowTerminatingError` -in the MSDN libray at -http://go.microsoft.com/fwlink/?LinkId=142144. +For more information, see +[`System.Management.Automation.Cmdlet.ThrowTerminatingError`](http://go.microsoft.com/fwlink/?LinkId=142144) +in the MSDN libray. -# Write Methods +### Write Methods -A function can call the following methods to return different types of -output. Notice that not all the output goes to the next command in the -pipeline. You can also use the various Write cmdlets, such as -Write-Error. +A function can call the following methods to return different types of output. +Notice that not all the output goes to the next command in the pipeline. You +can also use the various Write cmdlets, such as Write-Error. + +#### WriteCommandDetail -## WriteCommandDetail For information about the `WriteCommandDetails` method, see -`System.Management.Automation.Cmdlet.WriteCommandDetail` in the MSDN -library at http://go.microsoft.com/fwlink/?LinkId=142155. - -## WriteDebug -To provide information that can be used to troubleshoot a function, -make the function call the `WriteDebug` method. This displays debug -messages to the user. For more information, see -`System.Management.Automation.Cmdlet.WriteDebug` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142156. - -## WriteError -Functions should call this method when nonterminating errors occur and -the function is designed to continue processing records. For more -information, see `System.Management.Automation.Cmdlet.WriteError` in the -MSDN library at http://go.microsoft.com/fwlink/?LinkId=142157. +[`System.Management.Automation.Cmdlet.WriteCommandDetail`](http://go.microsoft.com/fwlink/?LinkId=142155) +in the MSDN library. + +#### WriteDebug + +To provide information that can be used to troubleshoot a function, make the +function call the `WriteDebug` method. This displays debug messages to the +user. For more information, see +[`System.Management.Automation.Cmdlet.WriteDebug`](http://go.microsoft.com/fwlink/?LinkId=142156) +in the MSDN library. + +#### WriteError + +Functions should call this method when nonterminating errors occur and the +function is designed to continue processing records. For more information, see +[`System.Management.Automation.Cmdlet.WriteError`](http://go.microsoft.com/fwlink/?LinkId=142157) +in the MSDN library. Note: If a terminating error occurs, the function should call the `ThrowTerminatingError` method. -## WriteObject -This method allows the function to send an object to the next command in -the pipeline. In most cases, this is the method to use when the function -returns data. For more information, see -`System.Management.Automation.PSCmdlet.WriteObject` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142158. - -## WriteProgress -For functions whose actions take a long time to complete, this method -allows the function to call the `WriteProgress` method so that progress -information is displayed. For example, you can display the percent -completed. For more information, see -`System.Management.Automation.PSCmdlet.WriteProgress` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142160. - -## WriteVerbose -To provide detailed information about what the function is doing, make -the function call the `WriteVerbose` method to display verbose messages to -the user. By default, verbose messages are not displayed. For more -information, see `System.Management.Automation.PSCmdlet.WriteVerbose` -in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142162. - -## WriteWarning -To provide information about conditions that may cause unexpected -results, make the function call the WriteWarning method to display -warning messages to the user. By default, warning messages are displayed. -For more information, see -`System.Management.Automation.PSCmdlet.WriteWarning` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142164. +#### WriteObject + +This method allows the function to send an object to the next command in the +pipeline. In most cases, this is the method to use when the function returns +data. For more information, see +[`System.Management.Automation.PSCmdlet.WriteObject`](http://go.microsoft.com/fwlink/?LinkId=142158) +in the MSDN library. + +#### WriteProgress + +For functions whose actions take a long time to complete, this method allows +the function to call the `WriteProgress` method so that progress information +is displayed. For example, you can display the percent completed. For more +information, see [`System.Management.Automation.PSCmdlet.WriteProgress`](http://go.microsoft.com/fwlink/?LinkId=142160) +in the MSDN library. + +#### WriteVerbose + +To provide detailed information about what the function is doing, make the +function call the `WriteVerbose` method to display verbose messages to the +user. By default, verbose messages are not displayed. For more information, +see +[`System.Management.Automation.PSCmdlet.WriteVerbose`](http://go.microsoft.com/fwlink/?LinkId=142162) +in the MSDN library. + +#### WriteWarning + +To provide information about conditions that may cause unexpected results, +make the function call the WriteWarning method to display warning messages to +the user. By default, warning messages are displayed. For more information, +see [`System.Management.Automation.PSCmdlet.WriteWarning`](http://go.microsoft.com/fwlink/?LinkId=142164) +in the MSDN library. Note: You can also display warning messages by configuring the `WarningPreference` variable or by using the `Verbose` and `Debug` command-line options. -# Other Methods and Properties +### Other Methods and Properties For information about the other methods and properties that can be accessed through the `$PSCmdlet` variable, see -`System.Management.Automation.PSCmdlet` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142139. +[`System.Management.Automation.PSCmdlet`](http://go.microsoft.com/fwlink/?LinkId=142139) +in the MSDN library. For example, the `ParameterSetName` property allows you to see the parameter set that is being used. Parameter sets allow you to create a function that -performs different tasks based on the parameters that are specified when -the function is run. +performs different tasks based on the parameters that are specified when the +function is run. -# SEE ALSO +## SEE ALSO [about_Functions](about_Functions.md) @@ -213,4 +214,3 @@ the function is run. [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) [about_Functions_OutputTypeAttribute](about_Functions_OutputTypeAttribute.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md index 7765c99a4084..f5f40dd0d876 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,13 @@ title: about_Functions_OutputTypeAttribute --- # About Functions OutputTypeAttribute -## about_Functions_OutputTypeAttribute - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes an attribute that reports the type of object that the function returns. -# LONG DESCRIPTION +## LONG DESCRIPTION The OutputType attribute lists the .NET types of objects that the functions returns. You can use its optional ParameterSetName parameter to list different @@ -32,24 +30,30 @@ The OutputType attribute value is only a documentation note. It is not derived from the function code or compared to the actual function output. As such, the value might be inaccurate. -# SYNTAX +## SYNTAX The OutputType attribute of functions has the following syntax: +``` [OutputType([], ParameterSetName="")] [OutputType("", ParameterSetName="")] +``` The ParameterSetName parameter is optional. You can list multiple types in the OutputType attribute. +``` [OutputType([],[],[])] +``` You can use the ParameterSetName parameter to indicate that different parameter sets return different types. +``` [OutputType([], ParameterSetName="","")] [OutputType([], ParameterSetName="")] +``` Place the OutputType attribute statements in the attributes list that precedes the Param statement. @@ -57,90 +61,99 @@ the Param statement. The following example shows the placement of the OutputType attribute in a simple function. +```powershell function SimpleFunction2 { -[OutputType([])] -Param ($Parameter1) + [OutputType([])] + Param ($Parameter1) - + } +``` The following example shows the placement of the OutputType attribute in advanced functions. +```powershell function AdvancedFunction1 { -[OutputType([])] -Param ( -[parameter(Mandatory=$true)] -[String[]] -$Parameter1 -# ) + [OutputType([])] + Param ( + [parameter(Mandatory=$true)] + [String[]] + $Parameter1 + ) - + } function AdvancedFunction2 { -[CmdletBinding(SupportsShouldProcess=)] -[OutputType([])] -Param ( -[parameter(Mandatory=$true)] -[String[]] -$Parameter1 -# ) + [CmdletBinding(SupportsShouldProcess=)] + [OutputType([])] + Param ( + [parameter(Mandatory=$true)] + [String[]] + $Parameter1 + ) - + } +``` # EXAMPLES - The following function uses the OutputType attribute to indicate that it returns a string value. +```powershell function Send-Greeting { -[OutputType([String])] -Param ($Name) + [OutputType([String])] + Param ($Name) -Hello, $Name + "Hello, $Name" } +``` To see the resulting output type property, use the Get-Command cmdlet. +``` PS C:> (Get-Command Send-Greeting).OutputType Name Type ---- ---- System.String System.String +``` The following advanced function uses the OutputType attribute to indicate that the function returns different types depending on the parameter set used in the function command. +```powershell function Get-User { -[CmdletBinding(DefaultParameterSetName="ID")] + [CmdletBinding(DefaultParameterSetName="ID")] -[OutputType("System.Int32", ParameterSetName="ID")] -[OutputType([String], ParameterSetName="Name")] + [OutputType("System.Int32", ParameterSetName="ID")] + [OutputType([String], ParameterSetName="Name")] -Param ( -[parameter(Mandatory=$true, ParameterSetName="ID")] -[Int[]] -$UserID, + Param ( + [parameter(Mandatory=$true, ParameterSetName="ID")] + [Int[]] + $UserID, -[parameter(Mandatory=$true, ParameterSetName="Name")] -[String[]] -$UserName -# ) + [parameter(Mandatory=$true, ParameterSetName="Name")] + [String[]] + $UserName + ) - + } +``` The following example demonstrates that the output type property value displays the value of the OutputType attribute, even when it is inaccurate. @@ -149,34 +162,38 @@ The Get-Time function returns a string that contains the short form of the time in any DateTime object. However, the OutputType attribute reports that it returns a System.DateTime object. +```powershell function Get-Time { -[OutputType([DateTime])] -Param -# ( + [OutputType([DateTime])] + Param ( + [parameter(Mandatory=$true)] + [Datetime]$DateTime + ) -[parameter(Mandatory=$true)] -[Datetime]$DateTime -# ) - -$DateTime.ToShortTimeString() + $DateTime.ToShortTimeString() } +``` The Get-Type method confirms that the function returns a string. +``` PS C:> (Get-Time -DateTime (Get-Date)).Gettype().FullName System.String +``` However, the OutputType property, which gets its value from the OutputType attribute, reports that the function returns a DateTime object. +``` PS C:> (Get-Command Get-Time).OutputType Name Type ---- ---- System.DateTime System.DateTime +``` -# NOTES +## NOTES The value of the OutputType property of a FunctionInfo object is an array of System.Management.Automation.PSTypeName objects, each of which have Name and @@ -185,7 +202,9 @@ Type properties. To get only the name of each output type, use a command with the following format. +```powershell (Get-Command Get-Time).OutputType | ForEach {$_.Name} +``` The value of the OutputType property can be null. Use a null value when the output is a not a .NET type, such as a WMI object or a formatted view @@ -202,4 +221,3 @@ of an object. [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md) [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_PSSessions.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_PSSessions.md index 196d7fddf1b9..a96bb8e474f6 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_PSSessions.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_PSSessions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,63 +10,120 @@ title: about_PSSessions ## Short Description -Describes Windows PowerShell sessions (PSSessions) and explains how to establish a persistent connection to a remote computer. +Describes Windows PowerShell sessions (PSSessions) and explains how to +establish a persistent connection to a remote computer. ## Long Description -To run Windows PowerShell commands on a remote computer, you can use the **ComputerName** parameter of a cmdlet, or you can create a Windows PowerShell session (PSSession) and run commands in the PSSession. +To run Windows PowerShell commands on a remote computer, you can use the +**ComputerName** parameter of a cmdlet, or you can create a Windows PowerShell +session (PSSession) and run commands in the PSSession. -When you create a PSSession, Windows PowerShell establishes a persistent connection to the remote computer. Use a PSSession to run a series of related commands on a remote computer. Commands that run in the same PSSession can share data, such as the values of variables, aliases, and functions. +When you create a PSSession, Windows PowerShell establishes a persistent +connection to the remote computer. Use a PSSession to run a series of related +commands on a remote computer. Commands that run in the same PSSession can +share data, such as the values of variables, aliases, and functions. -You can also create a PSSession on the local computer and run commands in it. A local PSSession uses the Windows PowerShell remoting infrastructure to create and maintain the PSSession. +You can also create a PSSession on the local computer and run commands in it. +A local PSSession uses the Windows PowerShell remoting infrastructure to +create and maintain the PSSession. -Beginning in Windows PowerShell 3.0, PSSessions are independent of the sessions in which they are created. Active PSSessions are maintained on the remote computer (or the computer at the remote end or "server-side" of the connection). As a result, you can disconnect from the PSSession and reconnect to it at a later time from the same computer or from a different computer. +Beginning in Windows PowerShell 3.0, PSSessions are independent of the +sessions in which they are created. Active PSSessions are maintained on the +remote computer (or the computer at the remote end or "server-side" of the +connection). As a result, you can disconnect from the PSSession and reconnect +to it at a later time from the same computer or from a different computer. -This topic explains how to create, use, get, and delete PSSessions. For more advanced information, see [about_PSSession_Details](about_PSSession_Details.md). +This topic explains how to create, use, get, and delete PSSessions. For more +advanced information, see +[about_PSSession_Details](about_PSSession_Details.md). -Note: PSSessions use the Windows PowerShell remoting infrastructure. To use PSSessions, the local and remote computers must be configured for remoting. For more information, see [about_Remote_Requirements](about_Remote_Requirements.md). +Note: PSSessions use the Windows PowerShell remoting infrastructure. To use +PSSessions, the local and remote computers must be configured for remoting. +For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). -In Windows Vista and later versions of Windows, to create a PSSession on a local computer, you must start Windows PowerShell with the "Run as administrator" option. +In Windows Vista and later versions of Windows, to create a PSSession on a +local computer, you must start Windows PowerShell with the "Run as +administrator" option. ## What Is a Session? A session is an environment in which Windows PowerShell runs. -Each time you start Windows PowerShell, a session is created for you, and you can run commands in the session. You can also add items to your session, such as modules and snap-ins, and you can create items, such as variables, functions, and aliases. These items exist only in the session and are deleted when the session ends. - -You can also create user-managed sessions, known as " Windows PowerShell sessions" or "PSSessions," on the local computer or on a remote computer. Like the default session, you can run commands in a PSSession and add and create items. - -However, unlike the session that starts automatically, you can control the PSSessions that you create. You can get, create, configure, and remove them, disconnect and reconnect to them, and run multiple commands in the same PSSession. The PSSession remains available until you delete it or it times out. - -Typically, you create a PSSession to run a series of related commands on a remote computer. When you create a PSSession on a remote computer, Windows PowerShell establishes a persistent connection to the remote computer to support the session. - -If you use the **ComputerName** parameter of the `Invoke-Command` or `Enter-PSSession` cmdlet to run a remote command or to start an interactive session, Windows PowerShell creates a temporary session on the remote computer and closes the session as soon as the command is complete or as soon as the interactive session ends. You cannot control these temporary sessions, and you cannot use them for more than a single command or a single interactive session. - -In Windows PowerShell, the "current session" is the session that you are working in. The "current session" can refer to any session, including a temporary session or a PSSession. +Each time you start Windows PowerShell, a session is created for you, and you +can run commands in the session. You can also add items to your session, such +as modules and snap-ins, and you can create items, such as variables, +functions, and aliases. These items exist only in the session and are deleted +when the session ends. + +You can also create user-managed sessions, known as " Windows PowerShell +sessions" or "PSSessions," on the local computer or on a remote computer. Like +the default session, you can run commands in a PSSession and add and create +items. However, unlike the session that starts automatically, you can control +the PSSessions that you create. You can get, create, configure, and remove +them, disconnect and reconnect to them, and run multiple commands in the same +PSSession. The PSSession remains available until you delete it or it times +out. + +Typically, you create a PSSession to run a series of related commands on a +remote computer. When you create a PSSession on a remote computer, Windows +PowerShell establishes a persistent connection to the remote computer to +support the session. + +If you use the **ComputerName** parameter of the `Invoke-Command` or +`Enter-PSSession` cmdlet to run a remote command or to start an interactive +session, Windows PowerShell creates a temporary session on the remote computer +and closes the session as soon as the command is complete or as soon as the +interactive session ends. You cannot control these temporary sessions, and you +cannot use them for more than a single command or a single interactive +session. + +In Windows PowerShell, the "current session" is the session that you are +working in. The "current session" can refer to any session, including a +temporary session or a PSSession. ## Why Use a PSSession? -Use a PSSession when you need a persistent connection to a remote computer. With a PSSession, you can run a series of commands that share data, such as the value of variables, the contents of a function, or the definition of an alias. +Use a PSSession when you need a persistent connection to a remote computer. +With a PSSession, you can run a series of commands that share data, such as +the value of variables, the contents of a function, or the definition of an +alias. -You can run remote commands without creating a PSSession. Use the **ComputerName** parameter of remote-enabled cmdlets to run a single command or a series of unrelated commands on one or many computers. +You can run remote commands without creating a PSSession. Use the +**ComputerName** parameter of remote-enabled cmdlets to run a single command +or a series of unrelated commands on one or many computers. -When you use the **ComputerName** parameter of `Invoke-Command` or `Enter-PSSession`, Windows PowerShell establishes a temporary connection to the remote computer and then closes the connection as soon as the command is complete. Any data elements that you create are lost when the connection is closed. +When you use the **ComputerName** parameter of `Invoke-Command` or +`Enter-PSSession`, Windows PowerShell establishes a temporary connection to +the remote computer and then closes the connection as soon as the command is +complete. Any data elements that you create are lost when the connection is +closed. -Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` and `Get-WmiObject`, use different remoting technologies to gather data. None create a persistent connection like a PSSession. +Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` +and `Get-WmiObject`, use different remoting technologies to gather data. None +create a persistent connection like a PSSession. ## How to Create a PSSession -To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession on a remote computer, use the **ComputerName** parameter of the `New-PSSession` cmdlet. +To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession +on a remote computer, use the **ComputerName** parameter of the +`New-PSSession` cmdlet. -For example, the following command creates a new PSSession on the Server01 computer. +For example, the following command creates a new PSSession on the Server01 +computer. ```powershell New-PSSession -ComputerName Server01 ``` -When you submit the command, `New-PSSession` creates the PSSession and returns an object that represents the PSSession. You can save the object in a variable when you create the PSSession, or you can use a `Get-PSSession` command to get the PSSession at a later time. +When you submit the command, `New-PSSession` creates the PSSession and returns +an object that represents the PSSession. You can save the object in a variable +when you create the PSSession, or you can use a `Get-PSSession` command to get +the PSSession at a later time. -For example, the following command creates a new PSSession on the Server01 computer and saves the resulting object in the $ps variable. +For example, the following command creates a new PSSession on the Server01 +computer and saves the resulting object in the $ps variable. ```powershell $ps = New-PSSession -ComputerName Server01 @@ -74,9 +131,12 @@ $ps = New-PSSession -ComputerName Server01 ## How to Create PSSessions on Multiple Computers -To create PSSessions on multiple computers, use the **ComputerName** parameter of the `New-PSSession` cmdlet. Type the names of the remote computers in a comma-separated list. +To create PSSessions on multiple computers, use the **ComputerName** parameter +of the `New-PSSession` cmdlet. Type the names of the remote computers in a +comma-separated list. -For example, to create PSSessions on the Server01, Server02, and Server03 computers, type: +For example, to create PSSessions on the Server01, Server02, and Server03 +computers, type: ```powershell New-PSSession -ComputerName Server01, Server02, Server03 @@ -86,7 +146,9 @@ New-PSSession -ComputerName Server01, Server02, Server03 ## How to Get PSSessions -To get the PSSessions that were created in your current session, use the `Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` returns the same type of object that `New-PSSession` returns. +To get the PSSessions that were created in your current session, use the +`Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` +returns the same type of object that `New-PSSession` returns. The following command gets all the PSSessions that were created in the current session. @@ -94,9 +156,10 @@ The following command gets all the PSSessions that were created in the current s Get-PSSession ``` -The default display of the PSSessions shows their ID and a default display name. You can assign an alternate display name when you create the session. +The default display of the PSSessions shows their ID and a default display +name. You can assign an alternate display name when you create the session. -``` +```output Id Name ComputerName State ConfigurationName --- ---- ------------ ----- --------------------- 1 Session1 Server01 Opened Microsoft.PowerShell @@ -104,31 +167,45 @@ Id Name ComputerName State ConfigurationName 3 Session3 Server03 Opened Microsoft.PowerShell ``` -You can also save the PSSessions in a variable. The following command gets the PSSessions and saves them in the $ps123 variable. +You can also save the PSSessions in a variable. The following command gets the +PSSessions and saves them in the \$ps123 variable. ```powershell $ps123 = Get-PSSession ``` -When using the PSSession cmdlets, you can refer to a PSSession by its ID, by its name, or by its instance ID (a GUID). The following command gets a PSSession by its ID and saves it in the $ps01 variable. +When using the PSSession cmdlets, you can refer to a PSSession by its ID, by +its name, or by its instance ID (a GUID). The following command gets a +PSSession by its ID and saves it in the \$ps01 variable. ```powershell $ps01 = Get-PSSession -Id 1 ``` -Beginning in Windows PowerShell 3.0, PSSessions are maintained on the remote computer. To get PSSessions that you created on particular remote computers, use the **ComputerName** parameter of the `Get-PSSession` cmdlet. The following command gets the PSSessions that you created on the Server01 remote computer. This includes PSSessions created in the current session and in other sessions on the local computer or other computers. +Beginning in Windows PowerShell 3.0, PSSessions are maintained on the remote +computer. To get PSSessions that you created on particular remote computers, +use the **ComputerName** parameter of the `Get-PSSession` cmdlet. The +following command gets the PSSessions that you created on the Server01 remote +computer. This includes PSSessions created in the current session and in other +sessions on the local computer or other computers. ```powershell Get-PSSession -ComputerName Server01 ``` -In Windows PowerShell 2.0, `Get-PSSession` gets only the PSSessions that were created in the current session. It does not get PSSessions that were created in other sessions or on other computers, even if the sessions are connected to and are running commands on the local computer. +In Windows PowerShell 2.0, `Get-PSSession` gets only the PSSessions that were +created in the current session. It does not get PSSessions that were created +in other sessions or on other computers, even if the sessions are connected to +and are running commands on the local computer. ## How to Run Commands in a PSSession -To run a command in one or more PSSessions, use the `Invoke-Command` cmdlet. Use the Session parameter to specify the PSSessions and the **ScriptBlock** parameter to specify the command. +To run a command in one or more PSSessions, use the `Invoke-Command` cmdlet. +Use the Session parameter to specify the PSSessions and the **ScriptBlock** +parameter to specify the command. -For example, to run a `Get-ChildItem` ("dir") command in each of the three PSSessions saved in the $ps123 variable, type: +For example, to run a `Get-ChildItem` ("dir") command in each of the three +PSSessions saved in the $ps123 variable, type: ```powershell Invoke-Command -Session $ps123 -ScriptBlock { Get-ChildItem } @@ -136,7 +213,8 @@ Invoke-Command -Session $ps123 -ScriptBlock { Get-ChildItem } ## How to Delete PSSessions -When you are finished with the PSSession, use the `Remove-PSSession` cmdlet to delete the PSSession and to release the resources that it was using. +When you are finished with the PSSession, use the `Remove-PSSession` cmdlet to +delete the PSSession and to release the resources that it was using. ```powershell Remove-PSSession -Session $ps @@ -148,35 +226,38 @@ or Remove-PSSession -Id 1 ``` -To remove a PSSession from a remote computer, use the **ComputerName** parameter of the `Remove-PSSession` cmdlet. +To remove a PSSession from a remote computer, use the **ComputerName** +parameter of the `Remove-PSSession` cmdlet. ```powershell Remove-PSSession -ComputerName Server01 -Id 1 ``` -If you do not delete the PSSession, the PSSession remains available for use until it times out. +If you do not delete the PSSession, the PSSession remains available for use +until it times out. -You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` cmdlet to set an expiration time for an idle PSSession. For more information, see [New-PSSessionOption](../New-PSSessionOption.md). +You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` +cmdlet to set an expiration time for an idle PSSession. For more information, +see [New-PSSessionOption](../New-PSSessionOption.md). ## The PSSession Cmdlets -| Cmdlet | Description | -| -------------------- | --------------------------------------------------------------- | -| Connect-PSSession | Connects a PSSession to the current session | -| Disconnect-PSSession | Disconnects a PSSession from the current session | -| Enter-PSSession | Starts an interactive session | -| Exit-PSSession | Ends an interactive session | -| Get-PSSession | Gets the PSSessions in the current session | -| New-PSSession | Creates a new PSSession on a local or remote computer | -| Receive-PSSession | Gets the results of commands that ran in a disconnected session | -| Remove-PSSession | Deletes the PSSessions in the current session | - For a list of PSSession cmdlets, type: ```powershell Get-Help *-PSSession ``` +- Connect-PSSession: Connects a PSSession to the current session +- Disconnect-PSSession: Disconnects a PSSession from the current session +- Enter-PSSession: Starts an interactive session +- Exit-PSSession: Ends an interactive session +- Get-PSSession: Gets the PSSessions in the current session +- New-PSSession: Creates a new PSSession on a local or remote computer +- Receive-PSSession: Gets the results of commands that ran in a disconnected + session +- Remove-PSSession: Deletes the PSSessions in the current session + ## For More Information For more information about PSSessions, see [about_PSSession_Details](about_PSSession_Details.md). diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md index 2fe708b363f5..a30c4841c8e3 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,176 +7,212 @@ title: about_PSSnapins --- # About PSSnapins -## about_PSSnapins - ## SHORT DESCRIPTION -Describes Windows PowerShell® snap-ins and shows how to use and manage them. +Describes Windows PowerShell® snap-ins and shows how to use and manage them. ## LONG DESCRIPTION -A Windows PowerShell snap-in is a Microsoft .NET Framework assembly that contains Windows PowerShell providers and\/or cmdlets. Windows PowerShell includes a set of basic snap-ins, but you can extend the power and value of Windows PowerShell by adding snap-ins that contain providers and cmdlets that you create or get from others. -When you add a snap-in, the cmdlets and providers that it contains are immediately available for use in the current session, but the change affects only the current session. +A Windows PowerShell snap-in is a Microsoft .NET Framework assembly that +contains Windows PowerShell providers and\/or cmdlets. Windows PowerShell +includes a set of basic snap-ins, but you can extend the power and value of +Windows PowerShell by adding snap-ins that contain providers and cmdlets that +you create or get from others. -To add the snap-in to all future sessions, save it in your Windows PowerShell profile. You can also use the Export-Console cmdlet to save the snap-in names to a console file and then use it in future sessions. You can even save multiple console files, each with a different set of snap-ins. +When you add a snap-in, the cmdlets and providers that it contains are +immediately available for use in the current session, but the change affects +only the current session. -NOTE: Windows PowerShell snap-ins (PSSnapins) are available for use in Windows PowerShell 3.0 and Windows PowerShell 2.0. They might be altered or unavailable in subsequent versions. To package Windows PowerShell cmdlets and providers, use modules. For information about creating modules and converting snap-ins to modules, see "Writing a Windows PowerShell Module" in MSDN at http:\/\/go.microsoft.com\/fwlink\/?LinkID\=141556. +To add the snap-in to all future sessions, save it in your Windows PowerShell +profile. You can also use the Export-Console cmdlet to save the snap-in names +to a console file and then use it in future sessions. You can even save +multiple console files, each with a different set of snap-ins. +NOTE: Windows PowerShell snap-ins (PSSnapins) are available for use in Windows +PowerShell 3.0 and Windows PowerShell 2.0. They might be altered or +unavailable in subsequent versions. To package Windows PowerShell cmdlets and +providers, use modules. For information about creating modules and converting +snap-ins to modules, see [Writing a Windows PowerShell Module](http://go.microsoft.com/fwlink/?LinkID=141556) +in the MSDN library. ### FINDING SNAP-INS -To get a list of the Windows PowerShell snap-ins on your computer, type: +To get a list of the Windows PowerShell snap-ins on your computer, type: -``` +```powershell get-pssnapin ``` - To get the snap-in for each Windows PowerShell provider, type: - -``` +```powershell get-psprovider | format-list name, pssnapin ``` - To get a list of the cmdlets in a Windows PowerShell snap-in, type: - -``` +```powershell get-command -module ``` - - ### INSTALLING A SNAP-IN -The built-in snap-ins are registered in the system and added to the default session when you start Windows PowerShell. However, you have to register snap-ins that you create or obtain from others and then add the snap-ins to your session. +The built-in snap-ins are registered in the system and added to the default +session when you start Windows PowerShell. However, you have to register +snap-ins that you create or obtain from others and then add the snap-ins to +your session. ### REGISTERING A SNAP-IN -A Windows PowerShell snap-in is a program written in a .NET Framework language that is compiled into a .dll file. To use the providers and cmdlets in a snap-in, you must first register the snap-in (add it to the registry). -Most snap-ins include an installation program (an .exe or .msi file) that registers the .dll file for you. However, if you receive a snap-in as a .dll file, you can register it on your system. For more information, see [How to Register Cmdlets, Providers, and Host Applications](https://go.microsoft.com/fwlink/?LinkID=143619) in the MSDN library. +A Windows PowerShell snap-in is a program written in a .NET Framework language +that is compiled into a .dll file. To use the providers and cmdlets in a +snap-in, you must first register the snap-in (add it to the registry). -To get all the registered snap-ins on your system or to verify that a snap-in is registered, type: +Most snap-ins include an installation program (an .exe or .msi file) that +registers the .dll file for you. However, if you receive a snap-in as a .dll +file, you can register it on your system. For more information, see +[How to Register Cmdlets, Providers, and Host Applications](https://go.microsoft.com/fwlink/?LinkID=143619) +in the MSDN library. +To get all the registered snap-ins on your system or to verify that a snap-in +is registered, type: -``` +```powershell get-pssnapin -registered ``` - - ### ADDING THE SNAP-IN TO THE CURRENT SESSION -To add a registered snap-in to the current session, use the Add-PsSnapin cmdlet. For example, to add the Microsoft SQL Server snap-in to the session, type: +To add a registered snap-in to the current session, use the Add-PsSnapin +cmdlet. For example, to add the Microsoft SQL Server snap-in to the session, +type: -``` +```powershell add-pssnapin sql ``` - -After the command is completed, the providers and cmdlets in the snap-in are available in the session. However, they are available only in the current session unless you save them. - +After the command is completed, the providers and cmdlets in the snap-in are +available in the session. However, they are available only in the current +session unless you save them. ### SAVING THE SNAP-INS -To use a snap-in in future Windows PowerShell sessions, add the Add-PsSnapin command to your Windows PowerShell profile. Or, export the snap-in names to a console file. -If you add the Add-PSSnapin command to your profile, it is available in all future Windows PowerShell sessions. If you export the names of the snap-ins in your session, you can use the export file only when you need the snap-ins. +To use a snap-in in future Windows PowerShell sessions, add the Add-PsSnapin +command to your Windows PowerShell profile. Or, export the snap-in names to a +console file. -To add the Add-PsSnapin command to your Windows PowerShell profile, open your profile, paste or type the command, and then save the profile. For more information, see about_Profiles. +If you add the Add-PSSnapin command to your profile, it is available in all +future Windows PowerShell sessions. If you export the names of the snap-ins in +your session, you can use the export file only when you need the snap-ins. -To save the snap-ins from a session in console file (.psc1), use the Export-Console cmdlet. For example, to save the snap-ins in the current session configuration to the NewConsole.psc1 file in the current directory, type: +To add the Add-PsSnapin command to your Windows PowerShell profile, open your +profile, paste or type the command, and then save the profile. For more +information, see about_Profiles. +To save the snap-ins from a session in console file (.psc1), use the +Export-Console cmdlet. For example, to save the snap-ins in the current +session configuration to the NewConsole.psc1 file in the current directory, +type: -``` +```powershell export-console NewConsole ``` - For more information, see Export-Console. - ### OPENING WINDOWS POWERSHELL WITH A CONSOLE FILE -To use a console file that includes the snap-in, start Windows PowerShell (PowerShell.exe) from the command prompt in Cmd.exe or in another Windows PowerShell session. Use the PsConsoleFile parameter to specify the console file that includes the snap-in. For example, the following command starts Windows PowerShell with the NewConsole.psc1 console file: +To use a console file that includes the snap-in, start Windows PowerShell +(PowerShell.exe) from the command prompt in Cmd.exe or in another Windows +PowerShell session. Use the PsConsoleFile parameter to specify the console +file that includes the snap-in. For example, the following command starts +Windows PowerShell with the NewConsole.psc1 console file: -``` +```powershell PowerShell.exe -psconsolefile NewConsole.psc1 ``` - The providers and cmdlets in the snapin are now available for use in the session. - ### REMOVING A SNAP-IN -To remove a Windows PowerShell snap-in from the current session, use the Remove-PsSnapin cmdlet. For example, to remove the SQL Server snap-in from the current session, type: +To remove a Windows PowerShell snap-in from the current session, use the +Remove-PsSnapin cmdlet. For example, to remove the SQL Server snap-in from the +current session, type: -``` +```powershell remove-pssnapin sql ``` - -This cmdlet removes the snap-in from the session. The snap-in is still loaded, but the providers and cmdlets that it supports are no longer available. - +This cmdlet removes the snap-in from the session. The snap-in is still loaded, +but the providers and cmdlets that it supports are no longer available. ### BUILT-IN COMMANDS -In Windows PowerShell 2.0 and in older-style host programs in Windows PowerShell 3.0 and later, the built-in commands that are installed with Windows PowerShell are packaged in snap-ins that are added automatically to every Windows PowerShell session. -Beginning in Windows PowerShell 3.0, in newer-style host programs -- those that start sessions by using the InitialSessionState.CreateDefault2 method -- the built-in commands are packaged in modules. The exception is Microsoft.PowerShell.Core, which always appears as a snap-in. The Core snap-in is included in every session by default. The built-in modules are loaded automatically on first-use. +In Windows PowerShell 2.0 and in older-style host programs in Windows +PowerShell 3.0 and later, the built-in commands that are installed with +Windows PowerShell are packaged in snap-ins that are added automatically to +every Windows PowerShell session. -NOTE: Remote sessions, including sessions that are started by using the New-PSSession cmdlet, are older-style sessions in which the built-in commands are packaged in snap-ins. +Beginning in Windows PowerShell 3.0, in newer-style host programs -- those +that start sessions by using the InitialSessionState.CreateDefault2 method -- +the built-in commands are packaged in modules. The exception is +Microsoft.PowerShell.Core, which always appears as a snap-in. The Core snap-in +is included in every session by default. The built-in modules are loaded +automatically on first-use. -The following snap-ins (or modules) are installed with Windows PowerShell. - -Microsoft.PowerShell.Core - -Contains providers and cmdlets used to manage the basic features of Windows PowerShell. It includes the FileSystem, Registry, Alias, Environment, Function, and Variable providers and basic cmdlets like Get-Help, Get-Command, and Get-History. - -Microsoft.PowerShell.Host - -Contains cmdlets used by the Windows PowerShell host, such as Start-Transcript and Stop-Transcript. +NOTE: Remote sessions, including sessions that are started by using the +New-PSSession cmdlet, are older-style sessions in which the built-in commands +are packaged in snap-ins. -Microsoft.PowerShell.Management - -Contains cmdlets such as Get-Service and Get-ChildItem that are used to manage Windows-based features. - -Microsoft.PowerShell.Security +The following snap-ins (or modules) are installed with Windows PowerShell. -Contains the Certificate provider and cmdlets used to manage Windows PowerShell security, such as Get-Acl, Get-AuthenticodeSignature, and ConvertTo-SecureString. +- Microsoft.PowerShell.Core - Contains providers and cmdlets used to manage + the basic features of Windows PowerShell. It includes the FileSystem, + Registry, Alias, Environment, Function, and Variable providers and basic + cmdlets like Get-Help, Get-Command, and Get-History. -Microsoft.PowerShell.Utility +- Microsoft.PowerShell.Host - Contains cmdlets used by the Windows PowerShell + host, such as Start-Transcript and Stop-Transcript. -Contains cmdlets used to manipulate objects and data, such as Get-Member, Write-Host, and Format-List. +- Microsoft.PowerShell.Management - Contains cmdlets such as Get-Service and + Get-ChildItem that are used to manage Windows-based features. -Microsoft.WSMan.Management +- Microsoft.PowerShell.Security - Contains the Certificate provider and + cmdlets used to manage Windows PowerShell security, such as Get-Acl, + Get-AuthenticodeSignature, and ConvertTo-SecureString. -Contains the WSMan provider and cmdlets that manage the Windows Remote Management service, such as Connect-WSMan and Enable-WSManCredSSP. +- Microsoft.PowerShell.Utility - Contains cmdlets used to manipulate objects + and data, such as Get-Member, Write-Host, and Format-List. +- Microsoft.WSMan.Management - Contains the WSMan provider and cmdlets that + manage the Windows Remote Management service, such as Connect-WSMan and + Enable-WSManCredSSP. ## LOGGING SNAP-IN EVENTS -Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets in Windows PowerShell modules and snap-ins by setting the LogPipelineExecutionDetails property of modules and snap-ins to TRUE. For more information, see about_EventLogs (http:\/\/go.microsoft.com\/fwlink\/?LinkID\=113224). +Beginning in Windows PowerShell 3.0, you can record execution events for the +cmdlets in Windows PowerShell modules and snap-ins by setting the +LogPipelineExecutionDetails property of modules and snap-ins to TRUE. For more +information, see [about_EventLogs](about_EventLogs.md). ## SEE ALSO -Add-PsSnapin +[Add-PsSnapin](../Add-PsSnapin.md) -Get-PsSnapin +[Get-PsSnapin](../Get-PsSnapin.md) -Remove-PsSnapin +[Remove-PsSnapin](../Remove-PsSnapin.md) -Export-Console +[Export-Console](../Export-Console.md) -Get-Command +[Get-Command](../Get-Command.md) [about_Profiles](about_Profiles.md) [about_Modules](about_Modules.md) -## KEYWORDS: +## KEYWORDS about_Snapins, about_Snap_ins, about_Snap-ins - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md index 3d20a4dd1c6d..276ed1c7ded8 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,197 +7,227 @@ title: about_Parameters --- # About Parameters -## about_Parameters - ## SHORT DESCRIPTION -Describes how to work with command parameters in Windows PowerShell®. +Describes how to work with command parameters in PowerShell. ## LONG DESCRIPTION -Most Windows PowerShell commands, such as cmdlets, functions, and scripts, rely on parameters to allow users to select options or provide input. The parameters follow the command name and have the following form: +Most Windows PowerShell commands, such as cmdlets, functions, and scripts, +rely on parameters to allow users to select options or provide input. The +parameters follow the command name and have the following form: ``` - ``` +The name of the parameter is preceded by a hyphen (-), which signals to +Windows PowerShell that the word following the hyphen is a parameter name. +Some parameters do not require or accept a parameter value. Other parameters +require a value, but do not require the parameter name in the command. -The name of the parameter is preceded by a hyphen (-), which signals to Windows PowerShell that the word following the hyphen is a parameter name. Some parameters do not require or accept a parameter value. Other parameters require a value, but do not require the parameter name in the command. - -The type of parameters and the requirements for those parameters vary. To find information about the parameters of a command, use the Get-Help cmdlet. For example, to find information about the parameters of the Get-ChildItem cmdlet, type: +The type of parameters and the requirements for those parameters vary. To find +information about the parameters of a command, use the Get-Help cmdlet. For +example, to find information about the parameters of the Get-ChildItem cmdlet, +type: -``` +```powershell Get-Help Get-ChildItem ``` +To find information about the parameters of a script, use the full path to the +script file. For example: -To find information about the parameters of a script, use the full path to the script file. For example: - - -``` +```powershell Get-Help $home\Documents\Scripts\Get-Function.ps1 ``` +The Get-Help cmdlet returns various details about the command, including a +description, the command syntax, information about the parameters, and +examples showing how to use the parameters in a command. -The Get-Help cmdlet returns various details about the command, including a description, the command syntax, information about the parameters, and examples showing how to use the parameters in a command. - -You can also use the Parameter parameter of the Get-Help cmdlet to find information about a particular parameter. Or, you can use the Parameter parameter with the wildcard character (\*) value to find information about all parameters of the command. For example, the following command gets information about all parameters of the Get-Member cmdlet: +You can also use the Parameter parameter of the Get-Help cmdlet to find +information about a particular parameter. Or, you can use the Parameter +parameter with the wildcard character (\*) value to find information about all +parameters of the command. For example, the following command gets information +about all parameters of the Get-Member cmdlet: -``` +```powershell Get-Help Get-Member -Parameter * ``` ### DEFAULT PARAMETER VALUES -Optional parameters have a default value, which is the value that is used or assumed when the parameter is not specified in the command. -For example, the default value of the ComputerName parameter of many cmdlets is the name of the local computer. As a result, the local computer name is used in the command unless the ComputerName parameter is specified. +Optional parameters have a default value, which is the value that is used or +assumed when the parameter is not specified in the command. -To find the default parameter value, see help topic for the cmdlet. The parameter description should include the default value. +For example, the default value of the ComputerName parameter of many cmdlets +is the name of the local computer. As a result, the local computer name is +used in the command unless the ComputerName parameter is specified. -You can also set a custom default value for any parameter of a cmdlet or advanced function. For information about setting custom default values, see about_Parameters_Default_Values. +To find the default parameter value, see help topic for the cmdlet. The +parameter description should include the default value. +You can also set a custom default value for any parameter of a cmdlet or +advanced function. For information about setting custom default values, see +[about_Parameters_Default_Values](about_Parameters_Default_Values.md). ### PARAMETER ATTRIBUTE TABLE -When you use the Full, Parameter, or Online parameters of the Get-Help cmdlet, Get-Help displays a parameter attribute table with detailed information about the parameter. -This information includes the details you need to know to use the parameter. For example, the help topic for the Get-ChildItem cmdlet includes the following details about its Path parameter: +When you use the Full, Parameter, or Online parameters of the Get-Help cmdlet, +Get-Help displays a parameter attribute table with detailed information about +the parameter. + +This information includes the details you need to know to use the parameter. +For example, the help topic for the Get-ChildItem cmdlet includes the +following details about its Path parameter: ``` --path - Specifies a path of one or more locations. Wildcard characters are +-path + Specifies a path of one or more locations. Wildcard characters are permitted. The default location is the current directory (.). -``` - - -``` -Required? false -Position? 1 -Default value Current directory -Accept pipeline input? true (ByValue, ByPropertyName) +Required? false +Position? 1 +Default value Current directory +Accept pipeline input? true (ByValue, ByPropertyName) Accept wildcard characters? true ``` +The parameter information includes the parameter syntax, a description of the +parameter, and the parameter attributes. The following sections describe the +parameter attributes. -The parameter information includes the parameter syntax, a description of the parameter, and the parameter attributes. The following sections describe the parameter attributes. +#### Parameter Required? -Parameter Required? +This setting indicates whether the parameter is mandatory, that is, whether +all commands that use this cmdlet must include this parameter. When the value +is "True" and the parameter is missing from the command, Windows PowerShell +prompts you for a value for the parameter. -This setting indicates whether the parameter is mandatory, that is, whether all commands that use this cmdlet must include this parameter. When the value is "True" and the parameter is missing from the command, Windows PowerShell prompts you for a value for the parameter. +#### Parameter Position? -Parameter Position? +This setting indicates whether you can supply a parameter's value without +preceding it with the parameter name. If set to "0" or "named," a parameter +name is required. This type of parameter is referred to as a named parameter. +A named parameter can be listed in any position after the cmdlet name. -This setting indicates whether you can supply a parameter's value without preceding it with the parameter name. If set to "0" or "named," a parameter name is required. This type of parameter is referred to as a named parameter. A named parameter can be listed in any position after the cmdlet name. +If the "Parameter position?" setting is set to an integer other than 0, the +parameter name is not required. This type of parameter is referred to as a +positional parameter, and the number indicates the position in which the +parameter must appear in relation to other positional parameters. If you +include the parameter name for a positional parameter, the parameter can be +listed in any position after the cmdlet name. -If the "Parameter position?" setting is set to an integer other than 0, the parameter name is not required. This type of parameter is referred to as a positional parameter, and the number indicates the position in which the parameter must appear in relation to other positional parameters. If you include the parameter name for a positional parameter, the parameter can be listed in any position after the cmdlet name. +For example, the Get-ChildItem cmdlet has Path and Exclude parameters. The +"Parameter position?" setting for Path is 1, which means that it is a +positional parameter. The "Parameter position?" setting for Exclude is 0, +which means that it is a named parameter. -For example, the Get-ChildItem cmdlet has Path and Exclude parameters. The "Parameter position?" setting for Path is 1, which means that it is a positional parameter. The "Parameter position?" setting for Exclude is 0, which means that it is a named parameter. +This means that Path does not require the parameter name, but its parameter +value must be the first or only unnamed parameter value in the command. +However, because the Exclude parameter is a named parameter, you can place it +in any position in the command. -This means that Path does not require the parameter name, but its parameter value must be the first or only unnamed parameter value in the command. However, because the Exclude parameter is a named parameter, you can place it in any position in the command. +As a result of the "Parameter position?" settings for these two parameters, +you can use any of the following commands: -As a result of the "Parameter position?" settings for these two parameters, you can use any of the following commands: - -``` -Get-ChildItem -path c:\techdocs -exclude *.ppt -Get-ChildItem c:\techdocs -exclude *.ppt -Get-ChildItem -exclude *.ppt -path c:\techdocs +```powershell +Get-ChildItem -path c:\techdocs -exclude *.ppt +Get-ChildItem c:\techdocs -exclude *.ppt +Get-ChildItem -exclude *.ppt -path c:\techdocs Get-ChildItem -exclude *.ppt c:\techdocs ``` +If you were to include another positional parameter without including the +parameter name, that parameter would have to be placed in the order specified +by the "Parameter position?" setting. -If you were to include another positional parameter without including the parameter name, that parameter would have to be placed in the order specified by the "Parameter position?" setting. +#### Parameter Type -Parameter Type +This setting specifies the Microsoft .NET Framework type of the parameter +value. For example, if the type is Int32, the parameter value must be an +integer. If the type is string, the parameter value must be a character +string. If the string contains spaces, the value must be enclosed in quotation +marks, or the spaces must be preceded by the escape character (`). -This setting specifies the Microsoft .NET Framework type of the parameter value. For example, if the type is Int32, the parameter value must be an integer. If the type is string, the parameter value must be a character string. If the string contains spaces, the value must be enclosed in quotation marks, or the spaces must be preceded by the escape character (`). +#### Default Value -Default Value +This setting specifies the value that the parameter will assume if no other +value is provided. For example, the default value of the Path parameter is +often the current directory. Required parameters never have a default value. +For many optional parameters, there is no default because the parameter has no +effect if it is not used. -This setting specifies the value that the parameter will assume if no other value is provided. For example, the default value of the Path parameter is often the current directory. Required parameters never have a default value. For many optional parameters, there is no default because the parameter has no effect if it is not used. +#### Accepts Multiple Values? -Accepts Multiple Values? +This setting indicates whether a parameter accepts multiple parameter values. +When a parameter accepts multiple values, you can type a comma-separated list +as the value of the parameter in the command, or save a comma-separated list +(an array) in a variable, and then specify the variable as the parameter +value. -This setting indicates whether a parameter accepts multiple parameter values. When a parameter accepts multiple values, you can type a comma-separated list as the value of the parameter in the command, or save a comma-separated list (an array) in a variable, and then specify the variable as the parameter value. +For example, the ServiceName parameter of the Get-Service cmdlet accepts +multiple values. The following commands are both valid: -For example, the ServiceName parameter of the Get-Service cmdlet accepts multiple values. The following commands are both valid: - - -``` +```powershell get-service -servicename winrm, netlogon ``` - - -``` -$s = "winrm", "netlogon" +```powershell +$s = "winrm", "netlogon" get-service -servicename $s ``` +#### Accepts Pipeline Input? -Accepts Pipeline Input? - -This setting indicates whether you can use the pipeline operator (|) to send a value to the parameter. - +This setting indicates whether you can use the pipeline operator (|) to +send a value to the parameter. ``` -Value Description ------ ----------- -False Indicates that you cannot pipe a value to the +Value Description +----- ----------- +False Indicates that you cannot pipe a value to the parameter. -``` - - -``` -True (by Value) Indicates that you can pipe any value to the - parameter, just so the value has the .NET - Framework type specified for the parameter or the - value can be converted to the specified .NET +True (by Value) Indicates that you can pipe any value to the + parameter, just so the value has the .NET + Framework type specified for the parameter or the + value can be converted to the specified .NET Framework type. ``` - - -``` -When a parameter is "True (by Value)", Windows -PowerShell tries to associate any piped values -with that parameter before it tries other methods -to interpret the command. -``` - - +When a parameter is "True (by Value)", Windows PowerShell tries to associate +any piped values with that parameter before it tries other methods to +interpret the command. ``` -True (by Property Name) Indicates that you can pipe a value to the - parameter, but the .NET Framework type of the - parameter must include a property with the same +True (by Property Name) Indicates that you can pipe a value to the + parameter, but the .NET Framework type of the + parameter must include a property with the same name as the parameter. ``` +For example, you can pipe a value to a Name parameter only when the value has +a property called "Name". +#### Accepts Wildcard Characters? -``` -For example, you can pipe a value to a Name -parameter only when the value has a property -called "Name". -``` - - -Accepts Wildcard Characters? - -This setting indicates whether the parameter's value can contain wildcard characters so that the parameter value can be matched to more than one existing item in the target container. +This setting indicates whether the parameter's value can contain wildcard +characters so that the parameter value can be matched to more than one +existing item in the target container. -Common Parameters - -Common parameters are parameters that you can use with any cmdlet. For more information about common parameters, see about_CommonParameters +#### Common Parameters +Common parameters are parameters that you can use with any cmdlet. For more +information about common parameters, see [about_CommonParameters](about_CommonParameters.md). ## SEE ALSO @@ -212,4 +242,3 @@ Common parameters are parameters that you can use with any cmdlet. For more info [about_Pipelines](about_Pipelines.md) [about_Wildcards](about_Wildcards.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md index 7d8eb37366e3..39bf01d2725e 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,21 +7,20 @@ title: about_PowerShell_exe --- # About PowerShell.exe -## about_PowerShell.exe +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use the PowerShell.exe command-line tool. Displays the syntax +and describes the command-line switches. -Explains how to use the PowerShell.exe command-line tool. Displays -the syntax and describes the command-line switches. +PowerShell.exe starts a Windows PowerShell session. You can use it in Cmd.exe +and in Windows PowerShell. -PowerShell.exe starts a Windows PowerShell session. You can use it -in Cmd.exe and in Windows PowerShell. +## LONG DESCRIPTION -# LONG DESCRIPTION - -# SYNTAX +### SYNTAX +``` PowerShell[.exe] [-EncodedCommand ] [-ExecutionPolicy ] @@ -39,137 +38,143 @@ PowerShell[.exe] [-Command { - | [-args ] | [] } ] PowerShell[.exe] -Help | -? | /? +``` + +### PARAMETERS + +#### -EncodedCommand + +Accepts a base-64-encoded string version of a command. Use this parameter to +submit commands to Windows PowerShell that require complex quotation marks or +curly braces. + +#### -ExecutionPolicy + +Sets the default execution policy for the current session and saves it in the +$env:PSExecutionPolicyPreference environment variable. This parameter does not +change the Windows PowerShell execution policy that is set in the registry. +For information about Windows PowerShell execution policies, including a list +of valid values, see [about_Execution_Policies](about_Execution_Policies.md). + +#### -File [] + +Runs the specified script in the local scope ("dot-sourced"), so that the +functions and variables that the script creates are available in the current +session. Enter the script file path and any parameters. File must be the last +parameter in the command, because all characters typed after the File +parameter name are interpreted as the script file path followed by the script +parameters. + +You can include the parameters of a script, and parameter values, in the value +of the File parameter. For example: -File .\\Get-Script.ps1 -Domain Central + +Typically, the switch parameters of a script are either included or omitted. +For example, the following command uses the All parameter of the +Get-Script.ps1 script file: -File .\\Get-Script.ps1 -All + +In rare cases, you might need to provide a Boolean value for a switch +parameter. To provide a Boolean value for a switch parameter in the value of +the File parameter, enclose the parameter name and value in curly braces, such +as the following: -File .\\Get-Script.ps1 {-All:$False}. + +#### -InputFormat {Text | XML} + +Describes the format of data sent to Windows PowerShell. Valid values are +"Text" (text strings) or "XML" (serialized CLIXML format). + +#### -Mta + +Starts Windows PowerShell using a multi-threaded apartment. This parameter is +introduced in Windows PowerShell 3.0. In Windows PowerShell 2.0, +multi-threaded apartment (MTA) is the default. In Windows PowerShell 3.0, +single-threaded apartment (STA) is the default. + +#### -NoExit -# PARAMETERS - - --EncodedCommand -Accepts a base-64-encoded string version of a command. -Use this parameter to submit commands to Windows PowerShell -that require complex quotation marks or curly braces. - --ExecutionPolicy -Sets the default execution policy for the current session -and saves it in the $env:PSExecutionPolicyPreference environment -variable. This parameter does not change the Windows PowerShell -execution policy that is set in the registry. For information -about Windows PowerShell execution policies, including a list -of valid values, see about_Execution_Policies -(http://go.microsoft.com/fwlink/?LinkID=135170). - --File [] -Runs the specified script in the local scope ("dot-sourced"), -so that the functions and variables that the script creates -are available in the current session. Enter the script file -path and any parameters. File must be the last parameter in -the command, because all characters typed after the File -parameter name are interpreted as the script file path followed -by the script parameters. - -You can include the parameters of a script, and parameter -values, in the value of the File parameter. For example: --File .\Get-Script.ps1 -Domain Central - -Typically, the switch parameters of a script are either -included or omitted. For example, the following command -uses the All parameter of the Get-Script.ps1 script file: --File .\Get-Script.ps1 -All - -In rare cases, you might need to provide a Boolean value -for a switch parameter. To provide a Boolean value for a -switch parameter in the value of the File parameter, -enclose the parameter name and value in curly braces, -such as the following: --File .\Get-Script.ps1 {-All:$False}. - --InputFormat {Text | XML} -Describes the format of data sent to Windows PowerShell. Valid -values are "Text" (text strings) or "XML" (serialized CLIXML format). - --Mta -Starts Windows PowerShell using a multi-threaded apartment. This -parameter is introduced in Windows PowerShell 3.0. In Windows -PowerShell 2.0, multi-threaded apartment (MTA) is the default. -In Windows PowerShell 3.0, single-threaded apartment (STA) is -the default. - --NoExit Does not exit after running startup commands. --NoLogo +#### -NoLogo + Hides the copyright banner at startup. --NonInteractive +#### -NonInteractive + Does not present an interactive prompt to the user. --NoProfile +#### -NoProfile + Does not load the Windows PowerShell profile. --OutputFormat {Text | XML} -Determines how output from Windows PowerShell is formatted. -Valid values are "Text" (text strings) or "XML" (serialized -CLIXML format). - --PSConsoleFile -Loads the specified Windows PowerShell console file. Enter -the path and name of the console file. To create a console file, -use the Export-Console cmdlet in Windows PowerShell. - --Sta -Starts Windows PowerShell using a single-threaded apartment. In -Windows PowerShell 2.0, multi-threaded apartment (MTA) is the default. -In Windows PowerShell 3.0, single-threaded apartment (STA) is the -default. - --Version -Starts the specified version of Windows PowerShell. Valid values -are 2.0 and 3.0. The version that you specify must be installed -on the system. If Windows PowerShell 3.0 is installed on the -computer, "3.0" is the default version. Otherwise, "2.0" is the -default version. For more information, see "Installing Windows -PowerShell" in the Windows PowerShell Getting Started Guide. - --WindowStyle -Sets the window style for the session. Valid values are Normal, -Minimized, Maximized and Hidden. - --Command -Executes the specified commands (and any parameters) as though -they were typed at the Windows PowerShell command prompt, and -then exits, unless the NoExit parameter is specified. - -The value of Command can be "-", a string. or a script block. If -the value of Command is "-", the command text is read from standard -input. - -Script blocks must be enclosed in braces ({}). You can specify a -script block only when running PowerShell.exe in Windows PowerShell. -The results of the script are returned to the parent shell as -deserialized XML objects, not live objects. - -If the value of Command is a string, Command must be the last -parameter in the command , because any characters typed after -the command are interpreted as the command arguments. +#### -OutputFormat {Text | XML} + +Determines how output from Windows PowerShell is formatted. Valid values are +"Text" (text strings) or "XML" (serialized CLIXML format). + +#### -PSConsoleFile + +Loads the specified Windows PowerShell console file. Enter the path and name +of the console file. To create a console file, use the Export-Console cmdlet +in Windows PowerShell. + +#### -Sta + +Starts Windows PowerShell using a single-threaded apartment. In Windows +PowerShell 2.0, multi-threaded apartment (MTA) is the default. In Windows +PowerShell 3.0, single-threaded apartment (STA) is the default. + +#### -Version + +Starts the specified version of Windows PowerShell. Valid values are 2.0 and +3.0. The version that you specify must be installed on the system. If Windows +PowerShell 3.0 is installed on the computer, "3.0" is the default version. +Otherwise, "2.0" is the default version. For more information, see "Installing +Windows PowerShell" in the Windows PowerShell Getting Started Guide. + +#### -WindowStyle + +Sets the window style for the session. Valid values are Normal, Minimized, +Maximized and Hidden. + +#### -Command + +Executes the specified commands (and any parameters) as though they were typed +at the Windows PowerShell command prompt, and then exits, unless the NoExit +parameter is specified. + +The value of Command can be "-", a string. or a script block. If the value of +Command is "-", the command text is read from standard input. + +Script blocks must be enclosed in braces ({}). You can specify a script block +only when running PowerShell.exe in Windows PowerShell. The results of the +script are returned to the parent shell as deserialized XML objects, not live +objects. + +If the value of Command is a string, Command must be the last parameter in the +command , because any characters typed after the command are interpreted as +the command arguments. To write a string that runs a Windows PowerShell command, use the format: + "& {}" -where the quotation marks indicate a string and the invoke operator -(&) causes the command to be executed. --Help, -?, /? -Displays help for PowerShell.exe. If you are typing a PowerShell.exe -command in Windows PowerShell, prepend the command parameters with a -hyphen (-), not a forward slash (/). You can use either a hyphen or -forward slash in Cmd.exe. +where the quotation marks indicate a string and the invoke operator (&) causes +the command to be executed. -# REMARKS: +#### -Help, -?, /? -Troubleshooting note: In Windows PowerShell 2.0, starting some programs -from the Windows PowerShell console fails with a LastExitCode of 0xc0000142. +Displays help for PowerShell.exe. If you are typing a PowerShell.exe command +in Windows PowerShell, prepend the command parameters with a hyphen (-), not a +forward slash (/). You can use either a hyphen or forward slash in Cmd.exe. -# EXAMPLES +### REMARKS +Troubleshooting note: In Windows PowerShell 2.0, starting some programs from +the Windows PowerShell console fails with a LastExitCode of 0xc0000142. + +### EXAMPLES + +```powershell PowerShell -PSConsoleFile sqlsnapin.psc1 PowerShell -Version 2.0 -NoLogo -InputFormat text -OutputFormat XML @@ -177,5 +182,4 @@ PowerShell -Version 2.0 -NoLogo -InputFormat text -OutputFormat XML PowerShell -Command {Get-EventLog -LogName security} PowerShell -Command "& {Get-EventLog -LogName security}" - - +``` \ No newline at end of file diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Providers.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Providers.md index dfed0885c30d..8080f77944b9 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Providers.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Providers.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,61 +7,58 @@ title: about_Providers --- # About Providers -## about_Providers - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes how Windows PowerShell providers provide access to data and -components that would not otherwise be easily accessible at the command -line. The data is presented in a consistent format that resembles a file -system drive. - -# LONG DESCRIPTION - -Windows PowerShell providers are Microsoft .NET Framework-based programs -that make the data in a specialized data store available in Windows -PowerShell so that you can view and manage it. - -The data that a provider exposes appears in a drive, and you access the -data in a path like you would on a hard disk drive. You can use any of the -built-in cmdlets that the provider supports to manage the data in the -provider drive. And, you can use custom cmdlets that are designed -especially for the data. - -The providers can also add dynamic parameters to the built-in cmdlets. -These are parameters that are available only when you use the cmdlet with -the provider data. - -# BUILT-IN PROVIDERS - -Windows PowerShell includes a set of built-in providers that you can use -to access the different types of data stores. - -| Provider | Drive | Data store | -| ----------- | ------------ | ------------------------------------------ | -| Alias | Alias: | Windows PowerShell aliases | -| Certificate | Cert: | x509 certificates for digital signatures | -| Environment | Env: | Windows environment variables | -| FileSystem | (*) | File system drives, directories, and files | -| Function | Function: | Windows PowerShell functions | -| Registry | HKLM:, HKCU: | Windows registry | -| Variable | Variable: | Windows PowerShell variables | -| WSMan | WSMan: | WS-Management configuration information | +components that would not otherwise be easily accessible at the command line. +The data is presented in a consistent format that resembles a file system +drive. + +## LONG DESCRIPTION + +Windows PowerShell providers are Microsoft .NET Framework-based programs that +make the data in a specialized data store available in Windows PowerShell so +that you can view and manage it. + +The data that a provider exposes appears in a drive, and you access the data +in a path like you would on a hard disk drive. You can use any of the built-in +cmdlets that the provider supports to manage the data in the provider drive. +And, you can use custom cmdlets that are designed especially for the data. + +The providers can also add dynamic parameters to the built-in cmdlets. These +are parameters that are available only when you use the cmdlet with the +provider data. + +## BUILT-IN PROVIDERS + +Windows PowerShell includes a set of built-in providers that you can use to +access the different types of data stores. + +|Provider |Drive |Data store | +|------------|-------------|-------------------------------------------| +|Alias |Alias: |Windows PowerShell aliases | +|Certificate |Cert: |x509 certificates for digital signatures | +|Environment |Env: |Windows environment variables | +|FileSystem |(*) |File system drives, directories, and files | +|Function |Function: |Windows PowerShell functions | +|Registry |HKLM:, HKCU: |Windows registry | +|Variable |Variable: |Windows PowerShell variables | +|WSMan |WSMan: |WS-Management configuration information | (*) The FileSystem drives vary on each system. -You can also create your own Windows PowerShell providers, and you can -install providers that others develop. To list the providers that are -available in your session, type: +You can also create your own Windows PowerShell providers, and you can install +providers that others develop. To list the providers that are available in +your session, type: get-psprovider -# INSTALLING AND REMOVING PROVIDERS +## INSTALLING AND REMOVING PROVIDERS Windows PowerShell providers are delivered to you in Windows PowerShell -snap-ins, which are .NET Framework-based programs that are compiled -into .dll files. The snap-ins can include providers and cmdlets. +snap-ins, which are .NET Framework-based programs that are compiled into .dll +files. The snap-ins can include providers and cmdlets. Before you use the provider features, you have to install the snap-in and then add it to your Windows PowerShell session. For more information, see @@ -76,96 +73,99 @@ cmdlet. This cmdlet does not uninstall the provider, but it makes the provider unavailable in the session. You can also use the Remove-PSDrive cmdlet to remove any drive from the -current session. This data on the drive is not affected, but the drive is -no longer available in that session. +current session. This data on the drive is not affected, but the drive is no +longer available in that session. -# VIEWING PROVIDERS +## VIEWING PROVIDERS To view the Windows PowerShell providers on your computer, type: +```powershell get-psprovider +``` -The output lists the built-in providers and the providers that you added -to the session. +The output lists the built-in providers and the providers that you added to +the session. -# THE PROVIDER CMDLETS +## THE PROVIDER CMDLETS -The following cmdlets are designed to work with the data exposed by -any provider. You can use the same cmdlets in the same way to manage -the different types of data that providers expose. After you -learn to manage the data of one provider, you can use the same -procedures with the data from any provider. +The following cmdlets are designed to work with the data exposed by any +provider. You can use the same cmdlets in the same way to manage the different +types of data that providers expose. After you learn to manage the data of one +provider, you can use the same procedures with the data from any provider. -For example, the New-Item cmdlet creates a new item. In the C: drive that -is supported by the FileSystem provider, you can use New-Item to create a -new file or folder. In the drives that are supported by the Registry -provider, you can use New-Item to create a new registry key. In the Alias: -drive, you can use New-Item to create a new alias. +For example, the New-Item cmdlet creates a new item. In the C: drive that is +supported by the FileSystem provider, you can use New-Item to create a new +file or folder. In the drives that are supported by the Registry provider, you +can use New-Item to create a new registry key. In the Alias: drive, you can +use New-Item to create a new alias. For detailed information about any of the following cmdlets, type: +``` get-help -detailed +``` -# CHILDITEM CMDLETS +### CHILDITEM CMDLETS -Get-ChildItem +- Get-ChildItem -# CONTENT CMDLETS +### CONTENT CMDLETS -Add-Content -Clear-Content -Get-Content -Set-Content +- Add-Content +- Clear-Content +- Get-Content +- Set-Content -# ITEM CMDLETS +### ITEM CMDLETS -Clear-Item -Copy-Item -Get-Item -Invoke-Item -Move-Item -New-Item -Remove-Item -Rename-Item -Set-Item +- Clear-Item +- Copy-Item +- Get-Item +- Invoke-Item +- Move-Item +- New-Item +- Remove-Item +- Rename-Item +- Set-Item -# ITEMPROPERTY CMDLETS +### ITEMPROPERTY CMDLETS -Clear-ItemProperty -Copy-ItemProperty -Get-ItemProperty -Move-ItemProperty -New-ItemProperty -Remove-ItemProperty -Rename-ItemProperty -Set-ItemProperty +- Clear-ItemProperty +- Copy-ItemProperty +- Get-ItemProperty +- Move-ItemProperty +- New-ItemProperty +- Remove-ItemProperty +- Rename-ItemProperty +- Set-ItemProperty -# LOCATION CMDLETS +### LOCATION CMDLETS -Get-Location -Pop-Location -Push-Location -Set-Location +- Get-Location +- Pop-Location +- Push-Location +- Set-Location -# PATH CMDLETS +### PATH CMDLETS -Join-Path -Convert-Path -Split-Path -Resolve-Path -Test-Path +- Join-Path +- Convert-Path +- Split-Path +- Resolve-Path +- Test-Path -# PSDRIVE CMDLETS +### PSDRIVE CMDLETS -Get-PSDrive -New-PSDrive -Remove-PSDrive +- Get-PSDrive +- New-PSDrive +- Remove-PSDrive -# PSPROVIDER CMDLETS +### PSPROVIDER CMDLETS -Get-PSProvider +- Get-PSProvider -# VIEWING PROVIDER DATA +## VIEWING PROVIDER DATA The primary benefit of a provider is that it exposes its data in a familiar and consistent way. The model for data presentation is a file system @@ -190,85 +190,108 @@ To view the contents of a provider drive, use the Get-Item or Get-ChildItem cmdlets. Type the drive name followed by a colon (:). For example, to view the contents of the Alias: drive, type: +```powershell get-item alias: +``` You can view and manage the data in any drive from another drive by including the drive name in the path. For example, to view the HKLM\Software registry key in the HKLM: drive from another drive, type: +```powershell get-childitem hklm:\software +``` To open the drive, use the Set-Location cmdlet. Remember the colon when you specify the drive path. For example, to change your location to the root directory of the Cert: drive, type: +```powershell set-location cert: +``` Then, to view the contents of the Cert: drive, type: +```powershell get-childitem +``` -# MOVING THROUGH HIERARCHICAL DATA +## MOVING THROUGH HIERARCHICAL DATA You can move through a provider drive just as you would a hard disk drive. If the data is arranged in a hierarchy of items within items, use a backslash () to indicate a child item. Use the following format: +``` drive:\location\child-location\... +``` For example, to change your location to the HKLM\Software registry key, type a Set-Location command, such as: +```powershell set-location hklm:\software +``` You can also use relative references to locations. A dot (.) represents the current location. For example, if you are in the HKLM:\Software\Microsoft registry key, and you want to list the registry subkeys in the HKLM:\Software\Microsoft\PowerShell key, type the following command: +```powershell get-childitem .\PowerShell +``` -# FINDING DYNAMIC PARAMETERS +## FINDING DYNAMIC PARAMETERS -Dynamic parameters are cmdlet parameters that are added to a cmdlet -by a provider. These parameters are available only when the cmdlet is -used with the provider that added them. +Dynamic parameters are cmdlet parameters that are added to a cmdlet by a +provider. These parameters are available only when the cmdlet is used with the +provider that added them. -For example, the Cert: drive adds the CodeSigningCert parameter -to the Get-Item and Get-ChildItem cmdlets. You can use this parameter -only when you use Get-Item or Get-ChildItem in the Cert: drive. +For example, the Cert: drive adds the CodeSigningCert parameter to the +Get-Item and Get-ChildItem cmdlets. You can use this parameter only when you +use Get-Item or Get-ChildItem in the Cert: drive. -For a list of the dynamic parameters that a provider supports, see the -Help file for the provider. Type: +For a list of the dynamic parameters that a provider supports, see the Help +file for the provider. Type: +``` get-help +``` For example: +```powershell get-help certificate +``` -# LEARNING ABOUT PROVIDERS +## LEARNING ABOUT PROVIDERS -Although all provider data appears in drives, and you use the same methods -to move through them, the similarity stops there. The data stores that -the provider exposes can be as varied as Active Directory locations and -Microsoft Exchange Server mailboxes. +Although all provider data appears in drives, and you use the same methods to +move through them, the similarity stops there. The data stores that the +provider exposes can be as varied as Active Directory locations and Microsoft +Exchange Server mailboxes. For information about individual Windows PowerShell providers, type: +``` get-help +``` For example: +```powershell get-help registry +``` For a list of Help topics about the providers, type: +```powershell get-help * -category provider +``` -# SEE ALSO +## SEE ALSO -about_Locations +[about_Locations](about_Locations.md) [about_Path_Syntax](about_Path_Syntax.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 96a296feca9a..8df82dca043b 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,290 +7,272 @@ title: about_Quoting_Rules --- # About Quoting Rules -## about_Quoting_Rules - ## SHORT DESCRIPTION -Describes rules for using single and double quotation marks in Windows PowerShell®. +Describes rules for using single and double quotation marks in PowerShell. ## LONG DESCRIPTION -Quotation marks are used to specify a literal string. You can enclose a string in single quotation marks (') or double quotation marks ("). -Quotation marks are also used to create a here-string. A here-string is a single-quoted or double-quoted string in which quotation marks are interpreted literally. A here-string can span multiple lines. All the lines in a here-string are interpreted as strings, even though they are not enclosed in quotation marks. +Quotation marks are used to specify a literal string. You can enclose a string +in single quotation marks (') or double quotation marks ("). -In commands to remote computers, quotation marks define the parts of the command that are run on the remote computer. In a remote session, quotation marks also determine whether the variables in a command are interpreted first on the local computer or on the remote computer. +Quotation marks are also used to create a here-string. A here-string is a +single-quoted or double-quoted string in which quotation marks are interpreted +literally. A here-string can span multiple lines. All the lines in a +here-string are interpreted as strings, even though they are not enclosed in +quotation marks. +In commands to remote computers, quotation marks define the parts of the +command that are run on the remote computer. In a remote session, quotation +marks also determine whether the variables in a command are interpreted first +on the local computer or on the remote computer. ### SINGLE AND DOUBLE-QUOTED STRINGS -When you enclose a string in double quotation marks (a double-quoted string), variable names that are preceded by a dollar sign ($) are replaced with the variable's value before the string is passed to the command for processing. -For example: +When you enclose a string in double quotation marks (a double-quoted string), +variable names that are preceded by a dollar sign ($) are replaced with the +variable's value before the string is passed to the command for processing. +For example: -``` +```powershell $i = 5 "The value of $i is $i." ``` - The output of this command is: - -``` +```output The value of 5 is 5. ``` +Also, in a double-quoted string, expressions are evaluated, and the result is +inserted in the string. For example: -Also, in a double-quoted string, expressions are evaluated, and the result is inserted in the string. For example: - - -``` +```powershell "The value of $(2+3) is 5." ``` - The output of this command is: - -``` +```output The value of 5 is 5. ``` +When you enclose a string in single-quotation marks (a single-quoted string), +the string is passed to the command exactly as you type it. No substitution is +performed. For example: -When you enclose a string in single-quotation marks (a single-quoted string), the string is passed to the command exactly as you type it. No substitution is performed. For example: - - -``` +```powershell $i = 5 'The value of $i is $i.' ``` - The output of this command is: - -``` +```output The value $i is $i. ``` +Similarly, expressions in single-quoted strings are not evaluated. They are +interpreted as literals. For example: -Similarly, expressions in single-quoted strings are not evaluated. They are interpreted as literals. For example: - - -``` +```powershell 'The value of $(2+3) is 5.' ``` - The output of this command is: - -``` +```output The value of $(2+3) is 5. ``` +To prevent the substitution of a variable value in a double-quoted string, use +the backtick character (`)(ASCII 96), which is the Windows PowerShell escape +character. -To prevent the substitution of a variable value in a double-quoted string, use the backtick character (`)(ASCII 96), which is the Windows PowerShell escape character. - -In the following example, the backtick character that precedes the first $i variable prevents Windows PowerShell from replacing the variable name with its value. For example: - +In the following example, the backtick character that precedes the first $i +variable prevents Windows PowerShell from replacing the variable name with its +value. For example: -``` +```powershell $i = 5 "The value of `$i is $i." ``` - The output of this command is: - -``` +```output The value $i is 5. ``` +To make double-quotation marks appear in a string, enclose the entire string +in single quotation marks. For example: -To make double-quotation marks appear in a string, enclose the entire string in single quotation marks. For example: - - -``` +```powershell 'As they say, "live and learn."' ``` - The output of this command is: - -``` +```output As they say, "live and learn." ``` +You can also enclose a single-quoted string in a double-quoted string. For +example: -You can also enclose a single-quoted string in a double-quoted string. For example: - - -``` +```powershell "As they say, 'live and learn.'" ``` - The output of this command is: - -``` +```output As they say, 'live and learn.' ``` - Or, double the quotation marks around a double-quoted phrase. For example: - -``` +```powershell "As they say, ""live and learn.""" ``` - The output of this command is: - -``` +```output As they say, "live and learn." ``` +To include a single quotation mark in a single-quoted string, use a second +consecutive single quote. For example: -To include a single quotation mark in a single-quoted string, use a second consecutive single quote. For example: - - -``` +```powershell 'don''t' ``` - The output of this command is: - -``` +```output don't ``` +To force Windows PowerShell to interpret a double quotation mark literally, +use a backtick character. This prevents Windows PowerShell from interpreting +the quotation mark as a string delimiter. For example: -To force Windows PowerShell to interpret a double quotation mark literally, use a backtick character. This prevents Windows PowerShell from interpreting the quotation mark as a string delimiter. For example: - - -``` +```powershell "Use a quotation mark (`") to begin a string." ``` +Because the contents of single-quoted strings are interpreted literally, you +cannot use the backtick character to force a literal character interpretation +in a single-quoted string. -Because the contents of single-quoted strings are interpreted literally, you cannot use the backtick character to force a literal character interpretation in a single-quoted string. - -For example, the following command generates an error because Windows PowerShell does not recognize the escape character. Instead, it interprets the second quotation mark as the end of the string. - +For example, the following command generates an error because Windows +PowerShell does not recognize the escape character. Instead, it interprets the +second quotation mark as the end of the string. -``` +```output PS C:\> 'Use a quotation mark (`') to begin a string.' Unexpected token ')' in expression or statement. At line:1 char:27 + 'Use a quotation mark (`') <<<< to begin a string.' ``` - - ### HERE-STRINGS + The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation marks are interpreted literally. A here-string can span multiple lines. All the lines in a here-string are interpreted as strings even though they are not enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string in which quotation +marks are interpreted literally. A here-string can span multiple lines. All +the lines in a here-string are interpreted as strings even though they are not +enclosed in quotation marks. -Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by their values. +Like regular strings, variables are replaced by their values in double-quoted +here-strings. In single-quoted here-strings, variables are not replaced by +their values. -You can use here-strings for any text, but they are particularly useful for the following kinds of text: +You can use here-strings for any text, but they are particularly useful for +the following kinds of text: --- Text that contains literal quotation marks --- Multiple lines of text, such as the text in an HTML or XML --- The Help text for a script or function document +- Text that contains literal quotation marks +- Multiple lines of text, such as the text in an HTML or XML +- The Help text for a script or function document -A here-string can have either of the following formats, where represents the linefeed or newline hidden character that is added when you press the ENTER key. +A here-string can have either of the following formats, where \ +represents the linefeed or newline hidden character that is added when you +press the ENTER key. +Double-quotes: ``` -Double-quotes: - @" - [string] ... - "@ +@" + [string] ... +"@ ``` - - -``` Single-quotes: - @' - [string] ... - '@ +``` +@' + [string] ... +'@ ``` +In either format, the closing quotation mark must be the first character in +the line. -In either format, the closing quotation mark must be the first character in the line. - -A here-string contains all the text between the two hidden characters. In the here-string, all quotation marks are interpreted literally. For example: - +A here-string contains all the text between the two hidden characters. In the +here-string, all quotation marks are interpreted literally. For example: -``` +```powershell @" For help, type "get-help" "@ ``` - The output of this command is: - -``` +```output For help, type "get-help" ``` - Using a here-string can simplify using a string in a command. For example: - -``` +```powershell @" Use a quotation mark (') to begin a string. "@ ``` - The output of this command is: - -``` +```output Use a quotation mark (') to begin a string. ``` +In single-quoted here-strings, variables are interpreted literally and +reproduced exactly. For example: -In single-quoted here-strings, variables are interpreted literally and reproduced exactly. For example: - - -``` +```powershell @' The $profile variable contains the path of your Windows PowerShell profile. '@ ``` - The output of this command is: - -``` +```output The $profile variable contains the path of your Windows PowerShell profile. ``` +In double-quoted here-strings, variables are replaced by their values. For +example: -In double-quoted here-strings, variables are replaced by their values. For example: - - -``` +```powershell @" Even if you have not created a profile, the path of the profile file is: @@ -298,21 +280,19 @@ $profile. "@ ``` - The output of this command is: - -``` +```output Even if you have not created a profile, the path of the profile file is: -C:\Users\User01\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1. +C:\Users\User1\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1. ``` +Here-strings are typically used to assign multiple lines to a variable. For +example, the following here-string assigns a page of XML to the $page +variable. -Here-strings are typically used to assign multiple lines to a variable. For example, the following here-string assigns a page of XML to the $page variable. - - -``` +```powershell $page = [XML] @" "@ ``` - -Here-strings are also a convenient format for input to the ConvertFrom-StringData cmdlet, which converts here-strings to hash tables. For more information, see ConvertFrom-StringData. - - -## KEYWORDS -about_Here-Strings - -about_Quotes - -about_Quotation_Marks - +Here-strings are also a convenient format for input to the +ConvertFrom-StringData cmdlet, which converts here-strings to hash tables. For +more information, see ConvertFrom-StringData. ## SEE ALSO [about_Special_Characters](about_Special_Characters.md) -ConvertFrom-StringData - +[ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote.md index ac5e0c6fa90a..36455b275f7e 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,73 +7,74 @@ title: about_Remote --- # About Remote -## about_Remote - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes how to run remote commands in Windows PowerShell. -# LONG DESCRIPTION - -You can run remote commands on a single computer or on multiple -computers by using a temporary or persistent connection. You can also -start an interactive session with a single remote computer. +## LONG DESCRIPTION -This topic provides a series of examples to show you how to -run different types of remote command. After you try these basic -commands, read the Help topics that describe each cmdlet that is -used in these commands. The topics provide the details and explain -how you can modify the commands to meet your needs. +You can run remote commands on a single computer or on multiple computers by +using a temporary or persistent connection. You can also start an interactive +session with a single remote computer. -Note: To use Windows PowerShell remoting, the local and remote computers -must be configured for remoting. For more information, see -about_Remote_Requirements. +This topic provides a series of examples to show you how to run different +types of remote command. After you try these basic commands, read the Help +topics that describe each cmdlet that is used in these commands. The topics +provide the details and explain how you can modify the commands to meet your +needs. -# HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION) +Note: To use Windows PowerShell remoting, the local and remote computers must +be configured for remoting. For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). +## HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION) -The easiest way to run remote commands is to start an -interactive session with a remote computer. +The easiest way to run remote commands is to start an interactive session with +a remote computer. -When the session starts, the commands that you type run on the -remote computer, just as though you typed them directly -on the remote computer. You can connect to only one -computer in each interactive session. +When the session starts, the commands that you type run on the remote +computer, just as though you typed them directly on the remote computer. You +can connect to only one computer in each interactive session. -To start an interactive session, use the Enter-PSSession -cmdlet. The following command starts an interactive session -with the Server01 computer: +To start an interactive session, use the Enter-PSSession cmdlet. The following +command starts an interactive session with the Server01 computer: +```powershell Enter-PSSession Server01 +``` -The command prompt changes to indicate that you are connected -to the Server01 computer. +The command prompt changes to indicate that you are connected to the Server01 +computer. +``` Server01\PS> +``` Now, you can type commands on the Server01 computer. To end the interactive session, type: +```powershell Exit-PSSession +``` For more information, see Enter-PSSession. -# HOW TO USE CMDLETS THAT HAVE A COMPUTERNAME PARAMETER TO GET REMOTE DATA +## HOW TO USE CMDLETS THAT HAVE A COMPUTERNAME PARAMETER TO GET REMOTE DATA - -Several cmdlets have a ComputerName parameter that lets you -get objects from remote computers. +Several cmdlets have a ComputerName parameter that lets you get objects from +remote computers. Because these cmdlets do not use WS-Management-based Windows PowerShell remoting, you can use the ComputerName parameter of these cmdlets on any -computer that is running Windows PowerShell. The computers do not have to -be configured for Windows PowerShell remoting, and the computers do not -have to meet the system requirements for remoting. +computer that is running Windows PowerShell. The computers do not have to be +configured for Windows PowerShell remoting, and the computers do not have to +meet the system requirements for remoting. The following cmdlets have a ComputerName parameter: +``` Clear-EventLog Limit-EventLog Get-Counter New-EventLog Get-EventLog Remove-EventLog @@ -82,15 +83,18 @@ Get-Process Show-EventLog Get-Service Stop-Computer Get-WinEvent Test-Connection Get-WmiObject Write-EventLog +``` For example, the following command gets the services on the Server01 remote computer: +```powershell Get-Service -ComputerName Server01 +``` -Typically, cmdlets that support remoting without special configuration -have a **ComputerName** parameter and do not have a **Session** parameter. -To find these cmdlets in your session, type: +Typically, cmdlets that support remoting without special configuration have a +**ComputerName** parameter and do not have a **Session** parameter. To find +these cmdlets in your session, type: ```powershell Get-Command | Where-Object { @@ -99,131 +103,134 @@ Get-Command | Where-Object { } ``` -# HOW TO RUN A REMOTE COMMAND +## HOW TO RUN A REMOTE COMMAND +To run other commands on remote computers, use the Invoke-Command cmdlet. -To run other commands on remote computers, use the -Invoke-Command cmdlet. +To run a single command or a few unrelated commands, use the ComputerName +parameter of Invoke-Command to specify the remote computers. Use the +ScriptBlock parameter to specify the command. -To run a single command or a few unrelated commands, use the -ComputerName parameter of Invoke-Command to specify the remote -computers. Use the ScriptBlock parameter to specify the command. - -For example, the following command runs a Get-Culture command -on the Server01 computer. +For example, the following command runs a Get-Culture command on the Server01 +computer. +```powershell Invoke-Command -ComputerName Server01 -ScriptBlock {Get-Culture} +``` -The ComputerName parameter is designed for situation in which you run -a single command or several unrelated commands on one or many computers. -To establish a persistent connection to a remote computer, use -the Session parameter. - -# HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION) +The ComputerName parameter is designed for situation in which you run a single +command or several unrelated commands on one or many computers. To establish a +persistent connection to a remote computer, use the Session parameter. +## HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION) -When you use the ComputerName parameter of the Invoke-Command -cmdlet, Windows PowerShell establishes a connection just for the -command. Then, it closes the connection when the command is complete. Any -variables or functions that are defined in the command are lost. +When you use the ComputerName parameter of the Invoke-Command cmdlet, Windows +PowerShell establishes a connection just for the command. Then, it closes the +connection when the command is complete. Any variables or functions that are +defined in the command are lost. -To create a persistent connection to a remote computer, use the -New-PSSession cmdlet. For example, the following command creates -PSSessions on the Server01 and Server02 computers and then saves the -PSSessions in the $s variable. +To create a persistent connection to a remote computer, use the New-PSSession +cmdlet. For example, the following command creates PSSessions on the Server01 +and Server02 computers and then saves the PSSessions in the $s variable. +```powershell $s = New-PSSession -ComputerName Server01, Server02 +``` -# HOW TO RUN COMMANDS IN A PSSESSION - +## HOW TO RUN COMMANDS IN A PSSESSION -With a PSSession, you can run a series of remote commands that -share data, like functions, aliases, and the values of variables. -To run commands in a PSSession, use the Session parameter of the -Invoke-Command cmdlet. +With a PSSession, you can run a series of remote commands that share data, +like functions, aliases, and the values of variables. To run commands in a +PSSession, use the Session parameter of the Invoke-Command cmdlet. -For example, the following command uses the Invoke-Command cmdlet -to run a Get-Process command in the PSSessions on the Server01 -and Server02 computers. The command saves the processes in a $p -variable in each PSSession. +For example, the following command uses the Invoke-Command cmdlet to run a +Get-Process command in the PSSessions on the Server01 and Server02 computers. +The command saves the processes in a $p variable in each PSSession. +```powershell Invoke-Command -Session $s -ScriptBlock {$p = Get-Process} +``` -Because the PSSession uses a persistent connection, you can run -another command in the same PSSession that uses the $p variable. -The following command counts the number of processes saved in $p. +Because the PSSession uses a persistent connection, you can run another +command in the same PSSession that uses the $p variable. The following command +counts the number of processes saved in $p. +```powershell Invoke-Command -Session $s -ScriptBlock {$p.count} +``` -# HOW TO RUN A REMOTE COMMAND ON MULTIPLE COMPUTERS - +## HOW TO RUN A REMOTE COMMAND ON MULTIPLE COMPUTERS -To run a remote command on multiple computers, type all of -the computer names in the value of the ComputerName parameter of -Invoke-Command. Separate the names with commas. +To run a remote command on multiple computers, type all of the computer names +in the value of the ComputerName parameter of Invoke-Command. Separate the +names with commas. -For example, the following command runs a Get-Culture command -on three computers: +For example, the following command runs a Get-Culture command on three +computers: +```powershell Invoke-Command -ComputerName S1, S2, S3 -ScriptBlock {Get-Culture} +``` -You can also run a command in multiple PSSessions. The following -commands create PSSessions on the Server01, Server02, and Server03 -computers and then run a Get-Culture command in each of the PSSessions. +You can also run a command in multiple PSSessions. The following commands +create PSSessions on the Server01, Server02, and Server03 computers and then +run a Get-Culture command in each of the PSSessions. +```powershell $s = New-PSSession -ComputerName S1, S2, S3 Invoke-Command -Session $s -ScriptBlock {Get-Culture} +``` To include the local computer list of computers, type the name of the local computer, type a dot (.), or type "localhost". +```powershell Invoke-Command -ComputerName S1, S2, S3, localhost -ScriptBlock {Get-Culture} +``` -# HOW TO RUN A SCRIPT ON REMOTE COMPUTERS - +## HOW TO RUN A SCRIPT ON REMOTE COMPUTERS -To run a local script on remote computers, use the -FilePath parameter of Invoke-Command. +To run a local script on remote computers, use the FilePath parameter of +Invoke-Command. -For example, the following command runs the Sample.ps1 script -on the S1 and S2 computers: +For example, the following command runs the Sample.ps1 script on the S1 and S2 +computers: +```powershell Invoke-Command -ComputerName S1, S2 -FilePath C:\Test\Sample.ps1 +``` -The results of the script are returned to the local computer. You -do not need to copy any files. - -# HOW TO STOP A REMOTE COMMAND - +The results of the script are returned to the local computer. You do not need +to copy any files. -To interrupt a command, press CTRL+C. The interrupt request is -passed to the remote computer where it terminates the remote command. +## HOW TO STOP A REMOTE COMMAND -# FOR MORE INFORMATION +To interrupt a command, press CTRL+C. The interrupt request is passed to the +remote computer where it terminates the remote command. +## FOR MORE INFORMATION --- For information about the system requirements for remoting, -see about_Remote_Requirements. +- For information about the system requirements for remoting, see + [about_Remote_Requirements](about_Remote_Requirements.md). --- For help in formatting remote output, see about_Remote_Output. +- For help in formatting remote output, see [about_Remote_Output](about_Remote_Output.md). --- For information about how remoting works, how to manage remote -data, special configurations, security issues, and other frequently -asked questions, see about_Remote_FAQ. +- For information about how remoting works, how to manage remote data, special + configurations, security issues, and other frequently asked questions, see + [about_Remote_FAQ](about_Remote_FAQ.md). --- For help in resolving remoting errors, see about_Remote_Troubleshooting. +- For help in resolving remoting errors, see about_Remote_Troubleshooting. --- For information about PSSessions and persistent connections, see -about_PSSessions. +- For information about PSSessions and persistent connections, see + [about_PSSessions](about_PSSessions.md). --- For information about Windows PowerShell background jobs, see -about_Jobs. +- For information about Windows PowerShell background jobs, see [about_Jobs](about_Jobs.md). -# KEYWORDS +## KEYWORDS about_Remoting -# SEE ALSO +## SEE ALSO [about_PSSessions](about_PSSessions.md) @@ -237,9 +244,8 @@ about_Remoting [about_Remote_Variables](about_Remote_Variables.md) -Enter-PSSession - -Invoke-Command +[Enter-PSSession](../Enter-PSSession.md) -New-PSSession +[Invoke-Command](../Invoke-Command.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md index eda447268fcd..445c1fa6f6b9 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,77 +7,71 @@ title: about_Remote_Requirements --- # About Remote Requirements -## about_Remote_Requirements +## SHORT DESCRIPTION +Describes the system requirements and configuration requirements for running +remote commands in Windows PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes the system requirements and configuration requirements for -running remote commands in Windows PowerShell. - -# LONG DESCRIPTION - -This topic describes the system requirements, user requirements, and -resource requirements for establishing remote connections and running -remote commands in Windows PowerShell. It also provides instructions for -configuring remote operations. +This topic describes the system requirements, user requirements, and resource +requirements for establishing remote connections and running remote commands +in Windows PowerShell. It also provides instructions for configuring remote +operations. Note: Many cmdlets (including the Get-Service, Get-Process, Get-WMIObject, -Get-EventLog, and Get-WinEvent cmdlets) get objects from remote -computers by using Microsoft .NET Framework methods to retrieve the -objects. They do not use the Windows PowerShell remoting -infrastructure. The requirements in this document do not apply to -these cmdlets. +Get-EventLog, and Get-WinEvent cmdlets) get objects from remote computers by +using Microsoft .NET Framework methods to retrieve the objects. They do not +use the Windows PowerShell remoting infrastructure. The requirements in this +document do not apply to these cmdlets. -To find the cmdlets that have a ComputerName parameter but do not use -Windows PowerShell remoting, read the description of the ComputerName -parameter of the cmdlets. - -# SYSTEM REQUIREMENTS +To find the cmdlets that have a ComputerName parameter but do not use Windows +PowerShell remoting, read the description of the ComputerName parameter of the +cmdlets. +## SYSTEM REQUIREMENTS To run remote sessions on Windows PowerShell 3.0, the local and remote computers must have the following: --- Windows PowerShell 3.0 or later --- The Microsoft .NET Framework 4 or later --- Windows Remote Management 3.0 +- Windows PowerShell 3.0 or later +- The Microsoft .NET Framework 4 or later +- Windows Remote Management 3.0 -To run remote sessions on Windows PowerShell 2.0, the local and remote computers -must have the following: +To run remote sessions on Windows PowerShell 2.0, the local and remote +computers must have the following: --- Windows PowerShell 2.0 or later --- The Microsoft .NET Framework 2.0 or later --- Windows Remote Management 2.0 +- Windows PowerShell 2.0 or later +- The Microsoft .NET Framework 2.0 or later +- Windows Remote Management 2.0 -You can create remote sessions between computers running Windows PowerShell 2.0 -and Windows PowerShell 3.0. However, features that run only on Windows -PowerShell 3.0, such as the ability to disconnect and reconnect to sessions, are -available only when both computers are running Windows PowerShell 3.0. +You can create remote sessions between computers running Windows PowerShell +2.0 and Windows PowerShell 3.0. However, features that run only on Windows +PowerShell 3.0, such as the ability to disconnect and reconnect to sessions, +are available only when both computers are running Windows PowerShell 3.0. To find the version number of an installed version of Windows PowerShell, use the $PSVersionTable automatic variable. -Windows Remote Management (WinRM) 3.0 and Microsoft .NET Framework 4 are included -in Windows 8, Windows Server 2012, and newer releases of the Windows operating -system. WinRM 3.0 is included in Windows Management Framework 3.0 for older -operating systems. If the computer does not have the required version of -WinRM or the Microsoft .NET Framework, the installation fails. - -# USER PERMISSIONS +Windows Remote Management (WinRM) 3.0 and Microsoft .NET Framework 4 are +included in Windows 8, Windows Server 2012, and newer releases of the Windows +operating system. WinRM 3.0 is included in Windows Management Framework 3.0 +for older operating systems. If the computer does not have the required +version of WinRM or the Microsoft .NET Framework, the installation fails. +## USER PERMISSIONS To create remote sessions and run remote commands, by default, the current user must be a member of the Administrators group on the remote computer or provide the credentials of an administrator. Otherwise, the command fails. The permissions required to create sessions and run commands on a remote -computer (or in a remote session on the local computer) are established by -the session configuration (also known as an "endpoint") on the remote -computer to which the session connects. Specifically, the security -descriptor on the session configuration determines who has access to the -session configuration and who can use it to connect. +computer (or in a remote session on the local computer) are established by the +session configuration (also known as an "endpoint") on the remote computer to +which the session connects. Specifically, the security descriptor on the +session configuration determines who has access to the session configuration +and who can use it to connect. The security descriptors on the default session configurations, Microsoft.PowerShell, Microsoft.PowerShell32, and @@ -85,48 +79,50 @@ Microsoft.PowerShell.Workflow, allow access only to members of the Administrators group. If the current user doesn't have permission to use the session configuration, -the command to run a command (which uses a temporary session) or create -a persistent session on the remote computer fails. The user can use the +the command to run a command (which uses a temporary session) or create a +persistent session on the remote computer fails. The user can use the ConfigurationName parameter of cmdlets that create sessions to select a different session configuration, if one is available. Members of the Administrators group on a computer can determine who has permission to connect to the computer remotely by changing the security -descriptors on the default session configurations and by creating new -session configurations with different security descriptors. +descriptors on the default session configurations and by creating new session +configurations with different security descriptors. For more informations about session configurations, see -about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). +[about_Session_Configurations](about_Session_Configurations.md). -# WINDOWS NETWORK LOCATIONS +## WINDOWS NETWORK LOCATIONS Beginning in Windows PowerShell 3.0, the Enable-PSRemoting cmdlet can enable remoting on client and server versions of Windows on private, domain, and public networks. On server versions of Windows with private and domain networks, the -Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted -remote access. It also creates a firewall rule for public networks that -allows remote access only from computers in the same local subnet. This -local subnet firewall rule is enabled by default on server versions of -Windows on public networks, but Enable-PSRemoting reapplies the rule in -case it was changed or deleted. - -On client versions of Windows with private and domain networks, by -default, the Enable-PSRemoting cmdlet creates firewall rules that -allow unrestricted remote access. - -To enable remoting on client versions of Windows with public networks, -use the SkipNetworkProfileCheck parameter of the Enable-PSRemoting cmdlet. -It creates a firewall rule that that allows remote access only from -computers in the same local subnet. +Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted remote +access. It also creates a firewall rule for public networks that allows remote +access only from computers in the same local subnet. This local subnet +firewall rule is enabled by default on server versions of Windows on public +networks, but Enable-PSRemoting reapplies the rule in case it was changed or +deleted. + +On client versions of Windows with private and domain networks, by default, +the Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted +remote access. + +To enable remoting on client versions of Windows with public networks, use the +SkipNetworkProfileCheck parameter of the Enable-PSRemoting cmdlet. It creates +a firewall rule that that allows remote access only from computers in the same +local subnet. To remove the local subnet restriction on public networks and allow remote -access from all locations on client and server versions of Windows, use -the Set-NetFirewallRule cmdlet in the NetSecurity module. Run the following +access from all locations on client and server versions of Windows, use the +Set-NetFirewallRule cmdlet in the NetSecurity module. Run the following command: +```powershell Set-NetFirewallRule -Name "WINRM-HTTP-In-TCP-PUBLIC" -RemoteAddress Any +``` In Windows PowerShell 2.0, on server versions of Windows, Enable-PSRemoting creates firewall rules that permit remote access on all networks. @@ -134,64 +130,55 @@ creates firewall rules that permit remote access on all networks. In Windows PowerShell 2.0, on client versions of Windows, Enable-PSRemoting creates firewall rules only on private and domain networks. If the network location is public, Enable-PSRemoting fails. -# . - -# RUN AS ADMINISTRATOR +## RUN AS ADMINISTRATOR +Administrator privileges are required for the following remoting operations: -Administrator privileges are required for the following remoting -operations: +- Establishing a remote connection to the local computer. This is commonly + known as a "loopback" scenario. --- Establishing a remote connection to the local computer. This is -commonly known as a "loopback" scenario. +- Managing session configurations on the local computer. --- Managing session configurations on the local computer. +- Viewing and changing WS-Management settings on the local computer. These are + the settings in the LocalHost node of the WSMAN: drive. --- Viewing and changing WS-Management settings on the local computer. -These are the settings in the LocalHost node of the WSMAN: drive. +To perform these tasks, you must start Windows PowerShell with the "Run as +administrator" option even if you are a member of the Administrators group on +the local computer. -To perform these tasks, you must start Windows PowerShell with the "Run -as administrator" option even if you are a member of the Administrators -group on the local computer. - -In Windows 7 and in Windows Server 2008 R2, to start Windows PowerShell -with the "Run as administrator" option: +In Windows 7 and in Windows Server 2008 R2, to start Windows PowerShell with +the "Run as administrator" option: 1. Click Start, click All Programs, click Accessories, and then click -the Windows PowerShell folder. - -2. Right-click Windows PowerShell, and then click -"Run as administrator". + the Windows PowerShell folder. +2. Right-click Windows PowerShell, and then click "Run as administrator". To start Windows PowerShell with the "Run as administrator" option: -1. Click Start, click All Programs, and then click the Windows -PowerShell folder. +1. Click Start, click All Programs, and then click the Windows PowerShell + folder. +2. Right-click Windows PowerShell, and then click "Run as administrator". -2. Right-click Windows PowerShell, and then click -"Run as administrator". - -The "Run as administrator" option is also available in other Windows -Explorer entries for Windows PowerShell, including shortcuts. Just -right-click the item, and then click "Run as administrator". +The "Run as administrator" option is also available in other Windows Explorer +entries for Windows PowerShell, including shortcuts. Just right-click the +item, and then click "Run as administrator". When you start Windows PowerShell from another program such as Cmd.exe, use the "Run as administrator" option to start the program. -# HOW TO CONFIGURE YOUR COMPUTER FOR REMOTING - +## HOW TO CONFIGURE YOUR COMPUTER FOR REMOTING Computers running all supported versions of Windows can establish remote connections to and run remote commands in Windows PowerShell without any configuration. However, to receive connections, and allow users to create -local and remote user-managed Windows PowerShell sessions ("PSSessions") -and run commands on the local computer, you must enable Windows PowerShell +local and remote user-managed Windows PowerShell sessions ("PSSessions") and +run commands on the local computer, you must enable Windows PowerShell remoting on the computer. Windows Server 2012 and newer releases of Windows Server are enabled for -Windows PowerShell remoting by default. If the settings are changed, -you can restore the default settings by running the Enable-PSRemoting cmdlet. +Windows PowerShell remoting by default. If the settings are changed, you can +restore the default settings by running the Enable-PSRemoting cmdlet. On all other supported versions of Windows, you need to run the Enable-PSRemoting cmdlet to enable Windows PowerShell remoting. @@ -199,45 +186,43 @@ Enable-PSRemoting cmdlet to enable Windows PowerShell remoting. The remoting features of Windows PowerShell are supported by the WinRM service, which is the Microsoft implementation of the Web Services for Management (WS-Management) protocol. When you enable Windows PowerShell -remoting, you change the default configuration of WS-Management and add -system configuration that allow users to connect to WS-Management. +remoting, you change the default configuration of WS-Management and add system +configuration that allow users to connect to WS-Management. To configure Windows PowerShell to receive remote commands: -1. Start Windows PowerShell with the "Run as administrator" -option. - -2. At the command prompt, type: -Enable-PSRemoting +1. Start Windows PowerShell with the "Run as administrator" option. +2. At the command prompt, type: `Enable-PSRemoting` To verify that remoting is configured correctly, run a test command such as -the following command, which creates a remote session on the local -computer. +the following command, which creates a remote session on the local computer. +```powershell New-PSSession +``` -If remoting is configured correctly, the command will create a session on -the local computer and return an object that represents the session. The -output should resemble the following sample output: - -C:\PS> new-pssession +If remoting is configured correctly, the command will create a session on the +local computer and return an object that represents the session. The output +should resemble the following sample output: +```output Id Name ComputerName State ConfigurationName -- ---- ------------ ----- ----- 1 Session1 localhost Opened Microsoft.PowerShell +``` -If the command fails, for assistance, see about_Remote_Troubleshooting. +If the command fails, for assistance, see +[about_Remote_Troubleshooting](about_Remote_Troubleshooting.md). -# UNDERSTAND POLICIES +## UNDERSTAND POLICIES +When you work remotely, you use two instances of Windows PowerShell, one on +the local computer and one on the remote computer. As a result, your work is +affected by the Windows policies and the Windows PowerShell policies on the +local and remote computers. -When you work remotely, you use two instances of Windows PowerShell, one -on the local computer and one on the remote computer. As a result, your -work is affected by the Windows policies and the Windows PowerShell -policies on the local and remote computers. - -In general, before you connect and as you are establishing the connection, -the policies on the local computer are in effect. When you are using the +In general, before you connect and as you are establishing the connection, the +policies on the local computer are in effect. When you are using the connection, the policies on the remote computer are in effect. # SEE ALSO @@ -248,9 +233,8 @@ connection, the policies on the remote computer are in effect. [about_PSSessions](about_PSSessions.md) -Invoke-Command - -Enter-PSSession +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 33bf188649a7..cdd13115f8e0 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,108 +7,109 @@ title: about_Remote_Variables --- # About Remote Variables -## about_Remote_Variables +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use local and remote variables in remote commands. -Explains how to use local and remote variables in remote -commands. +## LONG DESCRIPTION -# LONG DESCRIPTION - -You can use variables in commands that you run on remote -computers. Simply assign a value to the variable and then -use the variable in place of the value. - -By default, the variables in remote commands are assumed -to be defined in the session in which the command runs. You -can also use variables that are defined in the local session, -but you must identify them as local -variables in the command. - -# USING REMOTE VARIABLES - - -Windows PowerShell assumes that the variables used in remote -commands are defined in the session in which the command runs. +You can use variables in commands that you run on remote computers. Simply +assign a value to the variable and then use the variable in place of the +value. -In the following example, the $ps variable is defined in the -temporary session in which the Get-WinEvent command runs. +By default, the variables in remote commands are assumed to be defined in the +session in which the command runs. You can also use variables that are defined +in the local session, but you must identify them as local variables in the +command. -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"; Get-WinEvent -LogName $ps} +## USING REMOTE VARIABLES -Similarly, when the command runs in a persistent session (PSSession), -the remote variable must be defined in the same PSSession. +Windows PowerShell assumes that the variables used in remote commands are +defined in the session in which the command runs. -PS C:> $s = New-PSSession -ComputerName S1 +In the following example, the \$ps variable is defined in the temporary session +in which the Get-WinEvent command runs. -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"} +```powershell +Invoke-Command -ComputerName S1 -ScriptBlock { + $ps = "Windows PowerShell"; Get-WinEvent -LogName $ps +} +``` -PS C:> Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $ps} +Similarly, when the command runs in a persistent session (PSSession), the +remote variable must be defined in the same PSSession. -# USING LOCAL VARIABLES +```powershell +$s = New-PSSession -ComputerName S1 +Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"} +Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $ps} +``` +## USING LOCAL VARIABLES -You can also use local variables in remote commands, but you must -indicate that the variable is defined in the local session. +You can also use local variables in remote commands, but you must indicate +that the variable is defined in the local session. -Beginning in Windows PowerShell 3.0, you can use the Using scope -modifier to identify a local variable in a remote command. +Beginning in Windows PowerShell 3.0, you can use the Using scope modifier to +identify a local variable in a remote command. The syntax of Using is as follows: -The syntax is: +``` $Using: +``` -In the following example, the $ps variable is created in the local -session, but is used in the session in which the command runs. The -Using scope modifier identifies $ps as a local variable. +In the following example, the $ps variable is created in the local session, +but is used in the session in which the command runs. The Using scope modifier +identifies $ps as a local variable. -PS C:> $ps = "Windows PowerShell" -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {Get-WinEvent -LogName $Using:ps} +```powershell +$ps = "Windows PowerShell" +Invoke-Command -ComputerName S1 -ScriptBlock { + Get-WinEvent -LogName $Using:ps +} +``` You can also use the Using scope modifier in PSSessions. -PS C:> $s = New-PSSession -ComputerName S1 - -PS C:> $ps = "Windows PowerShell" +```powershell +$s = New-PSSession -ComputerName S1 +$ps = "Windows PowerShell" +Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +``` -PS C:> Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +## USING LOCAL VARIABLES IN WINDOWS POWERSHELL 2.0 -# USING LOCAL VARIABLES IN WINDOWS POWERSHELL 2.0 +You can use local variables in a remote command by defining parameters for the +remote command and using the ArgumentList parameter of the Invoke-Command +cmdlet to specify the local variable as the parameter value. +This command format is valid on Windows PowerShell 2.0 and later versions of +Windows PowerShell. -You can use local variables in a remote command by defining parameters -for the remote command and using the ArgumentList parameter of the -Invoke-Command cmdlet to specify the local variable as the parameter -value. - -This command format is valid on Windows PowerShell 2.0 and later versions -of Windows PowerShell. +- Use the param keyword to define parameters for the remote command. The + parameter names are placeholders that do not need to match the name of the + local variable. --- Use the param keyword to define parameters for the remote command. -The parameter names are placeholders that do not need to match the -name of the local variable. +- Use the parameters defined by the param keyword in the command. --- Use the parameters defined by the param keyword in the command. - --- Use the ArgumentList parameter of the Invoke-Command cmdlet to -specify the local variable as the parameter value. +- Use the ArgumentList parameter of the Invoke-Command cmdlet to specify the + local variable as the parameter value. For example, the following commands define the $ps variable in the local -session and then use it in a remote command. The command uses $log as -the parameter name and the local variable, $ps, as its value. - -C:\PS>$ps = "Windows PowerShell" +session and then use it in a remote command. The command uses $log as the +parameter name and the local variable, $ps, as its value. -C:\PS>Invoke-Command -ComputerName S1 -ScriptBlock {param($log) Get-WinEvent -logname $log} -ArgumentList $ps +```powershell +$ps = "Windows PowerShell" +Invoke-Command -ComputerName S1 -ScriptBlock { + param($log) + Get-WinEvent -logname $log +} -ArgumentList $ps +``` -# KEYWORDS - -about_Using - -# SEE ALSO +## SEE ALSO [about_Remote](about_Remote.md) @@ -116,9 +117,8 @@ about_Using [about_Scopes](about_Scopes.md) -Enter-PSSession - -Invoke-Command +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Requires.md index 4ae85a982fc2..c2e71e2f1753 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Requires.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -145,5 +145,4 @@ always a snap-in. [about_PSSnapins](about_PSSnapins.md) -Get-PSSnapin - +[Get-PSSnapin](../Get-PSSnapin.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Reserved_Words.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Reserved_Words.md index 874a7e5fd8a1..4c2f92e8b5fc 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Reserved_Words.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Reserved_Words.md @@ -70,8 +70,8 @@ Get-Help ## SEE ALSO - [about_Command_Syntax](about_Command_Syntax.md) -- [about_Special_Characters](about_Special_Characters.md) - [about_Language_Keywords](about_Language_Keywords.md) - [about_Parsing](about_Parsing.md) - [about_Quoting_Rules](about_Quoting_Rules.md) - [about_Script_Blocks](about_Script_Blocks.md) +- [about_Special_Characters](about_Special_Characters.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Return.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Return.md index 3f09476c754f..bcb1e40e8d25 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Return.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Return.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,118 +7,115 @@ title: about_Return --- # About Return -## about_Return - ## SHORT DESCRIPTION -Exits the current scope, which can be a function, script, or script block. +Exits the current scope, which can be a function, script, or script block. ## LONG DESCRIPTION -The Return keyword exits a function, script, or script block. It can be used to exit a scope at a specific point, to return a value, or to indicate that the end of the scope has been reached. -Users who are familiar with languages like C or C\# might want to use the Return keyword to make the logic of leaving a scope explicit. + The Return keyword exits a function, script, or script block. It can be used + to exit a scope at a specific point, to return a value, or to indicate that + the end of the scope has been reached. -In Windows PowerShell®, the results of each statement are returned as output, even without a statement that contains the Return keyword. Languages like C or C\# return only the value or values that are specified by the Return keyword. +Users who are familiar with languages like C or C\# might want to use the +Return keyword to make the logic of leaving a scope explicit. +In PowerShell, the results of each statement are returned as output, +even without a statement that contains the Return keyword. Languages like C or +C\# return only the value or values that are specified by the Return keyword. ### SYNTAX -The syntax for the Return keyword is as follows: +The syntax for the Return keyword is as follows: ``` return [] ``` - -The Return keyword can appear alone, or it can be followed by a value or expression, as follows: - +The Return keyword can appear alone, or it can be followed by a value or +expression, as follows: ``` -return -return $a +return +return $a return (2 + $a) ``` - ### EXAMPLES -The following example uses the Return keyword to exit a function at a specific point if a conditional is met: +The following example uses the Return keyword to exit a function at a specific +point if a conditional is met: ``` -function ScreenPassword($instance) -{ - if (!($instance.screensaversecure)) {return $instance.name} - -} - +function ScreenPassword($instance) +{ + if (!($instance.screensaversecure)) {return $instance.name} + +} + foreach ($a in @(get-wmiobject win32_desktop)) { ScreenPassword($a) } ``` +This script checks each user account. The ScreenPassword function returns the +name of any user account that does not have a password-protected screen saver. +If the screen saver is password protected, the function completes any other +statements to be run, and PowerShell does not return any value. -This script checks each user account. The ScreenPassword function returns the name of any user account that does not have a password-protected screen saver. If the screen saver is password protected, the function completes any other statements to be run, and Windows PowerShell does not return any value. - -In Windows PowerShell, values can be returned even if the Return keyword is not used. The results of each statement are returned. For example, the following statements return the value of the $a variable: - +In PowerShell, values can be returned even if the Return keyword is not used. +The results of each statement are returned. For example, the following +statements return the value of the \$a variable: ``` -$a +$a return ``` - The following statement also returns the value of $a: - ``` return $a ``` +The following example includes a statement intended to let the user know that +the function is performing a calculation: -The following example includes a statement intended to let the user know that the function is performing a calculation: +```powershell +function calculation { + param ($value) - -``` -function calculation { - param ($value) - - "Please wait. Working on calculation..." - $value += 73 - return $value - } + "Please wait. Working on calculation..." + $value += 73 + return $value +} ``` +Running this function and assigning the result to a variable has the following +effect: -Running this function and assigning the result to a variable has the following effect: - - -``` -C:\PS> $a = calculation 14 -C:\PS> +```powershell +$a = calculation 14 ``` +The "Please wait. Working on calculation..." string is not displayed. Instead, +it is assigned to the $a variable, as in the following example: -The "Please wait. Working on calculation..." string is not displayed. Instead, it is assigned to the $a variable, as in the following example: - - -``` -C:\PS> $a -Please wait. Working on calculation... +```output +C:\PS> $a +Please wait. Working on calculation... 87 ``` - -Both the informational string and the result of the calculation are returned by the function and assigned to the $a variable. - +Both the informational string and the result of the calculation are returned +by the function and assigned to the \$a variable. ## SEE ALSO -Exit keyword in about_Language_Keywords +[about_Language_Keywords](about_Language_Keywords.md) [about_Functions](about_Functions.md) [about_Scopes](about_Scopes.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md index 43445a359c43..2e47af3dba57 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,62 +7,56 @@ title: about_Run_With_PowerShell --- # About Run With PowerShell -## about_Run_With_PowerShell +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use the "Run with PowerShell" feature to run a script from a +file system drive. -Explains how to use the "Run with PowerShell" feature to run -a script from a file system drive. +## LONG DESCRIPTION -# LONG DESCRIPTION +Beginning in Windows PowerShell 3.0, you can use the "Run with PowerShell" +feature to run scripts from File Explorer in Windows 8 and Windows Server 2012 +and from Windows Explorer in earlier versions of Windows. -Beginning in Windows PowerShell 3.0, you can use the "Run with -PowerShell" feature to run scripts from File Explorer in Windows 8 -and Windows Server 2012 and from Windows Explorer in earlier -versions of Windows. +The "Run with PowerShell" feature is designed to run scripts that do not have +required parameters and do not return output to the command prompt. -The "Run with PowerShell" feature is designed to run scripts -that do not have required parameters and do not return output -to the command prompt. - -When you use the "Run with PowerShell" feature, the Windows -PowerShell console window appears only briefly, if at all. -You cannot interact with it. +When you use the "Run with PowerShell" feature, the Windows PowerShell console +window appears only briefly, if at all. You cannot interact with it. To use the "Run with PowerShell" feature: -In File Explorer (or Windows Explorer), right-click the -script file name and then select "Run with PowerShell". +In File Explorer (or Windows Explorer), right-click the script file name and +then select "Run with PowerShell". -The "Run with PowerShell" feature starts a Windows PowerShell -session that has an execution policy of Bypass, runs the -script, and closes the session. +The "Run with PowerShell" feature starts a Windows PowerShell session that has +an execution policy of Bypass, runs the script, and closes the session. It runs a command that has the following format: + +``` PowerShell.exe -File -ExecutionPolicy Bypass +``` -"Run with PowerShell" sets the Bypass execution policy only -for the session (the current instance of the PowerShell process) -in which the script runs. This feature does not change the execution -policy for the computer or the user. +"Run with PowerShell" sets the Bypass execution policy only for the session +(the current instance of the PowerShell process) in which the script runs. +This feature does not change the execution policy for the computer or the +user. -The "Run with PowerShell" feature is affected only by the AllSigned -execution policy. If the AllSigned execution policy is effective for -the computer or the user, "Run with PowerShell" runs only signed -scripts. "Run with PowerShell" is not affected by any other execution -policy. For more information, see about_Execution_Policies. +The "Run with PowerShell" feature is affected only by the AllSigned execution +policy. If the AllSigned execution policy is effective for the computer or the +user, "Run with PowerShell" runs only signed scripts. "Run with PowerShell" is +not affected by any other execution policy. For more information, see +[about_Execution_Policies](about_Execution_Policies.md). -Troubleshooting Note: Run with PowerShell command might prompt you -to confirm the execution policy change. +Troubleshooting Note: Run with PowerShell command might prompt you to confirm +the execution policy change. -# SEE ALSO +## SEE ALSO [about_Execution_Policies](about_Execution_Policies.md) [about_Group_Policy_Settings](about_Group_Policy_Settings.md) [about_Scripts](about_Scripts.md) - -"Running Scripts" (http://go.microsoft.com/fwlink/?LinkId=257680) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md index a4409d59d90f..06219eb3961e 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,63 +10,63 @@ title: about_Script_Internationalization ## Short Description -Describes the script internationalization features that make it easy for scripts to display -messages and instructions to users in their user interface (UI) language. +Describes the script internationalization features that make it easy for +scripts to display messages and instructions to users in their user interface +(UI) language. ## Long Description The Windows PowerShell script internationalization features allow you to -better serve users throughout the world by displaying Help and user -messages for scripts and functions in the user's UI language. +better serve users throughout the world by displaying Help and user messages +for scripts and functions in the user's UI language. -The script internationalization features query the UI culture of the -operating system during execution, import the appropriate -translated text strings, and display them to the user. The Data section -lets you store text strings separate from code so they are easily -identified and extracted. A new cmdlet, `ConvertFrom-StringData`, -converts text strings into dictionary-like hash tables to facilitate -translation. +The script internationalization features query the UI culture of the operating +system during execution, import the appropriate translated text strings, and +display them to the user. The Data section lets you store text strings +separate from code so they are easily identified and extracted. A new cmdlet, +`ConvertFrom-StringData`, converts text strings into dictionary-like hash +tables to facilitate translation. -To support international Help text, Windows PowerShell includes the -following features: +To support international Help text, Windows PowerShell includes the following +features: -* A Data section that separates text strings from code instructions. For -more information about the Data section, see [about_Data_Sections](about_Data_Sections.md). +* A Data section that separates text strings from code instructions. For more + information about the Data section, see + [aout_Data_Sections](about_Data_Sections.md). -* New automatic variables, $PSCulture and $PSUICulture. $PSCulture stores -the name of the UI language used on the system for elements such as -the date, time, and currency. The $PSUICulture variable stores the -name of the UI language used on the system for user interface elements -such as menus and text strings. +* New automatic variables, \$PSCulture and \$PSUICulture. \$PSCulture stores the + name of the UI language used on the system for elements such as the date, + time, and currency. The $PSUICulture variable stores the name of the UI + language used on the system for user interface elements such as menus and text + strings. * A cmdlet, `ConvertFrom-StringData`, that converts text strings into -dictionary-like hash tables to facilitate translation. For more -information, see [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md). + dictionary-like hash tables to facilitate translation. For more information, + see [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md). -* A new file type, .psd1, that stores translated text strings. The .psd1 -files are stored in language-specific subdirectories of the script -directory. +* A new file type, .psd1, that stores translated text strings. The .psd1 files + are stored in language-specific subdirectories of the script directory. -* A cmdlet, `Import-LocalizedData`, that imports translated text strings -for a specified language into a script at runtime. This cmdlet recognizes -and imports strings in any Windows-supported language. For more -information see [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md). +* A cmdlet, `Import-LocalizedData`, that imports translated text strings for a + specified language into a script at runtime. This cmdlet recognizes and + imports strings in any Windows-supported language. For more information see + [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md). ### The Data Section: Storing Default Strings -Use a Data section in the script to store the text strings in the default language. -Arrange the strings in key/value pairs in a here-string. Each key/value pair must -be on a separate line. If you include comments, the comments must be on separate -lines. +Use a Data section in the script to store the text strings in the default +language. Arrange the strings in key/value pairs in a here-string. Each +key/value pair must be on a separate line. If you include comments, the +comments must be on separate lines. -The `ConvertFrom-StringData` cmdlet converts the key/value pairs in the here-string -into a dictionary-like hash table that is stored in the value of the Data section -variable. +The `ConvertFrom-StringData` cmdlet converts the key/value pairs in the +here-string into a dictionary-like hash table that is stored in the value of +the Data section variable. In the following example, the Data section of the World.ps1 script includes the English-United States (en-US) set of prompt messages for a script. The -`ConvertFrom-StringData` cmdlet converts the strings into a hash table and stores -them in the $msgtable variable. +`ConvertFrom-StringData` cmdlet converts the strings into a hash table and +stores them in the $msgtable variable. ```powershell $msgTable = Data { @@ -79,21 +79,22 @@ $msgTable = Data { } ``` -For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). ### PSD1 Files: Storing Translated Strings -Save the script messages for each UI language in separate text files with -the same name as the script and the .psd1 file name extension. Store the files -in subdirectories of the script directory with names of cultures in the following +Save the script messages for each UI language in separate text files with the +same name as the script and the .psd1 file name extension. Store the files in +subdirectories of the script directory with names of cultures in the following format: \-\ Examples: de-DE, ar-SA, and zh-Hans -For example, if the World.ps1 script is stored in the C:\Scripts directory, you -would create a file directory structure that resembles the following: +For example, if the World.ps1 script is stored in the C:\Scripts directory, +you would create a file directory structure that resembles the following: ``` C:\Scripts @@ -104,8 +105,8 @@ C:\Scripts\zh-CN\World.psd1 ... ``` -The World.psd1 file in the de-DE subdirectory of the script directory -might include the following statement: +The World.psd1 file in the de-DE subdirectory of the script directory might +include the following statement: ```powershell ConvertFrom-StringData -StringData @' @@ -115,8 +116,8 @@ promptMsg = Please enter your user name (in German). '@ ``` -Similarly, the World.psd1 file in the ar-SA subdirectory of the script directory -might includes the following statement: +Similarly, the World.psd1 file in the ar-SA subdirectory of the script +directory might includes the following statement: ```powershell ConvertFrom-StringData -StringData @' @@ -128,70 +129,63 @@ promptMsg = Please enter your user name (in Arabic). ### Import-LocalizedData: Dynamic Retrieval of Translated Strings -To retrieve the strings in the UI language of the current user, use -the `Import-LocalizedData` cmdlet. +To retrieve the strings in the UI language of the current user, use the +`Import-LocalizedData` cmdlet. -`Import-LocalizedData` finds the value of the $PSUICulture automatic -variable and imports the content of the \.psd1 files in -the subdirectory that matches the $PSUICulture value. Then, it saves -the imported content in the variable specified by the value of the -**BindingVariable** parameter. +`Import-LocalizedData` finds the value of the \$PSUICulture automatic variable +and imports the content of the \.psd1 files in the subdirectory +that matches the \$PSUICulture value. Then, it saves the imported content in +the variable specified by the value of the **BindingVariable** parameter. ```powershell Import-LocalizedData -BindingVariable msgTable ``` For example, if the `Import-LocalizedData` command appears in the -C:\Scripts\World.ps1 script and the value of $PSUICulture is -"ar-SA", `Import-LocalizedData` finds the following file: +C:\\Scripts\\World.ps1 script and the value of $PSUICulture is "ar-SA", +`Import-LocalizedData` finds the following file: -C:\Scripts\ar-SA\World.psd1 +C:\\Scripts\\ar-SA\\World.psd1 -Then, it imports the Arabic text strings from the file into -the $msgTable variable, replacing any default strings that might -be defined in the Data section of the World.ps1 script. +Then, it imports the Arabic text strings from the file into the $msgTable +variable, replacing any default strings that might be defined in the Data +section of the World.ps1 script. -As a result, when the script uses the $msgTable variable -to display user messages, the messages are displayed in -Arabic. +As a result, when the script uses the $msgTable variable to display user +messages, the messages are displayed in Arabic. -For example, the following script displays the "Please enter your user -name" message in Arabic: +For example, the following script displays the "Please enter your user name" +message in Arabic: ```powershell if (!($username)) { $msgTable.promptMsg } ``` -If `Import-LocalizedData` cannot find a .psd1 file that matches the -value of $PSUIculture, the value of $msgTable is not replaced, -and the call to $msgTable.promptMsg displays the fallback en-US -strings. +If `Import-LocalizedData` cannot find a .psd1 file that matches the value of +\$PSUIculture, the value of \$msgTable is not replaced, and the call to +\$msgTable.promptMsg displays the fallback en-US strings. ## Examples -This example shows how the script internationalization features -are used in a script to display a day of the week to users -in the language that is set on the computer. +This example shows how the script internationalization features are used in a +script to display a day of the week to users in the language that is set on +the computer. -The following is a complete listing of the Sample1.ps1 script -file. +The following is a complete listing of the Sample1.ps1 script file. -The script begins with a Data section named Day ($Day) that -contains a `ConvertFrom-StringData` command. The expression -submitted to `ConvertFrom-StringData` is a here-string that -contains the day names in the default UI culture, en-US, in -key/value pairs. The `ConvertFrom-StringData` cmdlet converts -the key/value pairs in the here-string into a hash table and +The script begins with a Data section named Day ($Day) that contains a +`ConvertFrom-StringData` command. The expression submitted to +`ConvertFrom-StringData` is a here-string that contains the day names in the +default UI culture, en-US, in key/value pairs. The `ConvertFrom-StringData` +cmdlet converts the key/value pairs in the here-string into a hash table and then saves it in the value of the $Day variable. -The `Import-LocalizedData` command imports the contents of the -.psd1 file in the directory that matches the value of the -$PSUICulture automatic variable and then saves it in the $Day -variable, replacing the values of $Day that are defined in the -Data section. +The `Import-LocalizedData` command imports the contents of the .psd1 file in +the directory that matches the value of the $PSUICulture automatic variable +and then saves it in the $Day variable, replacing the values of $Day that are +defined in the Data section. -The remaining commands load the strings into an array and display -them. +The remaining commands load the strings into an array and display them. ```powershell $Day = Data { @@ -239,10 +233,10 @@ ConvertFrom-StringData @' '@ ``` -As a result, when you run Sample.ps1 on a system on which the value -of $PSUICulture is de-DE, the output of the script is: +As a result, when you run Sample.ps1 on a system on which the value of +\$PSUICulture is de-DE, the output of the script is: -``` +```output Today is Friday (in German) ``` @@ -254,4 +248,3 @@ Today is Friday (in German) * [about_Quoting_Rules](about_Quoting_Rules.md) * [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md) * [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md index fe470e6bc5b4..f181e4eac313 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,284 +7,296 @@ title: about_Session_Configuration_Files --- # About Session Configuration Files -## about_Session_Configuration_Files +## SHORT DESCRIPTION +Describes session configuration files, which are used in a session +configuration (also known as an "endpoint") to define the environment of +sessions that use the session configuration. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes session configuration files, which are used in a -session configuration (also known as an "endpoint") to define the -environment of sessions that use the session configuration. - -# LONG DESCRIPTION - -A "session configuration file" is a text file with a .pssc file -name extension that contains a hash table of session configuration -properties and values. You can use a session configuration file to -set the properties of a session configuration. Doing so defines -the environment of any Windows PowerShell sessions that use that -session configuration. +A "session configuration file" is a text file with a .pssc file name extension +that contains a hash table of session configuration properties and values. You +can use a session configuration file to set the properties of a session +configuration. Doing so defines the environment of any Windows PowerShell +sessions that use that session configuration. Session configuration files make it easy to create custom session configurations without using complex C# assemblies or scripts. -A "session configuration" or "endpoint" is a collection of local -computer settings that determine such things as which users can -create sessions on the computer; which commands users can run in -those sessions; and whether the session should run as a privileged -virtual account. For more information about session configurations, -see about_Session_Configurations -(http://go.microsoft.com/fwlink/?LinkID=145152). - -Session configurations were introduced in Windows PowerShell 2.0, -and session configuration files were introduced in Windows -PowerShell 3.0. You must use Windows PowerShell 3.0 to include a -session configuration file in a session configuration. However, -users of Windows PowerShell 2.0 (and later) are affected by the -settings in the session configuration. - -Creating Custom Sessions -You can customize many features of a Windows PowerShell session -by specifying session properties in a session configuration. You -can customize a session by writing a C# program that defines a -custom runspace, or you can use a session configuration file to -define the properties of sessions created by using the session -configuration. As a general rule, it is easier to use the session +A "session configuration" or "endpoint" is a collection of local computer +settings that determine such things as which users can create sessions on the +computer; which commands users can run in those sessions; and whether the +session should run as a privileged virtual account. For more information about +session configurations, see [about_Session_Configurations](about_Session_Configurations.md). + +Session configurations were introduced in Windows PowerShell 2.0, and session +configuration files were introduced in Windows PowerShell 3.0. You must use +Windows PowerShell 3.0 to include a session configuration file in a session +configuration. However, users of Windows PowerShell 2.0 (and later) are +affected by the settings in the session configuration. + +## Creating Custom Sessions + +You can customize many features of a Windows PowerShell session by specifying +session properties in a session configuration. You can customize a session by +writing a C# program that defines a custom runspace, or you can use a session +configuration file to define the properties of sessions created by using the +session configuration. As a general rule, it is easier to use the session configuration file than to write a C# program. You can use a session configuration file to create items such as -fully-functioning sessions for highly trusted users; locked-down -sessions that allow minimal access; sessions designed for -particular and that contain only the modules required for those -tasks; and sessions where unprivileged users can only run -specific commands as a privileged account. - -In addition to that, you can manage whether users of the -session can use Windows PowerShell language elements such as -script blocks, or whether they can only run commands. You can -manage the version of Windows PowerShell users can run in the -session; manage which modules are imported into the session; and -manage which cmdlets, functions, and aliases session users can -run. When using the RoleDefinitions field, you can give users -different capabilities in the session based on group membership. - -For more information about RoleDefinitions and how to define this -Value, see the help topic for the New-PSRoleCapabilityFile -Cmdlet. - -Creating a Session Configuration File -The easiest way to create a session configuration file is by -using the New-PSSessionConfigurationFile cmdlet. This cmdlet -generates a file that uses the correct syntax and format, and -that automatically verifies many of the configuration file -property values. - -For detailed descriptions of the properties that you can set in -a session configuration file, see the help topic for the -New-PSSessionConfigurationFile cmdlet. - -The following command creates a session configuration file that -uses the default values. The resulting configuration file uses only -the default values because no parameters other than the Path -parameter (which specifies the file path) are included: - -PS C:> New-PSSessionConfigurationFile -Path .\Defaults.pssc - -To view the new configuration file in your default text editor, -use the following command: - -PS C:> Invoke-Item -Path .\Defaults.pssc - -To create a session configuration for sessions in which -user can run commands, but not use other elements of the Windows -PowerShell language, type: - -PS C:> New-PSSessionConfigurationFile -LanguageMode NoLanguage +fully-functioning sessions for highly trusted users; locked-down sessions that +allow minimal access; sessions designed for particular and that contain only +the modules required for those tasks; and sessions where unprivileged users +can only run specific commands as a privileged account. + +In addition to that, you can manage whether users of the session can use +Windows PowerShell language elements such as script blocks, or whether they +can only run commands. You can manage the version of Windows PowerShell users +can run in the session; manage which modules are imported into the session; +and manage which cmdlets, functions, and aliases session users can run. When +using the RoleDefinitions field, you can give users different capabilities in +the session based on group membership. + +For more information about RoleDefinitions and how to define this Value, see +the help topic for the New-PSRoleCapabilityFile Cmdlet. + +## Creating a Session Configuration File + +The easiest way to create a session configuration file is by using the +New-PSSessionConfigurationFile cmdlet. This cmdlet generates a file that uses +the correct syntax and format, and that automatically verifies many of the +configuration file property values. + +For detailed descriptions of the properties that you can set in a session +configuration file, see the help topic for the New-PSSessionConfigurationFile +cmdlet. + +The following command creates a session configuration file that uses the +default values. The resulting configuration file uses only the default values +because no parameters other than the Path parameter (which specifies the file +path) are included: + +```powershell +New-PSSessionConfigurationFile -Path .\Defaults.pssc +``` + +To view the new configuration file in your default text editor, use the +following command: + +```powershell +Invoke-Item -Path .\Defaults.pssc +``` + +To create a session configuration for sessions in which user can run commands, +but not use other elements of the Windows PowerShell language, type: + +```powershell +New-PSSessionConfigurationFile -LanguageMode NoLanguage -Path .\NoLanguage.pssc +``` -In the preceding command, setting the LanguageMode parameter to -NoLanguage prevents users from doing such things as writing or -running scripts, or using variables. +In the preceding command, setting the LanguageMode parameter to NoLanguage +prevents users from doing such things as writing or running scripts, or using +variables. -To create a session configuration for sessions in which users can -use only Get cmdlets, type: +To create a session configuration for sessions in which users can use only Get +cmdlets, type: -PS C:> New-PSSessionConfigurationFile -VisibleCmdlets Get-* +```powershell +New-PSSessionConfigurationFile -VisibleCmdlets Get-* -Path .\GetSessions.pssc +``` -In the preceding example, setting the VisibleCmdlets parameter to -Get-* limits users to cmdlets that have names that start with the -string value "Get-". +In the preceding example, setting the VisibleCmdlets parameter to Get-* limits +users to cmdlets that have names that start with the string value "Get-". -To create a session configuration for sessions that run under a -privileged virtual account instead of the user's credentials, type: +To create a session configuration for sessions that run under a privileged +virtual account instead of the user's credentials, type: -PS C:> New-PSSessionConfigurationFile -RunAsVirtualAccount +```powershell +New-PSSessionConfigurationFile -RunAsVirtualAccount -Path .\VirtualAccount.pssc +``` -To create a session configuration for sessions in which the -commands visible to the user are specified in a role capabilities -file, type: +To create a session configuration for sessions in which the commands visible +to the user are specified in a role capabilities file, type: -PS C:> New-PSSessionConfigurationFile -RoleDefinitions +```powershell +New-PSSessionConfigurationFile -RoleDefinitions @{ 'CONTOSO\User' = @{ RoleCapabilities = 'Maintenance' }} -Path .\Maintenance.pssc +``` -Using a Session Configuration File -You can include a session configuration file when you create a -session configuration or add you can add a file to the session -configuration at a later time. +### Using a Session Configuration File -To include a session configuration file when creating a session -configuration, use the Path parameter of the -Register-PSSessionConfiguration cmdlet. +You can include a session configuration file when you create a session +configuration or add you can add a file to the session configuration at a +later time. -For example, the following command uses the NoLanguage.pssc file -when it creates a NoLanguage session configuration. +To include a session configuration file when creating a session configuration, +use the Path parameter of the Register-PSSessionConfiguration cmdlet. -PS C:> Register-PSSessionConfiguration -Name NoLanguage +For example, the following command uses the NoLanguage.pssc file when it +creates a NoLanguage session configuration. + +```powershell +Register-PSSessionConfiguration -Name NoLanguage -Path .\NoLanguage.pssc +``` -When a new NoLanguage session starts, users will only have access -to Windows PowerShell commands. +When a new NoLanguage session starts, users will only have access to Windows +PowerShell commands. -To add a session configuration file to an existing session -configuration, use the Set-PSSessionConfiguration cmdlet and the -Path parameter. This affects any new sessions created with the -specified session configuration. Note that the -Set-PSSessionConfiguration cmdlet changes the session itself and -does not modify the session configuration file. +To add a session configuration file to an existing session configuration, use +the Set-PSSessionConfiguration cmdlet and the Path parameter. This affects any +new sessions created with the specified session configuration. Note that the +Set-PSSessionConfiguration cmdlet changes the session itself and does not +modify the session configuration file. -For example, the following command adds the NoLanguage.pssc file -to the LockedDown session configuration. +For example, the following command adds the NoLanguage.pssc file to the +LockedDown session configuration. -PS C:> Set-PSSessionConfiguration -Name LockedDown +```powershell +Set-PSSessionConfiguration -Name LockedDown -Path .\NoLanguage.pssc +``` -When users use the LockedDown session configuration to create a -session, they will be able to run cmdlets but they will not be -able to create or use variables, assign values, or use other -Windows PowerShell language elements. +When users use the LockedDown session configuration to create a session, they +will be able to run cmdlets but they will not be able to create or use +variables, assign values, or use other Windows PowerShell language elements. -The following command uses the New-PSSession cmdlet to create a -session on the computer Srv01 that uses the LockedDown session -configuration, saving an object reference to the session in the $s -variable. The ACL (access control list) of the session -configuration determines who can use it to create a session. +The following command uses the New-PSSession cmdlet to create a session on the +computer Srv01 that uses the LockedDown session configuration, saving an +object reference to the session in the $s variable. The ACL (access control +list) of the session configuration determines who can use it to create a +session. -PS C:> $s = New-PSSession -ComputerName Srv01 +```powershell +$s = New-PSSession -ComputerName Srv01 -ConfigurationName LockedDown - -Because the NoLanguage constraints were added to the LockedDown -session configuration, users in LockedDown sessions will only be -able to run Windows PowerShell commands and cmdlets. For example, -the following two commands use the Invoke-Command cmdlet to run -commands in the session referenced in the $s variable. The first -command, which runs the Get-UICulture cmdlet and does not use any -variables, succeeds. The second command, which gets the value of -the $PSUICulture variable, fails. - -PS C:> Invoke-Command -Session $s {Get-UICulture} +``` + +Because the NoLanguage constraints were added to the LockedDown session +configuration, users in LockedDown sessions will only be able to run Windows +PowerShell commands and cmdlets. For example, the following two commands use +the Invoke-Command cmdlet to run commands in the session referenced in the $s +variable. The first command, which runs the Get-UICulture cmdlet and does not +use any variables, succeeds. The second command, which gets the value of the +$PSUICulture variable, fails. + +``` +Invoke-Command -Session $s {Get-UICulture} en-US -PS C:> Invoke-Command -Session $s {$PSUICulture} +Invoke-Command -Session $s {$PSUICulture} The syntax is not supported by this runspace. This might be because it is in no-language mode. + CategoryInfo : ParserError: ($PSUICulture:String) [], ParseException + FullyQualifiedErrorId : ScriptsNotAllowed +``` + +## Editing a Session Configuration File -Editing a Session Configuration File -All settings in a session configuration except for -RunAsVirtualAccount and RunAsVirtualAccountGroups can be modified -by editing the session configuration file used by the session -configuration. To do this, begin by locating the active copy of the -session configuration file. +All settings in a session configuration except for RunAsVirtualAccount and +RunAsVirtualAccountGroups can be modified by editing the session configuration +file used by the session configuration. To do this, begin by locating the +active copy of the session configuration file. -When you use a session configuration file in a session -configuration, Windows PowerShell creates an active copy of the -session configuration file and stores it in the -$pshome\SessionConfig directory on the local computer. +When you use a session configuration file in a session configuration, Windows +PowerShell creates an active copy of the session configuration file and stores +it in the \$pshome\\SessionConfig directory on the local computer. -The location of the active copy of a session configuration file is -stored in the ConfigFilePath property of the session configuration -object. +The location of the active copy of a session configuration file is stored in +the ConfigFilePath property of the session configuration object. -The following command gets the location of the session -configuration file for the NoLanguage session configuration. +The following command gets the location of the session configuration file for +the NoLanguage session configuration. -PS C:> (Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath +```powershell +(Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath +``` That command returns a file path similar to the following: +``` C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc +``` + +You can edit the .pssc file in any text editor. After the file is saved it +will be employed by any new sessions that use the session configuration. -You can edit the .pssc file in any text editor. After the file is -saved it will be employed by any new sessions that use the session -configuration. +If you need to modify the RunAsVirtualAccount or the RunAsVirtualAccountGroups +settings, you must un-register the session configuration and re-register a +session configuration file that includes the edited values. -If you need to modify the RunAsVirtualAccount or the -RunAsVirtualAccountGroups settings, you must un-register the -session configuration and re-register a session configuration file -that includes the edited values. +## Testing a Session Configuration File -Testing a Session Configuration File -Use the Test-PSSessionConfigurationFile cmdlet to test manually -edited session configuration files. That's important: if the file -syntax and values are not valid users will not be able to use the -session configuration to create a session. +Use the Test-PSSessionConfigurationFile cmdlet to test manually edited session +configuration files. That's important: if the file syntax and values are not +valid users will not be able to use the session configuration to create a +session. -For example, the following command tests the active session -configuration file of the NoLanguage session configuration. +For example, the following command tests the active session configuration file +of the NoLanguage session configuration. -PS C:> Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\ +```powershell +Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\ WindowsPowerShell\v1.0\SessionConfig\ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc +``` If the syntax and values in the configuration file are valid -Test-PSSessionConfigurationFile returns True. If the syntax and -values are not valid then the cmdlet returns False. - -You can use Test-PSSessionConfigurationFile to test any session -configuration file, including files that the -New-PSSessionConfiguration cmdlet creates. For more information, -see the help topic for the Test-PSSessionConfigurationFile cmdlet. - -Removing a Session Configuration File -You cannot remove a session configuration file from a session -configuration. However, you can replace the file with a new file -that uses the default settings. This effectively cancels the -settings used by the original configuration file. - -To replace a session configuration file, create a new session -configuration file that uses the default settings, then use the -Set-PSSessionConfiguration cmdlet to replace the custom session -configuration file with the new file. - -For example, the following commands create a Default session -configuration file and then replace the active session -configuration file in the NoLanguage session configuration. - -PS C:> New-PSSessionConfigurationFile -Path .\Default.pssc -PS C:> Set-PSSessionConfiguration -Name NoLanguage +Test-PSSessionConfigurationFile returns True. If the syntax and values are not +valid then the cmdlet returns False. + +You can use Test-PSSessionConfigurationFile to test any session configuration +file, including files that the New-PSSessionConfiguration cmdlet creates. For +more information, see the help topic for the Test-PSSessionConfigurationFile +cmdlet. + +## Removing a Session Configuration File + +You cannot remove a session configuration file from a session configuration. +However, you can replace the file with a new file that uses the default +settings. This effectively cancels the settings used by the original +configuration file. + +To replace a session configuration file, create a new session configuration +file that uses the default settings, then use the Set-PSSessionConfiguration +cmdlet to replace the custom session configuration file with the new file. + +For example, the following commands create a Default session configuration +file and then replace the active session configuration file in the NoLanguage +session configuration. + +```powershell +New-PSSessionConfigurationFile -Path .\Default.pssc +Set-PSSessionConfiguration -Name NoLanguage -Path .\Default.pssc +``` -When these commands finish, the NoLanguage session configuration -will actually provide full language support (the default setting) -for all sessions created with that session configuration. +When these commands finish, the NoLanguage session configuration will actually +provide full language support (the default setting) for all sessions created +with that session configuration. -Viewing the Properties of a Session Configuration -The session configuration objects that represent session -configurations using session configuration files have additional -properties that make it easy to discover and analyze the session -configuration. (Note that the type name shown below includes a -formatted view definition.) You can view the properties by running -the Get-PSSessionConfiguration cmdlet and piping the returned data -to the Get-Member cmdlet: +Viewing the Properties of a Session Configuration The session configuration +objects that represent session configurations using session configuration +files have additional properties that make it easy to discover and analyze the +session configuration. (Note that the type name shown below includes a +formatted view definition.) You can view the properties by running the +Get-PSSessionConfiguration cmdlet and piping the returned data to the +Get-Member cmdlet: -PS C:> Get-PSSessionConfiguration NoLanguage | Get-Member +```powershell +Get-PSSessionConfiguration NoLanguage | Get-Member +``` + +```output TypeName: Microsoft.PowerShell.Commands.PSSessionConfigurationCommands #PSSessionConfiguration @@ -331,62 +343,60 @@ SupportsOptions NoteProperty System.String Suppor... xmlns NoteProperty System.String xmlns=... XmlRenderingType NoteProperty System.String XmlRen... Permission ScriptProperty System.Object Permis... +``` -These properties make it easy to search for specific session -configurations. For example, you can use the ExecutionPolicy -property to find a session configuration that supports sessions -with the RemoteSigned execution policy. Note that, because the -ExecutionPolicy property exists only on sessions that use session -configuration files, the command might not return all qualifying +These properties make it easy to search for specific session configurations. +For example, you can use the ExecutionPolicy property to find a session +configuration that supports sessions with the RemoteSigned execution policy. +Note that, because the ExecutionPolicy property exists only on sessions that +use session configuration files, the command might not return all qualifying session configurations. -PS C:> Get-PSSessionConfiguration | +```powershell +Get-PSSessionConfiguration | where {$_.ExecutionPolicy -eq "RemoteSigned"} +``` -The following command gets session configurations in which the -RunAsUser is the Exchange administrator. +The following command gets session configurations in which the RunAsUser is +the Exchange administrator. -PS C:> Get-PSSessionConfiguration | +```powershell + Get-PSSessionConfiguration | where {$_.RunAsUser -eq "Exchange01\Admin01"} +``` -To view information about the role definitions associated with -a configuration use the Get-PSSessionCapability cmdlet. This -cmdlet enables you to determine the commands and environment -available to specific users in specific endpoints. +To view information about the role definitions associated with a configuration +use the Get-PSSessionCapability cmdlet. This cmdlet enables you to determine +the commands and environment available to specific users in specific +endpoints. -# NOTES +## NOTES -Session configurations also support a type of session known as an -"empty" session. An Empty session type enables you to create -custom sessions with selected commands. If you do not add modules, -functions, or scripts to an empty session, the session is limited -to expressions and might not be of any practical use. The -SessionType property tells you whether or not you are working with -an empty session. +Session configurations also support a type of session known as an "empty" +session. An Empty session type enables you to create custom sessions with +selected commands. If you do not add modules, functions, or scripts to an +empty session, the session is limited to expressions and might not be of any +practical use. The SessionType property tells you whether or not you are +working with an empty session. -# SEE ALSO +## SEE ALSO [about_Session_Configurations](about_Session_Configurations.md) -New-PSSession - -Disable-PSSessionConfiguration - -Enable-PSSessionConfiguration - -Get-PSSessionConfiguration +[New-PSSession](../New-PSSession.md) -New-PSSessionConfigurationFile +[Disable-PSSessionConfiguration](../Disable-PSSessionConfiguration.md) -Register-PSSessionConfiguration +[Enable-PSSessionConfiguration](../Enable-PSSessionConfiguration.md) -Set-PSSessionConfiguration +[Get-PSSessionConfiguration](../Get-PSSessionConfiguration.md) -Test-PSSessionConfigurationFile +[New-PSSessionConfigurationFile](../New-PSSessionConfigurationFile.md) -Unregister-PSSessionConfiguration +[Register-PSSessionConfiguration](../Register-PSSessionConfiguration.md) -Get-PSSessionCapability +[Set-PSSessionConfiguration](../Set-PSSessionConfiguration.md) -New-PSRoleCapabilityFile +[Test-PSSessionConfigurationFile](../Test-PSSessionConfigurationFile.md) +[Unregister-PSSessionConfiguration](../Unregister-PSSessionConfiguration.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Signing.md index e5836ac5ec8e..f8c13a29566e 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Signing.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,81 +7,81 @@ title: about_Signing --- # About Signing -## about_Signing +## SHORT DESCRIPTION +Explains how to sign scripts so that they comply with the PowerShell execution +policies. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Explains how to sign scripts so that they comply with the Windows -PowerShell execution policies. +The Restricted execution policy does not permit any scripts to run. The +AllSigned and RemoteSigned execution policies prevent PowerShell from running +scripts that do not have a digital signature. -# LONG DESCRIPTION +This topic explains how to run selected scripts that are not signed, even +while the execution policy is RemoteSigned, and how to sign scripts for your +own use. -The Restricted execution policy does not permit any scripts to run. -The AllSigned and RemoteSigned execution policies prevent Windows -PowerShell from running scripts that do not have a digital signature. +For more information about PowerShell execution policies, see +[about_Execution_Policies](about_Execution_Policies.md). -This topic explains how to run selected scripts that are not signed, -even while the execution policy is RemoteSigned, and how to sign -scripts for your own use. +## TO PERMIT SIGNED SCRIPTS TO RUN -For more information about Windows PowerShell execution policies, -see about_Execution_Policy. - -# TO PERMIT SIGNED SCRIPTS TO RUN - -------------------------------- -When you start Windows PowerShell on a computer for the first time, the -Restricted execution policy (the default) is likely to be in effect. +When you start PowerShell on a computer for the first time, the Restricted +execution policy (the default) is likely to be in effect. The Restricted policy does not permit any scripts to run. To find the effective execution policy on your computer, type: +```powershell Get-ExecutionPolicy +``` -To run unsigned scripts that you write on your local computer and -signed scripts from other users, start Windows PowerShell with the -Run as Administrator option and then use the following command to -change the execution policy on the computer to RemoteSigned: +To run unsigned scripts that you write on your local computer and signed +scripts from other users, start PowerShell with the Run as Administrator +option and then use the following command to change the execution policy on +the computer to RemoteSigned: +```powershell Set-ExecutionPolicy RemoteSigned +``` -For more information, see the help topic for the -Set-ExecutionPolicy cmdlet. +For more information, see the help topic for the Set-ExecutionPolicy cmdlet. -# RUNNING UNSIGNED SCRIPTS (REMOTESIGNED EXECUTION POLICY) +## RUNNING UNSIGNED SCRIPTS (REMOTESIGNED EXECUTION POLICY) --------------------------------------------------------- -If your Windows PowerShell execution policy is RemoteSigned, Windows +If your PowerShell execution policy is RemoteSigned, Windows PowerShell will not run unsigned scripts that are downloaded from the Internet, including unsigned scripts you receive through e-mail and instant messaging programs. -If you try to run a downloaded script, Windows PowerShell displays the +If you try to run a downloaded script, PowerShell displays the following error message: -The file cannot be loaded. The file - is not digitally signed. The script -will not execute on the system. Please see "Get-Help +```output +The file cannot be loaded. The file is not digitally +signed. The script will not execute on the system. Please see "Get-Help about_Signing" for more details. +``` Before you run the script, review the code to be sure that you trust it. Scripts have the same effect as any executable program. -To run an unsigned script, use the Unblock-File cmdlet or use the -Following procedure. +To run an unsigned script, use the Unblock-File cmdlet or use the following +procedure. 1. Save the script file on your computer. 2. Click Start, click My Computer, and locate the saved script file. 3. Right-click the script file, and then click Properties. 4. Click Unblock. -If a script that was downloaded from the Internet is digitally signed, but -you have not yet chosen to trust its publisher, Windows PowerShell displays -the following message: +If a script that was downloaded from the Internet is digitally signed, but you +have not yet chosen to trust its publisher, PowerShell displays the following +message: +```output Do you want to run software from this untrusted publisher? The file is published by CN=. This publisher is not trusted on your system. Only run scripts @@ -89,231 +89,206 @@ from trusted publishers. [V] Never run [D] Do not run [R] Run once [A] Always run [?] Help (default is "D"): +``` -If you trust the publisher, select "Run once" or "Always run." -If you do not trust the publisher, select either "Never run" or -"Do not run." If you select "Never run" or "Always run," Windows -PowerShell will not prompt you again for this publisher. +If you trust the publisher, select "Run once" or "Always run." If you do not +trust the publisher, select either "Never run" or "Do not run." If you select +"Never run" or "Always run," PowerShell will not prompt you again for +this publisher. -# METHODS OF SIGNING SCRIPTS +## METHODS OF SIGNING SCRIPTS --------------------------- -You can sign the scripts that you write and the scripts that you obtain -from other sources. Before you sign any script, examine each command -to verify that it is safe to run. +You can sign the scripts that you write and the +scripts that you obtain from other sources. Before you sign any script, +examine each command to verify that it is safe to run. -For best practices about code signing, see "Code-Signing -Best Practices" at http://go.microsoft.com/fwlink/?LinkId=119096. +For best practices about code signing, see +[Code-Signing Best Practices](http://go.microsoft.com/fwlink/?LinkId=119096). For more information about how to sign a script file, see Set-AuthenticodeSignature. -The New-SelfSignedCertificate cmdlet, introduced in the PKI module -in Windows PowerShell 3.0, creates a self-signed certificate that is -Appropriate for testing. For more information, see the help -topic for the New-SelfSignedCertificate cmdlet. - -To add a digital signature to a script, you must sign it with a code -signing certificate. Two types of certificates are suitable for signing -a script file: +The New-SelfSignedCertificate cmdlet, introduced in the PKI module in +PowerShell 3.0, creates a self-signed certificate that is Appropriate for +testing. For more information, see the help topic for the +New-SelfSignedCertificate cmdlet. --- Certificates that are created by a certification authority: +To add a digital signature to a script, you must sign it with a code signing +certificate. Two types of certificates are suitable for signing a script file: -For a fee, a public certification authority verifies your -identity and gives you a code signing certificate. When -you purchase your certificate from a reputable certification -authority, you are able to share your script with users -on other computers that are running Windows because those other -computers trust the certification authority. +- Certificates that are created by a certification authority: For a fee, a + public certification authority verifies your identity and gives you a code + signing certificate. When you purchase your certificate from a reputable + certification authority, you are able to share your script with users on + other computers that are running Windows because those other computers trust + the certification authority. --- Certificates that you create: +- Certificates that you create: You can create a self-signed certificate for + which your computer is the authority that creates the certificate. This + certificate is free of charge and enables you to write, sign, and run scripts + on your computer. However, a script signed by a self-signed certificate will + not run on other computers. -You can create a self-signed certificate for which -your computer is the authority that creates the certificate. -This certificate is free of charge and enables you to write, -sign, and run scripts on your computer. However, a script -signed by a self-signed certificate will not run on other -computers. +Typically, you would use a self-signed certificate only to sign scripts that +you write for your own use and to sign scripts that you get from other sources +that you have verified to be safe. It is not appropriate for scripts that will +be shared, even within an enterprise. -Typically, you would use a self-signed certificate only to sign -scripts that you write for your own use and to sign scripts that you get -from other sources that you have verified to be safe. It is not -appropriate for scripts that will be shared, even within an enterprise. +If you create a self-signed certificate, be sure to enable strong private key +protection on your certificate. This prevents malicious programs from signing +scripts on your behalf. The instructions are included at the end of this +topic. -If you create a self-signed certificate, be sure to enable strong -private key protection on your certificate. This prevents malicious -programs from signing scripts on your behalf. The instructions are -included at the end of this topic. +## CREATE A SELF-SIGNED CERTIFICATE -# CREATE A SELF-SIGNED CERTIFICATE - --------------------------------- To create a self-signed certificate in use the New-SelfSignedCertificate -cmdlet in the PKI module. This module is introduced in Windows PowerShell -3.0 and is included in Windows 8 and Windows Server 2012. For more -information, see the help topic for the New-SelfSignedCertificate cmdlet. +cmdlet in the PKI module. This module is introduced in PowerShell 3.0 and is +included in Windows 8 and Windows Server 2012. For more information, see the +help topic for the New-SelfSignedCertificate cmdlet. -To create a self-signed certificate in earlier versions of Windows, use -the Certificate Creation tool (MakeCert.exe). This tool is included in -the Microsoft .NET Framework SDK (versions 1.1 and later) and in the -Microsoft Windows SDK. +To create a self-signed certificate in earlier versions of Windows, use the +Certificate Creation tool (MakeCert.exe). This tool is included in the +Microsoft .NET Framework SDK (versions 1.1 and later) and in the Microsoft +Windows SDK. For more information about the syntax and the parameter descriptions of the -MakeCert.exe tool, see "Certificate Creation Tool (MakeCert.exe)" in the -MSDN (Microsoft Developer Network) library at -http://go.microsoft.com/fwlink/?LinkId=119097. +MakeCert.exe tool, see [Certificate Creation Tool (MakeCert.exe)](http://go.microsoft.com/fwlink/?LinkId=119097) +in the MSDN library. To use the MakeCert.exe tool to create a certificate, run the following commands in an SDK Command Prompt window. -Note: The first command creates a local certification authority for -your computer. The second command generates a personal -certificate from the certification authority. +Note: The first command creates a local certification authority for your +computer. The second command generates a personal certificate from the +certification authority. -Note: You can copy or type the commands exactly as they appear. -No substitutions are necessary, although you can change the -certificate name. +Note: You can copy or type the commands exactly as they appear. No +substitutions are necessary, although you can change the certificate name. +```powershell makecert -n "CN=PowerShell Local Certificate Root" -a sha1 ` -eku 1.3.6.1.5.5.7.3.3 -r -sv root.pvk root.cer ` -ss Root -sr localMachine makecert -pe -n "CN=PowerShell User" -ss MY -a sha1 ` -eku 1.3.6.1.5.5.7.3.3 -iv root.pvk -ic root.cer +``` -The MakeCert.exe tool will prompt you for a private key password. The -password ensures that no one can use or access the certificate without -your consent. Create and enter a password that you can remember. You will -use this password later to retrieve the certificate. +The MakeCert.exe tool will prompt you for a private key password. The password +ensures that no one can use or access the certificate without your consent. +Create and enter a password that you can remember. You will use this password +later to retrieve the certificate. -To verify that the certificate was generated correctly, use the -following command to get the certificate in the certificate -store on the computer. (You will not find a certificate file in the -file system directory.) +To verify that the certificate was generated correctly, use the following +command to get the certificate in the certificate store on the computer. (You +will not find a certificate file in the file system directory.) -At the Windows PowerShell prompt, type: +At the PowerShell prompt, type: +```powershell get-childitem cert:\CurrentUser\my -codesigning +``` -This command uses the Windows PowerShell Certificate provider to view -information about the certificate. +This command uses the PowerShell Certificate provider to view information +about the certificate. -If the certificate was created, the output shows the thumbprint -that identifies the certificate in a display that resembles the following: +If the certificate was created, the output shows the thumbprint that +identifies the certificate in a display that resembles the following: +```output Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My Thumbprint Subject ---------- ------- 4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ] +``` -# SIGN A SCRIPT - -------------- +## SIGN A SCRIPT -After you create a self-signed certificate, you can sign scripts. If you -use the AllSigned execution policy, signing a script permits you to run -the script on your computer. +After you create a self-signed certificate, you can sign scripts. If you use +the AllSigned execution policy, signing a script permits you to run the script +on your computer. -The following sample script, Add-Signature.ps1, signs a script. However, -if you are using the AllSigned execution policy, you must sign the +The following sample script, Add-Signature.ps1, signs a script. However, if +you are using the AllSigned execution policy, you must sign the Add-Signature.ps1 script before you run it. -To use this script, copy the following text into a text file, and -name it Add-Signature.ps1. - -Note: Be sure that the script file does not have a .txt file name -extension. If your text editor appends ".txt", enclose the file name -in quotation marks: "add-signature.ps1". +To use this script, copy the following text into a text file, and name it +Add-Signature.ps1. -## add-signature.ps1 +```powershell ## Signs a file param([string] $file=$(throw "Please specify a filename.")) $cert = @(Get-ChildItem cert:\CurrentUser\My -codesigning)[0] Set-AuthenticodeSignature $file $cert +``` -To sign the Add-Signature.ps1 script file, type the following commands at -the Windows PowerShell command prompt: +To sign the Add-Signature.ps1 script file, type the following commands at the +PowerShell command prompt: +```powershell $cert = @(Get-ChildItem cert:\CurrentUser\My -codesigning)[0] - Set-AuthenticodeSignature add-signature.ps1 $cert +``` -After the script is signed, you can run it on the local computer. -However, the script will not run on computers on which the Windows -PowerShell execution policy requires a digital signature from a -trusted authority. If you try, Windows PowerShell displays the following -error message: +After the script is signed, you can run it on the local computer. However, the +script will not run on computers on which the PowerShell execution +policy requires a digital signature from a trusted authority. If you try, +PowerShell displays the following error message: +```output The file C:\remote_file.ps1 cannot be loaded. The signature of the certificate cannot be verified. At line:1 char:15 + .\ remote_file.ps1 <<<< +``` -If Windows PowerShell displays this message when you run a -script that you did not write, treat the file as you would treat any -unsigned script. Review the code to determine whether you can trust the -script. - -# ENABLE STRONG PRIVATE KEY PROTECTION FOR YOUR CERTIFICATE +If PowerShell displays this message when you run a script that you did not +write, treat the file as you would treat any unsigned script. Review the code +to determine whether you can trust the script. ---------------------------------------------------------- +## ENABLE STRONG PRIVATE KEY PROTECTION FOR YOUR CERTIFICATE -If you have a private certificate on your computer, malicious -programs might be able to sign scripts on your behalf, which -authorizes Windows PowerShell to run them. +If you have a private certificate on your computer, malicious programs might +be able to sign scripts on your behalf, which authorizes PowerShell to run +them. -To prevent automated signing on your behalf, use Certificate -Manager (Certmgr.exe) to export your signing certificate to -a .pfx file. Certificate Manager is included in the Microsoft -.NET Framework SDK, the Microsoft Windows SDK, and in Internet -Explorer 5.0 and later versions. +To prevent automated signing on your behalf, use Certificate Manager +(Certmgr.exe) to export your signing certificate to a .pfx file. Certificate +Manager is included in the Microsoft .NET Framework SDK, the Microsoft Windows +SDK, and in Internet Explorer 5.0 and later versions. To export the certificate: 1. Start Certificate Manager. - 2. Select the certificate issued by PowerShell Local Certificate Root. - 3. Click Export to start the Certificate Export Wizard. - 4. Select "Yes, export the private key", and then click Next. - 5. Select "Enable strong protection." - 6. Type a password, and then type it again to confirm. - 7. Type a file name that has the .pfx file name extension. - 8. Click Finish. To re-import the certificate: 1. Start Certificate Manager. - 2. Click Import to start the Certificate Import Wizard. - -3. Open to the location of the .pfx file that you created during the -export process. - +3. Open to the location of the .pfx file that you created during the export + process. 4. On the Password page, select "Enable strong private key protection", -and then enter the password that you assigned during the export -process. - + and then enter the password that you assigned during the export + process. 5. Select the Personal certificate store. - 6. Click Finish. -# PREVENT THE SIGNATURE FROM EXPIRING +## PREVENT THE SIGNATURE FROM EXPIRING ------------------------------------ The digital signature in a script is valid until the signing certificate expires or as long as a time stamp server can verify that the script was signed while the signing certificate was valid. -Because most signing certificates are valid for one year only, using a -time stamp server ensures that users can use your script for many years -to come. +Because most signing certificates are valid for one year only, using a time +stamp server ensures that users can use your script for many years to come. # SEE ALSO @@ -321,13 +296,10 @@ to come. [about_Profiles](about_Profiles.md) -Get-ExecutionPolicy - -New-SelfSignedCertificate - -Set-ExecutionPolicy +[Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -Set-AuthenticodeSignature +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -"Introduction to Code Signing" (http://go.microsoft.com/fwlink/?LinkId=106296) +[Set-AuthenticodeSignature](../../Microsoft.PowerShell.Security/Set-AuthenticodeSignature.md) +[Introduction to Code Signing](http://go.microsoft.com/fwlink/?LinkId=106296) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md index 10b1d7bc00db..02d2b8d169e7 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,68 +7,61 @@ title: about_Splatting --- # About Splatting -## about_Splatting +## SHORT DESCRIPTION +Describes how to use splatting to pass parameters to commands in Windows +PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes how to use splatting to pass parameters to commands -in Windows PowerShell. +[This topic was contributed by Rohn Edwards of Gulfport, Mississippi, a system +administrator and the winner of the Advanced Division of the 2012 Scripting +Games. Revised for Windows PowerShell 3.0.] -# LONG DESCRIPTION +Splatting is a method of passing a collection of parameter values to a command +as unit. Windows PowerShell associates each value in the collection with a +command parameter. Splatted parameter values are stored in named splatting +variables, which look like standard variables, but begin with an At symbol (@) +instead of a dollar sign ($). The At symbol tells Windows PowerShell that you +are passing a collection of values, instead of a single value. -[This topic was contributed by Rohn Edwards of Gulfport, -Mississippi, a system administrator and the winner -of the Advanced Division of the 2012 Scripting Games. -Revised for Windows PowerShell 3.0.] +Splatting makes your commands shorter and easier to read. You can re-use the +splatting values in different command calls and use splatting to pass +parameter values from the `$PSBoundParameters` automatic variable to other +scripts and functions. -Splatting is a method of passing a collection of parameter -values to a command as unit. Windows PowerShell associates -each value in the collection with a command parameter. -Splatted parameter values are stored in named splatting -variables, which look like standard variables, but begin with -an At symbol (@) instead of a dollar sign ($). The At symbol -tells Windows PowerShell that you are passing a collection of -values, instead of a single value. +Beginning in Windows PowerShell 3.0, you can also use splatting to represent +all parameters of a command. -Splatting makes your commands shorter and easier to read. You -can re-use the splatting values in different command calls and -use splatting to pass parameter values from the `$PSBoundParameters` -automatic variable to other scripts and functions. +## SYNTAX -Beginning in Windows PowerShell 3.0, you can also use splatting -to represent all parameters of a command. - -# SYNTAX - -```powershell +``` @ @ ``` -To provide parameter values for positional parameters, in which -parameter names are not required, use the array syntax. To provide -parameter name and value pairs, use the hash table syntax. The -splatted value can appear anywhere in the parameter list. +To provide parameter values for positional parameters, in which parameter +names are not required, use the array syntax. To provide parameter name and +value pairs, use the hash table syntax. The splatted value can appear anywhere +in the parameter list. -When splatting, you do not need to use a hash table or an array to -pass all parameters. You may pass some parameters by using splatting -and pass others by position or by parameter name. Also, you can splat -multiple objects in a single command just so you pass no more than one -value for each parameter. +When splatting, you do not need to use a hash table or an array to pass all +parameters. You may pass some parameters by using splatting and pass others by +position or by parameter name. Also, you can splat multiple objects in a +single command just so you pass no more than one value for each parameter. -# SPLATTING WITH HASH TABLES +## SPLATTING WITH HASH TABLES -Use a hash table to splat parameter name and value pairs. You can use -this format for all parameter types, including positional and named -parameters and switch parameters. +Use a hash table to splat parameter name and value pairs. You can use this +format for all parameter types, including positional and named parameters and +switch parameters. -The following examples compare two `Copy-Item` commands that copy the -Test.txt file to the Test2.txt file in the same directory. +The following examples compare two `Copy-Item` commands that copy the Test.txt +file to the Test2.txt file in the same directory. -The first example uses the traditional format in which parameter names -are included. +The first example uses the traditional format in which parameter names are +included. ```powershell Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf @@ -76,9 +69,9 @@ Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf The second example uses hash table splatting. The first command creates a hash table of parameter-name and parameter-value pairs and stores it in the -\$HashArguments variable. The second command uses the `$HashArguments` variable -in a command with splatting. The At symbol (`@HashArguments`) replaces the -dollar sign (`$HashArguments`) in the command. +\$HashArguments variable. The second command uses the `$HashArguments` +variable in a command with splatting. The At symbol (`@HashArguments`) +replaces the dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. @@ -91,11 +84,11 @@ $HashArguments = @{ Copy-Item @HashArguments ``` -Note: In the first command, the At symbol (@) indicates a hash table, not -a splatted value. The syntax for hash tables in Windows PowerShell is: +Note: In the first command, the At symbol (@) indicates a hash table, not a +splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* -# SPLATTING WITH ARRAYS +## SPLATTING WITH ARRAYS Use an array to splat values for positional parameters, which do not require parameter names. The values must be in position-number order in the array. @@ -122,8 +115,7 @@ $ArrayArguments = "test.txt", "test2.txt" Copy-Item @ArrayArguments -WhatIf ``` -# EXAMPLES - +## EXAMPLES This example shows how to re-use splatted values in different commands. The commands in this example use the Write-Host cmdlet to write messages to the @@ -153,18 +145,16 @@ Write-Host "This is a test." @Colors Write-Host @Colors "This is another test." ``` -This example shows how to forward their parameters to other commands by -using splatting and the `$PSBoundParameters` automatic variable. +This example shows how to forward their parameters to other commands by using +splatting and the `$PSBoundParameters` automatic variable. -The $PSBoundParameters automatic variable is a dictionary -(System.Collections.Generic.Dictionary) that contains all of the -parameter names and values that are used when a script or function -is run. +The \$PSBoundParameters automatic variable is a dictionary +(System.Collections.Generic.Dictionary) that contains all of the parameter +names and values that are used when a script or function is run. -In the following example, we use the `$PSBoundParameters` variable to -forward the parameters values passed to a script or function from Test2 -function to the Test1 function. Both calls to the Test1 function from -Test2 use splatting. +In the following example, we use the `$PSBoundParameters` variable to forward +the parameters values passed to a script or function from Test2 function to +the Test1 function. Both calls to the Test1 function from Test2 use splatting. ```powershell function Test1 @@ -188,7 +178,9 @@ function Test2 $LimitedParameters.Remove("a") | Out-Null Test1 @LimitedParameters } +``` +```output Test2 -a 1 -b 2 -c 3 1 2 @@ -197,7 +189,7 @@ Test2 -a 1 -b 2 -c 3 3 ``` -# SPLATTING COMMAND PARAMETERS +## SPLATTING COMMAND PARAMETERS You can use splatting to represent the parameters of a command. This technique is useful when you are creating a proxy function, that is, a function that @@ -207,8 +199,8 @@ To splat the parameters of a command, use `@Args` to represent the command parameters. This technique is easier than enumerating command parameters and it works without revision even if the parameters of the called command change. -The feature uses the `$Args` automatic variable, which contains -all unassigned parameter values. +The feature uses the `$Args` automatic variable, which contains all unassigned +parameter values. For example, the following function calls the Get-Process cmdlet. In this function, `@Args` represents all of the parameters of the Get-Process cmdlet. @@ -217,19 +209,24 @@ function, `@Args` represents all of the parameters of the Get-Process cmdlet. function Get-MyProcess { Get-Process @Args } ``` -When you use the Get-MyProcess function, all unassigned -parameters and parameter values are passed to `@Args`, as -shown in the following commands. +When you use the Get-MyProcess function, all unassigned parameters and +parameter values are passed to `@Args`, as shown in the following commands. ```powershell Get-MyProcess -Name PowerShell +``` +```output Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 463 46 225484 237196 719 15.86 3228 powershell +``` +```powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo +``` +```output ProductVersion FileVersion FileName -------------- ----------- -------- 6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... @@ -248,7 +245,9 @@ function Get-MyCommand } Get-MyCommand -P -C -Name PowerShell +``` +```output Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Transactions.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Transactions.md index e93860f24d7f..5c292571cdac 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Transactions.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Transactions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,445 +7,454 @@ title: about_Transactions --- # About Transactions -## about_Transactions +## SHORT DESCRIPTION +Describes how to manage transacted operations in PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes how to manage transacted operations in Windows PowerShell. +Transactions are supported in PowerShell beginning in PowerShell 2.0. This +feature enables you to start a transaction, to indicate which commands are +part of the transaction, and to commit or roll back a transaction. -# LONG DESCRIPTION +## ABOUT TRANSACTIONS -Transactions are supported in Windows PowerShell beginning -in Windows PowerShell 2.0. This feature enables you to start -a transaction, to indicate which commands are part of the -transaction, and to commit or roll back a transaction. +In PowerShell, a transaction is a set of one or more commands that are managed +as a logical unit. A transaction can be completed ("committed"), which changes +data affected by the transaction. Or, a transaction can be completely undone +("rolled back") so that the affected data is not changed by the transaction. -# ABOUT TRANSACTIONS +Because the commands in a transaction are managed as a unit, either all +commands are committed, or all commands are rolled back. +Transactions are widely used in data processing, most notably in database +operations and for financial transactions. Transactions are most often used +when the worst-case scenario for a set of commands is not that they all fail, +but that some commands succeed while others fail, leaving the system in a +damaged, false, or uninterpretable state that is difficult to repair. -In Windows PowerShell, a transaction is a set of one or more -commands that are managed as a logical unit. A transaction can -be completed ("committed"), which changes data affected by the -transaction. Or, a transaction can be completely undone ("rolled back") -so that the affected data is not changed by the transaction. +## TRANSACTION CMDLETS -Because the commands in a transaction are managed as a unit, -either all commands are committed, or all commands are rolled -back. +PowerShell includes several cmdlets designed for managing transactions. -Transactions are widely used in data processing, most notably -in database operations and for financial transactions. Transactions -are most often used when the worst-case scenario for a set of -commands is not that they all fail, but that some commands succeed -while others fail, leaving the system in a damaged, false, or -uninterpretable state that is difficult to repair. - -# TRANSACTION CMDLETS - - -Windows PowerShell includes several cmdlets designed for managing -transactions. - -Cmdlet Description --------------- --------------------------------- -Start-Transaction Starts a new transaction. - -Use-Transaction Adds a command or expression to the -transaction. The command must use -transaction-enabled objects. - -Undo-Transaction Rolls back the transaction so that -no data is changed by the transaction. - -Complete-Transaction Commits the transaction. The data -affected by the transaction is changed. - -Get-Transaction Gets information about the active -transaction. +- Start-Transaction: Starts a new transaction. +- Use-Transaction: Adds a command or expression to the transaction. The + command must use transaction-enabled objects. +- Undo-Transaction: Rolls back the transaction so that no data is changed by + the transaction. +- Complete-Transaction: Commits the transaction. The data affected by the + transaction is changed. +- Get-Transaction: Gets information about the active transaction. For a list of transaction cmdlets, type: +```powershell get-command *transaction +``` For detailed information about the cmdlets, type: -get-help -detailed - -For example: - +```powershell get-help use-transaction -detailed +``` -# TRANSACTION-ENABLED ELEMENTS - +## TRANSACTION-ENABLED ELEMENTS -To participate in a transaction, both the cmdlet and the provider -must support transactions. This feature is built in to the objects -that are affected by the transaction. +To participate in a transaction, both the cmdlet and the provider must support +transactions. This feature is built in to the objects that are affected by the +transaction. -The Windows PowerShell Registry provider supports transactions -in Windows Vista. The TransactedString object -(Microsoft.PowerShell.Commands.Management.TransactedString) works -with any operating system that runs Windows PowerShell. +The PowerShell Registry provider supports transactions in Windows Vista. The +TransactedString object +(Microsoft.PowerShell.Commands.Management.TransactedString) works with any +operating system that runs PowerShell. -Other Windows PowerShell providers can support transactions. To -find the Windows PowerShell providers in your session that support -transactions, use the following command to find the "Transactions" -value in the Capabilities property of providers: +Other PowerShell providers can support transactions. To find the PowerShell +providers in your session that support transactions, use the following command +to find the "Transactions" value in the Capabilities property of providers: +```powershell get-psprovider | where {$_.Capabilities -like "transactions"} +``` -For more information about a provider, see the Help for the provider. -To get provider Help, type: +For more information about a provider, see the Help for the provider. To get +provider Help, type: +``` get-help +``` For example, to get Help for the Registry provider, type: +```powershell get-help registry +``` -# THE USETRANSACTION PARAMETER - +## THE USETRANSACTION PARAMETER -Cmdlets that can support transactions have a UseTransaction -parameter. This parameter includes the command in the active -transaction. You can use the full parameter name or its alias, -"usetx". +Cmdlets that can support transactions have a UseTransaction parameter. This +parameter includes the command in the active transaction. You can use the full +parameter name or its alias, "usetx". -The parameter can be used only when the session contains an -active transaction. If you enter a command with the UseTransaction -parameter when there is no active transaction, the command fails. +The parameter can be used only when the session contains an active +transaction. If you enter a command with the UseTransaction parameter when +there is no active transaction, the command fails. To find cmdlets with the UseTransaction parameter, type: +```powershell get-help * -parameter UseTransaction +``` -In Windows PowerShell core, all of the cmdlets designed to work -with Windows PowerShell providers support transactions. As a -result, you can use the provider cmdlets to manage transactions. +In PowerShell core, all of the cmdlets designed to work with PowerShell +providers support transactions. As a result, you can use the provider cmdlets +to manage transactions. -For more information about Windows PowerShell providers, -see about_Providers. +For more information about PowerShell providers, see [about_Providers](about_Providers.md). -# THE TRANSACTION OBJECT +## THE TRANSACTION OBJECT - -Transactions are represented in Windows PowerShell by a -transaction object, System.Management.Automation.Transaction. +Transactions are represented in PowerShell by a transaction object, +System.Management.Automation.Transaction. The object has the following properties: -RollbackPreference: -Contains the rollback preference set for the current -transaction. You can set the rollback preference when you -use Start-Transaction to start the transaction. +- RollbackPreference: Contains the rollback preference set for the current + transaction. You can set the rollback preference when you use + Start-Transaction to start the transaction. -The rollback preference determines the conditions under -which the transaction is rolled back automatically. Valid -values are Error, TerminatingError, and Never. The default -value is Error. + The rollback preference determines the conditions under which the transaction + is rolled back automatically. Valid values are Error, TerminatingError, and + Never. The default value is Error. -Status: -Contains the current status of the transaction. Valid -values are Active, Committed, and RolledBack. +- Status: Contains the current status of the transaction. Valid values are + Active, Committed, and RolledBack. -SubscriberCount: -Contains the number of subscribers to the transaction. A -subscriber is added to a transaction when you start a -transaction while another transaction is in progress. The -subscriber count is decremented when a subscriber commits -the transaction. +- SubscriberCount: Contains the number of subscribers to the transaction. A + subscriber is added to a transaction when you start a transaction while + another transaction is in progress. The subscriber count is decremented when + a subscriber commits the transaction. -# ACTIVE TRANSACTIONS +## ACTIVE TRANSACTIONS +In PowerShell, only one transaction is active at a time, and you can manage +only the active transaction. Multiple transactions can be in progress in the +same session at the same time, but only the most-recently started transaction +is active. -In Windows PowerShell, only one transaction is active at a -time, and you can manage only the active transaction. Multiple -transactions can be in progress in the same session at the same -time, but only the most-recently started transaction is active. +As a result, you cannot specify a particular transaction when using the +transaction cmdlets. Commands always apply to the active transaction. -As a result, you cannot specify a particular transaction when -using the transaction cmdlets. Commands always apply to the -active transaction. - -This is most evident in the behavior of the Get-Transaction cmdlet. -When you enter a Get-Transaction command, Get-Transaction always -gets only one transaction object. This object is the object that -represents the active transaction. +This is most evident in the behavior of the Get-Transaction cmdlet. When you +enter a Get-Transaction command, Get-Transaction always gets only one +transaction object. This object is the object that represents the active +transaction. To manage a different transaction, you must first finish the active -transaction, either by committing it or rolling it back. When you -do this, the previous transaction becomes active automatically. -Transactions become active in the reverse of order of which they are -started, so that the most recently started transaction is always -active. +transaction, either by committing it or rolling it back. When you do this, the +previous transaction becomes active automatically. Transactions become active +in the reverse of order of which they are started, so that the most recently +started transaction is always active. -# SUBSCRIBERS AND INDEPENDENT TRANSACTIONS +## SUBSCRIBERS AND INDEPENDENT TRANSACTIONS +If you start a transaction while another transaction is in progress, by +default, PowerShell does not start a new transaction. Instead, it adds a +"subscriber" to the current transaction. -If you start a transaction while another transaction is in progress, -by default, Windows PowerShell does not start a new transaction. -Instead, it adds a "subscriber" to the current transaction. +When a transaction has multiple subscribers, a single Undo-Transaction command +at any point rolls back the entire transaction for all subscribers. However, +to commit the transaction, you must enter a Complete-Transaction command for +every subscriber. -When a transaction has multiple subscribers, a single -Undo-Transaction command at any point rolls back the entire -transaction for all subscribers. However, to commit the transaction, -you must enter a Complete-Transaction command for every subscriber. - -To find the number of subscribers to a transaction, check the -SubscriberCount property of the transaction object. For example, -the following command uses the Get-Transaction cmdlet to get -the value of the SubscriberCount property of the active transaction: +To find the number of subscribers to a transaction, check the SubscriberCount +property of the transaction object. For example, the following command uses +the Get-Transaction cmdlet to get the value of the SubscriberCount property of +the active transaction: +```powershell (Get-Transaction).SubscriberCount +``` -Adding a subscriber is the default behavior because most transactions -that are started while another transaction is in progress are related -to the original transaction. In the typical model, a script that -contains a transaction calls a helper script that contains its own -transaction. Because the transactions are related, they should be -rolled back or committed as a unit. - -However, you can start a transaction that is independent of the -current transaction by using the Independent parameter of the -Start-Transaction cmdlet. +Adding a subscriber is the default behavior because most transactions that are +started while another transaction is in progress are related to the original +transaction. In the typical model, a script that contains a transaction calls +a helper script that contains its own transaction. Because the transactions +are related, they should be rolled back or committed as a unit. -When you start an independent transaction, Start-Transaction -creates a new transaction object, and the new transaction becomes -the active transaction. The independent transaction can be -committed or rolled back without affecting the original transaction. +However, you can start a transaction that is independent of the current +transaction by using the Independent parameter of the Start-Transaction +cmdlet. -When the independent transaction is finished (committed or rolled -back), the original transaction becomes the active transaction -again. +When you start an independent transaction, Start-Transaction creates a new +transaction object, and the new transaction becomes the active transaction. +The independent transaction can be committed or rolled back without affecting +the original transaction. -# CHANGING DATA +When the independent transaction is finished (committed or rolled back), the +original transaction becomes the active transaction again. +## CHANGING DATA -When you use transactions to change data, the data that is affected -by the transaction is not changed until you commit the transaction. -However, the same data can be changed by commands that are not -part of the transaction. +When you use transactions to change data, the data that is affected by the +transaction is not changed until you commit the transaction. However, the same +data can be changed by commands that are not part of the transaction. -Keep this in mind when you are using transactions to manage shared -data. Typically, databases have mechanisms that lock the data while -you are working on it, preventing other users, and other commands, -scripts, and functions, from changing it. +Keep this in mind when you are using transactions to manage shared data. +Typically, databases have mechanisms that lock the data while you are working +on it, preventing other users, and other commands, scripts, and functions, +from changing it. -However, the lock is a feature of the database. It is not related -to transactions. If you are working in a transaction-enabled -file system or other data store, the data can be changed while -the transaction is in progress. +However, the lock is a feature of the database. It is not related to +transactions. If you are working in a transaction-enabled file system or other +data store, the data can be changed while the transaction is in progress. -# EXAMPLES +## EXAMPLES -The examples in this section use the Windows PowerShell Registry -provider and assume that you are familiar with it. For information -about the Registry provider, type "get-help registry". +The examples in this section use the PowerShell Registry provider and assume +that you are familiar with it. For information about the Registry provider, +type "get-help registry". -# EXAMPLE 1: COMMITTING A TRANSACTION +### EXAMPLE 1: COMMITTING A TRANSACTION +To create a transaction, use the Start-Transaction cmdlet. The following +command starts a transaction with the default settings. -To create a transaction, use the Start-Transaction cmdlet. The -following command starts a transaction with the default settings. - +```powershell start-transaction +``` -To include commands in the transaction, use the UseTransaction -parameter of the cmdlet. By default, commands are not included -in the transaction, +To include commands in the transaction, use the UseTransaction parameter of +the cmdlet. By default, commands are not included in the transaction, -For example, the following command, which sets the current -location in the Software key of the HKCU: drive, is not included -in the transaction. +For example, the following command, which sets the current location in the +Software key of the HKCU: drive, is not included in the transaction. +```powershell cd hkcu:\Software +``` The following command, which creates the MyCompany key, uses the -UseTransaction parameter of the New-Item cmdlet to include the -command in the active transaction. +UseTransaction parameter of the New-Item cmdlet to include the command in the +active transaction. +```powershell new-item MyCompany -UseTransaction +``` -The command returns an object that represents the new key, but -because the command is part of the transaction, the registry -is not yet changed. +The command returns an object that represents the new key, but because the +command is part of the transaction, the registry is not yet changed. +``` Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -0 0 MyCompany {} + 0 0 MyCompany {} +``` -To commit the transaction, use the Complete-Transaction cmdlet. -Because it always affects the active transaction, you cannot specify -the transaction. +To commit the transaction, use the Complete-Transaction cmdlet. Because it +always affects the active transaction, you cannot specify the transaction. +```powershell complete-transaction +``` As a result, the MyCompany key is added to the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# EXAMPLE 2: ROLLING BACK A TRANSACTION +### EXAMPLE 2: ROLLING BACK A TRANSACTION +To create a transaction, use the Start-Transaction cmdlet. The following +command starts a transaction with the default settings. -To create a transaction, use the Start-Transaction cmdlet. The -following command starts a transaction with the default settings. - +```powershell start-transaction +``` The following command, which creates the MyOtherCompany key, uses the -UseTransaction parameter of the New-Item cmdlet to include the -command in the active transaction. +UseTransaction parameter of the New-Item cmdlet to include the command in the +active transaction. +```powershell new-item MyOtherCompany -UseTransaction +``` -The command returns an object that represents the new key, but -because the command is part of the transaction, the registry -is not yet changed. +The command returns an object that represents the new key, but because the +command is part of the transaction, the registry is not yet changed. +``` Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -0 0 MyOtherCompany {} + 0 0 MyOtherCompany {} +``` -To roll back the transaction, use the Undo-Transaction cmdlet. -Because it always affects the active transaction, you do not specify -the transaction. +To roll back the transaction, use the Undo-Transaction cmdlet. Because it +always affects the active transaction, you do not specify the transaction. +```powershell Undo-transaction +``` The result is that the MyOtherCompany key is not added to the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# EXAMPLE 3: PREVIEWING A TRANSACTION +### EXAMPLE 3: PREVIEWING A TRANSACTION +Typically, the commands used in a transaction change data. However, the +commands that get data are useful in a transaction, too, because they get data +inside of the transaction. This provides a preview of the changes that +committing the transaction would cause. -Typically, the commands used in a transaction change data. However, -the commands that get data are useful in a transaction, too, because -they get data inside of the transaction. This provides a preview of the -changes that committing the transaction would cause. - -The following example shows how to use the Get-ChildItem command -(the alias is "dir") to preview the changes in a transaction. +The following example shows how to use the Get-ChildItem command (the alias is +"dir") to preview the changes in a transaction. The following command starts a transaction. +```powershell start-transaction +``` -The following command uses the New-ItemProperty cmdlet to add the -MyKey registry entry to the MyCompany key. The command uses the -UseTransaction parameter to include the command in the transaction. +The following command uses the New-ItemProperty cmdlet to add the MyKey +registry entry to the MyCompany key. The command uses the UseTransaction +parameter to include the command in the transaction. +```powershell new-itemproperty -path MyCompany -Name MyKey -value 123 -UseTransaction +``` -The command returns an object representing the new registry entry, -but the registry entry is not changed. +The command returns an object representing the new registry entry, but the +registry entry is not changed. +``` MyKey ----- -# 123 - +123 +``` To get the items that are currently in the registry, use a Get-ChildItem -command ("dir") without the UseTransaction parameter. The following -command gets items that begin with "M." +command ("dir") without the UseTransaction parameter. The following command +gets items that begin with "M." +```powershell dir m* +``` The result shows that no entries have yet been added to the MyCompany key. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` To preview the effect of committing the transaction, enter a Get-ChildItem -("dir") command with the UseTransaction parameter. This command has a view -of the data from within the transaction. +("dir") command with the UseTransaction parameter. This command has a view of +the data from within the transaction. +```powershell dir m* -useTransaction +``` -The result shows that, if the transaction is committed, the MyKey entry -will be added to the MyCompany key. +The result shows that, if the transaction is committed, the MyKey entry will +be added to the MyCompany key. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 1 MyCompany {MyKey} - -# EXAMPLE 4: COMBINING TRANSACTED AND NON-TRANSACTED COMMANDS - + 83 1 Microsoft {(default)} + 0 1 MyCompany {MyKey} +``` -You can enter non-transacted commands during a transaction. The -non-transacted commands affect the data immediately, but they do -not affect the transaction. +### EXAMPLE 4: COMBINING TRANSACTED AND NON-TRANSACTED COMMANDS -The following command starts a transaction in the HKCU:\Software -registry key. +You can enter non-transacted commands during a transaction. The non-transacted +commands affect the data immediately, but they do not affect the transaction. +The following command starts a transaction in the HKCU:\Software registry key. +```powershell start-transaction +``` -The next three commands use the New-Item cmdlet to add keys to -the registry. The first and third commands use the UseTransaction -parameter to include the commands in the transaction. The second -command omits the parameter. Because the second command is not -included in the transaction, it is effective immediately. +The next three commands use the New-Item cmdlet to add keys to the registry. +The first and third commands use the UseTransaction parameter to include the +commands in the transaction. The second command omits the parameter. Because +the second command is not included in the transaction, it is effective +immediately. +```powershell new-item MyCompany1 -UseTransaction - new-item MyCompany2 - new-item MyCompany3 -UseTransaction +``` -To view the current state of the registry, use a Get-ChildItem ("dir") -command without the UseTransaction parameter. This command gets items -that begin with "M." +To view the current state of the registry, use a Get-ChildItem ("dir") command +without the UseTransaction parameter. This command gets items that begin with +"M." +```powershell dir m* +``` -The result shows that the MyCompany2 key is added to the registry, but -the MyCompany1 and MyCompany3 keys, which are part of the transaction, -are not added. +The result shows that the MyCompany2 key is added to the registry, but the +MyCompany1 and MyCompany3 keys, which are part of the transaction, are not +added. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany2 {} + 83 1 Microsoft {(default)} + 0 0 MyCompany2 {} +``` The following command commits the transaction. +```powershell complete-transaction +``` Now, the keys that were added as part of the transaction appear in the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property @@ -454,327 +463,389 @@ SKC VC Name Property 0 0 MyCompany1 {} 0 0 MyCompany2 {} 0 0 MyCompany3 {} +``` -# EXAMPLE 5: USING AUTOMATIC ROLLBACK +### EXAMPLE 5: USING AUTOMATIC ROLLBACK +When a command in a transaction generates an error of any kind, the +transaction is automatically rolled back. -When a command in a transaction generates an error -of any kind, the transaction is automatically rolled -back. - -This default behavior is designed for scripts that -run transactions. Scripts are typically well tested -and include error-handling logic, so errors are not +This default behavior is designed for scripts that run transactions. Scripts +are typically well tested and include error-handling logic, so errors are not expected and should terminate the transaction. -The first command starts a transaction in the HKCU:\Software -registry key. +The first command starts a transaction in the HKCU:\Software registry key. +```powershell start-transaction +``` -The following command uses the New-Item cmdlet to -add the MyCompany key to the registry. The command uses -the UseTransaction parameter (the alias is "usetx") to include -the command in the transaction. +The following command uses the New-Item cmdlet to add the MyCompany key to the +registry. The command uses the UseTransaction parameter (the alias is "usetx") +to include the command in the transaction. +```powershell New-Item MyCompany -UseTX +``` -Because the MyCompany key already exists in the registry, -the command fails, and the transaction is rolled back. +Because the MyCompany key already exists in the registry, the command fails, +and the transaction is rolled back. +```output New-Item : A key at this path already exists At line:1 char:9 + new-item <<<< MyCompany -usetx +``` -A Get-Transaction command confirms that the transaction -has been rolled back and that the SubscriberCount is 0. +A Get-Transaction command confirms that the transaction has been rolled back +and that the SubscriberCount is 0. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 0 RolledBack +``` -# EXAMPLE 6: CHANGING THE ROLLBACK PREFERENCE +### EXAMPLE 6: CHANGING THE ROLLBACK PREFERENCE - -If you want the transaction to be more error tolerant, -you can use the RollbackPreference parameter of -Start-Transaction to change the preference. +If you want the transaction to be more error tolerant, you can use the +RollbackPreference parameter of Start-Transaction to change the preference. The following command starts a transaction with a rollback preference of "Never". +```powershell start-transaction -rollbackpreference Never +``` -In this case, when the command fails, the transaction -is not automatically rolled back. +In this case, when the command fails, the transaction is not automatically +rolled back. +```powershell New-Item MyCompany -UseTX +``` +```output New-Item : A key at this path already exists At line:1 char:9 + new-item <<<< MyCompany -usetx +``` -Because the transaction is still active, you can -resubmit the command as part of the transaction. +Because the transaction is still active, you can resubmit the command as part +of the transaction. +```powershell New-Item MyOtherCompany -UseTX +``` -# EXAMPLE 7: USING THE USE-TRANSACTION CMDLET - +### EXAMPLE 7: USING THE USE-TRANSACTION CMDLET -The Use-Transaction cmdlet enables you to do direct scripting -against transaction-enabled Microsoft .NET Framework objects. -Use-Transaction takes a script block that can only contain commands -and expressions that use transaction-enabled .NET Framework objects, -such as instances of the +The Use-Transaction cmdlet enables you to do direct scripting against +transaction-enabled Microsoft .NET Framework objects. Use-Transaction takes a +script block that can only contain commands and expressions that use +transaction-enabled .NET Framework objects, such as instances of the Microsoft.PowerShell.Commands.Management.TransactedString class. The following command starts a transaction. +```powershell start-transaction +``` -The following New-Object command creates an instance of the -TransactedString class and saves it in the $t variable. +The following New-Object command creates an instance of the TransactedString +class and saves it in the $t variable. +```powershell $t = New-Object Microsoft.PowerShell.Commands.Management.TransactedString +``` -The following command uses the Append method of the TransactedString -object to add text to the string. Because the command is not part -of the transaction, the change is effective immediately. +The following command uses the Append method of the TransactedString object to +add text to the string. Because the command is not part of the transaction, +the change is effective immediately. +```powershell $t.append("Windows") +``` -The following command uses the same Append method to add text, but -it adds the text as part of the transaction. The command is enclosed -in braces, and it is set as the value of the ScriptBlock parameter of -Use-Transaction. The UseTransaction parameter (UseTx) is required. +The following command uses the same Append method to add text, but it adds the +text as part of the transaction. The command is enclosed in braces, and it is +set as the value of the ScriptBlock parameter of Use-Transaction. The +UseTransaction parameter (UseTx) is required. +```powershell use-transaction {$t.append(" PowerShell")} -usetx +``` -To see the current content of the transacted string in $t, use the -ToString method of the TransactedString object. +To see the current content of the transacted string in $t, use the ToString +method of the TransactedString object. +```powershell $t.tostring() +``` The output shows that only the non-transacted changes are effective. +```output Windows +``` -To see the current content of the transacted string in $t from within -the transaction, embed the expression in a Use-Transaction command. +To see the current content of the transacted string in $t from within the +transaction, embed the expression in a Use-Transaction command. +```powershell use-transaction {$s.tostring()} -usetx +``` The output shows the transaction view. -Windows PowerShell +```output +PowerShell +``` The following command commits the transaction. +```powershell complete-transaction +``` To see the final string: +``` $t.tostring() +PowerShell +``` -Windows PowerShell +### EXAMPLE 8: MANAGING MULTI-SUBSCRIBER TRANSACTIONS -# EXAMPLE 8: MANAGING MULTI-SUBSCRIBER TRANSACTIONS - - -When you start a transaction while another transaction is in -progress, Windows PowerShell does not create a second transaction -by default. Instead, it adds a subscriber to the current -transaction. +When you start a transaction while another transaction is in progress, +PowerShell does not create a second transaction by default. Instead, it adds a +subscriber to the current transaction. -This example shows how to view and manage a multi-subscriber -transaction. +This example shows how to view and manage a multi-subscriber transaction. Begin by starting a transaction in the HKCU:\Software key. +```powershell start-transaction +``` -The following command uses the Get-Transaction command to -get the active transaction. +The following command uses the Get-Transaction command to get the active +transaction. +```powershell get-transaction +``` The result shows the object that represents the active transaction. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The following command adds the MyCompany key to the registry. -The command uses the UseTransaction parameter to include the -command in the transaction. +The following command adds the MyCompany key to the registry. The command uses +the UseTransaction parameter to include the command in the transaction. +```powershell new-item MyCompany -UseTransaction +``` -The following command uses the Start-Transaction command to -start a transaction. Although this command is typed at the command -prompt, this scenario is more likely to happen when you run a -script that contains a transaction. +The following command uses the Start-Transaction command to start a +transaction. Although this command is typed at the command prompt, this +scenario is more likely to happen when you run a script that contains a +transaction. +```powershell start-transaction +``` -A Get-Transaction command shows that the subscriber count on the -transaction object is incremented. The value is now 2. +A Get-Transaction command shows that the subscriber count on the transaction +object is incremented. The value is now 2. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 2 Active +``` -The next command uses the New-ItemProperty cmdlet to add the -MyKey registry entry to the MyCompany key. It uses the UseTransaction -parameter to include the command in the transaction. +The next command uses the New-ItemProperty cmdlet to add the MyKey registry +entry to the MyCompany key. It uses the UseTransaction parameter to include +the command in the transaction. +```powershell new-itemproperty -path MyCompany -name MyKey -UseTransaction +``` -The MyCompany key does not exist in the registry, but this -command succeeds because the two commands are part of the -same transaction. +The MyCompany key does not exist in the registry, but this command succeeds +because the two commands are part of the same transaction. -The following command commits the transaction. If it rolled back -the transaction, the transaction would be rolled back for all the -subscribers. +The following command commits the transaction. If it rolled back the +transaction, the transaction would be rolled back for all the subscribers. +```powershell complete-transaction +``` -A Get-Transaction command shows that the subscriber count on the -transaction object is 1, but the value of Status is still Active -(not Committed). +A Get-Transaction command shows that the subscriber count on the transaction +object is 1, but the value of Status is still Active (not Committed). +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -To finish committing the transaction, enter a second Complete- -Transaction command. To commit a multi-subscriber transaction, -you must enter one Complete-Transaction command for each -Start-Transaction command. +To finish committing the transaction, enter a second Complete- Transaction +command. To commit a multi-subscriber transaction, you must enter one +Complete-Transaction command for each Start-Transaction command. +```powershell complete-transaction +``` -Another Get-Transaction command shows that the transaction -has been committed. +Another Get-Transaction command shows that the transaction has been committed. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 0 Committed +``` -# EXAMPLE 9: MANAGING INDEPENDENT TRANSACTIONS - +### EXAMPLE 9: MANAGING INDEPENDENT TRANSACTIONS -When you start a transaction while another transaction is in -progress, you can use the Independent parameter of Start-Transaction -to make the new transaction independent of the original transaction. +When you start a transaction while another transaction is in progress, you can +use the Independent parameter of Start-Transaction to make the new transaction +independent of the original transaction. -When you do, Start-Transaction creates a new transaction object -and makes the new transaction the active transaction. +When you do, Start-Transaction creates a new transaction object and makes the +new transaction the active transaction. -Begin by starting a transaction in the HKCU:\Software key. +Begin by starting a transaction in the HKCU:\\Software key. +```powershell start-transaction +``` -The following command uses the Get-Transaction command to -get the active transaction. +The following command uses the Get-Transaction command to get the active +transaction. +```powershell get-transaction +``` The result shows the object that represents the active transaction. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The following command adds the MyCompany registry key as part of -the transaction. It uses the UseTransaction parameter (UseTx) -to include the command in the active transaction. +The following command adds the MyCompany registry key as part of the +transaction. It uses the UseTransaction parameter (UseTx) to include the +command in the active transaction. +```powershell new-item MyCompany -use +``` -The following command starts a new transaction. The command uses -the Independent parameter to indicate that this transaction -is not a subscriber to the active transaction. +The following command starts a new transaction. The command uses the +Independent parameter to indicate that this transaction is not a subscriber to +the active transaction. +```powershell start-transaction -independent +``` -When you create an independent transaction, the new (most-recently -created) transaction becomes the active transaction. You can use -a Get-Transaction command to get the active transaction. +When you create an independent transaction, the new (most-recently created) +transaction becomes the active transaction. You can use a Get-Transaction +command to get the active transaction. +```powershell get-transaction +``` -Note that the SubscriberCount of the transaction is 1, indicating -that there are no other subscribers and that the transaction is -new. +Note that the SubscriberCount of the transaction is 1, indicating that there +are no other subscribers and that the transaction is new. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The new transaction must be finished (either committed or rolled -back) before you can manage the original transaction. +The new transaction must be finished (either committed or rolled back) before +you can manage the original transaction. -The following command adds the MyOtherCompany key to the registry. -It uses the UseTransaction parameter (UseTx) to include the command -in the active transaction. +The following command adds the MyOtherCompany key to the registry. It uses the +UseTransaction parameter (UseTx) to include the command in the active +transaction. +```powershell new-item MyOtherCompany -usetx +``` -Now, roll back the transaction. If there were a single -transaction with two subscribers, rolling back the transaction -would roll back the entire transaction for all the subscribers. +Now, roll back the transaction. If there were a single transaction with two +subscribers, rolling back the transaction would roll back the entire +transaction for all the subscribers. -However, because these transactions are independent, rolling -back the newest transaction cancels the registry changes and -makes the original transaction the active transaction. +However, because these transactions are independent, rolling back the newest +transaction cancels the registry changes and makes the original transaction +the active transaction. +```powershell undo-transaction +``` -A Get-Transaction command confirms that the original -transaction is still active in the session. +A Get-Transaction command confirms that the original transaction is still +active in the session. +```powershell get-transaction +``` +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` The following command commits the active transaction. +```powershell complete-transaction +``` -A Get-ChildItem command shows that the registry has been -changed. +A Get-ChildItem command shows that the registry has been changed. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# SEE ALSO +## SEE ALSO -Start-Transaction +[Start-Transaction](../../Microsoft.PowerShell.Management/Start-Transaction.md) -Get-Transaction +[Get-Transaction](../../Microsoft.PowerShell.Management/Get-Transaction.md) -Complete-Transaction +[Complete-Transaction](../../Microsoft.PowerShell.Management/Complete-Transaction.md) -Undo-Transaction +[Undo-Transaction](../../Microsoft.PowerShell.Management/Undo-Transaction.md) -Use-Transaction +[Use-Transaction](../../Microsoft.PowerShell.Management/Use-Transaction.md) -Registry (provider) +[Get-PSProvider](../../Microsoft.PowerShell.Management/Get-PSProvider.md) -[about_Providers](about_Providers.md) - -Get-PSProvider - -Get-ChildItem +[Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) +[about_Providers](about_Providers.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index 8c83f99a3472..7d45f6555135 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,487 +7,455 @@ title: about_Updatable_Help --- # About Updatable Help -## about_Updatable_Help +## SHORT DESCRIPTION +Describes the updatable help system in PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes the updatable help system in Windows PowerShell. +PowerShell provides several different ways to access the most up-to-date help +topics for PowerShell cmdlets and concepts. -# LONG DESCRIPTION +The Updatable Help system, introduced in PowerShell 3.0, is designed to assure +that you always have the newest help topics on your local computer so that you +can read them at the command line. It makes it easy to download and install +help files and to update them whenever newer help files become available. -Windows PowerShell provides several different ways to access -the most up-to-date help topics for Windows PowerShell cmdlets -and concepts. +To provide updated help for multiple computers in an enterprise and for +computers that do not have access to the Internet, Updatable Help lets you +download help files to a file system directory or file share, and then install +the help files from the file share. -The Updatable Help system, introduced in Windows PowerShell 3.0, -is designed to assure that you always have the newest help topics -on your local computer so that you can read them at the command -line. It makes it easy to download and install help files and -to update them whenever newer help files become available. +In PowerShell 4.0, the HelpInfoUri property is preserved over Windows +PowerShell remoting, which allows Save-Help to work for modules that are +installed on a remote computer, but are not necessarily installed on the local +computer. You can save a PSModuleInfo object to disk or removable media (such +as a USB drive) by running Export-Clixml on a computer that does not have +Internet access, importing the PSModuleInfo object on a computer that does +have Internet access, and then running Save-Help on the PSModuleInfo object. +The saved help can be copied to the remote, disconnected computer by using +removable media, and then installed by running Update-Help. These improvements +in Save-Help functionality let you install help on computers that are without +any kind of network access. For an example of how to use the new Save-Help +functionality, see "HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP" in this +topic. -To provide updated help for multiple computers in an enterprise -and for computers that do not have access to the Internet, Updatable -Help lets you download help files to a file system directory or file -share, and then install the help files from the file share. +Updatable Help also supports online access to the newest help topics and basic +help for cmdlets, even when there are no help files on the computer. -In Windows PowerShell 4.0, the HelpInfoUri property is preserved over -Windows PowerShell remoting, which allows Save-Help to work for -modules that are installed on a remote computer, but are not -necessarily installed on the local computer. You can save a PSModuleInfo -object to disk or removable media (such as a USB drive) by running -Export-Clixml on a computer that does not have Internet access, -importing the PSModuleInfo object on a computer that does have Internet -access, and then running Save-Help on the PSModuleInfo object. The -saved help can be copied to the remote, disconnected computer by using -removable media, and then installed by running Update-Help. These -improvements in Save-Help functionality let you install help on -computers that are without any kind of network access. For an example -of how to use the new Save-Help functionality, see "HOW TO UPDATE HELP -FROM A FILE SHARE: SAVE-HELP" in this topic. +PowerShell 3.0 does not come with Help files. You can use the Updatable Help +feature to install the help files for all of the commands that are included by +default in PowerShell and for all Windows modules. -Updatable Help also supports online access to the newest help topics -and basic help for cmdlets, even when there are no help files on the -computer. - -Windows PowerShell 3.0 does not come with Help files. You can use -the Updatable Help feature to install the help files for all of the -commands that are included by default in Windows PowerShell and for -all Windows modules. - -# UPDATABLE HELP CMDLETS - - -Update-Help: Downloads the newest help files from the Internet or -a file share, and installs them on the local computer. - -Save-Help: Downloads the newest help files from the Internet and -saves them in a file system directory or file share. To -install the help files on computers, use Update-Help. +## UPDATABLE HELP CMDLETS -Get-Help: -- Displays help topics at the command line. --- Gets help from the help files on the computer. --- Displays auto-generated help for cmdlets and functions -that do not have help files. --- Opens online help topics for cmdlets, functions, -scripts, and workflows in your default Internet -browser. +- Update-Help: Downloads the newest help files from the Internet or a file + share, and installs them on the local computer. -# UPDATE HELP IN WINDOWS POWERSHELL ISE +- Save-Help: Downloads the newest help files from the Internet and saves them in + a file system directory or file share. To install the help files on computers, + use Update-Help. -You can also update help by using the "Update Windows PowerShell -Help" item in the Help menu in Windows PowerShell Integrated -Scripting Environment (ISE). +- Get-Help: Displays help topics at the command line. Gets help from the + help files on the computer. Displays auto-generated help for cmdlets and + functions that do not have help files. Opens online help topics for + cmdlets, functions, scripts, and workflows in your default Internet browser. -The "Update Windows PowerShell Help" item runs an Update-Help -command without parameters. +## UPDATE HELP IN PowerShell ISE -# AUTO-GENERATED HELP: HELP WITHOUT HELP FILES +You can also update help by using the "Update PowerShell Help" item in the +Help menu in PowerShell Integrated Scripting Environment (ISE). +The "Update PowerShell Help" item runs an Update-Help command without +parameters. -If you do not have the help file for a cmdlet, function, -or workflow on the computer, the Get-Help cmdlet displays -auto-generated help and prompts you to download the help -files or read them online. +## AUTO-GENERATED HELP: HELP WITHOUT HELP FILES -Auto-generated help includes syntax and aliases, and remarks -that explain how to use the Updatable Help cmdlets and to -access the online help topics. +If you do not have the help file for a cmdlet, function, or workflow on the +computer, the Get-Help cmdlet displays auto-generated help and prompts you to +download the help files or read them online. -For example, the following command gets basic help for the -Get-Culture cmdlet. The output shows the Get-Help display -when there are no help files on the computer. +Auto-generated help includes syntax and aliases, and remarks that explain how +to use the Updatable Help cmdlets and to access the online help topics. -PS C:> Get-Help Get-Culture - -# NAME - -Get-Culture - -# SYNTAX +For example, the following command gets basic help for the Get-Culture cmdlet. +The output shows the Get-Help display when there are no help files on the +computer. -Get-Culture [] +```powershell +Get-Help Get-Culture +``` -# ALIASES +```output +NAME + Get-Culture -None +SYNTAX + Get-Culture [] -# REMARKS +ALIASES + None -To get the latest Help content including descriptions -and examples type: Update-Help. +REMARKS + To get the latest Help content including descriptions and examples + type: Update-Help. +``` -# HELP FILES FOR MODULES +## HELP FILES FOR MODULES +The smallest unit of Updatable Help is help for a module. Module help includes +help for all of the cmdlets, functions, workflows, providers, scripts, and +concepts in a module. You can update help for all modules that are installed +on the computer, even if they are not imported into the current session. -The smallest unit of Updatable Help is help for a module. Module -help includes help for all of the cmdlets, functions, workflows, -providers, scripts, and concepts in a module. You can update help -for all modules that are installed on the computer, even if they -are not imported into the current session. +You can update help for the entire module, but you cannot update help for +individual cmdlets. -You can update help for the entire module, but you cannot update -help for individual cmdlets. - -To find the module that contains a particular cmdlet, use the -following command format: +To find the module that contains a particular cmdlet, use the following +command format: +```powershell (Get-Command ).ModuleName +``` For example, to find the module that contains the Set-ExecutionPolicy cmdlet, type: +```powershell (Get-Command Set-ExecutionPolicy).ModuleName +``` To update help for a particular module, type: +```powershell Update-Help -Module +``` For example, to update help for the module that contains the Set-ExecutionPolicy cmdlet, type: +```powershell Update-Help -Module Microsoft.PowerShell.Security +``` -# PERMISSIONS FOR UPDATABLE HELP - - -To update help for the modules in the $pshome\Modules directory, -you must be member of the Administrators group on the computer. +## PERMISSIONS FOR UPDATABLE HELP -If you are not a member of the Administrators group, you cannot -update help for these modules; but if you have Internet access, -you can view help online in the TechNet Library. +To update help for the modules in the \$pshome\\Modules directory, you must be +member of the Administrators group on the computer. -Updating help for modules in the -$home\Documents\WindowsPowerShell\Modules -directory or modules in other subdirectories of the $home -directory do not require special permissions. +If you are not a member of the Administrators group, you cannot update help +for these modules; but if you have Internet access, you can view help online +in the TechNet Library. -The Update-Help and Save-Help cmdlets have a UseDefaultCredentials -parameter that provides the explicit credentials of the current -user. This parameter is designed for accessing secure Internet -locations. +Updating help for modules in the \$home\\Documents\\WindowsPowerShell\\Modules +directory or modules in other subdirectories of the \$home directory do not +require special permissions. -The Update-Help and Save-Help cmdlets also have a Credential -parameter that allows you to run the command on a remote -computer and access a file share on a third computer. The -Credential parameter is valid only when you use the SourcePath -or LiteralPath parameters of Update-Help and the DestinationPath -or LiteralPath parameters of Save-Help. +The Update-Help and Save-Help cmdlets have a UseDefaultCredentials parameter +that provides the explicit credentials of the current user. This parameter is +designed for accessing secure Internet locations. -# HOW TO INSTALL AND UPDATE HELP FILES +The Update-Help and Save-Help cmdlets also have a Credential parameter that +allows you to run the command on a remote computer and access a file share on +a third computer. The Credential parameter is valid only when you use the +SourcePath or LiteralPath parameters of Update-Help and the DestinationPath or +LiteralPath parameters of Save-Help. +## HOW TO INSTALL AND UPDATE HELP FILES -To download and install help files for the first time, or to update -the help files on your computer, use the Update-Help cmdlet. +To download and install help files for the first time, or to update the help +files on your computer, use the Update-Help cmdlet. -The Update-Help cmdlet does all of the hard work for you, including -the following tasks. +The Update-Help cmdlet does all of the hard work for you, including the +following tasks. --- Determines which modules support Updatable Help. --- Finds the Internet location where each module stores its -Updatable Help files. --- Compares the help files for each module on your computer to -the newest help files that are available for each module. --- Downloads the new files from the Internet. --- Unwraps the help file package. --- Verifies that the files are valid help files. --- Installs the help files in the language-specific subdirectory -of the module directory. +- Determines which modules support Updatable Help. +- Finds the Internet location where each module stores its Updatable Help files. +- Compares the help files for each module on your computer to the newest help + files that are available for each module. +- Downloads the new files from the Internet. +- Unwraps the help file package. +- Verifies that the files are valid help files. +- Installs the help files in the language-specific subdirectory of the module + directory. -To access the new help topics, use the Get-Help cmdlet. You do not -need to restart Windows PowerShell. +To access the new help topics, use the Get-Help cmdlet. You do not need to +restart PowerShell. -To install or update help for all modules on the computer that -supports Updatable Help, type: +To install or update help for all modules on the computer that supports +Updatable Help, type: +```powershell Update-Help +``` -To update help for particular modules, add the Module parameter -of Update-Help. Wildcard characters are permitted in the module name. +To update help for particular modules, add the Module parameter of +Update-Help. Wildcard characters are permitted in the module name. For example, to update help for the ServerManager module, type: +```powershell Update-Help -Module ServerManager - -# NOTES - -Without parameters, Update-Help updates help for all modules -in the session and for all installed modules that support -Updatable Help. To be included, modules must be installed in -directories that are listed in the value of the PSModulePath -environment variable. These are also modules that -are returned by a "Get-Help -ListAvailable" command. - -If the value of the Module parameter is * (all), Update-Help -attempts to update help for all installed modules, including -modules that do not support Updatable Help. This command -typically generates many errors as the cmdlet encounters modules -that do not support Updatable Help. - -# HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP - - -To support computers that are not connected to the Internet, -or to control or streamline help updating in an enterprise, -use the Save-Help cmdlet. The Save-Help cmdlet downloads help -files from the Internet and saves them in a file system directory -that you specify. - -Save-Help compares the help files in the specified directory to -the newest help files that are available for each module. If the -directory has no help files or newer help files are available for -the module, the Save-Help cmdlet downloads the new files from the -Internet. However, it does not unwrap or install the help files. - -To install or update the help files on a computer from help -files that were saved to a file system directory, use the -SourcePath parameter of the Update-Help cmdlet. The Update-Help -cmdlet identifies the newest help files, unwraps and validates them, -and installs them in the language-specific subdirectories of the -module directories. - -For example, to save help for all installed modules to the -\Server\Share directory, type: - -Save-Help -DestinationPath \Server\Share - -Then, to update help from the \Server\Share directory, type: - -Update-Help -SourcePath \Server\Share - -The following examples show the use of Save-Help to save help -for modules that are not installed on the local computer. In -this example, the administrator runs Save-Help to save the help -for the DhcpServer module from an Internet-connected client computer, -without installing the DhcpServer module or DHCP Server role on the -local computer. - -Option 1: Run Invoke-Command to get the PSModuleInfo object for -the remote module, save it in a variable, $m, and then run Save-Help -on the PSModuleInfo object by specifying the variable $m as the -module name. - +``` + +Without parameters, Update-Help updates help for all modules in the session +and for all installed modules that support Updatable Help. To be included, +modules must be installed in directories that are listed in the value of the +PSModulePath environment variable. These are also modules that are returned by +a "Get-Help -ListAvailable" command. + +If the value of the Module parameter is * (all), Update-Help attempts to +update help for all installed modules, including modules that do not support +Updatable Help. This command typically generates many errors as the cmdlet +encounters modules that do not support Updatable Help. + +## HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP + +To support computers that are not connected to the Internet, or to control or +streamline help updating in an enterprise, use the Save-Help cmdlet. The +Save-Help cmdlet downloads help files from the Internet and saves them in a +file system directory that you specify. + +Save-Help compares the help files in the specified directory to the newest +help files that are available for each module. If the directory has no help +files or newer help files are available for the module, the Save-Help cmdlet +downloads the new files from the Internet. However, it does not unwrap or +install the help files. + +To install or update the help files on a computer from help files that were +saved to a file system directory, use the SourcePath parameter of the +Update-Help cmdlet. The Update-Help cmdlet identifies the newest help files, +unwraps and validates them, and installs them in the language-specific +subdirectories of the module directories. + +For example, to save help for all installed modules to the \\\\Server\\Share +directory, type: + +```powershell +Save-Help -DestinationPath \\Server\Share +``` + +Then, to update help from the \\\\Server\\Share directory, type: + +```powershell +Update-Help -SourcePath \\Server\Share +``` + +The following examples show the use of Save-Help to save help for modules that +are not installed on the local computer. In this example, the administrator +runs Save-Help to save the help for the DhcpServer module from an +Internet-connected client computer, without installing the DhcpServer module +or DHCP Server role on the local computer. + +Option 1: Run Invoke-Command to get the PSModuleInfo object for the remote +module, save it in a variable, $m, and then run Save-Help on the PSModuleInfo +object by specifying the variable $m as the module name. + +```powershell $m = Invoke-Command -ComputerName RemoteServer -ScriptBlock { Get-Module -Name DhcpServer -ListAvailable } Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -Option 2: Open a PSSession, targeted at the computer that is -running the DHCP Server module, to get the PSModuleInfo object for -the module, save it in a variable $m, and then run Save-Help on the -object that is saved in the $m variable. +Option 2: Open a PSSession, targeted at the computer that is running the DHCP +Server module, to get the PSModuleInfo object for the module, save it in a +variable $m, and then run Save-Help on the object that is saved in the $m +variable. +```powershell $s = New-PSSession -ComputerName RemoteServer $m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -Option 3: Open a CIM session, targeted at the computer that is -running the DHCP Server module, to get the PSModuleInfo object for -the module, save it in a variable $m, and then run Save-Help on the -object that is saved in the $m variable. +Option 3: Open a CIM session, targeted at the computer that is running the +DHCP Server module, to get the PSModuleInfo object for the module, save it in +a variable $m, and then run Save-Help on the object that is saved in the $m +variable. +```powershell $c = New-CimSession -ComputerName RemoteServer $m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -In the following example, the administrator installs help for the -DHCP Server module on a computer that does not have network access. +In the following example, the administrator installs help for the DHCP Server +module on a computer that does not have network access. -First, run Export-Clixml to export the PSModuleInfo object to -a shared folder or to removable media. +First, run Export-Clixml to export the PSModuleInfo object to a shared folder +or to removable media. +```powershell $m = Get-Module -Name DhcpServer -ListAvailable Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m +``` -Next, transport the removable media to a computer that has -Internet access, and then import the PSModuleInfo object with -Import-Clixml. Run Save-Help to save the Help for the imported -DhcpServer module PSModuleInfo object. +Next, transport the removable media to a computer that has Internet access, +and then import the PSModuleInfo object with Import-Clixml. Run Save-Help to +save the Help for the imported DhcpServer module PSModuleInfo object. +```powershell $deserialized_m = Import-Clixml E:\UsbFlashDrive\DhcpModule.xml -Save-Help -Module $deserialized_m -DestinationPath -E:\UsbFlashDrive\SavedHelp - -Finally, transport the removable media back to the computer that -does not have network access, and then install the help by running -Update-Help. - -Update-Help -Module DhcpServer -SourcePath +Save-Help -Module $deserialized_m -DestinationPath ` E:\UsbFlashDrive\SavedHelp +``` -# NOTES: +Finally, transport the removable media back to the computer that does not have +network access, and then install the help by running Update-Help. -Without parameters, Save-Help downloads help for all modules -in the session and for all installed modules that support -Updatable Help. To be included, modules must be installed in -directories that are listed in the value of the PSModulePath -environment variable, on either the local computer or on a remote -computer for which you want to save help. These are also modules -that are returned by running a "Get-Help -ListAvailable" command. +```powershell +Update-Help -Module DhcpServer -SourcePath E:\UsbFlashDrive\SavedHelp +``` -# HOW TO UPDATE HELP FILES IN DIFFERENT LANGUAGES +Without parameters, Save-Help downloads help for all modules in the session +and for all installed modules that support Updatable Help. To be included, +modules must be installed in directories that are listed in the value of the +PSModulePath environment variable, on either the local computer or on a remote +computer for which you want to save help. These are also modules that are +returned by running a "Get-Help -ListAvailable" command. +## HOW TO UPDATE HELP FILES IN DIFFERENT LANGUAGES -By default, the Update-Help and Save-Help cmdlets download -help in the UI culture and language that is set for Windows -on the local computer. If help files for the specified modules -are not available in the local UI culture, Update-Help and -Save-Help use the Windows language fallback rules to find the +By default, the Update-Help and Save-Help cmdlets download help in the UI +culture and language that is set for Windows on the local computer. If help +files for the specified modules are not available in the local UI culture, +Update-Help and Save-Help use the Windows language fallback rules to find the best supported language. -However, you can use the UICulture parameters of the Update-Help -and Save-Help cmdlets to download and install help files in any -UI cultures in which they are available. +However, you can use the UICulture parameters of the Update-Help and Save-Help +cmdlets to download and install help files in any UI cultures in which they +are available. -For example, to save the newest help files for all modules on -the session in Japanese (Ja-jp) and French (fr-FR), type: +For example, to save the newest help files for all modules on the session in +Japanese (Ja-jp) and French (fr-FR), type: +```powershell Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr +``` -If help files for the modules are not available in the languages -that you specified, the Update-Help and Save-Help cmdlets return -an error message that lists the languages in which help for each -module is available so you can choose the alternative that best -meets your needs. +If help files for the modules are not available in the languages that you +specified, the Update-Help and Save-Help cmdlets return an error message that +lists the languages in which help for each module is available so you can +choose the alternative that best meets your needs. -# HOW TO UPDATE HELP AUTOMATICALLY +## HOW TO UPDATE HELP AUTOMATICALLY +To assure that you always have the newest help files, you can add an +Update-Help command to your PowerShell profile. -To assure that you always have the newest help files, you can -add an Update-Help command to your Windows PowerShell profile. +An internal quota prevents the Update-Help command from running more than once +each day. To override the once-per-day maximum, use the Force parameter. -An internal quota prevents the Update-Help command from running -more than once each day. To override the once-per-day maximum, -use the Force parameter. - -Use a command like the following one in your profile. This command -updates help for all installed modules in a background job so it -doesn't disturb your work. It uses an Out-Null command to suppress -the job that is returned and any error messages that would otherwise -appear when you use the command more than once per day. +Use a command like the following one in your profile. This command updates +help for all installed modules in a background job so it doesn't disturb your +work. It uses an Out-Null command to suppress the job that is returned and any +error messages that would otherwise appear when you use the command more than +once per day. +```powershell Start-Job {Update-Help} | Out-Null +``` -You can also create a scheduled job that runs the Update-Help or -Save-Help cmdlet at any interval. +You can also create a scheduled job that runs the Update-Help or Save-Help +cmdlet at any interval. For example, the following command creates a scheduled job that runs an -Update-Help help command every Friday at 5:00 AM. To run this command, -start Windows PowerShell with the "Run as administrator" option. +Update-Help help command every Friday at 5:00 AM. To run this command, start +PowerShell with the "Run as administrator" option. +```powershell Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} ` -Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM") +``` -For more information about scheduled jobs, see about_Scheduled_Jobs. - -# HOW TO USE ONLINE HELP - +## HOW TO USE ONLINE HELP -If you cannot or choose not to update the help files on your -local computer, you can still get the newest help files online. +If you cannot or choose not to update the help files on your local computer, +you can still get the newest help files online. -To open the online help topic for any cmdlet or function, use -the Online parameter of the Get-Help cmdlet. +To open the online help topic for any cmdlet or function, use the Online +parameter of the Get-Help cmdlet. -For example, the following command opens the online help topic -for the Get-Job cmdlet in your default Internet browser: +For example, the following command opens the online help topic for the Get-Job +cmdlet in your default Internet browser: +```powershell Get-Help Get-Job -Online --or- -Get-Help -on Get-Job - -To get online help for a script, use the Online parameter and -the full path to the script. - -The Online parameter does not work with About topics. To see -the about topics for Windows PowerShell Core, including help -topics about the Windows PowerShell language, see "Windows -PowerShell Core Module About Topics" at -http://go.microsoft.com/fwlink/?LinkID=113206. - -# HOW TO MINIMIZE OR PREVENT INTERNET DOWNLOADS - -To minimize Internet downloads and provide Updatable Help to -users who are not connected to the Internet, use the Save-Help -cmdlet. Download help from the Internet and save it to a network -share. Then, create a Group Policy setting or scheduled job that -runs an Update-Help command on all computers. Set the value of -the SourcePath parameter of the Update-Help cmdlet to the network -share. - -To prevent users who have Internet access from downloading Updatable -Help from the Internet, use the "Set the default source path for -Update-Help" Group Policy setting. +``` -This Group Policy setting implicitly adds the SourcePath parameter, -with the file system location that you specify, to every Update-Help -command on every affected computer. Users can use the SourcePath -parameter explicitly to specify a different file system location, but -they cannot exclude the SourcePath parameter and download help from -the Internet. +To get online help for a script, use the Online parameter and the full path to +the script. -NOTE: The "Set the default source path for Update-Help" group -policy setting appears under Computer Configuration and -User Configuration. However, only the policy setting -under Computer Configuration is effective. The policy -setting under User Configuration is ignored. +The Online parameter does not work with About topics. To see the about topics +for PowerShell Core, including help topics about the PowerShell language, see +[Windows PowerShell Core Module About Topics](http://go.microsoft.com/fwlink/?LinkID=113206). -For more information, see about_Group_Policy_Settings. +## HOW TO MINIMIZE OR PREVENT INTERNET DOWNLOADS -# HOW TO UPDATE HELP FOR NON-STANDARD MODULES +To minimize Internet downloads and provide Updatable Help to users who are not +connected to the Internet, use the Save-Help cmdlet. Download help from the +Internet and save it to a network share. Then, create a Group Policy setting +or scheduled job that runs an Update-Help command on all computers. Set the +value of the SourcePath parameter of the Update-Help cmdlet to the network +share. -To update or save help for a module that is not returned -by the ListAvailable parameter of the Get-Module cmdlet, -import the module into the current session before running -an Update-Help or Save-Help command. On a remote computer, -before running the Save-Help command, import the module into -the current CIM or PSSession--or Invoke-Command script block-- -that is connected to the remote computer. +To prevent users who have Internet access from downloading Updatable Help from +the Internet, use the "Set the default source path for Update-Help" Group +Policy setting. -When the module is in the current session, run the Update-Help -or Save-Help cmdlets without parameters, or use the Module -parameter to specify the module name. +This Group Policy setting implicitly adds the SourcePath parameter, with the +file system location that you specify, to every Update-Help command on every +affected computer. Users can use the SourcePath parameter explicitly to +specify a different file system location, but they cannot exclude the +SourcePath parameter and download help from the Internet. -The Module parameters of the Update-Help and Save-Help -cmdlets accept only a module name. They do not accept the -path to a module file. +NOTE: The "Set the default source path for Update-Help" group policy setting +appears under Computer Configuration and User Configuration. However, only the +policy setting under Computer Configuration is effective. The policy setting +under User Configuration is ignored. -Use this technique to update or save help for any module -that is not returned by the ListAvailable parameter of the -Get-Module cmdlet, such as a module that is installed in a -location that is not listed in the PSModulePath environment -variable, or a module that is not well-formed (the module -directory does not contain at least one file whose base name -is the same as the directory name). +For more information, see [about_Group_Policy_Settings](about_Group_Policy_Settings.md). -# HOW TO SUPPORT UPDATABLE HELP +## HOW TO UPDATE HELP FOR NON-STANDARD MODULES +To update or save help for a module that is not returned by the ListAvailable +parameter of the Get-Module cmdlet, import the module into the current session +before running an Update-Help or Save-Help command. On a remote computer, +before running the Save-Help command, import the module into the current CIM +or PSSession--or Invoke-Command script block-- that is connected to the remote +computer. -If you author a module, you can support online help and -Updatable Help for your modules. For more information, see -"Supporting Updatable Help" and "Supporting Online Help" -in the MSDN Library. +When the module is in the current session, run the Update-Help or Save-Help +cmdlets without parameters, or use the Module parameter to specify the module +name. -Updatable help not available for Windows PowerShell snap-ins -or comment-based help. +The Module parameters of the Update-Help and Save-Help cmdlets accept only a +module name. They do not accept the path to a module file. -# KEYWORDS +Use this technique to update or save help for any module that is not returned +by the ListAvailable parameter of the Get-Module cmdlet, such as a module that +is installed in a location that is not listed in the PSModulePath environment +variable, or a module that is not well-formed (the module directory does not +contain at least one file whose base name is the same as the directory name). -About_Updateable_Help +## HOW TO SUPPORT UPDATABLE HELP -# REMARKS +If you author a module, you can support online help and Updatable Help for +your modules. For more information, see "Supporting Updatable Help" and +"Supporting Online Help" in the MSDN Library. -The Update-Help and Save-Help cmdlets are not supported on -Windows Preinstallation Environment (Windows PE). +Updatable help not available for PowerShell snap-ins or comment-based help. -# SEE ALSO +# REMARKS -Get-Help +The Update-Help and Save-Help cmdlets are not supported on Windows +Preinstallation Environment (Windows PE). -Save-Help +## SEE ALSO -Update-Help +[Get-Help](../Get-Help.md) -Updatable Help Status Table (http://go.microsoft.com/fwlink/?LinkID=270007) +[Save-Help](../Save-Help.md) +[Update-Help](../Update-Help.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI.md index fe279908cfc3..bafb6c425a08 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_WMI.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,84 +7,104 @@ title: about_WMI --- # About WMI -## about_WMI - ## SHORT DESCRIPTION -Windows Management Instrumentation (WMI) uses the Common Information Model (CIM) to represent systems, applications, networks, devices, and other manageable components of the modern enterprise. +Windows Management Instrumentation (WMI) uses the Common Information Model +(CIM) to represent systems, applications, networks, devices, and other +manageable components of the modern enterprise. ## LONG DESCRIPTION -Windows Management Instrumentation (WMI) is Microsoft’s implementation of Web-Based Enterprise Management (WBEM), the industry standard. -Classic WMI uses DCOM to communicate with networked devices to manage remote systems. Windows PowerShell® 3.0 introduces a CIM provider model that uses WinRM to remove the dependency on DCOM. This CIM provider model also uses new WMI provider APIs that enable developers to write Windows PowerShell cmdlets in native code (C\+\+). +Windows Management Instrumentation (WMI) is Microsoft’s implementation of +Web-Based Enterprise Management (WBEM), the industry standard. -Do not confuse WMI providers with Windows PowerShell providers. Many Windows features have an associated WMI provider that exposes their management capabilities. To get WMI providers, run a WMI query that gets instances of the __Provider WMI class, such as the following query. +Classic WMI uses DCOM to communicate with networked devices to manage remote +systems. Windows PowerShell® 3.0 introduces a CIM provider model that uses +WinRM to remove the dependency on DCOM. This CIM provider model also uses new +WMI provider APIs that enable developers to write Windows PowerShell cmdlets +in native code (C\+\+). +Do not confuse WMI providers with Windows PowerShell providers. Many Windows +features have an associated WMI provider that exposes their management +capabilities. To get WMI providers, run a WMI query that gets instances of the +__Provider WMI class, such as the following query. -``` +```powershell Get-WmiObject -Class __Provider ``` - - ## THREE COMPONENTS OF WMI -The following three components of WMI interact with Windows PowerShell: Namespaces, Providers, and Classes. -WMI Namespaces organize WMI providers and WMI classes into groups of related components. In this way, they are similar to .NET Framework namespaces. Namespaces are not physical locations, but are more like logical databases. All WMI namespaces are instances of the __Namespace system class. The default WMI namespace is Root\/CIMV2 (since Microsoft Windows 2000). To use Windows PowerShell to get WMI namespaces in the current session, use a command with the following format. +The following three components of WMI interact with Windows PowerShell: +Namespaces, Providers, and Classes. +WMI Namespaces organize WMI providers and WMI classes into groups of related +components. In this way, they are similar to .NET Framework namespaces. +Namespaces are not physical locations, but are more like logical databases. +All WMI namespaces are instances of the __Namespace system class. The default +WMI namespace is Root\/CIMV2 (since Microsoft Windows 2000). To use Windows +PowerShell to get WMI namespaces in the current session, use a command with +the following format. -``` +```powershell Get-WmiObject -Class __Namespace ``` +To get WMI namespaces in other namespaces, use the Namespace parameter to +change the location of the search. The following command finds WMI namespaces +that reside in the Root/Cimv2/Applications namespace. -To get WMI namespaces in other namespaces, use the Namespace parameter to change the location of the search. The following command finds WMI namespaces that reside in the Root\/Cimv2\/Applications namespace. - - -``` -Get-WmiObject -Class __Namespace -Namespace -root/CIMv2/applications +```powershell +Get-WmiObject -Class __Namespace -Namespace root/CIMv2/applications ``` +WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces +on a particular system requires performing a recursive query starting at the +root namespace. -WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces on a particular system requires performing a recursive query starting at the root namespace. - -WMI Providers expose information about Windows manageable objects. A provider retrieves data from a component, and passes that data through WMI to a management application, such as Windows PowerShell. Most WMI providers are dynamic providers, which means that they obtain the data dynamically when it is requested through the management application. - +WMI Providers expose information about Windows manageable objects. A provider +retrieves data from a component, and passes that data through WMI to a +management application, such as Windows PowerShell. Most WMI providers are +dynamic providers, which means that they obtain the data dynamically when it +is requested through the management application. ## FINDING WMI CLASSES -In a default installation of Windows 8, there are more than 1,100 WMI classes in Root\/Cimv2. With this many WMI classes, the challenge becomes identifying the appropriate WMI class to use to perform a specific task. Windows PowerShell 3.0 provides two ways to find WMI classes that are related to a specific topic. -For example,to find WMI classes in the root\CIMV2 WMI namespace that are related to disks, you can use a query such as the one shown here. +In a default installation of Windows 8, there are more than 1,100 WMI classes +in Root\/Cimv2. With this many WMI classes, the challenge becomes identifying +the appropriate WMI class to use to perform a specific task. Windows +PowerShell 3.0 provides two ways to find WMI classes that are related to a +specific topic. +For example,to find WMI classes in the root\\CIMV2 WMI namespace that are +related to disks, you can use a query such as the one shown here. -``` +```powershell Get-WmiObject -List *disk* ``` +To find WMI classes that are related to memory, you might use a query such as +the one shown here. -To find WMI classes that are related to memory, you might use a query such as the one shown here. - - -``` +```powershell Get-WmiObject -List *memory* ``` +The CIM cmdlets also provide the ability to discover WMI classes. To do this, +use the Get-CIMClass cmdlet. The command shown here lists WMI classes related +to video. -The CIM cmdlets also provide the ability to discover WMI classes. To do this, use the Get-CIMClass cmdlet. The command shown here lists WMI classes related to video. - - -``` +```powershell Get-CimClass *video* ``` +Tab expansion works when changing WMI namespaces, and therefore use of tab +expansion makes sub-WMI namespaces easily discoverable. In the following +example, the Get-CimClass cmdlet lists WMI classes related to power settings. +To find it, type the `root/CIMV2/` namespace and then press the Tab key +several times until the power namespace appears. Here is the command: -Tab expansion works when changing WMI namespaces, and therefore use of tab expansion makes sub-WMI namespaces easily discoverable. In the following example, the Get-CimClass cmdlet lists WMI classes related to power settings. To find it, type the root\/CIMV2\/ WMI namespace, and then press type the root\/CIMV2\/ WMI namespace, and then press the Tab key several times until the power namespace appears. Here is the command: - - -``` +```powershell Get-CimClass *power* -Namespace root/cimv2/power ``` - - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_WQL.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_WQL.md index 4413e4b4bf38..5835819c2aeb 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_WQL.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_WQL.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,384 +7,356 @@ title: about_WQL --- # About WQL -## about_WQL +## SHORT DESCRIPTION +Describes WMI Query Language (WQL), which can be used to get WMI objects in +Windows PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes WMI Query Language (WQL), which can be -used to get WMI objects in Windows PowerShell. +WQL is the Windows Management Instrumentation (WMI) query language, which is +the language used to get information from WMI. -# LONG DESCRIPTION +You are not required to use WQL to perform a WMI query in Windows PowerShell. +Instead, you can use the parameters of the Get-WmiObject or Get-CimInstance +cmdlets. WQL queries are somewhat faster than standard Get-WmiObject commands +and the improved performance is evident when the commands run on hundreds of +systems. However, be sure that the time you spend to write a successful WQL +query doesn't outweigh the performance improvement. -WQL is the Windows Management Instrumentation (WMI) -query language, which is the language used to get -information from WMI. +The basic WQL statements you need to use WQL are Select, Where, and From. -You are not required to use WQL to perform a WMI -query in Windows PowerShell. Instead, you can -use the parameters of the Get-WmiObject or -Get-CimInstance cmdlets. WQL queries are somewhat -faster than standard Get-WmiObject commands and -the improved performance is evident when the commands -run on hundreds of systems. However, be sure that -the time you spend to write a successful WQL query -doesn't outweigh the performance improvement. +## WHEN TO USE WQL -The basic WQL statements you need to use WQL are -Select, Where, and From. +When working with WMI, and especially with WQL, do not forget that you are +also using Windows PowerShell. Often, if a WQL query does not work as +expected, it's easier to use a standard Windows PowerShell command than to +debug the WQL query. -# WHEN TO USE WQL - - -When working with WMI, and especially with WQL, -do not forget that you are also using Windows -PowerShell. Often, if a WQL query does not work as -expected, it's easier to use a standard Windows -PowerShell command than to debug the WQL query. - -Unless you are returning massive amounts of data -from across bandwidth-constrained remote systems, -it is rarely productive to spend hours trying to -perfect a complicated and convoluted WQL query -when there is a perfectly acceptable Windows -cmdlet that does the same thing, if a bit more +Unless you are returning massive amounts of data from across +bandwidth-constrained remote systems, it is rarely productive to spend hours +trying to perfect a complicated and convoluted WQL query when there is a +perfectly acceptable Windows cmdlet that does the same thing, if a bit more slowly. -# USING THE SELECT STATEMENT - +## USING THE SELECT STATEMENT -A typical WMI query begins with a Select statement -that gets all properties or particular properties -of a WMI class. To select all properties of a WMI -class, use an asterisk (*). The From keyword -specifies the WMI class. +A typical WMI query begins with a Select statement that gets all properties or +particular properties of a WMI class. To select all properties of a WMI class, +use an asterisk (*). The From keyword specifies the WMI class. A Select statement has the following format: +``` Select from +``` -For example, the following Select statement selects -all properties (*) from the instances of the Win32_Bios -WMI class. +For example, the following Select statement selects all properties (*) from +the instances of the Win32_Bios WMI class. +``` Select * from Win32_Bios +``` -To select a particular property of a WMI class, -place the property name between the Select and -From keywords. +To select a particular property of a WMI class, place the property name +between the Select and From keywords. -The following query selects only the name of -the BIOS from the Win32_Bios WMI class. The -command saves the query in the $queryName -variable. +The following query selects only the name of the BIOS from the Win32_Bios WMI +class. The command saves the query in the $queryName variable. +``` Select Name from Win32_Bios +``` -To select more than one property, use commas to -separate the property names. The following WMI -query selects the name and the version of the -Win32_Bios WMI class. The command saves the -query in the $queryNameVersion variable. +To select more than one property, use commas to separate the property names. +The following WMI query selects the name and the version of the Win32_Bios WMI +class. The command saves the query in the $queryNameVersion variable. +``` Select name, version from Win32_Bios +``` -# USING THE WQL QUERY +## USING THE WQL QUERY +There are three ways to use WQL query in Windows PowerShell command. -There are three ways to use WQL query in Windows -PowerShell command. +- Use the Get-WmiObject cmdlet +- Use the Get-CimInstance cmdlet +- Use the [wmisearcher] type accelerator. --- Use the Get-WmiObject cmdlet --- Use the Get-CimInstance cmdlet --- Use the [wmisearcher] type accelerator. +## USING THE GET-WMIOBJECT CMDLET -# USING THE GET-WMIOBJECT CMDLET +The most basic way to use the WQL query is to enclose it in quotation marks +(as a string) and then use the query string as the value of the Query +parameter of the Get-WmiObject cmdlet, as shown in the following example. -The most basic way to use the WQL query is to enclose -it in quotation marks (as a string) and then use the -query string as the value of the Query parameter of -the Get-WmiObject cmdlet, as shown in the following -example. - -PS C:> Get-WmiObject -Query "Select * from Win32_Bios" +```powershell +Get-WmiObject -Query "Select * from Win32_Bios" +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -You can also save the WQL statement in a variable -and then use the variable as the value of the Query -parameter, as shown in the following command. +You can also save the WQL statement in a variable and then use the variable as +the value of the Query parameter, as shown in the following command. -PS C:> $query = "Select * from Win32_Bios" -PS C:> Get-WmiObject -Query $query +```powershell +$query = "Select * from Win32_Bios" +Get-WmiObject -Query $query +``` -You can use either format with any WQL statement. -The following command uses the query in the -$queryName variable to get only the name and -version properties of the system BIOS. +You can use either format with any WQL statement. The following command uses +the query in the $queryName variable to get only the name and version +properties of the system BIOS. -PS C:> $queryNameVersion = "Select Name, Version from Win32_Bios" -PS C:> Get-WmiObject -Query $queryNameVersion - -# __GENUS : 2 +```powershell +$queryNameVersion = "Select Name, Version from Win32_Bios" +Get-WmiObject -Query $queryNameVersion +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS Version : LENOVO - 1360 +``` -Remember that you can use the parameters of the -Get-WmiObject cmdlet to get the same result. For -example, the following command also gets the values -of the Name and Version properties of instances of -the Win32_Bios WMI class. - -PS C:> Get-WmiObject -Class Win32_Bios -Property Name, Version +Remember that you can use the parameters of the Get-WmiObject cmdlet to get +the same result. For example, the following command also gets the values of +the Name and Version properties of instances of the Win32_Bios WMI class. -# __GENUS : 2 +```powershell +Get-WmiObject -Class Win32_Bios -Property Name, Version +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS Version : LENOVO - 1360 +``` -# USING THE GET-CIMINSTANCE CMDLET +## USING THE GET-CIMINSTANCE CMDLET +Beginning in Windows PowerShell 3.0, you can use the Get-CimInstance cmdlet to +run WQL queries. -Beginning in Windows PowerShell 3.0, you can use -the Get-CimInstance cmdlet to run WQL queries. +Get-CimInstance gets instances of CIM-compliant classes, including WMI +classes. The CIM cmdlets, introduced Windows PowerShell 3.0, perform the same +tasks as the WMI cmdlets. The CIM cmdlets comply with WS-Management (WSMan) +standards and with the Common Information Model (CIM) standard, which enables +the cmdlets to use the same techniques to manage Windows computers and +computers that are running other operating systems. -Get-CimInstance gets instances of CIM-compliant -classes, including WMI classes. The CIM cmdlets, -introduced Windows PowerShell 3.0, perform the same -tasks as the WMI cmdlets. The CIM cmdlets comply -with WS-Management (WSMan) standards and with the -Common Information Model (CIM) standard, which enables -the cmdlets to use the same techniques to manage -Windows computers and computers that are running -other operating systems. +The following command uses the Get-CimInstance cmdlet to run a WQL query. -The following command uses the Get-CimInstance -cmdlet to run a WQL query. +Any WQL query that can be used with Get-WmiObject can also be used with +Get-CimInstance. -Any WQL query that can be used with Get-WmiObject -can also be used with Get-CimInstance. - -PS C:> Get-CimInstance -Query "Select * from Win32_Bios" +```powershell +Get-CimInstance -Query "Select * from Win32_Bios" +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -Get-CimInstance returns a CimInstance object, instead of -the ManagementObject that Get-WmiObject returns, but -the objects are quite similar. +Get-CimInstance returns a CimInstance object, instead of the ManagementObject +that Get-WmiObject returns, but the objects are quite similar. -PS C:> (Get-CimInstance -Query "Select * from Win32_Bios").GetType().FullName +``` +(Get-CimInstance -Query "Select * from Win32_Bios").GetType().FullName Microsoft.Management.Infrastructure.CimInstance -PS C:> (Get-WmiObject -Query "Select * from Win32_Bios").GetType().FullName +(Get-WmiObject -Query "Select * from Win32_Bios").GetType().FullName System.Management.ManagementObject +``` -USING THE [wmisearcher] TYPE ACCELERATOR +## USING THE [wmisearcher] TYPE ACCELERATOR -The [wmisearcher] type accelerator creates a -ManagementObjectSearcher object from a WQL -statement string. The ManagementObjectSearcher -object has many properties and methods, but the -most basic method is the Get method, which -invokes the specified WMI query and returns -the resulting objects. +The [wmisearcher] type accelerator creates a ManagementObjectSearcher object +from a WQL statement string. The ManagementObjectSearcher object has many +properties and methods, but the most basic method is the Get method, which +invokes the specified WMI query and returns the resulting objects. -By using the [wmisearcher], you gain easy access -to the ManagementObjectSearcher .NET Framework class. -This lets you query WMI and to configure the way -the query is conducted. +By using the [wmisearcher], you gain easy access to the +ManagementObjectSearcher .NET Framework class. This lets you query WMI and to +configure the way the query is conducted. To use the [wmisearcher] type accelerator: -1. Cast the WQL string into a ManagementObjectSearcher -object. -2. Call the Get method of the ManagementObjectSearcher -object. +1. Cast the WQL string into a ManagementObjectSearcher object. +2. Call the Get method of the ManagementObjectSearcher object. -For example, the following command casts the "select -all" query, saves the result in the $bios variable, -and then calls the Get method of the ManagementObjectSearcher -object in the $bios variable. +For example, the following command casts the "select all" query, saves the +result in the $bios variable, and then calls the Get method of the +ManagementObjectSearcher object in the $bios variable. -PS C:> $bios = [wmisearcher]"Select * from Win32_Bios" -PS C:> $bios.Get() +```powershell +$bios = [wmisearcher]"Select * from Win32_Bios" +$bios.Get() +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -NOTE: Only selected object properties are displayed -by default. These properties are defined in the -Types.ps1xml file. +NOTE: Only selected object properties are displayed by default. These +properties are defined in the Types.ps1xml file. -You can use the [wmisearcher] type accelerator to -cast the query or the variable. In the following -example, the [wmisearcher] type accelerator is -used to cast the variable. The result is the same. +You can use the [wmisearcher] type accelerator to cast the query or the +variable. In the following example, the [wmisearcher] type accelerator is used +to cast the variable. The result is the same. -PS C:> [wmisearcher]$bios = "Select * from Win32_Bios" -PS C:> $bios.Get() +```powershell +[wmisearcher]$bios = "Select * from Win32_Bios" +$bios.Get() +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -When you use the [wmisearcher] type accelerator, it -changes the query string into a ManagementObjectSearcher -object, as shown in the following commands. +When you use the [wmisearcher] type accelerator, it changes the query string +into a ManagementObjectSearcher object, as shown in the following commands. -PS C:> $a = "Select * from Win32_Bios" -PS C:> $a.GetType().FullName +``` +$a = "Select * from Win32_Bios" +$a.GetType().FullName System.String -PS C:> $a = [wmisearcher]"Select * from Win32_Bios" -PS C:> $a.GetType().FullName +$a = [wmisearcher]"Select * from Win32_Bios" +$a.GetType().FullName System.Management.ManagementObjectSearcher +``` -This command format works on any query. The following -command gets the value of the Name property of the -Win32_Bios WMI class. - -PS C:> $biosname = [wmisearcher]"Select Name from Win32_Bios" -PS C:> $biosname.Get() +This command format works on any query. The following command gets the value +of the Name property of the Win32_Bios WMI class. -# __GENUS : 2 +```powershell +$biosname = [wmisearcher]"Select Name from Win32_Bios" +$biosname.Get() +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS +``` -You can perform this operation in a single command, -although the command is a bit more difficult to -interpret. +You can perform this operation in a single command, although the command is a +bit more difficult to interpret. -In this format, you use the [wmisearcher] type -accelerator to cast the WQL query string to a -ManagementObjectSearcher, and then call the Get -method on the object -- all in a single command. -The parentheses () that enclose the casted string -direct Windows PowerShell to cast the string before -calling the method. +In this format, you use the [wmisearcher] type accelerator to cast the WQL +query string to a ManagementObjectSearcher, and then call the Get method on +the object -- all in a single command. The parentheses () that enclose the +casted string direct Windows PowerShell to cast the string before calling the +method. -PS C:> ([wmisearcher]"Select name from Win32_Bios").Get() - -# __GENUS : 2 +```powershell +([wmisearcher]"Select name from Win32_Bios").Get() +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS +``` -# USING THE BASIC WQL WHERE STATEMENT - +## USING THE BASIC WQL WHERE STATEMENT -A Where statement establishes conditions -for the data that a Select statement returns. +A Where statement establishes conditions for the data that a Select statement +returns. The Where statement has the following format: +``` where +``` For example: +``` where Name = 'Notepad.exe' +``` -The Where statement is used with the Select -statement, as shown in the following example. +The Where statement is used with the Select statement, as shown in the +following example. +``` Select * from Win32_Process where Name = 'Notepad.exe' +``` -When using the Where statement, the property name -and value must be accurate. +When using the Where statement, the property name and value must be accurate. -For example, the following command gets the Notepad -processes on the local computer. +For example, the following command gets the Notepad processes on the local +computer. -PS C:> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad.exe'" +```powershell +Get-WmiObject -Query "Select * from Win32_Process where name='Notepad.exe'" +``` -However, the following command fails, because the -process name includes the ".exe" file name -extension. +However, the following command fails, because the process name includes the +".exe" file name extension. -PS C:> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad'" +```powershell +Get-WmiObject -Query "Select * from Win32_Process where name='Notepad'" +``` -# WHERE STATEMENT COMPARISON OPERATORS +## WHERE STATEMENT COMPARISON OPERATORS -The following operators are valid in a -WQL Where statement. +The following operators are valid in a WQL Where statement. +``` Operator Description ----------------------- = Equal @@ -398,334 +370,365 @@ LIKE Wildcard match IS Evaluates null ISNOT Evaluates not null ISA Evaluates a member of a WMI class +``` -There are other operators, but these are the ones -used for making comparisons. +There are other operators, but these are the ones used for making comparisons. -For example, the following query selects the Name -and Priority properties from processes in the -Win32_Process class where the process priority -is greater than or equal to 11. The Get-WmiObject -cmdlet runs the query. +For example, the following query selects the Name and Priority properties from +processes in the Win32_Process class where the process priority is greater +than or equal to 11. The Get-WmiObject cmdlet runs the query. -$highPriority = "Select Name, Priority from Win32_Process where Priority >= 11" +```powershell +$highPriority = "Select Name, Priority from Win32_Process " + + "where Priority >= 11" Get-WmiObject -Query $highPriority +``` -# USING THE WQL OPERATORS IN THE FILTER PARAMETER +## USING THE WQL OPERATORS IN THE FILTER PARAMETER +The WQL operators can also be used in the value of the Filter parameter of the +Get-WmiObject or Get-CimInstance cmdlets, as well as in the value of the Query +parameters of these cmdlets. -The WQL operators can also be used in the value -of the Filter parameter of the Get-WmiObject or -Get-CimInstance cmdlets, as well as in the value -of the Query parameters of these cmdlets. +For example, the following command gets the Name and ProcessID properties of +the last five processes that have ProcessID values greater than 1004. The +command uses the Filter parameter to specify the ProcessID condition. -For example, the following command gets the Name -and ProcessID properties of the last five processes -that have ProcessID values greater than 1004. The -command uses the Filter parameter to specify the -ProcessID condition. - -PS C:> Get-WmiObject -Class Win32_Process ` +```powershell +Get-WmiObject -Class Win32_Process ` -Property Name, ProcessID -Filter "ProcessID >= 1004" | Sort ProcessID | Select Name, ProcessID -Last 5 +``` +```output Name ProcessID ---- --------- SROSVC.exe 4220 -# WINWORD.EXE 4664 - +WINWORD.EXE 4664 TscHelp.exe 4744 SnagIt32.exe 4748 WmiPrvSE.exe 5056 +``` # USING THE LIKE OPERATOR -The Like operator lets you use wildcard characters -to filter the results of a WQL query. +The Like operator lets you use wildcard characters to filter the results of a +WQL query. +``` Like Operator Description -------------------------------------------------- [] Character in a range [a-f] or a set -of characters [abcdef]. The items in -a set do not need to be consecutive or -listed in alphabetical order. + of characters [abcdef]. The items in + a set do not need to be consecutive or + listed in alphabetical order. ^ Character not in a range [^a-f] or -not in a set [^abcdef]. The items in -a set do not need to be consecutive or -listed in alphabetical order. + not in a set [^abcdef]. The items in + a set do not need to be consecutive or + listed in alphabetical order. % A string of zero or more characters _ One character. -(underscore) NOTE: To use a literal underscore -in a query string, enclose it in -square brackets [_]. +(underscore) NOTE: To use a literal underscore + in a query string, enclose it in + square brackets [_]. +``` -When the Like operator is used without any wildcard -characters or range operators, it behaves like the -equality operator (=) and returns objects only +When the Like operator is used without any wildcard characters or range +operators, it behaves like the equality operator (=) and returns objects only when they are an exact match for the pattern. -You can combine the range operation with the percent -wildcard character to create simple, yet powerful -filters. +You can combine the range operation with the percent wildcard character to +create simple, yet powerful filters. -# LIKE OPERATOR EXAMPLES +### LIKE OPERATOR EXAMPLES +#### EXAMPLE 1: [] -EXAMPLE 1: [] -The following commands start Notepad and then -search for an instance of the Win32_Process -class that has a name that starts with a letter -between "H" and "N" (case-insensitive). +The following commands start Notepad and then search for an instance of the +Win32_Process class that has a name that starts with a letter between "H" and +"N" (case-insensitive). -The query should return any process from Hotpad.exe -through Notepad.exe. +The query should return any process from Hotpad.exe through Notepad.exe. -PS C:> Notepad # Starts Notepad -PS C:> $query = "Select * from win32_Process where Name LIKE '[H-N]otepad.exe'" -PS C:> Get-WmiObject -Query $query | Select Name, ProcessID +```powershell +Notepad # Starts Notepad +$query = "Select * from win32_Process where Name LIKE '[H-N]otepad.exe'" +Get-WmiObject -Query $query | Select Name, ProcessID +``` +```output Name ProcessID ---- --------- notepad.exe 1740 +``` + +#### EXAMPLE 2: [] and % -EXAMPLE 2: [] and % -The following commands select all process -that have a name that begins with a letter between -A and P (case-insensitive) followed by zero or more -letters in any combination. +The following commands select all process that have a name that begins with a +letter between A and P (case-insensitive) followed by zero or more letters in +any combination. -The Get-WmiObject cmdlet runs the query, the -Select-Object cmdlet gets the Name and ProcessID -properties, and the Sort-Object cmdlet sorts the -results in alphabetical order by name. +The Get-WmiObject cmdlet runs the query, the Select-Object cmdlet gets the +Name and ProcessID properties, and the Sort-Object cmdlet sorts the results in +alphabetical order by name. -PS C:> $query = "Select * from win32_Process where name LIKE '[A-P]%'" -PS C:> Get-WmiObject -Query $query | +```powershell +$query = "Select * from win32_Process where name LIKE '[A-P]%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID | Sort-Object -Property Name +``` -EXAMPLE 3: Not in Range (^) -The following command gets processes whose names -do not begin with any of the following letters: -# A, S, W, P, R, C, U, N +#### EXAMPLE 3: Not in Range (^) + +The following command gets processes whose names do not begin with any of the +following letters: A, S, W, P, R, C, U, N and followed zero or more letters. -PS C:> $query = "Select * from win32_Process where name LIKE '[^ASWPRCUN]%'" -PS C:> Get-WmiObject -Query $query | +```powershell +$query = "Select * from win32_Process where name LIKE '[^ASWPRCUN]%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID | Sort-Object -Property Name +``` + +#### EXAMPLE 4: Any characters -- or none (%) -EXAMPLE 4: Any characters -- or none (%) -The following commands get processes that have -names that begin with "calc". The % symbol in -WQL is equivalent to the asterisk (*) symbol in -regular expressions. +The following commands get processes that have names that begin with "calc". +The % symbol in WQL is equivalent to the asterisk (*) symbol in regular +expressions. -PS C:> $query = "Select * from win32_Process where Name LIKE 'calc%'" -PS C:> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +```powershell +$query = "Select * from win32_Process where Name LIKE 'calc%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +``` +```output Name ProcessID ---- --------- calc.exe 4424 +``` -EXAMPLE 5: One character (_) -The following commands get processes that -have names that have the following pattern, -"c_lc.exe" where the underscore character -represents any one character. This pattern -matches any name from calc.exe through -czlc.exe, or c9lc.exe, but does not match -names in which the "c" and "l" are separated -by more than one character. +#### EXAMPLE 5: One character (_) -PS C:> $query = "Select * from Win32_Process where Name LIKE 'c_lc.exe'" -PS C:> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +The following commands get processes that have names that have the following +pattern, "c_lc.exe" where the underscore character represents any one +character. This pattern matches any name from calc.exe through czlc.exe, or +c9lc.exe, but does not match names in which the "c" and "l" are separated by +more than one character. +```powershell +$query = "Select * from Win32_Process where Name LIKE 'c_lc.exe'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +``` + +```output Name ProcessID ---- --------- calc.exe 4424 +``` + +#### EXAMPLE 6: Exact match -EXAMPLE 6: Exact match -The following commands get processes named -WLIDSVC.exe. Even though the query uses the -Like keyword, it requires an exact match, -because the value does not include any -wildcard characters. +The following commands get processes named WLIDSVC.exe. Even though the query +uses the Like keyword, it requires an exact match, because the value does not +include any wildcard characters. +```powershell $query = "Select * from win32_Process where name LIKE 'WLIDSVC.exe'" Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +```powershell +```output Name ProcessID ---- --------- WLIDSVC.exe 84 +``` -# USING THE OR OPERATOR +## USING THE OR OPERATOR -To specify multiple independent conditions, use the Or -keyword. The Or keyword appears in the Where clause. It -performs an inclusive OR operation on two (or more) -conditions and returns items that meet any of the -conditions. +To specify multiple independent conditions, use the Or keyword. The Or keyword +appears in the Where clause. It performs an inclusive OR operation on two (or +more) conditions and returns items that meet any of the conditions. The Or operator has the following format: +``` Where or ... +``` -For example, the following commands get all instances -of the Win32_Process WMI class but returns them -only if the process name is winword.exe or excel.exe. +For example, the following commands get all instances of the Win32_Process WMI +class but returns them only if the process name is winword.exe or excel.exe. -PS C:> $q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe'" -PS C:> Get-WmiObject -Query $q +```powershell +$q = "Select * from Win32_Process where Name='winword.exe'" + + " or Name='excel.exe'" +Get-WmiObject -Query $q +``` -The Or statement can be used with more than two -conditions. In the following query, the Or statement -gets Winword.exe, Excel.exe, or Powershell.exe. +The Or statement can be used with more than two conditions. In the following +query, the Or statement gets Winword.exe, Excel.exe, or Powershell.exe. -$q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe' or Name = 'powershell.exe'" +```powershell +$q = "Select * from Win32_Process where Name='winword.exe'" + + " or Name='excel.exe' or Name='powershell.exe'" +``` -# USING THE AND OPERATOR +## USING THE AND OPERATOR -To specify multiple related conditions, use the And -keyword. The And keyword appears in the Where clause. It -returns items that meet all of the conditions. +To specify multiple related conditions, use the And keyword. The And keyword +appears in the Where clause. It returns items that meet all of the conditions. The And operator has the following format: +``` Where and ... +``` -For example, the following commands get processes -that have a name of "Winword.exe" and the process -ID of 6512. +For example, the following commands get processes that have a name of +"Winword.exe" and the process ID of 6512. Note that the commands use the Get-CimInstance cmdlet. -PS C:> $q = "Select * from Win32_Process where Name = 'winword.exe' and ProcessID =6512" -PS C:> Get-CimInstance -Query $q - -ProcessId Name HandleCount WorkingSetSize VirtualSize ---------- ---- ----------- -------------- ----------- -# 6512 WINWORD.EXE 768 117170176 633028608 +```powershell +$q = "Select * from Win32_Process where Name = 'winword.exe' " + + "and ProcessID =6512" +Get-CimInstance -Query $q +``` +```output +ProcessId Name HandleCount WorkingSetSize VirtualSize +--------- ---- ----------- -------------- ----------- +# 6512 WINWORD.EXE 768 117170176 633028608 +``` -All operators, including the Like operators are -valid with the Or and And operators. And, you can -combine the Or and And operators in a single query -with parentheses that tell Windows PowerShell which -clauses to process first. +All operators, including the Like operators are valid with the Or and And +operators. And, you can combine the Or and And operators in a single query +with parentheses that tell Windows PowerShell which clauses to process first. -This command uses the Windows PowerShell continuation -character (`) divide the command into two lines. +This command uses the Windows PowerShell continuation character (`) divide the +command into two lines. -PS C:> $q = "Select * from Win32_Process ` +```powershell +$q = "Select * from Win32_Process ` where (Name = 'winword.exe' or Name = 'excel.exe') and HandleCount > 700" +Get-CimInstance -Query $q +``` -PS C:> Get-CimInstance -Query $q -ProcessId Name HandleCount WorkingSetSize VirtualSize ---------- ---- ----------- -------------- ----------- -# 6512 WINWORD.EXE 797 117268480 634425344 +```output +ProcessId Name HandleCount WorkingSetSize VirtualSize +--------- ---- ----------- -------------- ----------- + 6512 WINWORD.EXE 797 117268480 634425344 + 9610 EXCEL.EXE 727 38858752 323227648 +``` -# 9610 EXCEL.EXE 727 38858752 323227648 +## SEARCHING FOR NULL VALUES +Searching for null values in WMI is challenging, because it can lead to +unpredictable results. Null is not zero and it is not equivalent or to an +empty string. Some WMI class properties are initialized and others are not, so +a search for null might not work for all properties. -# SEARCHING FOR NULL VALUES +To search for null values, use the Is operator with a value of "null". -Searching for null values in WMI is challenging, -because it can lead to unpredictable results. Null -is not zero and it is not equivalent or to an empty -string. Some WMI class properties are initialized and -others are not, so a search for null might not work -for all properties. +For example, the following commands get processes that have a null value for +the IntallDate property. The commands return many processes. -To search for null values, use the Is operator with -a value of "null". +```powershell +$q = "Select * from Win32_Process where InstallDate is null" +Get-WmiObject -Query $q +``` -For example, the following commands get processes -that have a null value for the IntallDate property. -The commands return many processes. +In contrast, the following command, gets user accounts that have a null value +for the Description property. This command does not return any user accounts, +even though most user accounts do not have any value for the Description +property. -PS C:> $q = "Select * from Win32_Process where InstallDate is null" -PS C:> Get-WmiObject -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Description is null" +Get-WmiObject -Query $q +``` -In contrast, the following command, gets user -accounts that have a null value for the Description -property. This command does not return any user -accounts, even though most user accounts do not have -any value for the Description property. - -PS C:> $q = "Select * from Win32_UserAccount where Description is null" -PS C:> Get-WmiObject -Query $q - -To find the user accounts that have no value for -the Description property, use the equality operator -to get an empty string. To represent the empty string, +To find the user accounts that have no value for the Description property, use +the equality operator to get an empty string. To represent the empty string, use two consecutive single quotation marks. +```powershell $q = "Select * from Win32_UserAccount where Description = '' " +``` -# USING TRUE OR FALSE +## USING TRUE OR FALSE -To get Boolean values in the properties of WMI -objects, use True and False. They are not case -sensitive. +To get Boolean values in the properties of WMI objects, use True and False. +They are not case sensitive. -The following WQL query returns only local user -accounts from a domain joined computer. +The following WQL query returns only local user accounts from a domain joined +computer. -PS C:> $q = "Select * from Win32_UserAccount where LocalAccount = True" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where LocalAccount = True" +Get-CimInstance -Query $q +``` + +To find domain accounts, use a value of False, as shown in the following +example. -To find domain accounts, use a value of False, -as shown in the following example. +```powershell +$q = "Select * from Win32_UserAccount where LocalAccount = False" +Get-CimInstance -Query $q +``` -PS C:> $q = "Select * from Win32_UserAccount where LocalAccount = False" -PS C:> Get-CimInstance -Query $q +## USING THE ESCAPE CHARACTER -# USING THE ESCAPE CHARACTER +WQL uses the backslash (\) as its escape character. This is different from +Windows PowerShell, which uses the backtick character (`). -WQL uses the backslash () as its escape -character. This is different from Windows -PowerShell, which uses the backtick -character (`). +Quotation marks, and the characters used for quotation marks, often need to be +escaped so that they are not misinterpreted. -Quotation marks, and the characters used for -quotation marks, often need to be escaped so -that they are not misinterpreted. +To find a user whose name includes a single quotation mark, use a backslash to +escape the single quotation mark, as shown in the following command. -To find a user whose name includes a single quotation -mark, use a backslash to escape the single quotation -mark, as shown in the following command. +```powershell +$q = "Select * from Win32_UserAccount where Name = 'Tim O\'Brian'" +Get-CimInstance -Query $q +``` -PS C:> $q = "Select * from Win32_UserAccount where Name = 'Tim O\'Brian'" -PS C:> Get-CimInstance -Query $q +```output Name Caption AccountType SID Domain ---- ------- ----------- --- ------ Tim O'Brian FABRIKAM\TimO 512 S-1-5-21-1457... FABRIKAM +``` -In some case, the backslash also needs to be -escaped. For example, the following commands -generate an Invalid Query error due to the -backslash in the Caption value. +In some case, the backslash also needs to be escaped. For example, the +following commands generate an Invalid Query error due to the backslash in the +Caption value. -PS C:> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" +Get-CimInstance -Query $q +``` + +```output Get-CimInstance : Invalid query At line:1 char:1 + Get-CimInstance -Query $q -# +!INCLUDE[]~~~~~~~~~~~ - -+ CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimException -+ FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastructure.CimCmdlets ++ ~~~~~~~~~~~ + + CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimExcep + + FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastr +``` -To escape the backslash, use a second backslash -character, as shown in the following command. +To escape the backslash, use a second backslash character, as shown in the +following command. -PS C:> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\\TimO'" +Get-CimInstance -Query $q +``` # SEE ALSO @@ -736,4 +739,3 @@ PS C:> Get-CimInstance -Query $q [about_WMI](about_WMI.md) [about_WMI_Cmdlets](about_WMI_Cmdlets.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md index 52e7e3216836..1c09f4504b20 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,108 +7,104 @@ title: about_Windows_PowerShell_ISE --- # About Windows PowerShell ISE -## about_Windows_PowerShell_ISE - - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes the features and system requirements of Windows PowerShell Integrated Scripting Environment (ISE). -# LONG DESCRIPTION +## LONG DESCRIPTION -Windows PowerShell ISE is a graphical host application for Windows -PowerShell. In Windows PowerShell ISE, you can run commands and write, -test, and debug scripts in a single Windows-based graphical user -interface. Its features include Intellisense, multiline editing, tab -completion, auto-save, syntax coloring, selective execution, -context-sensitive help, Show Command (compose commands in a window) -and support for double-byte character sets and right-to-left languages. +Windows PowerShell ISE is a graphical host application for Windows PowerShell. +In Windows PowerShell ISE, you can run commands and write, test, and debug +scripts in a single Windows-based graphical user interface. Its features +include Intellisense, multiline editing, tab completion, auto-save, syntax +coloring, selective execution, context-sensitive help, Show Command (compose +commands in a window) and support for double-byte character sets and +right-to-left languages. -Windows PowerShell ISE is an excellent tool for beginners. The Show -Command window and New Remote PowerShell Tab guide you through tasks -so that you can be successful on the first try. Snippets and error -indicators help you learn the Windows PowerShell language as you work. +Windows PowerShell ISE is an excellent tool for beginners. The Show Command +window and New Remote PowerShell Tab guide you through tasks so that you can +be successful on the first try. Snippets and error indicators help you learn +the Windows PowerShell language as you work. -Advanced users can take advantage of the sophisticated debugging -features, add-ons, and the Windows PowerShell ISE object model. +Advanced users can take advantage of the sophisticated debugging features, +add-ons, and the Windows PowerShell ISE object model. What's New in Windows PowerShell ISE in Windows PowerShell 4.0 -Windows PowerShell ISE introduces two new features in Windows -PowerShell 4.0. +Windows PowerShell ISE introduces two new features in Windows PowerShell 4.0. --- Windows PowerShell ISE now supports both Windows PowerShell -Workflow debugging and remote script debugging. For more -Information, see about_Debuggers. --- IntelliSense support has been added for Windows PowerShell Desired -State Configuration providers and configurations. +- Windows PowerShell ISE now supports both Windows PowerShell Workflow + debugging and remote script debugging. For more Information, see + about_Debuggers. -Starting Windows PowerShell ISE +- IntelliSense support has been added for Windows PowerShell Desired State + Configuration providers and configurations. + +## Starting Windows PowerShell ISE Windows PowerShell ISE is installed, enabled, and ready to use in all supported versions of Windows. -- In Windows 8.1, Windows 8, Windows Server 2012 R2, and Windows Server -2012, on the Start screen, type PowerShell_ISE, and then click -PowerShell_ISE or Windows PowerShell ISE. +- In Windows 8.1, Windows 8, Windows Server 2012 R2, and Windows Server 2012, + on the Start screen, type PowerShell_ISE, and then click PowerShell_ISE or + Windows PowerShell ISE. -- In Windows Server 2012 R2 and Windows Server 2012, in Server Manager, -on the Tools menu, click Windows PowerShell ISE. +- In Windows Server 2012 R2 and Windows Server 2012, in Server Manager, on the + Tools menu, click Windows PowerShell ISE. - In earlier versions of Windows, click Start, All Programs, Accessories, -Windows PowerShell, and then click Windows PowerShell ISE. + Windows PowerShell, and then click Windows PowerShell ISE. -- In a Windows PowerShell console, Cmd.exe, or the Run or Search box -in Windows, type "PowerShell_ise.exe". You can also use the command-line -parameters, including the NoProfile switch. For more information, see -PowerShell_ISE.exe Console Help -(http://go.microsoft.com/fwlink/?LinkId=243055). +- In a Windows PowerShell console, Cmd.exe, or the Run or Search box in + Windows, type "PowerShell_ise.exe". You can also use the command-line + parameters, including the NoProfile switch. For more information, see + [PowerShell_ISE.exe Console Help](http://go.microsoft.com/fwlink/?LinkId=243055). -Running Interactive Commands +## Running Interactive Commands -You can run any Windows PowerShell expression or command in Windows -PowerShell ISE. You can use cmdlets, providers, snap-ins, and modules as -you would use them in the Windows PowerShell console. +You can run any Windows PowerShell expression or command in Windows PowerShell +ISE. You can use cmdlets, providers, snap-ins, and modules as you would use +them in the Windows PowerShell console. You can type or paste interactive commands in the Console pane. To run the commands, you can use buttons, menu items, and keyboard shortcuts. -You can use the multiline editing feature to type or paste several lines -of code into the Console pane at once. When you press the UP ARROW key to -recall the previous command, all the lines in the command are recalled. -When you type commands, press SHIFT+ENTER to make a new blank line appear -under the current line. +You can use the multiline editing feature to type or paste several lines of +code into the Console pane at once. When you press the UP ARROW key to recall +the previous command, all the lines in the command are recalled. When you type +commands, press SHIFT+ENTER to make a new blank line appear under the current +line. -Viewing Output +## Viewing Output -The results of commands and scripts are displayed in the Console pane. You -can move or copy the results from the Console pane by using keyboard -shortcuts or the Copy button on the toolbar, and you can paste the results -in the Script pane or Console panes or other programs. To clear the Console -pane, click the "Clear Output Pane" button or type one of the following -commands: +The results of commands and scripts are displayed in the Console pane. You can +move or copy the results from the Console pane by using keyboard shortcuts or +the Copy button on the toolbar, and you can paste the results in the Script +pane or Console panes or other programs. To clear the Console pane, click the +"Clear Output Pane" button or type one of the following commands: +``` Clear-Host cls +``` -Writing Scripts and Functions +## Writing Scripts and Functions -In the Script pane, you can open, compose, edit, and run scripts. The -Script pane lets you edit scripts by using buttons and keyboard shortcuts. -You can also copy, cut, and paste text between the Script pane and the -Console pane. +In the Script pane, you can open, compose, edit, and run scripts. The Script +pane lets you edit scripts by using buttons and keyboard shortcuts. You can +also copy, cut, and paste text between the Script pane and the Console pane. -You can use the selective run feature to run all or part of a script. To -run part of a script, select the text you want to run, and then click the -Run Selection button or press F8. By default, F8 runs the current line. +You can use the selective run feature to run all or part of a script. To run +part of a script, select the text you want to run, and then click the Run +Selection button or press F8. By default, F8 runs the current line. Advanced editing features include brace-matching, expand-collapse, line numbers, error indicators, block editing and indenting, rich copy, and case conversion. -Getting Help +## Getting Help Windows PowerShell ISE includes help topics that describe its use. In addition, all installed help files are accessible from the Script and Command @@ -116,101 +112,99 @@ panes. Windows PowerShell ISE also supports context-sensitive help. To get help about a particular cmdlet, provider, or keyword, place the cursor in the name of the -item and press F1. To search the help topics, press F1 and type the search term. +item and press F1. To search the help topics, press F1 and type the search +term. To update the help topics on the computer, use the Update Windows PowerShell -Help item in the Help menu. This item updates help for the modules in the current -session in the current UI culture. It is equivalent to running the Update-Help -cmdlet without parameters. To update help for the cmdlets that come with Windows -PowerShell, start Windows PowerShell ISE with the "Run as administrator" option. +Help item in the Help menu. This item updates help for the modules in the +current session in the current UI culture. It is equivalent to running the +Update-Help cmdlet without parameters. To update help for the cmdlets that +come with Windows PowerShell, start Windows PowerShell ISE with the "Run as +administrator" option. You can also use the Get-Help, Save-Help, and Update-Help cmdlets in Windows PowerShell ISE, just as you use it in the Windows PowerShell console. However, in Windows PowerShell ISE, the Help function displays the entire help topic, -not one page at a time. +not one page at a time. -Debugging Scripts +## Debugging Scripts -You can use the Windows PowerShell ISE debugger to debug a Windows -PowerShell script or function. When you debug a script, you can use menu -items and shortcut keys to perform many of the same tasks that you would -perform in the Windows PowerShell console. For example, to set a line -breakpoint in a script, right-click the line of code, and then click -Toggle Breakpoint. +You can use the Windows PowerShell ISE debugger to debug a Windows PowerShell +script or function. When you debug a script, you can use menu items and +shortcut keys to perform many of the same tasks that you would perform in the +Windows PowerShell console. For example, to set a line breakpoint in a script, +right-click the line of code, and then click Toggle Breakpoint. -As you step through a script while debugging, the debugging highlighter -shows precisely which part of the command is running and automatically -opens files that include called functions and scripts. +As you step through a script while debugging, the debugging highlighter shows +precisely which part of the command is running and automatically opens files +that include called functions and scripts. -By default, the Toggle Breakpoint menu item sets a breakpoint on an -entire line in a script, but you can set a breakpoint on a variable -or command name. You can also set a breakpoint on a command by line -and column number, making it easier to debug long pipeline commands. +By default, the Toggle Breakpoint menu item sets a breakpoint on an entire +line in a script, but you can set a breakpoint on a variable or command name. +You can also set a breakpoint on a command by line and column number, making +it easier to debug long pipeline commands. -Often, you can debug syntax errors in a script just by opening the -script file in Windows PowerShell ISE. The error indicators identify -syntax errors and the outlining features let you collapse parts of the -script to focus on trouble spots. +Often, you can debug syntax errors in a script just by opening the script file +in Windows PowerShell ISE. The error indicators identify syntax errors and the +outlining features let you collapse parts of the script to focus on trouble +spots. -You can also use the Windows PowerShell debugger cmdlets in the Command -pane just as you would use them in the console. +You can also use the Windows PowerShell debugger cmdlets in the Command pane +just as you would use them in the console. -Running Remote Commands +## Running Remote Commands -The New Remote PowerShell Tab feature makes it easy to establish a -persistent user-managed Windows PowerShell session ("PSSession") to -the local computer or a remote computer. The command opens a pop-up -window that prompts you for a computer name and for the user account -that has permission to run commands on the remote computer. +The New Remote PowerShell Tab feature makes it easy to establish a persistent +user-managed Windows PowerShell session ("PSSession") to the local computer or +a remote computer. The command opens a pop-up window that prompts you for a +computer name and for the user account that has permission to run commands on +the remote computer. -Customizing the View +## Customizing the View -You can use Windows PowerShell ISE features to move and to resize the -Console pane and the Script pane. You can show and hide either pane, -and you can change the text size in all the panes. +You can use Windows PowerShell ISE features to move and to resize the Console +pane and the Script pane. You can show and hide either pane, and you can +change the text size in all the panes. -You can also use the Options window to customize the appearance and -operation of Windows PowerShell ISE. In addition, Windows PowerShell -ISE has a custom host variable, $psISE, that you can use to customize -Windows PowerShell ISE, including adding menus and menu items. +You can also use the Options window to customize the appearance and operation +of Windows PowerShell ISE. In addition, Windows PowerShell ISE has a custom +host variable, $psISE, that you can use to customize Windows PowerShell ISE, +including adding menus and menu items. -Windows PowerShell ISE Profile +## Windows PowerShell ISE Profile Windows PowerShell ISE has its own Windows PowerShell profile, -Microsoft.PowerShellISE_profile.ps1. In this profile, you can store -functions, aliases, variables, and commands that you use in Windows -PowerShell ISE. +Microsoft.PowerShellISE_profile.ps1. In this profile, you can store functions, +aliases, variables, and commands that you use in Windows PowerShell ISE. -Items in the Windows PowerShell AllHosts profiles (CurrentUser\AllHosts -and AllUsers\AllHosts) are also available in Windows PowerShell ISE, just -as they are in any Windows PowerShell host program. However, the items -in your Windows PowerShell console profiles are not available in Windows -PowerShell ISE. +Items in the Windows PowerShell AllHosts profiles (CurrentUser\\AllHosts and +AllUsers\\AllHosts) are also available in Windows PowerShell ISE, just as they +are in any Windows PowerShell host program. However, the items in your Windows +PowerShell console profiles are not available in Windows PowerShell ISE. Instructions for moving and reconfiguring your profiles are available in Windows PowerShell ISE Help and in about_Profiles. -# NOTES +## NOTES -Windows PowerShell ISE is an optional Windows Feature that is turned on -by default on client and server versions of Windows. To enable and disable +Windows PowerShell ISE is an optional Windows Feature that is turned on by +default on client and server versions of Windows. To enable and disable Windows PowerShell ISE in client versions of Windows, use Turn Windows -Features On or Off in Control Panel. To enable and disable Windows -PowerShell ISE in server versions of Windows, use the Add Roles -and Features Wizard in Server Manager. - -Because Windows PowerShell ISE requires a user interface, it does not work -on Server Core installations of Windows Server. However, if you add the -Windows PowerShell ISE feature, the installation automatically converts -to Server with a GUI. - -Windows PowerShell ISE is built on the Windows Presentation Foundation -(WPF). If the graphical elements of Windows PowerShell ISE do not render -correctly on your system, you might resolve the problem by adding or -adjusting the "Disable WPF Hardware acceleration" graphics rendering -settings on your system. For more information, see "Graphics Rendering -Registry Settings" in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=144711. +Features On or Off in Control Panel. To enable and disable Windows PowerShell +ISE in server versions of Windows, use the Add Roles and Features Wizard in +Server Manager. + +Because Windows PowerShell ISE requires a user interface, it does not work on +Server Core installations of Windows Server. However, if you add the Windows +PowerShell ISE feature, the installation automatically converts to Server with +a GUI. + +Windows PowerShell ISE is built on the Windows Presentation Foundation (WPF). +If the graphical elements of Windows PowerShell ISE do not render correctly on +your system, you might resolve the problem by adding or adjusting the "Disable +WPF Hardware acceleration" graphics rendering settings on your system. For +more information, see [Graphics Rendering Registry Settings](http://go.microsoft.com/fwlink/?LinkId=144711) +in the MSDN library. # SEE ALSO @@ -220,17 +214,16 @@ http://go.microsoft.com/fwlink/?LinkId=144711. [about_Updatable_Help](about_Updatable_Help.md) -Get-Help - -Get-IseSnippet +[Get-Help](../Get-Help.md) -Import-IseSnippet +[Get-IseSnippet](../../ISE/Get-IseSnippet.md) -New-IseSnippet +[Import-IseSnippet](../../ISE/Import-IseSnippet.md) -Save-Help +[New-IseSnippet](../../ISE/New-IseSnippet.md) -Show-Command +[Save-Help](../Save-Help.md) -Update-Help +[Show-Command](../../Microsoft.PowerShell.Utility/Show-Command.md) +[Update-Help](../Update-Help.md) \ No newline at end of file diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md index ad65ab0c16fe..720271edd23d 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,48 +7,60 @@ title: about_Windows_RT --- # About Windows RT -## about_Windows_RT - ## SHORT DESCRIPTION -Explains limitations of Windows PowerShell® 4.0 on Windows RT 8.1. +Explains limitations of Windows PowerShell® 4.0 on Windows RT 8.1. ## LONG DESCRIPTION -The Windows RT 8.1 operating system is installed on computers and devices (such as Microsoft Surface 2, on which it is the operating system that ships with the computer) that use Advanced RISC Machine (ARM) processors. - -Windows PowerShell 4.0 is included in Windows RT 8.1. All cmdlets, providers, and modules, and most scripts designed for Windows PowerShell 2.0 and later releases run on Windows RT 8.1 without changes. - -Because Windows RT 8.1 does not include all Windows features, some Windows PowerShell features work differently or do not work on Windows RT-based devices. The following list explains the differences. - --- Windows PowerShell ISE is not included in and cannot run on Windows RT 8.1. Windows PowerShell ISE requires Windows Presentation Foundation, which is not included in Windows RT 8.1. --- Windows PowerShell remoting and the WinRM service are disabled by default. To enable remoting, run the Enable-PSRemoting cmdlet. Also, run the Set-Service cmdlet to set the startup type of the WinRM service to Automatic, or Automatic (Delayed Start). +The Windows RT 8.1 operating system is installed on computers and devices +(such as Microsoft Surface 2, on which it is the operating system that ships +with the computer) that use Advanced RISC Machine (ARM) processors. -While remoting is disabled, you can use Windows PowerShell remoting to run commands on other computers, but other computers cannot run commands on the Windows RT device. Also, implicit remoting—that is, remoting that is built in to a cmdlet or script, and not explicitly requested with added parameters—does not work in Windows PowerShell running on Windows RT 8.1. +Windows PowerShell 4.0 is included in Windows RT 8.1. All cmdlets, providers, +and modules, and most scripts designed for Windows PowerShell 2.0 and later +releases run on Windows RT 8.1 without changes. --- Domain-joined computing and Kerberos authentication are not supported on Windows RT 8.1. You cannot use Windows PowerShell to add or manage these features. +Because Windows RT 8.1 does not include all Windows features, some Windows +PowerShell features work differently or do not work on Windows RT-based +devices. The following list explains the differences. --- Microsoft .NET Framework classes that are not supported on Windows RT 8.1 are also not supported by Windows PowerShell on Windows RT 8.1. +- Windows PowerShell ISE is not included in and cannot run on Windows RT 8.1. + Windows PowerShell ISE requires Windows Presentation Foundation, which is not + included in Windows RT 8.1. --- Transactions are not enabled on Windows RT 8.1. Transaction cmdlets, such as Start-Transaction, and transaction parameters, such as UseTransaction, do not work properly. +- Windows PowerShell remoting and the WinRM service are disabled by default. + To enable remoting, run the Enable-PSRemoting cmdlet. Also, run the + Set-Service cmdlet to set the startup type of the WinRM service to Automatic, + or Automatic (Delayed Start). --- All Windows PowerShell sessions on Windows RT 8.1 devices use the ConstrainedLanguage language mode. ConstrainedLanguage language mode is a companion to User Mode Code Integrity (UMCI). It permits all Windows cmdlets and Windows PowerShell language elements, but restricts types to ensure that users cannot use Windows PowerShell to circumvent or violate the UMCI protections. + While remoting is disabled, you can use Windows PowerShell remoting to run + commands on other computers, but other computers cannot run commands on the + Windows RT device. Also, implicit remoting—that is, remoting that is built in + to a cmdlet or script, and not explicitly requested with added parameters—does + not work in Windows PowerShell running on Windows RT 8.1. -For more information about ConstrainedLanguage language mode, see about_Language_Modes. +- Domain-joined computing and Kerberos authentication are not supported on + Windows RT 8.1. You cannot use Windows PowerShell to add or manage these + features. +- Microsoft .NET Framework classes that are not supported on Windows RT 8.1 + are also not supported by Windows PowerShell on Windows RT 8.1. -## KEYWORDS -about_ARM +- Transactions are not enabled on Windows RT 8.1. Transaction cmdlets, such + as Start-Transaction, and transaction parameters, such as UseTransaction, do + not work properly. -about_PowerShell_on_ARM - -about_PowerShell_on_Surface - -about_Windows_RT_8.1 - -about_WindowsRT +- All Windows PowerShell sessions on Windows RT 8.1 devices use the + ConstrainedLanguage language mode. ConstrainedLanguage language mode is a + companion to User Mode Code Integrity (UMCI). It permits all Windows cmdlets + and Windows PowerShell language elements, but restricts types to ensure that + users cannot use Windows PowerShell to circumvent or violate the UMCI + protections. +For more information about ConstrainedLanguage language mode, see +[about_Language_Modes](about_Language_Modes.md). ## SEE ALSO @@ -58,7 +70,3 @@ about_WindowsRT [about_Windows_PowerShell_ISE](about_Windows_PowerShell_ISE.md) -about_Workflows - -Windows PowerShell System Requirements: http://technet.microsoft.com/library/hh857337.aspx - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_logical_operators.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_logical_operators.md index cafeedc3d3f5..7d9280a26f85 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_logical_operators.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_logical_operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,13 +14,13 @@ Describes the operators that connect statements in PowerShell. ## LONG DESCRIPTION -The PowerShell logical operators connect expressions and statements, -allowing you to use a single expression to test for multiple conditions. +The PowerShell logical operators connect expressions and statements, allowing +you to use a single expression to test for multiple conditions. -For example, the following statement uses the and operator and the or -operator to connect three conditional statements. The statement is true -only when the value of $a is greater than the value of $b, and either $a or -$b is less than 20. +For example, the following statement uses the and operator and the or operator +to connect three conditional statements. The statement is true only when the +value of $a is greater than the value of $b, and either $a or $b is less than +20. ```powershell ($a -gt $b) -and (($a -lt 20) -or ($b -lt 20)) @@ -28,38 +28,43 @@ $b is less than 20. PowerShell supports the following logical operators. -|Operator|Description|Example| -|---|---|---| -|`-and`|Logical and. TRUE only when both statements are TRUE.|`(1 -eq 1) -and (1 -eq 2)`
`False`| -|`-or`|Logical or. TRUE when either or both statements are TRUE.|`(1 -eq 1) -or (1 -eq 2)`
`True`| -|`-xor`|Logical exclusive or. TRUE only when one of the statements is TRUE and the other is FALSE.|`(1 -eq 1) -xor (2 -eq 2)`
`False`| -|`-not`|Logical not. Negates the statement that follows it.|`-not (1 -eq 1)`
`False`| -|`!`|Logical not. Negates the statement that follows it. (Same as -not)|`!(1 -eq 1)`
`False`| +|Operator|Description |Example | +|--------|-----------------------------------|--------------------------| +|`-and` |Logical AND. TRUE when both |`(1 -eq 1) -and (1 -eq 2)`| +| |statements are TRUE. |`False` | +|`-or` |Logical OR. TRUE when either |`(1 -eq 1) -or (1 -eq 2)` | +| |statement is TRUE. |`True` | +|`-xor` |Logical EXCLUSIVE OR. TRUE when |`(1 -eq 1) -xor (2 -eq 2) | +| |only one statement is TRUE |`False` | +|`-not` |Logical not. Negates the statement |`-not (1 -eq 1)` | +| |that follows. |`False` | +|`!` |Same as `-not` |`!(1 -eq 1)` | +| | |`False` | Note: - The previous examples also use the equal to comparison operator `-eq`. For - more information, see about_Comparison_Operators. The examples also use - the Boolean values of integers. The integer 0 has a value of FALSE. All - other integers have a value of TRUE. +The previous examples also use the equal to comparison operator `-eq`. For +more information, see +[about_Comparison_Operators](about_Comparison_Operators.md). The examples also +use the Boolean values of integers. The integer 0 has a value of FALSE. All +other integers have a value of TRUE. - The syntax of the logical operators is as follows: +The syntax of the logical operators is as follows: -```powershell +``` {-AND | -OR | -XOR} {! | -NOT} ``` - Statements that use the logical operators return Boolean (TRUE or FALSE) - values. +Statements that use the logical operators return Boolean (TRUE or FALSE) +values. - The PowerShell logical operators evaluate only the statements required to - determine the truth value of the statement. If the left operand in a - statement that contains the and operator is FALSE, the right operand is - not evaluated. If the left operand in a statement that contains the or - statement is TRUE, the right operand is not evaluated. As a result, you - can use these statements in the same way that you would use the If - statement. +The PowerShell logical operators evaluate only the statements required to +determine the truth value of the statement. If the left operand in a statement +that contains the and operator is FALSE, the right operand is not evaluated. +If the left operand in a statement that contains the or statement is TRUE, the +right operand is not evaluated. As a result, you can use these statements in +the same way that you would use the If statement. ## SEE ALSO diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_scopes.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_scopes.md index caab8e08c0de..92f18f04064d 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_scopes.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_scopes.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-08 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,118 +7,108 @@ title: about_scopes --- # About Scopes -## about_Scopes - about_Scopes -# SHORT DESCRIPTION +## SHORT DESCRIPTION -Explains the concept of scope in Windows PowerShell and shows how to set -and change the scope of elements. +Explains the concept of scope in PowerShell and shows how to set and change +the scope of elements. -# LONG DESCRIPTION +## LONG DESCRIPTION -Windows PowerShell protects access to variables, aliases, functions, and -Windows PowerShell drives (PSDrives) by limiting where they can be read and -changed. By enforcing a few simple rules for scope, Windows PowerShell -helps to ensure that you do not inadvertently change an item that should -not be changed. +PowerShell protects access to variables, aliases, functions, and PowerShell +drives (PSDrives) by limiting where they can be read and changed. By enforcing +a few simple rules for scope, PowerShell helps to ensure that you do not +inadvertently change an item that should not be changed. The following are the basic rules of scope: -- An item you include in a scope is visible in the scope in which it -was created and in any child scope, unless you explicitly make it -private. You can place variables, aliases, functions, or Windows -PowerShell drives in one or more scopes. - -- An item that you created within a scope can be changed only in the -scope in which it was created, unless you explicitly specify a -different scope. - -If you create an item in a scope, and the item shares its name with an -item in a different scope, the original item might be hidden under the -new item. But, it is not overridden or changed. - -Windows PowerShell Scopes - -Scopes in Windows PowerShell have both names and numbers. The named -scopes specify an absolute scope. The numbers are relative and reflect -the relationship between scopes. - -Global: -The scope that is in effect when Windows PowerShell -starts. Variables and functions that are present when -Windows PowerShell starts have been created in the -global scope. This includes automatic variables and -preference variables. This also includes the variables, aliases, -and functions that are in your Windows PowerShell -profiles. - -Local: -The current scope. The local scope can be the global -scope or any other scope. - -Script: -The scope that is created while a script file runs. Only -the commands in the script run in the script scope. To -the commands in a script, the script scope is the local -scope. +- An item you include in a scope is visible in the scope in which it was +created and in any child scope, unless you explicitly make it private. You can +place variables, aliases, functions, or PowerShell drives in one or +more scopes. + +- An item that you created within a scope can be changed only in the scope in +which it was created, unless you explicitly specify a different scope. -Private: -Items in private scope cannot be seen outside of the current -scope. You can use private scope to create a private version -of an item with the same name in another scope. - -Numbered Scopes: -You can refer to scopes by name or by a number that -describes the relative position of one scope to another. -Scope 0 represents the current, or local, scope. Scope 1 -indicates the immediate parent scope. Scope 2 indicates the -parent of the parent scope, and so on. Numbered scopes -are useful if you have created many recursive +If you create an item in a scope, and the item shares its name with an item in +a different scope, the original item might be hidden under the new item. But, +it is not overridden or changed. + +## PowerShell Scopes + +Scopes in PowerShell have both names and numbers. The named scopes specify an +absolute scope. The numbers are relative and reflect the relationship between scopes. -Parent and Child Scopes +- Global: The scope that is in effect when PowerShell starts. Variables and +functions that are present when PowerShell starts have been created in the +global scope. This includes automatic variables and preference variables. This +also includes the variables, aliases, and functions that are in your +PowerShell profiles. + +- Local: The current scope. The local scope can be the global scope or any +other scope. -You can create a new scope by running a script or function, by creating -a session, or by starting a new instance of Windows PowerShell. When you -create a new scope, the result is a parent scope (the original scope) and -a child scope (the scope that you created). +- Script: The scope that is created while a script file runs. Only the +commands in the script run in the script scope. To the commands in a script, +the script scope is the local scope. -In Windows PowerShell, all scopes are child scopes of the global scope, -but you can create many scopes and many recursive scopes. +- Private: Items in private scope cannot be seen outside of the current scope. +You can use private scope to create a private version of an item with the same +name in another scope. + +- Numbered Scopes: You can refer to scopes by name or by a number that describes +the relative position of one scope to another. Scope 0 represents the current, +or local, scope. Scope 1 indicates the immediate parent scope. Scope 2 +indicates the parent of the parent scope, and so on. Numbered scopes are +useful if you have created many recursive scopes. + +## Parent and Child Scopes + +You can create a new scope by running a script or function, by creating a +session, or by starting a new instance of PowerShell. When you create a new +scope, the result is a parent scope (the original scope) and a child scope +(the scope that you created). + +In PowerShell, all scopes are child scopes of the global scope, but you can +create many scopes and many recursive scopes. Unless you explicitly make the items private, the items in the parent scope -are available to the child scope. However, items that you create and change -in the child scope do not affect the parent scope, unless you explicitly -specify the scope when you create the items. +are available to the child scope. However, items that you create and change in +the child scope do not affect the parent scope, unless you explicitly specify +the scope when you create the items. -Inheritance +## Inheritance -A child scope does not inherit the variables, aliases, and functions from -the parent scope. Unless an item is private, the child scope can view the -items in the parent scope. And, it can change the items by explicitly -specifying the parent scope, but the items are not part of the child scope. +A child scope does not inherit the variables, aliases, and functions from the +parent scope. Unless an item is private, the child scope can view the items in +the parent scope. And, it can change the items by explicitly specifying the +parent scope, but the items are not part of the child scope. -However, a child scope is created with a set of items. Typically, it -includes all the aliases that have the AllScope option. This option is -discussed later in this topic. It includes all the variables that have the -AllScope option, plus some variables that can be used to customize the -scope, such as MaximumFunctionCount. +However, a child scope is created with a set of items. Typically, it includes +all the aliases that have the AllScope option. This option is discussed later +in this topic. It includes all the variables that have the AllScope option, +plus some variables that can be used to customize the scope, such as +MaximumFunctionCount. To find the items in a particular scope, use the Scope parameter of Get-Variable or Get-Alias. For example, to get all the variables in the local scope, type: +```powershell get-variable -scope local +``` To get all the variables in the global scope, type: +```powershell get-variable -scope global +``` -Scope Modifiers +## Scope Modifiers To specify the scope of a new variable, alias, or function, use a scope modifier. The valid values of a modifier are Global, Local, Private, and @@ -126,362 +116,411 @@ Script. The syntax for a scope modifier in a variable is: +``` $[]: = +``` The syntax for a scope modifier in a function is: +``` function []: {} +``` The default scope for scripts is the script scope. The default scope for functions and aliases is the local scope, even if they are defined in a script. -The following command, which does not use a scope modifier, creates a -variable in the current or local scope: +The following command, which does not use a scope modifier, creates a variable +in the current or local scope: +```powershell $a = "one" +``` To create the same variable in the global scope, use the Global scope modifier: +```powershell $global:a = "one" +``` -To create the same variable in the script scope, use the script -scope modifier: +To create the same variable in the script scope, use the script scope +modifier: +```powershell $script:a = "one" +``` You can also use a scope modifier in functions. The following function definition creates a function in the global scope: -function global:Hello -{ -write-host "Hello, World" +```powershell +function global:Hello { + write-host "Hello, World" } +``` -You can also use scope modifiers to refer to a variable in a different -scope. The following command refers to the $test variable, first in the -local scope and then in the global scope: +You can also use scope modifiers to refer to a variable in a different scope. +The following command refers to the $test variable, first in the local scope +and then in the global scope: +```powershell $test - $global:test +``` -The Using scope modifier +### The Using scope modifier -Using is a special scope modifier that identifies a local -variable in a remote command. By default, variables in remote -commands are assumed to be defined in the remote session. +Using is a special scope modifier that identifies a local variable in a remote +command. By default, variables in remote commands are assumed to be defined in +the remote session. -The Using scope modifier is introduced in Windows PowerShell 3.0. +The Using scope modifier is introduced in PowerShell 3.0. -For more information, see about_Remote_Variables. +For more information, see [about_Remote_Variables](about_Remote_Variables.md). -The AllScope Option +### The AllScope Option Variables and aliases have an Option property that can take a value of AllScope. Items that have the AllScope property become part of any child scopes that you create, although they are not retroactively inherited by parent scopes. -An item that has the AllScope property is visible in the child scope, and -it is part of that scope. Changes to the item in any scope affect all the -scopes in which the variable is defined. +An item that has the AllScope property is visible in the child scope, and it +is part of that scope. Changes to the item in any scope affect all the scopes +in which the variable is defined. -Managing Scope +### Managing Scope -Several cmdlets have a Scope parameter that lets you get or set (create -and change) items in a particular scope. Use the following command to find -all the cmdlets in your session that have a Scope parameter: +Several cmdlets have a Scope parameter that lets you get or set (create and +change) items in a particular scope. Use the following command to find all the +cmdlets in your session that have a Scope parameter: +```powershell get-help * -parameter scope +``` -To find the variables that are visible in a particular scope, use the -Scope parameter of Get-Variable. The visible parameters include global -parameters, parameters in the parent scope, and parameters in the current -scope. +To find the variables that are visible in a particular scope, use the Scope +parameter of Get-Variable. The visible parameters include global parameters, +parameters in the parent scope, and parameters in the current scope. -For example, the following command gets the variables that are visible in -the local scope: +For example, the following command gets the variables that are visible in the +local scope: +```powershell get-variable -scope local +``` -To create a variable in a particular scope, use a scope modifier or the -Scope parameter of Set-Variable. The following command creates a variable -in the global scope: +To create a variable in a particular scope, use a scope modifier or the Scope +parameter of Set-Variable. The following command creates a variable in the +global scope: +```powershell new-variable -scope global -name a -value "One" +``` -You can also use the Scope parameter of the New-Alias, Set-Alias, or -Get-Alias cmdlets to specify the scope. The following command creates an -alias in the global scope: +You can also use the Scope parameter of the New-Alias, Set-Alias, or Get-Alias +cmdlets to specify the scope. The following command creates an alias in the +global scope: +```powershell new-alias -scope global -name np -value Notepad.exe +``` -To get the functions in a particular scope, use the Get-Item cmdlet when -you are in the scope. The Get-Item cmdlet does not have a scope parameter. +To get the functions in a particular scope, use the Get-Item cmdlet when you +are in the scope. The Get-Item cmdlet does not have a scope parameter. -Using Dot Source Notation with Scope +### Using Dot Source Notation with Scope Scripts and functions follow all the rules of scope. You create them in a particular scope, and they affect only that scope unless you use a cmdlet parameter or a scope modifier to change that scope. -But, you can add a script or function to the current scope by using dot -source notation. Then, when a script runs in the current scope, any -functions, aliases, and variables that the script creates are available -in the current scope. +But, you can add a script or function to the current scope by using dot source +notation. Then, when a script runs in the current scope, any functions, +aliases, and variables that the script creates are available in the current +scope. -To add a function to the current scope, type a dot (.) and a space before -the path and name of the function in the function call. +To add a function to the current scope, type a dot (.) and a space before the +path and name of the function in the function call. -For example, to run the Sample.ps1 script from the C:\Scripts directory in -the script scope (the default for scripts), use the following command: +For example, to run the Sample.ps1 script from the C:\Scripts directory in the +script scope (the default for scripts), use the following command: +```powershell c:\scripts\sample.ps1 +``` To run the Sample.ps1 script in the local scope, use the following command: +```powershell . c:\scripts.sample.ps1 +``` When you use the call operator (&) to run a function or script, it is not added to the current scope. The following example uses the call operator: +```powershell & c:\scripts.sample.ps1 +``` + +Any aliases, functions, or variables that the Sample.ps1 script creates are +not available in the current scope. + +### Restricting Without Scope + +A few PowerShell concepts are similar to scope or interact with scope. These +concepts may be confused with scope or the behavior of scope. + +Sessions, modules, and nested prompts are self-contained environments, but +they are not child scopes of the global scope in the session. + +- Sessions: A session is an environment in which PowerShell runs. When you + create a session on a remote computer, PowerShell establishes a + persistent connection to the remote computer. The persistent connection lets + you use the session for multiple related commands. + + Because a session is a contained environment, it has its own scope, but a + session is not a child scope of the session in which is was created. The + session starts with its own global scope. This scope is independent of the + global scope of the session. You can create child scopes in the session. For + example, you can run a script to create a child scope in a session. + +- Modules: You can use a PowerShell module to share and deliver PowerShell + tools. A module is a unit that can contain cmdlets, scripts, functions, + variables, aliases, and other useful items. Unless explicitly defined, the + items in a module are not accessible outside the module. Therefore, you can + add the module to your session and use the public items without worrying that + the other items might override the cmdlets, scripts, functions, and other + items in your session. -Any aliases, functions, or variables that the Sample.ps1 script creates -are not available in the current scope. - -Restricting Without Scope - -A few Windows PowerShell concepts are similar to scope or interact with -scope. These concepts may be confused with scope or the behavior of scope. - -Sessions, modules, and nested prompts are self-contained environments, -but they are not child scopes of the global scope in the session. - -Sessions: -A session is an environment in which Windows PowerShell runs. -When you create a session on a remote computer, Windows -PowerShell establishes a persistent connection to the remote -computer. The persistent connection lets you use the session for -multiple related commands. - -Because a session is a contained environment, it has its own -scope, but a session is not a child scope of the session in -which is was created. The session starts with its own global -scope. This scope is independent of the global scope of the session. -You can create child scopes in the session. For example, you can run -a script to create a child scope in a session. - -Modules: -You can use a Windows PowerShell module to share and deliver -Windows PowerShell tools. A module is a unit that can contain -cmdlets, scripts, functions, variables, aliases, and other useful -items. Unless explicitly defined, the items in a module are not -accessible outside the module. Therefore, you can add the module to -your session and use the public items without worrying that the -other items might override the cmdlets, scripts, functions, and other -items in your session. - -The privacy of a module behaves like a scope, but adding a module -to a session does not change the scope. And, the module does not have -its own scope, although the scripts in the module, like all Windows -PowerShell scripts, do have their own scope. - -Nested Prompts: -Similarly, nested prompts do not have their own scope. When you enter -a nested prompt, the nested prompt is a subset of the environment. -But, you remain within the local scope. - -Scripts do have their own scope. If you are debugging a script, and -you reach a breakpoint in the script, you enter the script scope. - -Private Option: -Aliases and variables have an Option property that can take a value -of Private. Items that have the Private option can be viewed and -changed in the scope in which they are created, but they cannot be -viewed or changed outside that scope. - -For example, if you create a variable that has a private option in the -global scope and then run a script, Get-Variable commands in the script -do not display the private variable. This occurs even if you use -the global scope modifier. - -You can use the Option parameter of the New-Variable, Set-Variable, -New-Alias, and Set-Alias cmdlets to set the value of the Option -property to Private. - -Visibility: -The Visibility property of a variable or alias determines whether you -can see the item outside the container, such as a module, in which it -was created. Visibility is designed for containers in the same way that -the Private value of the Option property is designed for scopes. - -The Visibility property takes the Public and Private values. Items -that have private visibility can be viewed and changed only in the -container in which they were created. If the container is added or -imported, the items that have private visibility cannot be viewed or -changed. - -Because Visibility is designed for containers, it works differently -in a scope. If you create an item that has private visibility in the -global scope, you cannot view or change the item in any scope. If you -try to view or change the value of a variable that has private -visibility, Windows PowerShell returns an error message. - -You can use the New-Variable and Set-Variable cmdlets to create a -variable that has private visibility. - -# EXAMPLES - - -Example 1: Change a Variable Value Only in a Script - -The following command changes the value of the $ConfirmPreference -variable in a script. The change does not affect the global scope. - -First, to display the value of the $ConfirmPreference variable in -the local scope, use the following command: + The privacy of a module behaves like a scope, but adding a module to a session + does not change the scope. And, the module does not have its own scope, + although the scripts in the module, like all PowerShell scripts, do + have their own scope. +- Nested Prompts: Similarly, nested prompts do not have their own scope. When + you enter a nested prompt, the nested prompt is a subset of the environment. + But, you remain within the local scope. + + Scripts do have their own scope. If you are debugging a script, and you reach + a breakpoint in the script, you enter the script scope. + +- Private Option: Aliases and variables have an Option property that can take a + value of Private. Items that have the Private option can be viewed and changed + in the scope in which they are created, but they cannot be viewed or changed + outside that scope. + + For example, if you create a variable that has a private option in the global + scope and then run a script, Get-Variable commands in the script do not + display the private variable. This occurs even if you use the global scope + modifier. + + You can use the Option parameter of the New-Variable, Set-Variable, New-Alias, + and Set-Alias cmdlets to set the value of the Option property to Private. + +- Visibility: The Visibility property of a variable or alias determines whether + you can see the item outside the container, such as a module, in which it was + created. Visibility is designed for containers in the same way that the + Private value of the Option property is designed for scopes. + + The Visibility property takes the Public and Private values. Items that have + private visibility can be viewed and changed only in the container in which + they were created. If the container is added or imported, the items that have + private visibility cannot be viewed or changed. + + Because Visibility is designed for containers, it works differently in a + scope. If you create an item that has private visibility in the global scope, + you cannot view or change the item in any scope. If you try to view or change + the value of a variable that has private visibility, PowerShell returns an + error message. + + You can use the New-Variable and Set-Variable cmdlets to create a variable + that has private visibility. + +## EXAMPLES + +### Example 1: Change a Variable Value Only in a Script + +The following command changes the value of the \$ConfirmPreference variable in +a script. The change does not affect the global scope. + +First, to display the value of the \$ConfirmPreference variable in the local +scope, use the following command: + +``` C:\PS> $ConfirmPreference High +``` Create a Scope.ps1 script that contains the following commands: +```powershell $ConfirmPreference = "Low" "The value of `$ConfirmPreference is $ConfirmPreference." +``` -Run the script. The script changes the value of the $ConfirmPreference -variable and then reports its value in the script scope. The output -should resemble the following output: +Run the script. The script changes the value of the \$ConfirmPreference +variable and then reports its value in the script scope. The output should +resemble the following output: +```output The value of $ConfirmPreference is Low. +``` -Next, test the current value of the $ConfirmPreference variable in the -current scope. +Next, test the current value of the \$ConfirmPreference variable in the current +scope. +``` C:\PS> $ConfirmPreference High +``` -This example shows that changes to the value of a variable in the script -scope do not affect the value of that variable in the parent scope. +This example shows that changes to the value of a variable in the script scope +do not affect the value of that variable in the parent scope. -Example 2: View a Variable Value in Different Scopes +### Example 2: View a Variable Value in Different Scopes -You can use scope modifiers to view the value of a variable in the local -scope and in a parent scope. +You can use scope modifiers to view the value of a variable in the local scope +and in a parent scope. First, define a $test variable in the global scope. +```powershell $test = "Global" +``` -Next, create a Sample.ps1 script that defines the $test -variable. In the script, use a scope modifier to refer -to either the global or local versions of the $test variable. +Next, create a Sample.ps1 script that defines the \$test variable. In the +script, use a scope modifier to refer to either the global or local versions +of the \$test variable. -In Sample.ps1 +In Sample.ps1: +```powershell $test = "Local" "The local value of `$test is $test." "The global value of `$test is $global:test." +``` When you run Sample.ps1, the output should resemble the following output: +```output The local value of $test is Local. The global value of $test is Global. +``` -When the script is complete, only the global value of $test is defined -in the session. +When the script is complete, only the global value of \$test is defined in the +session. +``` C:\PS> $test Global +``` -Example 3: Change the Value of a Variable in a Parent Scope +### Example 3: Change the Value of a Variable in a Parent Scope -Unless you protect an item by using the Private option or another -method, you can view and change the value of a variable in a parent -scope. +Unless you protect an item by using the Private option or another method, you +can view and change the value of a variable in a parent scope. -First, define a $test variable in the global scope. +First, define a \$test variable in the global scope. +```powershell $test = "Global" +``` -Next, create a Sample.ps1 script that defines the $test variable. In the -script, use a scope modifier to refer to either the global or local -versions of the $test variable. +Next, create a Sample.ps1 script that defines the \$test variable. In the +script, use a scope modifier to refer to either the global or local versions +of the \$test variable. -In Sample.ps1 +In Sample.ps1: +```powershell $global:test = "Local" "The global value of `$test is $global:test." +``` -When the script is complete, the global value of $test is changed. +When the script is complete, the global value of \$test is changed. +``` C:\PS> $test Local +``` -Example 4: Creating a Private Variable +### Example 4: Creating a Private Variable -A private variable is a variable that has an Option property that has a -value of Private. Private variables are inherited by the child scope, but -they can be viewed or changed only in the scope in which they were -created. +A private variable is a variable that has an Option property that has a value +of Private. Private variables are inherited by the child scope, but they can +be viewed or changed only in the scope in which they were created. -The following command creates a private variable called $ptest in the -local scope. +The following command creates a private variable called \$ptest in the local +scope. +```powershell New-Variable -Name ptest -Value 1 -Option private +``` -You can display and change the value of $ptest in the local scope. +You can display and change the value of \$ptest in the local scope. +``` C:\PS> $ptest -# 1 +1 C:\PS> $ptest = 2 C:\PS> $ptest -# 2 - +2 +``` -Next, create a Sample.ps1 script that contains the following commands. -The command tries to display and change the value of $ptest. +Next, create a Sample.ps1 script that contains the following commands. The +command tries to display and change the value of \$ptest. -In Sample.ps1 +In Sample.ps1: +```powershell "The value of `$Ptest is $Ptest." "The value of `$Ptest is $global:Ptest." +``` -Because the $ptest variable is not visible in the script scope, the -output is empty. +Because the $ptest variable is not visible in the script scope, the output is +empty. +```powershell "The value of $Ptest is ." "The value of $Ptest is ." +``` -Example 5: Using a Local Variable in a Remote Command +### Example 5: Using a Local Variable in a Remote Command -To indicate that a variable in a remote command was created in the -local session, use the Using scope modifier. By default, Windows -PowerShell assumes that the variables in remote commands were created -in the remote session. +To indicate that a variable in a remote command was created in the local +session, use the Using scope modifier. By default, PowerShell assumes +that the variables in remote commands were created in the remote session. The syntax is: + +``` $Using: +``` -For example, the following commands create a $Cred variable in the -local session and then use the $Cred variable in a remote command: +For example, the following commands create a $Cred variable in the local +session and then use the $Cred variable in a remote command: +```powershell $Cred = Get-Credential Invoke-Command $s {Remove-Item .\Test*.ps1 -Credential $Using:Cred} +``` -The Using scope was introduced in Windows PowerShell 3.0. - -In Windows PowerShell 2.0, to indicate that a variable was created in -the local session, use the following command format. +The Using scope was introduced in PowerShell 3.0. In PowerShell 2.0, to +indicate that a variable was created in the local session, use the following +command format. +```powershell $Cred = Get-Credential -Invoke-Command $s {param($c) Remove-Item .\Test*.ps1 -Credential $c} -ArgumentList $Cred +Invoke-Command $s { + param($c) + Remove-Item .\Test*.ps1 -Credential $c +} -ArgumentList $Cred +``` -# SEE ALSO +## SEE ALSO [about_Variables](about_Variables.md) @@ -490,4 +529,3 @@ Invoke-Command $s {param($c) Remove-Item .\Test*.ps1 -Credential $c} -ArgumentLi [about_Functions](about_Functions.md) [about_Script_Blocks](about_Script_Blocks.md) - From e740350c4f3553813454c8ea6f01f634bdc9e26a Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 4 Jan 2018 14:40:46 -0800 Subject: [PATCH 152/188] Reformatting v3 About_ topics missed in first pass (#2005) * v3 about scrub missed files * fixing broken links * fix broken link --- .../About/about_Debuggers.md | 663 +++++++------ .../About/about_Functions_Advanced_Methods.md | 270 +++--- .../about_Functions_OutputTypeAttribute.md | 118 ++- .../About/about_PSSessions.md | 189 ++-- .../About/about_PSSnapins.md | 188 ++-- .../About/about_Parameters.md | 237 +++-- .../About/about_PowerShell_exe.md | 254 ++--- .../About/about_Providers.md | 269 +++--- .../About/about_Quoting_Rules.md | 256 +++-- .../About/about_Remote.md | 238 ++--- .../About/about_Remote_Requirements.md | 244 +++-- .../About/about_Remote_Variables.md | 148 +-- .../About/about_Requires.md | 5 +- .../About/about_Return.md | 107 +-- .../About/about_Run_With_PowerShell.md | 68 +- .../about_Script_Internationalization.md | 179 ++-- .../about_Session_Configuration_Files.md | 506 +++++----- .../About/about_Signing.md | 326 +++---- .../About/about_Splatting.md | 137 ++- .../About/about_Transactions.md | 847 +++++++++-------- .../About/about_Updatable_Help.md | 664 +++++++------ .../About/about_WMI.md | 100 +- .../About/about_WQL.md | 892 +++++++++--------- .../About/about_Windows_PowerShell_ISE.md | 271 +++--- .../About/about_Windows_RT.md | 71 +- .../About/about_logical_operators.md | 63 +- .../About/about_scopes.md | 598 ++++++------ 27 files changed, 4091 insertions(+), 3817 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Debuggers.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Debuggers.md index 1ae634fbee9d..c7b464110d8d 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Debuggers.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Debuggers.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,64 +7,55 @@ title: about_Debuggers --- # About Debuggers -## about_Debuggers - - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes the Windows PowerShell debugger. -# LONG DESCRIPTION - -Debugging is the process of examining a script while it is running to -identify and correct errors in the script instructions. The -Windows PowerShell debugger can help you examine and identify -errors and inefficiencies in your scripts, functions, commands, Windows -PowerShell workflows, Windows PowerShell Desired State Configuration (DSC) -configurations, or expressions. - -Starting in Windows PowerShell 5.0, the Windows PowerShell debugger has been updated -to debug scripts, functions, workflows, commands, configurations, or expressions that are -running in either the console or Windows PowerShell ISE on remote computers. -You can run Enter-PSSession to start an interactive remote PowerShell session -in which you can set breakpoints and debug script files and commands on the -remote computer. Enter-PSSession functionality has been updated to let you -reconnect to and enter a disconnected session that is running a script or -command on a remote computer. If the running script hits a breakpoint, -your client session automatically starts the debugger. If the disconnected -session that is running a script has already hit a breakpoint, and is stopped -at the breakpoint, Enter-PSSession automatically starts the command-line -debugger, after you reconnect to the session. - -The Windows PowerShell debugger can also be used to debug Windows -PowerShell workflows, in either the Windows PowerShell console, or in -Windows PowerShell ISE. Starting in Windows PowerShell 5.0, you can debug -within running jobs or processes, either locally or remotely. +## LONG DESCRIPTION + +Debugging is the process of examining a script while it is running to identify +and correct errors in the script instructions. The Windows PowerShell debugger +can help you examine and identify errors and inefficiencies in your scripts, +functions, commands, Windows PowerShell workflows, Windows PowerShell Desired +State Configuration (DSC) configurations, or expressions. + +Starting in Windows PowerShell 5.0, the Windows PowerShell debugger has been +updated to debug scripts, functions, workflows, commands, configurations, or +expressions that are running in either the console or Windows PowerShell ISE +on remote computers. You can run Enter-PSSession to start an interactive +remote PowerShell session in which you can set breakpoints and debug script +files and commands on the remote computer. Enter-PSSession functionality has +been updated to let you reconnect to and enter a disconnected session that is +running a script or command on a remote computer. If the running script hits a +breakpoint, your client session automatically starts the debugger. If the +disconnected session that is running a script has already hit a breakpoint, +and is stopped at the breakpoint, Enter-PSSession automatically starts the +command-line debugger, after you reconnect to the session. + +The Windows PowerShell debugger can also be used to debug Windows PowerShell +workflows, in either the Windows PowerShell console, or in Windows PowerShell +ISE. Starting in Windows PowerShell 5.0, you can debug within running jobs or +processes, either locally or remotely. You can use the features of the Windows PowerShell debugger to examine a -Windows PowerShell script, function, command, workflow, or expression -while it is running. The Windows PowerShell debugger includes a set of -cmdlets that let you set breakpoints, manage breakpoints, and view the call -stack. - -Debugger Cmdlets -The Windows PowerShell debugger includes the following set of cmdlets: +Windows PowerShell script, function, command, workflow, or expression while it +is running. The Windows PowerShell debugger includes a set of cmdlets that let +you set breakpoints, manage breakpoints, and view the call stack. -Set-PsBreakpoint: Sets breakpoints on lines, variables, and -commands. +## Debugger Cmdlets -Get-PsBreakpoint: Gets breakpoints in the current session. - -Disable-PsBreakpoint: Turns off breakpoints in the current session. - -Enable-PsBreakpoint: Re-enables breakpoints in the current session. +The Windows PowerShell debugger includes the following set of cmdlets: -Remove-PsBreakpoint: Deletes breakpoints from the current session. +- `Set-PsBreakpoint`: Sets breakpoints on lines, variables, and commands. +- `Get-PsBreakpoint`: Gets breakpoints in the current session. +- `Disable-PsBreakpoint`: Turns off breakpoints in the current session. +- `Enable-PsBreakpoint`: Re-enables breakpoints in the current session. +- `Remove-PsBreakpoint`: Deletes breakpoints from the current session. +- `Get-PsCallStack`: Displays the current call stack. -Get-PsCallStack: Displays the current call stack. +## Starting and Stopping the Debugger -Starting and Stopping the Debugger To start the debugger, set one or more breakpoints. Then, run the script, command, or function that you want to debug. @@ -72,89 +63,85 @@ When you reach a breakpoint, execution stops, and control is turned over to the debugger. To stop the debugger, run the script, command, or function until it is -complete. Or, type "stop" or "t". +complete. Or, type `stop` or `t`. -Debugger Commands -When you use the debugger in the Windows PowerShell console, use the -following commands to control the execution. In Windows PowerShell ISE, -use commands on the Debug menu. +### Debugger Commands + +When you use the debugger in the Windows PowerShell console, use the following +commands to control the execution. In Windows PowerShell ISE, use commands on +the Debug menu. Note: For information about how to use the debugger in other host applications, see the host application documentation. -s, Step-into Executes the next statement and then stops. +- `s`, `StepInto`: Executes the next statement and then stops. -v, Step-over Executes the next statement, but skips functions -and invocations. The skipped statements are -executed, but not stepped through. +- `v`, `StepOver`: Executes the next statement, but skips functions and + invocations. The skipped statements are executed, but not stepped through. -Ctrl+Break -(Break All in ISE) Breaks into a running script within either the -Windows PowerShell console, or Windows PowerShell ISE. -Note that Ctrl+Break in Windows PowerShell 2.0, 3.0, -and 4.0 closes the program. Break All works on both -local and remote interactively-running scripts. +- `Ctrl+Break`: (Break All in ISE) Breaks into a running script within either + the Windows PowerShell console, or Windows PowerShell ISE. Note that + Ctrl+Break in Windows PowerShell 2.0, 3.0, and 4.0 closes the program. Break + All works on both local and remote interactively-running scripts. -o, Step-out Steps out of the current function; up one level -if nested. If in the main body, it continues to -the end or the next breakpoint. The skipped -statements are executed, but not stepped through. +- `o`, `StepOut`: Steps out of the current function; up one level if nested. + If in the main body, it continues to the end or the next breakpoint. The + skipped statements are executed, but not stepped through. -c, Continue Continues to run until the script is complete or -until the next breakpoint is reached. The skipped -statements are executed, but not stepped through. +- `c`, `Continue`: Continues to run until the script is complete or until the + next breakpoint is reached. The skipped statements are executed, but not + stepped through. -l, List Displays the part of the script that is executing. -By default, it displays the current line, five -previous lines, and 10 subsequent lines. To continue -listing the script, press ENTER. +- `l`, `List`: Displays the part of the script that is executing. By default, + it displays the current line, five previous lines, and 10 subsequent lines. + To continue listing the script, press ENTER. -l , List Displays 16 lines of the script beginning with the -line number specified by . +- `l `, `List`: Displays 16 lines of the script beginning with the line + number specified by ``. -l , List Displays lines of the script, beginning with the -line number specified by . +- `l `, `List`: Displays `` lines of the script, beginning with the + line number specified by ``. -q, Stop, Exit Stops executing the script, and exits the debugger. If you -are debugging a job by running the Debug-Job cmdlet, the Exit -command detaches the debugger, and allows the job to continue -running. +- `q`, `Stop`, `Exit`: Stops executing the script, and exits the debugger. If + you are debugging a job by running the Debug-Job cmdlet, the Exit command + detaches the debugger, and allows the job to continue running. -k, Get-PsCallStack Displays the current call stack. +- `k`, `Get-PsCallStack`: Displays the current call stack. - Repeats the last command if it was Step (s), -Step-over (v), or List (l). Otherwise, represents a -submit action. +- ``: Repeats the last command if it was Step (s), StepOver (v), or + List (l). Otherwise, represents a submit action. -?, h Displays the debugger command Help. +- `?`, `h`: Displays the debugger command Help. To exit the debugger, you can use Stop (q). + Starting in Windows PowerShell 5.0, you can run the Exit command to exit a nested debugging session that you started by running either Debug-Job or Debug-Runspace. -By using these debugger commands, you can run a script, stop on a point -of concern, examine the values of variables and the state of the system, -and continue running the script until you have identified a problem. +By using these debugger commands, you can run a script, stop on a point of +concern, examine the values of variables and the state of the system, and +continue running the script until you have identified a problem. -NOTE: If you step into a statement with a redirection operator, -such as ">", the Windows PowerShell debugger steps over all -remaining statements in the script. +NOTE: If you step into a statement with a redirection operator, such as ">", +the Windows PowerShell debugger steps over all remaining statements in the +script. Displaying the Values of script Variables -While you are in the debugger, you can also enter commands, display the -value of variables, use cmdlets, and run scripts at the command line. +While you are in the debugger, you can also enter commands, display the value +of variables, use cmdlets, and run scripts at the command line. -You can display the current value of all variables in the script that is -being debugged, except for the following automatic variables: - -# $_ +You can display the current value of all variables in the script that is being +debugged, except for the following automatic variables: +```powershell +$_ $Args $Input $MyInvocation $PSBoundParameters +``` If you try to display the value of any of these variables, you get the value of that variable for in an internal pipeline the debugger uses, not @@ -166,15 +153,20 @@ Then you can display the value of the new variable. For example, +```powershell $scriptArgs = $Args $scriptArgs +``` In the example in this topic, the value of the $MyInvocation variable is reassigned as follows: +```powershell $scriptname = $MyInvocation.MyCommand.Path +``` + +## The Debugger Environment -The Debugger Environment When you reach a breakpoint, you enter the debugger environment. The command prompt changes so that it begins with "[DBG]:". If you are debugging a workflow, the prompt is "[WFDBG]". You can customize @@ -189,87 +181,98 @@ command prompt. For example, the following is the default debugging prompt in the Windows PowerShell console: +``` [DBG]: PS (get-location)>>> +``` -You can find the nesting level by using the $NestedPromptLevel +You can find the nesting level by using the \$NestedPromptLevel automatic variable. -Additionally, an automatic variable, $PSDebugContext, is defined in -the local scope. You can use the presence of the $PsDebugContext +Additionally, an automatic variable, \$PSDebugContext, is defined in +the local scope. You can use the presence of the \$PsDebugContext variable to determine whether you are in the debugger. For example: +```powershell if ($psdebugcontext) {"Debugging"} else {"Not Debugging"} +``` -You can use the value of the $PSDebugContext variable in your +You can use the value of the \$PSDebugContext variable in your debugging. +``` [DBG]: PS>>> $psdebugcontext.invocationinfo Name CommandLineParameters UnboundArguments Location ---- --------------------- ---------------- -------- = {} {} C:\ps-test\vote.ps1 (1) +``` + +## Debugging and Scope -Debugging and Scope -Breaking into the debugger does not change the scope in which -you are operating, but when you reach a breakpoint in a script, -you move into the script scope. The script scope is a child -of the scope in which you ran the debugger. +Breaking into the debugger does not change the scope in which you are +operating, but when you reach a breakpoint in a script, you move into the +script scope. The script scope is a child of the scope in which you ran the +debugger. -To find the variables and aliases that are defined in the -script scope, use the Scope parameter of the Get-Alias or -Get-Variable cmdlets. +To find the variables and aliases that are defined in the script scope, use +the Scope parameter of the Get-Alias or Get-Variable cmdlets. -For example, the following command gets the variables in the -local (script) scope: +For example, the following command gets the variables in the local (script) +scope: +```powershell get-variable -scope 0 +``` You can abbreviate the command as: +```powershell gv -s 0 +``` -This is a useful way to see only the variables that you defined in the -script and that you defined while debugging. +This is a useful way to see only the variables that you defined in the script +and that you defined while debugging. Debugging at the Command Line -When you set a variable breakpoint or a command breakpoint, you can set -the breakpoint only in a script file. However, by default, the breakpoint -is set on anything that runs in the current session. - -For example, if you set a breakpoint on the $name variable, the debugger -breaks on any $name variable in any script, command, function, script -cmdlet or expression that you run until you disable or remove the -breakpoint. - -This allows you to debug your scripts in a more realistic context in -which they might be affected by functions, variables, and other scripts -in the session and in the user's profile. - -Line breakpoints are specific to script files, so they are set only in -script files. - -Debugging Workflows -The Windows PowerShell 4.0 debugger can be used to debug Windows -PowerShell workflows, either in the Windows PowerShell console, or in -Windows PowerShell ISE. There are some limitations with using -the Windows PowerShell debugger to debug workflows. - --- You can view workflow variables while you are in the debugger, but -setting workflow variables from within the debugger is not supported. --- Tab completion when stopped in the workflow debugger is not -available. --- Workflow debugging works only with synchronous running of workflows from -a Windows PowerShell script. You cannot debug workflows if they are -running as a job (with the -AsJob parameter). --- Other nested debugging scenarios--such as a workflow calling another -workflow, or a workflow calling a script--are not implemented. - -The following example demonstrates debugging a workflow. Note that when -the debugger steps into the workflow function, the debugger prompt changes -to [WFDBG]. +When you set a variable breakpoint or a command breakpoint, you can set the +breakpoint only in a script file. However, by default, the breakpoint is set +on anything that runs in the current session. + +For example, if you set a breakpoint on the \$name variable, the debugger +breaks on any \$name variable in any script, command, function, script cmdlet +or expression that you run until you disable or remove the breakpoint. + +This allows you to debug your scripts in a more realistic context in which +they might be affected by functions, variables, and other scripts in the +session and in the user's profile. + +Line breakpoints are specific to script files, so they are set only in script +files. + +## Debugging Workflows + +The Windows PowerShell 4.0 debugger can be used to debug Windows PowerShell +workflows, either in the Windows PowerShell console, or in Windows PowerShell +ISE. There are some limitations with using the Windows PowerShell debugger to +debug workflows. + +- You can view workflow variables while you are in the debugger, but setting + workflow variables from within the debugger is not supported. +- Tab completion when stopped in the workflow debugger is not available. +- Workflow debugging works only with synchronous running of workflows from a + Windows PowerShell script. You cannot debug workflows if they are running as a + job (with the **-AsJob** parameter). +- Other nested debugging scenarios--such as a workflow calling another + workflow, or a workflow calling a script--are not implemented. + +The following example demonstrates debugging a workflow. Note that when the +debugger steps into the workflow function, the debugger prompt changes to +[WFDBG]. + +```powershell PS C:> Set-PSBreakpoint -Script C:\TestWFDemo1.ps1 -Line 8 ID Script Line Command Variable Action @@ -350,32 +353,32 @@ At C:\TestWFDemo1.ps1:11 char:5 [WFDBG:localhost]: PS C:>> stepOut Get PowerShell process: -Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName PSComputerName -------- ------ ----- ----- ----- ------ -- ----------- -------------- -433 35 106688 128392 726 2.67 7124 powershell localhost -499 44 134244 172096 787 2.79 7452 powershell localhost +Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName +------- ------ ----- ----- ----- ------ -- ----------- + 433 35 106688 128392 726 2.67 7124 powershell + 499 44 134244 172096 787 2.79 7452 powershell + Workflow function complete. +``` + +## Debugging Functions -Debugging Functions When you set a breakpoint on a function that has Begin, Process, and End sections, the debugger breaks at the first line of each section. For example: -function test-cmdlet -{ -begin -{ -write-output "Begin" -} -process -{ -write-output "Process" -} -end -{ -write-output "End" -} +```powershell +function test-cmdlet { + begin { + write-output "Begin" + } + process { + write-output "Process" + } + end { + write-output "End" + } } C:\PS> set-psbreakpoint -command test-cmdlet @@ -406,20 +409,24 @@ Hit Command breakpoint on 'prompt:test-cmdlet' test-cmdlet # [DBG]: C:\PS> +``` +## Debugging Remote Scripts -Debugging Remote Scripts -Starting in Windows PowerShell 5.0, you can run the Windows PowerShell debugger in -a remote session, in either the console, or Windows PowerShell ISE. Enter-PSSession -functionality has been updated to let you reconnect to and enter a disconnected -session that is running on a remote computer, and currently running a script. -If the running script hits a breakpoint, your client session automatically -starts the debugger. The following is an example that shows how this works, -with breakpoints set in a script at lines 6, 11, 22, and 25. Note that in the -example, when the debugger starts, there are two identifying prompts: the -name of the computer on which the session is running, and the DBG prompt that -lets you know you are in debugging mode. +Starting in Windows PowerShell 5.0, you can run the Windows PowerShell +debugger in a remote session, in either the console, or Windows PowerShell +ISE. Enter-PSSession functionality has been updated to let you reconnect to +and enter a disconnected session that is running on a remote computer, and +currently running a script. If the running script hits a breakpoint, your +client session automatically starts the debugger. +The following is an example that shows how this works, with breakpoints set in +a script at lines 6, 11, 22, and 25. Note that in the example, when the +debugger starts, there are two identifying prompts: the name of the computer +on which the session is running, and the DBG prompt that lets you know you are +in debugging mode. + +```powershell Enter-Pssession -Cn localhost [localhost]: PS C:\psscripts> Set-PSBreakpoint .\ttest19.ps1 6,11,22,25 @@ -468,45 +475,54 @@ At C:\psscripts\ttest19.ps1:12 char:1 [localhost]: [DBG]: PS C:\psscripts>> quit [localhost]: PS C:\psscripts> Exit-PSSession PS C:\psscripts> +``` + +## Examples -Examples This test script detects the version of the operating system and displays a system-appropriate message. It includes a function, a function call, and a variable. The following command displays the contents of the test script file: +```powershell c:>\PS-test> get-content test.ps1 function psversion { -"Windows PowerShell " + $psversiontable.psversion -if ($psversiontable.psversion.major -lt 2) { -"Upgrade to Windows PowerShell 2.0!" -} -else { -"Have you run a background job today (start-job)?" -} + "Windows PowerShell " + $psversiontable.psversion + if ($psversiontable.psversion.major -lt 6) { + "Upgrade to Windows PowerShell 6.0!" + } + else { + "Have you run a background job today (start-job)?" + } } $scriptname = $MyInvocation.MyCommand.Path psversion "Done $scriptname." +``` -To start, set a breakpoint at a point of interest in the script, such -as a line, command, variable, or function. +To start, set a breakpoint at a point of interest in the script, such as a +line, command, variable, or function. -Start by creating a line breakpoint on the first line of the Test.ps1 -script in the current directory. +Start by creating a line breakpoint on the first line of the Test.ps1 script +in the current directory. +```powershell PS C:\ps-test> set-psbreakpoint -line 1 -script test.ps1 +``` You can abbreviate this command as: +```powershell PS C:\ps-test> spb 1 -s test.ps1 +``` The command returns a line-breakpoint object (System.Management.Automation.LineBreakpoint). +``` Column : 0 Line : 1 Action : @@ -515,193 +531,232 @@ HitCount : 0 Id : 0 Script : C:\ps-test\test.ps1 ScriptName : C:\ps-test\test.ps1 +``` Now, start the script. +```powershell PS C:\ps-test> .\test.ps1 +``` -When the script reaches the first breakpoint, the breakpoint message -indicates that the debugger is active. It describes the breakpoint and -previews the first line of the script, which is a function declaration. -The command prompt also changes to indicate that the debugger has -control. +When the script reaches the first breakpoint, the breakpoint message indicates +that the debugger is active. It describes the breakpoint and previews the +first line of the script, which is a function declaration. The command prompt +also changes to indicate that the debugger has control. -The preview line includes the script name and the line number of the -previewed command. +The preview line includes the script name and the line number of the previewed +command. +```powershell Entering debug mode. Use h or ? for help. Hit Line breakpoint on 'C:\ps-test\test.ps1:1' test.ps1:1 function psversion { # DBG> +``` +Use the Step command (s) to execute the first statement in the script and to +preview the next statement. The next statement uses the $MyInvocation +automatic variable to set the value of the $ScriptName variable to the path +and file name of the script file. -Use the Step command (s) to execute the first statement in the script -and to preview the next statement. The next statement uses the -$MyInvocation automatic variable to set the value of the $ScriptName -variable to the path and file name of the script file. - +```powershell DBG> s test.ps1:11 $scriptname = $MyInvocation.MyCommand.Path +``` -At this point, the $ScriptName variable is not populated, but you can +At this point, the \$ScriptName variable is not populated, but you can verify the value of the variable by displaying its value. In this case, -the value is $null. +the value is \$null. +```powershell DBG> $scriptname # DBG> - +``` Use another Step command (s) to execute the current statement and to preview the next statement in the script. The next statement calls the PsVersion function. +```powershell DBG> s test.ps1:12 psversion +``` At this point, the $ScriptName variable is populated, but you verify the value of the variable by displaying its value. In this case, the value is set to the script path. +```powershell DBG> $scriptname C:\ps-test\test.ps1 +``` Use another Step command to execute the function call. Press ENTER, or type "s" for Step. +```powershell DBG> s test.ps1:2 "Windows PowerShell " + $psversiontable.psversion +``` -The debug message includes a preview of the statement in the function. -To execute this statement and to preview the next statement in the -function, you can use a Step command. But, in this case, use a Step-Out -command (o). It completes the execution of the function (unless it -reaches a breakpoint) and steps to the next statement in the script. +The debug message includes a preview of the statement in the function. To +execute this statement and to preview the next statement in the function, you +can use a Step command. But, in this case, use a StepOut command (o). It +completes the execution of the function (unless it reaches a breakpoint) and +steps to the next statement in the script. +```powershell DBG> o Windows PowerShell 2.0 Have you run a background job today (start-job)? test.ps1:13 "Done $scriptname" +``` -Because we are on the last statement in the script, the Step, Step-Out, -and Continue commands have the same effect. In this case, use -Step-Out (o). +Because we are on the last statement in the script, the Step, StepOut, and +Continue commands have the same effect. In this case, use StepOut (o). +```powershell Done C:\ps-test\test.ps1 PS C:\ps-test> +``` -The Step-Out command executes the last command. The standard command -prompt indicates that the debugger has exited and returned control to the -command processor. +The StepOut command executes the last command. The standard command prompt +indicates that the debugger has exited and returned control to the command +processor. -Now, run the debugger again. First, to delete the current -breakpoint, use the Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. -(If you think you might reuse the breakpoint, use the -Disable-PsBreakpoint cmdlet instead of Remove-PsBreakpoint.) +Now, run the debugger again. First, to delete the current breakpoint, use the +Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. (If you think you might +reuse the breakpoint, use the Disable-PsBreakpoint cmdlet instead of +Remove-PsBreakpoint.) +```powershell PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint +``` You can abbreviate this command as: +```powershell PS C:\ps-test> gbp | rbp +``` Or, run the command by writing a function, such as the following function: +```powershell function delbr { gbp | rbp } +``` -Now, create a breakpoint on the $scriptname variable. +Now, create a breakpoint on the \$scriptname variable. +```powershell PS C:\ps-test> set-psbreakpoint -variable scriptname -script test.ps1 +``` You can abbreviate the command as: +```powershell PS C:\ps-test> sbp -v scriptname -s test.ps1 +``` Now, start the script. The script reaches the variable breakpoint. The default mode is Write, so execution stops just before the statement that changes the value of the variable. +```powershell PS C:\ps-test> .\test.ps1 Hit Variable breakpoint on 'C:\ps-test\test.ps1:$scriptname' (Write access) test.ps1:11 $scriptname = $MyInvocation.mycommand.path # DBG> +``` +Display the current value of the \$scriptname variable, which is \$null. -Display the current value of the $scriptname variable, which -is $null. - +```powershell DBG> $scriptname # DBG> +``` +Use a Step command (s) to execute the statement that populates the variable. +Then, display the new value of the \$scriptname variable. -Use a Step command (s) to execute the statement that populates -the variable. Then, display the new value of the $scriptname -variable. - +```powershell DBG> $scriptname C:\ps-test\test.ps1 +```powershell Use a Step command (s) to preview the next statement in the script. +```powershell DBG> s test.ps1:12 psversion +``` -The next statement is a call to the PsVersion function. To skip the -function but still execute it, use a Step-Over command (v). If you are -already in the function when you use Step-Over, it is not effective. The -function call is displayed, but it is not executed. +The next statement is a call to the PsVersion function. To skip the function +but still execute it, use a StepOver command (v). If you are already in the +function when you use StepOver, it is not effective. The function call is +displayed, but it is not executed. +```powershell DBG> v Windows PowerShell 2.0 Have you run a background job today (start-job)? test.ps1:13 "Done $scriptname" +``` -The Step-Over command executes the function, and it previews the next +The StepOver command executes the function, and it previews the next statement in the script, which prints the final line. Use a Stop command (t) to exit the debugger. The command prompt reverts to the standard command prompt. +```powershell C:\ps-test> +``` To delete the breakpoints, use the Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. +```powershell PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint +``` Create a new command breakpoint on the PsVersion function. +```powershell PS C:\ps-test> Set-PsBreakpoint -command psversion -script test.ps1 +``` You can abbreviate this command to: +```powershell PS C:\ps-test> sbp -c psversion -s test.ps1 +``` Now, run the script. +```powershell PS C:\ps-test> .\test.ps1 Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion' test.ps1:12 psversion # DBG> +``` - -The script reaches the breakpoint at the function call. At this point, -the function has not yet been called. This gives you the opportunity -to use the Action parameter of Set-PsBreakpoint to set conditions for -the execution of the breakpoint or to perform preparatory or diagnostic -tasks, such as starting a log or invoking a diagnostic or security -script. +The script reaches the breakpoint at the function call. At this point, the +function has not yet been called. This gives you the opportunity to use the +Action parameter of Set-PsBreakpoint to set conditions for the execution of +the breakpoint or to perform preparatory or diagnostic tasks, such as starting +a log or invoking a diagnostic or security script. To set an action, use a Continue command (c) to exit the script, and a -Remove-PsBreakpoint command to delete the current breakpoint. -(Breakpoints are read-only, so you cannot add an action to the current -breakpoint.) +Remove-PsBreakpoint command to delete the current breakpoint. (Breakpoints are +read-only, so you cannot add an action to the current breakpoint.) +```powershell DBG> c Windows PowerShell 2.0 Have you run a background job today (start-job)? @@ -709,104 +764,102 @@ Done C:\ps-test\test.ps1 PS C:\ps-test> get-psbreakpoint | remove-psbreakpoint PS C:\ps-test> +``` -Now, create a new command breakpoint with an action. The following -command sets a command breakpoint with an action that logs the value -of the $scriptname variable when the function is called. Because the -Break keyword is not used in the action, execution does not stop. (The -backtick (`) is the line-continuation character.) +Now, create a new command breakpoint with an action. The following command +sets a command breakpoint with an action that logs the value of the +\$scriptname variable when the function is called. Because the Break keyword is +not used in the action, execution does not stop. (The backtick (`) is the +line-continuation character.) +```powershell PS C:\ps-test> set-psbreakpoint -command psversion -script test.ps1 ` -action { add-content "The value of `$scriptname is $scriptname." ` -path action.log} +``` -You can also add actions that set conditions for the breakpoint. In -the following command, the command breakpoint is executed only if the -execution policy is set to RemoteSigned, the most restrictive policy -that still permits you to run scripts. (The backtick (`) is the -continuation character.) +You can also add actions that set conditions for the breakpoint. In the +following command, the command breakpoint is executed only if the execution +policy is set to RemoteSigned, the most restrictive policy that still permits +you to run scripts. (The backtick (`) is the continuation character.) +```powershell PS C:\ps-test> set-psbreakpoint -script test.ps1 -command psversion ` -action { if ((get-executionpolicy) -eq "RemoteSigned") { break }} +``` The Break keyword in the action directs the debugger to execute the -breakpoint. You can also use the Continue keyword to direct the debugger -to execute without breaking. Because the default keyword is Continue, -you must specify Break to stop execution. +breakpoint. You can also use the Continue keyword to direct the debugger to +execute without breaking. Because the default keyword is Continue, you must +specify Break to stop execution. Now, run the script. +```powershell PS C:\ps-test> .\test.ps1 Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion' test.ps1:12 psversion +```powershell Because the execution policy is set to RemoteSigned, execution stops at the function call. -At this point, you might want to check the call stack. Use the -Get-PsCallStack cmdlet or the Get-PsCallStack debugger command (k). -The following command gets the current call stack. +At this point, you might want to check the call stack. Use the Get-PsCallStack +cmdlet or the Get-PsCallStack debugger command (k). The following command gets +the current call stack. +```powershell DBG> k 2: prompt 1: .\test.ps1: $args=[] 0: prompt: $args=[] +``` This example demonstrates just a few of the many ways to use the Windows PowerShell debugger. -For more information about the debugger cmdlets, type the following -command: +For more information about the debugger cmdlets, type the following command: +```powershell help -full +``` For example, type: +```powershell help set-psbreakpoint -full +``` -Other Debugging Features in Windows PowerShell +## Other Debugging Features in Windows PowerShell In addition to the Windows PowerShell debugger, Windows PowerShell includes several other features that you can use to debug scripts and functions. --- Windows PowerShell Integrated Scripting Environment (ISE) includes -an interactive graphical debugger. For more information, start Windows -PowerShell ISE and press F1. - --- The Set-PSDebug cmdlet offers very basic script debugging features, -including stepping and tracing. - --- Use the Set-StrictMode cmdlet to detect references to -uninitialized variables, to references to non-existent properties -of an object, and to function syntax that is not valid. - --- Add diagnostic statements to a script, such as statements that -display the value of variables, statements that read input from -the command line, or statements that report the current -instruction. Use the cmdlets that contain the Write verb for -this task, such as Write-Host, Write-Debug, Write-Warning, and -Write-Verbose. - -# SEE ALSO - -Disable-PsBreakpoint - -Enable-PsBreakpoint - -Get-PsBreakpoint - -Get-PsCallStack - -Remove-PsBreakpoint - -Set-PsBreakpoint - -Set-PsDebug - -Set-Strictmode - -Write-Debug - -Write-Verbose - +- Windows PowerShell Integrated Scripting Environment (ISE) includes an + interactive graphical debugger. For more information, start PowerShell ISE + and press F1. + +- The Set-PSDebug cmdlet offers very basic script debugging features, + including stepping and tracing. + +- Use the Set-StrictMode cmdlet to detect references to uninitialized + variables, to references to non-existent properties of an object, and to + function syntax that is not valid. + +- Add diagnostic statements to a script, such as statements that display the + value of variables, statements that read input from the command line, or + statements that report the current instruction. Use the cmdlets that contain + the Write verb for this task, such as Write-Host, Write-Debug, Write-Warning, + and Write-Verbose. + +## SEE ALSO + +- [Disable-PsBreakpoint](../../Microsoft.PowerShell.Utility/Disable-PsBreakpoint.md) +- [Enable-PsBreakpoint](../../Microsoft.PowerShell.Utility/Enable-PsBreakpoint.md) +- [Get-PsBreakpoint](../../Microsoft.PowerShell.Utility/Get-PsBreakpoint.md) +- [Get-PsCallStack](../../Microsoft.PowerShell.Utility/Get-PsCallStack.md) +- [Remove-PsBreakpoint](../../Microsoft.PowerShell.Utility/Remove-PsBreakpoint.md) +- [Set-PsBreakpoint](../../Microsoft.PowerShell.Utility/Set-PsBreakpoint.md) +- [Write-Debug](../../Microsoft.PowerShell.Utility/Write-Debug.md) +- [Write-Verbose](../../Microsoft.PowerShell.Utility/Write-Verbose.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md index 3e4a5424b207..fbcfc30ca802 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,77 +7,72 @@ title: about_Functions_Advanced_Methods --- # About Functions Advanced Methods -## about_Functions_Advanced_Methods +## SHORT DESCRIPTION -# SHORT DESCRIPTION - -Describes how functions that specify the `CmdletBinding` attribute can use -the methods and properties that are available to compiled cmdlets. +Describes how functions that specify the `CmdletBinding` attribute can use the +methods and properties that are available to compiled cmdlets. # LONG DESCRIPTION Functions that specify the `CmdletBinding` attribute can access a number of -methods and properties through the `$pscmdlet` variable. These methods -include the following methods: +methods and properties through the `$pscmdlet` variable. These methods include +the following methods: - Input-processing methods that compiled cmdlets use to do their work. - - The `ShouldProcess` and `ShouldContinue` methods that are used to get -user feedback before an action is performed. - + user feedback before an action is performed. - The `ThrowTerminatingError` method for generating error records. - - Several Write methods that return different types of output. All the methods and properties of the `PSCmdlet` class are available to -advanced functions. For more information about these methods and -properties, see `System.Management.Automation.PSCmdlet` in the MSDN -(Microsoft Developer Network) library at -http://go.microsoft.com/fwlink/?LinkId=142139. - -# Input Processing Methods - -The methods described in this section are referred to as the input -processing methods. For functions, these three methods are represented -by the `Begin`, `Process`, and `End` blocks of the function. Each function -must include one or more of these blocks. The Windows PowerShell runtime -uses the code within these blocks when it is running a function. (These -blocks are also available to functions that do not use the `CmdletBinding` -attribute.) - -## Begin +advanced functions. For more information about these methods and properties, +see `System.Management.Automation.PSCmdlet` in the MSDN (Microsoft Developer +Network) library at http://go.microsoft.com/fwlink/?LinkId=142139. + +### Input Processing Methods + +The methods described in this section are referred to as the input processing +methods. For functions, these three methods are represented by the `Begin`, +`Process`, and `End` blocks of the function. Each function must include one or +more of these blocks. The Windows PowerShell runtime uses the code within +these blocks when it is running a function. (These blocks are also available +to functions that do not use the `CmdletBinding` attribute.) + +#### Begin + This block is used to provide optional one-time preprocessing for the -function. The Windows PowerShell runtime uses the code in this block one -time for each instance of the function in the pipeline. - -## Process -This block is used to provide record-by-record processing for the -function. This block might be used any number of times, or not at all, -depending on the input to the function. For example, if the function is -the first command in the pipeline, the `Process` block will be used one -time. If the function is not the first command in the pipeline, the -`Process` block is used one time for every input that the function -receives from the pipeline. If there is no pipeline input, the `Process` -block is not used. - -This block must be defined if a function parameter is set to accept -pipeline input. If this block is not defined and the parameter accepts -input from the pipeline, the function will miss the values that are -passed to the function through the pipeline. +function. The Windows PowerShell runtime uses the code in this block one time +for each instance of the function in the pipeline. + +#### Process + +This block is used to provide record-by-record processing for the function. +This block might be used any number of times, or not at all, depending on the +input to the function. For example, if the function is the first command in +the pipeline, the `Process` block will be used one time. If the function is +not the first command in the pipeline, the `Process` block is used one time +for every input that the function receives from the pipeline. If there is no +pipeline input, the `Process` block is not used. + +This block must be defined if a function parameter is set to accept pipeline +input. If this block is not defined and the parameter accepts input from the +pipeline, the function will miss the values that are passed to the function +through the pipeline. Also, when the function supports confirmation requests (when the `SupportsShouldProcess` parameter of the Parameter attribute is set to -`$True`), the call to the `ShouldProcess` method must be made from within -the Process block. +`$True`), the call to the `ShouldProcess` method must be made from within the +Process block. + +#### End -## End -This block is used to provide optional one-time post-processing for -the function. +This block is used to provide optional one-time post-processing for the +function. -The following example shows the outline of a function that contains a -`Begin` block for one-time preprocessing, a `Process` block for multiple -record processing, and an `End` block for one-time post-processing. +The following example shows the outline of a function that contains a `Begin` +block for one-time preprocessing, a `Process` block for multiple record +processing, and an `End` block for one-time post-processing. ```powershell Function Test-ScriptCmdlet @@ -90,119 +85,125 @@ Function Test-ScriptCmdlet } ``` -# Confirmation Methods +### Confirmation Methods + +#### ShouldProcess -## ShouldProcess This method is called to request confirmation from the user before the -function performs an action that would change the system. The function -can continue based on the Boolean value returned by the method. This -method can be called only from within the `Process{}` block of the -function. And, the `CmdletBinding` attribute must declare that the -function supports `ShouldProcess` (as shown in the previous example). +function performs an action that would change the system. The function can +continue based on the Boolean value returned by the method. This method can be +called only from within the `Process{}` block of the function. And, the +`CmdletBinding` attribute must declare that the function supports +`ShouldProcess` (as shown in the previous example). For more information about this method, see -`System.Management.Automation.Cmdlet.ShouldProcess` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142142. +[`System.Management.Automation.Cmdlet.ShouldProcess`](http://go.microsoft.com/fwlink/?LinkId=142142) +in the MSDN library. For more information about how to request confirmation, see -"Requesting Confirmation" in the MSDN library at -http://go.microsoft.com/fwlink/?LinkID=136658. +[Requesting Confirmation](http://go.microsoft.com/fwlink/?LinkID=136658) +in the MSDN library. + +#### ShouldContinue -## ShouldContinue -This method is called to request a second confirmation message. It -should be called when the `ShouldProcess` method returns `$true`. For more -information about this method, see -`System.Management.Automation.Cmdlet.ShouldContinue` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142143. +This method is called to request a second confirmation message. It should be +called when the `ShouldProcess` method returns `$true`. For more information +about this method, see `System.Management.Automation.Cmdlet.ShouldContinue` in +the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142143. -# Error Methods +### Error Methods Functions can call two different methods when errors occur. When a -nonterminating error occurs, the function should call the `WriteError` -method, which is described in the "Write Methods" section. When a -terminating error occurs and the function cannot continue, it should call -the `ThrowTerminatingError` method. You can also use the `Throw` statement for +nonterminating error occurs, the function should call the `WriteError` method, +which is described in the "Write Methods" section. When a terminating error +occurs and the function cannot continue, it should call the +`ThrowTerminatingError` method. You can also use the `Throw` statement for terminating errors and the `Write-Error` cmdlet for nonterminating errors. -For more information, see `System.Management.Automation.Cmdlet.ThrowTerminatingError` -in the MSDN libray at -http://go.microsoft.com/fwlink/?LinkId=142144. +For more information, see +[`System.Management.Automation.Cmdlet.ThrowTerminatingError`](http://go.microsoft.com/fwlink/?LinkId=142144) +in the MSDN libray. -# Write Methods +### Write Methods -A function can call the following methods to return different types of -output. Notice that not all the output goes to the next command in the -pipeline. You can also use the various Write cmdlets, such as -Write-Error. +A function can call the following methods to return different types of output. +Notice that not all the output goes to the next command in the pipeline. You +can also use the various Write cmdlets, such as Write-Error. + +#### WriteCommandDetail -## WriteCommandDetail For information about the `WriteCommandDetails` method, see -`System.Management.Automation.Cmdlet.WriteCommandDetail` in the MSDN -library at http://go.microsoft.com/fwlink/?LinkId=142155. - -## WriteDebug -To provide information that can be used to troubleshoot a function, -make the function call the `WriteDebug` method. This displays debug -messages to the user. For more information, see -`System.Management.Automation.Cmdlet.WriteDebug` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142156. - -## WriteError -Functions should call this method when nonterminating errors occur and -the function is designed to continue processing records. For more -information, see `System.Management.Automation.Cmdlet.WriteError` in the -MSDN library at http://go.microsoft.com/fwlink/?LinkId=142157. +[`System.Management.Automation.Cmdlet.WriteCommandDetail`](http://go.microsoft.com/fwlink/?LinkId=142155) +in the MSDN library. + +#### WriteDebug + +To provide information that can be used to troubleshoot a function, make the +function call the `WriteDebug` method. This displays debug messages to the +user. For more information, see +[`System.Management.Automation.Cmdlet.WriteDebug`](http://go.microsoft.com/fwlink/?LinkId=142156) +in the MSDN library. + +#### WriteError + +Functions should call this method when nonterminating errors occur and the +function is designed to continue processing records. For more information, see +[`System.Management.Automation.Cmdlet.WriteError`](http://go.microsoft.com/fwlink/?LinkId=142157) +in the MSDN library. Note: If a terminating error occurs, the function should call the `ThrowTerminatingError` method. -## WriteObject -This method allows the function to send an object to the next command in -the pipeline. In most cases, this is the method to use when the function -returns data. For more information, see -`System.Management.Automation.PSCmdlet.WriteObject` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142158. - -## WriteProgress -For functions whose actions take a long time to complete, this method -allows the function to call the `WriteProgress` method so that progress -information is displayed. For example, you can display the percent -completed. For more information, see -`System.Management.Automation.PSCmdlet.WriteProgress` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142160. - -## WriteVerbose -To provide detailed information about what the function is doing, make -the function call the `WriteVerbose` method to display verbose messages to -the user. By default, verbose messages are not displayed. For more -information, see `System.Management.Automation.PSCmdlet.WriteVerbose` -in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142162. - -## WriteWarning -To provide information about conditions that may cause unexpected -results, make the function call the WriteWarning method to display -warning messages to the user. By default, warning messages are displayed. -For more information, see -`System.Management.Automation.PSCmdlet.WriteWarning` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142164. +#### WriteObject + +This method allows the function to send an object to the next command in the +pipeline. In most cases, this is the method to use when the function returns +data. For more information, see +[`System.Management.Automation.PSCmdlet.WriteObject`](http://go.microsoft.com/fwlink/?LinkId=142158) +in the MSDN library. + +#### WriteProgress + +For functions whose actions take a long time to complete, this method allows +the function to call the `WriteProgress` method so that progress information +is displayed. For example, you can display the percent completed. For more +information, see [`System.Management.Automation.PSCmdlet.WriteProgress`](http://go.microsoft.com/fwlink/?LinkId=142160) +in the MSDN library. + +#### WriteVerbose + +To provide detailed information about what the function is doing, make the +function call the `WriteVerbose` method to display verbose messages to the +user. By default, verbose messages are not displayed. For more information, +see +[`System.Management.Automation.PSCmdlet.WriteVerbose`](http://go.microsoft.com/fwlink/?LinkId=142162) +in the MSDN library. + +#### WriteWarning + +To provide information about conditions that may cause unexpected results, +make the function call the WriteWarning method to display warning messages to +the user. By default, warning messages are displayed. For more information, +see [`System.Management.Automation.PSCmdlet.WriteWarning`](http://go.microsoft.com/fwlink/?LinkId=142164) +in the MSDN library. Note: You can also display warning messages by configuring the `WarningPreference` variable or by using the `Verbose` and `Debug` command-line options. -# Other Methods and Properties +### Other Methods and Properties For information about the other methods and properties that can be accessed through the `$PSCmdlet` variable, see -`System.Management.Automation.PSCmdlet` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142139. +[`System.Management.Automation.PSCmdlet`](http://go.microsoft.com/fwlink/?LinkId=142139) +in the MSDN library. For example, the `ParameterSetName` property allows you to see the parameter set that is being used. Parameter sets allow you to create a function that -performs different tasks based on the parameters that are specified when -the function is run. +performs different tasks based on the parameters that are specified when the +function is run. -# SEE ALSO +## SEE ALSO [about_Functions](about_Functions.md) @@ -213,4 +214,3 @@ the function is run. [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) [about_Functions_OutputTypeAttribute](about_Functions_OutputTypeAttribute.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md index 7765c99a4084..f5f40dd0d876 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,13 @@ title: about_Functions_OutputTypeAttribute --- # About Functions OutputTypeAttribute -## about_Functions_OutputTypeAttribute - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes an attribute that reports the type of object that the function returns. -# LONG DESCRIPTION +## LONG DESCRIPTION The OutputType attribute lists the .NET types of objects that the functions returns. You can use its optional ParameterSetName parameter to list different @@ -32,24 +30,30 @@ The OutputType attribute value is only a documentation note. It is not derived from the function code or compared to the actual function output. As such, the value might be inaccurate. -# SYNTAX +## SYNTAX The OutputType attribute of functions has the following syntax: +``` [OutputType([], ParameterSetName="")] [OutputType("", ParameterSetName="")] +``` The ParameterSetName parameter is optional. You can list multiple types in the OutputType attribute. +``` [OutputType([],[],[])] +``` You can use the ParameterSetName parameter to indicate that different parameter sets return different types. +``` [OutputType([], ParameterSetName="","")] [OutputType([], ParameterSetName="")] +``` Place the OutputType attribute statements in the attributes list that precedes the Param statement. @@ -57,90 +61,99 @@ the Param statement. The following example shows the placement of the OutputType attribute in a simple function. +```powershell function SimpleFunction2 { -[OutputType([])] -Param ($Parameter1) + [OutputType([])] + Param ($Parameter1) - + } +``` The following example shows the placement of the OutputType attribute in advanced functions. +```powershell function AdvancedFunction1 { -[OutputType([])] -Param ( -[parameter(Mandatory=$true)] -[String[]] -$Parameter1 -# ) + [OutputType([])] + Param ( + [parameter(Mandatory=$true)] + [String[]] + $Parameter1 + ) - + } function AdvancedFunction2 { -[CmdletBinding(SupportsShouldProcess=)] -[OutputType([])] -Param ( -[parameter(Mandatory=$true)] -[String[]] -$Parameter1 -# ) + [CmdletBinding(SupportsShouldProcess=)] + [OutputType([])] + Param ( + [parameter(Mandatory=$true)] + [String[]] + $Parameter1 + ) - + } +``` # EXAMPLES - The following function uses the OutputType attribute to indicate that it returns a string value. +```powershell function Send-Greeting { -[OutputType([String])] -Param ($Name) + [OutputType([String])] + Param ($Name) -Hello, $Name + "Hello, $Name" } +``` To see the resulting output type property, use the Get-Command cmdlet. +``` PS C:> (Get-Command Send-Greeting).OutputType Name Type ---- ---- System.String System.String +``` The following advanced function uses the OutputType attribute to indicate that the function returns different types depending on the parameter set used in the function command. +```powershell function Get-User { -[CmdletBinding(DefaultParameterSetName="ID")] + [CmdletBinding(DefaultParameterSetName="ID")] -[OutputType("System.Int32", ParameterSetName="ID")] -[OutputType([String], ParameterSetName="Name")] + [OutputType("System.Int32", ParameterSetName="ID")] + [OutputType([String], ParameterSetName="Name")] -Param ( -[parameter(Mandatory=$true, ParameterSetName="ID")] -[Int[]] -$UserID, + Param ( + [parameter(Mandatory=$true, ParameterSetName="ID")] + [Int[]] + $UserID, -[parameter(Mandatory=$true, ParameterSetName="Name")] -[String[]] -$UserName -# ) + [parameter(Mandatory=$true, ParameterSetName="Name")] + [String[]] + $UserName + ) - + } +``` The following example demonstrates that the output type property value displays the value of the OutputType attribute, even when it is inaccurate. @@ -149,34 +162,38 @@ The Get-Time function returns a string that contains the short form of the time in any DateTime object. However, the OutputType attribute reports that it returns a System.DateTime object. +```powershell function Get-Time { -[OutputType([DateTime])] -Param -# ( + [OutputType([DateTime])] + Param ( + [parameter(Mandatory=$true)] + [Datetime]$DateTime + ) -[parameter(Mandatory=$true)] -[Datetime]$DateTime -# ) - -$DateTime.ToShortTimeString() + $DateTime.ToShortTimeString() } +``` The Get-Type method confirms that the function returns a string. +``` PS C:> (Get-Time -DateTime (Get-Date)).Gettype().FullName System.String +``` However, the OutputType property, which gets its value from the OutputType attribute, reports that the function returns a DateTime object. +``` PS C:> (Get-Command Get-Time).OutputType Name Type ---- ---- System.DateTime System.DateTime +``` -# NOTES +## NOTES The value of the OutputType property of a FunctionInfo object is an array of System.Management.Automation.PSTypeName objects, each of which have Name and @@ -185,7 +202,9 @@ Type properties. To get only the name of each output type, use a command with the following format. +```powershell (Get-Command Get-Time).OutputType | ForEach {$_.Name} +``` The value of the OutputType property can be null. Use a null value when the output is a not a .NET type, such as a WMI object or a formatted view @@ -202,4 +221,3 @@ of an object. [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md) [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_PSSessions.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_PSSessions.md index 196d7fddf1b9..a96bb8e474f6 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_PSSessions.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_PSSessions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,63 +10,120 @@ title: about_PSSessions ## Short Description -Describes Windows PowerShell sessions (PSSessions) and explains how to establish a persistent connection to a remote computer. +Describes Windows PowerShell sessions (PSSessions) and explains how to +establish a persistent connection to a remote computer. ## Long Description -To run Windows PowerShell commands on a remote computer, you can use the **ComputerName** parameter of a cmdlet, or you can create a Windows PowerShell session (PSSession) and run commands in the PSSession. +To run Windows PowerShell commands on a remote computer, you can use the +**ComputerName** parameter of a cmdlet, or you can create a Windows PowerShell +session (PSSession) and run commands in the PSSession. -When you create a PSSession, Windows PowerShell establishes a persistent connection to the remote computer. Use a PSSession to run a series of related commands on a remote computer. Commands that run in the same PSSession can share data, such as the values of variables, aliases, and functions. +When you create a PSSession, Windows PowerShell establishes a persistent +connection to the remote computer. Use a PSSession to run a series of related +commands on a remote computer. Commands that run in the same PSSession can +share data, such as the values of variables, aliases, and functions. -You can also create a PSSession on the local computer and run commands in it. A local PSSession uses the Windows PowerShell remoting infrastructure to create and maintain the PSSession. +You can also create a PSSession on the local computer and run commands in it. +A local PSSession uses the Windows PowerShell remoting infrastructure to +create and maintain the PSSession. -Beginning in Windows PowerShell 3.0, PSSessions are independent of the sessions in which they are created. Active PSSessions are maintained on the remote computer (or the computer at the remote end or "server-side" of the connection). As a result, you can disconnect from the PSSession and reconnect to it at a later time from the same computer or from a different computer. +Beginning in Windows PowerShell 3.0, PSSessions are independent of the +sessions in which they are created. Active PSSessions are maintained on the +remote computer (or the computer at the remote end or "server-side" of the +connection). As a result, you can disconnect from the PSSession and reconnect +to it at a later time from the same computer or from a different computer. -This topic explains how to create, use, get, and delete PSSessions. For more advanced information, see [about_PSSession_Details](about_PSSession_Details.md). +This topic explains how to create, use, get, and delete PSSessions. For more +advanced information, see +[about_PSSession_Details](about_PSSession_Details.md). -Note: PSSessions use the Windows PowerShell remoting infrastructure. To use PSSessions, the local and remote computers must be configured for remoting. For more information, see [about_Remote_Requirements](about_Remote_Requirements.md). +Note: PSSessions use the Windows PowerShell remoting infrastructure. To use +PSSessions, the local and remote computers must be configured for remoting. +For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). -In Windows Vista and later versions of Windows, to create a PSSession on a local computer, you must start Windows PowerShell with the "Run as administrator" option. +In Windows Vista and later versions of Windows, to create a PSSession on a +local computer, you must start Windows PowerShell with the "Run as +administrator" option. ## What Is a Session? A session is an environment in which Windows PowerShell runs. -Each time you start Windows PowerShell, a session is created for you, and you can run commands in the session. You can also add items to your session, such as modules and snap-ins, and you can create items, such as variables, functions, and aliases. These items exist only in the session and are deleted when the session ends. - -You can also create user-managed sessions, known as " Windows PowerShell sessions" or "PSSessions," on the local computer or on a remote computer. Like the default session, you can run commands in a PSSession and add and create items. - -However, unlike the session that starts automatically, you can control the PSSessions that you create. You can get, create, configure, and remove them, disconnect and reconnect to them, and run multiple commands in the same PSSession. The PSSession remains available until you delete it or it times out. - -Typically, you create a PSSession to run a series of related commands on a remote computer. When you create a PSSession on a remote computer, Windows PowerShell establishes a persistent connection to the remote computer to support the session. - -If you use the **ComputerName** parameter of the `Invoke-Command` or `Enter-PSSession` cmdlet to run a remote command or to start an interactive session, Windows PowerShell creates a temporary session on the remote computer and closes the session as soon as the command is complete or as soon as the interactive session ends. You cannot control these temporary sessions, and you cannot use them for more than a single command or a single interactive session. - -In Windows PowerShell, the "current session" is the session that you are working in. The "current session" can refer to any session, including a temporary session or a PSSession. +Each time you start Windows PowerShell, a session is created for you, and you +can run commands in the session. You can also add items to your session, such +as modules and snap-ins, and you can create items, such as variables, +functions, and aliases. These items exist only in the session and are deleted +when the session ends. + +You can also create user-managed sessions, known as " Windows PowerShell +sessions" or "PSSessions," on the local computer or on a remote computer. Like +the default session, you can run commands in a PSSession and add and create +items. However, unlike the session that starts automatically, you can control +the PSSessions that you create. You can get, create, configure, and remove +them, disconnect and reconnect to them, and run multiple commands in the same +PSSession. The PSSession remains available until you delete it or it times +out. + +Typically, you create a PSSession to run a series of related commands on a +remote computer. When you create a PSSession on a remote computer, Windows +PowerShell establishes a persistent connection to the remote computer to +support the session. + +If you use the **ComputerName** parameter of the `Invoke-Command` or +`Enter-PSSession` cmdlet to run a remote command or to start an interactive +session, Windows PowerShell creates a temporary session on the remote computer +and closes the session as soon as the command is complete or as soon as the +interactive session ends. You cannot control these temporary sessions, and you +cannot use them for more than a single command or a single interactive +session. + +In Windows PowerShell, the "current session" is the session that you are +working in. The "current session" can refer to any session, including a +temporary session or a PSSession. ## Why Use a PSSession? -Use a PSSession when you need a persistent connection to a remote computer. With a PSSession, you can run a series of commands that share data, such as the value of variables, the contents of a function, or the definition of an alias. +Use a PSSession when you need a persistent connection to a remote computer. +With a PSSession, you can run a series of commands that share data, such as +the value of variables, the contents of a function, or the definition of an +alias. -You can run remote commands without creating a PSSession. Use the **ComputerName** parameter of remote-enabled cmdlets to run a single command or a series of unrelated commands on one or many computers. +You can run remote commands without creating a PSSession. Use the +**ComputerName** parameter of remote-enabled cmdlets to run a single command +or a series of unrelated commands on one or many computers. -When you use the **ComputerName** parameter of `Invoke-Command` or `Enter-PSSession`, Windows PowerShell establishes a temporary connection to the remote computer and then closes the connection as soon as the command is complete. Any data elements that you create are lost when the connection is closed. +When you use the **ComputerName** parameter of `Invoke-Command` or +`Enter-PSSession`, Windows PowerShell establishes a temporary connection to +the remote computer and then closes the connection as soon as the command is +complete. Any data elements that you create are lost when the connection is +closed. -Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` and `Get-WmiObject`, use different remoting technologies to gather data. None create a persistent connection like a PSSession. +Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` +and `Get-WmiObject`, use different remoting technologies to gather data. None +create a persistent connection like a PSSession. ## How to Create a PSSession -To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession on a remote computer, use the **ComputerName** parameter of the `New-PSSession` cmdlet. +To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession +on a remote computer, use the **ComputerName** parameter of the +`New-PSSession` cmdlet. -For example, the following command creates a new PSSession on the Server01 computer. +For example, the following command creates a new PSSession on the Server01 +computer. ```powershell New-PSSession -ComputerName Server01 ``` -When you submit the command, `New-PSSession` creates the PSSession and returns an object that represents the PSSession. You can save the object in a variable when you create the PSSession, or you can use a `Get-PSSession` command to get the PSSession at a later time. +When you submit the command, `New-PSSession` creates the PSSession and returns +an object that represents the PSSession. You can save the object in a variable +when you create the PSSession, or you can use a `Get-PSSession` command to get +the PSSession at a later time. -For example, the following command creates a new PSSession on the Server01 computer and saves the resulting object in the $ps variable. +For example, the following command creates a new PSSession on the Server01 +computer and saves the resulting object in the $ps variable. ```powershell $ps = New-PSSession -ComputerName Server01 @@ -74,9 +131,12 @@ $ps = New-PSSession -ComputerName Server01 ## How to Create PSSessions on Multiple Computers -To create PSSessions on multiple computers, use the **ComputerName** parameter of the `New-PSSession` cmdlet. Type the names of the remote computers in a comma-separated list. +To create PSSessions on multiple computers, use the **ComputerName** parameter +of the `New-PSSession` cmdlet. Type the names of the remote computers in a +comma-separated list. -For example, to create PSSessions on the Server01, Server02, and Server03 computers, type: +For example, to create PSSessions on the Server01, Server02, and Server03 +computers, type: ```powershell New-PSSession -ComputerName Server01, Server02, Server03 @@ -86,7 +146,9 @@ New-PSSession -ComputerName Server01, Server02, Server03 ## How to Get PSSessions -To get the PSSessions that were created in your current session, use the `Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` returns the same type of object that `New-PSSession` returns. +To get the PSSessions that were created in your current session, use the +`Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` +returns the same type of object that `New-PSSession` returns. The following command gets all the PSSessions that were created in the current session. @@ -94,9 +156,10 @@ The following command gets all the PSSessions that were created in the current s Get-PSSession ``` -The default display of the PSSessions shows their ID and a default display name. You can assign an alternate display name when you create the session. +The default display of the PSSessions shows their ID and a default display +name. You can assign an alternate display name when you create the session. -``` +```output Id Name ComputerName State ConfigurationName --- ---- ------------ ----- --------------------- 1 Session1 Server01 Opened Microsoft.PowerShell @@ -104,31 +167,45 @@ Id Name ComputerName State ConfigurationName 3 Session3 Server03 Opened Microsoft.PowerShell ``` -You can also save the PSSessions in a variable. The following command gets the PSSessions and saves them in the $ps123 variable. +You can also save the PSSessions in a variable. The following command gets the +PSSessions and saves them in the \$ps123 variable. ```powershell $ps123 = Get-PSSession ``` -When using the PSSession cmdlets, you can refer to a PSSession by its ID, by its name, or by its instance ID (a GUID). The following command gets a PSSession by its ID and saves it in the $ps01 variable. +When using the PSSession cmdlets, you can refer to a PSSession by its ID, by +its name, or by its instance ID (a GUID). The following command gets a +PSSession by its ID and saves it in the \$ps01 variable. ```powershell $ps01 = Get-PSSession -Id 1 ``` -Beginning in Windows PowerShell 3.0, PSSessions are maintained on the remote computer. To get PSSessions that you created on particular remote computers, use the **ComputerName** parameter of the `Get-PSSession` cmdlet. The following command gets the PSSessions that you created on the Server01 remote computer. This includes PSSessions created in the current session and in other sessions on the local computer or other computers. +Beginning in Windows PowerShell 3.0, PSSessions are maintained on the remote +computer. To get PSSessions that you created on particular remote computers, +use the **ComputerName** parameter of the `Get-PSSession` cmdlet. The +following command gets the PSSessions that you created on the Server01 remote +computer. This includes PSSessions created in the current session and in other +sessions on the local computer or other computers. ```powershell Get-PSSession -ComputerName Server01 ``` -In Windows PowerShell 2.0, `Get-PSSession` gets only the PSSessions that were created in the current session. It does not get PSSessions that were created in other sessions or on other computers, even if the sessions are connected to and are running commands on the local computer. +In Windows PowerShell 2.0, `Get-PSSession` gets only the PSSessions that were +created in the current session. It does not get PSSessions that were created +in other sessions or on other computers, even if the sessions are connected to +and are running commands on the local computer. ## How to Run Commands in a PSSession -To run a command in one or more PSSessions, use the `Invoke-Command` cmdlet. Use the Session parameter to specify the PSSessions and the **ScriptBlock** parameter to specify the command. +To run a command in one or more PSSessions, use the `Invoke-Command` cmdlet. +Use the Session parameter to specify the PSSessions and the **ScriptBlock** +parameter to specify the command. -For example, to run a `Get-ChildItem` ("dir") command in each of the three PSSessions saved in the $ps123 variable, type: +For example, to run a `Get-ChildItem` ("dir") command in each of the three +PSSessions saved in the $ps123 variable, type: ```powershell Invoke-Command -Session $ps123 -ScriptBlock { Get-ChildItem } @@ -136,7 +213,8 @@ Invoke-Command -Session $ps123 -ScriptBlock { Get-ChildItem } ## How to Delete PSSessions -When you are finished with the PSSession, use the `Remove-PSSession` cmdlet to delete the PSSession and to release the resources that it was using. +When you are finished with the PSSession, use the `Remove-PSSession` cmdlet to +delete the PSSession and to release the resources that it was using. ```powershell Remove-PSSession -Session $ps @@ -148,35 +226,38 @@ or Remove-PSSession -Id 1 ``` -To remove a PSSession from a remote computer, use the **ComputerName** parameter of the `Remove-PSSession` cmdlet. +To remove a PSSession from a remote computer, use the **ComputerName** +parameter of the `Remove-PSSession` cmdlet. ```powershell Remove-PSSession -ComputerName Server01 -Id 1 ``` -If you do not delete the PSSession, the PSSession remains available for use until it times out. +If you do not delete the PSSession, the PSSession remains available for use +until it times out. -You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` cmdlet to set an expiration time for an idle PSSession. For more information, see [New-PSSessionOption](../New-PSSessionOption.md). +You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` +cmdlet to set an expiration time for an idle PSSession. For more information, +see [New-PSSessionOption](../New-PSSessionOption.md). ## The PSSession Cmdlets -| Cmdlet | Description | -| -------------------- | --------------------------------------------------------------- | -| Connect-PSSession | Connects a PSSession to the current session | -| Disconnect-PSSession | Disconnects a PSSession from the current session | -| Enter-PSSession | Starts an interactive session | -| Exit-PSSession | Ends an interactive session | -| Get-PSSession | Gets the PSSessions in the current session | -| New-PSSession | Creates a new PSSession on a local or remote computer | -| Receive-PSSession | Gets the results of commands that ran in a disconnected session | -| Remove-PSSession | Deletes the PSSessions in the current session | - For a list of PSSession cmdlets, type: ```powershell Get-Help *-PSSession ``` +- Connect-PSSession: Connects a PSSession to the current session +- Disconnect-PSSession: Disconnects a PSSession from the current session +- Enter-PSSession: Starts an interactive session +- Exit-PSSession: Ends an interactive session +- Get-PSSession: Gets the PSSessions in the current session +- New-PSSession: Creates a new PSSession on a local or remote computer +- Receive-PSSession: Gets the results of commands that ran in a disconnected + session +- Remove-PSSession: Deletes the PSSessions in the current session + ## For More Information For more information about PSSessions, see [about_PSSession_Details](about_PSSession_Details.md). diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md index 2fe708b363f5..a30c4841c8e3 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,176 +7,212 @@ title: about_PSSnapins --- # About PSSnapins -## about_PSSnapins - ## SHORT DESCRIPTION -Describes Windows PowerShell® snap-ins and shows how to use and manage them. +Describes Windows PowerShell® snap-ins and shows how to use and manage them. ## LONG DESCRIPTION -A Windows PowerShell snap-in is a Microsoft .NET Framework assembly that contains Windows PowerShell providers and\/or cmdlets. Windows PowerShell includes a set of basic snap-ins, but you can extend the power and value of Windows PowerShell by adding snap-ins that contain providers and cmdlets that you create or get from others. -When you add a snap-in, the cmdlets and providers that it contains are immediately available for use in the current session, but the change affects only the current session. +A Windows PowerShell snap-in is a Microsoft .NET Framework assembly that +contains Windows PowerShell providers and\/or cmdlets. Windows PowerShell +includes a set of basic snap-ins, but you can extend the power and value of +Windows PowerShell by adding snap-ins that contain providers and cmdlets that +you create or get from others. -To add the snap-in to all future sessions, save it in your Windows PowerShell profile. You can also use the Export-Console cmdlet to save the snap-in names to a console file and then use it in future sessions. You can even save multiple console files, each with a different set of snap-ins. +When you add a snap-in, the cmdlets and providers that it contains are +immediately available for use in the current session, but the change affects +only the current session. -NOTE: Windows PowerShell snap-ins (PSSnapins) are available for use in Windows PowerShell 3.0 and Windows PowerShell 2.0. They might be altered or unavailable in subsequent versions. To package Windows PowerShell cmdlets and providers, use modules. For information about creating modules and converting snap-ins to modules, see "Writing a Windows PowerShell Module" in MSDN at http:\/\/go.microsoft.com\/fwlink\/?LinkID\=141556. +To add the snap-in to all future sessions, save it in your Windows PowerShell +profile. You can also use the Export-Console cmdlet to save the snap-in names +to a console file and then use it in future sessions. You can even save +multiple console files, each with a different set of snap-ins. +NOTE: Windows PowerShell snap-ins (PSSnapins) are available for use in Windows +PowerShell 3.0 and Windows PowerShell 2.0. They might be altered or +unavailable in subsequent versions. To package Windows PowerShell cmdlets and +providers, use modules. For information about creating modules and converting +snap-ins to modules, see [Writing a Windows PowerShell Module](http://go.microsoft.com/fwlink/?LinkID=141556) +in the MSDN library. ### FINDING SNAP-INS -To get a list of the Windows PowerShell snap-ins on your computer, type: +To get a list of the Windows PowerShell snap-ins on your computer, type: -``` +```powershell get-pssnapin ``` - To get the snap-in for each Windows PowerShell provider, type: - -``` +```powershell get-psprovider | format-list name, pssnapin ``` - To get a list of the cmdlets in a Windows PowerShell snap-in, type: - -``` +```powershell get-command -module ``` - - ### INSTALLING A SNAP-IN -The built-in snap-ins are registered in the system and added to the default session when you start Windows PowerShell. However, you have to register snap-ins that you create or obtain from others and then add the snap-ins to your session. +The built-in snap-ins are registered in the system and added to the default +session when you start Windows PowerShell. However, you have to register +snap-ins that you create or obtain from others and then add the snap-ins to +your session. ### REGISTERING A SNAP-IN -A Windows PowerShell snap-in is a program written in a .NET Framework language that is compiled into a .dll file. To use the providers and cmdlets in a snap-in, you must first register the snap-in (add it to the registry). -Most snap-ins include an installation program (an .exe or .msi file) that registers the .dll file for you. However, if you receive a snap-in as a .dll file, you can register it on your system. For more information, see [How to Register Cmdlets, Providers, and Host Applications](https://go.microsoft.com/fwlink/?LinkID=143619) in the MSDN library. +A Windows PowerShell snap-in is a program written in a .NET Framework language +that is compiled into a .dll file. To use the providers and cmdlets in a +snap-in, you must first register the snap-in (add it to the registry). -To get all the registered snap-ins on your system or to verify that a snap-in is registered, type: +Most snap-ins include an installation program (an .exe or .msi file) that +registers the .dll file for you. However, if you receive a snap-in as a .dll +file, you can register it on your system. For more information, see +[How to Register Cmdlets, Providers, and Host Applications](https://go.microsoft.com/fwlink/?LinkID=143619) +in the MSDN library. +To get all the registered snap-ins on your system or to verify that a snap-in +is registered, type: -``` +```powershell get-pssnapin -registered ``` - - ### ADDING THE SNAP-IN TO THE CURRENT SESSION -To add a registered snap-in to the current session, use the Add-PsSnapin cmdlet. For example, to add the Microsoft SQL Server snap-in to the session, type: +To add a registered snap-in to the current session, use the Add-PsSnapin +cmdlet. For example, to add the Microsoft SQL Server snap-in to the session, +type: -``` +```powershell add-pssnapin sql ``` - -After the command is completed, the providers and cmdlets in the snap-in are available in the session. However, they are available only in the current session unless you save them. - +After the command is completed, the providers and cmdlets in the snap-in are +available in the session. However, they are available only in the current +session unless you save them. ### SAVING THE SNAP-INS -To use a snap-in in future Windows PowerShell sessions, add the Add-PsSnapin command to your Windows PowerShell profile. Or, export the snap-in names to a console file. -If you add the Add-PSSnapin command to your profile, it is available in all future Windows PowerShell sessions. If you export the names of the snap-ins in your session, you can use the export file only when you need the snap-ins. +To use a snap-in in future Windows PowerShell sessions, add the Add-PsSnapin +command to your Windows PowerShell profile. Or, export the snap-in names to a +console file. -To add the Add-PsSnapin command to your Windows PowerShell profile, open your profile, paste or type the command, and then save the profile. For more information, see about_Profiles. +If you add the Add-PSSnapin command to your profile, it is available in all +future Windows PowerShell sessions. If you export the names of the snap-ins in +your session, you can use the export file only when you need the snap-ins. -To save the snap-ins from a session in console file (.psc1), use the Export-Console cmdlet. For example, to save the snap-ins in the current session configuration to the NewConsole.psc1 file in the current directory, type: +To add the Add-PsSnapin command to your Windows PowerShell profile, open your +profile, paste or type the command, and then save the profile. For more +information, see about_Profiles. +To save the snap-ins from a session in console file (.psc1), use the +Export-Console cmdlet. For example, to save the snap-ins in the current +session configuration to the NewConsole.psc1 file in the current directory, +type: -``` +```powershell export-console NewConsole ``` - For more information, see Export-Console. - ### OPENING WINDOWS POWERSHELL WITH A CONSOLE FILE -To use a console file that includes the snap-in, start Windows PowerShell (PowerShell.exe) from the command prompt in Cmd.exe or in another Windows PowerShell session. Use the PsConsoleFile parameter to specify the console file that includes the snap-in. For example, the following command starts Windows PowerShell with the NewConsole.psc1 console file: +To use a console file that includes the snap-in, start Windows PowerShell +(PowerShell.exe) from the command prompt in Cmd.exe or in another Windows +PowerShell session. Use the PsConsoleFile parameter to specify the console +file that includes the snap-in. For example, the following command starts +Windows PowerShell with the NewConsole.psc1 console file: -``` +```powershell PowerShell.exe -psconsolefile NewConsole.psc1 ``` - The providers and cmdlets in the snapin are now available for use in the session. - ### REMOVING A SNAP-IN -To remove a Windows PowerShell snap-in from the current session, use the Remove-PsSnapin cmdlet. For example, to remove the SQL Server snap-in from the current session, type: +To remove a Windows PowerShell snap-in from the current session, use the +Remove-PsSnapin cmdlet. For example, to remove the SQL Server snap-in from the +current session, type: -``` +```powershell remove-pssnapin sql ``` - -This cmdlet removes the snap-in from the session. The snap-in is still loaded, but the providers and cmdlets that it supports are no longer available. - +This cmdlet removes the snap-in from the session. The snap-in is still loaded, +but the providers and cmdlets that it supports are no longer available. ### BUILT-IN COMMANDS -In Windows PowerShell 2.0 and in older-style host programs in Windows PowerShell 3.0 and later, the built-in commands that are installed with Windows PowerShell are packaged in snap-ins that are added automatically to every Windows PowerShell session. -Beginning in Windows PowerShell 3.0, in newer-style host programs -- those that start sessions by using the InitialSessionState.CreateDefault2 method -- the built-in commands are packaged in modules. The exception is Microsoft.PowerShell.Core, which always appears as a snap-in. The Core snap-in is included in every session by default. The built-in modules are loaded automatically on first-use. +In Windows PowerShell 2.0 and in older-style host programs in Windows +PowerShell 3.0 and later, the built-in commands that are installed with +Windows PowerShell are packaged in snap-ins that are added automatically to +every Windows PowerShell session. -NOTE: Remote sessions, including sessions that are started by using the New-PSSession cmdlet, are older-style sessions in which the built-in commands are packaged in snap-ins. +Beginning in Windows PowerShell 3.0, in newer-style host programs -- those +that start sessions by using the InitialSessionState.CreateDefault2 method -- +the built-in commands are packaged in modules. The exception is +Microsoft.PowerShell.Core, which always appears as a snap-in. The Core snap-in +is included in every session by default. The built-in modules are loaded +automatically on first-use. -The following snap-ins (or modules) are installed with Windows PowerShell. - -Microsoft.PowerShell.Core - -Contains providers and cmdlets used to manage the basic features of Windows PowerShell. It includes the FileSystem, Registry, Alias, Environment, Function, and Variable providers and basic cmdlets like Get-Help, Get-Command, and Get-History. - -Microsoft.PowerShell.Host - -Contains cmdlets used by the Windows PowerShell host, such as Start-Transcript and Stop-Transcript. +NOTE: Remote sessions, including sessions that are started by using the +New-PSSession cmdlet, are older-style sessions in which the built-in commands +are packaged in snap-ins. -Microsoft.PowerShell.Management - -Contains cmdlets such as Get-Service and Get-ChildItem that are used to manage Windows-based features. - -Microsoft.PowerShell.Security +The following snap-ins (or modules) are installed with Windows PowerShell. -Contains the Certificate provider and cmdlets used to manage Windows PowerShell security, such as Get-Acl, Get-AuthenticodeSignature, and ConvertTo-SecureString. +- Microsoft.PowerShell.Core - Contains providers and cmdlets used to manage + the basic features of Windows PowerShell. It includes the FileSystem, + Registry, Alias, Environment, Function, and Variable providers and basic + cmdlets like Get-Help, Get-Command, and Get-History. -Microsoft.PowerShell.Utility +- Microsoft.PowerShell.Host - Contains cmdlets used by the Windows PowerShell + host, such as Start-Transcript and Stop-Transcript. -Contains cmdlets used to manipulate objects and data, such as Get-Member, Write-Host, and Format-List. +- Microsoft.PowerShell.Management - Contains cmdlets such as Get-Service and + Get-ChildItem that are used to manage Windows-based features. -Microsoft.WSMan.Management +- Microsoft.PowerShell.Security - Contains the Certificate provider and + cmdlets used to manage Windows PowerShell security, such as Get-Acl, + Get-AuthenticodeSignature, and ConvertTo-SecureString. -Contains the WSMan provider and cmdlets that manage the Windows Remote Management service, such as Connect-WSMan and Enable-WSManCredSSP. +- Microsoft.PowerShell.Utility - Contains cmdlets used to manipulate objects + and data, such as Get-Member, Write-Host, and Format-List. +- Microsoft.WSMan.Management - Contains the WSMan provider and cmdlets that + manage the Windows Remote Management service, such as Connect-WSMan and + Enable-WSManCredSSP. ## LOGGING SNAP-IN EVENTS -Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets in Windows PowerShell modules and snap-ins by setting the LogPipelineExecutionDetails property of modules and snap-ins to TRUE. For more information, see about_EventLogs (http:\/\/go.microsoft.com\/fwlink\/?LinkID\=113224). +Beginning in Windows PowerShell 3.0, you can record execution events for the +cmdlets in Windows PowerShell modules and snap-ins by setting the +LogPipelineExecutionDetails property of modules and snap-ins to TRUE. For more +information, see [about_EventLogs](about_EventLogs.md). ## SEE ALSO -Add-PsSnapin +[Add-PsSnapin](../Add-PsSnapin.md) -Get-PsSnapin +[Get-PsSnapin](../Get-PsSnapin.md) -Remove-PsSnapin +[Remove-PsSnapin](../Remove-PsSnapin.md) -Export-Console +[Export-Console](../Export-Console.md) -Get-Command +[Get-Command](../Get-Command.md) [about_Profiles](about_Profiles.md) [about_Modules](about_Modules.md) -## KEYWORDS: +## KEYWORDS about_Snapins, about_Snap_ins, about_Snap-ins - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md index 3d20a4dd1c6d..63ac66fd659e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,197 +7,227 @@ title: about_Parameters --- # About Parameters -## about_Parameters - ## SHORT DESCRIPTION -Describes how to work with command parameters in Windows PowerShell®. +Describes how to work with command parameters in Windows PowerShell®. ## LONG DESCRIPTION -Most Windows PowerShell commands, such as cmdlets, functions, and scripts, rely on parameters to allow users to select options or provide input. The parameters follow the command name and have the following form: +Most Windows PowerShell commands, such as cmdlets, functions, and scripts, +rely on parameters to allow users to select options or provide input. The +parameters follow the command name and have the following form: ``` - ``` +The name of the parameter is preceded by a hyphen (-), which signals to +Windows PowerShell that the word following the hyphen is a parameter name. +Some parameters do not require or accept a parameter value. Other parameters +require a value, but do not require the parameter name in the command. -The name of the parameter is preceded by a hyphen (-), which signals to Windows PowerShell that the word following the hyphen is a parameter name. Some parameters do not require or accept a parameter value. Other parameters require a value, but do not require the parameter name in the command. - -The type of parameters and the requirements for those parameters vary. To find information about the parameters of a command, use the Get-Help cmdlet. For example, to find information about the parameters of the Get-ChildItem cmdlet, type: +The type of parameters and the requirements for those parameters vary. To find +information about the parameters of a command, use the Get-Help cmdlet. For +example, to find information about the parameters of the Get-ChildItem cmdlet, +type: -``` +```powershell Get-Help Get-ChildItem ``` +To find information about the parameters of a script, use the full path to the +script file. For example: -To find information about the parameters of a script, use the full path to the script file. For example: - - -``` +```powershell Get-Help $home\Documents\Scripts\Get-Function.ps1 ``` +The Get-Help cmdlet returns various details about the command, including a +description, the command syntax, information about the parameters, and +examples showing how to use the parameters in a command. -The Get-Help cmdlet returns various details about the command, including a description, the command syntax, information about the parameters, and examples showing how to use the parameters in a command. - -You can also use the Parameter parameter of the Get-Help cmdlet to find information about a particular parameter. Or, you can use the Parameter parameter with the wildcard character (\*) value to find information about all parameters of the command. For example, the following command gets information about all parameters of the Get-Member cmdlet: +You can also use the Parameter parameter of the Get-Help cmdlet to find +information about a particular parameter. Or, you can use the Parameter +parameter with the wildcard character (\*) value to find information about all +parameters of the command. For example, the following command gets information +about all parameters of the Get-Member cmdlet: -``` +```powershell Get-Help Get-Member -Parameter * ``` ### DEFAULT PARAMETER VALUES -Optional parameters have a default value, which is the value that is used or assumed when the parameter is not specified in the command. -For example, the default value of the ComputerName parameter of many cmdlets is the name of the local computer. As a result, the local computer name is used in the command unless the ComputerName parameter is specified. +Optional parameters have a default value, which is the value that is used or +assumed when the parameter is not specified in the command. -To find the default parameter value, see help topic for the cmdlet. The parameter description should include the default value. +For example, the default value of the ComputerName parameter of many cmdlets +is the name of the local computer. As a result, the local computer name is +used in the command unless the ComputerName parameter is specified. -You can also set a custom default value for any parameter of a cmdlet or advanced function. For information about setting custom default values, see about_Parameters_Default_Values. +To find the default parameter value, see help topic for the cmdlet. The +parameter description should include the default value. +You can also set a custom default value for any parameter of a cmdlet or +advanced function. For information about setting custom default values, see +[about_Parameters_Default_Values](about_Parameters_Default_Values.md). ### PARAMETER ATTRIBUTE TABLE -When you use the Full, Parameter, or Online parameters of the Get-Help cmdlet, Get-Help displays a parameter attribute table with detailed information about the parameter. -This information includes the details you need to know to use the parameter. For example, the help topic for the Get-ChildItem cmdlet includes the following details about its Path parameter: +When you use the Full, Parameter, or Online parameters of the Get-Help cmdlet, +Get-Help displays a parameter attribute table with detailed information about +the parameter. + +This information includes the details you need to know to use the parameter. +For example, the help topic for the Get-ChildItem cmdlet includes the +following details about its Path parameter: ``` --path - Specifies a path of one or more locations. Wildcard characters are +-path + Specifies a path of one or more locations. Wildcard characters are permitted. The default location is the current directory (.). -``` - - -``` -Required? false -Position? 1 -Default value Current directory -Accept pipeline input? true (ByValue, ByPropertyName) +Required? false +Position? 1 +Default value Current directory +Accept pipeline input? true (ByValue, ByPropertyName) Accept wildcard characters? true ``` +The parameter information includes the parameter syntax, a description of the +parameter, and the parameter attributes. The following sections describe the +parameter attributes. -The parameter information includes the parameter syntax, a description of the parameter, and the parameter attributes. The following sections describe the parameter attributes. +#### Parameter Required? -Parameter Required? +This setting indicates whether the parameter is mandatory, that is, whether +all commands that use this cmdlet must include this parameter. When the value +is "True" and the parameter is missing from the command, Windows PowerShell +prompts you for a value for the parameter. -This setting indicates whether the parameter is mandatory, that is, whether all commands that use this cmdlet must include this parameter. When the value is "True" and the parameter is missing from the command, Windows PowerShell prompts you for a value for the parameter. +#### Parameter Position? -Parameter Position? +This setting indicates whether you can supply a parameter's value without +preceding it with the parameter name. If set to "0" or "named," a parameter +name is required. This type of parameter is referred to as a named parameter. +A named parameter can be listed in any position after the cmdlet name. -This setting indicates whether you can supply a parameter's value without preceding it with the parameter name. If set to "0" or "named," a parameter name is required. This type of parameter is referred to as a named parameter. A named parameter can be listed in any position after the cmdlet name. +If the "Parameter position?" setting is set to an integer other than 0, the +parameter name is not required. This type of parameter is referred to as a +positional parameter, and the number indicates the position in which the +parameter must appear in relation to other positional parameters. If you +include the parameter name for a positional parameter, the parameter can be +listed in any position after the cmdlet name. -If the "Parameter position?" setting is set to an integer other than 0, the parameter name is not required. This type of parameter is referred to as a positional parameter, and the number indicates the position in which the parameter must appear in relation to other positional parameters. If you include the parameter name for a positional parameter, the parameter can be listed in any position after the cmdlet name. +For example, the Get-ChildItem cmdlet has Path and Exclude parameters. The +"Parameter position?" setting for Path is 1, which means that it is a +positional parameter. The "Parameter position?" setting for Exclude is 0, +which means that it is a named parameter. -For example, the Get-ChildItem cmdlet has Path and Exclude parameters. The "Parameter position?" setting for Path is 1, which means that it is a positional parameter. The "Parameter position?" setting for Exclude is 0, which means that it is a named parameter. +This means that Path does not require the parameter name, but its parameter +value must be the first or only unnamed parameter value in the command. +However, because the Exclude parameter is a named parameter, you can place it +in any position in the command. -This means that Path does not require the parameter name, but its parameter value must be the first or only unnamed parameter value in the command. However, because the Exclude parameter is a named parameter, you can place it in any position in the command. +As a result of the "Parameter position?" settings for these two parameters, +you can use any of the following commands: -As a result of the "Parameter position?" settings for these two parameters, you can use any of the following commands: - -``` -Get-ChildItem -path c:\techdocs -exclude *.ppt -Get-ChildItem c:\techdocs -exclude *.ppt -Get-ChildItem -exclude *.ppt -path c:\techdocs +```powershell +Get-ChildItem -path c:\techdocs -exclude *.ppt +Get-ChildItem c:\techdocs -exclude *.ppt +Get-ChildItem -exclude *.ppt -path c:\techdocs Get-ChildItem -exclude *.ppt c:\techdocs ``` +If you were to include another positional parameter without including the +parameter name, that parameter would have to be placed in the order specified +by the "Parameter position?" setting. -If you were to include another positional parameter without including the parameter name, that parameter would have to be placed in the order specified by the "Parameter position?" setting. +#### Parameter Type -Parameter Type +This setting specifies the Microsoft .NET Framework type of the parameter +value. For example, if the type is Int32, the parameter value must be an +integer. If the type is string, the parameter value must be a character +string. If the string contains spaces, the value must be enclosed in quotation +marks, or the spaces must be preceded by the escape character (`). -This setting specifies the Microsoft .NET Framework type of the parameter value. For example, if the type is Int32, the parameter value must be an integer. If the type is string, the parameter value must be a character string. If the string contains spaces, the value must be enclosed in quotation marks, or the spaces must be preceded by the escape character (`). +#### Default Value -Default Value +This setting specifies the value that the parameter will assume if no other +value is provided. For example, the default value of the Path parameter is +often the current directory. Required parameters never have a default value. +For many optional parameters, there is no default because the parameter has no +effect if it is not used. -This setting specifies the value that the parameter will assume if no other value is provided. For example, the default value of the Path parameter is often the current directory. Required parameters never have a default value. For many optional parameters, there is no default because the parameter has no effect if it is not used. +#### Accepts Multiple Values? -Accepts Multiple Values? +This setting indicates whether a parameter accepts multiple parameter values. +When a parameter accepts multiple values, you can type a comma-separated list +as the value of the parameter in the command, or save a comma-separated list +(an array) in a variable, and then specify the variable as the parameter +value. -This setting indicates whether a parameter accepts multiple parameter values. When a parameter accepts multiple values, you can type a comma-separated list as the value of the parameter in the command, or save a comma-separated list (an array) in a variable, and then specify the variable as the parameter value. +For example, the ServiceName parameter of the Get-Service cmdlet accepts +multiple values. The following commands are both valid: -For example, the ServiceName parameter of the Get-Service cmdlet accepts multiple values. The following commands are both valid: - - -``` +```powershell get-service -servicename winrm, netlogon ``` - - -``` -$s = "winrm", "netlogon" +```powershell +$s = "winrm", "netlogon" get-service -servicename $s ``` +#### Accepts Pipeline Input? -Accepts Pipeline Input? - -This setting indicates whether you can use the pipeline operator (|) to send a value to the parameter. - +This setting indicates whether you can use the pipeline operator (|) to +send a value to the parameter. ``` -Value Description ------ ----------- -False Indicates that you cannot pipe a value to the +Value Description +----- ----------- +False Indicates that you cannot pipe a value to the parameter. -``` - - -``` -True (by Value) Indicates that you can pipe any value to the - parameter, just so the value has the .NET - Framework type specified for the parameter or the - value can be converted to the specified .NET +True (by Value) Indicates that you can pipe any value to the + parameter, just so the value has the .NET + Framework type specified for the parameter or the + value can be converted to the specified .NET Framework type. ``` - - -``` -When a parameter is "True (by Value)", Windows -PowerShell tries to associate any piped values -with that parameter before it tries other methods -to interpret the command. -``` - - +When a parameter is "True (by Value)", Windows PowerShell tries to associate +any piped values with that parameter before it tries other methods to +interpret the command. ``` -True (by Property Name) Indicates that you can pipe a value to the - parameter, but the .NET Framework type of the - parameter must include a property with the same +True (by Property Name) Indicates that you can pipe a value to the + parameter, but the .NET Framework type of the + parameter must include a property with the same name as the parameter. ``` +For example, you can pipe a value to a Name parameter only when the value has +a property called "Name". +#### Accepts Wildcard Characters? -``` -For example, you can pipe a value to a Name -parameter only when the value has a property -called "Name". -``` - - -Accepts Wildcard Characters? - -This setting indicates whether the parameter's value can contain wildcard characters so that the parameter value can be matched to more than one existing item in the target container. +This setting indicates whether the parameter's value can contain wildcard +characters so that the parameter value can be matched to more than one +existing item in the target container. -Common Parameters - -Common parameters are parameters that you can use with any cmdlet. For more information about common parameters, see about_CommonParameters +#### Common Parameters +Common parameters are parameters that you can use with any cmdlet. For more +information about common parameters, see [about_CommonParameters](about_CommonParameters.md). ## SEE ALSO @@ -212,4 +242,3 @@ Common parameters are parameters that you can use with any cmdlet. For more info [about_Pipelines](about_Pipelines.md) [about_Wildcards](about_Wildcards.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md index 7d8eb37366e3..39bf01d2725e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,21 +7,20 @@ title: about_PowerShell_exe --- # About PowerShell.exe -## about_PowerShell.exe +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use the PowerShell.exe command-line tool. Displays the syntax +and describes the command-line switches. -Explains how to use the PowerShell.exe command-line tool. Displays -the syntax and describes the command-line switches. +PowerShell.exe starts a Windows PowerShell session. You can use it in Cmd.exe +and in Windows PowerShell. -PowerShell.exe starts a Windows PowerShell session. You can use it -in Cmd.exe and in Windows PowerShell. +## LONG DESCRIPTION -# LONG DESCRIPTION - -# SYNTAX +### SYNTAX +``` PowerShell[.exe] [-EncodedCommand ] [-ExecutionPolicy ] @@ -39,137 +38,143 @@ PowerShell[.exe] [-Command { - | [-args ] | [] } ] PowerShell[.exe] -Help | -? | /? +``` + +### PARAMETERS + +#### -EncodedCommand + +Accepts a base-64-encoded string version of a command. Use this parameter to +submit commands to Windows PowerShell that require complex quotation marks or +curly braces. + +#### -ExecutionPolicy + +Sets the default execution policy for the current session and saves it in the +$env:PSExecutionPolicyPreference environment variable. This parameter does not +change the Windows PowerShell execution policy that is set in the registry. +For information about Windows PowerShell execution policies, including a list +of valid values, see [about_Execution_Policies](about_Execution_Policies.md). + +#### -File [] + +Runs the specified script in the local scope ("dot-sourced"), so that the +functions and variables that the script creates are available in the current +session. Enter the script file path and any parameters. File must be the last +parameter in the command, because all characters typed after the File +parameter name are interpreted as the script file path followed by the script +parameters. + +You can include the parameters of a script, and parameter values, in the value +of the File parameter. For example: -File .\\Get-Script.ps1 -Domain Central + +Typically, the switch parameters of a script are either included or omitted. +For example, the following command uses the All parameter of the +Get-Script.ps1 script file: -File .\\Get-Script.ps1 -All + +In rare cases, you might need to provide a Boolean value for a switch +parameter. To provide a Boolean value for a switch parameter in the value of +the File parameter, enclose the parameter name and value in curly braces, such +as the following: -File .\\Get-Script.ps1 {-All:$False}. + +#### -InputFormat {Text | XML} + +Describes the format of data sent to Windows PowerShell. Valid values are +"Text" (text strings) or "XML" (serialized CLIXML format). + +#### -Mta + +Starts Windows PowerShell using a multi-threaded apartment. This parameter is +introduced in Windows PowerShell 3.0. In Windows PowerShell 2.0, +multi-threaded apartment (MTA) is the default. In Windows PowerShell 3.0, +single-threaded apartment (STA) is the default. + +#### -NoExit -# PARAMETERS - - --EncodedCommand -Accepts a base-64-encoded string version of a command. -Use this parameter to submit commands to Windows PowerShell -that require complex quotation marks or curly braces. - --ExecutionPolicy -Sets the default execution policy for the current session -and saves it in the $env:PSExecutionPolicyPreference environment -variable. This parameter does not change the Windows PowerShell -execution policy that is set in the registry. For information -about Windows PowerShell execution policies, including a list -of valid values, see about_Execution_Policies -(http://go.microsoft.com/fwlink/?LinkID=135170). - --File [] -Runs the specified script in the local scope ("dot-sourced"), -so that the functions and variables that the script creates -are available in the current session. Enter the script file -path and any parameters. File must be the last parameter in -the command, because all characters typed after the File -parameter name are interpreted as the script file path followed -by the script parameters. - -You can include the parameters of a script, and parameter -values, in the value of the File parameter. For example: --File .\Get-Script.ps1 -Domain Central - -Typically, the switch parameters of a script are either -included or omitted. For example, the following command -uses the All parameter of the Get-Script.ps1 script file: --File .\Get-Script.ps1 -All - -In rare cases, you might need to provide a Boolean value -for a switch parameter. To provide a Boolean value for a -switch parameter in the value of the File parameter, -enclose the parameter name and value in curly braces, -such as the following: --File .\Get-Script.ps1 {-All:$False}. - --InputFormat {Text | XML} -Describes the format of data sent to Windows PowerShell. Valid -values are "Text" (text strings) or "XML" (serialized CLIXML format). - --Mta -Starts Windows PowerShell using a multi-threaded apartment. This -parameter is introduced in Windows PowerShell 3.0. In Windows -PowerShell 2.0, multi-threaded apartment (MTA) is the default. -In Windows PowerShell 3.0, single-threaded apartment (STA) is -the default. - --NoExit Does not exit after running startup commands. --NoLogo +#### -NoLogo + Hides the copyright banner at startup. --NonInteractive +#### -NonInteractive + Does not present an interactive prompt to the user. --NoProfile +#### -NoProfile + Does not load the Windows PowerShell profile. --OutputFormat {Text | XML} -Determines how output from Windows PowerShell is formatted. -Valid values are "Text" (text strings) or "XML" (serialized -CLIXML format). - --PSConsoleFile -Loads the specified Windows PowerShell console file. Enter -the path and name of the console file. To create a console file, -use the Export-Console cmdlet in Windows PowerShell. - --Sta -Starts Windows PowerShell using a single-threaded apartment. In -Windows PowerShell 2.0, multi-threaded apartment (MTA) is the default. -In Windows PowerShell 3.0, single-threaded apartment (STA) is the -default. - --Version -Starts the specified version of Windows PowerShell. Valid values -are 2.0 and 3.0. The version that you specify must be installed -on the system. If Windows PowerShell 3.0 is installed on the -computer, "3.0" is the default version. Otherwise, "2.0" is the -default version. For more information, see "Installing Windows -PowerShell" in the Windows PowerShell Getting Started Guide. - --WindowStyle -Sets the window style for the session. Valid values are Normal, -Minimized, Maximized and Hidden. - --Command -Executes the specified commands (and any parameters) as though -they were typed at the Windows PowerShell command prompt, and -then exits, unless the NoExit parameter is specified. - -The value of Command can be "-", a string. or a script block. If -the value of Command is "-", the command text is read from standard -input. - -Script blocks must be enclosed in braces ({}). You can specify a -script block only when running PowerShell.exe in Windows PowerShell. -The results of the script are returned to the parent shell as -deserialized XML objects, not live objects. - -If the value of Command is a string, Command must be the last -parameter in the command , because any characters typed after -the command are interpreted as the command arguments. +#### -OutputFormat {Text | XML} + +Determines how output from Windows PowerShell is formatted. Valid values are +"Text" (text strings) or "XML" (serialized CLIXML format). + +#### -PSConsoleFile + +Loads the specified Windows PowerShell console file. Enter the path and name +of the console file. To create a console file, use the Export-Console cmdlet +in Windows PowerShell. + +#### -Sta + +Starts Windows PowerShell using a single-threaded apartment. In Windows +PowerShell 2.0, multi-threaded apartment (MTA) is the default. In Windows +PowerShell 3.0, single-threaded apartment (STA) is the default. + +#### -Version + +Starts the specified version of Windows PowerShell. Valid values are 2.0 and +3.0. The version that you specify must be installed on the system. If Windows +PowerShell 3.0 is installed on the computer, "3.0" is the default version. +Otherwise, "2.0" is the default version. For more information, see "Installing +Windows PowerShell" in the Windows PowerShell Getting Started Guide. + +#### -WindowStyle + +Sets the window style for the session. Valid values are Normal, Minimized, +Maximized and Hidden. + +#### -Command + +Executes the specified commands (and any parameters) as though they were typed +at the Windows PowerShell command prompt, and then exits, unless the NoExit +parameter is specified. + +The value of Command can be "-", a string. or a script block. If the value of +Command is "-", the command text is read from standard input. + +Script blocks must be enclosed in braces ({}). You can specify a script block +only when running PowerShell.exe in Windows PowerShell. The results of the +script are returned to the parent shell as deserialized XML objects, not live +objects. + +If the value of Command is a string, Command must be the last parameter in the +command , because any characters typed after the command are interpreted as +the command arguments. To write a string that runs a Windows PowerShell command, use the format: + "& {}" -where the quotation marks indicate a string and the invoke operator -(&) causes the command to be executed. --Help, -?, /? -Displays help for PowerShell.exe. If you are typing a PowerShell.exe -command in Windows PowerShell, prepend the command parameters with a -hyphen (-), not a forward slash (/). You can use either a hyphen or -forward slash in Cmd.exe. +where the quotation marks indicate a string and the invoke operator (&) causes +the command to be executed. -# REMARKS: +#### -Help, -?, /? -Troubleshooting note: In Windows PowerShell 2.0, starting some programs -from the Windows PowerShell console fails with a LastExitCode of 0xc0000142. +Displays help for PowerShell.exe. If you are typing a PowerShell.exe command +in Windows PowerShell, prepend the command parameters with a hyphen (-), not a +forward slash (/). You can use either a hyphen or forward slash in Cmd.exe. -# EXAMPLES +### REMARKS +Troubleshooting note: In Windows PowerShell 2.0, starting some programs from +the Windows PowerShell console fails with a LastExitCode of 0xc0000142. + +### EXAMPLES + +```powershell PowerShell -PSConsoleFile sqlsnapin.psc1 PowerShell -Version 2.0 -NoLogo -InputFormat text -OutputFormat XML @@ -177,5 +182,4 @@ PowerShell -Version 2.0 -NoLogo -InputFormat text -OutputFormat XML PowerShell -Command {Get-EventLog -LogName security} PowerShell -Command "& {Get-EventLog -LogName security}" - - +``` \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Providers.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Providers.md index dfed0885c30d..8080f77944b9 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Providers.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Providers.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,61 +7,58 @@ title: about_Providers --- # About Providers -## about_Providers - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes how Windows PowerShell providers provide access to data and -components that would not otherwise be easily accessible at the command -line. The data is presented in a consistent format that resembles a file -system drive. - -# LONG DESCRIPTION - -Windows PowerShell providers are Microsoft .NET Framework-based programs -that make the data in a specialized data store available in Windows -PowerShell so that you can view and manage it. - -The data that a provider exposes appears in a drive, and you access the -data in a path like you would on a hard disk drive. You can use any of the -built-in cmdlets that the provider supports to manage the data in the -provider drive. And, you can use custom cmdlets that are designed -especially for the data. - -The providers can also add dynamic parameters to the built-in cmdlets. -These are parameters that are available only when you use the cmdlet with -the provider data. - -# BUILT-IN PROVIDERS - -Windows PowerShell includes a set of built-in providers that you can use -to access the different types of data stores. - -| Provider | Drive | Data store | -| ----------- | ------------ | ------------------------------------------ | -| Alias | Alias: | Windows PowerShell aliases | -| Certificate | Cert: | x509 certificates for digital signatures | -| Environment | Env: | Windows environment variables | -| FileSystem | (*) | File system drives, directories, and files | -| Function | Function: | Windows PowerShell functions | -| Registry | HKLM:, HKCU: | Windows registry | -| Variable | Variable: | Windows PowerShell variables | -| WSMan | WSMan: | WS-Management configuration information | +components that would not otherwise be easily accessible at the command line. +The data is presented in a consistent format that resembles a file system +drive. + +## LONG DESCRIPTION + +Windows PowerShell providers are Microsoft .NET Framework-based programs that +make the data in a specialized data store available in Windows PowerShell so +that you can view and manage it. + +The data that a provider exposes appears in a drive, and you access the data +in a path like you would on a hard disk drive. You can use any of the built-in +cmdlets that the provider supports to manage the data in the provider drive. +And, you can use custom cmdlets that are designed especially for the data. + +The providers can also add dynamic parameters to the built-in cmdlets. These +are parameters that are available only when you use the cmdlet with the +provider data. + +## BUILT-IN PROVIDERS + +Windows PowerShell includes a set of built-in providers that you can use to +access the different types of data stores. + +|Provider |Drive |Data store | +|------------|-------------|-------------------------------------------| +|Alias |Alias: |Windows PowerShell aliases | +|Certificate |Cert: |x509 certificates for digital signatures | +|Environment |Env: |Windows environment variables | +|FileSystem |(*) |File system drives, directories, and files | +|Function |Function: |Windows PowerShell functions | +|Registry |HKLM:, HKCU: |Windows registry | +|Variable |Variable: |Windows PowerShell variables | +|WSMan |WSMan: |WS-Management configuration information | (*) The FileSystem drives vary on each system. -You can also create your own Windows PowerShell providers, and you can -install providers that others develop. To list the providers that are -available in your session, type: +You can also create your own Windows PowerShell providers, and you can install +providers that others develop. To list the providers that are available in +your session, type: get-psprovider -# INSTALLING AND REMOVING PROVIDERS +## INSTALLING AND REMOVING PROVIDERS Windows PowerShell providers are delivered to you in Windows PowerShell -snap-ins, which are .NET Framework-based programs that are compiled -into .dll files. The snap-ins can include providers and cmdlets. +snap-ins, which are .NET Framework-based programs that are compiled into .dll +files. The snap-ins can include providers and cmdlets. Before you use the provider features, you have to install the snap-in and then add it to your Windows PowerShell session. For more information, see @@ -76,96 +73,99 @@ cmdlet. This cmdlet does not uninstall the provider, but it makes the provider unavailable in the session. You can also use the Remove-PSDrive cmdlet to remove any drive from the -current session. This data on the drive is not affected, but the drive is -no longer available in that session. +current session. This data on the drive is not affected, but the drive is no +longer available in that session. -# VIEWING PROVIDERS +## VIEWING PROVIDERS To view the Windows PowerShell providers on your computer, type: +```powershell get-psprovider +``` -The output lists the built-in providers and the providers that you added -to the session. +The output lists the built-in providers and the providers that you added to +the session. -# THE PROVIDER CMDLETS +## THE PROVIDER CMDLETS -The following cmdlets are designed to work with the data exposed by -any provider. You can use the same cmdlets in the same way to manage -the different types of data that providers expose. After you -learn to manage the data of one provider, you can use the same -procedures with the data from any provider. +The following cmdlets are designed to work with the data exposed by any +provider. You can use the same cmdlets in the same way to manage the different +types of data that providers expose. After you learn to manage the data of one +provider, you can use the same procedures with the data from any provider. -For example, the New-Item cmdlet creates a new item. In the C: drive that -is supported by the FileSystem provider, you can use New-Item to create a -new file or folder. In the drives that are supported by the Registry -provider, you can use New-Item to create a new registry key. In the Alias: -drive, you can use New-Item to create a new alias. +For example, the New-Item cmdlet creates a new item. In the C: drive that is +supported by the FileSystem provider, you can use New-Item to create a new +file or folder. In the drives that are supported by the Registry provider, you +can use New-Item to create a new registry key. In the Alias: drive, you can +use New-Item to create a new alias. For detailed information about any of the following cmdlets, type: +``` get-help -detailed +``` -# CHILDITEM CMDLETS +### CHILDITEM CMDLETS -Get-ChildItem +- Get-ChildItem -# CONTENT CMDLETS +### CONTENT CMDLETS -Add-Content -Clear-Content -Get-Content -Set-Content +- Add-Content +- Clear-Content +- Get-Content +- Set-Content -# ITEM CMDLETS +### ITEM CMDLETS -Clear-Item -Copy-Item -Get-Item -Invoke-Item -Move-Item -New-Item -Remove-Item -Rename-Item -Set-Item +- Clear-Item +- Copy-Item +- Get-Item +- Invoke-Item +- Move-Item +- New-Item +- Remove-Item +- Rename-Item +- Set-Item -# ITEMPROPERTY CMDLETS +### ITEMPROPERTY CMDLETS -Clear-ItemProperty -Copy-ItemProperty -Get-ItemProperty -Move-ItemProperty -New-ItemProperty -Remove-ItemProperty -Rename-ItemProperty -Set-ItemProperty +- Clear-ItemProperty +- Copy-ItemProperty +- Get-ItemProperty +- Move-ItemProperty +- New-ItemProperty +- Remove-ItemProperty +- Rename-ItemProperty +- Set-ItemProperty -# LOCATION CMDLETS +### LOCATION CMDLETS -Get-Location -Pop-Location -Push-Location -Set-Location +- Get-Location +- Pop-Location +- Push-Location +- Set-Location -# PATH CMDLETS +### PATH CMDLETS -Join-Path -Convert-Path -Split-Path -Resolve-Path -Test-Path +- Join-Path +- Convert-Path +- Split-Path +- Resolve-Path +- Test-Path -# PSDRIVE CMDLETS +### PSDRIVE CMDLETS -Get-PSDrive -New-PSDrive -Remove-PSDrive +- Get-PSDrive +- New-PSDrive +- Remove-PSDrive -# PSPROVIDER CMDLETS +### PSPROVIDER CMDLETS -Get-PSProvider +- Get-PSProvider -# VIEWING PROVIDER DATA +## VIEWING PROVIDER DATA The primary benefit of a provider is that it exposes its data in a familiar and consistent way. The model for data presentation is a file system @@ -190,85 +190,108 @@ To view the contents of a provider drive, use the Get-Item or Get-ChildItem cmdlets. Type the drive name followed by a colon (:). For example, to view the contents of the Alias: drive, type: +```powershell get-item alias: +``` You can view and manage the data in any drive from another drive by including the drive name in the path. For example, to view the HKLM\Software registry key in the HKLM: drive from another drive, type: +```powershell get-childitem hklm:\software +``` To open the drive, use the Set-Location cmdlet. Remember the colon when you specify the drive path. For example, to change your location to the root directory of the Cert: drive, type: +```powershell set-location cert: +``` Then, to view the contents of the Cert: drive, type: +```powershell get-childitem +``` -# MOVING THROUGH HIERARCHICAL DATA +## MOVING THROUGH HIERARCHICAL DATA You can move through a provider drive just as you would a hard disk drive. If the data is arranged in a hierarchy of items within items, use a backslash () to indicate a child item. Use the following format: +``` drive:\location\child-location\... +``` For example, to change your location to the HKLM\Software registry key, type a Set-Location command, such as: +```powershell set-location hklm:\software +``` You can also use relative references to locations. A dot (.) represents the current location. For example, if you are in the HKLM:\Software\Microsoft registry key, and you want to list the registry subkeys in the HKLM:\Software\Microsoft\PowerShell key, type the following command: +```powershell get-childitem .\PowerShell +``` -# FINDING DYNAMIC PARAMETERS +## FINDING DYNAMIC PARAMETERS -Dynamic parameters are cmdlet parameters that are added to a cmdlet -by a provider. These parameters are available only when the cmdlet is -used with the provider that added them. +Dynamic parameters are cmdlet parameters that are added to a cmdlet by a +provider. These parameters are available only when the cmdlet is used with the +provider that added them. -For example, the Cert: drive adds the CodeSigningCert parameter -to the Get-Item and Get-ChildItem cmdlets. You can use this parameter -only when you use Get-Item or Get-ChildItem in the Cert: drive. +For example, the Cert: drive adds the CodeSigningCert parameter to the +Get-Item and Get-ChildItem cmdlets. You can use this parameter only when you +use Get-Item or Get-ChildItem in the Cert: drive. -For a list of the dynamic parameters that a provider supports, see the -Help file for the provider. Type: +For a list of the dynamic parameters that a provider supports, see the Help +file for the provider. Type: +``` get-help +``` For example: +```powershell get-help certificate +``` -# LEARNING ABOUT PROVIDERS +## LEARNING ABOUT PROVIDERS -Although all provider data appears in drives, and you use the same methods -to move through them, the similarity stops there. The data stores that -the provider exposes can be as varied as Active Directory locations and -Microsoft Exchange Server mailboxes. +Although all provider data appears in drives, and you use the same methods to +move through them, the similarity stops there. The data stores that the +provider exposes can be as varied as Active Directory locations and Microsoft +Exchange Server mailboxes. For information about individual Windows PowerShell providers, type: +``` get-help +``` For example: +```powershell get-help registry +``` For a list of Help topics about the providers, type: +```powershell get-help * -category provider +``` -# SEE ALSO +## SEE ALSO -about_Locations +[about_Locations](about_Locations.md) [about_Path_Syntax](about_Path_Syntax.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 8e80d2130ae4..8df82dca043b 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,290 +7,272 @@ title: about_Quoting_Rules --- # About Quoting Rules -## about_Quoting_Rules - ## SHORT DESCRIPTION -Describes rules for using single and double quotation marks in Windows PowerShell®. +Describes rules for using single and double quotation marks in PowerShell. ## LONG DESCRIPTION -Quotation marks are used to specify a literal string. You can enclose a string in single quotation marks (') or double quotation marks ("). -Quotation marks are also used to create a here-string. A here-string is a single-quoted or double-quoted string in which quotation marks are interpreted literally. A here-string can span multiple lines. All the lines in a here-string are interpreted as strings, even though they are not enclosed in quotation marks. +Quotation marks are used to specify a literal string. You can enclose a string +in single quotation marks (') or double quotation marks ("). -In commands to remote computers, quotation marks define the parts of the command that are run on the remote computer. In a remote session, quotation marks also determine whether the variables in a command are interpreted first on the local computer or on the remote computer. +Quotation marks are also used to create a here-string. A here-string is a +single-quoted or double-quoted string in which quotation marks are interpreted +literally. A here-string can span multiple lines. All the lines in a +here-string are interpreted as strings, even though they are not enclosed in +quotation marks. +In commands to remote computers, quotation marks define the parts of the +command that are run on the remote computer. In a remote session, quotation +marks also determine whether the variables in a command are interpreted first +on the local computer or on the remote computer. ### SINGLE AND DOUBLE-QUOTED STRINGS -When you enclose a string in double quotation marks (a double-quoted string), variable names that are preceded by a dollar sign ($) are replaced with the variable's value before the string is passed to the command for processing. -For example: +When you enclose a string in double quotation marks (a double-quoted string), +variable names that are preceded by a dollar sign ($) are replaced with the +variable's value before the string is passed to the command for processing. +For example: -``` +```powershell $i = 5 "The value of $i is $i." ``` - The output of this command is: - -``` +```output The value of 5 is 5. ``` +Also, in a double-quoted string, expressions are evaluated, and the result is +inserted in the string. For example: -Also, in a double-quoted string, expressions are evaluated, and the result is inserted in the string. For example: - - -``` +```powershell "The value of $(2+3) is 5." ``` - The output of this command is: - -``` +```output The value of 5 is 5. ``` +When you enclose a string in single-quotation marks (a single-quoted string), +the string is passed to the command exactly as you type it. No substitution is +performed. For example: -When you enclose a string in single-quotation marks (a single-quoted string), the string is passed to the command exactly as you type it. No substitution is performed. For example: - - -``` +```powershell $i = 5 'The value of $i is $i.' ``` - The output of this command is: - -``` +```output The value $i is $i. ``` +Similarly, expressions in single-quoted strings are not evaluated. They are +interpreted as literals. For example: -Similarly, expressions in single-quoted strings are not evaluated. They are interpreted as literals. For example: - - -``` +```powershell 'The value of $(2+3) is 5.' ``` - The output of this command is: - -``` +```output The value of $(2+3) is 5. ``` +To prevent the substitution of a variable value in a double-quoted string, use +the backtick character (`)(ASCII 96), which is the Windows PowerShell escape +character. -To prevent the substitution of a variable value in a double-quoted string, use the backtick character (`)(ASCII 96), which is the Windows PowerShell escape character. - -In the following example, the backtick character that precedes the first $i variable prevents Windows PowerShell from replacing the variable name with its value. For example: - +In the following example, the backtick character that precedes the first $i +variable prevents Windows PowerShell from replacing the variable name with its +value. For example: -``` +```powershell $i = 5 "The value of `$i is $i." ``` - The output of this command is: - -``` +```output The value $i is 5. ``` +To make double-quotation marks appear in a string, enclose the entire string +in single quotation marks. For example: -To make double-quotation marks appear in a string, enclose the entire string in single quotation marks. For example: - - -``` +```powershell 'As they say, "live and learn."' ``` - The output of this command is: - -``` +```output As they say, "live and learn." ``` +You can also enclose a single-quoted string in a double-quoted string. For +example: -You can also enclose a single-quoted string in a double-quoted string. For example: - - -``` +```powershell "As they say, 'live and learn.'" ``` - The output of this command is: - -``` +```output As they say, 'live and learn.' ``` - Or, double the quotation marks around a double-quoted phrase. For example: - -``` +```powershell "As they say, ""live and learn.""" ``` - The output of this command is: - -``` +```output As they say, "live and learn." ``` +To include a single quotation mark in a single-quoted string, use a second +consecutive single quote. For example: -To include a single quotation mark in a single-quoted string, use a second consecutive single quote. For example: - - -``` +```powershell 'don''t' ``` - The output of this command is: - -``` +```output don't ``` +To force Windows PowerShell to interpret a double quotation mark literally, +use a backtick character. This prevents Windows PowerShell from interpreting +the quotation mark as a string delimiter. For example: -To force Windows PowerShell to interpret a double quotation mark literally, use a backtick character. This prevents Windows PowerShell from interpreting the quotation mark as a string delimiter. For example: - - -``` +```powershell "Use a quotation mark (`") to begin a string." ``` +Because the contents of single-quoted strings are interpreted literally, you +cannot use the backtick character to force a literal character interpretation +in a single-quoted string. -Because the contents of single-quoted strings are interpreted literally, you cannot use the backtick character to force a literal character interpretation in a single-quoted string. - -For example, the following command generates an error because Windows PowerShell does not recognize the escape character. Instead, it interprets the second quotation mark as the end of the string. - +For example, the following command generates an error because Windows +PowerShell does not recognize the escape character. Instead, it interprets the +second quotation mark as the end of the string. -``` +```output PS C:\> 'Use a quotation mark (`') to begin a string.' Unexpected token ')' in expression or statement. At line:1 char:27 + 'Use a quotation mark (`') <<<< to begin a string.' ``` - - ### HERE-STRINGS + The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation marks are interpreted literally. A here-string can span multiple lines. All the lines in a here-string are interpreted as strings even though they are not enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string in which quotation +marks are interpreted literally. A here-string can span multiple lines. All +the lines in a here-string are interpreted as strings even though they are not +enclosed in quotation marks. -Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by their values. +Like regular strings, variables are replaced by their values in double-quoted +here-strings. In single-quoted here-strings, variables are not replaced by +their values. -You can use here-strings for any text, but they are particularly useful for the following kinds of text: +You can use here-strings for any text, but they are particularly useful for +the following kinds of text: --- Text that contains literal quotation marks --- Multiple lines of text, such as the text in an HTML or XML --- The Help text for a script or function document +- Text that contains literal quotation marks +- Multiple lines of text, such as the text in an HTML or XML +- The Help text for a script or function document -A here-string can have either of the following formats, where represents the linefeed or newline hidden character that is added when you press the ENTER key. +A here-string can have either of the following formats, where \ +represents the linefeed or newline hidden character that is added when you +press the ENTER key. +Double-quotes: ``` -Double-quotes: - @" - [string] ... - "@ +@" + [string] ... +"@ ``` - - -``` Single-quotes: - @' - [string] ... - '@ +``` +@' + [string] ... +'@ ``` +In either format, the closing quotation mark must be the first character in +the line. -In either format, the closing quotation mark must be the first character in the line. - -A here-string contains all the text between the two hidden characters. In the here-string, all quotation marks are interpreted literally. For example: - +A here-string contains all the text between the two hidden characters. In the +here-string, all quotation marks are interpreted literally. For example: -``` +```powershell @" For help, type "get-help" "@ ``` - The output of this command is: - -``` +```output For help, type "get-help" ``` - Using a here-string can simplify using a string in a command. For example: - -``` +```powershell @" Use a quotation mark (') to begin a string. "@ ``` - The output of this command is: - -``` +```output Use a quotation mark (') to begin a string. ``` +In single-quoted here-strings, variables are interpreted literally and +reproduced exactly. For example: -In single-quoted here-strings, variables are interpreted literally and reproduced exactly. For example: - - -``` +```powershell @' The $profile variable contains the path of your Windows PowerShell profile. '@ ``` - The output of this command is: - -``` +```output The $profile variable contains the path of your Windows PowerShell profile. ``` +In double-quoted here-strings, variables are replaced by their values. For +example: -In double-quoted here-strings, variables are replaced by their values. For example: - - -``` +```powershell @" Even if you have not created a profile, the path of the profile file is: @@ -298,21 +280,19 @@ $profile. "@ ``` - The output of this command is: - -``` +```output Even if you have not created a profile, the path of the profile file is: -C:\Users\User01\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1. +C:\Users\User1\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1. ``` +Here-strings are typically used to assign multiple lines to a variable. For +example, the following here-string assigns a page of XML to the $page +variable. -Here-strings are typically used to assign multiple lines to a variable. For example, the following here-string assigns a page of XML to the $page variable. - - -``` +```powershell $page = [XML] @" "@ ``` - -Here-strings are also a convenient format for input to the ConvertFrom-StringData cmdlet, which converts here-strings to hash tables. For more information, see ConvertFrom-StringData. - - -## KEYWORDS -about_Here-Strings - -about_Quotes - -about_Quotation_Marks - +Here-strings are also a convenient format for input to the +ConvertFrom-StringData cmdlet, which converts here-strings to hash tables. For +more information, see ConvertFrom-StringData. ## SEE ALSO [about_Special_Characters](about_Special_Characters.md) -ConvertFrom-StringData +[ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote.md index ac5e0c6fa90a..36455b275f7e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,73 +7,74 @@ title: about_Remote --- # About Remote -## about_Remote - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes how to run remote commands in Windows PowerShell. -# LONG DESCRIPTION - -You can run remote commands on a single computer or on multiple -computers by using a temporary or persistent connection. You can also -start an interactive session with a single remote computer. +## LONG DESCRIPTION -This topic provides a series of examples to show you how to -run different types of remote command. After you try these basic -commands, read the Help topics that describe each cmdlet that is -used in these commands. The topics provide the details and explain -how you can modify the commands to meet your needs. +You can run remote commands on a single computer or on multiple computers by +using a temporary or persistent connection. You can also start an interactive +session with a single remote computer. -Note: To use Windows PowerShell remoting, the local and remote computers -must be configured for remoting. For more information, see -about_Remote_Requirements. +This topic provides a series of examples to show you how to run different +types of remote command. After you try these basic commands, read the Help +topics that describe each cmdlet that is used in these commands. The topics +provide the details and explain how you can modify the commands to meet your +needs. -# HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION) +Note: To use Windows PowerShell remoting, the local and remote computers must +be configured for remoting. For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). +## HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION) -The easiest way to run remote commands is to start an -interactive session with a remote computer. +The easiest way to run remote commands is to start an interactive session with +a remote computer. -When the session starts, the commands that you type run on the -remote computer, just as though you typed them directly -on the remote computer. You can connect to only one -computer in each interactive session. +When the session starts, the commands that you type run on the remote +computer, just as though you typed them directly on the remote computer. You +can connect to only one computer in each interactive session. -To start an interactive session, use the Enter-PSSession -cmdlet. The following command starts an interactive session -with the Server01 computer: +To start an interactive session, use the Enter-PSSession cmdlet. The following +command starts an interactive session with the Server01 computer: +```powershell Enter-PSSession Server01 +``` -The command prompt changes to indicate that you are connected -to the Server01 computer. +The command prompt changes to indicate that you are connected to the Server01 +computer. +``` Server01\PS> +``` Now, you can type commands on the Server01 computer. To end the interactive session, type: +```powershell Exit-PSSession +``` For more information, see Enter-PSSession. -# HOW TO USE CMDLETS THAT HAVE A COMPUTERNAME PARAMETER TO GET REMOTE DATA +## HOW TO USE CMDLETS THAT HAVE A COMPUTERNAME PARAMETER TO GET REMOTE DATA - -Several cmdlets have a ComputerName parameter that lets you -get objects from remote computers. +Several cmdlets have a ComputerName parameter that lets you get objects from +remote computers. Because these cmdlets do not use WS-Management-based Windows PowerShell remoting, you can use the ComputerName parameter of these cmdlets on any -computer that is running Windows PowerShell. The computers do not have to -be configured for Windows PowerShell remoting, and the computers do not -have to meet the system requirements for remoting. +computer that is running Windows PowerShell. The computers do not have to be +configured for Windows PowerShell remoting, and the computers do not have to +meet the system requirements for remoting. The following cmdlets have a ComputerName parameter: +``` Clear-EventLog Limit-EventLog Get-Counter New-EventLog Get-EventLog Remove-EventLog @@ -82,15 +83,18 @@ Get-Process Show-EventLog Get-Service Stop-Computer Get-WinEvent Test-Connection Get-WmiObject Write-EventLog +``` For example, the following command gets the services on the Server01 remote computer: +```powershell Get-Service -ComputerName Server01 +``` -Typically, cmdlets that support remoting without special configuration -have a **ComputerName** parameter and do not have a **Session** parameter. -To find these cmdlets in your session, type: +Typically, cmdlets that support remoting without special configuration have a +**ComputerName** parameter and do not have a **Session** parameter. To find +these cmdlets in your session, type: ```powershell Get-Command | Where-Object { @@ -99,131 +103,134 @@ Get-Command | Where-Object { } ``` -# HOW TO RUN A REMOTE COMMAND +## HOW TO RUN A REMOTE COMMAND +To run other commands on remote computers, use the Invoke-Command cmdlet. -To run other commands on remote computers, use the -Invoke-Command cmdlet. +To run a single command or a few unrelated commands, use the ComputerName +parameter of Invoke-Command to specify the remote computers. Use the +ScriptBlock parameter to specify the command. -To run a single command or a few unrelated commands, use the -ComputerName parameter of Invoke-Command to specify the remote -computers. Use the ScriptBlock parameter to specify the command. - -For example, the following command runs a Get-Culture command -on the Server01 computer. +For example, the following command runs a Get-Culture command on the Server01 +computer. +```powershell Invoke-Command -ComputerName Server01 -ScriptBlock {Get-Culture} +``` -The ComputerName parameter is designed for situation in which you run -a single command or several unrelated commands on one or many computers. -To establish a persistent connection to a remote computer, use -the Session parameter. - -# HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION) +The ComputerName parameter is designed for situation in which you run a single +command or several unrelated commands on one or many computers. To establish a +persistent connection to a remote computer, use the Session parameter. +## HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION) -When you use the ComputerName parameter of the Invoke-Command -cmdlet, Windows PowerShell establishes a connection just for the -command. Then, it closes the connection when the command is complete. Any -variables or functions that are defined in the command are lost. +When you use the ComputerName parameter of the Invoke-Command cmdlet, Windows +PowerShell establishes a connection just for the command. Then, it closes the +connection when the command is complete. Any variables or functions that are +defined in the command are lost. -To create a persistent connection to a remote computer, use the -New-PSSession cmdlet. For example, the following command creates -PSSessions on the Server01 and Server02 computers and then saves the -PSSessions in the $s variable. +To create a persistent connection to a remote computer, use the New-PSSession +cmdlet. For example, the following command creates PSSessions on the Server01 +and Server02 computers and then saves the PSSessions in the $s variable. +```powershell $s = New-PSSession -ComputerName Server01, Server02 +``` -# HOW TO RUN COMMANDS IN A PSSESSION - +## HOW TO RUN COMMANDS IN A PSSESSION -With a PSSession, you can run a series of remote commands that -share data, like functions, aliases, and the values of variables. -To run commands in a PSSession, use the Session parameter of the -Invoke-Command cmdlet. +With a PSSession, you can run a series of remote commands that share data, +like functions, aliases, and the values of variables. To run commands in a +PSSession, use the Session parameter of the Invoke-Command cmdlet. -For example, the following command uses the Invoke-Command cmdlet -to run a Get-Process command in the PSSessions on the Server01 -and Server02 computers. The command saves the processes in a $p -variable in each PSSession. +For example, the following command uses the Invoke-Command cmdlet to run a +Get-Process command in the PSSessions on the Server01 and Server02 computers. +The command saves the processes in a $p variable in each PSSession. +```powershell Invoke-Command -Session $s -ScriptBlock {$p = Get-Process} +``` -Because the PSSession uses a persistent connection, you can run -another command in the same PSSession that uses the $p variable. -The following command counts the number of processes saved in $p. +Because the PSSession uses a persistent connection, you can run another +command in the same PSSession that uses the $p variable. The following command +counts the number of processes saved in $p. +```powershell Invoke-Command -Session $s -ScriptBlock {$p.count} +``` -# HOW TO RUN A REMOTE COMMAND ON MULTIPLE COMPUTERS - +## HOW TO RUN A REMOTE COMMAND ON MULTIPLE COMPUTERS -To run a remote command on multiple computers, type all of -the computer names in the value of the ComputerName parameter of -Invoke-Command. Separate the names with commas. +To run a remote command on multiple computers, type all of the computer names +in the value of the ComputerName parameter of Invoke-Command. Separate the +names with commas. -For example, the following command runs a Get-Culture command -on three computers: +For example, the following command runs a Get-Culture command on three +computers: +```powershell Invoke-Command -ComputerName S1, S2, S3 -ScriptBlock {Get-Culture} +``` -You can also run a command in multiple PSSessions. The following -commands create PSSessions on the Server01, Server02, and Server03 -computers and then run a Get-Culture command in each of the PSSessions. +You can also run a command in multiple PSSessions. The following commands +create PSSessions on the Server01, Server02, and Server03 computers and then +run a Get-Culture command in each of the PSSessions. +```powershell $s = New-PSSession -ComputerName S1, S2, S3 Invoke-Command -Session $s -ScriptBlock {Get-Culture} +``` To include the local computer list of computers, type the name of the local computer, type a dot (.), or type "localhost". +```powershell Invoke-Command -ComputerName S1, S2, S3, localhost -ScriptBlock {Get-Culture} +``` -# HOW TO RUN A SCRIPT ON REMOTE COMPUTERS - +## HOW TO RUN A SCRIPT ON REMOTE COMPUTERS -To run a local script on remote computers, use the -FilePath parameter of Invoke-Command. +To run a local script on remote computers, use the FilePath parameter of +Invoke-Command. -For example, the following command runs the Sample.ps1 script -on the S1 and S2 computers: +For example, the following command runs the Sample.ps1 script on the S1 and S2 +computers: +```powershell Invoke-Command -ComputerName S1, S2 -FilePath C:\Test\Sample.ps1 +``` -The results of the script are returned to the local computer. You -do not need to copy any files. - -# HOW TO STOP A REMOTE COMMAND - +The results of the script are returned to the local computer. You do not need +to copy any files. -To interrupt a command, press CTRL+C. The interrupt request is -passed to the remote computer where it terminates the remote command. +## HOW TO STOP A REMOTE COMMAND -# FOR MORE INFORMATION +To interrupt a command, press CTRL+C. The interrupt request is passed to the +remote computer where it terminates the remote command. +## FOR MORE INFORMATION --- For information about the system requirements for remoting, -see about_Remote_Requirements. +- For information about the system requirements for remoting, see + [about_Remote_Requirements](about_Remote_Requirements.md). --- For help in formatting remote output, see about_Remote_Output. +- For help in formatting remote output, see [about_Remote_Output](about_Remote_Output.md). --- For information about how remoting works, how to manage remote -data, special configurations, security issues, and other frequently -asked questions, see about_Remote_FAQ. +- For information about how remoting works, how to manage remote data, special + configurations, security issues, and other frequently asked questions, see + [about_Remote_FAQ](about_Remote_FAQ.md). --- For help in resolving remoting errors, see about_Remote_Troubleshooting. +- For help in resolving remoting errors, see about_Remote_Troubleshooting. --- For information about PSSessions and persistent connections, see -about_PSSessions. +- For information about PSSessions and persistent connections, see + [about_PSSessions](about_PSSessions.md). --- For information about Windows PowerShell background jobs, see -about_Jobs. +- For information about Windows PowerShell background jobs, see [about_Jobs](about_Jobs.md). -# KEYWORDS +## KEYWORDS about_Remoting -# SEE ALSO +## SEE ALSO [about_PSSessions](about_PSSessions.md) @@ -237,9 +244,8 @@ about_Remoting [about_Remote_Variables](about_Remote_Variables.md) -Enter-PSSession - -Invoke-Command +[Enter-PSSession](../Enter-PSSession.md) -New-PSSession +[Invoke-Command](../Invoke-Command.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md index eda447268fcd..445c1fa6f6b9 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,77 +7,71 @@ title: about_Remote_Requirements --- # About Remote Requirements -## about_Remote_Requirements +## SHORT DESCRIPTION +Describes the system requirements and configuration requirements for running +remote commands in Windows PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes the system requirements and configuration requirements for -running remote commands in Windows PowerShell. - -# LONG DESCRIPTION - -This topic describes the system requirements, user requirements, and -resource requirements for establishing remote connections and running -remote commands in Windows PowerShell. It also provides instructions for -configuring remote operations. +This topic describes the system requirements, user requirements, and resource +requirements for establishing remote connections and running remote commands +in Windows PowerShell. It also provides instructions for configuring remote +operations. Note: Many cmdlets (including the Get-Service, Get-Process, Get-WMIObject, -Get-EventLog, and Get-WinEvent cmdlets) get objects from remote -computers by using Microsoft .NET Framework methods to retrieve the -objects. They do not use the Windows PowerShell remoting -infrastructure. The requirements in this document do not apply to -these cmdlets. +Get-EventLog, and Get-WinEvent cmdlets) get objects from remote computers by +using Microsoft .NET Framework methods to retrieve the objects. They do not +use the Windows PowerShell remoting infrastructure. The requirements in this +document do not apply to these cmdlets. -To find the cmdlets that have a ComputerName parameter but do not use -Windows PowerShell remoting, read the description of the ComputerName -parameter of the cmdlets. - -# SYSTEM REQUIREMENTS +To find the cmdlets that have a ComputerName parameter but do not use Windows +PowerShell remoting, read the description of the ComputerName parameter of the +cmdlets. +## SYSTEM REQUIREMENTS To run remote sessions on Windows PowerShell 3.0, the local and remote computers must have the following: --- Windows PowerShell 3.0 or later --- The Microsoft .NET Framework 4 or later --- Windows Remote Management 3.0 +- Windows PowerShell 3.0 or later +- The Microsoft .NET Framework 4 or later +- Windows Remote Management 3.0 -To run remote sessions on Windows PowerShell 2.0, the local and remote computers -must have the following: +To run remote sessions on Windows PowerShell 2.0, the local and remote +computers must have the following: --- Windows PowerShell 2.0 or later --- The Microsoft .NET Framework 2.0 or later --- Windows Remote Management 2.0 +- Windows PowerShell 2.0 or later +- The Microsoft .NET Framework 2.0 or later +- Windows Remote Management 2.0 -You can create remote sessions between computers running Windows PowerShell 2.0 -and Windows PowerShell 3.0. However, features that run only on Windows -PowerShell 3.0, such as the ability to disconnect and reconnect to sessions, are -available only when both computers are running Windows PowerShell 3.0. +You can create remote sessions between computers running Windows PowerShell +2.0 and Windows PowerShell 3.0. However, features that run only on Windows +PowerShell 3.0, such as the ability to disconnect and reconnect to sessions, +are available only when both computers are running Windows PowerShell 3.0. To find the version number of an installed version of Windows PowerShell, use the $PSVersionTable automatic variable. -Windows Remote Management (WinRM) 3.0 and Microsoft .NET Framework 4 are included -in Windows 8, Windows Server 2012, and newer releases of the Windows operating -system. WinRM 3.0 is included in Windows Management Framework 3.0 for older -operating systems. If the computer does not have the required version of -WinRM or the Microsoft .NET Framework, the installation fails. - -# USER PERMISSIONS +Windows Remote Management (WinRM) 3.0 and Microsoft .NET Framework 4 are +included in Windows 8, Windows Server 2012, and newer releases of the Windows +operating system. WinRM 3.0 is included in Windows Management Framework 3.0 +for older operating systems. If the computer does not have the required +version of WinRM or the Microsoft .NET Framework, the installation fails. +## USER PERMISSIONS To create remote sessions and run remote commands, by default, the current user must be a member of the Administrators group on the remote computer or provide the credentials of an administrator. Otherwise, the command fails. The permissions required to create sessions and run commands on a remote -computer (or in a remote session on the local computer) are established by -the session configuration (also known as an "endpoint") on the remote -computer to which the session connects. Specifically, the security -descriptor on the session configuration determines who has access to the -session configuration and who can use it to connect. +computer (or in a remote session on the local computer) are established by the +session configuration (also known as an "endpoint") on the remote computer to +which the session connects. Specifically, the security descriptor on the +session configuration determines who has access to the session configuration +and who can use it to connect. The security descriptors on the default session configurations, Microsoft.PowerShell, Microsoft.PowerShell32, and @@ -85,48 +79,50 @@ Microsoft.PowerShell.Workflow, allow access only to members of the Administrators group. If the current user doesn't have permission to use the session configuration, -the command to run a command (which uses a temporary session) or create -a persistent session on the remote computer fails. The user can use the +the command to run a command (which uses a temporary session) or create a +persistent session on the remote computer fails. The user can use the ConfigurationName parameter of cmdlets that create sessions to select a different session configuration, if one is available. Members of the Administrators group on a computer can determine who has permission to connect to the computer remotely by changing the security -descriptors on the default session configurations and by creating new -session configurations with different security descriptors. +descriptors on the default session configurations and by creating new session +configurations with different security descriptors. For more informations about session configurations, see -about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). +[about_Session_Configurations](about_Session_Configurations.md). -# WINDOWS NETWORK LOCATIONS +## WINDOWS NETWORK LOCATIONS Beginning in Windows PowerShell 3.0, the Enable-PSRemoting cmdlet can enable remoting on client and server versions of Windows on private, domain, and public networks. On server versions of Windows with private and domain networks, the -Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted -remote access. It also creates a firewall rule for public networks that -allows remote access only from computers in the same local subnet. This -local subnet firewall rule is enabled by default on server versions of -Windows on public networks, but Enable-PSRemoting reapplies the rule in -case it was changed or deleted. - -On client versions of Windows with private and domain networks, by -default, the Enable-PSRemoting cmdlet creates firewall rules that -allow unrestricted remote access. - -To enable remoting on client versions of Windows with public networks, -use the SkipNetworkProfileCheck parameter of the Enable-PSRemoting cmdlet. -It creates a firewall rule that that allows remote access only from -computers in the same local subnet. +Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted remote +access. It also creates a firewall rule for public networks that allows remote +access only from computers in the same local subnet. This local subnet +firewall rule is enabled by default on server versions of Windows on public +networks, but Enable-PSRemoting reapplies the rule in case it was changed or +deleted. + +On client versions of Windows with private and domain networks, by default, +the Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted +remote access. + +To enable remoting on client versions of Windows with public networks, use the +SkipNetworkProfileCheck parameter of the Enable-PSRemoting cmdlet. It creates +a firewall rule that that allows remote access only from computers in the same +local subnet. To remove the local subnet restriction on public networks and allow remote -access from all locations on client and server versions of Windows, use -the Set-NetFirewallRule cmdlet in the NetSecurity module. Run the following +access from all locations on client and server versions of Windows, use the +Set-NetFirewallRule cmdlet in the NetSecurity module. Run the following command: +```powershell Set-NetFirewallRule -Name "WINRM-HTTP-In-TCP-PUBLIC" -RemoteAddress Any +``` In Windows PowerShell 2.0, on server versions of Windows, Enable-PSRemoting creates firewall rules that permit remote access on all networks. @@ -134,64 +130,55 @@ creates firewall rules that permit remote access on all networks. In Windows PowerShell 2.0, on client versions of Windows, Enable-PSRemoting creates firewall rules only on private and domain networks. If the network location is public, Enable-PSRemoting fails. -# . - -# RUN AS ADMINISTRATOR +## RUN AS ADMINISTRATOR +Administrator privileges are required for the following remoting operations: -Administrator privileges are required for the following remoting -operations: +- Establishing a remote connection to the local computer. This is commonly + known as a "loopback" scenario. --- Establishing a remote connection to the local computer. This is -commonly known as a "loopback" scenario. +- Managing session configurations on the local computer. --- Managing session configurations on the local computer. +- Viewing and changing WS-Management settings on the local computer. These are + the settings in the LocalHost node of the WSMAN: drive. --- Viewing and changing WS-Management settings on the local computer. -These are the settings in the LocalHost node of the WSMAN: drive. +To perform these tasks, you must start Windows PowerShell with the "Run as +administrator" option even if you are a member of the Administrators group on +the local computer. -To perform these tasks, you must start Windows PowerShell with the "Run -as administrator" option even if you are a member of the Administrators -group on the local computer. - -In Windows 7 and in Windows Server 2008 R2, to start Windows PowerShell -with the "Run as administrator" option: +In Windows 7 and in Windows Server 2008 R2, to start Windows PowerShell with +the "Run as administrator" option: 1. Click Start, click All Programs, click Accessories, and then click -the Windows PowerShell folder. - -2. Right-click Windows PowerShell, and then click -"Run as administrator". + the Windows PowerShell folder. +2. Right-click Windows PowerShell, and then click "Run as administrator". To start Windows PowerShell with the "Run as administrator" option: -1. Click Start, click All Programs, and then click the Windows -PowerShell folder. +1. Click Start, click All Programs, and then click the Windows PowerShell + folder. +2. Right-click Windows PowerShell, and then click "Run as administrator". -2. Right-click Windows PowerShell, and then click -"Run as administrator". - -The "Run as administrator" option is also available in other Windows -Explorer entries for Windows PowerShell, including shortcuts. Just -right-click the item, and then click "Run as administrator". +The "Run as administrator" option is also available in other Windows Explorer +entries for Windows PowerShell, including shortcuts. Just right-click the +item, and then click "Run as administrator". When you start Windows PowerShell from another program such as Cmd.exe, use the "Run as administrator" option to start the program. -# HOW TO CONFIGURE YOUR COMPUTER FOR REMOTING - +## HOW TO CONFIGURE YOUR COMPUTER FOR REMOTING Computers running all supported versions of Windows can establish remote connections to and run remote commands in Windows PowerShell without any configuration. However, to receive connections, and allow users to create -local and remote user-managed Windows PowerShell sessions ("PSSessions") -and run commands on the local computer, you must enable Windows PowerShell +local and remote user-managed Windows PowerShell sessions ("PSSessions") and +run commands on the local computer, you must enable Windows PowerShell remoting on the computer. Windows Server 2012 and newer releases of Windows Server are enabled for -Windows PowerShell remoting by default. If the settings are changed, -you can restore the default settings by running the Enable-PSRemoting cmdlet. +Windows PowerShell remoting by default. If the settings are changed, you can +restore the default settings by running the Enable-PSRemoting cmdlet. On all other supported versions of Windows, you need to run the Enable-PSRemoting cmdlet to enable Windows PowerShell remoting. @@ -199,45 +186,43 @@ Enable-PSRemoting cmdlet to enable Windows PowerShell remoting. The remoting features of Windows PowerShell are supported by the WinRM service, which is the Microsoft implementation of the Web Services for Management (WS-Management) protocol. When you enable Windows PowerShell -remoting, you change the default configuration of WS-Management and add -system configuration that allow users to connect to WS-Management. +remoting, you change the default configuration of WS-Management and add system +configuration that allow users to connect to WS-Management. To configure Windows PowerShell to receive remote commands: -1. Start Windows PowerShell with the "Run as administrator" -option. - -2. At the command prompt, type: -Enable-PSRemoting +1. Start Windows PowerShell with the "Run as administrator" option. +2. At the command prompt, type: `Enable-PSRemoting` To verify that remoting is configured correctly, run a test command such as -the following command, which creates a remote session on the local -computer. +the following command, which creates a remote session on the local computer. +```powershell New-PSSession +``` -If remoting is configured correctly, the command will create a session on -the local computer and return an object that represents the session. The -output should resemble the following sample output: - -C:\PS> new-pssession +If remoting is configured correctly, the command will create a session on the +local computer and return an object that represents the session. The output +should resemble the following sample output: +```output Id Name ComputerName State ConfigurationName -- ---- ------------ ----- ----- 1 Session1 localhost Opened Microsoft.PowerShell +``` -If the command fails, for assistance, see about_Remote_Troubleshooting. +If the command fails, for assistance, see +[about_Remote_Troubleshooting](about_Remote_Troubleshooting.md). -# UNDERSTAND POLICIES +## UNDERSTAND POLICIES +When you work remotely, you use two instances of Windows PowerShell, one on +the local computer and one on the remote computer. As a result, your work is +affected by the Windows policies and the Windows PowerShell policies on the +local and remote computers. -When you work remotely, you use two instances of Windows PowerShell, one -on the local computer and one on the remote computer. As a result, your -work is affected by the Windows policies and the Windows PowerShell -policies on the local and remote computers. - -In general, before you connect and as you are establishing the connection, -the policies on the local computer are in effect. When you are using the +In general, before you connect and as you are establishing the connection, the +policies on the local computer are in effect. When you are using the connection, the policies on the remote computer are in effect. # SEE ALSO @@ -248,9 +233,8 @@ connection, the policies on the remote computer are in effect. [about_PSSessions](about_PSSessions.md) -Invoke-Command - -Enter-PSSession +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 33bf188649a7..cdd13115f8e0 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,108 +7,109 @@ title: about_Remote_Variables --- # About Remote Variables -## about_Remote_Variables +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use local and remote variables in remote commands. -Explains how to use local and remote variables in remote -commands. +## LONG DESCRIPTION -# LONG DESCRIPTION - -You can use variables in commands that you run on remote -computers. Simply assign a value to the variable and then -use the variable in place of the value. - -By default, the variables in remote commands are assumed -to be defined in the session in which the command runs. You -can also use variables that are defined in the local session, -but you must identify them as local -variables in the command. - -# USING REMOTE VARIABLES - - -Windows PowerShell assumes that the variables used in remote -commands are defined in the session in which the command runs. +You can use variables in commands that you run on remote computers. Simply +assign a value to the variable and then use the variable in place of the +value. -In the following example, the $ps variable is defined in the -temporary session in which the Get-WinEvent command runs. +By default, the variables in remote commands are assumed to be defined in the +session in which the command runs. You can also use variables that are defined +in the local session, but you must identify them as local variables in the +command. -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"; Get-WinEvent -LogName $ps} +## USING REMOTE VARIABLES -Similarly, when the command runs in a persistent session (PSSession), -the remote variable must be defined in the same PSSession. +Windows PowerShell assumes that the variables used in remote commands are +defined in the session in which the command runs. -PS C:> $s = New-PSSession -ComputerName S1 +In the following example, the \$ps variable is defined in the temporary session +in which the Get-WinEvent command runs. -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"} +```powershell +Invoke-Command -ComputerName S1 -ScriptBlock { + $ps = "Windows PowerShell"; Get-WinEvent -LogName $ps +} +``` -PS C:> Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $ps} +Similarly, when the command runs in a persistent session (PSSession), the +remote variable must be defined in the same PSSession. -# USING LOCAL VARIABLES +```powershell +$s = New-PSSession -ComputerName S1 +Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"} +Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $ps} +``` +## USING LOCAL VARIABLES -You can also use local variables in remote commands, but you must -indicate that the variable is defined in the local session. +You can also use local variables in remote commands, but you must indicate +that the variable is defined in the local session. -Beginning in Windows PowerShell 3.0, you can use the Using scope -modifier to identify a local variable in a remote command. +Beginning in Windows PowerShell 3.0, you can use the Using scope modifier to +identify a local variable in a remote command. The syntax of Using is as follows: -The syntax is: +``` $Using: +``` -In the following example, the $ps variable is created in the local -session, but is used in the session in which the command runs. The -Using scope modifier identifies $ps as a local variable. +In the following example, the $ps variable is created in the local session, +but is used in the session in which the command runs. The Using scope modifier +identifies $ps as a local variable. -PS C:> $ps = "Windows PowerShell" -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {Get-WinEvent -LogName $Using:ps} +```powershell +$ps = "Windows PowerShell" +Invoke-Command -ComputerName S1 -ScriptBlock { + Get-WinEvent -LogName $Using:ps +} +``` You can also use the Using scope modifier in PSSessions. -PS C:> $s = New-PSSession -ComputerName S1 - -PS C:> $ps = "Windows PowerShell" +```powershell +$s = New-PSSession -ComputerName S1 +$ps = "Windows PowerShell" +Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +``` -PS C:> Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +## USING LOCAL VARIABLES IN WINDOWS POWERSHELL 2.0 -# USING LOCAL VARIABLES IN WINDOWS POWERSHELL 2.0 +You can use local variables in a remote command by defining parameters for the +remote command and using the ArgumentList parameter of the Invoke-Command +cmdlet to specify the local variable as the parameter value. +This command format is valid on Windows PowerShell 2.0 and later versions of +Windows PowerShell. -You can use local variables in a remote command by defining parameters -for the remote command and using the ArgumentList parameter of the -Invoke-Command cmdlet to specify the local variable as the parameter -value. - -This command format is valid on Windows PowerShell 2.0 and later versions -of Windows PowerShell. +- Use the param keyword to define parameters for the remote command. The + parameter names are placeholders that do not need to match the name of the + local variable. --- Use the param keyword to define parameters for the remote command. -The parameter names are placeholders that do not need to match the -name of the local variable. +- Use the parameters defined by the param keyword in the command. --- Use the parameters defined by the param keyword in the command. - --- Use the ArgumentList parameter of the Invoke-Command cmdlet to -specify the local variable as the parameter value. +- Use the ArgumentList parameter of the Invoke-Command cmdlet to specify the + local variable as the parameter value. For example, the following commands define the $ps variable in the local -session and then use it in a remote command. The command uses $log as -the parameter name and the local variable, $ps, as its value. - -C:\PS>$ps = "Windows PowerShell" +session and then use it in a remote command. The command uses $log as the +parameter name and the local variable, $ps, as its value. -C:\PS>Invoke-Command -ComputerName S1 -ScriptBlock {param($log) Get-WinEvent -logname $log} -ArgumentList $ps +```powershell +$ps = "Windows PowerShell" +Invoke-Command -ComputerName S1 -ScriptBlock { + param($log) + Get-WinEvent -logname $log +} -ArgumentList $ps +``` -# KEYWORDS - -about_Using - -# SEE ALSO +## SEE ALSO [about_Remote](about_Remote.md) @@ -116,9 +117,8 @@ about_Using [about_Scopes](about_Scopes.md) -Enter-PSSession - -Invoke-Command +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Requires.md index 4ae85a982fc2..c2e71e2f1753 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Requires.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -145,5 +145,4 @@ always a snap-in. [about_PSSnapins](about_PSSnapins.md) -Get-PSSnapin - +[Get-PSSnapin](../Get-PSSnapin.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Return.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Return.md index 3f09476c754f..bcb1e40e8d25 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Return.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Return.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,118 +7,115 @@ title: about_Return --- # About Return -## about_Return - ## SHORT DESCRIPTION -Exits the current scope, which can be a function, script, or script block. +Exits the current scope, which can be a function, script, or script block. ## LONG DESCRIPTION -The Return keyword exits a function, script, or script block. It can be used to exit a scope at a specific point, to return a value, or to indicate that the end of the scope has been reached. -Users who are familiar with languages like C or C\# might want to use the Return keyword to make the logic of leaving a scope explicit. + The Return keyword exits a function, script, or script block. It can be used + to exit a scope at a specific point, to return a value, or to indicate that + the end of the scope has been reached. -In Windows PowerShell®, the results of each statement are returned as output, even without a statement that contains the Return keyword. Languages like C or C\# return only the value or values that are specified by the Return keyword. +Users who are familiar with languages like C or C\# might want to use the +Return keyword to make the logic of leaving a scope explicit. +In PowerShell, the results of each statement are returned as output, +even without a statement that contains the Return keyword. Languages like C or +C\# return only the value or values that are specified by the Return keyword. ### SYNTAX -The syntax for the Return keyword is as follows: +The syntax for the Return keyword is as follows: ``` return [] ``` - -The Return keyword can appear alone, or it can be followed by a value or expression, as follows: - +The Return keyword can appear alone, or it can be followed by a value or +expression, as follows: ``` -return -return $a +return +return $a return (2 + $a) ``` - ### EXAMPLES -The following example uses the Return keyword to exit a function at a specific point if a conditional is met: +The following example uses the Return keyword to exit a function at a specific +point if a conditional is met: ``` -function ScreenPassword($instance) -{ - if (!($instance.screensaversecure)) {return $instance.name} - -} - +function ScreenPassword($instance) +{ + if (!($instance.screensaversecure)) {return $instance.name} + +} + foreach ($a in @(get-wmiobject win32_desktop)) { ScreenPassword($a) } ``` +This script checks each user account. The ScreenPassword function returns the +name of any user account that does not have a password-protected screen saver. +If the screen saver is password protected, the function completes any other +statements to be run, and PowerShell does not return any value. -This script checks each user account. The ScreenPassword function returns the name of any user account that does not have a password-protected screen saver. If the screen saver is password protected, the function completes any other statements to be run, and Windows PowerShell does not return any value. - -In Windows PowerShell, values can be returned even if the Return keyword is not used. The results of each statement are returned. For example, the following statements return the value of the $a variable: - +In PowerShell, values can be returned even if the Return keyword is not used. +The results of each statement are returned. For example, the following +statements return the value of the \$a variable: ``` -$a +$a return ``` - The following statement also returns the value of $a: - ``` return $a ``` +The following example includes a statement intended to let the user know that +the function is performing a calculation: -The following example includes a statement intended to let the user know that the function is performing a calculation: +```powershell +function calculation { + param ($value) - -``` -function calculation { - param ($value) - - "Please wait. Working on calculation..." - $value += 73 - return $value - } + "Please wait. Working on calculation..." + $value += 73 + return $value +} ``` +Running this function and assigning the result to a variable has the following +effect: -Running this function and assigning the result to a variable has the following effect: - - -``` -C:\PS> $a = calculation 14 -C:\PS> +```powershell +$a = calculation 14 ``` +The "Please wait. Working on calculation..." string is not displayed. Instead, +it is assigned to the $a variable, as in the following example: -The "Please wait. Working on calculation..." string is not displayed. Instead, it is assigned to the $a variable, as in the following example: - - -``` -C:\PS> $a -Please wait. Working on calculation... +```output +C:\PS> $a +Please wait. Working on calculation... 87 ``` - -Both the informational string and the result of the calculation are returned by the function and assigned to the $a variable. - +Both the informational string and the result of the calculation are returned +by the function and assigned to the \$a variable. ## SEE ALSO -Exit keyword in about_Language_Keywords +[about_Language_Keywords](about_Language_Keywords.md) [about_Functions](about_Functions.md) [about_Scopes](about_Scopes.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md index 43445a359c43..2e47af3dba57 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,62 +7,56 @@ title: about_Run_With_PowerShell --- # About Run With PowerShell -## about_Run_With_PowerShell +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use the "Run with PowerShell" feature to run a script from a +file system drive. -Explains how to use the "Run with PowerShell" feature to run -a script from a file system drive. +## LONG DESCRIPTION -# LONG DESCRIPTION +Beginning in Windows PowerShell 3.0, you can use the "Run with PowerShell" +feature to run scripts from File Explorer in Windows 8 and Windows Server 2012 +and from Windows Explorer in earlier versions of Windows. -Beginning in Windows PowerShell 3.0, you can use the "Run with -PowerShell" feature to run scripts from File Explorer in Windows 8 -and Windows Server 2012 and from Windows Explorer in earlier -versions of Windows. +The "Run with PowerShell" feature is designed to run scripts that do not have +required parameters and do not return output to the command prompt. -The "Run with PowerShell" feature is designed to run scripts -that do not have required parameters and do not return output -to the command prompt. - -When you use the "Run with PowerShell" feature, the Windows -PowerShell console window appears only briefly, if at all. -You cannot interact with it. +When you use the "Run with PowerShell" feature, the Windows PowerShell console +window appears only briefly, if at all. You cannot interact with it. To use the "Run with PowerShell" feature: -In File Explorer (or Windows Explorer), right-click the -script file name and then select "Run with PowerShell". +In File Explorer (or Windows Explorer), right-click the script file name and +then select "Run with PowerShell". -The "Run with PowerShell" feature starts a Windows PowerShell -session that has an execution policy of Bypass, runs the -script, and closes the session. +The "Run with PowerShell" feature starts a Windows PowerShell session that has +an execution policy of Bypass, runs the script, and closes the session. It runs a command that has the following format: + +``` PowerShell.exe -File -ExecutionPolicy Bypass +``` -"Run with PowerShell" sets the Bypass execution policy only -for the session (the current instance of the PowerShell process) -in which the script runs. This feature does not change the execution -policy for the computer or the user. +"Run with PowerShell" sets the Bypass execution policy only for the session +(the current instance of the PowerShell process) in which the script runs. +This feature does not change the execution policy for the computer or the +user. -The "Run with PowerShell" feature is affected only by the AllSigned -execution policy. If the AllSigned execution policy is effective for -the computer or the user, "Run with PowerShell" runs only signed -scripts. "Run with PowerShell" is not affected by any other execution -policy. For more information, see about_Execution_Policies. +The "Run with PowerShell" feature is affected only by the AllSigned execution +policy. If the AllSigned execution policy is effective for the computer or the +user, "Run with PowerShell" runs only signed scripts. "Run with PowerShell" is +not affected by any other execution policy. For more information, see +[about_Execution_Policies](about_Execution_Policies.md). -Troubleshooting Note: Run with PowerShell command might prompt you -to confirm the execution policy change. +Troubleshooting Note: Run with PowerShell command might prompt you to confirm +the execution policy change. -# SEE ALSO +## SEE ALSO [about_Execution_Policies](about_Execution_Policies.md) [about_Group_Policy_Settings](about_Group_Policy_Settings.md) [about_Scripts](about_Scripts.md) - -"Running Scripts" (http://go.microsoft.com/fwlink/?LinkId=257680) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md index a4409d59d90f..06219eb3961e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,63 +10,63 @@ title: about_Script_Internationalization ## Short Description -Describes the script internationalization features that make it easy for scripts to display -messages and instructions to users in their user interface (UI) language. +Describes the script internationalization features that make it easy for +scripts to display messages and instructions to users in their user interface +(UI) language. ## Long Description The Windows PowerShell script internationalization features allow you to -better serve users throughout the world by displaying Help and user -messages for scripts and functions in the user's UI language. +better serve users throughout the world by displaying Help and user messages +for scripts and functions in the user's UI language. -The script internationalization features query the UI culture of the -operating system during execution, import the appropriate -translated text strings, and display them to the user. The Data section -lets you store text strings separate from code so they are easily -identified and extracted. A new cmdlet, `ConvertFrom-StringData`, -converts text strings into dictionary-like hash tables to facilitate -translation. +The script internationalization features query the UI culture of the operating +system during execution, import the appropriate translated text strings, and +display them to the user. The Data section lets you store text strings +separate from code so they are easily identified and extracted. A new cmdlet, +`ConvertFrom-StringData`, converts text strings into dictionary-like hash +tables to facilitate translation. -To support international Help text, Windows PowerShell includes the -following features: +To support international Help text, Windows PowerShell includes the following +features: -* A Data section that separates text strings from code instructions. For -more information about the Data section, see [about_Data_Sections](about_Data_Sections.md). +* A Data section that separates text strings from code instructions. For more + information about the Data section, see + [aout_Data_Sections](about_Data_Sections.md). -* New automatic variables, $PSCulture and $PSUICulture. $PSCulture stores -the name of the UI language used on the system for elements such as -the date, time, and currency. The $PSUICulture variable stores the -name of the UI language used on the system for user interface elements -such as menus and text strings. +* New automatic variables, \$PSCulture and \$PSUICulture. \$PSCulture stores the + name of the UI language used on the system for elements such as the date, + time, and currency. The $PSUICulture variable stores the name of the UI + language used on the system for user interface elements such as menus and text + strings. * A cmdlet, `ConvertFrom-StringData`, that converts text strings into -dictionary-like hash tables to facilitate translation. For more -information, see [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md). + dictionary-like hash tables to facilitate translation. For more information, + see [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md). -* A new file type, .psd1, that stores translated text strings. The .psd1 -files are stored in language-specific subdirectories of the script -directory. +* A new file type, .psd1, that stores translated text strings. The .psd1 files + are stored in language-specific subdirectories of the script directory. -* A cmdlet, `Import-LocalizedData`, that imports translated text strings -for a specified language into a script at runtime. This cmdlet recognizes -and imports strings in any Windows-supported language. For more -information see [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md). +* A cmdlet, `Import-LocalizedData`, that imports translated text strings for a + specified language into a script at runtime. This cmdlet recognizes and + imports strings in any Windows-supported language. For more information see + [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md). ### The Data Section: Storing Default Strings -Use a Data section in the script to store the text strings in the default language. -Arrange the strings in key/value pairs in a here-string. Each key/value pair must -be on a separate line. If you include comments, the comments must be on separate -lines. +Use a Data section in the script to store the text strings in the default +language. Arrange the strings in key/value pairs in a here-string. Each +key/value pair must be on a separate line. If you include comments, the +comments must be on separate lines. -The `ConvertFrom-StringData` cmdlet converts the key/value pairs in the here-string -into a dictionary-like hash table that is stored in the value of the Data section -variable. +The `ConvertFrom-StringData` cmdlet converts the key/value pairs in the +here-string into a dictionary-like hash table that is stored in the value of +the Data section variable. In the following example, the Data section of the World.ps1 script includes the English-United States (en-US) set of prompt messages for a script. The -`ConvertFrom-StringData` cmdlet converts the strings into a hash table and stores -them in the $msgtable variable. +`ConvertFrom-StringData` cmdlet converts the strings into a hash table and +stores them in the $msgtable variable. ```powershell $msgTable = Data { @@ -79,21 +79,22 @@ $msgTable = Data { } ``` -For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). ### PSD1 Files: Storing Translated Strings -Save the script messages for each UI language in separate text files with -the same name as the script and the .psd1 file name extension. Store the files -in subdirectories of the script directory with names of cultures in the following +Save the script messages for each UI language in separate text files with the +same name as the script and the .psd1 file name extension. Store the files in +subdirectories of the script directory with names of cultures in the following format: \-\ Examples: de-DE, ar-SA, and zh-Hans -For example, if the World.ps1 script is stored in the C:\Scripts directory, you -would create a file directory structure that resembles the following: +For example, if the World.ps1 script is stored in the C:\Scripts directory, +you would create a file directory structure that resembles the following: ``` C:\Scripts @@ -104,8 +105,8 @@ C:\Scripts\zh-CN\World.psd1 ... ``` -The World.psd1 file in the de-DE subdirectory of the script directory -might include the following statement: +The World.psd1 file in the de-DE subdirectory of the script directory might +include the following statement: ```powershell ConvertFrom-StringData -StringData @' @@ -115,8 +116,8 @@ promptMsg = Please enter your user name (in German). '@ ``` -Similarly, the World.psd1 file in the ar-SA subdirectory of the script directory -might includes the following statement: +Similarly, the World.psd1 file in the ar-SA subdirectory of the script +directory might includes the following statement: ```powershell ConvertFrom-StringData -StringData @' @@ -128,70 +129,63 @@ promptMsg = Please enter your user name (in Arabic). ### Import-LocalizedData: Dynamic Retrieval of Translated Strings -To retrieve the strings in the UI language of the current user, use -the `Import-LocalizedData` cmdlet. +To retrieve the strings in the UI language of the current user, use the +`Import-LocalizedData` cmdlet. -`Import-LocalizedData` finds the value of the $PSUICulture automatic -variable and imports the content of the \.psd1 files in -the subdirectory that matches the $PSUICulture value. Then, it saves -the imported content in the variable specified by the value of the -**BindingVariable** parameter. +`Import-LocalizedData` finds the value of the \$PSUICulture automatic variable +and imports the content of the \.psd1 files in the subdirectory +that matches the \$PSUICulture value. Then, it saves the imported content in +the variable specified by the value of the **BindingVariable** parameter. ```powershell Import-LocalizedData -BindingVariable msgTable ``` For example, if the `Import-LocalizedData` command appears in the -C:\Scripts\World.ps1 script and the value of $PSUICulture is -"ar-SA", `Import-LocalizedData` finds the following file: +C:\\Scripts\\World.ps1 script and the value of $PSUICulture is "ar-SA", +`Import-LocalizedData` finds the following file: -C:\Scripts\ar-SA\World.psd1 +C:\\Scripts\\ar-SA\\World.psd1 -Then, it imports the Arabic text strings from the file into -the $msgTable variable, replacing any default strings that might -be defined in the Data section of the World.ps1 script. +Then, it imports the Arabic text strings from the file into the $msgTable +variable, replacing any default strings that might be defined in the Data +section of the World.ps1 script. -As a result, when the script uses the $msgTable variable -to display user messages, the messages are displayed in -Arabic. +As a result, when the script uses the $msgTable variable to display user +messages, the messages are displayed in Arabic. -For example, the following script displays the "Please enter your user -name" message in Arabic: +For example, the following script displays the "Please enter your user name" +message in Arabic: ```powershell if (!($username)) { $msgTable.promptMsg } ``` -If `Import-LocalizedData` cannot find a .psd1 file that matches the -value of $PSUIculture, the value of $msgTable is not replaced, -and the call to $msgTable.promptMsg displays the fallback en-US -strings. +If `Import-LocalizedData` cannot find a .psd1 file that matches the value of +\$PSUIculture, the value of \$msgTable is not replaced, and the call to +\$msgTable.promptMsg displays the fallback en-US strings. ## Examples -This example shows how the script internationalization features -are used in a script to display a day of the week to users -in the language that is set on the computer. +This example shows how the script internationalization features are used in a +script to display a day of the week to users in the language that is set on +the computer. -The following is a complete listing of the Sample1.ps1 script -file. +The following is a complete listing of the Sample1.ps1 script file. -The script begins with a Data section named Day ($Day) that -contains a `ConvertFrom-StringData` command. The expression -submitted to `ConvertFrom-StringData` is a here-string that -contains the day names in the default UI culture, en-US, in -key/value pairs. The `ConvertFrom-StringData` cmdlet converts -the key/value pairs in the here-string into a hash table and +The script begins with a Data section named Day ($Day) that contains a +`ConvertFrom-StringData` command. The expression submitted to +`ConvertFrom-StringData` is a here-string that contains the day names in the +default UI culture, en-US, in key/value pairs. The `ConvertFrom-StringData` +cmdlet converts the key/value pairs in the here-string into a hash table and then saves it in the value of the $Day variable. -The `Import-LocalizedData` command imports the contents of the -.psd1 file in the directory that matches the value of the -$PSUICulture automatic variable and then saves it in the $Day -variable, replacing the values of $Day that are defined in the -Data section. +The `Import-LocalizedData` command imports the contents of the .psd1 file in +the directory that matches the value of the $PSUICulture automatic variable +and then saves it in the $Day variable, replacing the values of $Day that are +defined in the Data section. -The remaining commands load the strings into an array and display -them. +The remaining commands load the strings into an array and display them. ```powershell $Day = Data { @@ -239,10 +233,10 @@ ConvertFrom-StringData @' '@ ``` -As a result, when you run Sample.ps1 on a system on which the value -of $PSUICulture is de-DE, the output of the script is: +As a result, when you run Sample.ps1 on a system on which the value of +\$PSUICulture is de-DE, the output of the script is: -``` +```output Today is Friday (in German) ``` @@ -254,4 +248,3 @@ Today is Friday (in German) * [about_Quoting_Rules](about_Quoting_Rules.md) * [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md) * [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md index fe470e6bc5b4..f181e4eac313 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,284 +7,296 @@ title: about_Session_Configuration_Files --- # About Session Configuration Files -## about_Session_Configuration_Files +## SHORT DESCRIPTION +Describes session configuration files, which are used in a session +configuration (also known as an "endpoint") to define the environment of +sessions that use the session configuration. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes session configuration files, which are used in a -session configuration (also known as an "endpoint") to define the -environment of sessions that use the session configuration. - -# LONG DESCRIPTION - -A "session configuration file" is a text file with a .pssc file -name extension that contains a hash table of session configuration -properties and values. You can use a session configuration file to -set the properties of a session configuration. Doing so defines -the environment of any Windows PowerShell sessions that use that -session configuration. +A "session configuration file" is a text file with a .pssc file name extension +that contains a hash table of session configuration properties and values. You +can use a session configuration file to set the properties of a session +configuration. Doing so defines the environment of any Windows PowerShell +sessions that use that session configuration. Session configuration files make it easy to create custom session configurations without using complex C# assemblies or scripts. -A "session configuration" or "endpoint" is a collection of local -computer settings that determine such things as which users can -create sessions on the computer; which commands users can run in -those sessions; and whether the session should run as a privileged -virtual account. For more information about session configurations, -see about_Session_Configurations -(http://go.microsoft.com/fwlink/?LinkID=145152). - -Session configurations were introduced in Windows PowerShell 2.0, -and session configuration files were introduced in Windows -PowerShell 3.0. You must use Windows PowerShell 3.0 to include a -session configuration file in a session configuration. However, -users of Windows PowerShell 2.0 (and later) are affected by the -settings in the session configuration. - -Creating Custom Sessions -You can customize many features of a Windows PowerShell session -by specifying session properties in a session configuration. You -can customize a session by writing a C# program that defines a -custom runspace, or you can use a session configuration file to -define the properties of sessions created by using the session -configuration. As a general rule, it is easier to use the session +A "session configuration" or "endpoint" is a collection of local computer +settings that determine such things as which users can create sessions on the +computer; which commands users can run in those sessions; and whether the +session should run as a privileged virtual account. For more information about +session configurations, see [about_Session_Configurations](about_Session_Configurations.md). + +Session configurations were introduced in Windows PowerShell 2.0, and session +configuration files were introduced in Windows PowerShell 3.0. You must use +Windows PowerShell 3.0 to include a session configuration file in a session +configuration. However, users of Windows PowerShell 2.0 (and later) are +affected by the settings in the session configuration. + +## Creating Custom Sessions + +You can customize many features of a Windows PowerShell session by specifying +session properties in a session configuration. You can customize a session by +writing a C# program that defines a custom runspace, or you can use a session +configuration file to define the properties of sessions created by using the +session configuration. As a general rule, it is easier to use the session configuration file than to write a C# program. You can use a session configuration file to create items such as -fully-functioning sessions for highly trusted users; locked-down -sessions that allow minimal access; sessions designed for -particular and that contain only the modules required for those -tasks; and sessions where unprivileged users can only run -specific commands as a privileged account. - -In addition to that, you can manage whether users of the -session can use Windows PowerShell language elements such as -script blocks, or whether they can only run commands. You can -manage the version of Windows PowerShell users can run in the -session; manage which modules are imported into the session; and -manage which cmdlets, functions, and aliases session users can -run. When using the RoleDefinitions field, you can give users -different capabilities in the session based on group membership. - -For more information about RoleDefinitions and how to define this -Value, see the help topic for the New-PSRoleCapabilityFile -Cmdlet. - -Creating a Session Configuration File -The easiest way to create a session configuration file is by -using the New-PSSessionConfigurationFile cmdlet. This cmdlet -generates a file that uses the correct syntax and format, and -that automatically verifies many of the configuration file -property values. - -For detailed descriptions of the properties that you can set in -a session configuration file, see the help topic for the -New-PSSessionConfigurationFile cmdlet. - -The following command creates a session configuration file that -uses the default values. The resulting configuration file uses only -the default values because no parameters other than the Path -parameter (which specifies the file path) are included: - -PS C:> New-PSSessionConfigurationFile -Path .\Defaults.pssc - -To view the new configuration file in your default text editor, -use the following command: - -PS C:> Invoke-Item -Path .\Defaults.pssc - -To create a session configuration for sessions in which -user can run commands, but not use other elements of the Windows -PowerShell language, type: - -PS C:> New-PSSessionConfigurationFile -LanguageMode NoLanguage +fully-functioning sessions for highly trusted users; locked-down sessions that +allow minimal access; sessions designed for particular and that contain only +the modules required for those tasks; and sessions where unprivileged users +can only run specific commands as a privileged account. + +In addition to that, you can manage whether users of the session can use +Windows PowerShell language elements such as script blocks, or whether they +can only run commands. You can manage the version of Windows PowerShell users +can run in the session; manage which modules are imported into the session; +and manage which cmdlets, functions, and aliases session users can run. When +using the RoleDefinitions field, you can give users different capabilities in +the session based on group membership. + +For more information about RoleDefinitions and how to define this Value, see +the help topic for the New-PSRoleCapabilityFile Cmdlet. + +## Creating a Session Configuration File + +The easiest way to create a session configuration file is by using the +New-PSSessionConfigurationFile cmdlet. This cmdlet generates a file that uses +the correct syntax and format, and that automatically verifies many of the +configuration file property values. + +For detailed descriptions of the properties that you can set in a session +configuration file, see the help topic for the New-PSSessionConfigurationFile +cmdlet. + +The following command creates a session configuration file that uses the +default values. The resulting configuration file uses only the default values +because no parameters other than the Path parameter (which specifies the file +path) are included: + +```powershell +New-PSSessionConfigurationFile -Path .\Defaults.pssc +``` + +To view the new configuration file in your default text editor, use the +following command: + +```powershell +Invoke-Item -Path .\Defaults.pssc +``` + +To create a session configuration for sessions in which user can run commands, +but not use other elements of the Windows PowerShell language, type: + +```powershell +New-PSSessionConfigurationFile -LanguageMode NoLanguage -Path .\NoLanguage.pssc +``` -In the preceding command, setting the LanguageMode parameter to -NoLanguage prevents users from doing such things as writing or -running scripts, or using variables. +In the preceding command, setting the LanguageMode parameter to NoLanguage +prevents users from doing such things as writing or running scripts, or using +variables. -To create a session configuration for sessions in which users can -use only Get cmdlets, type: +To create a session configuration for sessions in which users can use only Get +cmdlets, type: -PS C:> New-PSSessionConfigurationFile -VisibleCmdlets Get-* +```powershell +New-PSSessionConfigurationFile -VisibleCmdlets Get-* -Path .\GetSessions.pssc +``` -In the preceding example, setting the VisibleCmdlets parameter to -Get-* limits users to cmdlets that have names that start with the -string value "Get-". +In the preceding example, setting the VisibleCmdlets parameter to Get-* limits +users to cmdlets that have names that start with the string value "Get-". -To create a session configuration for sessions that run under a -privileged virtual account instead of the user's credentials, type: +To create a session configuration for sessions that run under a privileged +virtual account instead of the user's credentials, type: -PS C:> New-PSSessionConfigurationFile -RunAsVirtualAccount +```powershell +New-PSSessionConfigurationFile -RunAsVirtualAccount -Path .\VirtualAccount.pssc +``` -To create a session configuration for sessions in which the -commands visible to the user are specified in a role capabilities -file, type: +To create a session configuration for sessions in which the commands visible +to the user are specified in a role capabilities file, type: -PS C:> New-PSSessionConfigurationFile -RoleDefinitions +```powershell +New-PSSessionConfigurationFile -RoleDefinitions @{ 'CONTOSO\User' = @{ RoleCapabilities = 'Maintenance' }} -Path .\Maintenance.pssc +``` -Using a Session Configuration File -You can include a session configuration file when you create a -session configuration or add you can add a file to the session -configuration at a later time. +### Using a Session Configuration File -To include a session configuration file when creating a session -configuration, use the Path parameter of the -Register-PSSessionConfiguration cmdlet. +You can include a session configuration file when you create a session +configuration or add you can add a file to the session configuration at a +later time. -For example, the following command uses the NoLanguage.pssc file -when it creates a NoLanguage session configuration. +To include a session configuration file when creating a session configuration, +use the Path parameter of the Register-PSSessionConfiguration cmdlet. -PS C:> Register-PSSessionConfiguration -Name NoLanguage +For example, the following command uses the NoLanguage.pssc file when it +creates a NoLanguage session configuration. + +```powershell +Register-PSSessionConfiguration -Name NoLanguage -Path .\NoLanguage.pssc +``` -When a new NoLanguage session starts, users will only have access -to Windows PowerShell commands. +When a new NoLanguage session starts, users will only have access to Windows +PowerShell commands. -To add a session configuration file to an existing session -configuration, use the Set-PSSessionConfiguration cmdlet and the -Path parameter. This affects any new sessions created with the -specified session configuration. Note that the -Set-PSSessionConfiguration cmdlet changes the session itself and -does not modify the session configuration file. +To add a session configuration file to an existing session configuration, use +the Set-PSSessionConfiguration cmdlet and the Path parameter. This affects any +new sessions created with the specified session configuration. Note that the +Set-PSSessionConfiguration cmdlet changes the session itself and does not +modify the session configuration file. -For example, the following command adds the NoLanguage.pssc file -to the LockedDown session configuration. +For example, the following command adds the NoLanguage.pssc file to the +LockedDown session configuration. -PS C:> Set-PSSessionConfiguration -Name LockedDown +```powershell +Set-PSSessionConfiguration -Name LockedDown -Path .\NoLanguage.pssc +``` -When users use the LockedDown session configuration to create a -session, they will be able to run cmdlets but they will not be -able to create or use variables, assign values, or use other -Windows PowerShell language elements. +When users use the LockedDown session configuration to create a session, they +will be able to run cmdlets but they will not be able to create or use +variables, assign values, or use other Windows PowerShell language elements. -The following command uses the New-PSSession cmdlet to create a -session on the computer Srv01 that uses the LockedDown session -configuration, saving an object reference to the session in the $s -variable. The ACL (access control list) of the session -configuration determines who can use it to create a session. +The following command uses the New-PSSession cmdlet to create a session on the +computer Srv01 that uses the LockedDown session configuration, saving an +object reference to the session in the $s variable. The ACL (access control +list) of the session configuration determines who can use it to create a +session. -PS C:> $s = New-PSSession -ComputerName Srv01 +```powershell +$s = New-PSSession -ComputerName Srv01 -ConfigurationName LockedDown - -Because the NoLanguage constraints were added to the LockedDown -session configuration, users in LockedDown sessions will only be -able to run Windows PowerShell commands and cmdlets. For example, -the following two commands use the Invoke-Command cmdlet to run -commands in the session referenced in the $s variable. The first -command, which runs the Get-UICulture cmdlet and does not use any -variables, succeeds. The second command, which gets the value of -the $PSUICulture variable, fails. - -PS C:> Invoke-Command -Session $s {Get-UICulture} +``` + +Because the NoLanguage constraints were added to the LockedDown session +configuration, users in LockedDown sessions will only be able to run Windows +PowerShell commands and cmdlets. For example, the following two commands use +the Invoke-Command cmdlet to run commands in the session referenced in the $s +variable. The first command, which runs the Get-UICulture cmdlet and does not +use any variables, succeeds. The second command, which gets the value of the +$PSUICulture variable, fails. + +``` +Invoke-Command -Session $s {Get-UICulture} en-US -PS C:> Invoke-Command -Session $s {$PSUICulture} +Invoke-Command -Session $s {$PSUICulture} The syntax is not supported by this runspace. This might be because it is in no-language mode. + CategoryInfo : ParserError: ($PSUICulture:String) [], ParseException + FullyQualifiedErrorId : ScriptsNotAllowed +``` + +## Editing a Session Configuration File -Editing a Session Configuration File -All settings in a session configuration except for -RunAsVirtualAccount and RunAsVirtualAccountGroups can be modified -by editing the session configuration file used by the session -configuration. To do this, begin by locating the active copy of the -session configuration file. +All settings in a session configuration except for RunAsVirtualAccount and +RunAsVirtualAccountGroups can be modified by editing the session configuration +file used by the session configuration. To do this, begin by locating the +active copy of the session configuration file. -When you use a session configuration file in a session -configuration, Windows PowerShell creates an active copy of the -session configuration file and stores it in the -$pshome\SessionConfig directory on the local computer. +When you use a session configuration file in a session configuration, Windows +PowerShell creates an active copy of the session configuration file and stores +it in the \$pshome\\SessionConfig directory on the local computer. -The location of the active copy of a session configuration file is -stored in the ConfigFilePath property of the session configuration -object. +The location of the active copy of a session configuration file is stored in +the ConfigFilePath property of the session configuration object. -The following command gets the location of the session -configuration file for the NoLanguage session configuration. +The following command gets the location of the session configuration file for +the NoLanguage session configuration. -PS C:> (Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath +```powershell +(Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath +``` That command returns a file path similar to the following: +``` C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc +``` + +You can edit the .pssc file in any text editor. After the file is saved it +will be employed by any new sessions that use the session configuration. -You can edit the .pssc file in any text editor. After the file is -saved it will be employed by any new sessions that use the session -configuration. +If you need to modify the RunAsVirtualAccount or the RunAsVirtualAccountGroups +settings, you must un-register the session configuration and re-register a +session configuration file that includes the edited values. -If you need to modify the RunAsVirtualAccount or the -RunAsVirtualAccountGroups settings, you must un-register the -session configuration and re-register a session configuration file -that includes the edited values. +## Testing a Session Configuration File -Testing a Session Configuration File -Use the Test-PSSessionConfigurationFile cmdlet to test manually -edited session configuration files. That's important: if the file -syntax and values are not valid users will not be able to use the -session configuration to create a session. +Use the Test-PSSessionConfigurationFile cmdlet to test manually edited session +configuration files. That's important: if the file syntax and values are not +valid users will not be able to use the session configuration to create a +session. -For example, the following command tests the active session -configuration file of the NoLanguage session configuration. +For example, the following command tests the active session configuration file +of the NoLanguage session configuration. -PS C:> Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\ +```powershell +Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\ WindowsPowerShell\v1.0\SessionConfig\ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc +``` If the syntax and values in the configuration file are valid -Test-PSSessionConfigurationFile returns True. If the syntax and -values are not valid then the cmdlet returns False. - -You can use Test-PSSessionConfigurationFile to test any session -configuration file, including files that the -New-PSSessionConfiguration cmdlet creates. For more information, -see the help topic for the Test-PSSessionConfigurationFile cmdlet. - -Removing a Session Configuration File -You cannot remove a session configuration file from a session -configuration. However, you can replace the file with a new file -that uses the default settings. This effectively cancels the -settings used by the original configuration file. - -To replace a session configuration file, create a new session -configuration file that uses the default settings, then use the -Set-PSSessionConfiguration cmdlet to replace the custom session -configuration file with the new file. - -For example, the following commands create a Default session -configuration file and then replace the active session -configuration file in the NoLanguage session configuration. - -PS C:> New-PSSessionConfigurationFile -Path .\Default.pssc -PS C:> Set-PSSessionConfiguration -Name NoLanguage +Test-PSSessionConfigurationFile returns True. If the syntax and values are not +valid then the cmdlet returns False. + +You can use Test-PSSessionConfigurationFile to test any session configuration +file, including files that the New-PSSessionConfiguration cmdlet creates. For +more information, see the help topic for the Test-PSSessionConfigurationFile +cmdlet. + +## Removing a Session Configuration File + +You cannot remove a session configuration file from a session configuration. +However, you can replace the file with a new file that uses the default +settings. This effectively cancels the settings used by the original +configuration file. + +To replace a session configuration file, create a new session configuration +file that uses the default settings, then use the Set-PSSessionConfiguration +cmdlet to replace the custom session configuration file with the new file. + +For example, the following commands create a Default session configuration +file and then replace the active session configuration file in the NoLanguage +session configuration. + +```powershell +New-PSSessionConfigurationFile -Path .\Default.pssc +Set-PSSessionConfiguration -Name NoLanguage -Path .\Default.pssc +``` -When these commands finish, the NoLanguage session configuration -will actually provide full language support (the default setting) -for all sessions created with that session configuration. +When these commands finish, the NoLanguage session configuration will actually +provide full language support (the default setting) for all sessions created +with that session configuration. -Viewing the Properties of a Session Configuration -The session configuration objects that represent session -configurations using session configuration files have additional -properties that make it easy to discover and analyze the session -configuration. (Note that the type name shown below includes a -formatted view definition.) You can view the properties by running -the Get-PSSessionConfiguration cmdlet and piping the returned data -to the Get-Member cmdlet: +Viewing the Properties of a Session Configuration The session configuration +objects that represent session configurations using session configuration +files have additional properties that make it easy to discover and analyze the +session configuration. (Note that the type name shown below includes a +formatted view definition.) You can view the properties by running the +Get-PSSessionConfiguration cmdlet and piping the returned data to the +Get-Member cmdlet: -PS C:> Get-PSSessionConfiguration NoLanguage | Get-Member +```powershell +Get-PSSessionConfiguration NoLanguage | Get-Member +``` + +```output TypeName: Microsoft.PowerShell.Commands.PSSessionConfigurationCommands #PSSessionConfiguration @@ -331,62 +343,60 @@ SupportsOptions NoteProperty System.String Suppor... xmlns NoteProperty System.String xmlns=... XmlRenderingType NoteProperty System.String XmlRen... Permission ScriptProperty System.Object Permis... +``` -These properties make it easy to search for specific session -configurations. For example, you can use the ExecutionPolicy -property to find a session configuration that supports sessions -with the RemoteSigned execution policy. Note that, because the -ExecutionPolicy property exists only on sessions that use session -configuration files, the command might not return all qualifying +These properties make it easy to search for specific session configurations. +For example, you can use the ExecutionPolicy property to find a session +configuration that supports sessions with the RemoteSigned execution policy. +Note that, because the ExecutionPolicy property exists only on sessions that +use session configuration files, the command might not return all qualifying session configurations. -PS C:> Get-PSSessionConfiguration | +```powershell +Get-PSSessionConfiguration | where {$_.ExecutionPolicy -eq "RemoteSigned"} +``` -The following command gets session configurations in which the -RunAsUser is the Exchange administrator. +The following command gets session configurations in which the RunAsUser is +the Exchange administrator. -PS C:> Get-PSSessionConfiguration | +```powershell + Get-PSSessionConfiguration | where {$_.RunAsUser -eq "Exchange01\Admin01"} +``` -To view information about the role definitions associated with -a configuration use the Get-PSSessionCapability cmdlet. This -cmdlet enables you to determine the commands and environment -available to specific users in specific endpoints. +To view information about the role definitions associated with a configuration +use the Get-PSSessionCapability cmdlet. This cmdlet enables you to determine +the commands and environment available to specific users in specific +endpoints. -# NOTES +## NOTES -Session configurations also support a type of session known as an -"empty" session. An Empty session type enables you to create -custom sessions with selected commands. If you do not add modules, -functions, or scripts to an empty session, the session is limited -to expressions and might not be of any practical use. The -SessionType property tells you whether or not you are working with -an empty session. +Session configurations also support a type of session known as an "empty" +session. An Empty session type enables you to create custom sessions with +selected commands. If you do not add modules, functions, or scripts to an +empty session, the session is limited to expressions and might not be of any +practical use. The SessionType property tells you whether or not you are +working with an empty session. -# SEE ALSO +## SEE ALSO [about_Session_Configurations](about_Session_Configurations.md) -New-PSSession - -Disable-PSSessionConfiguration - -Enable-PSSessionConfiguration - -Get-PSSessionConfiguration +[New-PSSession](../New-PSSession.md) -New-PSSessionConfigurationFile +[Disable-PSSessionConfiguration](../Disable-PSSessionConfiguration.md) -Register-PSSessionConfiguration +[Enable-PSSessionConfiguration](../Enable-PSSessionConfiguration.md) -Set-PSSessionConfiguration +[Get-PSSessionConfiguration](../Get-PSSessionConfiguration.md) -Test-PSSessionConfigurationFile +[New-PSSessionConfigurationFile](../New-PSSessionConfigurationFile.md) -Unregister-PSSessionConfiguration +[Register-PSSessionConfiguration](../Register-PSSessionConfiguration.md) -Get-PSSessionCapability +[Set-PSSessionConfiguration](../Set-PSSessionConfiguration.md) -New-PSRoleCapabilityFile +[Test-PSSessionConfigurationFile](../Test-PSSessionConfigurationFile.md) +[Unregister-PSSessionConfiguration](../Unregister-PSSessionConfiguration.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Signing.md index e5836ac5ec8e..f8c13a29566e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Signing.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,81 +7,81 @@ title: about_Signing --- # About Signing -## about_Signing +## SHORT DESCRIPTION +Explains how to sign scripts so that they comply with the PowerShell execution +policies. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Explains how to sign scripts so that they comply with the Windows -PowerShell execution policies. +The Restricted execution policy does not permit any scripts to run. The +AllSigned and RemoteSigned execution policies prevent PowerShell from running +scripts that do not have a digital signature. -# LONG DESCRIPTION +This topic explains how to run selected scripts that are not signed, even +while the execution policy is RemoteSigned, and how to sign scripts for your +own use. -The Restricted execution policy does not permit any scripts to run. -The AllSigned and RemoteSigned execution policies prevent Windows -PowerShell from running scripts that do not have a digital signature. +For more information about PowerShell execution policies, see +[about_Execution_Policies](about_Execution_Policies.md). -This topic explains how to run selected scripts that are not signed, -even while the execution policy is RemoteSigned, and how to sign -scripts for your own use. +## TO PERMIT SIGNED SCRIPTS TO RUN -For more information about Windows PowerShell execution policies, -see about_Execution_Policy. - -# TO PERMIT SIGNED SCRIPTS TO RUN - -------------------------------- -When you start Windows PowerShell on a computer for the first time, the -Restricted execution policy (the default) is likely to be in effect. +When you start PowerShell on a computer for the first time, the Restricted +execution policy (the default) is likely to be in effect. The Restricted policy does not permit any scripts to run. To find the effective execution policy on your computer, type: +```powershell Get-ExecutionPolicy +``` -To run unsigned scripts that you write on your local computer and -signed scripts from other users, start Windows PowerShell with the -Run as Administrator option and then use the following command to -change the execution policy on the computer to RemoteSigned: +To run unsigned scripts that you write on your local computer and signed +scripts from other users, start PowerShell with the Run as Administrator +option and then use the following command to change the execution policy on +the computer to RemoteSigned: +```powershell Set-ExecutionPolicy RemoteSigned +``` -For more information, see the help topic for the -Set-ExecutionPolicy cmdlet. +For more information, see the help topic for the Set-ExecutionPolicy cmdlet. -# RUNNING UNSIGNED SCRIPTS (REMOTESIGNED EXECUTION POLICY) +## RUNNING UNSIGNED SCRIPTS (REMOTESIGNED EXECUTION POLICY) --------------------------------------------------------- -If your Windows PowerShell execution policy is RemoteSigned, Windows +If your PowerShell execution policy is RemoteSigned, Windows PowerShell will not run unsigned scripts that are downloaded from the Internet, including unsigned scripts you receive through e-mail and instant messaging programs. -If you try to run a downloaded script, Windows PowerShell displays the +If you try to run a downloaded script, PowerShell displays the following error message: -The file cannot be loaded. The file - is not digitally signed. The script -will not execute on the system. Please see "Get-Help +```output +The file cannot be loaded. The file is not digitally +signed. The script will not execute on the system. Please see "Get-Help about_Signing" for more details. +``` Before you run the script, review the code to be sure that you trust it. Scripts have the same effect as any executable program. -To run an unsigned script, use the Unblock-File cmdlet or use the -Following procedure. +To run an unsigned script, use the Unblock-File cmdlet or use the following +procedure. 1. Save the script file on your computer. 2. Click Start, click My Computer, and locate the saved script file. 3. Right-click the script file, and then click Properties. 4. Click Unblock. -If a script that was downloaded from the Internet is digitally signed, but -you have not yet chosen to trust its publisher, Windows PowerShell displays -the following message: +If a script that was downloaded from the Internet is digitally signed, but you +have not yet chosen to trust its publisher, PowerShell displays the following +message: +```output Do you want to run software from this untrusted publisher? The file is published by CN=. This publisher is not trusted on your system. Only run scripts @@ -89,231 +89,206 @@ from trusted publishers. [V] Never run [D] Do not run [R] Run once [A] Always run [?] Help (default is "D"): +``` -If you trust the publisher, select "Run once" or "Always run." -If you do not trust the publisher, select either "Never run" or -"Do not run." If you select "Never run" or "Always run," Windows -PowerShell will not prompt you again for this publisher. +If you trust the publisher, select "Run once" or "Always run." If you do not +trust the publisher, select either "Never run" or "Do not run." If you select +"Never run" or "Always run," PowerShell will not prompt you again for +this publisher. -# METHODS OF SIGNING SCRIPTS +## METHODS OF SIGNING SCRIPTS --------------------------- -You can sign the scripts that you write and the scripts that you obtain -from other sources. Before you sign any script, examine each command -to verify that it is safe to run. +You can sign the scripts that you write and the +scripts that you obtain from other sources. Before you sign any script, +examine each command to verify that it is safe to run. -For best practices about code signing, see "Code-Signing -Best Practices" at http://go.microsoft.com/fwlink/?LinkId=119096. +For best practices about code signing, see +[Code-Signing Best Practices](http://go.microsoft.com/fwlink/?LinkId=119096). For more information about how to sign a script file, see Set-AuthenticodeSignature. -The New-SelfSignedCertificate cmdlet, introduced in the PKI module -in Windows PowerShell 3.0, creates a self-signed certificate that is -Appropriate for testing. For more information, see the help -topic for the New-SelfSignedCertificate cmdlet. - -To add a digital signature to a script, you must sign it with a code -signing certificate. Two types of certificates are suitable for signing -a script file: +The New-SelfSignedCertificate cmdlet, introduced in the PKI module in +PowerShell 3.0, creates a self-signed certificate that is Appropriate for +testing. For more information, see the help topic for the +New-SelfSignedCertificate cmdlet. --- Certificates that are created by a certification authority: +To add a digital signature to a script, you must sign it with a code signing +certificate. Two types of certificates are suitable for signing a script file: -For a fee, a public certification authority verifies your -identity and gives you a code signing certificate. When -you purchase your certificate from a reputable certification -authority, you are able to share your script with users -on other computers that are running Windows because those other -computers trust the certification authority. +- Certificates that are created by a certification authority: For a fee, a + public certification authority verifies your identity and gives you a code + signing certificate. When you purchase your certificate from a reputable + certification authority, you are able to share your script with users on + other computers that are running Windows because those other computers trust + the certification authority. --- Certificates that you create: +- Certificates that you create: You can create a self-signed certificate for + which your computer is the authority that creates the certificate. This + certificate is free of charge and enables you to write, sign, and run scripts + on your computer. However, a script signed by a self-signed certificate will + not run on other computers. -You can create a self-signed certificate for which -your computer is the authority that creates the certificate. -This certificate is free of charge and enables you to write, -sign, and run scripts on your computer. However, a script -signed by a self-signed certificate will not run on other -computers. +Typically, you would use a self-signed certificate only to sign scripts that +you write for your own use and to sign scripts that you get from other sources +that you have verified to be safe. It is not appropriate for scripts that will +be shared, even within an enterprise. -Typically, you would use a self-signed certificate only to sign -scripts that you write for your own use and to sign scripts that you get -from other sources that you have verified to be safe. It is not -appropriate for scripts that will be shared, even within an enterprise. +If you create a self-signed certificate, be sure to enable strong private key +protection on your certificate. This prevents malicious programs from signing +scripts on your behalf. The instructions are included at the end of this +topic. -If you create a self-signed certificate, be sure to enable strong -private key protection on your certificate. This prevents malicious -programs from signing scripts on your behalf. The instructions are -included at the end of this topic. +## CREATE A SELF-SIGNED CERTIFICATE -# CREATE A SELF-SIGNED CERTIFICATE - --------------------------------- To create a self-signed certificate in use the New-SelfSignedCertificate -cmdlet in the PKI module. This module is introduced in Windows PowerShell -3.0 and is included in Windows 8 and Windows Server 2012. For more -information, see the help topic for the New-SelfSignedCertificate cmdlet. +cmdlet in the PKI module. This module is introduced in PowerShell 3.0 and is +included in Windows 8 and Windows Server 2012. For more information, see the +help topic for the New-SelfSignedCertificate cmdlet. -To create a self-signed certificate in earlier versions of Windows, use -the Certificate Creation tool (MakeCert.exe). This tool is included in -the Microsoft .NET Framework SDK (versions 1.1 and later) and in the -Microsoft Windows SDK. +To create a self-signed certificate in earlier versions of Windows, use the +Certificate Creation tool (MakeCert.exe). This tool is included in the +Microsoft .NET Framework SDK (versions 1.1 and later) and in the Microsoft +Windows SDK. For more information about the syntax and the parameter descriptions of the -MakeCert.exe tool, see "Certificate Creation Tool (MakeCert.exe)" in the -MSDN (Microsoft Developer Network) library at -http://go.microsoft.com/fwlink/?LinkId=119097. +MakeCert.exe tool, see [Certificate Creation Tool (MakeCert.exe)](http://go.microsoft.com/fwlink/?LinkId=119097) +in the MSDN library. To use the MakeCert.exe tool to create a certificate, run the following commands in an SDK Command Prompt window. -Note: The first command creates a local certification authority for -your computer. The second command generates a personal -certificate from the certification authority. +Note: The first command creates a local certification authority for your +computer. The second command generates a personal certificate from the +certification authority. -Note: You can copy or type the commands exactly as they appear. -No substitutions are necessary, although you can change the -certificate name. +Note: You can copy or type the commands exactly as they appear. No +substitutions are necessary, although you can change the certificate name. +```powershell makecert -n "CN=PowerShell Local Certificate Root" -a sha1 ` -eku 1.3.6.1.5.5.7.3.3 -r -sv root.pvk root.cer ` -ss Root -sr localMachine makecert -pe -n "CN=PowerShell User" -ss MY -a sha1 ` -eku 1.3.6.1.5.5.7.3.3 -iv root.pvk -ic root.cer +``` -The MakeCert.exe tool will prompt you for a private key password. The -password ensures that no one can use or access the certificate without -your consent. Create and enter a password that you can remember. You will -use this password later to retrieve the certificate. +The MakeCert.exe tool will prompt you for a private key password. The password +ensures that no one can use or access the certificate without your consent. +Create and enter a password that you can remember. You will use this password +later to retrieve the certificate. -To verify that the certificate was generated correctly, use the -following command to get the certificate in the certificate -store on the computer. (You will not find a certificate file in the -file system directory.) +To verify that the certificate was generated correctly, use the following +command to get the certificate in the certificate store on the computer. (You +will not find a certificate file in the file system directory.) -At the Windows PowerShell prompt, type: +At the PowerShell prompt, type: +```powershell get-childitem cert:\CurrentUser\my -codesigning +``` -This command uses the Windows PowerShell Certificate provider to view -information about the certificate. +This command uses the PowerShell Certificate provider to view information +about the certificate. -If the certificate was created, the output shows the thumbprint -that identifies the certificate in a display that resembles the following: +If the certificate was created, the output shows the thumbprint that +identifies the certificate in a display that resembles the following: +```output Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My Thumbprint Subject ---------- ------- 4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ] +``` -# SIGN A SCRIPT - -------------- +## SIGN A SCRIPT -After you create a self-signed certificate, you can sign scripts. If you -use the AllSigned execution policy, signing a script permits you to run -the script on your computer. +After you create a self-signed certificate, you can sign scripts. If you use +the AllSigned execution policy, signing a script permits you to run the script +on your computer. -The following sample script, Add-Signature.ps1, signs a script. However, -if you are using the AllSigned execution policy, you must sign the +The following sample script, Add-Signature.ps1, signs a script. However, if +you are using the AllSigned execution policy, you must sign the Add-Signature.ps1 script before you run it. -To use this script, copy the following text into a text file, and -name it Add-Signature.ps1. - -Note: Be sure that the script file does not have a .txt file name -extension. If your text editor appends ".txt", enclose the file name -in quotation marks: "add-signature.ps1". +To use this script, copy the following text into a text file, and name it +Add-Signature.ps1. -## add-signature.ps1 +```powershell ## Signs a file param([string] $file=$(throw "Please specify a filename.")) $cert = @(Get-ChildItem cert:\CurrentUser\My -codesigning)[0] Set-AuthenticodeSignature $file $cert +``` -To sign the Add-Signature.ps1 script file, type the following commands at -the Windows PowerShell command prompt: +To sign the Add-Signature.ps1 script file, type the following commands at the +PowerShell command prompt: +```powershell $cert = @(Get-ChildItem cert:\CurrentUser\My -codesigning)[0] - Set-AuthenticodeSignature add-signature.ps1 $cert +``` -After the script is signed, you can run it on the local computer. -However, the script will not run on computers on which the Windows -PowerShell execution policy requires a digital signature from a -trusted authority. If you try, Windows PowerShell displays the following -error message: +After the script is signed, you can run it on the local computer. However, the +script will not run on computers on which the PowerShell execution +policy requires a digital signature from a trusted authority. If you try, +PowerShell displays the following error message: +```output The file C:\remote_file.ps1 cannot be loaded. The signature of the certificate cannot be verified. At line:1 char:15 + .\ remote_file.ps1 <<<< +``` -If Windows PowerShell displays this message when you run a -script that you did not write, treat the file as you would treat any -unsigned script. Review the code to determine whether you can trust the -script. - -# ENABLE STRONG PRIVATE KEY PROTECTION FOR YOUR CERTIFICATE +If PowerShell displays this message when you run a script that you did not +write, treat the file as you would treat any unsigned script. Review the code +to determine whether you can trust the script. ---------------------------------------------------------- +## ENABLE STRONG PRIVATE KEY PROTECTION FOR YOUR CERTIFICATE -If you have a private certificate on your computer, malicious -programs might be able to sign scripts on your behalf, which -authorizes Windows PowerShell to run them. +If you have a private certificate on your computer, malicious programs might +be able to sign scripts on your behalf, which authorizes PowerShell to run +them. -To prevent automated signing on your behalf, use Certificate -Manager (Certmgr.exe) to export your signing certificate to -a .pfx file. Certificate Manager is included in the Microsoft -.NET Framework SDK, the Microsoft Windows SDK, and in Internet -Explorer 5.0 and later versions. +To prevent automated signing on your behalf, use Certificate Manager +(Certmgr.exe) to export your signing certificate to a .pfx file. Certificate +Manager is included in the Microsoft .NET Framework SDK, the Microsoft Windows +SDK, and in Internet Explorer 5.0 and later versions. To export the certificate: 1. Start Certificate Manager. - 2. Select the certificate issued by PowerShell Local Certificate Root. - 3. Click Export to start the Certificate Export Wizard. - 4. Select "Yes, export the private key", and then click Next. - 5. Select "Enable strong protection." - 6. Type a password, and then type it again to confirm. - 7. Type a file name that has the .pfx file name extension. - 8. Click Finish. To re-import the certificate: 1. Start Certificate Manager. - 2. Click Import to start the Certificate Import Wizard. - -3. Open to the location of the .pfx file that you created during the -export process. - +3. Open to the location of the .pfx file that you created during the export + process. 4. On the Password page, select "Enable strong private key protection", -and then enter the password that you assigned during the export -process. - + and then enter the password that you assigned during the export + process. 5. Select the Personal certificate store. - 6. Click Finish. -# PREVENT THE SIGNATURE FROM EXPIRING +## PREVENT THE SIGNATURE FROM EXPIRING ------------------------------------ The digital signature in a script is valid until the signing certificate expires or as long as a time stamp server can verify that the script was signed while the signing certificate was valid. -Because most signing certificates are valid for one year only, using a -time stamp server ensures that users can use your script for many years -to come. +Because most signing certificates are valid for one year only, using a time +stamp server ensures that users can use your script for many years to come. # SEE ALSO @@ -321,13 +296,10 @@ to come. [about_Profiles](about_Profiles.md) -Get-ExecutionPolicy - -New-SelfSignedCertificate - -Set-ExecutionPolicy +[Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -Set-AuthenticodeSignature +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -"Introduction to Code Signing" (http://go.microsoft.com/fwlink/?LinkId=106296) +[Set-AuthenticodeSignature](../../Microsoft.PowerShell.Security/Set-AuthenticodeSignature.md) +[Introduction to Code Signing](http://go.microsoft.com/fwlink/?LinkId=106296) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Splatting.md index 10b1d7bc00db..02d2b8d169e7 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,68 +7,61 @@ title: about_Splatting --- # About Splatting -## about_Splatting +## SHORT DESCRIPTION +Describes how to use splatting to pass parameters to commands in Windows +PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes how to use splatting to pass parameters to commands -in Windows PowerShell. +[This topic was contributed by Rohn Edwards of Gulfport, Mississippi, a system +administrator and the winner of the Advanced Division of the 2012 Scripting +Games. Revised for Windows PowerShell 3.0.] -# LONG DESCRIPTION +Splatting is a method of passing a collection of parameter values to a command +as unit. Windows PowerShell associates each value in the collection with a +command parameter. Splatted parameter values are stored in named splatting +variables, which look like standard variables, but begin with an At symbol (@) +instead of a dollar sign ($). The At symbol tells Windows PowerShell that you +are passing a collection of values, instead of a single value. -[This topic was contributed by Rohn Edwards of Gulfport, -Mississippi, a system administrator and the winner -of the Advanced Division of the 2012 Scripting Games. -Revised for Windows PowerShell 3.0.] +Splatting makes your commands shorter and easier to read. You can re-use the +splatting values in different command calls and use splatting to pass +parameter values from the `$PSBoundParameters` automatic variable to other +scripts and functions. -Splatting is a method of passing a collection of parameter -values to a command as unit. Windows PowerShell associates -each value in the collection with a command parameter. -Splatted parameter values are stored in named splatting -variables, which look like standard variables, but begin with -an At symbol (@) instead of a dollar sign ($). The At symbol -tells Windows PowerShell that you are passing a collection of -values, instead of a single value. +Beginning in Windows PowerShell 3.0, you can also use splatting to represent +all parameters of a command. -Splatting makes your commands shorter and easier to read. You -can re-use the splatting values in different command calls and -use splatting to pass parameter values from the `$PSBoundParameters` -automatic variable to other scripts and functions. +## SYNTAX -Beginning in Windows PowerShell 3.0, you can also use splatting -to represent all parameters of a command. - -# SYNTAX - -```powershell +``` @ @ ``` -To provide parameter values for positional parameters, in which -parameter names are not required, use the array syntax. To provide -parameter name and value pairs, use the hash table syntax. The -splatted value can appear anywhere in the parameter list. +To provide parameter values for positional parameters, in which parameter +names are not required, use the array syntax. To provide parameter name and +value pairs, use the hash table syntax. The splatted value can appear anywhere +in the parameter list. -When splatting, you do not need to use a hash table or an array to -pass all parameters. You may pass some parameters by using splatting -and pass others by position or by parameter name. Also, you can splat -multiple objects in a single command just so you pass no more than one -value for each parameter. +When splatting, you do not need to use a hash table or an array to pass all +parameters. You may pass some parameters by using splatting and pass others by +position or by parameter name. Also, you can splat multiple objects in a +single command just so you pass no more than one value for each parameter. -# SPLATTING WITH HASH TABLES +## SPLATTING WITH HASH TABLES -Use a hash table to splat parameter name and value pairs. You can use -this format for all parameter types, including positional and named -parameters and switch parameters. +Use a hash table to splat parameter name and value pairs. You can use this +format for all parameter types, including positional and named parameters and +switch parameters. -The following examples compare two `Copy-Item` commands that copy the -Test.txt file to the Test2.txt file in the same directory. +The following examples compare two `Copy-Item` commands that copy the Test.txt +file to the Test2.txt file in the same directory. -The first example uses the traditional format in which parameter names -are included. +The first example uses the traditional format in which parameter names are +included. ```powershell Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf @@ -76,9 +69,9 @@ Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf The second example uses hash table splatting. The first command creates a hash table of parameter-name and parameter-value pairs and stores it in the -\$HashArguments variable. The second command uses the `$HashArguments` variable -in a command with splatting. The At symbol (`@HashArguments`) replaces the -dollar sign (`$HashArguments`) in the command. +\$HashArguments variable. The second command uses the `$HashArguments` +variable in a command with splatting. The At symbol (`@HashArguments`) +replaces the dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. @@ -91,11 +84,11 @@ $HashArguments = @{ Copy-Item @HashArguments ``` -Note: In the first command, the At symbol (@) indicates a hash table, not -a splatted value. The syntax for hash tables in Windows PowerShell is: +Note: In the first command, the At symbol (@) indicates a hash table, not a +splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* -# SPLATTING WITH ARRAYS +## SPLATTING WITH ARRAYS Use an array to splat values for positional parameters, which do not require parameter names. The values must be in position-number order in the array. @@ -122,8 +115,7 @@ $ArrayArguments = "test.txt", "test2.txt" Copy-Item @ArrayArguments -WhatIf ``` -# EXAMPLES - +## EXAMPLES This example shows how to re-use splatted values in different commands. The commands in this example use the Write-Host cmdlet to write messages to the @@ -153,18 +145,16 @@ Write-Host "This is a test." @Colors Write-Host @Colors "This is another test." ``` -This example shows how to forward their parameters to other commands by -using splatting and the `$PSBoundParameters` automatic variable. +This example shows how to forward their parameters to other commands by using +splatting and the `$PSBoundParameters` automatic variable. -The $PSBoundParameters automatic variable is a dictionary -(System.Collections.Generic.Dictionary) that contains all of the -parameter names and values that are used when a script or function -is run. +The \$PSBoundParameters automatic variable is a dictionary +(System.Collections.Generic.Dictionary) that contains all of the parameter +names and values that are used when a script or function is run. -In the following example, we use the `$PSBoundParameters` variable to -forward the parameters values passed to a script or function from Test2 -function to the Test1 function. Both calls to the Test1 function from -Test2 use splatting. +In the following example, we use the `$PSBoundParameters` variable to forward +the parameters values passed to a script or function from Test2 function to +the Test1 function. Both calls to the Test1 function from Test2 use splatting. ```powershell function Test1 @@ -188,7 +178,9 @@ function Test2 $LimitedParameters.Remove("a") | Out-Null Test1 @LimitedParameters } +``` +```output Test2 -a 1 -b 2 -c 3 1 2 @@ -197,7 +189,7 @@ Test2 -a 1 -b 2 -c 3 3 ``` -# SPLATTING COMMAND PARAMETERS +## SPLATTING COMMAND PARAMETERS You can use splatting to represent the parameters of a command. This technique is useful when you are creating a proxy function, that is, a function that @@ -207,8 +199,8 @@ To splat the parameters of a command, use `@Args` to represent the command parameters. This technique is easier than enumerating command parameters and it works without revision even if the parameters of the called command change. -The feature uses the `$Args` automatic variable, which contains -all unassigned parameter values. +The feature uses the `$Args` automatic variable, which contains all unassigned +parameter values. For example, the following function calls the Get-Process cmdlet. In this function, `@Args` represents all of the parameters of the Get-Process cmdlet. @@ -217,19 +209,24 @@ function, `@Args` represents all of the parameters of the Get-Process cmdlet. function Get-MyProcess { Get-Process @Args } ``` -When you use the Get-MyProcess function, all unassigned -parameters and parameter values are passed to `@Args`, as -shown in the following commands. +When you use the Get-MyProcess function, all unassigned parameters and +parameter values are passed to `@Args`, as shown in the following commands. ```powershell Get-MyProcess -Name PowerShell +``` +```output Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 463 46 225484 237196 719 15.86 3228 powershell +``` +```powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo +``` +```output ProductVersion FileVersion FileName -------------- ----------- -------- 6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... @@ -248,7 +245,9 @@ function Get-MyCommand } Get-MyCommand -P -C -Name PowerShell +``` +```output Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Transactions.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Transactions.md index e93860f24d7f..5c292571cdac 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Transactions.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Transactions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,445 +7,454 @@ title: about_Transactions --- # About Transactions -## about_Transactions +## SHORT DESCRIPTION +Describes how to manage transacted operations in PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes how to manage transacted operations in Windows PowerShell. +Transactions are supported in PowerShell beginning in PowerShell 2.0. This +feature enables you to start a transaction, to indicate which commands are +part of the transaction, and to commit or roll back a transaction. -# LONG DESCRIPTION +## ABOUT TRANSACTIONS -Transactions are supported in Windows PowerShell beginning -in Windows PowerShell 2.0. This feature enables you to start -a transaction, to indicate which commands are part of the -transaction, and to commit or roll back a transaction. +In PowerShell, a transaction is a set of one or more commands that are managed +as a logical unit. A transaction can be completed ("committed"), which changes +data affected by the transaction. Or, a transaction can be completely undone +("rolled back") so that the affected data is not changed by the transaction. -# ABOUT TRANSACTIONS +Because the commands in a transaction are managed as a unit, either all +commands are committed, or all commands are rolled back. +Transactions are widely used in data processing, most notably in database +operations and for financial transactions. Transactions are most often used +when the worst-case scenario for a set of commands is not that they all fail, +but that some commands succeed while others fail, leaving the system in a +damaged, false, or uninterpretable state that is difficult to repair. -In Windows PowerShell, a transaction is a set of one or more -commands that are managed as a logical unit. A transaction can -be completed ("committed"), which changes data affected by the -transaction. Or, a transaction can be completely undone ("rolled back") -so that the affected data is not changed by the transaction. +## TRANSACTION CMDLETS -Because the commands in a transaction are managed as a unit, -either all commands are committed, or all commands are rolled -back. +PowerShell includes several cmdlets designed for managing transactions. -Transactions are widely used in data processing, most notably -in database operations and for financial transactions. Transactions -are most often used when the worst-case scenario for a set of -commands is not that they all fail, but that some commands succeed -while others fail, leaving the system in a damaged, false, or -uninterpretable state that is difficult to repair. - -# TRANSACTION CMDLETS - - -Windows PowerShell includes several cmdlets designed for managing -transactions. - -Cmdlet Description --------------- --------------------------------- -Start-Transaction Starts a new transaction. - -Use-Transaction Adds a command or expression to the -transaction. The command must use -transaction-enabled objects. - -Undo-Transaction Rolls back the transaction so that -no data is changed by the transaction. - -Complete-Transaction Commits the transaction. The data -affected by the transaction is changed. - -Get-Transaction Gets information about the active -transaction. +- Start-Transaction: Starts a new transaction. +- Use-Transaction: Adds a command or expression to the transaction. The + command must use transaction-enabled objects. +- Undo-Transaction: Rolls back the transaction so that no data is changed by + the transaction. +- Complete-Transaction: Commits the transaction. The data affected by the + transaction is changed. +- Get-Transaction: Gets information about the active transaction. For a list of transaction cmdlets, type: +```powershell get-command *transaction +``` For detailed information about the cmdlets, type: -get-help -detailed - -For example: - +```powershell get-help use-transaction -detailed +``` -# TRANSACTION-ENABLED ELEMENTS - +## TRANSACTION-ENABLED ELEMENTS -To participate in a transaction, both the cmdlet and the provider -must support transactions. This feature is built in to the objects -that are affected by the transaction. +To participate in a transaction, both the cmdlet and the provider must support +transactions. This feature is built in to the objects that are affected by the +transaction. -The Windows PowerShell Registry provider supports transactions -in Windows Vista. The TransactedString object -(Microsoft.PowerShell.Commands.Management.TransactedString) works -with any operating system that runs Windows PowerShell. +The PowerShell Registry provider supports transactions in Windows Vista. The +TransactedString object +(Microsoft.PowerShell.Commands.Management.TransactedString) works with any +operating system that runs PowerShell. -Other Windows PowerShell providers can support transactions. To -find the Windows PowerShell providers in your session that support -transactions, use the following command to find the "Transactions" -value in the Capabilities property of providers: +Other PowerShell providers can support transactions. To find the PowerShell +providers in your session that support transactions, use the following command +to find the "Transactions" value in the Capabilities property of providers: +```powershell get-psprovider | where {$_.Capabilities -like "transactions"} +``` -For more information about a provider, see the Help for the provider. -To get provider Help, type: +For more information about a provider, see the Help for the provider. To get +provider Help, type: +``` get-help +``` For example, to get Help for the Registry provider, type: +```powershell get-help registry +``` -# THE USETRANSACTION PARAMETER - +## THE USETRANSACTION PARAMETER -Cmdlets that can support transactions have a UseTransaction -parameter. This parameter includes the command in the active -transaction. You can use the full parameter name or its alias, -"usetx". +Cmdlets that can support transactions have a UseTransaction parameter. This +parameter includes the command in the active transaction. You can use the full +parameter name or its alias, "usetx". -The parameter can be used only when the session contains an -active transaction. If you enter a command with the UseTransaction -parameter when there is no active transaction, the command fails. +The parameter can be used only when the session contains an active +transaction. If you enter a command with the UseTransaction parameter when +there is no active transaction, the command fails. To find cmdlets with the UseTransaction parameter, type: +```powershell get-help * -parameter UseTransaction +``` -In Windows PowerShell core, all of the cmdlets designed to work -with Windows PowerShell providers support transactions. As a -result, you can use the provider cmdlets to manage transactions. +In PowerShell core, all of the cmdlets designed to work with PowerShell +providers support transactions. As a result, you can use the provider cmdlets +to manage transactions. -For more information about Windows PowerShell providers, -see about_Providers. +For more information about PowerShell providers, see [about_Providers](about_Providers.md). -# THE TRANSACTION OBJECT +## THE TRANSACTION OBJECT - -Transactions are represented in Windows PowerShell by a -transaction object, System.Management.Automation.Transaction. +Transactions are represented in PowerShell by a transaction object, +System.Management.Automation.Transaction. The object has the following properties: -RollbackPreference: -Contains the rollback preference set for the current -transaction. You can set the rollback preference when you -use Start-Transaction to start the transaction. +- RollbackPreference: Contains the rollback preference set for the current + transaction. You can set the rollback preference when you use + Start-Transaction to start the transaction. -The rollback preference determines the conditions under -which the transaction is rolled back automatically. Valid -values are Error, TerminatingError, and Never. The default -value is Error. + The rollback preference determines the conditions under which the transaction + is rolled back automatically. Valid values are Error, TerminatingError, and + Never. The default value is Error. -Status: -Contains the current status of the transaction. Valid -values are Active, Committed, and RolledBack. +- Status: Contains the current status of the transaction. Valid values are + Active, Committed, and RolledBack. -SubscriberCount: -Contains the number of subscribers to the transaction. A -subscriber is added to a transaction when you start a -transaction while another transaction is in progress. The -subscriber count is decremented when a subscriber commits -the transaction. +- SubscriberCount: Contains the number of subscribers to the transaction. A + subscriber is added to a transaction when you start a transaction while + another transaction is in progress. The subscriber count is decremented when + a subscriber commits the transaction. -# ACTIVE TRANSACTIONS +## ACTIVE TRANSACTIONS +In PowerShell, only one transaction is active at a time, and you can manage +only the active transaction. Multiple transactions can be in progress in the +same session at the same time, but only the most-recently started transaction +is active. -In Windows PowerShell, only one transaction is active at a -time, and you can manage only the active transaction. Multiple -transactions can be in progress in the same session at the same -time, but only the most-recently started transaction is active. +As a result, you cannot specify a particular transaction when using the +transaction cmdlets. Commands always apply to the active transaction. -As a result, you cannot specify a particular transaction when -using the transaction cmdlets. Commands always apply to the -active transaction. - -This is most evident in the behavior of the Get-Transaction cmdlet. -When you enter a Get-Transaction command, Get-Transaction always -gets only one transaction object. This object is the object that -represents the active transaction. +This is most evident in the behavior of the Get-Transaction cmdlet. When you +enter a Get-Transaction command, Get-Transaction always gets only one +transaction object. This object is the object that represents the active +transaction. To manage a different transaction, you must first finish the active -transaction, either by committing it or rolling it back. When you -do this, the previous transaction becomes active automatically. -Transactions become active in the reverse of order of which they are -started, so that the most recently started transaction is always -active. +transaction, either by committing it or rolling it back. When you do this, the +previous transaction becomes active automatically. Transactions become active +in the reverse of order of which they are started, so that the most recently +started transaction is always active. -# SUBSCRIBERS AND INDEPENDENT TRANSACTIONS +## SUBSCRIBERS AND INDEPENDENT TRANSACTIONS +If you start a transaction while another transaction is in progress, by +default, PowerShell does not start a new transaction. Instead, it adds a +"subscriber" to the current transaction. -If you start a transaction while another transaction is in progress, -by default, Windows PowerShell does not start a new transaction. -Instead, it adds a "subscriber" to the current transaction. +When a transaction has multiple subscribers, a single Undo-Transaction command +at any point rolls back the entire transaction for all subscribers. However, +to commit the transaction, you must enter a Complete-Transaction command for +every subscriber. -When a transaction has multiple subscribers, a single -Undo-Transaction command at any point rolls back the entire -transaction for all subscribers. However, to commit the transaction, -you must enter a Complete-Transaction command for every subscriber. - -To find the number of subscribers to a transaction, check the -SubscriberCount property of the transaction object. For example, -the following command uses the Get-Transaction cmdlet to get -the value of the SubscriberCount property of the active transaction: +To find the number of subscribers to a transaction, check the SubscriberCount +property of the transaction object. For example, the following command uses +the Get-Transaction cmdlet to get the value of the SubscriberCount property of +the active transaction: +```powershell (Get-Transaction).SubscriberCount +``` -Adding a subscriber is the default behavior because most transactions -that are started while another transaction is in progress are related -to the original transaction. In the typical model, a script that -contains a transaction calls a helper script that contains its own -transaction. Because the transactions are related, they should be -rolled back or committed as a unit. - -However, you can start a transaction that is independent of the -current transaction by using the Independent parameter of the -Start-Transaction cmdlet. +Adding a subscriber is the default behavior because most transactions that are +started while another transaction is in progress are related to the original +transaction. In the typical model, a script that contains a transaction calls +a helper script that contains its own transaction. Because the transactions +are related, they should be rolled back or committed as a unit. -When you start an independent transaction, Start-Transaction -creates a new transaction object, and the new transaction becomes -the active transaction. The independent transaction can be -committed or rolled back without affecting the original transaction. +However, you can start a transaction that is independent of the current +transaction by using the Independent parameter of the Start-Transaction +cmdlet. -When the independent transaction is finished (committed or rolled -back), the original transaction becomes the active transaction -again. +When you start an independent transaction, Start-Transaction creates a new +transaction object, and the new transaction becomes the active transaction. +The independent transaction can be committed or rolled back without affecting +the original transaction. -# CHANGING DATA +When the independent transaction is finished (committed or rolled back), the +original transaction becomes the active transaction again. +## CHANGING DATA -When you use transactions to change data, the data that is affected -by the transaction is not changed until you commit the transaction. -However, the same data can be changed by commands that are not -part of the transaction. +When you use transactions to change data, the data that is affected by the +transaction is not changed until you commit the transaction. However, the same +data can be changed by commands that are not part of the transaction. -Keep this in mind when you are using transactions to manage shared -data. Typically, databases have mechanisms that lock the data while -you are working on it, preventing other users, and other commands, -scripts, and functions, from changing it. +Keep this in mind when you are using transactions to manage shared data. +Typically, databases have mechanisms that lock the data while you are working +on it, preventing other users, and other commands, scripts, and functions, +from changing it. -However, the lock is a feature of the database. It is not related -to transactions. If you are working in a transaction-enabled -file system or other data store, the data can be changed while -the transaction is in progress. +However, the lock is a feature of the database. It is not related to +transactions. If you are working in a transaction-enabled file system or other +data store, the data can be changed while the transaction is in progress. -# EXAMPLES +## EXAMPLES -The examples in this section use the Windows PowerShell Registry -provider and assume that you are familiar with it. For information -about the Registry provider, type "get-help registry". +The examples in this section use the PowerShell Registry provider and assume +that you are familiar with it. For information about the Registry provider, +type "get-help registry". -# EXAMPLE 1: COMMITTING A TRANSACTION +### EXAMPLE 1: COMMITTING A TRANSACTION +To create a transaction, use the Start-Transaction cmdlet. The following +command starts a transaction with the default settings. -To create a transaction, use the Start-Transaction cmdlet. The -following command starts a transaction with the default settings. - +```powershell start-transaction +``` -To include commands in the transaction, use the UseTransaction -parameter of the cmdlet. By default, commands are not included -in the transaction, +To include commands in the transaction, use the UseTransaction parameter of +the cmdlet. By default, commands are not included in the transaction, -For example, the following command, which sets the current -location in the Software key of the HKCU: drive, is not included -in the transaction. +For example, the following command, which sets the current location in the +Software key of the HKCU: drive, is not included in the transaction. +```powershell cd hkcu:\Software +``` The following command, which creates the MyCompany key, uses the -UseTransaction parameter of the New-Item cmdlet to include the -command in the active transaction. +UseTransaction parameter of the New-Item cmdlet to include the command in the +active transaction. +```powershell new-item MyCompany -UseTransaction +``` -The command returns an object that represents the new key, but -because the command is part of the transaction, the registry -is not yet changed. +The command returns an object that represents the new key, but because the +command is part of the transaction, the registry is not yet changed. +``` Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -0 0 MyCompany {} + 0 0 MyCompany {} +``` -To commit the transaction, use the Complete-Transaction cmdlet. -Because it always affects the active transaction, you cannot specify -the transaction. +To commit the transaction, use the Complete-Transaction cmdlet. Because it +always affects the active transaction, you cannot specify the transaction. +```powershell complete-transaction +``` As a result, the MyCompany key is added to the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# EXAMPLE 2: ROLLING BACK A TRANSACTION +### EXAMPLE 2: ROLLING BACK A TRANSACTION +To create a transaction, use the Start-Transaction cmdlet. The following +command starts a transaction with the default settings. -To create a transaction, use the Start-Transaction cmdlet. The -following command starts a transaction with the default settings. - +```powershell start-transaction +``` The following command, which creates the MyOtherCompany key, uses the -UseTransaction parameter of the New-Item cmdlet to include the -command in the active transaction. +UseTransaction parameter of the New-Item cmdlet to include the command in the +active transaction. +```powershell new-item MyOtherCompany -UseTransaction +``` -The command returns an object that represents the new key, but -because the command is part of the transaction, the registry -is not yet changed. +The command returns an object that represents the new key, but because the +command is part of the transaction, the registry is not yet changed. +``` Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -0 0 MyOtherCompany {} + 0 0 MyOtherCompany {} +``` -To roll back the transaction, use the Undo-Transaction cmdlet. -Because it always affects the active transaction, you do not specify -the transaction. +To roll back the transaction, use the Undo-Transaction cmdlet. Because it +always affects the active transaction, you do not specify the transaction. +```powershell Undo-transaction +``` The result is that the MyOtherCompany key is not added to the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# EXAMPLE 3: PREVIEWING A TRANSACTION +### EXAMPLE 3: PREVIEWING A TRANSACTION +Typically, the commands used in a transaction change data. However, the +commands that get data are useful in a transaction, too, because they get data +inside of the transaction. This provides a preview of the changes that +committing the transaction would cause. -Typically, the commands used in a transaction change data. However, -the commands that get data are useful in a transaction, too, because -they get data inside of the transaction. This provides a preview of the -changes that committing the transaction would cause. - -The following example shows how to use the Get-ChildItem command -(the alias is "dir") to preview the changes in a transaction. +The following example shows how to use the Get-ChildItem command (the alias is +"dir") to preview the changes in a transaction. The following command starts a transaction. +```powershell start-transaction +``` -The following command uses the New-ItemProperty cmdlet to add the -MyKey registry entry to the MyCompany key. The command uses the -UseTransaction parameter to include the command in the transaction. +The following command uses the New-ItemProperty cmdlet to add the MyKey +registry entry to the MyCompany key. The command uses the UseTransaction +parameter to include the command in the transaction. +```powershell new-itemproperty -path MyCompany -Name MyKey -value 123 -UseTransaction +``` -The command returns an object representing the new registry entry, -but the registry entry is not changed. +The command returns an object representing the new registry entry, but the +registry entry is not changed. +``` MyKey ----- -# 123 - +123 +``` To get the items that are currently in the registry, use a Get-ChildItem -command ("dir") without the UseTransaction parameter. The following -command gets items that begin with "M." +command ("dir") without the UseTransaction parameter. The following command +gets items that begin with "M." +```powershell dir m* +``` The result shows that no entries have yet been added to the MyCompany key. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` To preview the effect of committing the transaction, enter a Get-ChildItem -("dir") command with the UseTransaction parameter. This command has a view -of the data from within the transaction. +("dir") command with the UseTransaction parameter. This command has a view of +the data from within the transaction. +```powershell dir m* -useTransaction +``` -The result shows that, if the transaction is committed, the MyKey entry -will be added to the MyCompany key. +The result shows that, if the transaction is committed, the MyKey entry will +be added to the MyCompany key. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 1 MyCompany {MyKey} - -# EXAMPLE 4: COMBINING TRANSACTED AND NON-TRANSACTED COMMANDS - + 83 1 Microsoft {(default)} + 0 1 MyCompany {MyKey} +``` -You can enter non-transacted commands during a transaction. The -non-transacted commands affect the data immediately, but they do -not affect the transaction. +### EXAMPLE 4: COMBINING TRANSACTED AND NON-TRANSACTED COMMANDS -The following command starts a transaction in the HKCU:\Software -registry key. +You can enter non-transacted commands during a transaction. The non-transacted +commands affect the data immediately, but they do not affect the transaction. +The following command starts a transaction in the HKCU:\Software registry key. +```powershell start-transaction +``` -The next three commands use the New-Item cmdlet to add keys to -the registry. The first and third commands use the UseTransaction -parameter to include the commands in the transaction. The second -command omits the parameter. Because the second command is not -included in the transaction, it is effective immediately. +The next three commands use the New-Item cmdlet to add keys to the registry. +The first and third commands use the UseTransaction parameter to include the +commands in the transaction. The second command omits the parameter. Because +the second command is not included in the transaction, it is effective +immediately. +```powershell new-item MyCompany1 -UseTransaction - new-item MyCompany2 - new-item MyCompany3 -UseTransaction +``` -To view the current state of the registry, use a Get-ChildItem ("dir") -command without the UseTransaction parameter. This command gets items -that begin with "M." +To view the current state of the registry, use a Get-ChildItem ("dir") command +without the UseTransaction parameter. This command gets items that begin with +"M." +```powershell dir m* +``` -The result shows that the MyCompany2 key is added to the registry, but -the MyCompany1 and MyCompany3 keys, which are part of the transaction, -are not added. +The result shows that the MyCompany2 key is added to the registry, but the +MyCompany1 and MyCompany3 keys, which are part of the transaction, are not +added. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany2 {} + 83 1 Microsoft {(default)} + 0 0 MyCompany2 {} +``` The following command commits the transaction. +```powershell complete-transaction +``` Now, the keys that were added as part of the transaction appear in the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property @@ -454,327 +463,389 @@ SKC VC Name Property 0 0 MyCompany1 {} 0 0 MyCompany2 {} 0 0 MyCompany3 {} +``` -# EXAMPLE 5: USING AUTOMATIC ROLLBACK +### EXAMPLE 5: USING AUTOMATIC ROLLBACK +When a command in a transaction generates an error of any kind, the +transaction is automatically rolled back. -When a command in a transaction generates an error -of any kind, the transaction is automatically rolled -back. - -This default behavior is designed for scripts that -run transactions. Scripts are typically well tested -and include error-handling logic, so errors are not +This default behavior is designed for scripts that run transactions. Scripts +are typically well tested and include error-handling logic, so errors are not expected and should terminate the transaction. -The first command starts a transaction in the HKCU:\Software -registry key. +The first command starts a transaction in the HKCU:\Software registry key. +```powershell start-transaction +``` -The following command uses the New-Item cmdlet to -add the MyCompany key to the registry. The command uses -the UseTransaction parameter (the alias is "usetx") to include -the command in the transaction. +The following command uses the New-Item cmdlet to add the MyCompany key to the +registry. The command uses the UseTransaction parameter (the alias is "usetx") +to include the command in the transaction. +```powershell New-Item MyCompany -UseTX +``` -Because the MyCompany key already exists in the registry, -the command fails, and the transaction is rolled back. +Because the MyCompany key already exists in the registry, the command fails, +and the transaction is rolled back. +```output New-Item : A key at this path already exists At line:1 char:9 + new-item <<<< MyCompany -usetx +``` -A Get-Transaction command confirms that the transaction -has been rolled back and that the SubscriberCount is 0. +A Get-Transaction command confirms that the transaction has been rolled back +and that the SubscriberCount is 0. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 0 RolledBack +``` -# EXAMPLE 6: CHANGING THE ROLLBACK PREFERENCE +### EXAMPLE 6: CHANGING THE ROLLBACK PREFERENCE - -If you want the transaction to be more error tolerant, -you can use the RollbackPreference parameter of -Start-Transaction to change the preference. +If you want the transaction to be more error tolerant, you can use the +RollbackPreference parameter of Start-Transaction to change the preference. The following command starts a transaction with a rollback preference of "Never". +```powershell start-transaction -rollbackpreference Never +``` -In this case, when the command fails, the transaction -is not automatically rolled back. +In this case, when the command fails, the transaction is not automatically +rolled back. +```powershell New-Item MyCompany -UseTX +``` +```output New-Item : A key at this path already exists At line:1 char:9 + new-item <<<< MyCompany -usetx +``` -Because the transaction is still active, you can -resubmit the command as part of the transaction. +Because the transaction is still active, you can resubmit the command as part +of the transaction. +```powershell New-Item MyOtherCompany -UseTX +``` -# EXAMPLE 7: USING THE USE-TRANSACTION CMDLET - +### EXAMPLE 7: USING THE USE-TRANSACTION CMDLET -The Use-Transaction cmdlet enables you to do direct scripting -against transaction-enabled Microsoft .NET Framework objects. -Use-Transaction takes a script block that can only contain commands -and expressions that use transaction-enabled .NET Framework objects, -such as instances of the +The Use-Transaction cmdlet enables you to do direct scripting against +transaction-enabled Microsoft .NET Framework objects. Use-Transaction takes a +script block that can only contain commands and expressions that use +transaction-enabled .NET Framework objects, such as instances of the Microsoft.PowerShell.Commands.Management.TransactedString class. The following command starts a transaction. +```powershell start-transaction +``` -The following New-Object command creates an instance of the -TransactedString class and saves it in the $t variable. +The following New-Object command creates an instance of the TransactedString +class and saves it in the $t variable. +```powershell $t = New-Object Microsoft.PowerShell.Commands.Management.TransactedString +``` -The following command uses the Append method of the TransactedString -object to add text to the string. Because the command is not part -of the transaction, the change is effective immediately. +The following command uses the Append method of the TransactedString object to +add text to the string. Because the command is not part of the transaction, +the change is effective immediately. +```powershell $t.append("Windows") +``` -The following command uses the same Append method to add text, but -it adds the text as part of the transaction. The command is enclosed -in braces, and it is set as the value of the ScriptBlock parameter of -Use-Transaction. The UseTransaction parameter (UseTx) is required. +The following command uses the same Append method to add text, but it adds the +text as part of the transaction. The command is enclosed in braces, and it is +set as the value of the ScriptBlock parameter of Use-Transaction. The +UseTransaction parameter (UseTx) is required. +```powershell use-transaction {$t.append(" PowerShell")} -usetx +``` -To see the current content of the transacted string in $t, use the -ToString method of the TransactedString object. +To see the current content of the transacted string in $t, use the ToString +method of the TransactedString object. +```powershell $t.tostring() +``` The output shows that only the non-transacted changes are effective. +```output Windows +``` -To see the current content of the transacted string in $t from within -the transaction, embed the expression in a Use-Transaction command. +To see the current content of the transacted string in $t from within the +transaction, embed the expression in a Use-Transaction command. +```powershell use-transaction {$s.tostring()} -usetx +``` The output shows the transaction view. -Windows PowerShell +```output +PowerShell +``` The following command commits the transaction. +```powershell complete-transaction +``` To see the final string: +``` $t.tostring() +PowerShell +``` -Windows PowerShell +### EXAMPLE 8: MANAGING MULTI-SUBSCRIBER TRANSACTIONS -# EXAMPLE 8: MANAGING MULTI-SUBSCRIBER TRANSACTIONS - - -When you start a transaction while another transaction is in -progress, Windows PowerShell does not create a second transaction -by default. Instead, it adds a subscriber to the current -transaction. +When you start a transaction while another transaction is in progress, +PowerShell does not create a second transaction by default. Instead, it adds a +subscriber to the current transaction. -This example shows how to view and manage a multi-subscriber -transaction. +This example shows how to view and manage a multi-subscriber transaction. Begin by starting a transaction in the HKCU:\Software key. +```powershell start-transaction +``` -The following command uses the Get-Transaction command to -get the active transaction. +The following command uses the Get-Transaction command to get the active +transaction. +```powershell get-transaction +``` The result shows the object that represents the active transaction. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The following command adds the MyCompany key to the registry. -The command uses the UseTransaction parameter to include the -command in the transaction. +The following command adds the MyCompany key to the registry. The command uses +the UseTransaction parameter to include the command in the transaction. +```powershell new-item MyCompany -UseTransaction +``` -The following command uses the Start-Transaction command to -start a transaction. Although this command is typed at the command -prompt, this scenario is more likely to happen when you run a -script that contains a transaction. +The following command uses the Start-Transaction command to start a +transaction. Although this command is typed at the command prompt, this +scenario is more likely to happen when you run a script that contains a +transaction. +```powershell start-transaction +``` -A Get-Transaction command shows that the subscriber count on the -transaction object is incremented. The value is now 2. +A Get-Transaction command shows that the subscriber count on the transaction +object is incremented. The value is now 2. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 2 Active +``` -The next command uses the New-ItemProperty cmdlet to add the -MyKey registry entry to the MyCompany key. It uses the UseTransaction -parameter to include the command in the transaction. +The next command uses the New-ItemProperty cmdlet to add the MyKey registry +entry to the MyCompany key. It uses the UseTransaction parameter to include +the command in the transaction. +```powershell new-itemproperty -path MyCompany -name MyKey -UseTransaction +``` -The MyCompany key does not exist in the registry, but this -command succeeds because the two commands are part of the -same transaction. +The MyCompany key does not exist in the registry, but this command succeeds +because the two commands are part of the same transaction. -The following command commits the transaction. If it rolled back -the transaction, the transaction would be rolled back for all the -subscribers. +The following command commits the transaction. If it rolled back the +transaction, the transaction would be rolled back for all the subscribers. +```powershell complete-transaction +``` -A Get-Transaction command shows that the subscriber count on the -transaction object is 1, but the value of Status is still Active -(not Committed). +A Get-Transaction command shows that the subscriber count on the transaction +object is 1, but the value of Status is still Active (not Committed). +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -To finish committing the transaction, enter a second Complete- -Transaction command. To commit a multi-subscriber transaction, -you must enter one Complete-Transaction command for each -Start-Transaction command. +To finish committing the transaction, enter a second Complete- Transaction +command. To commit a multi-subscriber transaction, you must enter one +Complete-Transaction command for each Start-Transaction command. +```powershell complete-transaction +``` -Another Get-Transaction command shows that the transaction -has been committed. +Another Get-Transaction command shows that the transaction has been committed. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 0 Committed +``` -# EXAMPLE 9: MANAGING INDEPENDENT TRANSACTIONS - +### EXAMPLE 9: MANAGING INDEPENDENT TRANSACTIONS -When you start a transaction while another transaction is in -progress, you can use the Independent parameter of Start-Transaction -to make the new transaction independent of the original transaction. +When you start a transaction while another transaction is in progress, you can +use the Independent parameter of Start-Transaction to make the new transaction +independent of the original transaction. -When you do, Start-Transaction creates a new transaction object -and makes the new transaction the active transaction. +When you do, Start-Transaction creates a new transaction object and makes the +new transaction the active transaction. -Begin by starting a transaction in the HKCU:\Software key. +Begin by starting a transaction in the HKCU:\\Software key. +```powershell start-transaction +``` -The following command uses the Get-Transaction command to -get the active transaction. +The following command uses the Get-Transaction command to get the active +transaction. +```powershell get-transaction +``` The result shows the object that represents the active transaction. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The following command adds the MyCompany registry key as part of -the transaction. It uses the UseTransaction parameter (UseTx) -to include the command in the active transaction. +The following command adds the MyCompany registry key as part of the +transaction. It uses the UseTransaction parameter (UseTx) to include the +command in the active transaction. +```powershell new-item MyCompany -use +``` -The following command starts a new transaction. The command uses -the Independent parameter to indicate that this transaction -is not a subscriber to the active transaction. +The following command starts a new transaction. The command uses the +Independent parameter to indicate that this transaction is not a subscriber to +the active transaction. +```powershell start-transaction -independent +``` -When you create an independent transaction, the new (most-recently -created) transaction becomes the active transaction. You can use -a Get-Transaction command to get the active transaction. +When you create an independent transaction, the new (most-recently created) +transaction becomes the active transaction. You can use a Get-Transaction +command to get the active transaction. +```powershell get-transaction +``` -Note that the SubscriberCount of the transaction is 1, indicating -that there are no other subscribers and that the transaction is -new. +Note that the SubscriberCount of the transaction is 1, indicating that there +are no other subscribers and that the transaction is new. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The new transaction must be finished (either committed or rolled -back) before you can manage the original transaction. +The new transaction must be finished (either committed or rolled back) before +you can manage the original transaction. -The following command adds the MyOtherCompany key to the registry. -It uses the UseTransaction parameter (UseTx) to include the command -in the active transaction. +The following command adds the MyOtherCompany key to the registry. It uses the +UseTransaction parameter (UseTx) to include the command in the active +transaction. +```powershell new-item MyOtherCompany -usetx +``` -Now, roll back the transaction. If there were a single -transaction with two subscribers, rolling back the transaction -would roll back the entire transaction for all the subscribers. +Now, roll back the transaction. If there were a single transaction with two +subscribers, rolling back the transaction would roll back the entire +transaction for all the subscribers. -However, because these transactions are independent, rolling -back the newest transaction cancels the registry changes and -makes the original transaction the active transaction. +However, because these transactions are independent, rolling back the newest +transaction cancels the registry changes and makes the original transaction +the active transaction. +```powershell undo-transaction +``` -A Get-Transaction command confirms that the original -transaction is still active in the session. +A Get-Transaction command confirms that the original transaction is still +active in the session. +```powershell get-transaction +``` +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` The following command commits the active transaction. +```powershell complete-transaction +``` -A Get-ChildItem command shows that the registry has been -changed. +A Get-ChildItem command shows that the registry has been changed. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# SEE ALSO +## SEE ALSO -Start-Transaction +[Start-Transaction](../../Microsoft.PowerShell.Management/Start-Transaction.md) -Get-Transaction +[Get-Transaction](../../Microsoft.PowerShell.Management/Get-Transaction.md) -Complete-Transaction +[Complete-Transaction](../../Microsoft.PowerShell.Management/Complete-Transaction.md) -Undo-Transaction +[Undo-Transaction](../../Microsoft.PowerShell.Management/Undo-Transaction.md) -Use-Transaction +[Use-Transaction](../../Microsoft.PowerShell.Management/Use-Transaction.md) -Registry (provider) +[Get-PSProvider](../../Microsoft.PowerShell.Management/Get-PSProvider.md) -[about_Providers](about_Providers.md) - -Get-PSProvider - -Get-ChildItem +[Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) +[about_Providers](about_Providers.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index 6bb686ca0a2e..7d45f6555135 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,487 +7,455 @@ title: about_Updatable_Help --- # About Updatable Help -## about_Updatable_Help +## SHORT DESCRIPTION +Describes the updatable help system in PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes the updatable help system in Windows PowerShell. +PowerShell provides several different ways to access the most up-to-date help +topics for PowerShell cmdlets and concepts. -# LONG DESCRIPTION +The Updatable Help system, introduced in PowerShell 3.0, is designed to assure +that you always have the newest help topics on your local computer so that you +can read them at the command line. It makes it easy to download and install +help files and to update them whenever newer help files become available. -Windows PowerShell provides several different ways to access -the most up-to-date help topics for Windows PowerShell cmdlets -and concepts. +To provide updated help for multiple computers in an enterprise and for +computers that do not have access to the Internet, Updatable Help lets you +download help files to a file system directory or file share, and then install +the help files from the file share. -The Updatable Help system, introduced in Windows PowerShell 3.0, -is designed to assure that you always have the newest help topics -on your local computer so that you can read them at the command -line. It makes it easy to download and install help files and -to update them whenever newer help files become available. +In PowerShell 4.0, the HelpInfoUri property is preserved over Windows +PowerShell remoting, which allows Save-Help to work for modules that are +installed on a remote computer, but are not necessarily installed on the local +computer. You can save a PSModuleInfo object to disk or removable media (such +as a USB drive) by running Export-Clixml on a computer that does not have +Internet access, importing the PSModuleInfo object on a computer that does +have Internet access, and then running Save-Help on the PSModuleInfo object. +The saved help can be copied to the remote, disconnected computer by using +removable media, and then installed by running Update-Help. These improvements +in Save-Help functionality let you install help on computers that are without +any kind of network access. For an example of how to use the new Save-Help +functionality, see "HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP" in this +topic. -To provide updated help for multiple computers in an enterprise -and for computers that do not have access to the Internet, Updatable -Help lets you download help files to a file system directory or file -share, and then install the help files from the file share. +Updatable Help also supports online access to the newest help topics and basic +help for cmdlets, even when there are no help files on the computer. -In Windows PowerShell 4.0, the HelpInfoUri property is preserved over -Windows PowerShell remoting, which allows Save-Help to work for -modules that are installed on a remote computer, but are not -necessarily installed on the local computer. You can save a PSModuleInfo -object to disk or removable media (such as a USB drive) by running -Export-Clixml on a computer that does not have Internet access, -importing the PSModuleInfo object on a computer that does have Internet -access, and then running Save-Help on the PSModuleInfo object. The -saved help can be copied to the remote, disconnected computer by using -removable media, and then installed by running Update-Help. These -improvements in Save-Help functionality let you install help on -computers that are without any kind of network access. For an example -of how to use the new Save-Help functionality, see "HOW TO UPDATE HELP -FROM A FILE SHARE: SAVE-HELP" in this topic. +PowerShell 3.0 does not come with Help files. You can use the Updatable Help +feature to install the help files for all of the commands that are included by +default in PowerShell and for all Windows modules. -Updatable Help also supports online access to the newest help topics -and basic help for cmdlets, even when there are no help files on the -computer. - -Windows PowerShell 3.0 does not come with Help files. You can use -the Updatable Help feature to install the help files for all of the -commands that are included by default in Windows PowerShell and for -all Windows modules. - -# UPDATABLE HELP CMDLETS - - -Update-Help: Downloads the newest help files from the Internet or -a file share, and installs them on the local computer. - -Save-Help: Downloads the newest help files from the Internet and -saves them in a file system directory or file share. To -install the help files on computers, use Update-Help. +## UPDATABLE HELP CMDLETS -Get-Help: -- Displays help topics at the command line. --- Gets help from the help files on the computer. --- Displays auto-generated help for cmdlets and functions -that do not have help files. --- Opens online help topics for cmdlets, functions, -scripts, and workflows in your default Internet -browser. +- Update-Help: Downloads the newest help files from the Internet or a file + share, and installs them on the local computer. -# UPDATE HELP IN WINDOWS POWERSHELL ISE +- Save-Help: Downloads the newest help files from the Internet and saves them in + a file system directory or file share. To install the help files on computers, + use Update-Help. -You can also update help by using the "Update Windows PowerShell -Help" item in the Help menu in Windows PowerShell Integrated -Scripting Environment (ISE). +- Get-Help: Displays help topics at the command line. Gets help from the + help files on the computer. Displays auto-generated help for cmdlets and + functions that do not have help files. Opens online help topics for + cmdlets, functions, scripts, and workflows in your default Internet browser. -The "Update Windows PowerShell Help" item runs an Update-Help -command without parameters. +## UPDATE HELP IN PowerShell ISE -# AUTO-GENERATED HELP: HELP WITHOUT HELP FILES +You can also update help by using the "Update PowerShell Help" item in the +Help menu in PowerShell Integrated Scripting Environment (ISE). +The "Update PowerShell Help" item runs an Update-Help command without +parameters. -If you do not have the help file for a cmdlet, function, -or workflow on the computer, the Get-Help cmdlet displays -auto-generated help and prompts you to download the help -files or read them online. +## AUTO-GENERATED HELP: HELP WITHOUT HELP FILES -Auto-generated help includes syntax and aliases, and remarks -that explain how to use the Updatable Help cmdlets and to -access the online help topics. +If you do not have the help file for a cmdlet, function, or workflow on the +computer, the Get-Help cmdlet displays auto-generated help and prompts you to +download the help files or read them online. -For example, the following command gets basic help for the -Get-Culture cmdlet. The output shows the Get-Help display -when there are no help files on the computer. +Auto-generated help includes syntax and aliases, and remarks that explain how +to use the Updatable Help cmdlets and to access the online help topics. -PS C:> Get-Help Get-Culture - -# NAME - -Get-Culture - -# SYNTAX +For example, the following command gets basic help for the Get-Culture cmdlet. +The output shows the Get-Help display when there are no help files on the +computer. -Get-Culture [] +```powershell +Get-Help Get-Culture +``` -# ALIASES +```output +NAME + Get-Culture -None +SYNTAX + Get-Culture [] -# REMARKS +ALIASES + None -To get the latest Help content including descriptions -and examples type: Update-Help. +REMARKS + To get the latest Help content including descriptions and examples + type: Update-Help. +``` -# HELP FILES FOR MODULES +## HELP FILES FOR MODULES +The smallest unit of Updatable Help is help for a module. Module help includes +help for all of the cmdlets, functions, workflows, providers, scripts, and +concepts in a module. You can update help for all modules that are installed +on the computer, even if they are not imported into the current session. -The smallest unit of Updatable Help is help for a module. Module -help includes help for all of the cmdlets, functions, workflows, -providers, scripts, and concepts in a module. You can update help -for all modules that are installed on the computer, even if they -are not imported into the current session. +You can update help for the entire module, but you cannot update help for +individual cmdlets. -You can update help for the entire module, but you cannot update -help for individual cmdlets. - -To find the module that contains a particular cmdlet, use the -following command format: +To find the module that contains a particular cmdlet, use the following +command format: +```powershell (Get-Command ).ModuleName +``` For example, to find the module that contains the Set-ExecutionPolicy cmdlet, type: +```powershell (Get-Command Set-ExecutionPolicy).ModuleName +``` To update help for a particular module, type: +```powershell Update-Help -Module +``` For example, to update help for the module that contains the Set-ExecutionPolicy cmdlet, type: +```powershell Update-Help -Module Microsoft.PowerShell.Security +``` -# PERMISSIONS FOR UPDATABLE HELP - - -To update help for the modules in the $pshome\Modules directory, -you must be member of the Administrators group on the computer. +## PERMISSIONS FOR UPDATABLE HELP -If you are not a member of the Administrators group, you cannot -update help for these modules; but if you have Internet access, -you can view help online in the TechNet Library. +To update help for the modules in the \$pshome\\Modules directory, you must be +member of the Administrators group on the computer. -Updating help for modules in the -$home\Documents\WindowsPowerShell\Modules -directory or modules in other subdirectories of the $home -directory do not require special permissions. +If you are not a member of the Administrators group, you cannot update help +for these modules; but if you have Internet access, you can view help online +in the TechNet Library. -The Update-Help and Save-Help cmdlets have a UseDefaultCredentials -parameter that provides the explicit credentials of the current -user. This parameter is designed for accessing secure Internet -locations. +Updating help for modules in the \$home\\Documents\\WindowsPowerShell\\Modules +directory or modules in other subdirectories of the \$home directory do not +require special permissions. -The Update-Help and Save-Help cmdlets also have a Credential -parameter that allows you to run the command on a remote -computer and access a file share on a third computer. The -Credential parameter is valid only when you use the SourcePath -or LiteralPath parameters of Update-Help and the DestinationPath -or LiteralPath parameters of Save-Help. +The Update-Help and Save-Help cmdlets have a UseDefaultCredentials parameter +that provides the explicit credentials of the current user. This parameter is +designed for accessing secure Internet locations. -# HOW TO INSTALL AND UPDATE HELP FILES +The Update-Help and Save-Help cmdlets also have a Credential parameter that +allows you to run the command on a remote computer and access a file share on +a third computer. The Credential parameter is valid only when you use the +SourcePath or LiteralPath parameters of Update-Help and the DestinationPath or +LiteralPath parameters of Save-Help. +## HOW TO INSTALL AND UPDATE HELP FILES -To download and install help files for the first time, or to update -the help files on your computer, use the Update-Help cmdlet. +To download and install help files for the first time, or to update the help +files on your computer, use the Update-Help cmdlet. -The Update-Help cmdlet does all of the hard work for you, including -the following tasks. +The Update-Help cmdlet does all of the hard work for you, including the +following tasks. --- Determines which modules support Updatable Help. --- Finds the Internet location where each module stores its -Updatable Help files. --- Compares the help files for each module on your computer to -the newest help files that are available for each module. --- Downloads the new files from the Internet. --- Unwraps the help file package. --- Verifies that the files are valid help files. --- Installs the help files in the language-specific subdirectory -of the module directory. +- Determines which modules support Updatable Help. +- Finds the Internet location where each module stores its Updatable Help files. +- Compares the help files for each module on your computer to the newest help + files that are available for each module. +- Downloads the new files from the Internet. +- Unwraps the help file package. +- Verifies that the files are valid help files. +- Installs the help files in the language-specific subdirectory of the module + directory. -To access the new help topics, use the Get-Help cmdlet. You do not -need to restart Windows PowerShell. +To access the new help topics, use the Get-Help cmdlet. You do not need to +restart PowerShell. -To install or update help for all modules on the computer that -supports Updatable Help, type: +To install or update help for all modules on the computer that supports +Updatable Help, type: +```powershell Update-Help +``` -To update help for particular modules, add the Module parameter -of Update-Help. Wildcard characters are permitted in the module name. +To update help for particular modules, add the Module parameter of +Update-Help. Wildcard characters are permitted in the module name. For example, to update help for the ServerManager module, type: +```powershell Update-Help -Module ServerManager - -# NOTES - -Without parameters, Update-Help updates help for all modules -in the session and for all installed modules that support -Updatable Help. To be included, modules must be installed in -directories that are listed in the value of the PSModulePath -environment variable. These are also modules that -are returned by a "Get-Help -ListAvailable" command. - -If the value of the Module parameter is * (all), Update-Help -attempts to update help for all installed modules, including -modules that do not support Updatable Help. This command -typically generates many errors as the cmdlet encounters modules -that do not support Updatable Help. - -# HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP - - -To support computers that are not connected to the Internet, -or to control or streamline help updating in an enterprise, -use the Save-Help cmdlet. The Save-Help cmdlet downloads help -files from the Internet and saves them in a file system directory -that you specify. - -Save-Help compares the help files in the specified directory to -the newest help files that are available for each module. If the -directory has no help files or newer help files are available for -the module, the Save-Help cmdlet downloads the new files from the -Internet. However, it does not unwrap or install the help files. - -To install or update the help files on a computer from help -files that were saved to a file system directory, use the -SourcePath parameter of the Update-Help cmdlet. The Update-Help -cmdlet identifies the newest help files, unwraps and validates them, -and installs them in the language-specific subdirectories of the -module directories. - -For example, to save help for all installed modules to the -\Server\Share directory, type: - -Save-Help -DestinationPath \Server\Share - -Then, to update help from the \Server\Share directory, type: - -Update-Help -SourcePath \Server\Share - -The following examples show the use of Save-Help to save help -for modules that are not installed on the local computer. In -this example, the administrator runs Save-Help to save the help -for the DhcpServer module from an Internet-connected client computer, -without installing the DhcpServer module or DHCP Server role on the -local computer. - -Option 1: Run Invoke-Command to get the PSModuleInfo object for -the remote module, save it in a variable, $m, and then run Save-Help -on the PSModuleInfo object by specifying the variable $m as the -module name. - +``` + +Without parameters, Update-Help updates help for all modules in the session +and for all installed modules that support Updatable Help. To be included, +modules must be installed in directories that are listed in the value of the +PSModulePath environment variable. These are also modules that are returned by +a "Get-Help -ListAvailable" command. + +If the value of the Module parameter is * (all), Update-Help attempts to +update help for all installed modules, including modules that do not support +Updatable Help. This command typically generates many errors as the cmdlet +encounters modules that do not support Updatable Help. + +## HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP + +To support computers that are not connected to the Internet, or to control or +streamline help updating in an enterprise, use the Save-Help cmdlet. The +Save-Help cmdlet downloads help files from the Internet and saves them in a +file system directory that you specify. + +Save-Help compares the help files in the specified directory to the newest +help files that are available for each module. If the directory has no help +files or newer help files are available for the module, the Save-Help cmdlet +downloads the new files from the Internet. However, it does not unwrap or +install the help files. + +To install or update the help files on a computer from help files that were +saved to a file system directory, use the SourcePath parameter of the +Update-Help cmdlet. The Update-Help cmdlet identifies the newest help files, +unwraps and validates them, and installs them in the language-specific +subdirectories of the module directories. + +For example, to save help for all installed modules to the \\\\Server\\Share +directory, type: + +```powershell +Save-Help -DestinationPath \\Server\Share +``` + +Then, to update help from the \\\\Server\\Share directory, type: + +```powershell +Update-Help -SourcePath \\Server\Share +``` + +The following examples show the use of Save-Help to save help for modules that +are not installed on the local computer. In this example, the administrator +runs Save-Help to save the help for the DhcpServer module from an +Internet-connected client computer, without installing the DhcpServer module +or DHCP Server role on the local computer. + +Option 1: Run Invoke-Command to get the PSModuleInfo object for the remote +module, save it in a variable, $m, and then run Save-Help on the PSModuleInfo +object by specifying the variable $m as the module name. + +```powershell $m = Invoke-Command -ComputerName RemoteServer -ScriptBlock { Get-Module -Name DhcpServer -ListAvailable } Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -Option 2: Open a PSSession, targeted at the computer that is -running the DHCP Server module, to get the PSModuleInfo object for -the module, save it in a variable $m, and then run Save-Help on the -object that is saved in the $m variable. +Option 2: Open a PSSession, targeted at the computer that is running the DHCP +Server module, to get the PSModuleInfo object for the module, save it in a +variable $m, and then run Save-Help on the object that is saved in the $m +variable. +```powershell $s = New-PSSession -ComputerName RemoteServer $m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -Option 3: Open a CIM session, targeted at the computer that is -running the DHCP Server module, to get the PSModuleInfo object for -the module, save it in a variable $m, and then run Save-Help on the -object that is saved in the $m variable. +Option 3: Open a CIM session, targeted at the computer that is running the +DHCP Server module, to get the PSModuleInfo object for the module, save it in +a variable $m, and then run Save-Help on the object that is saved in the $m +variable. +```powershell $c = New-CimSession -ComputerName RemoteServer $m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -In the following example, the administrator installs help for the -DHCP Server module on a computer that does not have network access. +In the following example, the administrator installs help for the DHCP Server +module on a computer that does not have network access. -First, run Export-Clixml to export the PSModuleInfo object to -a shared folder or to removable media. +First, run Export-Clixml to export the PSModuleInfo object to a shared folder +or to removable media. +```powershell $m = Get-Module -Name DhcpServer -ListAvailable Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m +``` -Next, transport the removable media to a computer that has -Internet access, and then import the PSModuleInfo object with -Import-Clixml. Run Save-Help to save the Help for the imported -DhcpServer module PSModuleInfo object. +Next, transport the removable media to a computer that has Internet access, +and then import the PSModuleInfo object with Import-Clixml. Run Save-Help to +save the Help for the imported DhcpServer module PSModuleInfo object. +```powershell $deserialized_m = Import-Clixml E:\UsbFlashDrive\DhcpModule.xml -Save-Help -Module $deserialized_m -DestinationPath -E:\UsbFlashDrive\SavedHelp - -Finally, transport the removable media back to the computer that -does not have network access, and then install the help by running -Update-Help. - -Update-Help -Module DhcpServer -SourcePath +Save-Help -Module $deserialized_m -DestinationPath ` E:\UsbFlashDrive\SavedHelp +``` -# NOTES: +Finally, transport the removable media back to the computer that does not have +network access, and then install the help by running Update-Help. -Without parameters, Save-Help downloads help for all modules -in the session and for all installed modules that support -Updatable Help. To be included, modules must be installed in -directories that are listed in the value of the PSModulePath -environment variable, on either the local computer or on a remote -computer for which you want to save help. These are also modules -that are returned by running a "Get-Help -ListAvailable" command. +```powershell +Update-Help -Module DhcpServer -SourcePath E:\UsbFlashDrive\SavedHelp +``` -# HOW TO UPDATE HELP FILES IN DIFFERENT LANGUAGES +Without parameters, Save-Help downloads help for all modules in the session +and for all installed modules that support Updatable Help. To be included, +modules must be installed in directories that are listed in the value of the +PSModulePath environment variable, on either the local computer or on a remote +computer for which you want to save help. These are also modules that are +returned by running a "Get-Help -ListAvailable" command. +## HOW TO UPDATE HELP FILES IN DIFFERENT LANGUAGES -By default, the Update-Help and Save-Help cmdlets download -help in the UI culture and language that is set for Windows -on the local computer. If help files for the specified modules -are not available in the local UI culture, Update-Help and -Save-Help use the Windows language fallback rules to find the +By default, the Update-Help and Save-Help cmdlets download help in the UI +culture and language that is set for Windows on the local computer. If help +files for the specified modules are not available in the local UI culture, +Update-Help and Save-Help use the Windows language fallback rules to find the best supported language. -However, you can use the UICulture parameters of the Update-Help -and Save-Help cmdlets to download and install help files in any -UI cultures in which they are available. +However, you can use the UICulture parameters of the Update-Help and Save-Help +cmdlets to download and install help files in any UI cultures in which they +are available. -For example, to save the newest help files for all modules on -the session in Japanese (Ja-jp) and French (fr-FR), type: +For example, to save the newest help files for all modules on the session in +Japanese (Ja-jp) and French (fr-FR), type: +```powershell Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr +``` -If help files for the modules are not available in the languages -that you specified, the Update-Help and Save-Help cmdlets return -an error message that lists the languages in which help for each -module is available so you can choose the alternative that best -meets your needs. +If help files for the modules are not available in the languages that you +specified, the Update-Help and Save-Help cmdlets return an error message that +lists the languages in which help for each module is available so you can +choose the alternative that best meets your needs. -# HOW TO UPDATE HELP AUTOMATICALLY +## HOW TO UPDATE HELP AUTOMATICALLY +To assure that you always have the newest help files, you can add an +Update-Help command to your PowerShell profile. -To assure that you always have the newest help files, you can -add an Update-Help command to your Windows PowerShell profile. +An internal quota prevents the Update-Help command from running more than once +each day. To override the once-per-day maximum, use the Force parameter. -An internal quota prevents the Update-Help command from running -more than once each day. To override the once-per-day maximum, -use the Force parameter. - -Use a command like the following one in your profile. This command -updates help for all installed modules in a background job so it -doesn't disturb your work. It uses an Out-Null command to suppress -the job that is returned and any error messages that would otherwise -appear when you use the command more than once per day. +Use a command like the following one in your profile. This command updates +help for all installed modules in a background job so it doesn't disturb your +work. It uses an Out-Null command to suppress the job that is returned and any +error messages that would otherwise appear when you use the command more than +once per day. +```powershell Start-Job {Update-Help} | Out-Null +``` -You can also create a scheduled job that runs the Update-Help or -Save-Help cmdlet at any interval. +You can also create a scheduled job that runs the Update-Help or Save-Help +cmdlet at any interval. For example, the following command creates a scheduled job that runs an -Update-Help help command every Friday at 5:00 AM. To run this command, -start Windows PowerShell with the "Run as administrator" option. +Update-Help help command every Friday at 5:00 AM. To run this command, start +PowerShell with the "Run as administrator" option. +```powershell Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} ` -Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM") +``` -For more information about scheduled jobs, see about_Scheduled_Jobs. - -# HOW TO USE ONLINE HELP - +## HOW TO USE ONLINE HELP -If you cannot or choose not to update the help files on your -local computer, you can still get the newest help files online. +If you cannot or choose not to update the help files on your local computer, +you can still get the newest help files online. -To open the online help topic for any cmdlet or function, use -the Online parameter of the Get-Help cmdlet. +To open the online help topic for any cmdlet or function, use the Online +parameter of the Get-Help cmdlet. -For example, the following command opens the online help topic -for the Get-Job cmdlet in your default Internet browser: +For example, the following command opens the online help topic for the Get-Job +cmdlet in your default Internet browser: +```powershell Get-Help Get-Job -Online --or- -Get-Help -on Get-Job - -To get online help for a script, use the Online parameter and -the full path to the script. - -The Online parameter does not work with About topics. To see -the about topics for Windows PowerShell Core, including help -topics about the Windows PowerShell language, see "Windows -PowerShell Core Module About Topics" at -http://go.microsoft.com/fwlink/?LinkID=113206. - -# HOW TO MINIMIZE OR PREVENT INTERNET DOWNLOADS - -To minimize Internet downloads and provide Updatable Help to -users who are not connected to the Internet, use the Save-Help -cmdlet. Download help from the Internet and save it to a network -share. Then, create a Group Policy setting or scheduled job that -runs an Update-Help command on all computers. Set the value of -the SourcePath parameter of the Update-Help cmdlet to the network -share. - -To prevent users who have Internet access from downloading Updatable -Help from the Internet, use the "Set the default source path for -Update-Help" Group Policy setting. +``` -This Group Policy setting implicitly adds the SourcePath parameter, -with the file system location that you specify, to every Update-Help -command on every affected computer. Users can use the SourcePath -parameter explicitly to specify a different file system location, but -they cannot exclude the SourcePath parameter and download help from -the Internet. +To get online help for a script, use the Online parameter and the full path to +the script. -NOTE: The "Set the default source path for Update-Help" group -policy setting appears under Computer Configuration and -User Configuration. However, only the policy setting -under Computer Configuration is effective. The policy -setting under User Configuration is ignored. +The Online parameter does not work with About topics. To see the about topics +for PowerShell Core, including help topics about the PowerShell language, see +[Windows PowerShell Core Module About Topics](http://go.microsoft.com/fwlink/?LinkID=113206). -For more information, see about_Group_Policy_Settings. +## HOW TO MINIMIZE OR PREVENT INTERNET DOWNLOADS -# HOW TO UPDATE HELP FOR NON-STANDARD MODULES +To minimize Internet downloads and provide Updatable Help to users who are not +connected to the Internet, use the Save-Help cmdlet. Download help from the +Internet and save it to a network share. Then, create a Group Policy setting +or scheduled job that runs an Update-Help command on all computers. Set the +value of the SourcePath parameter of the Update-Help cmdlet to the network +share. -To update or save help for a module that is not returned -by the ListAvailable parameter of the Get-Module cmdlet, -import the module into the current session before running -an Update-Help or Save-Help command. On a remote computer, -before running the Save-Help command, import the module into -the current CIM or PSSession--or Invoke-Command script block-- -that is connected to the remote computer. +To prevent users who have Internet access from downloading Updatable Help from +the Internet, use the "Set the default source path for Update-Help" Group +Policy setting. -When the module is in the current session, run the Update-Help -or Save-Help cmdlets without parameters, or use the Module -parameter to specify the module name. +This Group Policy setting implicitly adds the SourcePath parameter, with the +file system location that you specify, to every Update-Help command on every +affected computer. Users can use the SourcePath parameter explicitly to +specify a different file system location, but they cannot exclude the +SourcePath parameter and download help from the Internet. -The Module parameters of the Update-Help and Save-Help -cmdlets accept only a module name. They do not accept the -path to a module file. +NOTE: The "Set the default source path for Update-Help" group policy setting +appears under Computer Configuration and User Configuration. However, only the +policy setting under Computer Configuration is effective. The policy setting +under User Configuration is ignored. -Use this technique to update or save help for any module -that is not returned by the ListAvailable parameter of the -Get-Module cmdlet, such as a module that is installed in a -location that is not listed in the PSModulePath environment -variable, or a module that is not well-formed (the module -directory does not contain at least one file whose base name -is the same as the directory name). +For more information, see [about_Group_Policy_Settings](about_Group_Policy_Settings.md). -# HOW TO SUPPORT UPDATABLE HELP +## HOW TO UPDATE HELP FOR NON-STANDARD MODULES +To update or save help for a module that is not returned by the ListAvailable +parameter of the Get-Module cmdlet, import the module into the current session +before running an Update-Help or Save-Help command. On a remote computer, +before running the Save-Help command, import the module into the current CIM +or PSSession--or Invoke-Command script block-- that is connected to the remote +computer. -If you author a module, you can support online help and -Updatable Help for your modules. For more information, see -"Supporting Updatable Help" and "Supporting Online Help" -in the MSDN Library. +When the module is in the current session, run the Update-Help or Save-Help +cmdlets without parameters, or use the Module parameter to specify the module +name. -Updatable help not available for Windows PowerShell snap-ins -or comment-based help. +The Module parameters of the Update-Help and Save-Help cmdlets accept only a +module name. They do not accept the path to a module file. -# KEYWORDS +Use this technique to update or save help for any module that is not returned +by the ListAvailable parameter of the Get-Module cmdlet, such as a module that +is installed in a location that is not listed in the PSModulePath environment +variable, or a module that is not well-formed (the module directory does not +contain at least one file whose base name is the same as the directory name). -About_Updateable_Help +## HOW TO SUPPORT UPDATABLE HELP -# REMARKS +If you author a module, you can support online help and Updatable Help for +your modules. For more information, see "Supporting Updatable Help" and +"Supporting Online Help" in the MSDN Library. -The Update-Help and Save-Help cmdlets are not supported on -Windows Preinstallation Environment (Windows PE). +Updatable help not available for PowerShell snap-ins or comment-based help. -# SEE ALSO +# REMARKS -Get-Help +The Update-Help and Save-Help cmdlets are not supported on Windows +Preinstallation Environment (Windows PE). -Save-Help +## SEE ALSO -Update-Help +[Get-Help](../Get-Help.md) -Updatable Help Status Table: http://go.microsoft.com/fwlink/?LinkID=270007 +[Save-Help](../Save-Help.md) +[Update-Help](../Update-Help.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI.md index fe279908cfc3..bafb6c425a08 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_WMI.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,84 +7,104 @@ title: about_WMI --- # About WMI -## about_WMI - ## SHORT DESCRIPTION -Windows Management Instrumentation (WMI) uses the Common Information Model (CIM) to represent systems, applications, networks, devices, and other manageable components of the modern enterprise. +Windows Management Instrumentation (WMI) uses the Common Information Model +(CIM) to represent systems, applications, networks, devices, and other +manageable components of the modern enterprise. ## LONG DESCRIPTION -Windows Management Instrumentation (WMI) is Microsoft’s implementation of Web-Based Enterprise Management (WBEM), the industry standard. -Classic WMI uses DCOM to communicate with networked devices to manage remote systems. Windows PowerShell® 3.0 introduces a CIM provider model that uses WinRM to remove the dependency on DCOM. This CIM provider model also uses new WMI provider APIs that enable developers to write Windows PowerShell cmdlets in native code (C\+\+). +Windows Management Instrumentation (WMI) is Microsoft’s implementation of +Web-Based Enterprise Management (WBEM), the industry standard. -Do not confuse WMI providers with Windows PowerShell providers. Many Windows features have an associated WMI provider that exposes their management capabilities. To get WMI providers, run a WMI query that gets instances of the __Provider WMI class, such as the following query. +Classic WMI uses DCOM to communicate with networked devices to manage remote +systems. Windows PowerShell® 3.0 introduces a CIM provider model that uses +WinRM to remove the dependency on DCOM. This CIM provider model also uses new +WMI provider APIs that enable developers to write Windows PowerShell cmdlets +in native code (C\+\+). +Do not confuse WMI providers with Windows PowerShell providers. Many Windows +features have an associated WMI provider that exposes their management +capabilities. To get WMI providers, run a WMI query that gets instances of the +__Provider WMI class, such as the following query. -``` +```powershell Get-WmiObject -Class __Provider ``` - - ## THREE COMPONENTS OF WMI -The following three components of WMI interact with Windows PowerShell: Namespaces, Providers, and Classes. -WMI Namespaces organize WMI providers and WMI classes into groups of related components. In this way, they are similar to .NET Framework namespaces. Namespaces are not physical locations, but are more like logical databases. All WMI namespaces are instances of the __Namespace system class. The default WMI namespace is Root\/CIMV2 (since Microsoft Windows 2000). To use Windows PowerShell to get WMI namespaces in the current session, use a command with the following format. +The following three components of WMI interact with Windows PowerShell: +Namespaces, Providers, and Classes. +WMI Namespaces organize WMI providers and WMI classes into groups of related +components. In this way, they are similar to .NET Framework namespaces. +Namespaces are not physical locations, but are more like logical databases. +All WMI namespaces are instances of the __Namespace system class. The default +WMI namespace is Root\/CIMV2 (since Microsoft Windows 2000). To use Windows +PowerShell to get WMI namespaces in the current session, use a command with +the following format. -``` +```powershell Get-WmiObject -Class __Namespace ``` +To get WMI namespaces in other namespaces, use the Namespace parameter to +change the location of the search. The following command finds WMI namespaces +that reside in the Root/Cimv2/Applications namespace. -To get WMI namespaces in other namespaces, use the Namespace parameter to change the location of the search. The following command finds WMI namespaces that reside in the Root\/Cimv2\/Applications namespace. - - -``` -Get-WmiObject -Class __Namespace -Namespace -root/CIMv2/applications +```powershell +Get-WmiObject -Class __Namespace -Namespace root/CIMv2/applications ``` +WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces +on a particular system requires performing a recursive query starting at the +root namespace. -WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces on a particular system requires performing a recursive query starting at the root namespace. - -WMI Providers expose information about Windows manageable objects. A provider retrieves data from a component, and passes that data through WMI to a management application, such as Windows PowerShell. Most WMI providers are dynamic providers, which means that they obtain the data dynamically when it is requested through the management application. - +WMI Providers expose information about Windows manageable objects. A provider +retrieves data from a component, and passes that data through WMI to a +management application, such as Windows PowerShell. Most WMI providers are +dynamic providers, which means that they obtain the data dynamically when it +is requested through the management application. ## FINDING WMI CLASSES -In a default installation of Windows 8, there are more than 1,100 WMI classes in Root\/Cimv2. With this many WMI classes, the challenge becomes identifying the appropriate WMI class to use to perform a specific task. Windows PowerShell 3.0 provides two ways to find WMI classes that are related to a specific topic. -For example,to find WMI classes in the root\CIMV2 WMI namespace that are related to disks, you can use a query such as the one shown here. +In a default installation of Windows 8, there are more than 1,100 WMI classes +in Root\/Cimv2. With this many WMI classes, the challenge becomes identifying +the appropriate WMI class to use to perform a specific task. Windows +PowerShell 3.0 provides two ways to find WMI classes that are related to a +specific topic. +For example,to find WMI classes in the root\\CIMV2 WMI namespace that are +related to disks, you can use a query such as the one shown here. -``` +```powershell Get-WmiObject -List *disk* ``` +To find WMI classes that are related to memory, you might use a query such as +the one shown here. -To find WMI classes that are related to memory, you might use a query such as the one shown here. - - -``` +```powershell Get-WmiObject -List *memory* ``` +The CIM cmdlets also provide the ability to discover WMI classes. To do this, +use the Get-CIMClass cmdlet. The command shown here lists WMI classes related +to video. -The CIM cmdlets also provide the ability to discover WMI classes. To do this, use the Get-CIMClass cmdlet. The command shown here lists WMI classes related to video. - - -``` +```powershell Get-CimClass *video* ``` +Tab expansion works when changing WMI namespaces, and therefore use of tab +expansion makes sub-WMI namespaces easily discoverable. In the following +example, the Get-CimClass cmdlet lists WMI classes related to power settings. +To find it, type the `root/CIMV2/` namespace and then press the Tab key +several times until the power namespace appears. Here is the command: -Tab expansion works when changing WMI namespaces, and therefore use of tab expansion makes sub-WMI namespaces easily discoverable. In the following example, the Get-CimClass cmdlet lists WMI classes related to power settings. To find it, type the root\/CIMV2\/ WMI namespace, and then press type the root\/CIMV2\/ WMI namespace, and then press the Tab key several times until the power namespace appears. Here is the command: - - -``` +```powershell Get-CimClass *power* -Namespace root/cimv2/power ``` - - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_WQL.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_WQL.md index 4413e4b4bf38..5835819c2aeb 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_WQL.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_WQL.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,384 +7,356 @@ title: about_WQL --- # About WQL -## about_WQL +## SHORT DESCRIPTION +Describes WMI Query Language (WQL), which can be used to get WMI objects in +Windows PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes WMI Query Language (WQL), which can be -used to get WMI objects in Windows PowerShell. +WQL is the Windows Management Instrumentation (WMI) query language, which is +the language used to get information from WMI. -# LONG DESCRIPTION +You are not required to use WQL to perform a WMI query in Windows PowerShell. +Instead, you can use the parameters of the Get-WmiObject or Get-CimInstance +cmdlets. WQL queries are somewhat faster than standard Get-WmiObject commands +and the improved performance is evident when the commands run on hundreds of +systems. However, be sure that the time you spend to write a successful WQL +query doesn't outweigh the performance improvement. -WQL is the Windows Management Instrumentation (WMI) -query language, which is the language used to get -information from WMI. +The basic WQL statements you need to use WQL are Select, Where, and From. -You are not required to use WQL to perform a WMI -query in Windows PowerShell. Instead, you can -use the parameters of the Get-WmiObject or -Get-CimInstance cmdlets. WQL queries are somewhat -faster than standard Get-WmiObject commands and -the improved performance is evident when the commands -run on hundreds of systems. However, be sure that -the time you spend to write a successful WQL query -doesn't outweigh the performance improvement. +## WHEN TO USE WQL -The basic WQL statements you need to use WQL are -Select, Where, and From. +When working with WMI, and especially with WQL, do not forget that you are +also using Windows PowerShell. Often, if a WQL query does not work as +expected, it's easier to use a standard Windows PowerShell command than to +debug the WQL query. -# WHEN TO USE WQL - - -When working with WMI, and especially with WQL, -do not forget that you are also using Windows -PowerShell. Often, if a WQL query does not work as -expected, it's easier to use a standard Windows -PowerShell command than to debug the WQL query. - -Unless you are returning massive amounts of data -from across bandwidth-constrained remote systems, -it is rarely productive to spend hours trying to -perfect a complicated and convoluted WQL query -when there is a perfectly acceptable Windows -cmdlet that does the same thing, if a bit more +Unless you are returning massive amounts of data from across +bandwidth-constrained remote systems, it is rarely productive to spend hours +trying to perfect a complicated and convoluted WQL query when there is a +perfectly acceptable Windows cmdlet that does the same thing, if a bit more slowly. -# USING THE SELECT STATEMENT - +## USING THE SELECT STATEMENT -A typical WMI query begins with a Select statement -that gets all properties or particular properties -of a WMI class. To select all properties of a WMI -class, use an asterisk (*). The From keyword -specifies the WMI class. +A typical WMI query begins with a Select statement that gets all properties or +particular properties of a WMI class. To select all properties of a WMI class, +use an asterisk (*). The From keyword specifies the WMI class. A Select statement has the following format: +``` Select from +``` -For example, the following Select statement selects -all properties (*) from the instances of the Win32_Bios -WMI class. +For example, the following Select statement selects all properties (*) from +the instances of the Win32_Bios WMI class. +``` Select * from Win32_Bios +``` -To select a particular property of a WMI class, -place the property name between the Select and -From keywords. +To select a particular property of a WMI class, place the property name +between the Select and From keywords. -The following query selects only the name of -the BIOS from the Win32_Bios WMI class. The -command saves the query in the $queryName -variable. +The following query selects only the name of the BIOS from the Win32_Bios WMI +class. The command saves the query in the $queryName variable. +``` Select Name from Win32_Bios +``` -To select more than one property, use commas to -separate the property names. The following WMI -query selects the name and the version of the -Win32_Bios WMI class. The command saves the -query in the $queryNameVersion variable. +To select more than one property, use commas to separate the property names. +The following WMI query selects the name and the version of the Win32_Bios WMI +class. The command saves the query in the $queryNameVersion variable. +``` Select name, version from Win32_Bios +``` -# USING THE WQL QUERY +## USING THE WQL QUERY +There are three ways to use WQL query in Windows PowerShell command. -There are three ways to use WQL query in Windows -PowerShell command. +- Use the Get-WmiObject cmdlet +- Use the Get-CimInstance cmdlet +- Use the [wmisearcher] type accelerator. --- Use the Get-WmiObject cmdlet --- Use the Get-CimInstance cmdlet --- Use the [wmisearcher] type accelerator. +## USING THE GET-WMIOBJECT CMDLET -# USING THE GET-WMIOBJECT CMDLET +The most basic way to use the WQL query is to enclose it in quotation marks +(as a string) and then use the query string as the value of the Query +parameter of the Get-WmiObject cmdlet, as shown in the following example. -The most basic way to use the WQL query is to enclose -it in quotation marks (as a string) and then use the -query string as the value of the Query parameter of -the Get-WmiObject cmdlet, as shown in the following -example. - -PS C:> Get-WmiObject -Query "Select * from Win32_Bios" +```powershell +Get-WmiObject -Query "Select * from Win32_Bios" +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -You can also save the WQL statement in a variable -and then use the variable as the value of the Query -parameter, as shown in the following command. +You can also save the WQL statement in a variable and then use the variable as +the value of the Query parameter, as shown in the following command. -PS C:> $query = "Select * from Win32_Bios" -PS C:> Get-WmiObject -Query $query +```powershell +$query = "Select * from Win32_Bios" +Get-WmiObject -Query $query +``` -You can use either format with any WQL statement. -The following command uses the query in the -$queryName variable to get only the name and -version properties of the system BIOS. +You can use either format with any WQL statement. The following command uses +the query in the $queryName variable to get only the name and version +properties of the system BIOS. -PS C:> $queryNameVersion = "Select Name, Version from Win32_Bios" -PS C:> Get-WmiObject -Query $queryNameVersion - -# __GENUS : 2 +```powershell +$queryNameVersion = "Select Name, Version from Win32_Bios" +Get-WmiObject -Query $queryNameVersion +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS Version : LENOVO - 1360 +``` -Remember that you can use the parameters of the -Get-WmiObject cmdlet to get the same result. For -example, the following command also gets the values -of the Name and Version properties of instances of -the Win32_Bios WMI class. - -PS C:> Get-WmiObject -Class Win32_Bios -Property Name, Version +Remember that you can use the parameters of the Get-WmiObject cmdlet to get +the same result. For example, the following command also gets the values of +the Name and Version properties of instances of the Win32_Bios WMI class. -# __GENUS : 2 +```powershell +Get-WmiObject -Class Win32_Bios -Property Name, Version +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS Version : LENOVO - 1360 +``` -# USING THE GET-CIMINSTANCE CMDLET +## USING THE GET-CIMINSTANCE CMDLET +Beginning in Windows PowerShell 3.0, you can use the Get-CimInstance cmdlet to +run WQL queries. -Beginning in Windows PowerShell 3.0, you can use -the Get-CimInstance cmdlet to run WQL queries. +Get-CimInstance gets instances of CIM-compliant classes, including WMI +classes. The CIM cmdlets, introduced Windows PowerShell 3.0, perform the same +tasks as the WMI cmdlets. The CIM cmdlets comply with WS-Management (WSMan) +standards and with the Common Information Model (CIM) standard, which enables +the cmdlets to use the same techniques to manage Windows computers and +computers that are running other operating systems. -Get-CimInstance gets instances of CIM-compliant -classes, including WMI classes. The CIM cmdlets, -introduced Windows PowerShell 3.0, perform the same -tasks as the WMI cmdlets. The CIM cmdlets comply -with WS-Management (WSMan) standards and with the -Common Information Model (CIM) standard, which enables -the cmdlets to use the same techniques to manage -Windows computers and computers that are running -other operating systems. +The following command uses the Get-CimInstance cmdlet to run a WQL query. -The following command uses the Get-CimInstance -cmdlet to run a WQL query. +Any WQL query that can be used with Get-WmiObject can also be used with +Get-CimInstance. -Any WQL query that can be used with Get-WmiObject -can also be used with Get-CimInstance. - -PS C:> Get-CimInstance -Query "Select * from Win32_Bios" +```powershell +Get-CimInstance -Query "Select * from Win32_Bios" +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -Get-CimInstance returns a CimInstance object, instead of -the ManagementObject that Get-WmiObject returns, but -the objects are quite similar. +Get-CimInstance returns a CimInstance object, instead of the ManagementObject +that Get-WmiObject returns, but the objects are quite similar. -PS C:> (Get-CimInstance -Query "Select * from Win32_Bios").GetType().FullName +``` +(Get-CimInstance -Query "Select * from Win32_Bios").GetType().FullName Microsoft.Management.Infrastructure.CimInstance -PS C:> (Get-WmiObject -Query "Select * from Win32_Bios").GetType().FullName +(Get-WmiObject -Query "Select * from Win32_Bios").GetType().FullName System.Management.ManagementObject +``` -USING THE [wmisearcher] TYPE ACCELERATOR +## USING THE [wmisearcher] TYPE ACCELERATOR -The [wmisearcher] type accelerator creates a -ManagementObjectSearcher object from a WQL -statement string. The ManagementObjectSearcher -object has many properties and methods, but the -most basic method is the Get method, which -invokes the specified WMI query and returns -the resulting objects. +The [wmisearcher] type accelerator creates a ManagementObjectSearcher object +from a WQL statement string. The ManagementObjectSearcher object has many +properties and methods, but the most basic method is the Get method, which +invokes the specified WMI query and returns the resulting objects. -By using the [wmisearcher], you gain easy access -to the ManagementObjectSearcher .NET Framework class. -This lets you query WMI and to configure the way -the query is conducted. +By using the [wmisearcher], you gain easy access to the +ManagementObjectSearcher .NET Framework class. This lets you query WMI and to +configure the way the query is conducted. To use the [wmisearcher] type accelerator: -1. Cast the WQL string into a ManagementObjectSearcher -object. -2. Call the Get method of the ManagementObjectSearcher -object. +1. Cast the WQL string into a ManagementObjectSearcher object. +2. Call the Get method of the ManagementObjectSearcher object. -For example, the following command casts the "select -all" query, saves the result in the $bios variable, -and then calls the Get method of the ManagementObjectSearcher -object in the $bios variable. +For example, the following command casts the "select all" query, saves the +result in the $bios variable, and then calls the Get method of the +ManagementObjectSearcher object in the $bios variable. -PS C:> $bios = [wmisearcher]"Select * from Win32_Bios" -PS C:> $bios.Get() +```powershell +$bios = [wmisearcher]"Select * from Win32_Bios" +$bios.Get() +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -NOTE: Only selected object properties are displayed -by default. These properties are defined in the -Types.ps1xml file. +NOTE: Only selected object properties are displayed by default. These +properties are defined in the Types.ps1xml file. -You can use the [wmisearcher] type accelerator to -cast the query or the variable. In the following -example, the [wmisearcher] type accelerator is -used to cast the variable. The result is the same. +You can use the [wmisearcher] type accelerator to cast the query or the +variable. In the following example, the [wmisearcher] type accelerator is used +to cast the variable. The result is the same. -PS C:> [wmisearcher]$bios = "Select * from Win32_Bios" -PS C:> $bios.Get() +```powershell +[wmisearcher]$bios = "Select * from Win32_Bios" +$bios.Get() +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -When you use the [wmisearcher] type accelerator, it -changes the query string into a ManagementObjectSearcher -object, as shown in the following commands. +When you use the [wmisearcher] type accelerator, it changes the query string +into a ManagementObjectSearcher object, as shown in the following commands. -PS C:> $a = "Select * from Win32_Bios" -PS C:> $a.GetType().FullName +``` +$a = "Select * from Win32_Bios" +$a.GetType().FullName System.String -PS C:> $a = [wmisearcher]"Select * from Win32_Bios" -PS C:> $a.GetType().FullName +$a = [wmisearcher]"Select * from Win32_Bios" +$a.GetType().FullName System.Management.ManagementObjectSearcher +``` -This command format works on any query. The following -command gets the value of the Name property of the -Win32_Bios WMI class. - -PS C:> $biosname = [wmisearcher]"Select Name from Win32_Bios" -PS C:> $biosname.Get() +This command format works on any query. The following command gets the value +of the Name property of the Win32_Bios WMI class. -# __GENUS : 2 +```powershell +$biosname = [wmisearcher]"Select Name from Win32_Bios" +$biosname.Get() +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS +``` -You can perform this operation in a single command, -although the command is a bit more difficult to -interpret. +You can perform this operation in a single command, although the command is a +bit more difficult to interpret. -In this format, you use the [wmisearcher] type -accelerator to cast the WQL query string to a -ManagementObjectSearcher, and then call the Get -method on the object -- all in a single command. -The parentheses () that enclose the casted string -direct Windows PowerShell to cast the string before -calling the method. +In this format, you use the [wmisearcher] type accelerator to cast the WQL +query string to a ManagementObjectSearcher, and then call the Get method on +the object -- all in a single command. The parentheses () that enclose the +casted string direct Windows PowerShell to cast the string before calling the +method. -PS C:> ([wmisearcher]"Select name from Win32_Bios").Get() - -# __GENUS : 2 +```powershell +([wmisearcher]"Select name from Win32_Bios").Get() +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS +``` -# USING THE BASIC WQL WHERE STATEMENT - +## USING THE BASIC WQL WHERE STATEMENT -A Where statement establishes conditions -for the data that a Select statement returns. +A Where statement establishes conditions for the data that a Select statement +returns. The Where statement has the following format: +``` where +``` For example: +``` where Name = 'Notepad.exe' +``` -The Where statement is used with the Select -statement, as shown in the following example. +The Where statement is used with the Select statement, as shown in the +following example. +``` Select * from Win32_Process where Name = 'Notepad.exe' +``` -When using the Where statement, the property name -and value must be accurate. +When using the Where statement, the property name and value must be accurate. -For example, the following command gets the Notepad -processes on the local computer. +For example, the following command gets the Notepad processes on the local +computer. -PS C:> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad.exe'" +```powershell +Get-WmiObject -Query "Select * from Win32_Process where name='Notepad.exe'" +``` -However, the following command fails, because the -process name includes the ".exe" file name -extension. +However, the following command fails, because the process name includes the +".exe" file name extension. -PS C:> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad'" +```powershell +Get-WmiObject -Query "Select * from Win32_Process where name='Notepad'" +``` -# WHERE STATEMENT COMPARISON OPERATORS +## WHERE STATEMENT COMPARISON OPERATORS -The following operators are valid in a -WQL Where statement. +The following operators are valid in a WQL Where statement. +``` Operator Description ----------------------- = Equal @@ -398,334 +370,365 @@ LIKE Wildcard match IS Evaluates null ISNOT Evaluates not null ISA Evaluates a member of a WMI class +``` -There are other operators, but these are the ones -used for making comparisons. +There are other operators, but these are the ones used for making comparisons. -For example, the following query selects the Name -and Priority properties from processes in the -Win32_Process class where the process priority -is greater than or equal to 11. The Get-WmiObject -cmdlet runs the query. +For example, the following query selects the Name and Priority properties from +processes in the Win32_Process class where the process priority is greater +than or equal to 11. The Get-WmiObject cmdlet runs the query. -$highPriority = "Select Name, Priority from Win32_Process where Priority >= 11" +```powershell +$highPriority = "Select Name, Priority from Win32_Process " + + "where Priority >= 11" Get-WmiObject -Query $highPriority +``` -# USING THE WQL OPERATORS IN THE FILTER PARAMETER +## USING THE WQL OPERATORS IN THE FILTER PARAMETER +The WQL operators can also be used in the value of the Filter parameter of the +Get-WmiObject or Get-CimInstance cmdlets, as well as in the value of the Query +parameters of these cmdlets. -The WQL operators can also be used in the value -of the Filter parameter of the Get-WmiObject or -Get-CimInstance cmdlets, as well as in the value -of the Query parameters of these cmdlets. +For example, the following command gets the Name and ProcessID properties of +the last five processes that have ProcessID values greater than 1004. The +command uses the Filter parameter to specify the ProcessID condition. -For example, the following command gets the Name -and ProcessID properties of the last five processes -that have ProcessID values greater than 1004. The -command uses the Filter parameter to specify the -ProcessID condition. - -PS C:> Get-WmiObject -Class Win32_Process ` +```powershell +Get-WmiObject -Class Win32_Process ` -Property Name, ProcessID -Filter "ProcessID >= 1004" | Sort ProcessID | Select Name, ProcessID -Last 5 +``` +```output Name ProcessID ---- --------- SROSVC.exe 4220 -# WINWORD.EXE 4664 - +WINWORD.EXE 4664 TscHelp.exe 4744 SnagIt32.exe 4748 WmiPrvSE.exe 5056 +``` # USING THE LIKE OPERATOR -The Like operator lets you use wildcard characters -to filter the results of a WQL query. +The Like operator lets you use wildcard characters to filter the results of a +WQL query. +``` Like Operator Description -------------------------------------------------- [] Character in a range [a-f] or a set -of characters [abcdef]. The items in -a set do not need to be consecutive or -listed in alphabetical order. + of characters [abcdef]. The items in + a set do not need to be consecutive or + listed in alphabetical order. ^ Character not in a range [^a-f] or -not in a set [^abcdef]. The items in -a set do not need to be consecutive or -listed in alphabetical order. + not in a set [^abcdef]. The items in + a set do not need to be consecutive or + listed in alphabetical order. % A string of zero or more characters _ One character. -(underscore) NOTE: To use a literal underscore -in a query string, enclose it in -square brackets [_]. +(underscore) NOTE: To use a literal underscore + in a query string, enclose it in + square brackets [_]. +``` -When the Like operator is used without any wildcard -characters or range operators, it behaves like the -equality operator (=) and returns objects only +When the Like operator is used without any wildcard characters or range +operators, it behaves like the equality operator (=) and returns objects only when they are an exact match for the pattern. -You can combine the range operation with the percent -wildcard character to create simple, yet powerful -filters. +You can combine the range operation with the percent wildcard character to +create simple, yet powerful filters. -# LIKE OPERATOR EXAMPLES +### LIKE OPERATOR EXAMPLES +#### EXAMPLE 1: [] -EXAMPLE 1: [] -The following commands start Notepad and then -search for an instance of the Win32_Process -class that has a name that starts with a letter -between "H" and "N" (case-insensitive). +The following commands start Notepad and then search for an instance of the +Win32_Process class that has a name that starts with a letter between "H" and +"N" (case-insensitive). -The query should return any process from Hotpad.exe -through Notepad.exe. +The query should return any process from Hotpad.exe through Notepad.exe. -PS C:> Notepad # Starts Notepad -PS C:> $query = "Select * from win32_Process where Name LIKE '[H-N]otepad.exe'" -PS C:> Get-WmiObject -Query $query | Select Name, ProcessID +```powershell +Notepad # Starts Notepad +$query = "Select * from win32_Process where Name LIKE '[H-N]otepad.exe'" +Get-WmiObject -Query $query | Select Name, ProcessID +``` +```output Name ProcessID ---- --------- notepad.exe 1740 +``` + +#### EXAMPLE 2: [] and % -EXAMPLE 2: [] and % -The following commands select all process -that have a name that begins with a letter between -A and P (case-insensitive) followed by zero or more -letters in any combination. +The following commands select all process that have a name that begins with a +letter between A and P (case-insensitive) followed by zero or more letters in +any combination. -The Get-WmiObject cmdlet runs the query, the -Select-Object cmdlet gets the Name and ProcessID -properties, and the Sort-Object cmdlet sorts the -results in alphabetical order by name. +The Get-WmiObject cmdlet runs the query, the Select-Object cmdlet gets the +Name and ProcessID properties, and the Sort-Object cmdlet sorts the results in +alphabetical order by name. -PS C:> $query = "Select * from win32_Process where name LIKE '[A-P]%'" -PS C:> Get-WmiObject -Query $query | +```powershell +$query = "Select * from win32_Process where name LIKE '[A-P]%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID | Sort-Object -Property Name +``` -EXAMPLE 3: Not in Range (^) -The following command gets processes whose names -do not begin with any of the following letters: -# A, S, W, P, R, C, U, N +#### EXAMPLE 3: Not in Range (^) + +The following command gets processes whose names do not begin with any of the +following letters: A, S, W, P, R, C, U, N and followed zero or more letters. -PS C:> $query = "Select * from win32_Process where name LIKE '[^ASWPRCUN]%'" -PS C:> Get-WmiObject -Query $query | +```powershell +$query = "Select * from win32_Process where name LIKE '[^ASWPRCUN]%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID | Sort-Object -Property Name +``` + +#### EXAMPLE 4: Any characters -- or none (%) -EXAMPLE 4: Any characters -- or none (%) -The following commands get processes that have -names that begin with "calc". The % symbol in -WQL is equivalent to the asterisk (*) symbol in -regular expressions. +The following commands get processes that have names that begin with "calc". +The % symbol in WQL is equivalent to the asterisk (*) symbol in regular +expressions. -PS C:> $query = "Select * from win32_Process where Name LIKE 'calc%'" -PS C:> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +```powershell +$query = "Select * from win32_Process where Name LIKE 'calc%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +``` +```output Name ProcessID ---- --------- calc.exe 4424 +``` -EXAMPLE 5: One character (_) -The following commands get processes that -have names that have the following pattern, -"c_lc.exe" where the underscore character -represents any one character. This pattern -matches any name from calc.exe through -czlc.exe, or c9lc.exe, but does not match -names in which the "c" and "l" are separated -by more than one character. +#### EXAMPLE 5: One character (_) -PS C:> $query = "Select * from Win32_Process where Name LIKE 'c_lc.exe'" -PS C:> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +The following commands get processes that have names that have the following +pattern, "c_lc.exe" where the underscore character represents any one +character. This pattern matches any name from calc.exe through czlc.exe, or +c9lc.exe, but does not match names in which the "c" and "l" are separated by +more than one character. +```powershell +$query = "Select * from Win32_Process where Name LIKE 'c_lc.exe'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +``` + +```output Name ProcessID ---- --------- calc.exe 4424 +``` + +#### EXAMPLE 6: Exact match -EXAMPLE 6: Exact match -The following commands get processes named -WLIDSVC.exe. Even though the query uses the -Like keyword, it requires an exact match, -because the value does not include any -wildcard characters. +The following commands get processes named WLIDSVC.exe. Even though the query +uses the Like keyword, it requires an exact match, because the value does not +include any wildcard characters. +```powershell $query = "Select * from win32_Process where name LIKE 'WLIDSVC.exe'" Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +```powershell +```output Name ProcessID ---- --------- WLIDSVC.exe 84 +``` -# USING THE OR OPERATOR +## USING THE OR OPERATOR -To specify multiple independent conditions, use the Or -keyword. The Or keyword appears in the Where clause. It -performs an inclusive OR operation on two (or more) -conditions and returns items that meet any of the -conditions. +To specify multiple independent conditions, use the Or keyword. The Or keyword +appears in the Where clause. It performs an inclusive OR operation on two (or +more) conditions and returns items that meet any of the conditions. The Or operator has the following format: +``` Where or ... +``` -For example, the following commands get all instances -of the Win32_Process WMI class but returns them -only if the process name is winword.exe or excel.exe. +For example, the following commands get all instances of the Win32_Process WMI +class but returns them only if the process name is winword.exe or excel.exe. -PS C:> $q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe'" -PS C:> Get-WmiObject -Query $q +```powershell +$q = "Select * from Win32_Process where Name='winword.exe'" + + " or Name='excel.exe'" +Get-WmiObject -Query $q +``` -The Or statement can be used with more than two -conditions. In the following query, the Or statement -gets Winword.exe, Excel.exe, or Powershell.exe. +The Or statement can be used with more than two conditions. In the following +query, the Or statement gets Winword.exe, Excel.exe, or Powershell.exe. -$q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe' or Name = 'powershell.exe'" +```powershell +$q = "Select * from Win32_Process where Name='winword.exe'" + + " or Name='excel.exe' or Name='powershell.exe'" +``` -# USING THE AND OPERATOR +## USING THE AND OPERATOR -To specify multiple related conditions, use the And -keyword. The And keyword appears in the Where clause. It -returns items that meet all of the conditions. +To specify multiple related conditions, use the And keyword. The And keyword +appears in the Where clause. It returns items that meet all of the conditions. The And operator has the following format: +``` Where and ... +``` -For example, the following commands get processes -that have a name of "Winword.exe" and the process -ID of 6512. +For example, the following commands get processes that have a name of +"Winword.exe" and the process ID of 6512. Note that the commands use the Get-CimInstance cmdlet. -PS C:> $q = "Select * from Win32_Process where Name = 'winword.exe' and ProcessID =6512" -PS C:> Get-CimInstance -Query $q - -ProcessId Name HandleCount WorkingSetSize VirtualSize ---------- ---- ----------- -------------- ----------- -# 6512 WINWORD.EXE 768 117170176 633028608 +```powershell +$q = "Select * from Win32_Process where Name = 'winword.exe' " + + "and ProcessID =6512" +Get-CimInstance -Query $q +``` +```output +ProcessId Name HandleCount WorkingSetSize VirtualSize +--------- ---- ----------- -------------- ----------- +# 6512 WINWORD.EXE 768 117170176 633028608 +``` -All operators, including the Like operators are -valid with the Or and And operators. And, you can -combine the Or and And operators in a single query -with parentheses that tell Windows PowerShell which -clauses to process first. +All operators, including the Like operators are valid with the Or and And +operators. And, you can combine the Or and And operators in a single query +with parentheses that tell Windows PowerShell which clauses to process first. -This command uses the Windows PowerShell continuation -character (`) divide the command into two lines. +This command uses the Windows PowerShell continuation character (`) divide the +command into two lines. -PS C:> $q = "Select * from Win32_Process ` +```powershell +$q = "Select * from Win32_Process ` where (Name = 'winword.exe' or Name = 'excel.exe') and HandleCount > 700" +Get-CimInstance -Query $q +``` -PS C:> Get-CimInstance -Query $q -ProcessId Name HandleCount WorkingSetSize VirtualSize ---------- ---- ----------- -------------- ----------- -# 6512 WINWORD.EXE 797 117268480 634425344 +```output +ProcessId Name HandleCount WorkingSetSize VirtualSize +--------- ---- ----------- -------------- ----------- + 6512 WINWORD.EXE 797 117268480 634425344 + 9610 EXCEL.EXE 727 38858752 323227648 +``` -# 9610 EXCEL.EXE 727 38858752 323227648 +## SEARCHING FOR NULL VALUES +Searching for null values in WMI is challenging, because it can lead to +unpredictable results. Null is not zero and it is not equivalent or to an +empty string. Some WMI class properties are initialized and others are not, so +a search for null might not work for all properties. -# SEARCHING FOR NULL VALUES +To search for null values, use the Is operator with a value of "null". -Searching for null values in WMI is challenging, -because it can lead to unpredictable results. Null -is not zero and it is not equivalent or to an empty -string. Some WMI class properties are initialized and -others are not, so a search for null might not work -for all properties. +For example, the following commands get processes that have a null value for +the IntallDate property. The commands return many processes. -To search for null values, use the Is operator with -a value of "null". +```powershell +$q = "Select * from Win32_Process where InstallDate is null" +Get-WmiObject -Query $q +``` -For example, the following commands get processes -that have a null value for the IntallDate property. -The commands return many processes. +In contrast, the following command, gets user accounts that have a null value +for the Description property. This command does not return any user accounts, +even though most user accounts do not have any value for the Description +property. -PS C:> $q = "Select * from Win32_Process where InstallDate is null" -PS C:> Get-WmiObject -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Description is null" +Get-WmiObject -Query $q +``` -In contrast, the following command, gets user -accounts that have a null value for the Description -property. This command does not return any user -accounts, even though most user accounts do not have -any value for the Description property. - -PS C:> $q = "Select * from Win32_UserAccount where Description is null" -PS C:> Get-WmiObject -Query $q - -To find the user accounts that have no value for -the Description property, use the equality operator -to get an empty string. To represent the empty string, +To find the user accounts that have no value for the Description property, use +the equality operator to get an empty string. To represent the empty string, use two consecutive single quotation marks. +```powershell $q = "Select * from Win32_UserAccount where Description = '' " +``` -# USING TRUE OR FALSE +## USING TRUE OR FALSE -To get Boolean values in the properties of WMI -objects, use True and False. They are not case -sensitive. +To get Boolean values in the properties of WMI objects, use True and False. +They are not case sensitive. -The following WQL query returns only local user -accounts from a domain joined computer. +The following WQL query returns only local user accounts from a domain joined +computer. -PS C:> $q = "Select * from Win32_UserAccount where LocalAccount = True" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where LocalAccount = True" +Get-CimInstance -Query $q +``` + +To find domain accounts, use a value of False, as shown in the following +example. -To find domain accounts, use a value of False, -as shown in the following example. +```powershell +$q = "Select * from Win32_UserAccount where LocalAccount = False" +Get-CimInstance -Query $q +``` -PS C:> $q = "Select * from Win32_UserAccount where LocalAccount = False" -PS C:> Get-CimInstance -Query $q +## USING THE ESCAPE CHARACTER -# USING THE ESCAPE CHARACTER +WQL uses the backslash (\) as its escape character. This is different from +Windows PowerShell, which uses the backtick character (`). -WQL uses the backslash () as its escape -character. This is different from Windows -PowerShell, which uses the backtick -character (`). +Quotation marks, and the characters used for quotation marks, often need to be +escaped so that they are not misinterpreted. -Quotation marks, and the characters used for -quotation marks, often need to be escaped so -that they are not misinterpreted. +To find a user whose name includes a single quotation mark, use a backslash to +escape the single quotation mark, as shown in the following command. -To find a user whose name includes a single quotation -mark, use a backslash to escape the single quotation -mark, as shown in the following command. +```powershell +$q = "Select * from Win32_UserAccount where Name = 'Tim O\'Brian'" +Get-CimInstance -Query $q +``` -PS C:> $q = "Select * from Win32_UserAccount where Name = 'Tim O\'Brian'" -PS C:> Get-CimInstance -Query $q +```output Name Caption AccountType SID Domain ---- ------- ----------- --- ------ Tim O'Brian FABRIKAM\TimO 512 S-1-5-21-1457... FABRIKAM +``` -In some case, the backslash also needs to be -escaped. For example, the following commands -generate an Invalid Query error due to the -backslash in the Caption value. +In some case, the backslash also needs to be escaped. For example, the +following commands generate an Invalid Query error due to the backslash in the +Caption value. -PS C:> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" +Get-CimInstance -Query $q +``` + +```output Get-CimInstance : Invalid query At line:1 char:1 + Get-CimInstance -Query $q -# +!INCLUDE[]~~~~~~~~~~~ - -+ CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimException -+ FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastructure.CimCmdlets ++ ~~~~~~~~~~~ + + CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimExcep + + FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastr +``` -To escape the backslash, use a second backslash -character, as shown in the following command. +To escape the backslash, use a second backslash character, as shown in the +following command. -PS C:> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\\TimO'" +Get-CimInstance -Query $q +``` # SEE ALSO @@ -736,4 +739,3 @@ PS C:> Get-CimInstance -Query $q [about_WMI](about_WMI.md) [about_WMI_Cmdlets](about_WMI_Cmdlets.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md index 52e7e3216836..1c09f4504b20 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,108 +7,104 @@ title: about_Windows_PowerShell_ISE --- # About Windows PowerShell ISE -## about_Windows_PowerShell_ISE - - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes the features and system requirements of Windows PowerShell Integrated Scripting Environment (ISE). -# LONG DESCRIPTION +## LONG DESCRIPTION -Windows PowerShell ISE is a graphical host application for Windows -PowerShell. In Windows PowerShell ISE, you can run commands and write, -test, and debug scripts in a single Windows-based graphical user -interface. Its features include Intellisense, multiline editing, tab -completion, auto-save, syntax coloring, selective execution, -context-sensitive help, Show Command (compose commands in a window) -and support for double-byte character sets and right-to-left languages. +Windows PowerShell ISE is a graphical host application for Windows PowerShell. +In Windows PowerShell ISE, you can run commands and write, test, and debug +scripts in a single Windows-based graphical user interface. Its features +include Intellisense, multiline editing, tab completion, auto-save, syntax +coloring, selective execution, context-sensitive help, Show Command (compose +commands in a window) and support for double-byte character sets and +right-to-left languages. -Windows PowerShell ISE is an excellent tool for beginners. The Show -Command window and New Remote PowerShell Tab guide you through tasks -so that you can be successful on the first try. Snippets and error -indicators help you learn the Windows PowerShell language as you work. +Windows PowerShell ISE is an excellent tool for beginners. The Show Command +window and New Remote PowerShell Tab guide you through tasks so that you can +be successful on the first try. Snippets and error indicators help you learn +the Windows PowerShell language as you work. -Advanced users can take advantage of the sophisticated debugging -features, add-ons, and the Windows PowerShell ISE object model. +Advanced users can take advantage of the sophisticated debugging features, +add-ons, and the Windows PowerShell ISE object model. What's New in Windows PowerShell ISE in Windows PowerShell 4.0 -Windows PowerShell ISE introduces two new features in Windows -PowerShell 4.0. +Windows PowerShell ISE introduces two new features in Windows PowerShell 4.0. --- Windows PowerShell ISE now supports both Windows PowerShell -Workflow debugging and remote script debugging. For more -Information, see about_Debuggers. --- IntelliSense support has been added for Windows PowerShell Desired -State Configuration providers and configurations. +- Windows PowerShell ISE now supports both Windows PowerShell Workflow + debugging and remote script debugging. For more Information, see + about_Debuggers. -Starting Windows PowerShell ISE +- IntelliSense support has been added for Windows PowerShell Desired State + Configuration providers and configurations. + +## Starting Windows PowerShell ISE Windows PowerShell ISE is installed, enabled, and ready to use in all supported versions of Windows. -- In Windows 8.1, Windows 8, Windows Server 2012 R2, and Windows Server -2012, on the Start screen, type PowerShell_ISE, and then click -PowerShell_ISE or Windows PowerShell ISE. +- In Windows 8.1, Windows 8, Windows Server 2012 R2, and Windows Server 2012, + on the Start screen, type PowerShell_ISE, and then click PowerShell_ISE or + Windows PowerShell ISE. -- In Windows Server 2012 R2 and Windows Server 2012, in Server Manager, -on the Tools menu, click Windows PowerShell ISE. +- In Windows Server 2012 R2 and Windows Server 2012, in Server Manager, on the + Tools menu, click Windows PowerShell ISE. - In earlier versions of Windows, click Start, All Programs, Accessories, -Windows PowerShell, and then click Windows PowerShell ISE. + Windows PowerShell, and then click Windows PowerShell ISE. -- In a Windows PowerShell console, Cmd.exe, or the Run or Search box -in Windows, type "PowerShell_ise.exe". You can also use the command-line -parameters, including the NoProfile switch. For more information, see -PowerShell_ISE.exe Console Help -(http://go.microsoft.com/fwlink/?LinkId=243055). +- In a Windows PowerShell console, Cmd.exe, or the Run or Search box in + Windows, type "PowerShell_ise.exe". You can also use the command-line + parameters, including the NoProfile switch. For more information, see + [PowerShell_ISE.exe Console Help](http://go.microsoft.com/fwlink/?LinkId=243055). -Running Interactive Commands +## Running Interactive Commands -You can run any Windows PowerShell expression or command in Windows -PowerShell ISE. You can use cmdlets, providers, snap-ins, and modules as -you would use them in the Windows PowerShell console. +You can run any Windows PowerShell expression or command in Windows PowerShell +ISE. You can use cmdlets, providers, snap-ins, and modules as you would use +them in the Windows PowerShell console. You can type or paste interactive commands in the Console pane. To run the commands, you can use buttons, menu items, and keyboard shortcuts. -You can use the multiline editing feature to type or paste several lines -of code into the Console pane at once. When you press the UP ARROW key to -recall the previous command, all the lines in the command are recalled. -When you type commands, press SHIFT+ENTER to make a new blank line appear -under the current line. +You can use the multiline editing feature to type or paste several lines of +code into the Console pane at once. When you press the UP ARROW key to recall +the previous command, all the lines in the command are recalled. When you type +commands, press SHIFT+ENTER to make a new blank line appear under the current +line. -Viewing Output +## Viewing Output -The results of commands and scripts are displayed in the Console pane. You -can move or copy the results from the Console pane by using keyboard -shortcuts or the Copy button on the toolbar, and you can paste the results -in the Script pane or Console panes or other programs. To clear the Console -pane, click the "Clear Output Pane" button or type one of the following -commands: +The results of commands and scripts are displayed in the Console pane. You can +move or copy the results from the Console pane by using keyboard shortcuts or +the Copy button on the toolbar, and you can paste the results in the Script +pane or Console panes or other programs. To clear the Console pane, click the +"Clear Output Pane" button or type one of the following commands: +``` Clear-Host cls +``` -Writing Scripts and Functions +## Writing Scripts and Functions -In the Script pane, you can open, compose, edit, and run scripts. The -Script pane lets you edit scripts by using buttons and keyboard shortcuts. -You can also copy, cut, and paste text between the Script pane and the -Console pane. +In the Script pane, you can open, compose, edit, and run scripts. The Script +pane lets you edit scripts by using buttons and keyboard shortcuts. You can +also copy, cut, and paste text between the Script pane and the Console pane. -You can use the selective run feature to run all or part of a script. To -run part of a script, select the text you want to run, and then click the -Run Selection button or press F8. By default, F8 runs the current line. +You can use the selective run feature to run all or part of a script. To run +part of a script, select the text you want to run, and then click the Run +Selection button or press F8. By default, F8 runs the current line. Advanced editing features include brace-matching, expand-collapse, line numbers, error indicators, block editing and indenting, rich copy, and case conversion. -Getting Help +## Getting Help Windows PowerShell ISE includes help topics that describe its use. In addition, all installed help files are accessible from the Script and Command @@ -116,101 +112,99 @@ panes. Windows PowerShell ISE also supports context-sensitive help. To get help about a particular cmdlet, provider, or keyword, place the cursor in the name of the -item and press F1. To search the help topics, press F1 and type the search term. +item and press F1. To search the help topics, press F1 and type the search +term. To update the help topics on the computer, use the Update Windows PowerShell -Help item in the Help menu. This item updates help for the modules in the current -session in the current UI culture. It is equivalent to running the Update-Help -cmdlet without parameters. To update help for the cmdlets that come with Windows -PowerShell, start Windows PowerShell ISE with the "Run as administrator" option. +Help item in the Help menu. This item updates help for the modules in the +current session in the current UI culture. It is equivalent to running the +Update-Help cmdlet without parameters. To update help for the cmdlets that +come with Windows PowerShell, start Windows PowerShell ISE with the "Run as +administrator" option. You can also use the Get-Help, Save-Help, and Update-Help cmdlets in Windows PowerShell ISE, just as you use it in the Windows PowerShell console. However, in Windows PowerShell ISE, the Help function displays the entire help topic, -not one page at a time. +not one page at a time. -Debugging Scripts +## Debugging Scripts -You can use the Windows PowerShell ISE debugger to debug a Windows -PowerShell script or function. When you debug a script, you can use menu -items and shortcut keys to perform many of the same tasks that you would -perform in the Windows PowerShell console. For example, to set a line -breakpoint in a script, right-click the line of code, and then click -Toggle Breakpoint. +You can use the Windows PowerShell ISE debugger to debug a Windows PowerShell +script or function. When you debug a script, you can use menu items and +shortcut keys to perform many of the same tasks that you would perform in the +Windows PowerShell console. For example, to set a line breakpoint in a script, +right-click the line of code, and then click Toggle Breakpoint. -As you step through a script while debugging, the debugging highlighter -shows precisely which part of the command is running and automatically -opens files that include called functions and scripts. +As you step through a script while debugging, the debugging highlighter shows +precisely which part of the command is running and automatically opens files +that include called functions and scripts. -By default, the Toggle Breakpoint menu item sets a breakpoint on an -entire line in a script, but you can set a breakpoint on a variable -or command name. You can also set a breakpoint on a command by line -and column number, making it easier to debug long pipeline commands. +By default, the Toggle Breakpoint menu item sets a breakpoint on an entire +line in a script, but you can set a breakpoint on a variable or command name. +You can also set a breakpoint on a command by line and column number, making +it easier to debug long pipeline commands. -Often, you can debug syntax errors in a script just by opening the -script file in Windows PowerShell ISE. The error indicators identify -syntax errors and the outlining features let you collapse parts of the -script to focus on trouble spots. +Often, you can debug syntax errors in a script just by opening the script file +in Windows PowerShell ISE. The error indicators identify syntax errors and the +outlining features let you collapse parts of the script to focus on trouble +spots. -You can also use the Windows PowerShell debugger cmdlets in the Command -pane just as you would use them in the console. +You can also use the Windows PowerShell debugger cmdlets in the Command pane +just as you would use them in the console. -Running Remote Commands +## Running Remote Commands -The New Remote PowerShell Tab feature makes it easy to establish a -persistent user-managed Windows PowerShell session ("PSSession") to -the local computer or a remote computer. The command opens a pop-up -window that prompts you for a computer name and for the user account -that has permission to run commands on the remote computer. +The New Remote PowerShell Tab feature makes it easy to establish a persistent +user-managed Windows PowerShell session ("PSSession") to the local computer or +a remote computer. The command opens a pop-up window that prompts you for a +computer name and for the user account that has permission to run commands on +the remote computer. -Customizing the View +## Customizing the View -You can use Windows PowerShell ISE features to move and to resize the -Console pane and the Script pane. You can show and hide either pane, -and you can change the text size in all the panes. +You can use Windows PowerShell ISE features to move and to resize the Console +pane and the Script pane. You can show and hide either pane, and you can +change the text size in all the panes. -You can also use the Options window to customize the appearance and -operation of Windows PowerShell ISE. In addition, Windows PowerShell -ISE has a custom host variable, $psISE, that you can use to customize -Windows PowerShell ISE, including adding menus and menu items. +You can also use the Options window to customize the appearance and operation +of Windows PowerShell ISE. In addition, Windows PowerShell ISE has a custom +host variable, $psISE, that you can use to customize Windows PowerShell ISE, +including adding menus and menu items. -Windows PowerShell ISE Profile +## Windows PowerShell ISE Profile Windows PowerShell ISE has its own Windows PowerShell profile, -Microsoft.PowerShellISE_profile.ps1. In this profile, you can store -functions, aliases, variables, and commands that you use in Windows -PowerShell ISE. +Microsoft.PowerShellISE_profile.ps1. In this profile, you can store functions, +aliases, variables, and commands that you use in Windows PowerShell ISE. -Items in the Windows PowerShell AllHosts profiles (CurrentUser\AllHosts -and AllUsers\AllHosts) are also available in Windows PowerShell ISE, just -as they are in any Windows PowerShell host program. However, the items -in your Windows PowerShell console profiles are not available in Windows -PowerShell ISE. +Items in the Windows PowerShell AllHosts profiles (CurrentUser\\AllHosts and +AllUsers\\AllHosts) are also available in Windows PowerShell ISE, just as they +are in any Windows PowerShell host program. However, the items in your Windows +PowerShell console profiles are not available in Windows PowerShell ISE. Instructions for moving and reconfiguring your profiles are available in Windows PowerShell ISE Help and in about_Profiles. -# NOTES +## NOTES -Windows PowerShell ISE is an optional Windows Feature that is turned on -by default on client and server versions of Windows. To enable and disable +Windows PowerShell ISE is an optional Windows Feature that is turned on by +default on client and server versions of Windows. To enable and disable Windows PowerShell ISE in client versions of Windows, use Turn Windows -Features On or Off in Control Panel. To enable and disable Windows -PowerShell ISE in server versions of Windows, use the Add Roles -and Features Wizard in Server Manager. - -Because Windows PowerShell ISE requires a user interface, it does not work -on Server Core installations of Windows Server. However, if you add the -Windows PowerShell ISE feature, the installation automatically converts -to Server with a GUI. - -Windows PowerShell ISE is built on the Windows Presentation Foundation -(WPF). If the graphical elements of Windows PowerShell ISE do not render -correctly on your system, you might resolve the problem by adding or -adjusting the "Disable WPF Hardware acceleration" graphics rendering -settings on your system. For more information, see "Graphics Rendering -Registry Settings" in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=144711. +Features On or Off in Control Panel. To enable and disable Windows PowerShell +ISE in server versions of Windows, use the Add Roles and Features Wizard in +Server Manager. + +Because Windows PowerShell ISE requires a user interface, it does not work on +Server Core installations of Windows Server. However, if you add the Windows +PowerShell ISE feature, the installation automatically converts to Server with +a GUI. + +Windows PowerShell ISE is built on the Windows Presentation Foundation (WPF). +If the graphical elements of Windows PowerShell ISE do not render correctly on +your system, you might resolve the problem by adding or adjusting the "Disable +WPF Hardware acceleration" graphics rendering settings on your system. For +more information, see [Graphics Rendering Registry Settings](http://go.microsoft.com/fwlink/?LinkId=144711) +in the MSDN library. # SEE ALSO @@ -220,17 +214,16 @@ http://go.microsoft.com/fwlink/?LinkId=144711. [about_Updatable_Help](about_Updatable_Help.md) -Get-Help - -Get-IseSnippet +[Get-Help](../Get-Help.md) -Import-IseSnippet +[Get-IseSnippet](../../ISE/Get-IseSnippet.md) -New-IseSnippet +[Import-IseSnippet](../../ISE/Import-IseSnippet.md) -Save-Help +[New-IseSnippet](../../ISE/New-IseSnippet.md) -Show-Command +[Save-Help](../Save-Help.md) -Update-Help +[Show-Command](../../Microsoft.PowerShell.Utility/Show-Command.md) +[Update-Help](../Update-Help.md) \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md index ad65ab0c16fe..26c1585936bf 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,48 +7,60 @@ title: about_Windows_RT --- # About Windows RT -## about_Windows_RT - ## SHORT DESCRIPTION -Explains limitations of Windows PowerShell® 4.0 on Windows RT 8.1. +Explains limitations of Windows PowerShell® 4.0 on Windows RT 8.1. ## LONG DESCRIPTION -The Windows RT 8.1 operating system is installed on computers and devices (such as Microsoft Surface 2, on which it is the operating system that ships with the computer) that use Advanced RISC Machine (ARM) processors. - -Windows PowerShell 4.0 is included in Windows RT 8.1. All cmdlets, providers, and modules, and most scripts designed for Windows PowerShell 2.0 and later releases run on Windows RT 8.1 without changes. - -Because Windows RT 8.1 does not include all Windows features, some Windows PowerShell features work differently or do not work on Windows RT-based devices. The following list explains the differences. - --- Windows PowerShell ISE is not included in and cannot run on Windows RT 8.1. Windows PowerShell ISE requires Windows Presentation Foundation, which is not included in Windows RT 8.1. --- Windows PowerShell remoting and the WinRM service are disabled by default. To enable remoting, run the Enable-PSRemoting cmdlet. Also, run the Set-Service cmdlet to set the startup type of the WinRM service to Automatic, or Automatic (Delayed Start). +The Windows RT 8.1 operating system is installed on computers and devices +(such as Microsoft Surface 2, on which it is the operating system that ships +with the computer) that use Advanced RISC Machine (ARM) processors. -While remoting is disabled, you can use Windows PowerShell remoting to run commands on other computers, but other computers cannot run commands on the Windows RT device. Also, implicit remoting—that is, remoting that is built in to a cmdlet or script, and not explicitly requested with added parameters—does not work in Windows PowerShell running on Windows RT 8.1. +Windows PowerShell 4.0 is included in Windows RT 8.1. All cmdlets, providers, +and modules, and most scripts designed for Windows PowerShell 2.0 and later +releases run on Windows RT 8.1 without changes. --- Domain-joined computing and Kerberos authentication are not supported on Windows RT 8.1. You cannot use Windows PowerShell to add or manage these features. +Because Windows RT 8.1 does not include all Windows features, some Windows +PowerShell features work differently or do not work on Windows RT-based +devices. The following list explains the differences. --- Microsoft .NET Framework classes that are not supported on Windows RT 8.1 are also not supported by Windows PowerShell on Windows RT 8.1. +- Windows PowerShell ISE is not included in and cannot run on Windows RT 8.1. + Windows PowerShell ISE requires Windows Presentation Foundation, which is not + included in Windows RT 8.1. --- Transactions are not enabled on Windows RT 8.1. Transaction cmdlets, such as Start-Transaction, and transaction parameters, such as UseTransaction, do not work properly. +- Windows PowerShell remoting and the WinRM service are disabled by default. + To enable remoting, run the Enable-PSRemoting cmdlet. Also, run the + Set-Service cmdlet to set the startup type of the WinRM service to Automatic, + or Automatic (Delayed Start). --- All Windows PowerShell sessions on Windows RT 8.1 devices use the ConstrainedLanguage language mode. ConstrainedLanguage language mode is a companion to User Mode Code Integrity (UMCI). It permits all Windows cmdlets and Windows PowerShell language elements, but restricts types to ensure that users cannot use Windows PowerShell to circumvent or violate the UMCI protections. + While remoting is disabled, you can use Windows PowerShell remoting to run + commands on other computers, but other computers cannot run commands on the + Windows RT device. Also, implicit remoting—that is, remoting that is built in + to a cmdlet or script, and not explicitly requested with added parameters—does + not work in Windows PowerShell running on Windows RT 8.1. -For more information about ConstrainedLanguage language mode, see about_Language_Modes. +- Domain-joined computing and Kerberos authentication are not supported on + Windows RT 8.1. You cannot use Windows PowerShell to add or manage these + features. +- Microsoft .NET Framework classes that are not supported on Windows RT 8.1 + are also not supported by Windows PowerShell on Windows RT 8.1. -## KEYWORDS -about_ARM +- Transactions are not enabled on Windows RT 8.1. Transaction cmdlets, such + as Start-Transaction, and transaction parameters, such as UseTransaction, do + not work properly. -about_PowerShell_on_ARM - -about_PowerShell_on_Surface - -about_Windows_RT_8.1 - -about_WindowsRT +- All Windows PowerShell sessions on Windows RT 8.1 devices use the + ConstrainedLanguage language mode. ConstrainedLanguage language mode is a + companion to User Mode Code Integrity (UMCI). It permits all Windows cmdlets + and Windows PowerShell language elements, but restricts types to ensure that + users cannot use Windows PowerShell to circumvent or violate the UMCI + protections. +For more information about ConstrainedLanguage language mode, see +[about_Language_Modes](about_Language_Modes.md). ## SEE ALSO @@ -57,8 +69,3 @@ about_WindowsRT [about_Remote](about_Remote.md) [about_Windows_PowerShell_ISE](about_Windows_PowerShell_ISE.md) - -about_Workflows - -Windows PowerShell System Requirements: http://technet.microsoft.com/library/hh857337.aspx - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_logical_operators.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_logical_operators.md index cafeedc3d3f5..7d9280a26f85 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_logical_operators.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_logical_operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,13 +14,13 @@ Describes the operators that connect statements in PowerShell. ## LONG DESCRIPTION -The PowerShell logical operators connect expressions and statements, -allowing you to use a single expression to test for multiple conditions. +The PowerShell logical operators connect expressions and statements, allowing +you to use a single expression to test for multiple conditions. -For example, the following statement uses the and operator and the or -operator to connect three conditional statements. The statement is true -only when the value of $a is greater than the value of $b, and either $a or -$b is less than 20. +For example, the following statement uses the and operator and the or operator +to connect three conditional statements. The statement is true only when the +value of $a is greater than the value of $b, and either $a or $b is less than +20. ```powershell ($a -gt $b) -and (($a -lt 20) -or ($b -lt 20)) @@ -28,38 +28,43 @@ $b is less than 20. PowerShell supports the following logical operators. -|Operator|Description|Example| -|---|---|---| -|`-and`|Logical and. TRUE only when both statements are TRUE.|`(1 -eq 1) -and (1 -eq 2)`
`False`| -|`-or`|Logical or. TRUE when either or both statements are TRUE.|`(1 -eq 1) -or (1 -eq 2)`
`True`| -|`-xor`|Logical exclusive or. TRUE only when one of the statements is TRUE and the other is FALSE.|`(1 -eq 1) -xor (2 -eq 2)`
`False`| -|`-not`|Logical not. Negates the statement that follows it.|`-not (1 -eq 1)`
`False`| -|`!`|Logical not. Negates the statement that follows it. (Same as -not)|`!(1 -eq 1)`
`False`| +|Operator|Description |Example | +|--------|-----------------------------------|--------------------------| +|`-and` |Logical AND. TRUE when both |`(1 -eq 1) -and (1 -eq 2)`| +| |statements are TRUE. |`False` | +|`-or` |Logical OR. TRUE when either |`(1 -eq 1) -or (1 -eq 2)` | +| |statement is TRUE. |`True` | +|`-xor` |Logical EXCLUSIVE OR. TRUE when |`(1 -eq 1) -xor (2 -eq 2) | +| |only one statement is TRUE |`False` | +|`-not` |Logical not. Negates the statement |`-not (1 -eq 1)` | +| |that follows. |`False` | +|`!` |Same as `-not` |`!(1 -eq 1)` | +| | |`False` | Note: - The previous examples also use the equal to comparison operator `-eq`. For - more information, see about_Comparison_Operators. The examples also use - the Boolean values of integers. The integer 0 has a value of FALSE. All - other integers have a value of TRUE. +The previous examples also use the equal to comparison operator `-eq`. For +more information, see +[about_Comparison_Operators](about_Comparison_Operators.md). The examples also +use the Boolean values of integers. The integer 0 has a value of FALSE. All +other integers have a value of TRUE. - The syntax of the logical operators is as follows: +The syntax of the logical operators is as follows: -```powershell +``` {-AND | -OR | -XOR} {! | -NOT} ``` - Statements that use the logical operators return Boolean (TRUE or FALSE) - values. +Statements that use the logical operators return Boolean (TRUE or FALSE) +values. - The PowerShell logical operators evaluate only the statements required to - determine the truth value of the statement. If the left operand in a - statement that contains the and operator is FALSE, the right operand is - not evaluated. If the left operand in a statement that contains the or - statement is TRUE, the right operand is not evaluated. As a result, you - can use these statements in the same way that you would use the If - statement. +The PowerShell logical operators evaluate only the statements required to +determine the truth value of the statement. If the left operand in a statement +that contains the and operator is FALSE, the right operand is not evaluated. +If the left operand in a statement that contains the or statement is TRUE, the +right operand is not evaluated. As a result, you can use these statements in +the same way that you would use the If statement. ## SEE ALSO diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_scopes.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_scopes.md index caab8e08c0de..92f18f04064d 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_scopes.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_scopes.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-08 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,118 +7,108 @@ title: about_scopes --- # About Scopes -## about_Scopes - about_Scopes -# SHORT DESCRIPTION +## SHORT DESCRIPTION -Explains the concept of scope in Windows PowerShell and shows how to set -and change the scope of elements. +Explains the concept of scope in PowerShell and shows how to set and change +the scope of elements. -# LONG DESCRIPTION +## LONG DESCRIPTION -Windows PowerShell protects access to variables, aliases, functions, and -Windows PowerShell drives (PSDrives) by limiting where they can be read and -changed. By enforcing a few simple rules for scope, Windows PowerShell -helps to ensure that you do not inadvertently change an item that should -not be changed. +PowerShell protects access to variables, aliases, functions, and PowerShell +drives (PSDrives) by limiting where they can be read and changed. By enforcing +a few simple rules for scope, PowerShell helps to ensure that you do not +inadvertently change an item that should not be changed. The following are the basic rules of scope: -- An item you include in a scope is visible in the scope in which it -was created and in any child scope, unless you explicitly make it -private. You can place variables, aliases, functions, or Windows -PowerShell drives in one or more scopes. - -- An item that you created within a scope can be changed only in the -scope in which it was created, unless you explicitly specify a -different scope. - -If you create an item in a scope, and the item shares its name with an -item in a different scope, the original item might be hidden under the -new item. But, it is not overridden or changed. - -Windows PowerShell Scopes - -Scopes in Windows PowerShell have both names and numbers. The named -scopes specify an absolute scope. The numbers are relative and reflect -the relationship between scopes. - -Global: -The scope that is in effect when Windows PowerShell -starts. Variables and functions that are present when -Windows PowerShell starts have been created in the -global scope. This includes automatic variables and -preference variables. This also includes the variables, aliases, -and functions that are in your Windows PowerShell -profiles. - -Local: -The current scope. The local scope can be the global -scope or any other scope. - -Script: -The scope that is created while a script file runs. Only -the commands in the script run in the script scope. To -the commands in a script, the script scope is the local -scope. +- An item you include in a scope is visible in the scope in which it was +created and in any child scope, unless you explicitly make it private. You can +place variables, aliases, functions, or PowerShell drives in one or +more scopes. + +- An item that you created within a scope can be changed only in the scope in +which it was created, unless you explicitly specify a different scope. -Private: -Items in private scope cannot be seen outside of the current -scope. You can use private scope to create a private version -of an item with the same name in another scope. - -Numbered Scopes: -You can refer to scopes by name or by a number that -describes the relative position of one scope to another. -Scope 0 represents the current, or local, scope. Scope 1 -indicates the immediate parent scope. Scope 2 indicates the -parent of the parent scope, and so on. Numbered scopes -are useful if you have created many recursive +If you create an item in a scope, and the item shares its name with an item in +a different scope, the original item might be hidden under the new item. But, +it is not overridden or changed. + +## PowerShell Scopes + +Scopes in PowerShell have both names and numbers. The named scopes specify an +absolute scope. The numbers are relative and reflect the relationship between scopes. -Parent and Child Scopes +- Global: The scope that is in effect when PowerShell starts. Variables and +functions that are present when PowerShell starts have been created in the +global scope. This includes automatic variables and preference variables. This +also includes the variables, aliases, and functions that are in your +PowerShell profiles. + +- Local: The current scope. The local scope can be the global scope or any +other scope. -You can create a new scope by running a script or function, by creating -a session, or by starting a new instance of Windows PowerShell. When you -create a new scope, the result is a parent scope (the original scope) and -a child scope (the scope that you created). +- Script: The scope that is created while a script file runs. Only the +commands in the script run in the script scope. To the commands in a script, +the script scope is the local scope. -In Windows PowerShell, all scopes are child scopes of the global scope, -but you can create many scopes and many recursive scopes. +- Private: Items in private scope cannot be seen outside of the current scope. +You can use private scope to create a private version of an item with the same +name in another scope. + +- Numbered Scopes: You can refer to scopes by name or by a number that describes +the relative position of one scope to another. Scope 0 represents the current, +or local, scope. Scope 1 indicates the immediate parent scope. Scope 2 +indicates the parent of the parent scope, and so on. Numbered scopes are +useful if you have created many recursive scopes. + +## Parent and Child Scopes + +You can create a new scope by running a script or function, by creating a +session, or by starting a new instance of PowerShell. When you create a new +scope, the result is a parent scope (the original scope) and a child scope +(the scope that you created). + +In PowerShell, all scopes are child scopes of the global scope, but you can +create many scopes and many recursive scopes. Unless you explicitly make the items private, the items in the parent scope -are available to the child scope. However, items that you create and change -in the child scope do not affect the parent scope, unless you explicitly -specify the scope when you create the items. +are available to the child scope. However, items that you create and change in +the child scope do not affect the parent scope, unless you explicitly specify +the scope when you create the items. -Inheritance +## Inheritance -A child scope does not inherit the variables, aliases, and functions from -the parent scope. Unless an item is private, the child scope can view the -items in the parent scope. And, it can change the items by explicitly -specifying the parent scope, but the items are not part of the child scope. +A child scope does not inherit the variables, aliases, and functions from the +parent scope. Unless an item is private, the child scope can view the items in +the parent scope. And, it can change the items by explicitly specifying the +parent scope, but the items are not part of the child scope. -However, a child scope is created with a set of items. Typically, it -includes all the aliases that have the AllScope option. This option is -discussed later in this topic. It includes all the variables that have the -AllScope option, plus some variables that can be used to customize the -scope, such as MaximumFunctionCount. +However, a child scope is created with a set of items. Typically, it includes +all the aliases that have the AllScope option. This option is discussed later +in this topic. It includes all the variables that have the AllScope option, +plus some variables that can be used to customize the scope, such as +MaximumFunctionCount. To find the items in a particular scope, use the Scope parameter of Get-Variable or Get-Alias. For example, to get all the variables in the local scope, type: +```powershell get-variable -scope local +``` To get all the variables in the global scope, type: +```powershell get-variable -scope global +``` -Scope Modifiers +## Scope Modifiers To specify the scope of a new variable, alias, or function, use a scope modifier. The valid values of a modifier are Global, Local, Private, and @@ -126,362 +116,411 @@ Script. The syntax for a scope modifier in a variable is: +``` $[]: = +``` The syntax for a scope modifier in a function is: +``` function []: {} +``` The default scope for scripts is the script scope. The default scope for functions and aliases is the local scope, even if they are defined in a script. -The following command, which does not use a scope modifier, creates a -variable in the current or local scope: +The following command, which does not use a scope modifier, creates a variable +in the current or local scope: +```powershell $a = "one" +``` To create the same variable in the global scope, use the Global scope modifier: +```powershell $global:a = "one" +``` -To create the same variable in the script scope, use the script -scope modifier: +To create the same variable in the script scope, use the script scope +modifier: +```powershell $script:a = "one" +``` You can also use a scope modifier in functions. The following function definition creates a function in the global scope: -function global:Hello -{ -write-host "Hello, World" +```powershell +function global:Hello { + write-host "Hello, World" } +``` -You can also use scope modifiers to refer to a variable in a different -scope. The following command refers to the $test variable, first in the -local scope and then in the global scope: +You can also use scope modifiers to refer to a variable in a different scope. +The following command refers to the $test variable, first in the local scope +and then in the global scope: +```powershell $test - $global:test +``` -The Using scope modifier +### The Using scope modifier -Using is a special scope modifier that identifies a local -variable in a remote command. By default, variables in remote -commands are assumed to be defined in the remote session. +Using is a special scope modifier that identifies a local variable in a remote +command. By default, variables in remote commands are assumed to be defined in +the remote session. -The Using scope modifier is introduced in Windows PowerShell 3.0. +The Using scope modifier is introduced in PowerShell 3.0. -For more information, see about_Remote_Variables. +For more information, see [about_Remote_Variables](about_Remote_Variables.md). -The AllScope Option +### The AllScope Option Variables and aliases have an Option property that can take a value of AllScope. Items that have the AllScope property become part of any child scopes that you create, although they are not retroactively inherited by parent scopes. -An item that has the AllScope property is visible in the child scope, and -it is part of that scope. Changes to the item in any scope affect all the -scopes in which the variable is defined. +An item that has the AllScope property is visible in the child scope, and it +is part of that scope. Changes to the item in any scope affect all the scopes +in which the variable is defined. -Managing Scope +### Managing Scope -Several cmdlets have a Scope parameter that lets you get or set (create -and change) items in a particular scope. Use the following command to find -all the cmdlets in your session that have a Scope parameter: +Several cmdlets have a Scope parameter that lets you get or set (create and +change) items in a particular scope. Use the following command to find all the +cmdlets in your session that have a Scope parameter: +```powershell get-help * -parameter scope +``` -To find the variables that are visible in a particular scope, use the -Scope parameter of Get-Variable. The visible parameters include global -parameters, parameters in the parent scope, and parameters in the current -scope. +To find the variables that are visible in a particular scope, use the Scope +parameter of Get-Variable. The visible parameters include global parameters, +parameters in the parent scope, and parameters in the current scope. -For example, the following command gets the variables that are visible in -the local scope: +For example, the following command gets the variables that are visible in the +local scope: +```powershell get-variable -scope local +``` -To create a variable in a particular scope, use a scope modifier or the -Scope parameter of Set-Variable. The following command creates a variable -in the global scope: +To create a variable in a particular scope, use a scope modifier or the Scope +parameter of Set-Variable. The following command creates a variable in the +global scope: +```powershell new-variable -scope global -name a -value "One" +``` -You can also use the Scope parameter of the New-Alias, Set-Alias, or -Get-Alias cmdlets to specify the scope. The following command creates an -alias in the global scope: +You can also use the Scope parameter of the New-Alias, Set-Alias, or Get-Alias +cmdlets to specify the scope. The following command creates an alias in the +global scope: +```powershell new-alias -scope global -name np -value Notepad.exe +``` -To get the functions in a particular scope, use the Get-Item cmdlet when -you are in the scope. The Get-Item cmdlet does not have a scope parameter. +To get the functions in a particular scope, use the Get-Item cmdlet when you +are in the scope. The Get-Item cmdlet does not have a scope parameter. -Using Dot Source Notation with Scope +### Using Dot Source Notation with Scope Scripts and functions follow all the rules of scope. You create them in a particular scope, and they affect only that scope unless you use a cmdlet parameter or a scope modifier to change that scope. -But, you can add a script or function to the current scope by using dot -source notation. Then, when a script runs in the current scope, any -functions, aliases, and variables that the script creates are available -in the current scope. +But, you can add a script or function to the current scope by using dot source +notation. Then, when a script runs in the current scope, any functions, +aliases, and variables that the script creates are available in the current +scope. -To add a function to the current scope, type a dot (.) and a space before -the path and name of the function in the function call. +To add a function to the current scope, type a dot (.) and a space before the +path and name of the function in the function call. -For example, to run the Sample.ps1 script from the C:\Scripts directory in -the script scope (the default for scripts), use the following command: +For example, to run the Sample.ps1 script from the C:\Scripts directory in the +script scope (the default for scripts), use the following command: +```powershell c:\scripts\sample.ps1 +``` To run the Sample.ps1 script in the local scope, use the following command: +```powershell . c:\scripts.sample.ps1 +``` When you use the call operator (&) to run a function or script, it is not added to the current scope. The following example uses the call operator: +```powershell & c:\scripts.sample.ps1 +``` + +Any aliases, functions, or variables that the Sample.ps1 script creates are +not available in the current scope. + +### Restricting Without Scope + +A few PowerShell concepts are similar to scope or interact with scope. These +concepts may be confused with scope or the behavior of scope. + +Sessions, modules, and nested prompts are self-contained environments, but +they are not child scopes of the global scope in the session. + +- Sessions: A session is an environment in which PowerShell runs. When you + create a session on a remote computer, PowerShell establishes a + persistent connection to the remote computer. The persistent connection lets + you use the session for multiple related commands. + + Because a session is a contained environment, it has its own scope, but a + session is not a child scope of the session in which is was created. The + session starts with its own global scope. This scope is independent of the + global scope of the session. You can create child scopes in the session. For + example, you can run a script to create a child scope in a session. + +- Modules: You can use a PowerShell module to share and deliver PowerShell + tools. A module is a unit that can contain cmdlets, scripts, functions, + variables, aliases, and other useful items. Unless explicitly defined, the + items in a module are not accessible outside the module. Therefore, you can + add the module to your session and use the public items without worrying that + the other items might override the cmdlets, scripts, functions, and other + items in your session. -Any aliases, functions, or variables that the Sample.ps1 script creates -are not available in the current scope. - -Restricting Without Scope - -A few Windows PowerShell concepts are similar to scope or interact with -scope. These concepts may be confused with scope or the behavior of scope. - -Sessions, modules, and nested prompts are self-contained environments, -but they are not child scopes of the global scope in the session. - -Sessions: -A session is an environment in which Windows PowerShell runs. -When you create a session on a remote computer, Windows -PowerShell establishes a persistent connection to the remote -computer. The persistent connection lets you use the session for -multiple related commands. - -Because a session is a contained environment, it has its own -scope, but a session is not a child scope of the session in -which is was created. The session starts with its own global -scope. This scope is independent of the global scope of the session. -You can create child scopes in the session. For example, you can run -a script to create a child scope in a session. - -Modules: -You can use a Windows PowerShell module to share and deliver -Windows PowerShell tools. A module is a unit that can contain -cmdlets, scripts, functions, variables, aliases, and other useful -items. Unless explicitly defined, the items in a module are not -accessible outside the module. Therefore, you can add the module to -your session and use the public items without worrying that the -other items might override the cmdlets, scripts, functions, and other -items in your session. - -The privacy of a module behaves like a scope, but adding a module -to a session does not change the scope. And, the module does not have -its own scope, although the scripts in the module, like all Windows -PowerShell scripts, do have their own scope. - -Nested Prompts: -Similarly, nested prompts do not have their own scope. When you enter -a nested prompt, the nested prompt is a subset of the environment. -But, you remain within the local scope. - -Scripts do have their own scope. If you are debugging a script, and -you reach a breakpoint in the script, you enter the script scope. - -Private Option: -Aliases and variables have an Option property that can take a value -of Private. Items that have the Private option can be viewed and -changed in the scope in which they are created, but they cannot be -viewed or changed outside that scope. - -For example, if you create a variable that has a private option in the -global scope and then run a script, Get-Variable commands in the script -do not display the private variable. This occurs even if you use -the global scope modifier. - -You can use the Option parameter of the New-Variable, Set-Variable, -New-Alias, and Set-Alias cmdlets to set the value of the Option -property to Private. - -Visibility: -The Visibility property of a variable or alias determines whether you -can see the item outside the container, such as a module, in which it -was created. Visibility is designed for containers in the same way that -the Private value of the Option property is designed for scopes. - -The Visibility property takes the Public and Private values. Items -that have private visibility can be viewed and changed only in the -container in which they were created. If the container is added or -imported, the items that have private visibility cannot be viewed or -changed. - -Because Visibility is designed for containers, it works differently -in a scope. If you create an item that has private visibility in the -global scope, you cannot view or change the item in any scope. If you -try to view or change the value of a variable that has private -visibility, Windows PowerShell returns an error message. - -You can use the New-Variable and Set-Variable cmdlets to create a -variable that has private visibility. - -# EXAMPLES - - -Example 1: Change a Variable Value Only in a Script - -The following command changes the value of the $ConfirmPreference -variable in a script. The change does not affect the global scope. - -First, to display the value of the $ConfirmPreference variable in -the local scope, use the following command: + The privacy of a module behaves like a scope, but adding a module to a session + does not change the scope. And, the module does not have its own scope, + although the scripts in the module, like all PowerShell scripts, do + have their own scope. +- Nested Prompts: Similarly, nested prompts do not have their own scope. When + you enter a nested prompt, the nested prompt is a subset of the environment. + But, you remain within the local scope. + + Scripts do have their own scope. If you are debugging a script, and you reach + a breakpoint in the script, you enter the script scope. + +- Private Option: Aliases and variables have an Option property that can take a + value of Private. Items that have the Private option can be viewed and changed + in the scope in which they are created, but they cannot be viewed or changed + outside that scope. + + For example, if you create a variable that has a private option in the global + scope and then run a script, Get-Variable commands in the script do not + display the private variable. This occurs even if you use the global scope + modifier. + + You can use the Option parameter of the New-Variable, Set-Variable, New-Alias, + and Set-Alias cmdlets to set the value of the Option property to Private. + +- Visibility: The Visibility property of a variable or alias determines whether + you can see the item outside the container, such as a module, in which it was + created. Visibility is designed for containers in the same way that the + Private value of the Option property is designed for scopes. + + The Visibility property takes the Public and Private values. Items that have + private visibility can be viewed and changed only in the container in which + they were created. If the container is added or imported, the items that have + private visibility cannot be viewed or changed. + + Because Visibility is designed for containers, it works differently in a + scope. If you create an item that has private visibility in the global scope, + you cannot view or change the item in any scope. If you try to view or change + the value of a variable that has private visibility, PowerShell returns an + error message. + + You can use the New-Variable and Set-Variable cmdlets to create a variable + that has private visibility. + +## EXAMPLES + +### Example 1: Change a Variable Value Only in a Script + +The following command changes the value of the \$ConfirmPreference variable in +a script. The change does not affect the global scope. + +First, to display the value of the \$ConfirmPreference variable in the local +scope, use the following command: + +``` C:\PS> $ConfirmPreference High +``` Create a Scope.ps1 script that contains the following commands: +```powershell $ConfirmPreference = "Low" "The value of `$ConfirmPreference is $ConfirmPreference." +``` -Run the script. The script changes the value of the $ConfirmPreference -variable and then reports its value in the script scope. The output -should resemble the following output: +Run the script. The script changes the value of the \$ConfirmPreference +variable and then reports its value in the script scope. The output should +resemble the following output: +```output The value of $ConfirmPreference is Low. +``` -Next, test the current value of the $ConfirmPreference variable in the -current scope. +Next, test the current value of the \$ConfirmPreference variable in the current +scope. +``` C:\PS> $ConfirmPreference High +``` -This example shows that changes to the value of a variable in the script -scope do not affect the value of that variable in the parent scope. +This example shows that changes to the value of a variable in the script scope +do not affect the value of that variable in the parent scope. -Example 2: View a Variable Value in Different Scopes +### Example 2: View a Variable Value in Different Scopes -You can use scope modifiers to view the value of a variable in the local -scope and in a parent scope. +You can use scope modifiers to view the value of a variable in the local scope +and in a parent scope. First, define a $test variable in the global scope. +```powershell $test = "Global" +``` -Next, create a Sample.ps1 script that defines the $test -variable. In the script, use a scope modifier to refer -to either the global or local versions of the $test variable. +Next, create a Sample.ps1 script that defines the \$test variable. In the +script, use a scope modifier to refer to either the global or local versions +of the \$test variable. -In Sample.ps1 +In Sample.ps1: +```powershell $test = "Local" "The local value of `$test is $test." "The global value of `$test is $global:test." +``` When you run Sample.ps1, the output should resemble the following output: +```output The local value of $test is Local. The global value of $test is Global. +``` -When the script is complete, only the global value of $test is defined -in the session. +When the script is complete, only the global value of \$test is defined in the +session. +``` C:\PS> $test Global +``` -Example 3: Change the Value of a Variable in a Parent Scope +### Example 3: Change the Value of a Variable in a Parent Scope -Unless you protect an item by using the Private option or another -method, you can view and change the value of a variable in a parent -scope. +Unless you protect an item by using the Private option or another method, you +can view and change the value of a variable in a parent scope. -First, define a $test variable in the global scope. +First, define a \$test variable in the global scope. +```powershell $test = "Global" +``` -Next, create a Sample.ps1 script that defines the $test variable. In the -script, use a scope modifier to refer to either the global or local -versions of the $test variable. +Next, create a Sample.ps1 script that defines the \$test variable. In the +script, use a scope modifier to refer to either the global or local versions +of the \$test variable. -In Sample.ps1 +In Sample.ps1: +```powershell $global:test = "Local" "The global value of `$test is $global:test." +``` -When the script is complete, the global value of $test is changed. +When the script is complete, the global value of \$test is changed. +``` C:\PS> $test Local +``` -Example 4: Creating a Private Variable +### Example 4: Creating a Private Variable -A private variable is a variable that has an Option property that has a -value of Private. Private variables are inherited by the child scope, but -they can be viewed or changed only in the scope in which they were -created. +A private variable is a variable that has an Option property that has a value +of Private. Private variables are inherited by the child scope, but they can +be viewed or changed only in the scope in which they were created. -The following command creates a private variable called $ptest in the -local scope. +The following command creates a private variable called \$ptest in the local +scope. +```powershell New-Variable -Name ptest -Value 1 -Option private +``` -You can display and change the value of $ptest in the local scope. +You can display and change the value of \$ptest in the local scope. +``` C:\PS> $ptest -# 1 +1 C:\PS> $ptest = 2 C:\PS> $ptest -# 2 - +2 +``` -Next, create a Sample.ps1 script that contains the following commands. -The command tries to display and change the value of $ptest. +Next, create a Sample.ps1 script that contains the following commands. The +command tries to display and change the value of \$ptest. -In Sample.ps1 +In Sample.ps1: +```powershell "The value of `$Ptest is $Ptest." "The value of `$Ptest is $global:Ptest." +``` -Because the $ptest variable is not visible in the script scope, the -output is empty. +Because the $ptest variable is not visible in the script scope, the output is +empty. +```powershell "The value of $Ptest is ." "The value of $Ptest is ." +``` -Example 5: Using a Local Variable in a Remote Command +### Example 5: Using a Local Variable in a Remote Command -To indicate that a variable in a remote command was created in the -local session, use the Using scope modifier. By default, Windows -PowerShell assumes that the variables in remote commands were created -in the remote session. +To indicate that a variable in a remote command was created in the local +session, use the Using scope modifier. By default, PowerShell assumes +that the variables in remote commands were created in the remote session. The syntax is: + +``` $Using: +``` -For example, the following commands create a $Cred variable in the -local session and then use the $Cred variable in a remote command: +For example, the following commands create a $Cred variable in the local +session and then use the $Cred variable in a remote command: +```powershell $Cred = Get-Credential Invoke-Command $s {Remove-Item .\Test*.ps1 -Credential $Using:Cred} +``` -The Using scope was introduced in Windows PowerShell 3.0. - -In Windows PowerShell 2.0, to indicate that a variable was created in -the local session, use the following command format. +The Using scope was introduced in PowerShell 3.0. In PowerShell 2.0, to +indicate that a variable was created in the local session, use the following +command format. +```powershell $Cred = Get-Credential -Invoke-Command $s {param($c) Remove-Item .\Test*.ps1 -Credential $c} -ArgumentList $Cred +Invoke-Command $s { + param($c) + Remove-Item .\Test*.ps1 -Credential $c +} -ArgumentList $Cred +``` -# SEE ALSO +## SEE ALSO [about_Variables](about_Variables.md) @@ -490,4 +529,3 @@ Invoke-Command $s {param($c) Remove-Item .\Test*.ps1 -Credential $c} -ArgumentLi [about_Functions](about_Functions.md) [about_Script_Blocks](about_Script_Blocks.md) - From 98f2b8abaf4b47fe3bae3e5ef8a0e8ad6300c7d7 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 4 Jan 2018 14:41:05 -0800 Subject: [PATCH 153/188] Reformatting v5 About_ topics missed in first pass (#2008) * v5 about scrub missed files * fixing broken links --- .../About/about_Debuggers.md | 661 +++++---- .../About/about_Functions_Advanced_Methods.md | 270 ++-- .../about_Functions_OutputTypeAttribute.md | 118 +- .../About/about_Language_Keywords.md | 2 +- .../About/about_PSSessions.md | 189 ++- .../About/about_PSSnapins.md | 189 ++- .../About/about_Parameters.md | 237 +-- .../About/about_PowerShell_exe.md | 254 ++-- .../About/about_Quoting_Rules.md | 257 ++-- .../About/about_Remote.md | 238 +-- .../About/about_Remote_Requirements.md | 244 ++- .../About/about_Remote_Variables.md | 148 +- .../About/about_Requires.md | 5 +- .../About/about_Reserved_Words.md | 2 +- .../About/about_Return.md | 107 +- .../About/about_Run_With_PowerShell.md | 68 +- .../about_Script_Internationalization.md | 179 ++- .../about_Session_Configuration_Files.md | 506 +++---- .../About/about_Signing.md | 326 ++-- .../About/about_Splatting.md | 137 +- .../About/about_Transactions.md | 847 ++++++----- .../About/about_Updatable_Help.md | 664 ++++----- .../About/about_WMI.md | 100 +- .../About/about_WQL.md | 892 +++++------ .../About/about_Windows_PowerShell_ISE.md | 271 ++-- .../About/about_Windows_RT.md | 71 +- .../About/about_desiredstateconfiguration.md | 316 ++-- .../About/about_dsclogresource.md | 23 +- .../About/about_hidden.md | 264 ++-- .../About/about_logical_operators.md | 63 +- .../About/about_packagemanagement.md | 20 +- .../About/about_psconsolehostreadline.md | 79 +- .../About/about_psreadline.md | 1309 +++++++++-------- .../About/about_scopes.md | 598 ++++---- .../About/about_type_accelerators.md | 17 - .../About/about_windows_powershell_5.0.md | 614 ++++---- 36 files changed, 5318 insertions(+), 4967 deletions(-) delete mode 100644 reference/5.0/Microsoft.PowerShell.Core/About/about_type_accelerators.md diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Debuggers.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Debuggers.md index 8ea961ecdfe8..c7b464110d8d 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Debuggers.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Debuggers.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,64 +7,55 @@ title: about_Debuggers --- # About Debuggers -## about_Debuggers - - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes the Windows PowerShell debugger. -# LONG DESCRIPTION - -Debugging is the process of examining a script while it is running to -identify and correct errors in the script instructions. The -Windows PowerShell debugger can help you examine and identify -errors and inefficiencies in your scripts, functions, commands, Windows -PowerShell workflows, Windows PowerShell Desired State Configuration (DSC) -configurations, or expressions. - -Starting in Windows PowerShell 5.0, the Windows PowerShell debugger has been updated -to debug scripts, functions, workflows, commands, configurations, or expressions that are -running in either the console or Windows PowerShell ISE on remote computers. -You can run Enter-PSSession to start an interactive remote PowerShell session -in which you can set breakpoints and debug script files and commands on the -remote computer. Enter-PSSession functionality has been updated to let you -reconnect to and enter a disconnected session that is running a script or -command on a remote computer. If the running script hits a breakpoint, -your client session automatically starts the debugger. If the disconnected -session that is running a script has already hit a breakpoint, and is stopped -at the breakpoint, Enter-PSSession automatically starts the command-line -debugger, after you reconnect to the session. - -The Windows PowerShell debugger can also be used to debug Windows -PowerShell workflows, in either the Windows PowerShell console, or in -Windows PowerShell ISE. Starting in Windows PowerShell 5.0, you can debug -within running jobs or processes, either locally or remotely. +## LONG DESCRIPTION + +Debugging is the process of examining a script while it is running to identify +and correct errors in the script instructions. The Windows PowerShell debugger +can help you examine and identify errors and inefficiencies in your scripts, +functions, commands, Windows PowerShell workflows, Windows PowerShell Desired +State Configuration (DSC) configurations, or expressions. + +Starting in Windows PowerShell 5.0, the Windows PowerShell debugger has been +updated to debug scripts, functions, workflows, commands, configurations, or +expressions that are running in either the console or Windows PowerShell ISE +on remote computers. You can run Enter-PSSession to start an interactive +remote PowerShell session in which you can set breakpoints and debug script +files and commands on the remote computer. Enter-PSSession functionality has +been updated to let you reconnect to and enter a disconnected session that is +running a script or command on a remote computer. If the running script hits a +breakpoint, your client session automatically starts the debugger. If the +disconnected session that is running a script has already hit a breakpoint, +and is stopped at the breakpoint, Enter-PSSession automatically starts the +command-line debugger, after you reconnect to the session. + +The Windows PowerShell debugger can also be used to debug Windows PowerShell +workflows, in either the Windows PowerShell console, or in Windows PowerShell +ISE. Starting in Windows PowerShell 5.0, you can debug within running jobs or +processes, either locally or remotely. You can use the features of the Windows PowerShell debugger to examine a -Windows PowerShell script, function, command, workflow, or expression -while it is running. The Windows PowerShell debugger includes a set of -cmdlets that let you set breakpoints, manage breakpoints, and view the call -stack. - -Debugger Cmdlets -The Windows PowerShell debugger includes the following set of cmdlets: +Windows PowerShell script, function, command, workflow, or expression while it +is running. The Windows PowerShell debugger includes a set of cmdlets that let +you set breakpoints, manage breakpoints, and view the call stack. -Set-PsBreakpoint: Sets breakpoints on lines, variables, and -commands. +## Debugger Cmdlets -Get-PsBreakpoint: Gets breakpoints in the current session. - -Disable-PsBreakpoint: Turns off breakpoints in the current session. - -Enable-PsBreakpoint: Re-enables breakpoints in the current session. +The Windows PowerShell debugger includes the following set of cmdlets: -Remove-PsBreakpoint: Deletes breakpoints from the current session. +- `Set-PsBreakpoint`: Sets breakpoints on lines, variables, and commands. +- `Get-PsBreakpoint`: Gets breakpoints in the current session. +- `Disable-PsBreakpoint`: Turns off breakpoints in the current session. +- `Enable-PsBreakpoint`: Re-enables breakpoints in the current session. +- `Remove-PsBreakpoint`: Deletes breakpoints from the current session. +- `Get-PsCallStack`: Displays the current call stack. -Get-PsCallStack: Displays the current call stack. +## Starting and Stopping the Debugger -Starting and Stopping the Debugger To start the debugger, set one or more breakpoints. Then, run the script, command, or function that you want to debug. @@ -72,89 +63,85 @@ When you reach a breakpoint, execution stops, and control is turned over to the debugger. To stop the debugger, run the script, command, or function until it is -complete. Or, type "stop" or "t". +complete. Or, type `stop` or `t`. -Debugger Commands -When you use the debugger in the Windows PowerShell console, use the -following commands to control the execution. In Windows PowerShell ISE, -use commands on the Debug menu. +### Debugger Commands + +When you use the debugger in the Windows PowerShell console, use the following +commands to control the execution. In Windows PowerShell ISE, use commands on +the Debug menu. Note: For information about how to use the debugger in other host applications, see the host application documentation. -s, StepInto Executes the next statement and then stops. +- `s`, `StepInto`: Executes the next statement and then stops. -v, StepOver Executes the next statement, but skips functions -and invocations. The skipped statements are -executed, but not stepped through. +- `v`, `StepOver`: Executes the next statement, but skips functions and + invocations. The skipped statements are executed, but not stepped through. -Ctrl+Break -(Break All in ISE) Breaks into a running script within either the -Windows PowerShell console, or Windows PowerShell ISE. -Note that Ctrl+Break in Windows PowerShell 2.0, 3.0, -and 4.0 closes the program. Break All works on both -local and remote interactively-running scripts. +- `Ctrl+Break`: (Break All in ISE) Breaks into a running script within either + the Windows PowerShell console, or Windows PowerShell ISE. Note that + Ctrl+Break in Windows PowerShell 2.0, 3.0, and 4.0 closes the program. Break + All works on both local and remote interactively-running scripts. -o, StepOut Steps out of the current function; up one level -if nested. If in the main body, it continues to -the end or the next breakpoint. The skipped -statements are executed, but not stepped through. +- `o`, `StepOut`: Steps out of the current function; up one level if nested. + If in the main body, it continues to the end or the next breakpoint. The + skipped statements are executed, but not stepped through. -c, Continue Continues to run until the script is complete or -until the next breakpoint is reached. The skipped -statements are executed, but not stepped through. +- `c`, `Continue`: Continues to run until the script is complete or until the + next breakpoint is reached. The skipped statements are executed, but not + stepped through. -l, List Displays the part of the script that is executing. -By default, it displays the current line, five -previous lines, and 10 subsequent lines. To continue -listing the script, press ENTER. +- `l`, `List`: Displays the part of the script that is executing. By default, + it displays the current line, five previous lines, and 10 subsequent lines. + To continue listing the script, press ENTER. -l , List Displays 16 lines of the script beginning with the -line number specified by . +- `l `, `List`: Displays 16 lines of the script beginning with the line + number specified by ``. -l , List Displays lines of the script, beginning with the -line number specified by . +- `l `, `List`: Displays `` lines of the script, beginning with the + line number specified by ``. -q, Stop, Exit Stops executing the script, and exits the debugger. If you -are debugging a job by running the Debug-Job cmdlet, the Exit -command detaches the debugger, and allows the job to continue -running. +- `q`, `Stop`, `Exit`: Stops executing the script, and exits the debugger. If + you are debugging a job by running the Debug-Job cmdlet, the Exit command + detaches the debugger, and allows the job to continue running. -k, Get-PsCallStack Displays the current call stack. +- `k`, `Get-PsCallStack`: Displays the current call stack. - Repeats the last command if it was Step (s), -StepOver (v), or List (l). Otherwise, represents a -submit action. +- ``: Repeats the last command if it was Step (s), StepOver (v), or + List (l). Otherwise, represents a submit action. -?, h Displays the debugger command Help. +- `?`, `h`: Displays the debugger command Help. To exit the debugger, you can use Stop (q). + Starting in Windows PowerShell 5.0, you can run the Exit command to exit a nested debugging session that you started by running either Debug-Job or Debug-Runspace. -By using these debugger commands, you can run a script, stop on a point -of concern, examine the values of variables and the state of the system, -and continue running the script until you have identified a problem. +By using these debugger commands, you can run a script, stop on a point of +concern, examine the values of variables and the state of the system, and +continue running the script until you have identified a problem. -NOTE: If you step into a statement with a redirection operator, -such as ">", the Windows PowerShell debugger steps over all -remaining statements in the script. +NOTE: If you step into a statement with a redirection operator, such as ">", +the Windows PowerShell debugger steps over all remaining statements in the +script. Displaying the Values of script Variables -While you are in the debugger, you can also enter commands, display the -value of variables, use cmdlets, and run scripts at the command line. +While you are in the debugger, you can also enter commands, display the value +of variables, use cmdlets, and run scripts at the command line. -You can display the current value of all variables in the script that is -being debugged, except for the following automatic variables: - -# $_ +You can display the current value of all variables in the script that is being +debugged, except for the following automatic variables: +```powershell +$_ $Args $Input $MyInvocation $PSBoundParameters +``` If you try to display the value of any of these variables, you get the value of that variable for in an internal pipeline the debugger uses, not @@ -166,15 +153,20 @@ Then you can display the value of the new variable. For example, +```powershell $scriptArgs = $Args $scriptArgs +``` In the example in this topic, the value of the $MyInvocation variable is reassigned as follows: +```powershell $scriptname = $MyInvocation.MyCommand.Path +``` + +## The Debugger Environment -The Debugger Environment When you reach a breakpoint, you enter the debugger environment. The command prompt changes so that it begins with "[DBG]:". If you are debugging a workflow, the prompt is "[WFDBG]". You can customize @@ -189,87 +181,98 @@ command prompt. For example, the following is the default debugging prompt in the Windows PowerShell console: +``` [DBG]: PS (get-location)>>> +``` -You can find the nesting level by using the $NestedPromptLevel +You can find the nesting level by using the \$NestedPromptLevel automatic variable. -Additionally, an automatic variable, $PSDebugContext, is defined in -the local scope. You can use the presence of the $PsDebugContext +Additionally, an automatic variable, \$PSDebugContext, is defined in +the local scope. You can use the presence of the \$PsDebugContext variable to determine whether you are in the debugger. For example: +```powershell if ($psdebugcontext) {"Debugging"} else {"Not Debugging"} +``` -You can use the value of the $PSDebugContext variable in your +You can use the value of the \$PSDebugContext variable in your debugging. +``` [DBG]: PS>>> $psdebugcontext.invocationinfo Name CommandLineParameters UnboundArguments Location ---- --------------------- ---------------- -------- = {} {} C:\ps-test\vote.ps1 (1) +``` + +## Debugging and Scope -Debugging and Scope -Breaking into the debugger does not change the scope in which -you are operating, but when you reach a breakpoint in a script, -you move into the script scope. The script scope is a child -of the scope in which you ran the debugger. +Breaking into the debugger does not change the scope in which you are +operating, but when you reach a breakpoint in a script, you move into the +script scope. The script scope is a child of the scope in which you ran the +debugger. -To find the variables and aliases that are defined in the -script scope, use the Scope parameter of the Get-Alias or -Get-Variable cmdlets. +To find the variables and aliases that are defined in the script scope, use +the Scope parameter of the Get-Alias or Get-Variable cmdlets. -For example, the following command gets the variables in the -local (script) scope: +For example, the following command gets the variables in the local (script) +scope: +```powershell get-variable -scope 0 +``` You can abbreviate the command as: +```powershell gv -s 0 +``` -This is a useful way to see only the variables that you defined in the -script and that you defined while debugging. +This is a useful way to see only the variables that you defined in the script +and that you defined while debugging. Debugging at the Command Line -When you set a variable breakpoint or a command breakpoint, you can set -the breakpoint only in a script file. However, by default, the breakpoint -is set on anything that runs in the current session. - -For example, if you set a breakpoint on the $name variable, the debugger -breaks on any $name variable in any script, command, function, script -cmdlet or expression that you run until you disable or remove the -breakpoint. - -This allows you to debug your scripts in a more realistic context in -which they might be affected by functions, variables, and other scripts -in the session and in the user's profile. - -Line breakpoints are specific to script files, so they are set only in -script files. - -Debugging Workflows -The Windows PowerShell 4.0 debugger can be used to debug Windows -PowerShell workflows, either in the Windows PowerShell console, or in -Windows PowerShell ISE. There are some limitations with using -the Windows PowerShell debugger to debug workflows. - --- You can view workflow variables while you are in the debugger, but -setting workflow variables from within the debugger is not supported. --- Tab completion when stopped in the workflow debugger is not -available. --- Workflow debugging works only with synchronous running of workflows from -a Windows PowerShell script. You cannot debug workflows if they are -running as a job (with the -AsJob parameter). --- Other nested debugging scenarios--such as a workflow calling another -workflow, or a workflow calling a script--are not implemented. - -The following example demonstrates debugging a workflow. Note that when -the debugger steps into the workflow function, the debugger prompt changes -to [WFDBG]. +When you set a variable breakpoint or a command breakpoint, you can set the +breakpoint only in a script file. However, by default, the breakpoint is set +on anything that runs in the current session. + +For example, if you set a breakpoint on the \$name variable, the debugger +breaks on any \$name variable in any script, command, function, script cmdlet +or expression that you run until you disable or remove the breakpoint. + +This allows you to debug your scripts in a more realistic context in which +they might be affected by functions, variables, and other scripts in the +session and in the user's profile. + +Line breakpoints are specific to script files, so they are set only in script +files. + +## Debugging Workflows + +The Windows PowerShell 4.0 debugger can be used to debug Windows PowerShell +workflows, either in the Windows PowerShell console, or in Windows PowerShell +ISE. There are some limitations with using the Windows PowerShell debugger to +debug workflows. + +- You can view workflow variables while you are in the debugger, but setting + workflow variables from within the debugger is not supported. +- Tab completion when stopped in the workflow debugger is not available. +- Workflow debugging works only with synchronous running of workflows from a + Windows PowerShell script. You cannot debug workflows if they are running as a + job (with the **-AsJob** parameter). +- Other nested debugging scenarios--such as a workflow calling another + workflow, or a workflow calling a script--are not implemented. + +The following example demonstrates debugging a workflow. Note that when the +debugger steps into the workflow function, the debugger prompt changes to +[WFDBG]. + +```powershell PS C:> Set-PSBreakpoint -Script C:\TestWFDemo1.ps1 -Line 8 ID Script Line Command Variable Action @@ -350,32 +353,32 @@ At C:\TestWFDemo1.ps1:11 char:5 [WFDBG:localhost]: PS C:>> stepOut Get PowerShell process: -Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName PSComputerName -------- ------ ----- ----- ----- ------ -- ----------- -------------- -433 35 106688 128392 726 2.67 7124 powershell localhost -499 44 134244 172096 787 2.79 7452 powershell localhost +Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName +------- ------ ----- ----- ----- ------ -- ----------- + 433 35 106688 128392 726 2.67 7124 powershell + 499 44 134244 172096 787 2.79 7452 powershell + Workflow function complete. +``` + +## Debugging Functions -Debugging Functions When you set a breakpoint on a function that has Begin, Process, and End sections, the debugger breaks at the first line of each section. For example: -function test-cmdlet -{ -begin -{ -write-output "Begin" -} -process -{ -write-output "Process" -} -end -{ -write-output "End" -} +```powershell +function test-cmdlet { + begin { + write-output "Begin" + } + process { + write-output "Process" + } + end { + write-output "End" + } } C:\PS> set-psbreakpoint -command test-cmdlet @@ -406,20 +409,24 @@ Hit Command breakpoint on 'prompt:test-cmdlet' test-cmdlet # [DBG]: C:\PS> +``` +## Debugging Remote Scripts -Debugging Remote Scripts -Starting in Windows PowerShell 5.0, you can run the Windows PowerShell debugger in -a remote session, in either the console, or Windows PowerShell ISE. Enter-PSSession -functionality has been updated to let you reconnect to and enter a disconnected -session that is running on a remote computer, and currently running a script. -If the running script hits a breakpoint, your client session automatically -starts the debugger. The following is an example that shows how this works, -with breakpoints set in a script at lines 6, 11, 22, and 25. Note that in the -example, when the debugger starts, there are two identifying prompts: the -name of the computer on which the session is running, and the DBG prompt that -lets you know you are in debugging mode. +Starting in Windows PowerShell 5.0, you can run the Windows PowerShell +debugger in a remote session, in either the console, or Windows PowerShell +ISE. Enter-PSSession functionality has been updated to let you reconnect to +and enter a disconnected session that is running on a remote computer, and +currently running a script. If the running script hits a breakpoint, your +client session automatically starts the debugger. +The following is an example that shows how this works, with breakpoints set in +a script at lines 6, 11, 22, and 25. Note that in the example, when the +debugger starts, there are two identifying prompts: the name of the computer +on which the session is running, and the DBG prompt that lets you know you are +in debugging mode. + +```powershell Enter-Pssession -Cn localhost [localhost]: PS C:\psscripts> Set-PSBreakpoint .\ttest19.ps1 6,11,22,25 @@ -468,45 +475,54 @@ At C:\psscripts\ttest19.ps1:12 char:1 [localhost]: [DBG]: PS C:\psscripts>> quit [localhost]: PS C:\psscripts> Exit-PSSession PS C:\psscripts> +``` + +## Examples -Examples This test script detects the version of the operating system and displays a system-appropriate message. It includes a function, a function call, and a variable. The following command displays the contents of the test script file: +```powershell c:>\PS-test> get-content test.ps1 function psversion { -"Windows PowerShell " + $psversiontable.psversion -if ($psversiontable.psversion.major -lt 2) { -"Upgrade to Windows PowerShell 2.0!" -} -else { -"Have you run a background job today (start-job)?" -} + "Windows PowerShell " + $psversiontable.psversion + if ($psversiontable.psversion.major -lt 6) { + "Upgrade to Windows PowerShell 6.0!" + } + else { + "Have you run a background job today (start-job)?" + } } $scriptname = $MyInvocation.MyCommand.Path psversion "Done $scriptname." +``` -To start, set a breakpoint at a point of interest in the script, such -as a line, command, variable, or function. +To start, set a breakpoint at a point of interest in the script, such as a +line, command, variable, or function. -Start by creating a line breakpoint on the first line of the Test.ps1 -script in the current directory. +Start by creating a line breakpoint on the first line of the Test.ps1 script +in the current directory. +```powershell PS C:\ps-test> set-psbreakpoint -line 1 -script test.ps1 +``` You can abbreviate this command as: +```powershell PS C:\ps-test> spb 1 -s test.ps1 +``` The command returns a line-breakpoint object (System.Management.Automation.LineBreakpoint). +``` Column : 0 Line : 1 Action : @@ -515,150 +531,181 @@ HitCount : 0 Id : 0 Script : C:\ps-test\test.ps1 ScriptName : C:\ps-test\test.ps1 +``` Now, start the script. +```powershell PS C:\ps-test> .\test.ps1 +``` -When the script reaches the first breakpoint, the breakpoint message -indicates that the debugger is active. It describes the breakpoint and -previews the first line of the script, which is a function declaration. -The command prompt also changes to indicate that the debugger has -control. +When the script reaches the first breakpoint, the breakpoint message indicates +that the debugger is active. It describes the breakpoint and previews the +first line of the script, which is a function declaration. The command prompt +also changes to indicate that the debugger has control. -The preview line includes the script name and the line number of the -previewed command. +The preview line includes the script name and the line number of the previewed +command. +```powershell Entering debug mode. Use h or ? for help. Hit Line breakpoint on 'C:\ps-test\test.ps1:1' test.ps1:1 function psversion { # DBG> +``` +Use the Step command (s) to execute the first statement in the script and to +preview the next statement. The next statement uses the $MyInvocation +automatic variable to set the value of the $ScriptName variable to the path +and file name of the script file. -Use the Step command (s) to execute the first statement in the script -and to preview the next statement. The next statement uses the -$MyInvocation automatic variable to set the value of the $ScriptName -variable to the path and file name of the script file. - +```powershell DBG> s test.ps1:11 $scriptname = $MyInvocation.MyCommand.Path +``` -At this point, the $ScriptName variable is not populated, but you can +At this point, the \$ScriptName variable is not populated, but you can verify the value of the variable by displaying its value. In this case, -the value is $null. +the value is \$null. +```powershell DBG> $scriptname # DBG> - +``` Use another Step command (s) to execute the current statement and to preview the next statement in the script. The next statement calls the PsVersion function. +```powershell DBG> s test.ps1:12 psversion +``` At this point, the $ScriptName variable is populated, but you verify the value of the variable by displaying its value. In this case, the value is set to the script path. +```powershell DBG> $scriptname C:\ps-test\test.ps1 +``` Use another Step command to execute the function call. Press ENTER, or type "s" for Step. +```powershell DBG> s test.ps1:2 "Windows PowerShell " + $psversiontable.psversion +``` -The debug message includes a preview of the statement in the function. -To execute this statement and to preview the next statement in the -function, you can use a Step command. But, in this case, use a StepOut -command (o). It completes the execution of the function (unless it -reaches a breakpoint) and steps to the next statement in the script. +The debug message includes a preview of the statement in the function. To +execute this statement and to preview the next statement in the function, you +can use a Step command. But, in this case, use a StepOut command (o). It +completes the execution of the function (unless it reaches a breakpoint) and +steps to the next statement in the script. +```powershell DBG> o Windows PowerShell 2.0 Have you run a background job today (start-job)? test.ps1:13 "Done $scriptname" +``` -Because we are on the last statement in the script, the Step, StepOut, -and Continue commands have the same effect. In this case, use -StepOut (o). +Because we are on the last statement in the script, the Step, StepOut, and +Continue commands have the same effect. In this case, use StepOut (o). +```powershell Done C:\ps-test\test.ps1 PS C:\ps-test> +``` -The StepOut command executes the last command. The standard command -prompt indicates that the debugger has exited and returned control to the -command processor. +The StepOut command executes the last command. The standard command prompt +indicates that the debugger has exited and returned control to the command +processor. -Now, run the debugger again. First, to delete the current -breakpoint, use the Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. -(If you think you might reuse the breakpoint, use the -Disable-PsBreakpoint cmdlet instead of Remove-PsBreakpoint.) +Now, run the debugger again. First, to delete the current breakpoint, use the +Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. (If you think you might +reuse the breakpoint, use the Disable-PsBreakpoint cmdlet instead of +Remove-PsBreakpoint.) +```powershell PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint +``` You can abbreviate this command as: +```powershell PS C:\ps-test> gbp | rbp +``` Or, run the command by writing a function, such as the following function: +```powershell function delbr { gbp | rbp } +``` -Now, create a breakpoint on the $scriptname variable. +Now, create a breakpoint on the \$scriptname variable. +```powershell PS C:\ps-test> set-psbreakpoint -variable scriptname -script test.ps1 +``` You can abbreviate the command as: +```powershell PS C:\ps-test> sbp -v scriptname -s test.ps1 +``` Now, start the script. The script reaches the variable breakpoint. The default mode is Write, so execution stops just before the statement that changes the value of the variable. +```powershell PS C:\ps-test> .\test.ps1 Hit Variable breakpoint on 'C:\ps-test\test.ps1:$scriptname' (Write access) test.ps1:11 $scriptname = $MyInvocation.mycommand.path # DBG> +``` +Display the current value of the \$scriptname variable, which is \$null. -Display the current value of the $scriptname variable, which -is $null. - +```powershell DBG> $scriptname # DBG> +``` +Use a Step command (s) to execute the statement that populates the variable. +Then, display the new value of the \$scriptname variable. -Use a Step command (s) to execute the statement that populates -the variable. Then, display the new value of the $scriptname -variable. - +```powershell DBG> $scriptname C:\ps-test\test.ps1 +```powershell Use a Step command (s) to preview the next statement in the script. +```powershell DBG> s test.ps1:12 psversion +``` -The next statement is a call to the PsVersion function. To skip the -function but still execute it, use a StepOver command (v). If you are -already in the function when you use StepOver, it is not effective. The -function call is displayed, but it is not executed. +The next statement is a call to the PsVersion function. To skip the function +but still execute it, use a StepOver command (v). If you are already in the +function when you use StepOver, it is not effective. The function call is +displayed, but it is not executed. +```powershell DBG> v Windows PowerShell 2.0 Have you run a background job today (start-job)? test.ps1:13 "Done $scriptname" +``` The StepOver command executes the function, and it previews the next statement in the script, which prints the final line. @@ -666,42 +713,50 @@ statement in the script, which prints the final line. Use a Stop command (t) to exit the debugger. The command prompt reverts to the standard command prompt. +```powershell C:\ps-test> +``` To delete the breakpoints, use the Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. +```powershell PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint +``` Create a new command breakpoint on the PsVersion function. +```powershell PS C:\ps-test> Set-PsBreakpoint -command psversion -script test.ps1 +``` You can abbreviate this command to: +```powershell PS C:\ps-test> sbp -c psversion -s test.ps1 +``` Now, run the script. +```powershell PS C:\ps-test> .\test.ps1 Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion' test.ps1:12 psversion # DBG> +``` - -The script reaches the breakpoint at the function call. At this point, -the function has not yet been called. This gives you the opportunity -to use the Action parameter of Set-PsBreakpoint to set conditions for -the execution of the breakpoint or to perform preparatory or diagnostic -tasks, such as starting a log or invoking a diagnostic or security -script. +The script reaches the breakpoint at the function call. At this point, the +function has not yet been called. This gives you the opportunity to use the +Action parameter of Set-PsBreakpoint to set conditions for the execution of +the breakpoint or to perform preparatory or diagnostic tasks, such as starting +a log or invoking a diagnostic or security script. To set an action, use a Continue command (c) to exit the script, and a -Remove-PsBreakpoint command to delete the current breakpoint. -(Breakpoints are read-only, so you cannot add an action to the current -breakpoint.) +Remove-PsBreakpoint command to delete the current breakpoint. (Breakpoints are +read-only, so you cannot add an action to the current breakpoint.) +```powershell DBG> c Windows PowerShell 2.0 Have you run a background job today (start-job)? @@ -709,104 +764,102 @@ Done C:\ps-test\test.ps1 PS C:\ps-test> get-psbreakpoint | remove-psbreakpoint PS C:\ps-test> +``` -Now, create a new command breakpoint with an action. The following -command sets a command breakpoint with an action that logs the value -of the $scriptname variable when the function is called. Because the -Break keyword is not used in the action, execution does not stop. (The -backtick (`) is the line-continuation character.) +Now, create a new command breakpoint with an action. The following command +sets a command breakpoint with an action that logs the value of the +\$scriptname variable when the function is called. Because the Break keyword is +not used in the action, execution does not stop. (The backtick (`) is the +line-continuation character.) +```powershell PS C:\ps-test> set-psbreakpoint -command psversion -script test.ps1 ` -action { add-content "The value of `$scriptname is $scriptname." ` -path action.log} +``` -You can also add actions that set conditions for the breakpoint. In -the following command, the command breakpoint is executed only if the -execution policy is set to RemoteSigned, the most restrictive policy -that still permits you to run scripts. (The backtick (`) is the -continuation character.) +You can also add actions that set conditions for the breakpoint. In the +following command, the command breakpoint is executed only if the execution +policy is set to RemoteSigned, the most restrictive policy that still permits +you to run scripts. (The backtick (`) is the continuation character.) +```powershell PS C:\ps-test> set-psbreakpoint -script test.ps1 -command psversion ` -action { if ((get-executionpolicy) -eq "RemoteSigned") { break }} +``` The Break keyword in the action directs the debugger to execute the -breakpoint. You can also use the Continue keyword to direct the debugger -to execute without breaking. Because the default keyword is Continue, -you must specify Break to stop execution. +breakpoint. You can also use the Continue keyword to direct the debugger to +execute without breaking. Because the default keyword is Continue, you must +specify Break to stop execution. Now, run the script. +```powershell PS C:\ps-test> .\test.ps1 Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion' test.ps1:12 psversion +```powershell Because the execution policy is set to RemoteSigned, execution stops at the function call. -At this point, you might want to check the call stack. Use the -Get-PsCallStack cmdlet or the Get-PsCallStack debugger command (k). -The following command gets the current call stack. +At this point, you might want to check the call stack. Use the Get-PsCallStack +cmdlet or the Get-PsCallStack debugger command (k). The following command gets +the current call stack. +```powershell DBG> k 2: prompt 1: .\test.ps1: $args=[] 0: prompt: $args=[] +``` This example demonstrates just a few of the many ways to use the Windows PowerShell debugger. -For more information about the debugger cmdlets, type the following -command: +For more information about the debugger cmdlets, type the following command: +```powershell help -full +``` For example, type: +```powershell help set-psbreakpoint -full +``` -Other Debugging Features in Windows PowerShell +## Other Debugging Features in Windows PowerShell In addition to the Windows PowerShell debugger, Windows PowerShell includes several other features that you can use to debug scripts and functions. --- Windows PowerShell Integrated Scripting Environment (ISE) includes -an interactive graphical debugger. For more information, start Windows -PowerShell ISE and press F1. - --- The Set-PSDebug cmdlet offers very basic script debugging features, -including stepping and tracing. - --- Use the Set-StrictMode cmdlet to detect references to -uninitialized variables, to references to non-existent properties -of an object, and to function syntax that is not valid. - --- Add diagnostic statements to a script, such as statements that -display the value of variables, statements that read input from -the command line, or statements that report the current -instruction. Use the cmdlets that contain the Write verb for -this task, such as Write-Host, Write-Debug, Write-Warning, and -Write-Verbose. - -# SEE ALSO - -Disable-PsBreakpoint - -Enable-PsBreakpoint - -Get-PsBreakpoint - -Get-PsCallStack - -Remove-PsBreakpoint - -Set-PsBreakpoint - -Set-PsDebug - -Set-Strictmode - -Write-Debug - -Write-Verbose - +- Windows PowerShell Integrated Scripting Environment (ISE) includes an + interactive graphical debugger. For more information, start PowerShell ISE + and press F1. + +- The Set-PSDebug cmdlet offers very basic script debugging features, + including stepping and tracing. + +- Use the Set-StrictMode cmdlet to detect references to uninitialized + variables, to references to non-existent properties of an object, and to + function syntax that is not valid. + +- Add diagnostic statements to a script, such as statements that display the + value of variables, statements that read input from the command line, or + statements that report the current instruction. Use the cmdlets that contain + the Write verb for this task, such as Write-Host, Write-Debug, Write-Warning, + and Write-Verbose. + +## SEE ALSO + +- [Disable-PsBreakpoint](../../Microsoft.PowerShell.Utility/Disable-PsBreakpoint.md) +- [Enable-PsBreakpoint](../../Microsoft.PowerShell.Utility/Enable-PsBreakpoint.md) +- [Get-PsBreakpoint](../../Microsoft.PowerShell.Utility/Get-PsBreakpoint.md) +- [Get-PsCallStack](../../Microsoft.PowerShell.Utility/Get-PsCallStack.md) +- [Remove-PsBreakpoint](../../Microsoft.PowerShell.Utility/Remove-PsBreakpoint.md) +- [Set-PsBreakpoint](../../Microsoft.PowerShell.Utility/Set-PsBreakpoint.md) +- [Write-Debug](../../Microsoft.PowerShell.Utility/Write-Debug.md) +- [Write-Verbose](../../Microsoft.PowerShell.Utility/Write-Verbose.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md index 3e4a5424b207..fbcfc30ca802 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,77 +7,72 @@ title: about_Functions_Advanced_Methods --- # About Functions Advanced Methods -## about_Functions_Advanced_Methods +## SHORT DESCRIPTION -# SHORT DESCRIPTION - -Describes how functions that specify the `CmdletBinding` attribute can use -the methods and properties that are available to compiled cmdlets. +Describes how functions that specify the `CmdletBinding` attribute can use the +methods and properties that are available to compiled cmdlets. # LONG DESCRIPTION Functions that specify the `CmdletBinding` attribute can access a number of -methods and properties through the `$pscmdlet` variable. These methods -include the following methods: +methods and properties through the `$pscmdlet` variable. These methods include +the following methods: - Input-processing methods that compiled cmdlets use to do their work. - - The `ShouldProcess` and `ShouldContinue` methods that are used to get -user feedback before an action is performed. - + user feedback before an action is performed. - The `ThrowTerminatingError` method for generating error records. - - Several Write methods that return different types of output. All the methods and properties of the `PSCmdlet` class are available to -advanced functions. For more information about these methods and -properties, see `System.Management.Automation.PSCmdlet` in the MSDN -(Microsoft Developer Network) library at -http://go.microsoft.com/fwlink/?LinkId=142139. - -# Input Processing Methods - -The methods described in this section are referred to as the input -processing methods. For functions, these three methods are represented -by the `Begin`, `Process`, and `End` blocks of the function. Each function -must include one or more of these blocks. The Windows PowerShell runtime -uses the code within these blocks when it is running a function. (These -blocks are also available to functions that do not use the `CmdletBinding` -attribute.) - -## Begin +advanced functions. For more information about these methods and properties, +see `System.Management.Automation.PSCmdlet` in the MSDN (Microsoft Developer +Network) library at http://go.microsoft.com/fwlink/?LinkId=142139. + +### Input Processing Methods + +The methods described in this section are referred to as the input processing +methods. For functions, these three methods are represented by the `Begin`, +`Process`, and `End` blocks of the function. Each function must include one or +more of these blocks. The Windows PowerShell runtime uses the code within +these blocks when it is running a function. (These blocks are also available +to functions that do not use the `CmdletBinding` attribute.) + +#### Begin + This block is used to provide optional one-time preprocessing for the -function. The Windows PowerShell runtime uses the code in this block one -time for each instance of the function in the pipeline. - -## Process -This block is used to provide record-by-record processing for the -function. This block might be used any number of times, or not at all, -depending on the input to the function. For example, if the function is -the first command in the pipeline, the `Process` block will be used one -time. If the function is not the first command in the pipeline, the -`Process` block is used one time for every input that the function -receives from the pipeline. If there is no pipeline input, the `Process` -block is not used. - -This block must be defined if a function parameter is set to accept -pipeline input. If this block is not defined and the parameter accepts -input from the pipeline, the function will miss the values that are -passed to the function through the pipeline. +function. The Windows PowerShell runtime uses the code in this block one time +for each instance of the function in the pipeline. + +#### Process + +This block is used to provide record-by-record processing for the function. +This block might be used any number of times, or not at all, depending on the +input to the function. For example, if the function is the first command in +the pipeline, the `Process` block will be used one time. If the function is +not the first command in the pipeline, the `Process` block is used one time +for every input that the function receives from the pipeline. If there is no +pipeline input, the `Process` block is not used. + +This block must be defined if a function parameter is set to accept pipeline +input. If this block is not defined and the parameter accepts input from the +pipeline, the function will miss the values that are passed to the function +through the pipeline. Also, when the function supports confirmation requests (when the `SupportsShouldProcess` parameter of the Parameter attribute is set to -`$True`), the call to the `ShouldProcess` method must be made from within -the Process block. +`$True`), the call to the `ShouldProcess` method must be made from within the +Process block. + +#### End -## End -This block is used to provide optional one-time post-processing for -the function. +This block is used to provide optional one-time post-processing for the +function. -The following example shows the outline of a function that contains a -`Begin` block for one-time preprocessing, a `Process` block for multiple -record processing, and an `End` block for one-time post-processing. +The following example shows the outline of a function that contains a `Begin` +block for one-time preprocessing, a `Process` block for multiple record +processing, and an `End` block for one-time post-processing. ```powershell Function Test-ScriptCmdlet @@ -90,119 +85,125 @@ Function Test-ScriptCmdlet } ``` -# Confirmation Methods +### Confirmation Methods + +#### ShouldProcess -## ShouldProcess This method is called to request confirmation from the user before the -function performs an action that would change the system. The function -can continue based on the Boolean value returned by the method. This -method can be called only from within the `Process{}` block of the -function. And, the `CmdletBinding` attribute must declare that the -function supports `ShouldProcess` (as shown in the previous example). +function performs an action that would change the system. The function can +continue based on the Boolean value returned by the method. This method can be +called only from within the `Process{}` block of the function. And, the +`CmdletBinding` attribute must declare that the function supports +`ShouldProcess` (as shown in the previous example). For more information about this method, see -`System.Management.Automation.Cmdlet.ShouldProcess` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142142. +[`System.Management.Automation.Cmdlet.ShouldProcess`](http://go.microsoft.com/fwlink/?LinkId=142142) +in the MSDN library. For more information about how to request confirmation, see -"Requesting Confirmation" in the MSDN library at -http://go.microsoft.com/fwlink/?LinkID=136658. +[Requesting Confirmation](http://go.microsoft.com/fwlink/?LinkID=136658) +in the MSDN library. + +#### ShouldContinue -## ShouldContinue -This method is called to request a second confirmation message. It -should be called when the `ShouldProcess` method returns `$true`. For more -information about this method, see -`System.Management.Automation.Cmdlet.ShouldContinue` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142143. +This method is called to request a second confirmation message. It should be +called when the `ShouldProcess` method returns `$true`. For more information +about this method, see `System.Management.Automation.Cmdlet.ShouldContinue` in +the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142143. -# Error Methods +### Error Methods Functions can call two different methods when errors occur. When a -nonterminating error occurs, the function should call the `WriteError` -method, which is described in the "Write Methods" section. When a -terminating error occurs and the function cannot continue, it should call -the `ThrowTerminatingError` method. You can also use the `Throw` statement for +nonterminating error occurs, the function should call the `WriteError` method, +which is described in the "Write Methods" section. When a terminating error +occurs and the function cannot continue, it should call the +`ThrowTerminatingError` method. You can also use the `Throw` statement for terminating errors and the `Write-Error` cmdlet for nonterminating errors. -For more information, see `System.Management.Automation.Cmdlet.ThrowTerminatingError` -in the MSDN libray at -http://go.microsoft.com/fwlink/?LinkId=142144. +For more information, see +[`System.Management.Automation.Cmdlet.ThrowTerminatingError`](http://go.microsoft.com/fwlink/?LinkId=142144) +in the MSDN libray. -# Write Methods +### Write Methods -A function can call the following methods to return different types of -output. Notice that not all the output goes to the next command in the -pipeline. You can also use the various Write cmdlets, such as -Write-Error. +A function can call the following methods to return different types of output. +Notice that not all the output goes to the next command in the pipeline. You +can also use the various Write cmdlets, such as Write-Error. + +#### WriteCommandDetail -## WriteCommandDetail For information about the `WriteCommandDetails` method, see -`System.Management.Automation.Cmdlet.WriteCommandDetail` in the MSDN -library at http://go.microsoft.com/fwlink/?LinkId=142155. - -## WriteDebug -To provide information that can be used to troubleshoot a function, -make the function call the `WriteDebug` method. This displays debug -messages to the user. For more information, see -`System.Management.Automation.Cmdlet.WriteDebug` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142156. - -## WriteError -Functions should call this method when nonterminating errors occur and -the function is designed to continue processing records. For more -information, see `System.Management.Automation.Cmdlet.WriteError` in the -MSDN library at http://go.microsoft.com/fwlink/?LinkId=142157. +[`System.Management.Automation.Cmdlet.WriteCommandDetail`](http://go.microsoft.com/fwlink/?LinkId=142155) +in the MSDN library. + +#### WriteDebug + +To provide information that can be used to troubleshoot a function, make the +function call the `WriteDebug` method. This displays debug messages to the +user. For more information, see +[`System.Management.Automation.Cmdlet.WriteDebug`](http://go.microsoft.com/fwlink/?LinkId=142156) +in the MSDN library. + +#### WriteError + +Functions should call this method when nonterminating errors occur and the +function is designed to continue processing records. For more information, see +[`System.Management.Automation.Cmdlet.WriteError`](http://go.microsoft.com/fwlink/?LinkId=142157) +in the MSDN library. Note: If a terminating error occurs, the function should call the `ThrowTerminatingError` method. -## WriteObject -This method allows the function to send an object to the next command in -the pipeline. In most cases, this is the method to use when the function -returns data. For more information, see -`System.Management.Automation.PSCmdlet.WriteObject` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142158. - -## WriteProgress -For functions whose actions take a long time to complete, this method -allows the function to call the `WriteProgress` method so that progress -information is displayed. For example, you can display the percent -completed. For more information, see -`System.Management.Automation.PSCmdlet.WriteProgress` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142160. - -## WriteVerbose -To provide detailed information about what the function is doing, make -the function call the `WriteVerbose` method to display verbose messages to -the user. By default, verbose messages are not displayed. For more -information, see `System.Management.Automation.PSCmdlet.WriteVerbose` -in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142162. - -## WriteWarning -To provide information about conditions that may cause unexpected -results, make the function call the WriteWarning method to display -warning messages to the user. By default, warning messages are displayed. -For more information, see -`System.Management.Automation.PSCmdlet.WriteWarning` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142164. +#### WriteObject + +This method allows the function to send an object to the next command in the +pipeline. In most cases, this is the method to use when the function returns +data. For more information, see +[`System.Management.Automation.PSCmdlet.WriteObject`](http://go.microsoft.com/fwlink/?LinkId=142158) +in the MSDN library. + +#### WriteProgress + +For functions whose actions take a long time to complete, this method allows +the function to call the `WriteProgress` method so that progress information +is displayed. For example, you can display the percent completed. For more +information, see [`System.Management.Automation.PSCmdlet.WriteProgress`](http://go.microsoft.com/fwlink/?LinkId=142160) +in the MSDN library. + +#### WriteVerbose + +To provide detailed information about what the function is doing, make the +function call the `WriteVerbose` method to display verbose messages to the +user. By default, verbose messages are not displayed. For more information, +see +[`System.Management.Automation.PSCmdlet.WriteVerbose`](http://go.microsoft.com/fwlink/?LinkId=142162) +in the MSDN library. + +#### WriteWarning + +To provide information about conditions that may cause unexpected results, +make the function call the WriteWarning method to display warning messages to +the user. By default, warning messages are displayed. For more information, +see [`System.Management.Automation.PSCmdlet.WriteWarning`](http://go.microsoft.com/fwlink/?LinkId=142164) +in the MSDN library. Note: You can also display warning messages by configuring the `WarningPreference` variable or by using the `Verbose` and `Debug` command-line options. -# Other Methods and Properties +### Other Methods and Properties For information about the other methods and properties that can be accessed through the `$PSCmdlet` variable, see -`System.Management.Automation.PSCmdlet` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142139. +[`System.Management.Automation.PSCmdlet`](http://go.microsoft.com/fwlink/?LinkId=142139) +in the MSDN library. For example, the `ParameterSetName` property allows you to see the parameter set that is being used. Parameter sets allow you to create a function that -performs different tasks based on the parameters that are specified when -the function is run. +performs different tasks based on the parameters that are specified when the +function is run. -# SEE ALSO +## SEE ALSO [about_Functions](about_Functions.md) @@ -213,4 +214,3 @@ the function is run. [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) [about_Functions_OutputTypeAttribute](about_Functions_OutputTypeAttribute.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md index 7765c99a4084..f5f40dd0d876 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,13 @@ title: about_Functions_OutputTypeAttribute --- # About Functions OutputTypeAttribute -## about_Functions_OutputTypeAttribute - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes an attribute that reports the type of object that the function returns. -# LONG DESCRIPTION +## LONG DESCRIPTION The OutputType attribute lists the .NET types of objects that the functions returns. You can use its optional ParameterSetName parameter to list different @@ -32,24 +30,30 @@ The OutputType attribute value is only a documentation note. It is not derived from the function code or compared to the actual function output. As such, the value might be inaccurate. -# SYNTAX +## SYNTAX The OutputType attribute of functions has the following syntax: +``` [OutputType([], ParameterSetName="")] [OutputType("", ParameterSetName="")] +``` The ParameterSetName parameter is optional. You can list multiple types in the OutputType attribute. +``` [OutputType([],[],[])] +``` You can use the ParameterSetName parameter to indicate that different parameter sets return different types. +``` [OutputType([], ParameterSetName="","")] [OutputType([], ParameterSetName="")] +``` Place the OutputType attribute statements in the attributes list that precedes the Param statement. @@ -57,90 +61,99 @@ the Param statement. The following example shows the placement of the OutputType attribute in a simple function. +```powershell function SimpleFunction2 { -[OutputType([])] -Param ($Parameter1) + [OutputType([])] + Param ($Parameter1) - + } +``` The following example shows the placement of the OutputType attribute in advanced functions. +```powershell function AdvancedFunction1 { -[OutputType([])] -Param ( -[parameter(Mandatory=$true)] -[String[]] -$Parameter1 -# ) + [OutputType([])] + Param ( + [parameter(Mandatory=$true)] + [String[]] + $Parameter1 + ) - + } function AdvancedFunction2 { -[CmdletBinding(SupportsShouldProcess=)] -[OutputType([])] -Param ( -[parameter(Mandatory=$true)] -[String[]] -$Parameter1 -# ) + [CmdletBinding(SupportsShouldProcess=)] + [OutputType([])] + Param ( + [parameter(Mandatory=$true)] + [String[]] + $Parameter1 + ) - + } +``` # EXAMPLES - The following function uses the OutputType attribute to indicate that it returns a string value. +```powershell function Send-Greeting { -[OutputType([String])] -Param ($Name) + [OutputType([String])] + Param ($Name) -Hello, $Name + "Hello, $Name" } +``` To see the resulting output type property, use the Get-Command cmdlet. +``` PS C:> (Get-Command Send-Greeting).OutputType Name Type ---- ---- System.String System.String +``` The following advanced function uses the OutputType attribute to indicate that the function returns different types depending on the parameter set used in the function command. +```powershell function Get-User { -[CmdletBinding(DefaultParameterSetName="ID")] + [CmdletBinding(DefaultParameterSetName="ID")] -[OutputType("System.Int32", ParameterSetName="ID")] -[OutputType([String], ParameterSetName="Name")] + [OutputType("System.Int32", ParameterSetName="ID")] + [OutputType([String], ParameterSetName="Name")] -Param ( -[parameter(Mandatory=$true, ParameterSetName="ID")] -[Int[]] -$UserID, + Param ( + [parameter(Mandatory=$true, ParameterSetName="ID")] + [Int[]] + $UserID, -[parameter(Mandatory=$true, ParameterSetName="Name")] -[String[]] -$UserName -# ) + [parameter(Mandatory=$true, ParameterSetName="Name")] + [String[]] + $UserName + ) - + } +``` The following example demonstrates that the output type property value displays the value of the OutputType attribute, even when it is inaccurate. @@ -149,34 +162,38 @@ The Get-Time function returns a string that contains the short form of the time in any DateTime object. However, the OutputType attribute reports that it returns a System.DateTime object. +```powershell function Get-Time { -[OutputType([DateTime])] -Param -# ( + [OutputType([DateTime])] + Param ( + [parameter(Mandatory=$true)] + [Datetime]$DateTime + ) -[parameter(Mandatory=$true)] -[Datetime]$DateTime -# ) - -$DateTime.ToShortTimeString() + $DateTime.ToShortTimeString() } +``` The Get-Type method confirms that the function returns a string. +``` PS C:> (Get-Time -DateTime (Get-Date)).Gettype().FullName System.String +``` However, the OutputType property, which gets its value from the OutputType attribute, reports that the function returns a DateTime object. +``` PS C:> (Get-Command Get-Time).OutputType Name Type ---- ---- System.DateTime System.DateTime +``` -# NOTES +## NOTES The value of the OutputType property of a FunctionInfo object is an array of System.Management.Automation.PSTypeName objects, each of which have Name and @@ -185,7 +202,9 @@ Type properties. To get only the name of each output type, use a command with the following format. +```powershell (Get-Command Get-Time).OutputType | ForEach {$_.Name} +``` The value of the OutputType property can be null. Use a null value when the output is a not a .NET type, such as a WMI object or a formatted view @@ -202,4 +221,3 @@ of an object. [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md) [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Language_Keywords.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Language_Keywords.md index 4588722728a4..a8db7aa4cd39 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Language_Keywords.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Language_Keywords.md @@ -584,7 +584,7 @@ Syntax: do {} while () ``` -# SEE ALSO +## SEE ALSO - [about_Special_Characters](about_Special_Characters.md) - [about_Wildcards](about_Wildcards.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_PSSessions.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_PSSessions.md index 196d7fddf1b9..a96bb8e474f6 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_PSSessions.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_PSSessions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,63 +10,120 @@ title: about_PSSessions ## Short Description -Describes Windows PowerShell sessions (PSSessions) and explains how to establish a persistent connection to a remote computer. +Describes Windows PowerShell sessions (PSSessions) and explains how to +establish a persistent connection to a remote computer. ## Long Description -To run Windows PowerShell commands on a remote computer, you can use the **ComputerName** parameter of a cmdlet, or you can create a Windows PowerShell session (PSSession) and run commands in the PSSession. +To run Windows PowerShell commands on a remote computer, you can use the +**ComputerName** parameter of a cmdlet, or you can create a Windows PowerShell +session (PSSession) and run commands in the PSSession. -When you create a PSSession, Windows PowerShell establishes a persistent connection to the remote computer. Use a PSSession to run a series of related commands on a remote computer. Commands that run in the same PSSession can share data, such as the values of variables, aliases, and functions. +When you create a PSSession, Windows PowerShell establishes a persistent +connection to the remote computer. Use a PSSession to run a series of related +commands on a remote computer. Commands that run in the same PSSession can +share data, such as the values of variables, aliases, and functions. -You can also create a PSSession on the local computer and run commands in it. A local PSSession uses the Windows PowerShell remoting infrastructure to create and maintain the PSSession. +You can also create a PSSession on the local computer and run commands in it. +A local PSSession uses the Windows PowerShell remoting infrastructure to +create and maintain the PSSession. -Beginning in Windows PowerShell 3.0, PSSessions are independent of the sessions in which they are created. Active PSSessions are maintained on the remote computer (or the computer at the remote end or "server-side" of the connection). As a result, you can disconnect from the PSSession and reconnect to it at a later time from the same computer or from a different computer. +Beginning in Windows PowerShell 3.0, PSSessions are independent of the +sessions in which they are created. Active PSSessions are maintained on the +remote computer (or the computer at the remote end or "server-side" of the +connection). As a result, you can disconnect from the PSSession and reconnect +to it at a later time from the same computer or from a different computer. -This topic explains how to create, use, get, and delete PSSessions. For more advanced information, see [about_PSSession_Details](about_PSSession_Details.md). +This topic explains how to create, use, get, and delete PSSessions. For more +advanced information, see +[about_PSSession_Details](about_PSSession_Details.md). -Note: PSSessions use the Windows PowerShell remoting infrastructure. To use PSSessions, the local and remote computers must be configured for remoting. For more information, see [about_Remote_Requirements](about_Remote_Requirements.md). +Note: PSSessions use the Windows PowerShell remoting infrastructure. To use +PSSessions, the local and remote computers must be configured for remoting. +For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). -In Windows Vista and later versions of Windows, to create a PSSession on a local computer, you must start Windows PowerShell with the "Run as administrator" option. +In Windows Vista and later versions of Windows, to create a PSSession on a +local computer, you must start Windows PowerShell with the "Run as +administrator" option. ## What Is a Session? A session is an environment in which Windows PowerShell runs. -Each time you start Windows PowerShell, a session is created for you, and you can run commands in the session. You can also add items to your session, such as modules and snap-ins, and you can create items, such as variables, functions, and aliases. These items exist only in the session and are deleted when the session ends. - -You can also create user-managed sessions, known as " Windows PowerShell sessions" or "PSSessions," on the local computer or on a remote computer. Like the default session, you can run commands in a PSSession and add and create items. - -However, unlike the session that starts automatically, you can control the PSSessions that you create. You can get, create, configure, and remove them, disconnect and reconnect to them, and run multiple commands in the same PSSession. The PSSession remains available until you delete it or it times out. - -Typically, you create a PSSession to run a series of related commands on a remote computer. When you create a PSSession on a remote computer, Windows PowerShell establishes a persistent connection to the remote computer to support the session. - -If you use the **ComputerName** parameter of the `Invoke-Command` or `Enter-PSSession` cmdlet to run a remote command or to start an interactive session, Windows PowerShell creates a temporary session on the remote computer and closes the session as soon as the command is complete or as soon as the interactive session ends. You cannot control these temporary sessions, and you cannot use them for more than a single command or a single interactive session. - -In Windows PowerShell, the "current session" is the session that you are working in. The "current session" can refer to any session, including a temporary session or a PSSession. +Each time you start Windows PowerShell, a session is created for you, and you +can run commands in the session. You can also add items to your session, such +as modules and snap-ins, and you can create items, such as variables, +functions, and aliases. These items exist only in the session and are deleted +when the session ends. + +You can also create user-managed sessions, known as " Windows PowerShell +sessions" or "PSSessions," on the local computer or on a remote computer. Like +the default session, you can run commands in a PSSession and add and create +items. However, unlike the session that starts automatically, you can control +the PSSessions that you create. You can get, create, configure, and remove +them, disconnect and reconnect to them, and run multiple commands in the same +PSSession. The PSSession remains available until you delete it or it times +out. + +Typically, you create a PSSession to run a series of related commands on a +remote computer. When you create a PSSession on a remote computer, Windows +PowerShell establishes a persistent connection to the remote computer to +support the session. + +If you use the **ComputerName** parameter of the `Invoke-Command` or +`Enter-PSSession` cmdlet to run a remote command or to start an interactive +session, Windows PowerShell creates a temporary session on the remote computer +and closes the session as soon as the command is complete or as soon as the +interactive session ends. You cannot control these temporary sessions, and you +cannot use them for more than a single command or a single interactive +session. + +In Windows PowerShell, the "current session" is the session that you are +working in. The "current session" can refer to any session, including a +temporary session or a PSSession. ## Why Use a PSSession? -Use a PSSession when you need a persistent connection to a remote computer. With a PSSession, you can run a series of commands that share data, such as the value of variables, the contents of a function, or the definition of an alias. +Use a PSSession when you need a persistent connection to a remote computer. +With a PSSession, you can run a series of commands that share data, such as +the value of variables, the contents of a function, or the definition of an +alias. -You can run remote commands without creating a PSSession. Use the **ComputerName** parameter of remote-enabled cmdlets to run a single command or a series of unrelated commands on one or many computers. +You can run remote commands without creating a PSSession. Use the +**ComputerName** parameter of remote-enabled cmdlets to run a single command +or a series of unrelated commands on one or many computers. -When you use the **ComputerName** parameter of `Invoke-Command` or `Enter-PSSession`, Windows PowerShell establishes a temporary connection to the remote computer and then closes the connection as soon as the command is complete. Any data elements that you create are lost when the connection is closed. +When you use the **ComputerName** parameter of `Invoke-Command` or +`Enter-PSSession`, Windows PowerShell establishes a temporary connection to +the remote computer and then closes the connection as soon as the command is +complete. Any data elements that you create are lost when the connection is +closed. -Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` and `Get-WmiObject`, use different remoting technologies to gather data. None create a persistent connection like a PSSession. +Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` +and `Get-WmiObject`, use different remoting technologies to gather data. None +create a persistent connection like a PSSession. ## How to Create a PSSession -To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession on a remote computer, use the **ComputerName** parameter of the `New-PSSession` cmdlet. +To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession +on a remote computer, use the **ComputerName** parameter of the +`New-PSSession` cmdlet. -For example, the following command creates a new PSSession on the Server01 computer. +For example, the following command creates a new PSSession on the Server01 +computer. ```powershell New-PSSession -ComputerName Server01 ``` -When you submit the command, `New-PSSession` creates the PSSession and returns an object that represents the PSSession. You can save the object in a variable when you create the PSSession, or you can use a `Get-PSSession` command to get the PSSession at a later time. +When you submit the command, `New-PSSession` creates the PSSession and returns +an object that represents the PSSession. You can save the object in a variable +when you create the PSSession, or you can use a `Get-PSSession` command to get +the PSSession at a later time. -For example, the following command creates a new PSSession on the Server01 computer and saves the resulting object in the $ps variable. +For example, the following command creates a new PSSession on the Server01 +computer and saves the resulting object in the $ps variable. ```powershell $ps = New-PSSession -ComputerName Server01 @@ -74,9 +131,12 @@ $ps = New-PSSession -ComputerName Server01 ## How to Create PSSessions on Multiple Computers -To create PSSessions on multiple computers, use the **ComputerName** parameter of the `New-PSSession` cmdlet. Type the names of the remote computers in a comma-separated list. +To create PSSessions on multiple computers, use the **ComputerName** parameter +of the `New-PSSession` cmdlet. Type the names of the remote computers in a +comma-separated list. -For example, to create PSSessions on the Server01, Server02, and Server03 computers, type: +For example, to create PSSessions on the Server01, Server02, and Server03 +computers, type: ```powershell New-PSSession -ComputerName Server01, Server02, Server03 @@ -86,7 +146,9 @@ New-PSSession -ComputerName Server01, Server02, Server03 ## How to Get PSSessions -To get the PSSessions that were created in your current session, use the `Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` returns the same type of object that `New-PSSession` returns. +To get the PSSessions that were created in your current session, use the +`Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` +returns the same type of object that `New-PSSession` returns. The following command gets all the PSSessions that were created in the current session. @@ -94,9 +156,10 @@ The following command gets all the PSSessions that were created in the current s Get-PSSession ``` -The default display of the PSSessions shows their ID and a default display name. You can assign an alternate display name when you create the session. +The default display of the PSSessions shows their ID and a default display +name. You can assign an alternate display name when you create the session. -``` +```output Id Name ComputerName State ConfigurationName --- ---- ------------ ----- --------------------- 1 Session1 Server01 Opened Microsoft.PowerShell @@ -104,31 +167,45 @@ Id Name ComputerName State ConfigurationName 3 Session3 Server03 Opened Microsoft.PowerShell ``` -You can also save the PSSessions in a variable. The following command gets the PSSessions and saves them in the $ps123 variable. +You can also save the PSSessions in a variable. The following command gets the +PSSessions and saves them in the \$ps123 variable. ```powershell $ps123 = Get-PSSession ``` -When using the PSSession cmdlets, you can refer to a PSSession by its ID, by its name, or by its instance ID (a GUID). The following command gets a PSSession by its ID and saves it in the $ps01 variable. +When using the PSSession cmdlets, you can refer to a PSSession by its ID, by +its name, or by its instance ID (a GUID). The following command gets a +PSSession by its ID and saves it in the \$ps01 variable. ```powershell $ps01 = Get-PSSession -Id 1 ``` -Beginning in Windows PowerShell 3.0, PSSessions are maintained on the remote computer. To get PSSessions that you created on particular remote computers, use the **ComputerName** parameter of the `Get-PSSession` cmdlet. The following command gets the PSSessions that you created on the Server01 remote computer. This includes PSSessions created in the current session and in other sessions on the local computer or other computers. +Beginning in Windows PowerShell 3.0, PSSessions are maintained on the remote +computer. To get PSSessions that you created on particular remote computers, +use the **ComputerName** parameter of the `Get-PSSession` cmdlet. The +following command gets the PSSessions that you created on the Server01 remote +computer. This includes PSSessions created in the current session and in other +sessions on the local computer or other computers. ```powershell Get-PSSession -ComputerName Server01 ``` -In Windows PowerShell 2.0, `Get-PSSession` gets only the PSSessions that were created in the current session. It does not get PSSessions that were created in other sessions or on other computers, even if the sessions are connected to and are running commands on the local computer. +In Windows PowerShell 2.0, `Get-PSSession` gets only the PSSessions that were +created in the current session. It does not get PSSessions that were created +in other sessions or on other computers, even if the sessions are connected to +and are running commands on the local computer. ## How to Run Commands in a PSSession -To run a command in one or more PSSessions, use the `Invoke-Command` cmdlet. Use the Session parameter to specify the PSSessions and the **ScriptBlock** parameter to specify the command. +To run a command in one or more PSSessions, use the `Invoke-Command` cmdlet. +Use the Session parameter to specify the PSSessions and the **ScriptBlock** +parameter to specify the command. -For example, to run a `Get-ChildItem` ("dir") command in each of the three PSSessions saved in the $ps123 variable, type: +For example, to run a `Get-ChildItem` ("dir") command in each of the three +PSSessions saved in the $ps123 variable, type: ```powershell Invoke-Command -Session $ps123 -ScriptBlock { Get-ChildItem } @@ -136,7 +213,8 @@ Invoke-Command -Session $ps123 -ScriptBlock { Get-ChildItem } ## How to Delete PSSessions -When you are finished with the PSSession, use the `Remove-PSSession` cmdlet to delete the PSSession and to release the resources that it was using. +When you are finished with the PSSession, use the `Remove-PSSession` cmdlet to +delete the PSSession and to release the resources that it was using. ```powershell Remove-PSSession -Session $ps @@ -148,35 +226,38 @@ or Remove-PSSession -Id 1 ``` -To remove a PSSession from a remote computer, use the **ComputerName** parameter of the `Remove-PSSession` cmdlet. +To remove a PSSession from a remote computer, use the **ComputerName** +parameter of the `Remove-PSSession` cmdlet. ```powershell Remove-PSSession -ComputerName Server01 -Id 1 ``` -If you do not delete the PSSession, the PSSession remains available for use until it times out. +If you do not delete the PSSession, the PSSession remains available for use +until it times out. -You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` cmdlet to set an expiration time for an idle PSSession. For more information, see [New-PSSessionOption](../New-PSSessionOption.md). +You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` +cmdlet to set an expiration time for an idle PSSession. For more information, +see [New-PSSessionOption](../New-PSSessionOption.md). ## The PSSession Cmdlets -| Cmdlet | Description | -| -------------------- | --------------------------------------------------------------- | -| Connect-PSSession | Connects a PSSession to the current session | -| Disconnect-PSSession | Disconnects a PSSession from the current session | -| Enter-PSSession | Starts an interactive session | -| Exit-PSSession | Ends an interactive session | -| Get-PSSession | Gets the PSSessions in the current session | -| New-PSSession | Creates a new PSSession on a local or remote computer | -| Receive-PSSession | Gets the results of commands that ran in a disconnected session | -| Remove-PSSession | Deletes the PSSessions in the current session | - For a list of PSSession cmdlets, type: ```powershell Get-Help *-PSSession ``` +- Connect-PSSession: Connects a PSSession to the current session +- Disconnect-PSSession: Disconnects a PSSession from the current session +- Enter-PSSession: Starts an interactive session +- Exit-PSSession: Ends an interactive session +- Get-PSSession: Gets the PSSessions in the current session +- New-PSSession: Creates a new PSSession on a local or remote computer +- Receive-PSSession: Gets the results of commands that ran in a disconnected + session +- Remove-PSSession: Deletes the PSSessions in the current session + ## For More Information For more information about PSSessions, see [about_PSSession_Details](about_PSSession_Details.md). diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md index b8e804006dd5..a30c4841c8e3 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_PSSnapins.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,177 +7,212 @@ title: about_PSSnapins --- # About PSSnapins -## about_PSSnapins - ## SHORT DESCRIPTION -Describes Windows PowerShell?snap-ins and shows how to use and manage them. +Describes Windows PowerShell® snap-ins and shows how to use and manage them. ## LONG DESCRIPTION -A Windows PowerShell snap-in is a Microsoft .NET Framework assembly that contains Windows PowerShell providers and\/or cmdlets. Windows PowerShell includes a set of basic snap-ins, but you can extend the power and value of Windows PowerShell by adding snap-ins that contain providers and cmdlets that you create or get from others. -When you add a snap-in, the cmdlets and providers that it contains are immediately available for use in the current session, but the change affects only the current session. +A Windows PowerShell snap-in is a Microsoft .NET Framework assembly that +contains Windows PowerShell providers and\/or cmdlets. Windows PowerShell +includes a set of basic snap-ins, but you can extend the power and value of +Windows PowerShell by adding snap-ins that contain providers and cmdlets that +you create or get from others. -To add the snap-in to all future sessions, save it in your Windows PowerShell profile. You can also use the Export-Console cmdlet to save the snap-in names to a console file and then use it in future sessions. You can even save multiple console files, each with a different set of snap-ins. +When you add a snap-in, the cmdlets and providers that it contains are +immediately available for use in the current session, but the change affects +only the current session. -NOTE: Windows PowerShell snap-ins (PSSnapins) are available for use in Windows PowerShell 3.0 and Windows PowerShell 2.0. They might be altered or unavailable in subsequent versions. To package Windows PowerShell cmdlets and providers, use modules. For information about creating modules and converting snap-ins to modules, see "Writing a Windows PowerShell Module" in MSDN at http:\/\/go.microsoft.com\/fwlink\/?LinkID\=141556. +To add the snap-in to all future sessions, save it in your Windows PowerShell +profile. You can also use the Export-Console cmdlet to save the snap-in names +to a console file and then use it in future sessions. You can even save +multiple console files, each with a different set of snap-ins. +NOTE: Windows PowerShell snap-ins (PSSnapins) are available for use in Windows +PowerShell 3.0 and Windows PowerShell 2.0. They might be altered or +unavailable in subsequent versions. To package Windows PowerShell cmdlets and +providers, use modules. For information about creating modules and converting +snap-ins to modules, see [Writing a Windows PowerShell Module](http://go.microsoft.com/fwlink/?LinkID=141556) +in the MSDN library. ### FINDING SNAP-INS -To get a list of the Windows PowerShell snap-ins on your computer, type: +To get a list of the Windows PowerShell snap-ins on your computer, type: -``` +```powershell get-pssnapin ``` - To get the snap-in for each Windows PowerShell provider, type: - -``` +```powershell get-psprovider | format-list name, pssnapin ``` - To get a list of the cmdlets in a Windows PowerShell snap-in, type: - -``` +```powershell get-command -module ``` - - ### INSTALLING A SNAP-IN -The built-in snap-ins are registered in the system and added to the default session when you start Windows PowerShell. However, you have to register snap-ins that you create or obtain from others and then add the snap-ins to your session. +The built-in snap-ins are registered in the system and added to the default +session when you start Windows PowerShell. However, you have to register +snap-ins that you create or obtain from others and then add the snap-ins to +your session. ### REGISTERING A SNAP-IN -A Windows PowerShell snap-in is a program written in a .NET Framework language that is compiled into a .dll file. To use the providers and cmdlets in a snap-in, you must first register the snap-in (add it to the registry). -Most snap-ins include an installation program (an .exe or .msi file) that registers the .dll file for you. However, if you receive a snap-in as a .dll file, you can register it on your system. For more information, see [How to Register Cmdlets, Providers, and Host Applications](https://go.microsoft.com/fwlink/?LinkID=143619) in the MSDN library. +A Windows PowerShell snap-in is a program written in a .NET Framework language +that is compiled into a .dll file. To use the providers and cmdlets in a +snap-in, you must first register the snap-in (add it to the registry). -To get all the registered snap-ins on your system or to verify that a snap-in is registered, type: +Most snap-ins include an installation program (an .exe or .msi file) that +registers the .dll file for you. However, if you receive a snap-in as a .dll +file, you can register it on your system. For more information, see +[How to Register Cmdlets, Providers, and Host Applications](https://go.microsoft.com/fwlink/?LinkID=143619) +in the MSDN library. +To get all the registered snap-ins on your system or to verify that a snap-in +is registered, type: -``` +```powershell get-pssnapin -registered ``` - - ### ADDING THE SNAP-IN TO THE CURRENT SESSION -To add a registered snap-in to the current session, use the Add-PsSnapin cmdlet. For example, to add the Microsoft SQL Server snap-in to the session, type: +To add a registered snap-in to the current session, use the Add-PsSnapin +cmdlet. For example, to add the Microsoft SQL Server snap-in to the session, +type: -``` +```powershell add-pssnapin sql ``` - -After the command is completed, the providers and cmdlets in the snap-in are available in the session. However, they are available only in the current session unless you save them. - +After the command is completed, the providers and cmdlets in the snap-in are +available in the session. However, they are available only in the current +session unless you save them. ### SAVING THE SNAP-INS -To use a snap-in in future Windows PowerShell sessions, add the Add-PsSnapin command to your Windows PowerShell profile. Or, export the snap-in names to a console file. -If you add the Add-PSSnapin command to your profile, it is available in all future Windows PowerShell sessions. If you export the names of the snap-ins in your session, you can use the export file only when you need the snap-ins. +To use a snap-in in future Windows PowerShell sessions, add the Add-PsSnapin +command to your Windows PowerShell profile. Or, export the snap-in names to a +console file. -To add the Add-PsSnapin command to your Windows PowerShell profile, open your profile, paste or type the command, and then save the profile. For more information, see about_Profiles. +If you add the Add-PSSnapin command to your profile, it is available in all +future Windows PowerShell sessions. If you export the names of the snap-ins in +your session, you can use the export file only when you need the snap-ins. -To save the snap-ins from a session in console file (.psc1), use the Export-Console cmdlet. For example, to save the snap-ins in the current session configuration to the NewConsole.psc1 file in the current directory, type: +To add the Add-PsSnapin command to your Windows PowerShell profile, open your +profile, paste or type the command, and then save the profile. For more +information, see about_Profiles. +To save the snap-ins from a session in console file (.psc1), use the +Export-Console cmdlet. For example, to save the snap-ins in the current +session configuration to the NewConsole.psc1 file in the current directory, +type: -``` +```powershell export-console NewConsole ``` - For more information, see Export-Console. - ### OPENING WINDOWS POWERSHELL WITH A CONSOLE FILE -To use a console file that includes the snap-in, start Windows PowerShell (PowerShell.exe) from the command prompt in Cmd.exe or in another Windows PowerShell session. Use the PsConsoleFile parameter to specify the console file that includes the snap-in. For example, the following command starts Windows PowerShell with the NewConsole.psc1 console file: +To use a console file that includes the snap-in, start Windows PowerShell +(PowerShell.exe) from the command prompt in Cmd.exe or in another Windows +PowerShell session. Use the PsConsoleFile parameter to specify the console +file that includes the snap-in. For example, the following command starts +Windows PowerShell with the NewConsole.psc1 console file: -``` +```powershell PowerShell.exe -psconsolefile NewConsole.psc1 ``` - The providers and cmdlets in the snapin are now available for use in the session. - ### REMOVING A SNAP-IN -To remove a Windows PowerShell snap-in from the current session, use the Remove-PsSnapin cmdlet. For example, to remove the SQL Server snap-in from the current session, type: +To remove a Windows PowerShell snap-in from the current session, use the +Remove-PsSnapin cmdlet. For example, to remove the SQL Server snap-in from the +current session, type: -``` +```powershell remove-pssnapin sql ``` - -This cmdlet removes the snap-in from the session. The snap-in is still loaded, but the providers and cmdlets that it supports are no longer available. - +This cmdlet removes the snap-in from the session. The snap-in is still loaded, +but the providers and cmdlets that it supports are no longer available. ### BUILT-IN COMMANDS -In Windows PowerShell 2.0 and in older-style host programs in Windows PowerShell 3.0 and later, the built-in commands that are installed with Windows PowerShell are packaged in snap-ins that are added automatically to every Windows PowerShell session. - -Beginning in Windows PowerShell 3.0, in newer-style host programs -- those that start sessions by using the InitialSessionState.CreateDefault2 method -- the built-in commands are packaged in modules. The exception is Microsoft.PowerShell.Core, which always appears as a snap-in. The Core snap-in is included in every session by default. The built-in modules are loaded automatically on first-use. -NOTE: Remote sessions, including sessions that are started by using the New-PSSession cmdlet, are older-style sessions in which the built-in commands are packaged in snap-ins. +In Windows PowerShell 2.0 and in older-style host programs in Windows +PowerShell 3.0 and later, the built-in commands that are installed with +Windows PowerShell are packaged in snap-ins that are added automatically to +every Windows PowerShell session. -The following snap-ins (or modules) are installed with Windows PowerShell. - -Microsoft.PowerShell.Core - -Contains providers and cmdlets used to manage the basic features of Windows PowerShell. It includes the FileSystem, Registry, Alias, Environment, Function, and Variable providers and basic cmdlets like Get-Help, Get-Command, and Get-History. - -Microsoft.PowerShell.Host - -Contains cmdlets used by the Windows PowerShell host, such as Start-Transcript and Stop-Transcript. +Beginning in Windows PowerShell 3.0, in newer-style host programs -- those +that start sessions by using the InitialSessionState.CreateDefault2 method -- +the built-in commands are packaged in modules. The exception is +Microsoft.PowerShell.Core, which always appears as a snap-in. The Core snap-in +is included in every session by default. The built-in modules are loaded +automatically on first-use. -Microsoft.PowerShell.Management +NOTE: Remote sessions, including sessions that are started by using the +New-PSSession cmdlet, are older-style sessions in which the built-in commands +are packaged in snap-ins. -Contains cmdlets such as Get-Service and Get-ChildItem that are used to manage Windows-based features. - -Microsoft.PowerShell.Security +The following snap-ins (or modules) are installed with Windows PowerShell. -Contains the Certificate provider and cmdlets used to manage Windows PowerShell security, such as Get-Acl, Get-AuthenticodeSignature, and ConvertTo-SecureString. +- Microsoft.PowerShell.Core - Contains providers and cmdlets used to manage + the basic features of Windows PowerShell. It includes the FileSystem, + Registry, Alias, Environment, Function, and Variable providers and basic + cmdlets like Get-Help, Get-Command, and Get-History. -Microsoft.PowerShell.Utility +- Microsoft.PowerShell.Host - Contains cmdlets used by the Windows PowerShell + host, such as Start-Transcript and Stop-Transcript. -Contains cmdlets used to manipulate objects and data, such as Get-Member, Write-Host, and Format-List. +- Microsoft.PowerShell.Management - Contains cmdlets such as Get-Service and + Get-ChildItem that are used to manage Windows-based features. -Microsoft.WSMan.Management +- Microsoft.PowerShell.Security - Contains the Certificate provider and + cmdlets used to manage Windows PowerShell security, such as Get-Acl, + Get-AuthenticodeSignature, and ConvertTo-SecureString. -Contains the WSMan provider and cmdlets that manage the Windows Remote Management service, such as Connect-WSMan and Enable-WSManCredSSP. +- Microsoft.PowerShell.Utility - Contains cmdlets used to manipulate objects + and data, such as Get-Member, Write-Host, and Format-List. +- Microsoft.WSMan.Management - Contains the WSMan provider and cmdlets that + manage the Windows Remote Management service, such as Connect-WSMan and + Enable-WSManCredSSP. ## LOGGING SNAP-IN EVENTS -Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets in Windows PowerShell modules and snap-ins by setting the LogPipelineExecutionDetails property of modules and snap-ins to TRUE. For more information, see about_EventLogs (http:\/\/go.microsoft.com\/fwlink\/?LinkID\=113224). +Beginning in Windows PowerShell 3.0, you can record execution events for the +cmdlets in Windows PowerShell modules and snap-ins by setting the +LogPipelineExecutionDetails property of modules and snap-ins to TRUE. For more +information, see [about_EventLogs](about_EventLogs.md). ## SEE ALSO -Add-PsSnapin +[Add-PsSnapin](../Add-PsSnapin.md) -Get-PsSnapin +[Get-PsSnapin](../Get-PsSnapin.md) -Remove-PsSnapin +[Remove-PsSnapin](../Remove-PsSnapin.md) -Export-Console +[Export-Console](../Export-Console.md) -Get-Command +[Get-Command](../Get-Command.md) [about_Profiles](about_Profiles.md) [about_Modules](about_Modules.md) - -## KEYWORDS: +## KEYWORDS about_Snapins, about_Snap_ins, about_Snap-ins - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters.md index 28a776a008a3..b74b7e5b0cb0 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,197 +7,227 @@ title: about_Parameters --- # About Parameters -## about_Parameters - ## SHORT DESCRIPTION -Describes how to work with command parameters in Windows PowerShell? +Describes how to work with command parameters in PowerShell. ## LONG DESCRIPTION -Most Windows PowerShell commands, such as cmdlets, functions, and scripts, rely on parameters to allow users to select options or provide input. The parameters follow the command name and have the following form: +Most PowerShell commands, such as cmdlets, functions, and scripts, +rely on parameters to allow users to select options or provide input. The +parameters follow the command name and have the following form: ``` - ``` +The name of the parameter is preceded by a hyphen (-), which signals to +Windows PowerShell that the word following the hyphen is a parameter name. +Some parameters do not require or accept a parameter value. Other parameters +require a value, but do not require the parameter name in the command. -The name of the parameter is preceded by a hyphen (-), which signals to Windows PowerShell that the word following the hyphen is a parameter name. Some parameters do not require or accept a parameter value. Other parameters require a value, but do not require the parameter name in the command. - -The type of parameters and the requirements for those parameters vary. To find information about the parameters of a command, use the Get-Help cmdlet. For example, to find information about the parameters of the Get-ChildItem cmdlet, type: +The type of parameters and the requirements for those parameters vary. To find +information about the parameters of a command, use the Get-Help cmdlet. For +example, to find information about the parameters of the Get-ChildItem cmdlet, +type: -``` +```powershell Get-Help Get-ChildItem ``` +To find information about the parameters of a script, use the full path to the +script file. For example: -To find information about the parameters of a script, use the full path to the script file. For example: - - -``` +```powershell Get-Help $home\Documents\Scripts\Get-Function.ps1 ``` +The Get-Help cmdlet returns various details about the command, including a +description, the command syntax, information about the parameters, and +examples showing how to use the parameters in a command. -The Get-Help cmdlet returns various details about the command, including a description, the command syntax, information about the parameters, and examples showing how to use the parameters in a command. - -You can also use the Parameter parameter of the Get-Help cmdlet to find information about a particular parameter. Or, you can use the Parameter parameter with the wildcard character (\*) value to find information about all parameters of the command. For example, the following command gets information about all parameters of the Get-Member cmdlet: +You can also use the Parameter parameter of the Get-Help cmdlet to find +information about a particular parameter. Or, you can use the Parameter +parameter with the wildcard character (\*) value to find information about all +parameters of the command. For example, the following command gets information +about all parameters of the Get-Member cmdlet: -``` +```powershell Get-Help Get-Member -Parameter * ``` ### DEFAULT PARAMETER VALUES -Optional parameters have a default value, which is the value that is used or assumed when the parameter is not specified in the command. -For example, the default value of the ComputerName parameter of many cmdlets is the name of the local computer. As a result, the local computer name is used in the command unless the ComputerName parameter is specified. +Optional parameters have a default value, which is the value that is used or +assumed when the parameter is not specified in the command. -To find the default parameter value, see help topic for the cmdlet. The parameter description should include the default value. +For example, the default value of the ComputerName parameter of many cmdlets +is the name of the local computer. As a result, the local computer name is +used in the command unless the ComputerName parameter is specified. -You can also set a custom default value for any parameter of a cmdlet or advanced function. For information about setting custom default values, see about_Parameters_Default_Values. +To find the default parameter value, see help topic for the cmdlet. The +parameter description should include the default value. +You can also set a custom default value for any parameter of a cmdlet or +advanced function. For information about setting custom default values, see +[about_Parameters_Default_Values](about_Parameters_Default_Values.md). ### PARAMETER ATTRIBUTE TABLE -When you use the Full, Parameter, or Online parameters of the Get-Help cmdlet, Get-Help displays a parameter attribute table with detailed information about the parameter. -This information includes the details you need to know to use the parameter. For example, the help topic for the Get-ChildItem cmdlet includes the following details about its Path parameter: +When you use the Full, Parameter, or Online parameters of the Get-Help cmdlet, +Get-Help displays a parameter attribute table with detailed information about +the parameter. + +This information includes the details you need to know to use the parameter. +For example, the help topic for the Get-ChildItem cmdlet includes the +following details about its Path parameter: ``` --path - Specifies a path of one or more locations. Wildcard characters are +-path + Specifies a path of one or more locations. Wildcard characters are permitted. The default location is the current directory (.). -``` - - -``` -Required? false -Position? 1 -Default value Current directory -Accept pipeline input? true (ByValue, ByPropertyName) +Required? false +Position? 1 +Default value Current directory +Accept pipeline input? true (ByValue, ByPropertyName) Accept wildcard characters? true ``` +The parameter information includes the parameter syntax, a description of the +parameter, and the parameter attributes. The following sections describe the +parameter attributes. -The parameter information includes the parameter syntax, a description of the parameter, and the parameter attributes. The following sections describe the parameter attributes. +#### Parameter Required? -Parameter Required? +This setting indicates whether the parameter is mandatory, that is, whether +all commands that use this cmdlet must include this parameter. When the value +is "True" and the parameter is missing from the command, Windows PowerShell +prompts you for a value for the parameter. -This setting indicates whether the parameter is mandatory, that is, whether all commands that use this cmdlet must include this parameter. When the value is "True" and the parameter is missing from the command, Windows PowerShell prompts you for a value for the parameter. +#### Parameter Position? -Parameter Position? +This setting indicates whether you can supply a parameter's value without +preceding it with the parameter name. If set to "0" or "named," a parameter +name is required. This type of parameter is referred to as a named parameter. +A named parameter can be listed in any position after the cmdlet name. -This setting indicates whether you can supply a parameter's value without preceding it with the parameter name. If set to "0" or "named," a parameter name is required. This type of parameter is referred to as a named parameter. A named parameter can be listed in any position after the cmdlet name. +If the "Parameter position?" setting is set to an integer other than 0, the +parameter name is not required. This type of parameter is referred to as a +positional parameter, and the number indicates the position in which the +parameter must appear in relation to other positional parameters. If you +include the parameter name for a positional parameter, the parameter can be +listed in any position after the cmdlet name. -If the "Parameter position?" setting is set to an integer other than 0, the parameter name is not required. This type of parameter is referred to as a positional parameter, and the number indicates the position in which the parameter must appear in relation to other positional parameters. If you include the parameter name for a positional parameter, the parameter can be listed in any position after the cmdlet name. +For example, the Get-ChildItem cmdlet has Path and Exclude parameters. The +"Parameter position?" setting for Path is 1, which means that it is a +positional parameter. The "Parameter position?" setting for Exclude is 0, +which means that it is a named parameter. -For example, the Get-ChildItem cmdlet has Path and Exclude parameters. The "Parameter position?" setting for Path is 1, which means that it is a positional parameter. The "Parameter position?" setting for Exclude is 0, which means that it is a named parameter. +This means that Path does not require the parameter name, but its parameter +value must be the first or only unnamed parameter value in the command. +However, because the Exclude parameter is a named parameter, you can place it +in any position in the command. -This means that Path does not require the parameter name, but its parameter value must be the first or only unnamed parameter value in the command. However, because the Exclude parameter is a named parameter, you can place it in any position in the command. +As a result of the "Parameter position?" settings for these two parameters, +you can use any of the following commands: -As a result of the "Parameter position?" settings for these two parameters, you can use any of the following commands: - -``` -Get-ChildItem -path c:\techdocs -exclude *.ppt -Get-ChildItem c:\techdocs -exclude *.ppt -Get-ChildItem -exclude *.ppt -path c:\techdocs +```powershell +Get-ChildItem -path c:\techdocs -exclude *.ppt +Get-ChildItem c:\techdocs -exclude *.ppt +Get-ChildItem -exclude *.ppt -path c:\techdocs Get-ChildItem -exclude *.ppt c:\techdocs ``` +If you were to include another positional parameter without including the +parameter name, that parameter would have to be placed in the order specified +by the "Parameter position?" setting. -If you were to include another positional parameter without including the parameter name, that parameter would have to be placed in the order specified by the "Parameter position?" setting. +#### Parameter Type -Parameter Type +This setting specifies the Microsoft .NET Framework type of the parameter +value. For example, if the type is Int32, the parameter value must be an +integer. If the type is string, the parameter value must be a character +string. If the string contains spaces, the value must be enclosed in quotation +marks, or the spaces must be preceded by the escape character (`). -This setting specifies the Microsoft .NET Framework type of the parameter value. For example, if the type is Int32, the parameter value must be an integer. If the type is string, the parameter value must be a character string. If the string contains spaces, the value must be enclosed in quotation marks, or the spaces must be preceded by the escape character (`). +#### Default Value -Default Value +This setting specifies the value that the parameter will assume if no other +value is provided. For example, the default value of the Path parameter is +often the current directory. Required parameters never have a default value. +For many optional parameters, there is no default because the parameter has no +effect if it is not used. -This setting specifies the value that the parameter will assume if no other value is provided. For example, the default value of the Path parameter is often the current directory. Required parameters never have a default value. For many optional parameters, there is no default because the parameter has no effect if it is not used. +#### Accepts Multiple Values? -Accepts Multiple Values? +This setting indicates whether a parameter accepts multiple parameter values. +When a parameter accepts multiple values, you can type a comma-separated list +as the value of the parameter in the command, or save a comma-separated list +(an array) in a variable, and then specify the variable as the parameter +value. -This setting indicates whether a parameter accepts multiple parameter values. When a parameter accepts multiple values, you can type a comma-separated list as the value of the parameter in the command, or save a comma-separated list (an array) in a variable, and then specify the variable as the parameter value. +For example, the ServiceName parameter of the Get-Service cmdlet accepts +multiple values. The following commands are both valid: -For example, the ServiceName parameter of the Get-Service cmdlet accepts multiple values. The following commands are both valid: - - -``` +```powershell get-service -servicename winrm, netlogon ``` - - -``` -$s = "winrm", "netlogon" +```powershell +$s = "winrm", "netlogon" get-service -servicename $s ``` +#### Accepts Pipeline Input? -Accepts Pipeline Input? - -This setting indicates whether you can use the pipeline operator (|) to send a value to the parameter. - +This setting indicates whether you can use the pipeline operator (|) to +send a value to the parameter. ``` -Value Description ------ ----------- -False Indicates that you cannot pipe a value to the +Value Description +----- ----------- +False Indicates that you cannot pipe a value to the parameter. -``` - - -``` -True (by Value) Indicates that you can pipe any value to the - parameter, just so the value has the .NET - Framework type specified for the parameter or the - value can be converted to the specified .NET +True (by Value) Indicates that you can pipe any value to the + parameter, just so the value has the .NET + Framework type specified for the parameter or the + value can be converted to the specified .NET Framework type. ``` - - -``` -When a parameter is "True (by Value)", Windows -PowerShell tries to associate any piped values -with that parameter before it tries other methods -to interpret the command. -``` - - +When a parameter is "True (by Value)", Windows PowerShell tries to associate +any piped values with that parameter before it tries other methods to +interpret the command. ``` -True (by Property Name) Indicates that you can pipe a value to the - parameter, but the .NET Framework type of the - parameter must include a property with the same +True (by Property Name) Indicates that you can pipe a value to the + parameter, but the .NET Framework type of the + parameter must include a property with the same name as the parameter. ``` +For example, you can pipe a value to a Name parameter only when the value has +a property called "Name". +#### Accepts Wildcard Characters? -``` -For example, you can pipe a value to a Name -parameter only when the value has a property -called "Name". -``` - - -Accepts Wildcard Characters? - -This setting indicates whether the parameter's value can contain wildcard characters so that the parameter value can be matched to more than one existing item in the target container. +This setting indicates whether the parameter's value can contain wildcard +characters so that the parameter value can be matched to more than one +existing item in the target container. -Common Parameters - -Common parameters are parameters that you can use with any cmdlet. For more information about common parameters, see about_CommonParameters +#### Common Parameters +Common parameters are parameters that you can use with any cmdlet. For more +information about common parameters, see [about_CommonParameters](about_CommonParameters.md). ## SEE ALSO @@ -212,4 +242,3 @@ Common parameters are parameters that you can use with any cmdlet. For more info [about_Pipelines](about_Pipelines.md) [about_Wildcards](about_Wildcards.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md index 7d8eb37366e3..39bf01d2725e 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,21 +7,20 @@ title: about_PowerShell_exe --- # About PowerShell.exe -## about_PowerShell.exe +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use the PowerShell.exe command-line tool. Displays the syntax +and describes the command-line switches. -Explains how to use the PowerShell.exe command-line tool. Displays -the syntax and describes the command-line switches. +PowerShell.exe starts a Windows PowerShell session. You can use it in Cmd.exe +and in Windows PowerShell. -PowerShell.exe starts a Windows PowerShell session. You can use it -in Cmd.exe and in Windows PowerShell. +## LONG DESCRIPTION -# LONG DESCRIPTION - -# SYNTAX +### SYNTAX +``` PowerShell[.exe] [-EncodedCommand ] [-ExecutionPolicy ] @@ -39,137 +38,143 @@ PowerShell[.exe] [-Command { - | [-args ] | [] } ] PowerShell[.exe] -Help | -? | /? +``` + +### PARAMETERS + +#### -EncodedCommand + +Accepts a base-64-encoded string version of a command. Use this parameter to +submit commands to Windows PowerShell that require complex quotation marks or +curly braces. + +#### -ExecutionPolicy + +Sets the default execution policy for the current session and saves it in the +$env:PSExecutionPolicyPreference environment variable. This parameter does not +change the Windows PowerShell execution policy that is set in the registry. +For information about Windows PowerShell execution policies, including a list +of valid values, see [about_Execution_Policies](about_Execution_Policies.md). + +#### -File [] + +Runs the specified script in the local scope ("dot-sourced"), so that the +functions and variables that the script creates are available in the current +session. Enter the script file path and any parameters. File must be the last +parameter in the command, because all characters typed after the File +parameter name are interpreted as the script file path followed by the script +parameters. + +You can include the parameters of a script, and parameter values, in the value +of the File parameter. For example: -File .\\Get-Script.ps1 -Domain Central + +Typically, the switch parameters of a script are either included or omitted. +For example, the following command uses the All parameter of the +Get-Script.ps1 script file: -File .\\Get-Script.ps1 -All + +In rare cases, you might need to provide a Boolean value for a switch +parameter. To provide a Boolean value for a switch parameter in the value of +the File parameter, enclose the parameter name and value in curly braces, such +as the following: -File .\\Get-Script.ps1 {-All:$False}. + +#### -InputFormat {Text | XML} + +Describes the format of data sent to Windows PowerShell. Valid values are +"Text" (text strings) or "XML" (serialized CLIXML format). + +#### -Mta + +Starts Windows PowerShell using a multi-threaded apartment. This parameter is +introduced in Windows PowerShell 3.0. In Windows PowerShell 2.0, +multi-threaded apartment (MTA) is the default. In Windows PowerShell 3.0, +single-threaded apartment (STA) is the default. + +#### -NoExit -# PARAMETERS - - --EncodedCommand -Accepts a base-64-encoded string version of a command. -Use this parameter to submit commands to Windows PowerShell -that require complex quotation marks or curly braces. - --ExecutionPolicy -Sets the default execution policy for the current session -and saves it in the $env:PSExecutionPolicyPreference environment -variable. This parameter does not change the Windows PowerShell -execution policy that is set in the registry. For information -about Windows PowerShell execution policies, including a list -of valid values, see about_Execution_Policies -(http://go.microsoft.com/fwlink/?LinkID=135170). - --File [] -Runs the specified script in the local scope ("dot-sourced"), -so that the functions and variables that the script creates -are available in the current session. Enter the script file -path and any parameters. File must be the last parameter in -the command, because all characters typed after the File -parameter name are interpreted as the script file path followed -by the script parameters. - -You can include the parameters of a script, and parameter -values, in the value of the File parameter. For example: --File .\Get-Script.ps1 -Domain Central - -Typically, the switch parameters of a script are either -included or omitted. For example, the following command -uses the All parameter of the Get-Script.ps1 script file: --File .\Get-Script.ps1 -All - -In rare cases, you might need to provide a Boolean value -for a switch parameter. To provide a Boolean value for a -switch parameter in the value of the File parameter, -enclose the parameter name and value in curly braces, -such as the following: --File .\Get-Script.ps1 {-All:$False}. - --InputFormat {Text | XML} -Describes the format of data sent to Windows PowerShell. Valid -values are "Text" (text strings) or "XML" (serialized CLIXML format). - --Mta -Starts Windows PowerShell using a multi-threaded apartment. This -parameter is introduced in Windows PowerShell 3.0. In Windows -PowerShell 2.0, multi-threaded apartment (MTA) is the default. -In Windows PowerShell 3.0, single-threaded apartment (STA) is -the default. - --NoExit Does not exit after running startup commands. --NoLogo +#### -NoLogo + Hides the copyright banner at startup. --NonInteractive +#### -NonInteractive + Does not present an interactive prompt to the user. --NoProfile +#### -NoProfile + Does not load the Windows PowerShell profile. --OutputFormat {Text | XML} -Determines how output from Windows PowerShell is formatted. -Valid values are "Text" (text strings) or "XML" (serialized -CLIXML format). - --PSConsoleFile -Loads the specified Windows PowerShell console file. Enter -the path and name of the console file. To create a console file, -use the Export-Console cmdlet in Windows PowerShell. - --Sta -Starts Windows PowerShell using a single-threaded apartment. In -Windows PowerShell 2.0, multi-threaded apartment (MTA) is the default. -In Windows PowerShell 3.0, single-threaded apartment (STA) is the -default. - --Version -Starts the specified version of Windows PowerShell. Valid values -are 2.0 and 3.0. The version that you specify must be installed -on the system. If Windows PowerShell 3.0 is installed on the -computer, "3.0" is the default version. Otherwise, "2.0" is the -default version. For more information, see "Installing Windows -PowerShell" in the Windows PowerShell Getting Started Guide. - --WindowStyle -Sets the window style for the session. Valid values are Normal, -Minimized, Maximized and Hidden. - --Command -Executes the specified commands (and any parameters) as though -they were typed at the Windows PowerShell command prompt, and -then exits, unless the NoExit parameter is specified. - -The value of Command can be "-", a string. or a script block. If -the value of Command is "-", the command text is read from standard -input. - -Script blocks must be enclosed in braces ({}). You can specify a -script block only when running PowerShell.exe in Windows PowerShell. -The results of the script are returned to the parent shell as -deserialized XML objects, not live objects. - -If the value of Command is a string, Command must be the last -parameter in the command , because any characters typed after -the command are interpreted as the command arguments. +#### -OutputFormat {Text | XML} + +Determines how output from Windows PowerShell is formatted. Valid values are +"Text" (text strings) or "XML" (serialized CLIXML format). + +#### -PSConsoleFile + +Loads the specified Windows PowerShell console file. Enter the path and name +of the console file. To create a console file, use the Export-Console cmdlet +in Windows PowerShell. + +#### -Sta + +Starts Windows PowerShell using a single-threaded apartment. In Windows +PowerShell 2.0, multi-threaded apartment (MTA) is the default. In Windows +PowerShell 3.0, single-threaded apartment (STA) is the default. + +#### -Version + +Starts the specified version of Windows PowerShell. Valid values are 2.0 and +3.0. The version that you specify must be installed on the system. If Windows +PowerShell 3.0 is installed on the computer, "3.0" is the default version. +Otherwise, "2.0" is the default version. For more information, see "Installing +Windows PowerShell" in the Windows PowerShell Getting Started Guide. + +#### -WindowStyle + +Sets the window style for the session. Valid values are Normal, Minimized, +Maximized and Hidden. + +#### -Command + +Executes the specified commands (and any parameters) as though they were typed +at the Windows PowerShell command prompt, and then exits, unless the NoExit +parameter is specified. + +The value of Command can be "-", a string. or a script block. If the value of +Command is "-", the command text is read from standard input. + +Script blocks must be enclosed in braces ({}). You can specify a script block +only when running PowerShell.exe in Windows PowerShell. The results of the +script are returned to the parent shell as deserialized XML objects, not live +objects. + +If the value of Command is a string, Command must be the last parameter in the +command , because any characters typed after the command are interpreted as +the command arguments. To write a string that runs a Windows PowerShell command, use the format: + "& {}" -where the quotation marks indicate a string and the invoke operator -(&) causes the command to be executed. --Help, -?, /? -Displays help for PowerShell.exe. If you are typing a PowerShell.exe -command in Windows PowerShell, prepend the command parameters with a -hyphen (-), not a forward slash (/). You can use either a hyphen or -forward slash in Cmd.exe. +where the quotation marks indicate a string and the invoke operator (&) causes +the command to be executed. -# REMARKS: +#### -Help, -?, /? -Troubleshooting note: In Windows PowerShell 2.0, starting some programs -from the Windows PowerShell console fails with a LastExitCode of 0xc0000142. +Displays help for PowerShell.exe. If you are typing a PowerShell.exe command +in Windows PowerShell, prepend the command parameters with a hyphen (-), not a +forward slash (/). You can use either a hyphen or forward slash in Cmd.exe. -# EXAMPLES +### REMARKS +Troubleshooting note: In Windows PowerShell 2.0, starting some programs from +the Windows PowerShell console fails with a LastExitCode of 0xc0000142. + +### EXAMPLES + +```powershell PowerShell -PSConsoleFile sqlsnapin.psc1 PowerShell -Version 2.0 -NoLogo -InputFormat text -OutputFormat XML @@ -177,5 +182,4 @@ PowerShell -Version 2.0 -NoLogo -InputFormat text -OutputFormat XML PowerShell -Command {Get-EventLog -LogName security} PowerShell -Command "& {Get-EventLog -LogName security}" - - +``` \ No newline at end of file diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 6781e0765962..8df82dca043b 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,290 +7,272 @@ title: about_Quoting_Rules --- # About Quoting Rules -## about_Quoting_Rules - ## SHORT DESCRIPTION -Describes rules for using single and double quotation marks in Windows PowerShell? +Describes rules for using single and double quotation marks in PowerShell. ## LONG DESCRIPTION -Quotation marks are used to specify a literal string. You can enclose a string in single quotation marks (') or double quotation marks ("). -Quotation marks are also used to create a here-string. A here-string is a single-quoted or double-quoted string in which quotation marks are interpreted literally. A here-string can span multiple lines. All the lines in a here-string are interpreted as strings, even though they are not enclosed in quotation marks. +Quotation marks are used to specify a literal string. You can enclose a string +in single quotation marks (') or double quotation marks ("). -In commands to remote computers, quotation marks define the parts of the command that are run on the remote computer. In a remote session, quotation marks also determine whether the variables in a command are interpreted first on the local computer or on the remote computer. +Quotation marks are also used to create a here-string. A here-string is a +single-quoted or double-quoted string in which quotation marks are interpreted +literally. A here-string can span multiple lines. All the lines in a +here-string are interpreted as strings, even though they are not enclosed in +quotation marks. +In commands to remote computers, quotation marks define the parts of the +command that are run on the remote computer. In a remote session, quotation +marks also determine whether the variables in a command are interpreted first +on the local computer or on the remote computer. ### SINGLE AND DOUBLE-QUOTED STRINGS -When you enclose a string in double quotation marks (a double-quoted string), variable names that are preceded by a dollar sign ($) are replaced with the variable's value before the string is passed to the command for processing. -For example: +When you enclose a string in double quotation marks (a double-quoted string), +variable names that are preceded by a dollar sign ($) are replaced with the +variable's value before the string is passed to the command for processing. +For example: -``` +```powershell $i = 5 "The value of $i is $i." ``` - The output of this command is: - -``` +```output The value of 5 is 5. ``` +Also, in a double-quoted string, expressions are evaluated, and the result is +inserted in the string. For example: -Also, in a double-quoted string, expressions are evaluated, and the result is inserted in the string. For example: - - -``` +```powershell "The value of $(2+3) is 5." ``` - The output of this command is: - -``` +```output The value of 5 is 5. ``` +When you enclose a string in single-quotation marks (a single-quoted string), +the string is passed to the command exactly as you type it. No substitution is +performed. For example: -When you enclose a string in single-quotation marks (a single-quoted string), the string is passed to the command exactly as you type it. No substitution is performed. For example: - - -``` +```powershell $i = 5 'The value of $i is $i.' ``` - The output of this command is: - -``` +```output The value $i is $i. ``` +Similarly, expressions in single-quoted strings are not evaluated. They are +interpreted as literals. For example: -Similarly, expressions in single-quoted strings are not evaluated. They are interpreted as literals. For example: - - -``` +```powershell 'The value of $(2+3) is 5.' ``` - The output of this command is: - -``` +```output The value of $(2+3) is 5. ``` +To prevent the substitution of a variable value in a double-quoted string, use +the backtick character (`)(ASCII 96), which is the Windows PowerShell escape +character. -To prevent the substitution of a variable value in a double-quoted string, use the backtick character (`)(ASCII 96), which is the Windows PowerShell escape character. - -In the following example, the backtick character that precedes the first $i variable prevents Windows PowerShell from replacing the variable name with its value. For example: - +In the following example, the backtick character that precedes the first $i +variable prevents Windows PowerShell from replacing the variable name with its +value. For example: -``` +```powershell $i = 5 "The value of `$i is $i." ``` - The output of this command is: - -``` +```output The value $i is 5. ``` +To make double-quotation marks appear in a string, enclose the entire string +in single quotation marks. For example: -To make double-quotation marks appear in a string, enclose the entire string in single quotation marks. For example: - - -``` +```powershell 'As they say, "live and learn."' ``` - The output of this command is: - -``` +```output As they say, "live and learn." ``` +You can also enclose a single-quoted string in a double-quoted string. For +example: -You can also enclose a single-quoted string in a double-quoted string. For example: - - -``` +```powershell "As they say, 'live and learn.'" ``` - The output of this command is: - -``` +```output As they say, 'live and learn.' ``` - Or, double the quotation marks around a double-quoted phrase. For example: - -``` +```powershell "As they say, ""live and learn.""" ``` - The output of this command is: - -``` +```output As they say, "live and learn." ``` +To include a single quotation mark in a single-quoted string, use a second +consecutive single quote. For example: -To include a single quotation mark in a single-quoted string, use a second consecutive single quote. For example: - - -``` +```powershell 'don''t' ``` - The output of this command is: - -``` +```output don't ``` +To force Windows PowerShell to interpret a double quotation mark literally, +use a backtick character. This prevents Windows PowerShell from interpreting +the quotation mark as a string delimiter. For example: -To force Windows PowerShell to interpret a double quotation mark literally, use a backtick character. This prevents Windows PowerShell from interpreting the quotation mark as a string delimiter. For example: - - -``` +```powershell "Use a quotation mark (`") to begin a string." ``` +Because the contents of single-quoted strings are interpreted literally, you +cannot use the backtick character to force a literal character interpretation +in a single-quoted string. -Because the contents of single-quoted strings are interpreted literally, you cannot use the backtick character to force a literal character interpretation in a single-quoted string. - -For example, the following command generates an error because Windows PowerShell does not recognize the escape character. Instead, it interprets the second quotation mark as the end of the string. - +For example, the following command generates an error because Windows +PowerShell does not recognize the escape character. Instead, it interprets the +second quotation mark as the end of the string. -``` +```output PS C:\> 'Use a quotation mark (`') to begin a string.' Unexpected token ')' in expression or statement. At line:1 char:27 + 'Use a quotation mark (`') <<<< to begin a string.' ``` - - ### HERE-STRINGS + The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation marks are interpreted literally. A here-string can span multiple lines. All the lines in a here-string are interpreted as strings even though they are not enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string in which quotation +marks are interpreted literally. A here-string can span multiple lines. All +the lines in a here-string are interpreted as strings even though they are not +enclosed in quotation marks. -Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by their values. +Like regular strings, variables are replaced by their values in double-quoted +here-strings. In single-quoted here-strings, variables are not replaced by +their values. -You can use here-strings for any text, but they are particularly useful for the following kinds of text: +You can use here-strings for any text, but they are particularly useful for +the following kinds of text: --- Text that contains literal quotation marks --- Multiple lines of text, such as the text in an HTML or XML --- The Help text for a script or function document +- Text that contains literal quotation marks +- Multiple lines of text, such as the text in an HTML or XML +- The Help text for a script or function document -A here-string can have either of the following formats, where represents the linefeed or newline hidden character that is added when you press the ENTER key. +A here-string can have either of the following formats, where \ +represents the linefeed or newline hidden character that is added when you +press the ENTER key. +Double-quotes: ``` -Double-quotes: - @" - [string] ... - "@ +@" + [string] ... +"@ ``` - - -``` Single-quotes: - @' - [string] ... - '@ +``` +@' + [string] ... +'@ ``` +In either format, the closing quotation mark must be the first character in +the line. -In either format, the closing quotation mark must be the first character in the line. - -A here-string contains all the text between the two hidden characters. In the here-string, all quotation marks are interpreted literally. For example: - +A here-string contains all the text between the two hidden characters. In the +here-string, all quotation marks are interpreted literally. For example: -``` +```powershell @" For help, type "get-help" "@ ``` - The output of this command is: - -``` +```output For help, type "get-help" ``` - Using a here-string can simplify using a string in a command. For example: - -``` +```powershell @" Use a quotation mark (') to begin a string. "@ ``` - The output of this command is: - -``` +```output Use a quotation mark (') to begin a string. ``` +In single-quoted here-strings, variables are interpreted literally and +reproduced exactly. For example: -In single-quoted here-strings, variables are interpreted literally and reproduced exactly. For example: - - -``` +```powershell @' The $profile variable contains the path of your Windows PowerShell profile. '@ ``` - The output of this command is: - -``` +```output The $profile variable contains the path of your Windows PowerShell profile. ``` +In double-quoted here-strings, variables are replaced by their values. For +example: -In double-quoted here-strings, variables are replaced by their values. For example: - - -``` +```powershell @" Even if you have not created a profile, the path of the profile file is: @@ -298,21 +280,19 @@ $profile. "@ ``` - The output of this command is: - -``` +```output Even if you have not created a profile, the path of the profile file is: -C:\Users\User01\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1. +C:\Users\User1\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1. ``` +Here-strings are typically used to assign multiple lines to a variable. For +example, the following here-string assigns a page of XML to the $page +variable. -Here-strings are typically used to assign multiple lines to a variable. For example, the following here-string assigns a page of XML to the $page variable. - - -``` +```powershell $page = [XML] @" "@ ``` - -Here-strings are also a convenient format for input to the ConvertFrom-StringData cmdlet, which converts here-strings to hash tables. For more information, see ConvertFrom-StringData. - - -## KEYWORDS -about_Here-Strings - -about_Quotes - -about_Quotation_Marks - +Here-strings are also a convenient format for input to the +ConvertFrom-StringData cmdlet, which converts here-strings to hash tables. For +more information, see ConvertFrom-StringData. ## SEE ALSO [about_Special_Characters](about_Special_Characters.md) -ConvertFrom-StringData - +[ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote.md index ac5e0c6fa90a..36455b275f7e 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,73 +7,74 @@ title: about_Remote --- # About Remote -## about_Remote - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes how to run remote commands in Windows PowerShell. -# LONG DESCRIPTION - -You can run remote commands on a single computer or on multiple -computers by using a temporary or persistent connection. You can also -start an interactive session with a single remote computer. +## LONG DESCRIPTION -This topic provides a series of examples to show you how to -run different types of remote command. After you try these basic -commands, read the Help topics that describe each cmdlet that is -used in these commands. The topics provide the details and explain -how you can modify the commands to meet your needs. +You can run remote commands on a single computer or on multiple computers by +using a temporary or persistent connection. You can also start an interactive +session with a single remote computer. -Note: To use Windows PowerShell remoting, the local and remote computers -must be configured for remoting. For more information, see -about_Remote_Requirements. +This topic provides a series of examples to show you how to run different +types of remote command. After you try these basic commands, read the Help +topics that describe each cmdlet that is used in these commands. The topics +provide the details and explain how you can modify the commands to meet your +needs. -# HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION) +Note: To use Windows PowerShell remoting, the local and remote computers must +be configured for remoting. For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). +## HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION) -The easiest way to run remote commands is to start an -interactive session with a remote computer. +The easiest way to run remote commands is to start an interactive session with +a remote computer. -When the session starts, the commands that you type run on the -remote computer, just as though you typed them directly -on the remote computer. You can connect to only one -computer in each interactive session. +When the session starts, the commands that you type run on the remote +computer, just as though you typed them directly on the remote computer. You +can connect to only one computer in each interactive session. -To start an interactive session, use the Enter-PSSession -cmdlet. The following command starts an interactive session -with the Server01 computer: +To start an interactive session, use the Enter-PSSession cmdlet. The following +command starts an interactive session with the Server01 computer: +```powershell Enter-PSSession Server01 +``` -The command prompt changes to indicate that you are connected -to the Server01 computer. +The command prompt changes to indicate that you are connected to the Server01 +computer. +``` Server01\PS> +``` Now, you can type commands on the Server01 computer. To end the interactive session, type: +```powershell Exit-PSSession +``` For more information, see Enter-PSSession. -# HOW TO USE CMDLETS THAT HAVE A COMPUTERNAME PARAMETER TO GET REMOTE DATA +## HOW TO USE CMDLETS THAT HAVE A COMPUTERNAME PARAMETER TO GET REMOTE DATA - -Several cmdlets have a ComputerName parameter that lets you -get objects from remote computers. +Several cmdlets have a ComputerName parameter that lets you get objects from +remote computers. Because these cmdlets do not use WS-Management-based Windows PowerShell remoting, you can use the ComputerName parameter of these cmdlets on any -computer that is running Windows PowerShell. The computers do not have to -be configured for Windows PowerShell remoting, and the computers do not -have to meet the system requirements for remoting. +computer that is running Windows PowerShell. The computers do not have to be +configured for Windows PowerShell remoting, and the computers do not have to +meet the system requirements for remoting. The following cmdlets have a ComputerName parameter: +``` Clear-EventLog Limit-EventLog Get-Counter New-EventLog Get-EventLog Remove-EventLog @@ -82,15 +83,18 @@ Get-Process Show-EventLog Get-Service Stop-Computer Get-WinEvent Test-Connection Get-WmiObject Write-EventLog +``` For example, the following command gets the services on the Server01 remote computer: +```powershell Get-Service -ComputerName Server01 +``` -Typically, cmdlets that support remoting without special configuration -have a **ComputerName** parameter and do not have a **Session** parameter. -To find these cmdlets in your session, type: +Typically, cmdlets that support remoting without special configuration have a +**ComputerName** parameter and do not have a **Session** parameter. To find +these cmdlets in your session, type: ```powershell Get-Command | Where-Object { @@ -99,131 +103,134 @@ Get-Command | Where-Object { } ``` -# HOW TO RUN A REMOTE COMMAND +## HOW TO RUN A REMOTE COMMAND +To run other commands on remote computers, use the Invoke-Command cmdlet. -To run other commands on remote computers, use the -Invoke-Command cmdlet. +To run a single command or a few unrelated commands, use the ComputerName +parameter of Invoke-Command to specify the remote computers. Use the +ScriptBlock parameter to specify the command. -To run a single command or a few unrelated commands, use the -ComputerName parameter of Invoke-Command to specify the remote -computers. Use the ScriptBlock parameter to specify the command. - -For example, the following command runs a Get-Culture command -on the Server01 computer. +For example, the following command runs a Get-Culture command on the Server01 +computer. +```powershell Invoke-Command -ComputerName Server01 -ScriptBlock {Get-Culture} +``` -The ComputerName parameter is designed for situation in which you run -a single command or several unrelated commands on one or many computers. -To establish a persistent connection to a remote computer, use -the Session parameter. - -# HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION) +The ComputerName parameter is designed for situation in which you run a single +command or several unrelated commands on one or many computers. To establish a +persistent connection to a remote computer, use the Session parameter. +## HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION) -When you use the ComputerName parameter of the Invoke-Command -cmdlet, Windows PowerShell establishes a connection just for the -command. Then, it closes the connection when the command is complete. Any -variables or functions that are defined in the command are lost. +When you use the ComputerName parameter of the Invoke-Command cmdlet, Windows +PowerShell establishes a connection just for the command. Then, it closes the +connection when the command is complete. Any variables or functions that are +defined in the command are lost. -To create a persistent connection to a remote computer, use the -New-PSSession cmdlet. For example, the following command creates -PSSessions on the Server01 and Server02 computers and then saves the -PSSessions in the $s variable. +To create a persistent connection to a remote computer, use the New-PSSession +cmdlet. For example, the following command creates PSSessions on the Server01 +and Server02 computers and then saves the PSSessions in the $s variable. +```powershell $s = New-PSSession -ComputerName Server01, Server02 +``` -# HOW TO RUN COMMANDS IN A PSSESSION - +## HOW TO RUN COMMANDS IN A PSSESSION -With a PSSession, you can run a series of remote commands that -share data, like functions, aliases, and the values of variables. -To run commands in a PSSession, use the Session parameter of the -Invoke-Command cmdlet. +With a PSSession, you can run a series of remote commands that share data, +like functions, aliases, and the values of variables. To run commands in a +PSSession, use the Session parameter of the Invoke-Command cmdlet. -For example, the following command uses the Invoke-Command cmdlet -to run a Get-Process command in the PSSessions on the Server01 -and Server02 computers. The command saves the processes in a $p -variable in each PSSession. +For example, the following command uses the Invoke-Command cmdlet to run a +Get-Process command in the PSSessions on the Server01 and Server02 computers. +The command saves the processes in a $p variable in each PSSession. +```powershell Invoke-Command -Session $s -ScriptBlock {$p = Get-Process} +``` -Because the PSSession uses a persistent connection, you can run -another command in the same PSSession that uses the $p variable. -The following command counts the number of processes saved in $p. +Because the PSSession uses a persistent connection, you can run another +command in the same PSSession that uses the $p variable. The following command +counts the number of processes saved in $p. +```powershell Invoke-Command -Session $s -ScriptBlock {$p.count} +``` -# HOW TO RUN A REMOTE COMMAND ON MULTIPLE COMPUTERS - +## HOW TO RUN A REMOTE COMMAND ON MULTIPLE COMPUTERS -To run a remote command on multiple computers, type all of -the computer names in the value of the ComputerName parameter of -Invoke-Command. Separate the names with commas. +To run a remote command on multiple computers, type all of the computer names +in the value of the ComputerName parameter of Invoke-Command. Separate the +names with commas. -For example, the following command runs a Get-Culture command -on three computers: +For example, the following command runs a Get-Culture command on three +computers: +```powershell Invoke-Command -ComputerName S1, S2, S3 -ScriptBlock {Get-Culture} +``` -You can also run a command in multiple PSSessions. The following -commands create PSSessions on the Server01, Server02, and Server03 -computers and then run a Get-Culture command in each of the PSSessions. +You can also run a command in multiple PSSessions. The following commands +create PSSessions on the Server01, Server02, and Server03 computers and then +run a Get-Culture command in each of the PSSessions. +```powershell $s = New-PSSession -ComputerName S1, S2, S3 Invoke-Command -Session $s -ScriptBlock {Get-Culture} +``` To include the local computer list of computers, type the name of the local computer, type a dot (.), or type "localhost". +```powershell Invoke-Command -ComputerName S1, S2, S3, localhost -ScriptBlock {Get-Culture} +``` -# HOW TO RUN A SCRIPT ON REMOTE COMPUTERS - +## HOW TO RUN A SCRIPT ON REMOTE COMPUTERS -To run a local script on remote computers, use the -FilePath parameter of Invoke-Command. +To run a local script on remote computers, use the FilePath parameter of +Invoke-Command. -For example, the following command runs the Sample.ps1 script -on the S1 and S2 computers: +For example, the following command runs the Sample.ps1 script on the S1 and S2 +computers: +```powershell Invoke-Command -ComputerName S1, S2 -FilePath C:\Test\Sample.ps1 +``` -The results of the script are returned to the local computer. You -do not need to copy any files. - -# HOW TO STOP A REMOTE COMMAND - +The results of the script are returned to the local computer. You do not need +to copy any files. -To interrupt a command, press CTRL+C. The interrupt request is -passed to the remote computer where it terminates the remote command. +## HOW TO STOP A REMOTE COMMAND -# FOR MORE INFORMATION +To interrupt a command, press CTRL+C. The interrupt request is passed to the +remote computer where it terminates the remote command. +## FOR MORE INFORMATION --- For information about the system requirements for remoting, -see about_Remote_Requirements. +- For information about the system requirements for remoting, see + [about_Remote_Requirements](about_Remote_Requirements.md). --- For help in formatting remote output, see about_Remote_Output. +- For help in formatting remote output, see [about_Remote_Output](about_Remote_Output.md). --- For information about how remoting works, how to manage remote -data, special configurations, security issues, and other frequently -asked questions, see about_Remote_FAQ. +- For information about how remoting works, how to manage remote data, special + configurations, security issues, and other frequently asked questions, see + [about_Remote_FAQ](about_Remote_FAQ.md). --- For help in resolving remoting errors, see about_Remote_Troubleshooting. +- For help in resolving remoting errors, see about_Remote_Troubleshooting. --- For information about PSSessions and persistent connections, see -about_PSSessions. +- For information about PSSessions and persistent connections, see + [about_PSSessions](about_PSSessions.md). --- For information about Windows PowerShell background jobs, see -about_Jobs. +- For information about Windows PowerShell background jobs, see [about_Jobs](about_Jobs.md). -# KEYWORDS +## KEYWORDS about_Remoting -# SEE ALSO +## SEE ALSO [about_PSSessions](about_PSSessions.md) @@ -237,9 +244,8 @@ about_Remoting [about_Remote_Variables](about_Remote_Variables.md) -Enter-PSSession - -Invoke-Command +[Enter-PSSession](../Enter-PSSession.md) -New-PSSession +[Invoke-Command](../Invoke-Command.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md index eda447268fcd..445c1fa6f6b9 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,77 +7,71 @@ title: about_Remote_Requirements --- # About Remote Requirements -## about_Remote_Requirements +## SHORT DESCRIPTION +Describes the system requirements and configuration requirements for running +remote commands in Windows PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes the system requirements and configuration requirements for -running remote commands in Windows PowerShell. - -# LONG DESCRIPTION - -This topic describes the system requirements, user requirements, and -resource requirements for establishing remote connections and running -remote commands in Windows PowerShell. It also provides instructions for -configuring remote operations. +This topic describes the system requirements, user requirements, and resource +requirements for establishing remote connections and running remote commands +in Windows PowerShell. It also provides instructions for configuring remote +operations. Note: Many cmdlets (including the Get-Service, Get-Process, Get-WMIObject, -Get-EventLog, and Get-WinEvent cmdlets) get objects from remote -computers by using Microsoft .NET Framework methods to retrieve the -objects. They do not use the Windows PowerShell remoting -infrastructure. The requirements in this document do not apply to -these cmdlets. +Get-EventLog, and Get-WinEvent cmdlets) get objects from remote computers by +using Microsoft .NET Framework methods to retrieve the objects. They do not +use the Windows PowerShell remoting infrastructure. The requirements in this +document do not apply to these cmdlets. -To find the cmdlets that have a ComputerName parameter but do not use -Windows PowerShell remoting, read the description of the ComputerName -parameter of the cmdlets. - -# SYSTEM REQUIREMENTS +To find the cmdlets that have a ComputerName parameter but do not use Windows +PowerShell remoting, read the description of the ComputerName parameter of the +cmdlets. +## SYSTEM REQUIREMENTS To run remote sessions on Windows PowerShell 3.0, the local and remote computers must have the following: --- Windows PowerShell 3.0 or later --- The Microsoft .NET Framework 4 or later --- Windows Remote Management 3.0 +- Windows PowerShell 3.0 or later +- The Microsoft .NET Framework 4 or later +- Windows Remote Management 3.0 -To run remote sessions on Windows PowerShell 2.0, the local and remote computers -must have the following: +To run remote sessions on Windows PowerShell 2.0, the local and remote +computers must have the following: --- Windows PowerShell 2.0 or later --- The Microsoft .NET Framework 2.0 or later --- Windows Remote Management 2.0 +- Windows PowerShell 2.0 or later +- The Microsoft .NET Framework 2.0 or later +- Windows Remote Management 2.0 -You can create remote sessions between computers running Windows PowerShell 2.0 -and Windows PowerShell 3.0. However, features that run only on Windows -PowerShell 3.0, such as the ability to disconnect and reconnect to sessions, are -available only when both computers are running Windows PowerShell 3.0. +You can create remote sessions between computers running Windows PowerShell +2.0 and Windows PowerShell 3.0. However, features that run only on Windows +PowerShell 3.0, such as the ability to disconnect and reconnect to sessions, +are available only when both computers are running Windows PowerShell 3.0. To find the version number of an installed version of Windows PowerShell, use the $PSVersionTable automatic variable. -Windows Remote Management (WinRM) 3.0 and Microsoft .NET Framework 4 are included -in Windows 8, Windows Server 2012, and newer releases of the Windows operating -system. WinRM 3.0 is included in Windows Management Framework 3.0 for older -operating systems. If the computer does not have the required version of -WinRM or the Microsoft .NET Framework, the installation fails. - -# USER PERMISSIONS +Windows Remote Management (WinRM) 3.0 and Microsoft .NET Framework 4 are +included in Windows 8, Windows Server 2012, and newer releases of the Windows +operating system. WinRM 3.0 is included in Windows Management Framework 3.0 +for older operating systems. If the computer does not have the required +version of WinRM or the Microsoft .NET Framework, the installation fails. +## USER PERMISSIONS To create remote sessions and run remote commands, by default, the current user must be a member of the Administrators group on the remote computer or provide the credentials of an administrator. Otherwise, the command fails. The permissions required to create sessions and run commands on a remote -computer (or in a remote session on the local computer) are established by -the session configuration (also known as an "endpoint") on the remote -computer to which the session connects. Specifically, the security -descriptor on the session configuration determines who has access to the -session configuration and who can use it to connect. +computer (or in a remote session on the local computer) are established by the +session configuration (also known as an "endpoint") on the remote computer to +which the session connects. Specifically, the security descriptor on the +session configuration determines who has access to the session configuration +and who can use it to connect. The security descriptors on the default session configurations, Microsoft.PowerShell, Microsoft.PowerShell32, and @@ -85,48 +79,50 @@ Microsoft.PowerShell.Workflow, allow access only to members of the Administrators group. If the current user doesn't have permission to use the session configuration, -the command to run a command (which uses a temporary session) or create -a persistent session on the remote computer fails. The user can use the +the command to run a command (which uses a temporary session) or create a +persistent session on the remote computer fails. The user can use the ConfigurationName parameter of cmdlets that create sessions to select a different session configuration, if one is available. Members of the Administrators group on a computer can determine who has permission to connect to the computer remotely by changing the security -descriptors on the default session configurations and by creating new -session configurations with different security descriptors. +descriptors on the default session configurations and by creating new session +configurations with different security descriptors. For more informations about session configurations, see -about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). +[about_Session_Configurations](about_Session_Configurations.md). -# WINDOWS NETWORK LOCATIONS +## WINDOWS NETWORK LOCATIONS Beginning in Windows PowerShell 3.0, the Enable-PSRemoting cmdlet can enable remoting on client and server versions of Windows on private, domain, and public networks. On server versions of Windows with private and domain networks, the -Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted -remote access. It also creates a firewall rule for public networks that -allows remote access only from computers in the same local subnet. This -local subnet firewall rule is enabled by default on server versions of -Windows on public networks, but Enable-PSRemoting reapplies the rule in -case it was changed or deleted. - -On client versions of Windows with private and domain networks, by -default, the Enable-PSRemoting cmdlet creates firewall rules that -allow unrestricted remote access. - -To enable remoting on client versions of Windows with public networks, -use the SkipNetworkProfileCheck parameter of the Enable-PSRemoting cmdlet. -It creates a firewall rule that that allows remote access only from -computers in the same local subnet. +Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted remote +access. It also creates a firewall rule for public networks that allows remote +access only from computers in the same local subnet. This local subnet +firewall rule is enabled by default on server versions of Windows on public +networks, but Enable-PSRemoting reapplies the rule in case it was changed or +deleted. + +On client versions of Windows with private and domain networks, by default, +the Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted +remote access. + +To enable remoting on client versions of Windows with public networks, use the +SkipNetworkProfileCheck parameter of the Enable-PSRemoting cmdlet. It creates +a firewall rule that that allows remote access only from computers in the same +local subnet. To remove the local subnet restriction on public networks and allow remote -access from all locations on client and server versions of Windows, use -the Set-NetFirewallRule cmdlet in the NetSecurity module. Run the following +access from all locations on client and server versions of Windows, use the +Set-NetFirewallRule cmdlet in the NetSecurity module. Run the following command: +```powershell Set-NetFirewallRule -Name "WINRM-HTTP-In-TCP-PUBLIC" -RemoteAddress Any +``` In Windows PowerShell 2.0, on server versions of Windows, Enable-PSRemoting creates firewall rules that permit remote access on all networks. @@ -134,64 +130,55 @@ creates firewall rules that permit remote access on all networks. In Windows PowerShell 2.0, on client versions of Windows, Enable-PSRemoting creates firewall rules only on private and domain networks. If the network location is public, Enable-PSRemoting fails. -# . - -# RUN AS ADMINISTRATOR +## RUN AS ADMINISTRATOR +Administrator privileges are required for the following remoting operations: -Administrator privileges are required for the following remoting -operations: +- Establishing a remote connection to the local computer. This is commonly + known as a "loopback" scenario. --- Establishing a remote connection to the local computer. This is -commonly known as a "loopback" scenario. +- Managing session configurations on the local computer. --- Managing session configurations on the local computer. +- Viewing and changing WS-Management settings on the local computer. These are + the settings in the LocalHost node of the WSMAN: drive. --- Viewing and changing WS-Management settings on the local computer. -These are the settings in the LocalHost node of the WSMAN: drive. +To perform these tasks, you must start Windows PowerShell with the "Run as +administrator" option even if you are a member of the Administrators group on +the local computer. -To perform these tasks, you must start Windows PowerShell with the "Run -as administrator" option even if you are a member of the Administrators -group on the local computer. - -In Windows 7 and in Windows Server 2008 R2, to start Windows PowerShell -with the "Run as administrator" option: +In Windows 7 and in Windows Server 2008 R2, to start Windows PowerShell with +the "Run as administrator" option: 1. Click Start, click All Programs, click Accessories, and then click -the Windows PowerShell folder. - -2. Right-click Windows PowerShell, and then click -"Run as administrator". + the Windows PowerShell folder. +2. Right-click Windows PowerShell, and then click "Run as administrator". To start Windows PowerShell with the "Run as administrator" option: -1. Click Start, click All Programs, and then click the Windows -PowerShell folder. +1. Click Start, click All Programs, and then click the Windows PowerShell + folder. +2. Right-click Windows PowerShell, and then click "Run as administrator". -2. Right-click Windows PowerShell, and then click -"Run as administrator". - -The "Run as administrator" option is also available in other Windows -Explorer entries for Windows PowerShell, including shortcuts. Just -right-click the item, and then click "Run as administrator". +The "Run as administrator" option is also available in other Windows Explorer +entries for Windows PowerShell, including shortcuts. Just right-click the +item, and then click "Run as administrator". When you start Windows PowerShell from another program such as Cmd.exe, use the "Run as administrator" option to start the program. -# HOW TO CONFIGURE YOUR COMPUTER FOR REMOTING - +## HOW TO CONFIGURE YOUR COMPUTER FOR REMOTING Computers running all supported versions of Windows can establish remote connections to and run remote commands in Windows PowerShell without any configuration. However, to receive connections, and allow users to create -local and remote user-managed Windows PowerShell sessions ("PSSessions") -and run commands on the local computer, you must enable Windows PowerShell +local and remote user-managed Windows PowerShell sessions ("PSSessions") and +run commands on the local computer, you must enable Windows PowerShell remoting on the computer. Windows Server 2012 and newer releases of Windows Server are enabled for -Windows PowerShell remoting by default. If the settings are changed, -you can restore the default settings by running the Enable-PSRemoting cmdlet. +Windows PowerShell remoting by default. If the settings are changed, you can +restore the default settings by running the Enable-PSRemoting cmdlet. On all other supported versions of Windows, you need to run the Enable-PSRemoting cmdlet to enable Windows PowerShell remoting. @@ -199,45 +186,43 @@ Enable-PSRemoting cmdlet to enable Windows PowerShell remoting. The remoting features of Windows PowerShell are supported by the WinRM service, which is the Microsoft implementation of the Web Services for Management (WS-Management) protocol. When you enable Windows PowerShell -remoting, you change the default configuration of WS-Management and add -system configuration that allow users to connect to WS-Management. +remoting, you change the default configuration of WS-Management and add system +configuration that allow users to connect to WS-Management. To configure Windows PowerShell to receive remote commands: -1. Start Windows PowerShell with the "Run as administrator" -option. - -2. At the command prompt, type: -Enable-PSRemoting +1. Start Windows PowerShell with the "Run as administrator" option. +2. At the command prompt, type: `Enable-PSRemoting` To verify that remoting is configured correctly, run a test command such as -the following command, which creates a remote session on the local -computer. +the following command, which creates a remote session on the local computer. +```powershell New-PSSession +``` -If remoting is configured correctly, the command will create a session on -the local computer and return an object that represents the session. The -output should resemble the following sample output: - -C:\PS> new-pssession +If remoting is configured correctly, the command will create a session on the +local computer and return an object that represents the session. The output +should resemble the following sample output: +```output Id Name ComputerName State ConfigurationName -- ---- ------------ ----- ----- 1 Session1 localhost Opened Microsoft.PowerShell +``` -If the command fails, for assistance, see about_Remote_Troubleshooting. +If the command fails, for assistance, see +[about_Remote_Troubleshooting](about_Remote_Troubleshooting.md). -# UNDERSTAND POLICIES +## UNDERSTAND POLICIES +When you work remotely, you use two instances of Windows PowerShell, one on +the local computer and one on the remote computer. As a result, your work is +affected by the Windows policies and the Windows PowerShell policies on the +local and remote computers. -When you work remotely, you use two instances of Windows PowerShell, one -on the local computer and one on the remote computer. As a result, your -work is affected by the Windows policies and the Windows PowerShell -policies on the local and remote computers. - -In general, before you connect and as you are establishing the connection, -the policies on the local computer are in effect. When you are using the +In general, before you connect and as you are establishing the connection, the +policies on the local computer are in effect. When you are using the connection, the policies on the remote computer are in effect. # SEE ALSO @@ -248,9 +233,8 @@ connection, the policies on the remote computer are in effect. [about_PSSessions](about_PSSessions.md) -Invoke-Command - -Enter-PSSession +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 33bf188649a7..cdd13115f8e0 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,108 +7,109 @@ title: about_Remote_Variables --- # About Remote Variables -## about_Remote_Variables +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use local and remote variables in remote commands. -Explains how to use local and remote variables in remote -commands. +## LONG DESCRIPTION -# LONG DESCRIPTION - -You can use variables in commands that you run on remote -computers. Simply assign a value to the variable and then -use the variable in place of the value. - -By default, the variables in remote commands are assumed -to be defined in the session in which the command runs. You -can also use variables that are defined in the local session, -but you must identify them as local -variables in the command. - -# USING REMOTE VARIABLES - - -Windows PowerShell assumes that the variables used in remote -commands are defined in the session in which the command runs. +You can use variables in commands that you run on remote computers. Simply +assign a value to the variable and then use the variable in place of the +value. -In the following example, the $ps variable is defined in the -temporary session in which the Get-WinEvent command runs. +By default, the variables in remote commands are assumed to be defined in the +session in which the command runs. You can also use variables that are defined +in the local session, but you must identify them as local variables in the +command. -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"; Get-WinEvent -LogName $ps} +## USING REMOTE VARIABLES -Similarly, when the command runs in a persistent session (PSSession), -the remote variable must be defined in the same PSSession. +Windows PowerShell assumes that the variables used in remote commands are +defined in the session in which the command runs. -PS C:> $s = New-PSSession -ComputerName S1 +In the following example, the \$ps variable is defined in the temporary session +in which the Get-WinEvent command runs. -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"} +```powershell +Invoke-Command -ComputerName S1 -ScriptBlock { + $ps = "Windows PowerShell"; Get-WinEvent -LogName $ps +} +``` -PS C:> Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $ps} +Similarly, when the command runs in a persistent session (PSSession), the +remote variable must be defined in the same PSSession. -# USING LOCAL VARIABLES +```powershell +$s = New-PSSession -ComputerName S1 +Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"} +Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $ps} +``` +## USING LOCAL VARIABLES -You can also use local variables in remote commands, but you must -indicate that the variable is defined in the local session. +You can also use local variables in remote commands, but you must indicate +that the variable is defined in the local session. -Beginning in Windows PowerShell 3.0, you can use the Using scope -modifier to identify a local variable in a remote command. +Beginning in Windows PowerShell 3.0, you can use the Using scope modifier to +identify a local variable in a remote command. The syntax of Using is as follows: -The syntax is: +``` $Using: +``` -In the following example, the $ps variable is created in the local -session, but is used in the session in which the command runs. The -Using scope modifier identifies $ps as a local variable. +In the following example, the $ps variable is created in the local session, +but is used in the session in which the command runs. The Using scope modifier +identifies $ps as a local variable. -PS C:> $ps = "Windows PowerShell" -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {Get-WinEvent -LogName $Using:ps} +```powershell +$ps = "Windows PowerShell" +Invoke-Command -ComputerName S1 -ScriptBlock { + Get-WinEvent -LogName $Using:ps +} +``` You can also use the Using scope modifier in PSSessions. -PS C:> $s = New-PSSession -ComputerName S1 - -PS C:> $ps = "Windows PowerShell" +```powershell +$s = New-PSSession -ComputerName S1 +$ps = "Windows PowerShell" +Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +``` -PS C:> Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +## USING LOCAL VARIABLES IN WINDOWS POWERSHELL 2.0 -# USING LOCAL VARIABLES IN WINDOWS POWERSHELL 2.0 +You can use local variables in a remote command by defining parameters for the +remote command and using the ArgumentList parameter of the Invoke-Command +cmdlet to specify the local variable as the parameter value. +This command format is valid on Windows PowerShell 2.0 and later versions of +Windows PowerShell. -You can use local variables in a remote command by defining parameters -for the remote command and using the ArgumentList parameter of the -Invoke-Command cmdlet to specify the local variable as the parameter -value. - -This command format is valid on Windows PowerShell 2.0 and later versions -of Windows PowerShell. +- Use the param keyword to define parameters for the remote command. The + parameter names are placeholders that do not need to match the name of the + local variable. --- Use the param keyword to define parameters for the remote command. -The parameter names are placeholders that do not need to match the -name of the local variable. +- Use the parameters defined by the param keyword in the command. --- Use the parameters defined by the param keyword in the command. - --- Use the ArgumentList parameter of the Invoke-Command cmdlet to -specify the local variable as the parameter value. +- Use the ArgumentList parameter of the Invoke-Command cmdlet to specify the + local variable as the parameter value. For example, the following commands define the $ps variable in the local -session and then use it in a remote command. The command uses $log as -the parameter name and the local variable, $ps, as its value. - -C:\PS>$ps = "Windows PowerShell" +session and then use it in a remote command. The command uses $log as the +parameter name and the local variable, $ps, as its value. -C:\PS>Invoke-Command -ComputerName S1 -ScriptBlock {param($log) Get-WinEvent -logname $log} -ArgumentList $ps +```powershell +$ps = "Windows PowerShell" +Invoke-Command -ComputerName S1 -ScriptBlock { + param($log) + Get-WinEvent -logname $log +} -ArgumentList $ps +``` -# KEYWORDS - -about_Using - -# SEE ALSO +## SEE ALSO [about_Remote](about_Remote.md) @@ -116,9 +117,8 @@ about_Using [about_Scopes](about_Scopes.md) -Enter-PSSession - -Invoke-Command +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Requires.md index 4ae85a982fc2..c2e71e2f1753 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Requires.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -145,5 +145,4 @@ always a snap-in. [about_PSSnapins](about_PSSnapins.md) -Get-PSSnapin - +[Get-PSSnapin](../Get-PSSnapin.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Reserved_Words.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Reserved_Words.md index 874a7e5fd8a1..4c2f92e8b5fc 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Reserved_Words.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Reserved_Words.md @@ -70,8 +70,8 @@ Get-Help ## SEE ALSO - [about_Command_Syntax](about_Command_Syntax.md) -- [about_Special_Characters](about_Special_Characters.md) - [about_Language_Keywords](about_Language_Keywords.md) - [about_Parsing](about_Parsing.md) - [about_Quoting_Rules](about_Quoting_Rules.md) - [about_Script_Blocks](about_Script_Blocks.md) +- [about_Special_Characters](about_Special_Characters.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Return.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Return.md index eb8d94d341f8..bcb1e40e8d25 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Return.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Return.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,118 +7,115 @@ title: about_Return --- # About Return -## about_Return - ## SHORT DESCRIPTION -Exits the current scope, which can be a function, script, or script block. +Exits the current scope, which can be a function, script, or script block. ## LONG DESCRIPTION -The Return keyword exits a function, script, or script block. It can be used to exit a scope at a specific point, to return a value, or to indicate that the end of the scope has been reached. -Users who are familiar with languages like C or C\# might want to use the Return keyword to make the logic of leaving a scope explicit. + The Return keyword exits a function, script, or script block. It can be used + to exit a scope at a specific point, to return a value, or to indicate that + the end of the scope has been reached. -In Windows PowerShell? the results of each statement are returned as output, even without a statement that contains the Return keyword. Languages like C or C\# return only the value or values that are specified by the Return keyword. +Users who are familiar with languages like C or C\# might want to use the +Return keyword to make the logic of leaving a scope explicit. +In PowerShell, the results of each statement are returned as output, +even without a statement that contains the Return keyword. Languages like C or +C\# return only the value or values that are specified by the Return keyword. ### SYNTAX -The syntax for the Return keyword is as follows: +The syntax for the Return keyword is as follows: ``` return [] ``` - -The Return keyword can appear alone, or it can be followed by a value or expression, as follows: - +The Return keyword can appear alone, or it can be followed by a value or +expression, as follows: ``` -return -return $a +return +return $a return (2 + $a) ``` - ### EXAMPLES -The following example uses the Return keyword to exit a function at a specific point if a conditional is met: +The following example uses the Return keyword to exit a function at a specific +point if a conditional is met: ``` -function ScreenPassword($instance) -{ - if (!($instance.screensaversecure)) {return $instance.name} - -} - +function ScreenPassword($instance) +{ + if (!($instance.screensaversecure)) {return $instance.name} + +} + foreach ($a in @(get-wmiobject win32_desktop)) { ScreenPassword($a) } ``` +This script checks each user account. The ScreenPassword function returns the +name of any user account that does not have a password-protected screen saver. +If the screen saver is password protected, the function completes any other +statements to be run, and PowerShell does not return any value. -This script checks each user account. The ScreenPassword function returns the name of any user account that does not have a password-protected screen saver. If the screen saver is password protected, the function completes any other statements to be run, and Windows PowerShell does not return any value. - -In Windows PowerShell, values can be returned even if the Return keyword is not used. The results of each statement are returned. For example, the following statements return the value of the $a variable: - +In PowerShell, values can be returned even if the Return keyword is not used. +The results of each statement are returned. For example, the following +statements return the value of the \$a variable: ``` -$a +$a return ``` - The following statement also returns the value of $a: - ``` return $a ``` +The following example includes a statement intended to let the user know that +the function is performing a calculation: -The following example includes a statement intended to let the user know that the function is performing a calculation: +```powershell +function calculation { + param ($value) - -``` -function calculation { - param ($value) - - "Please wait. Working on calculation..." - $value += 73 - return $value - } + "Please wait. Working on calculation..." + $value += 73 + return $value +} ``` +Running this function and assigning the result to a variable has the following +effect: -Running this function and assigning the result to a variable has the following effect: - - -``` -C:\PS> $a = calculation 14 -C:\PS> +```powershell +$a = calculation 14 ``` +The "Please wait. Working on calculation..." string is not displayed. Instead, +it is assigned to the $a variable, as in the following example: -The "Please wait. Working on calculation..." string is not displayed. Instead, it is assigned to the $a variable, as in the following example: - - -``` -C:\PS> $a -Please wait. Working on calculation... +```output +C:\PS> $a +Please wait. Working on calculation... 87 ``` - -Both the informational string and the result of the calculation are returned by the function and assigned to the $a variable. - +Both the informational string and the result of the calculation are returned +by the function and assigned to the \$a variable. ## SEE ALSO -Exit keyword in about_Language_Keywords +[about_Language_Keywords](about_Language_Keywords.md) [about_Functions](about_Functions.md) [about_Scopes](about_Scopes.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md index 43445a359c43..2e47af3dba57 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,62 +7,56 @@ title: about_Run_With_PowerShell --- # About Run With PowerShell -## about_Run_With_PowerShell +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use the "Run with PowerShell" feature to run a script from a +file system drive. -Explains how to use the "Run with PowerShell" feature to run -a script from a file system drive. +## LONG DESCRIPTION -# LONG DESCRIPTION +Beginning in Windows PowerShell 3.0, you can use the "Run with PowerShell" +feature to run scripts from File Explorer in Windows 8 and Windows Server 2012 +and from Windows Explorer in earlier versions of Windows. -Beginning in Windows PowerShell 3.0, you can use the "Run with -PowerShell" feature to run scripts from File Explorer in Windows 8 -and Windows Server 2012 and from Windows Explorer in earlier -versions of Windows. +The "Run with PowerShell" feature is designed to run scripts that do not have +required parameters and do not return output to the command prompt. -The "Run with PowerShell" feature is designed to run scripts -that do not have required parameters and do not return output -to the command prompt. - -When you use the "Run with PowerShell" feature, the Windows -PowerShell console window appears only briefly, if at all. -You cannot interact with it. +When you use the "Run with PowerShell" feature, the Windows PowerShell console +window appears only briefly, if at all. You cannot interact with it. To use the "Run with PowerShell" feature: -In File Explorer (or Windows Explorer), right-click the -script file name and then select "Run with PowerShell". +In File Explorer (or Windows Explorer), right-click the script file name and +then select "Run with PowerShell". -The "Run with PowerShell" feature starts a Windows PowerShell -session that has an execution policy of Bypass, runs the -script, and closes the session. +The "Run with PowerShell" feature starts a Windows PowerShell session that has +an execution policy of Bypass, runs the script, and closes the session. It runs a command that has the following format: + +``` PowerShell.exe -File -ExecutionPolicy Bypass +``` -"Run with PowerShell" sets the Bypass execution policy only -for the session (the current instance of the PowerShell process) -in which the script runs. This feature does not change the execution -policy for the computer or the user. +"Run with PowerShell" sets the Bypass execution policy only for the session +(the current instance of the PowerShell process) in which the script runs. +This feature does not change the execution policy for the computer or the +user. -The "Run with PowerShell" feature is affected only by the AllSigned -execution policy. If the AllSigned execution policy is effective for -the computer or the user, "Run with PowerShell" runs only signed -scripts. "Run with PowerShell" is not affected by any other execution -policy. For more information, see about_Execution_Policies. +The "Run with PowerShell" feature is affected only by the AllSigned execution +policy. If the AllSigned execution policy is effective for the computer or the +user, "Run with PowerShell" runs only signed scripts. "Run with PowerShell" is +not affected by any other execution policy. For more information, see +[about_Execution_Policies](about_Execution_Policies.md). -Troubleshooting Note: Run with PowerShell command might prompt you -to confirm the execution policy change. +Troubleshooting Note: Run with PowerShell command might prompt you to confirm +the execution policy change. -# SEE ALSO +## SEE ALSO [about_Execution_Policies](about_Execution_Policies.md) [about_Group_Policy_Settings](about_Group_Policy_Settings.md) [about_Scripts](about_Scripts.md) - -"Running Scripts" (http://go.microsoft.com/fwlink/?LinkId=257680) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md index a4409d59d90f..06219eb3961e 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,63 +10,63 @@ title: about_Script_Internationalization ## Short Description -Describes the script internationalization features that make it easy for scripts to display -messages and instructions to users in their user interface (UI) language. +Describes the script internationalization features that make it easy for +scripts to display messages and instructions to users in their user interface +(UI) language. ## Long Description The Windows PowerShell script internationalization features allow you to -better serve users throughout the world by displaying Help and user -messages for scripts and functions in the user's UI language. +better serve users throughout the world by displaying Help and user messages +for scripts and functions in the user's UI language. -The script internationalization features query the UI culture of the -operating system during execution, import the appropriate -translated text strings, and display them to the user. The Data section -lets you store text strings separate from code so they are easily -identified and extracted. A new cmdlet, `ConvertFrom-StringData`, -converts text strings into dictionary-like hash tables to facilitate -translation. +The script internationalization features query the UI culture of the operating +system during execution, import the appropriate translated text strings, and +display them to the user. The Data section lets you store text strings +separate from code so they are easily identified and extracted. A new cmdlet, +`ConvertFrom-StringData`, converts text strings into dictionary-like hash +tables to facilitate translation. -To support international Help text, Windows PowerShell includes the -following features: +To support international Help text, Windows PowerShell includes the following +features: -* A Data section that separates text strings from code instructions. For -more information about the Data section, see [about_Data_Sections](about_Data_Sections.md). +* A Data section that separates text strings from code instructions. For more + information about the Data section, see + [aout_Data_Sections](about_Data_Sections.md). -* New automatic variables, $PSCulture and $PSUICulture. $PSCulture stores -the name of the UI language used on the system for elements such as -the date, time, and currency. The $PSUICulture variable stores the -name of the UI language used on the system for user interface elements -such as menus and text strings. +* New automatic variables, \$PSCulture and \$PSUICulture. \$PSCulture stores the + name of the UI language used on the system for elements such as the date, + time, and currency. The $PSUICulture variable stores the name of the UI + language used on the system for user interface elements such as menus and text + strings. * A cmdlet, `ConvertFrom-StringData`, that converts text strings into -dictionary-like hash tables to facilitate translation. For more -information, see [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md). + dictionary-like hash tables to facilitate translation. For more information, + see [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md). -* A new file type, .psd1, that stores translated text strings. The .psd1 -files are stored in language-specific subdirectories of the script -directory. +* A new file type, .psd1, that stores translated text strings. The .psd1 files + are stored in language-specific subdirectories of the script directory. -* A cmdlet, `Import-LocalizedData`, that imports translated text strings -for a specified language into a script at runtime. This cmdlet recognizes -and imports strings in any Windows-supported language. For more -information see [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md). +* A cmdlet, `Import-LocalizedData`, that imports translated text strings for a + specified language into a script at runtime. This cmdlet recognizes and + imports strings in any Windows-supported language. For more information see + [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md). ### The Data Section: Storing Default Strings -Use a Data section in the script to store the text strings in the default language. -Arrange the strings in key/value pairs in a here-string. Each key/value pair must -be on a separate line. If you include comments, the comments must be on separate -lines. +Use a Data section in the script to store the text strings in the default +language. Arrange the strings in key/value pairs in a here-string. Each +key/value pair must be on a separate line. If you include comments, the +comments must be on separate lines. -The `ConvertFrom-StringData` cmdlet converts the key/value pairs in the here-string -into a dictionary-like hash table that is stored in the value of the Data section -variable. +The `ConvertFrom-StringData` cmdlet converts the key/value pairs in the +here-string into a dictionary-like hash table that is stored in the value of +the Data section variable. In the following example, the Data section of the World.ps1 script includes the English-United States (en-US) set of prompt messages for a script. The -`ConvertFrom-StringData` cmdlet converts the strings into a hash table and stores -them in the $msgtable variable. +`ConvertFrom-StringData` cmdlet converts the strings into a hash table and +stores them in the $msgtable variable. ```powershell $msgTable = Data { @@ -79,21 +79,22 @@ $msgTable = Data { } ``` -For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). ### PSD1 Files: Storing Translated Strings -Save the script messages for each UI language in separate text files with -the same name as the script and the .psd1 file name extension. Store the files -in subdirectories of the script directory with names of cultures in the following +Save the script messages for each UI language in separate text files with the +same name as the script and the .psd1 file name extension. Store the files in +subdirectories of the script directory with names of cultures in the following format: \-\ Examples: de-DE, ar-SA, and zh-Hans -For example, if the World.ps1 script is stored in the C:\Scripts directory, you -would create a file directory structure that resembles the following: +For example, if the World.ps1 script is stored in the C:\Scripts directory, +you would create a file directory structure that resembles the following: ``` C:\Scripts @@ -104,8 +105,8 @@ C:\Scripts\zh-CN\World.psd1 ... ``` -The World.psd1 file in the de-DE subdirectory of the script directory -might include the following statement: +The World.psd1 file in the de-DE subdirectory of the script directory might +include the following statement: ```powershell ConvertFrom-StringData -StringData @' @@ -115,8 +116,8 @@ promptMsg = Please enter your user name (in German). '@ ``` -Similarly, the World.psd1 file in the ar-SA subdirectory of the script directory -might includes the following statement: +Similarly, the World.psd1 file in the ar-SA subdirectory of the script +directory might includes the following statement: ```powershell ConvertFrom-StringData -StringData @' @@ -128,70 +129,63 @@ promptMsg = Please enter your user name (in Arabic). ### Import-LocalizedData: Dynamic Retrieval of Translated Strings -To retrieve the strings in the UI language of the current user, use -the `Import-LocalizedData` cmdlet. +To retrieve the strings in the UI language of the current user, use the +`Import-LocalizedData` cmdlet. -`Import-LocalizedData` finds the value of the $PSUICulture automatic -variable and imports the content of the \.psd1 files in -the subdirectory that matches the $PSUICulture value. Then, it saves -the imported content in the variable specified by the value of the -**BindingVariable** parameter. +`Import-LocalizedData` finds the value of the \$PSUICulture automatic variable +and imports the content of the \.psd1 files in the subdirectory +that matches the \$PSUICulture value. Then, it saves the imported content in +the variable specified by the value of the **BindingVariable** parameter. ```powershell Import-LocalizedData -BindingVariable msgTable ``` For example, if the `Import-LocalizedData` command appears in the -C:\Scripts\World.ps1 script and the value of $PSUICulture is -"ar-SA", `Import-LocalizedData` finds the following file: +C:\\Scripts\\World.ps1 script and the value of $PSUICulture is "ar-SA", +`Import-LocalizedData` finds the following file: -C:\Scripts\ar-SA\World.psd1 +C:\\Scripts\\ar-SA\\World.psd1 -Then, it imports the Arabic text strings from the file into -the $msgTable variable, replacing any default strings that might -be defined in the Data section of the World.ps1 script. +Then, it imports the Arabic text strings from the file into the $msgTable +variable, replacing any default strings that might be defined in the Data +section of the World.ps1 script. -As a result, when the script uses the $msgTable variable -to display user messages, the messages are displayed in -Arabic. +As a result, when the script uses the $msgTable variable to display user +messages, the messages are displayed in Arabic. -For example, the following script displays the "Please enter your user -name" message in Arabic: +For example, the following script displays the "Please enter your user name" +message in Arabic: ```powershell if (!($username)) { $msgTable.promptMsg } ``` -If `Import-LocalizedData` cannot find a .psd1 file that matches the -value of $PSUIculture, the value of $msgTable is not replaced, -and the call to $msgTable.promptMsg displays the fallback en-US -strings. +If `Import-LocalizedData` cannot find a .psd1 file that matches the value of +\$PSUIculture, the value of \$msgTable is not replaced, and the call to +\$msgTable.promptMsg displays the fallback en-US strings. ## Examples -This example shows how the script internationalization features -are used in a script to display a day of the week to users -in the language that is set on the computer. +This example shows how the script internationalization features are used in a +script to display a day of the week to users in the language that is set on +the computer. -The following is a complete listing of the Sample1.ps1 script -file. +The following is a complete listing of the Sample1.ps1 script file. -The script begins with a Data section named Day ($Day) that -contains a `ConvertFrom-StringData` command. The expression -submitted to `ConvertFrom-StringData` is a here-string that -contains the day names in the default UI culture, en-US, in -key/value pairs. The `ConvertFrom-StringData` cmdlet converts -the key/value pairs in the here-string into a hash table and +The script begins with a Data section named Day ($Day) that contains a +`ConvertFrom-StringData` command. The expression submitted to +`ConvertFrom-StringData` is a here-string that contains the day names in the +default UI culture, en-US, in key/value pairs. The `ConvertFrom-StringData` +cmdlet converts the key/value pairs in the here-string into a hash table and then saves it in the value of the $Day variable. -The `Import-LocalizedData` command imports the contents of the -.psd1 file in the directory that matches the value of the -$PSUICulture automatic variable and then saves it in the $Day -variable, replacing the values of $Day that are defined in the -Data section. +The `Import-LocalizedData` command imports the contents of the .psd1 file in +the directory that matches the value of the $PSUICulture automatic variable +and then saves it in the $Day variable, replacing the values of $Day that are +defined in the Data section. -The remaining commands load the strings into an array and display -them. +The remaining commands load the strings into an array and display them. ```powershell $Day = Data { @@ -239,10 +233,10 @@ ConvertFrom-StringData @' '@ ``` -As a result, when you run Sample.ps1 on a system on which the value -of $PSUICulture is de-DE, the output of the script is: +As a result, when you run Sample.ps1 on a system on which the value of +\$PSUICulture is de-DE, the output of the script is: -``` +```output Today is Friday (in German) ``` @@ -254,4 +248,3 @@ Today is Friday (in German) * [about_Quoting_Rules](about_Quoting_Rules.md) * [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md) * [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md index fe470e6bc5b4..b3d7fc0d56e2 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,284 +7,296 @@ title: about_Session_Configuration_Files --- # About Session Configuration Files -## about_Session_Configuration_Files +## SHORT DESCRIPTION +Describes session configuration files, which are used in a session +configuration (also known as an "endpoint") to define the environment of +sessions that use the session configuration. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes session configuration files, which are used in a -session configuration (also known as an "endpoint") to define the -environment of sessions that use the session configuration. - -# LONG DESCRIPTION - -A "session configuration file" is a text file with a .pssc file -name extension that contains a hash table of session configuration -properties and values. You can use a session configuration file to -set the properties of a session configuration. Doing so defines -the environment of any Windows PowerShell sessions that use that -session configuration. +A "session configuration file" is a text file with a .pssc file name extension +that contains a hash table of session configuration properties and values. You +can use a session configuration file to set the properties of a session +configuration. Doing so defines the environment of any Windows PowerShell +sessions that use that session configuration. Session configuration files make it easy to create custom session configurations without using complex C# assemblies or scripts. -A "session configuration" or "endpoint" is a collection of local -computer settings that determine such things as which users can -create sessions on the computer; which commands users can run in -those sessions; and whether the session should run as a privileged -virtual account. For more information about session configurations, -see about_Session_Configurations -(http://go.microsoft.com/fwlink/?LinkID=145152). - -Session configurations were introduced in Windows PowerShell 2.0, -and session configuration files were introduced in Windows -PowerShell 3.0. You must use Windows PowerShell 3.0 to include a -session configuration file in a session configuration. However, -users of Windows PowerShell 2.0 (and later) are affected by the -settings in the session configuration. - -Creating Custom Sessions -You can customize many features of a Windows PowerShell session -by specifying session properties in a session configuration. You -can customize a session by writing a C# program that defines a -custom runspace, or you can use a session configuration file to -define the properties of sessions created by using the session -configuration. As a general rule, it is easier to use the session +A "session configuration" or "endpoint" is a collection of local computer +settings that determine such things as which users can create sessions on the +computer; which commands users can run in those sessions; and whether the +session should run as a privileged virtual account. For more information about +session configurations, see [about_Session_Configurations](about_Session_Configurations.md). + +Session configurations were introduced in Windows PowerShell 2.0, and session +configuration files were introduced in Windows PowerShell 3.0. You must use +Windows PowerShell 3.0 to include a session configuration file in a session +configuration. However, users of Windows PowerShell 2.0 (and later) are +affected by the settings in the session configuration. + +## Creating Custom Sessions + +You can customize many features of a Windows PowerShell session by specifying +session properties in a session configuration. You can customize a session by +writing a C# program that defines a custom runspace, or you can use a session +configuration file to define the properties of sessions created by using the +session configuration. As a general rule, it is easier to use the session configuration file than to write a C# program. You can use a session configuration file to create items such as -fully-functioning sessions for highly trusted users; locked-down -sessions that allow minimal access; sessions designed for -particular and that contain only the modules required for those -tasks; and sessions where unprivileged users can only run -specific commands as a privileged account. - -In addition to that, you can manage whether users of the -session can use Windows PowerShell language elements such as -script blocks, or whether they can only run commands. You can -manage the version of Windows PowerShell users can run in the -session; manage which modules are imported into the session; and -manage which cmdlets, functions, and aliases session users can -run. When using the RoleDefinitions field, you can give users -different capabilities in the session based on group membership. - -For more information about RoleDefinitions and how to define this -Value, see the help topic for the New-PSRoleCapabilityFile -Cmdlet. - -Creating a Session Configuration File -The easiest way to create a session configuration file is by -using the New-PSSessionConfigurationFile cmdlet. This cmdlet -generates a file that uses the correct syntax and format, and -that automatically verifies many of the configuration file -property values. - -For detailed descriptions of the properties that you can set in -a session configuration file, see the help topic for the -New-PSSessionConfigurationFile cmdlet. - -The following command creates a session configuration file that -uses the default values. The resulting configuration file uses only -the default values because no parameters other than the Path -parameter (which specifies the file path) are included: - -PS C:> New-PSSessionConfigurationFile -Path .\Defaults.pssc - -To view the new configuration file in your default text editor, -use the following command: - -PS C:> Invoke-Item -Path .\Defaults.pssc - -To create a session configuration for sessions in which -user can run commands, but not use other elements of the Windows -PowerShell language, type: - -PS C:> New-PSSessionConfigurationFile -LanguageMode NoLanguage +fully-functioning sessions for highly trusted users; locked-down sessions that +allow minimal access; sessions designed for particular and that contain only +the modules required for those tasks; and sessions where unprivileged users +can only run specific commands as a privileged account. + +In addition to that, you can manage whether users of the session can use +Windows PowerShell language elements such as script blocks, or whether they +can only run commands. You can manage the version of Windows PowerShell users +can run in the session; manage which modules are imported into the session; +and manage which cmdlets, functions, and aliases session users can run. When +using the RoleDefinitions field, you can give users different capabilities in +the session based on group membership. + +For more information about RoleDefinitions and how to define this Value, see +the help topic for the New-PSRoleCapabilityFile Cmdlet. + +## Creating a Session Configuration File + +The easiest way to create a session configuration file is by using the +New-PSSessionConfigurationFile cmdlet. This cmdlet generates a file that uses +the correct syntax and format, and that automatically verifies many of the +configuration file property values. + +For detailed descriptions of the properties that you can set in a session +configuration file, see the help topic for the New-PSSessionConfigurationFile +cmdlet. + +The following command creates a session configuration file that uses the +default values. The resulting configuration file uses only the default values +because no parameters other than the Path parameter (which specifies the file +path) are included: + +```powershell +New-PSSessionConfigurationFile -Path .\Defaults.pssc +``` + +To view the new configuration file in your default text editor, use the +following command: + +```powershell +Invoke-Item -Path .\Defaults.pssc +``` + +To create a session configuration for sessions in which user can run commands, +but not use other elements of the Windows PowerShell language, type: + +```powershell +New-PSSessionConfigurationFile -LanguageMode NoLanguage -Path .\NoLanguage.pssc +``` -In the preceding command, setting the LanguageMode parameter to -NoLanguage prevents users from doing such things as writing or -running scripts, or using variables. +In the preceding command, setting the LanguageMode parameter to NoLanguage +prevents users from doing such things as writing or running scripts, or using +variables. -To create a session configuration for sessions in which users can -use only Get cmdlets, type: +To create a session configuration for sessions in which users can use only Get +cmdlets, type: -PS C:> New-PSSessionConfigurationFile -VisibleCmdlets Get-* +```powershell +New-PSSessionConfigurationFile -VisibleCmdlets Get-* -Path .\GetSessions.pssc +``` -In the preceding example, setting the VisibleCmdlets parameter to -Get-* limits users to cmdlets that have names that start with the -string value "Get-". +In the preceding example, setting the VisibleCmdlets parameter to Get-* limits +users to cmdlets that have names that start with the string value "Get-". -To create a session configuration for sessions that run under a -privileged virtual account instead of the user's credentials, type: +To create a session configuration for sessions that run under a privileged +virtual account instead of the user's credentials, type: -PS C:> New-PSSessionConfigurationFile -RunAsVirtualAccount +```powershell +New-PSSessionConfigurationFile -RunAsVirtualAccount -Path .\VirtualAccount.pssc +``` -To create a session configuration for sessions in which the -commands visible to the user are specified in a role capabilities -file, type: +To create a session configuration for sessions in which the commands visible +to the user are specified in a role capabilities file, type: -PS C:> New-PSSessionConfigurationFile -RoleDefinitions +```powershell +New-PSSessionConfigurationFile -RoleDefinitions @{ 'CONTOSO\User' = @{ RoleCapabilities = 'Maintenance' }} -Path .\Maintenance.pssc +``` -Using a Session Configuration File -You can include a session configuration file when you create a -session configuration or add you can add a file to the session -configuration at a later time. +### Using a Session Configuration File -To include a session configuration file when creating a session -configuration, use the Path parameter of the -Register-PSSessionConfiguration cmdlet. +You can include a session configuration file when you create a session +configuration or add you can add a file to the session configuration at a +later time. -For example, the following command uses the NoLanguage.pssc file -when it creates a NoLanguage session configuration. +To include a session configuration file when creating a session configuration, +use the Path parameter of the Register-PSSessionConfiguration cmdlet. -PS C:> Register-PSSessionConfiguration -Name NoLanguage +For example, the following command uses the NoLanguage.pssc file when it +creates a NoLanguage session configuration. + +```powershell +Register-PSSessionConfiguration -Name NoLanguage -Path .\NoLanguage.pssc +``` -When a new NoLanguage session starts, users will only have access -to Windows PowerShell commands. +When a new NoLanguage session starts, users will only have access to Windows +PowerShell commands. -To add a session configuration file to an existing session -configuration, use the Set-PSSessionConfiguration cmdlet and the -Path parameter. This affects any new sessions created with the -specified session configuration. Note that the -Set-PSSessionConfiguration cmdlet changes the session itself and -does not modify the session configuration file. +To add a session configuration file to an existing session configuration, use +the Set-PSSessionConfiguration cmdlet and the Path parameter. This affects any +new sessions created with the specified session configuration. Note that the +Set-PSSessionConfiguration cmdlet changes the session itself and does not +modify the session configuration file. -For example, the following command adds the NoLanguage.pssc file -to the LockedDown session configuration. +For example, the following command adds the NoLanguage.pssc file to the +LockedDown session configuration. -PS C:> Set-PSSessionConfiguration -Name LockedDown +```powershell +Set-PSSessionConfiguration -Name LockedDown -Path .\NoLanguage.pssc +``` -When users use the LockedDown session configuration to create a -session, they will be able to run cmdlets but they will not be -able to create or use variables, assign values, or use other -Windows PowerShell language elements. +When users use the LockedDown session configuration to create a session, they +will be able to run cmdlets but they will not be able to create or use +variables, assign values, or use other Windows PowerShell language elements. -The following command uses the New-PSSession cmdlet to create a -session on the computer Srv01 that uses the LockedDown session -configuration, saving an object reference to the session in the $s -variable. The ACL (access control list) of the session -configuration determines who can use it to create a session. +The following command uses the New-PSSession cmdlet to create a session on the +computer Srv01 that uses the LockedDown session configuration, saving an +object reference to the session in the $s variable. The ACL (access control +list) of the session configuration determines who can use it to create a +session. -PS C:> $s = New-PSSession -ComputerName Srv01 +```powershell +$s = New-PSSession -ComputerName Srv01 -ConfigurationName LockedDown - -Because the NoLanguage constraints were added to the LockedDown -session configuration, users in LockedDown sessions will only be -able to run Windows PowerShell commands and cmdlets. For example, -the following two commands use the Invoke-Command cmdlet to run -commands in the session referenced in the $s variable. The first -command, which runs the Get-UICulture cmdlet and does not use any -variables, succeeds. The second command, which gets the value of -the $PSUICulture variable, fails. - -PS C:> Invoke-Command -Session $s {Get-UICulture} +``` + +Because the NoLanguage constraints were added to the LockedDown session +configuration, users in LockedDown sessions will only be able to run Windows +PowerShell commands and cmdlets. For example, the following two commands use +the Invoke-Command cmdlet to run commands in the session referenced in the $s +variable. The first command, which runs the Get-UICulture cmdlet and does not +use any variables, succeeds. The second command, which gets the value of the +$PSUICulture variable, fails. + +``` +Invoke-Command -Session $s {Get-UICulture} en-US -PS C:> Invoke-Command -Session $s {$PSUICulture} +Invoke-Command -Session $s {$PSUICulture} The syntax is not supported by this runspace. This might be because it is in no-language mode. + CategoryInfo : ParserError: ($PSUICulture:String) [], ParseException + FullyQualifiedErrorId : ScriptsNotAllowed +``` + +## Editing a Session Configuration File -Editing a Session Configuration File -All settings in a session configuration except for -RunAsVirtualAccount and RunAsVirtualAccountGroups can be modified -by editing the session configuration file used by the session -configuration. To do this, begin by locating the active copy of the -session configuration file. +All settings in a session configuration except for RunAsVirtualAccount and +RunAsVirtualAccountGroups can be modified by editing the session configuration +file used by the session configuration. To do this, begin by locating the +active copy of the session configuration file. -When you use a session configuration file in a session -configuration, Windows PowerShell creates an active copy of the -session configuration file and stores it in the -$pshome\SessionConfig directory on the local computer. +When you use a session configuration file in a session configuration, Windows +PowerShell creates an active copy of the session configuration file and stores +it in the \$pshome\\SessionConfig directory on the local computer. -The location of the active copy of a session configuration file is -stored in the ConfigFilePath property of the session configuration -object. +The location of the active copy of a session configuration file is stored in +the ConfigFilePath property of the session configuration object. -The following command gets the location of the session -configuration file for the NoLanguage session configuration. +The following command gets the location of the session configuration file for +the NoLanguage session configuration. -PS C:> (Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath +```powershell +(Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath +``` That command returns a file path similar to the following: +``` C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc +``` -You can edit the .pssc file in any text editor. After the file is -saved it will be employed by any new sessions that use the session -configuration. +You can edit the .pssc file in any text editor. After the file is saved it +will be employed by any new sessions that use the session configuration. -If you need to modify the RunAsVirtualAccount or the -RunAsVirtualAccountGroups settings, you must un-register the -session configuration and re-register a session configuration file -that includes the edited values. +If you need to modify the RunAsVirtualAccount or the RunAsVirtualAccountGroups +settings, you must un-register the session configuration and re-register a +session configuration file that includes the edited values. -Testing a Session Configuration File -Use the Test-PSSessionConfigurationFile cmdlet to test manually -edited session configuration files. That's important: if the file -syntax and values are not valid users will not be able to use the -session configuration to create a session. +## Testing a Session Configuration File -For example, the following command tests the active session -configuration file of the NoLanguage session configuration. +Use the Test-PSSessionConfigurationFile cmdlet to test manually edited session +configuration files. That's important: if the file syntax and values are not +valid users will not be able to use the session configuration to create a +session. -PS C:> Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\ +For example, the following command tests the active session configuration file +of the NoLanguage session configuration. + +```powershell +Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\ WindowsPowerShell\v1.0\SessionConfig\ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc +``` If the syntax and values in the configuration file are valid -Test-PSSessionConfigurationFile returns True. If the syntax and -values are not valid then the cmdlet returns False. - -You can use Test-PSSessionConfigurationFile to test any session -configuration file, including files that the -New-PSSessionConfiguration cmdlet creates. For more information, -see the help topic for the Test-PSSessionConfigurationFile cmdlet. - -Removing a Session Configuration File -You cannot remove a session configuration file from a session -configuration. However, you can replace the file with a new file -that uses the default settings. This effectively cancels the -settings used by the original configuration file. - -To replace a session configuration file, create a new session -configuration file that uses the default settings, then use the -Set-PSSessionConfiguration cmdlet to replace the custom session -configuration file with the new file. - -For example, the following commands create a Default session -configuration file and then replace the active session -configuration file in the NoLanguage session configuration. - -PS C:> New-PSSessionConfigurationFile -Path .\Default.pssc -PS C:> Set-PSSessionConfiguration -Name NoLanguage +Test-PSSessionConfigurationFile returns True. If the syntax and values are not +valid then the cmdlet returns False. + +You can use Test-PSSessionConfigurationFile to test any session configuration +file, including files that the New-PSSessionConfiguration cmdlet creates. For +more information, see the help topic for the Test-PSSessionConfigurationFile +cmdlet. + +## Removing a Session Configuration File + +You cannot remove a session configuration file from a session configuration. +However, you can replace the file with a new file that uses the default +settings. This effectively cancels the settings used by the original +configuration file. + +To replace a session configuration file, create a new session configuration +file that uses the default settings, then use the Set-PSSessionConfiguration +cmdlet to replace the custom session configuration file with the new file. + +For example, the following commands create a Default session configuration +file and then replace the active session configuration file in the NoLanguage +session configuration. + +```powershell +New-PSSessionConfigurationFile -Path .\Default.pssc +Set-PSSessionConfiguration -Name NoLanguage -Path .\Default.pssc +``` -When these commands finish, the NoLanguage session configuration -will actually provide full language support (the default setting) -for all sessions created with that session configuration. +When these commands finish, the NoLanguage session configuration will actually +provide full language support (the default setting) for all sessions created +with that session configuration. -Viewing the Properties of a Session Configuration -The session configuration objects that represent session -configurations using session configuration files have additional -properties that make it easy to discover and analyze the session -configuration. (Note that the type name shown below includes a -formatted view definition.) You can view the properties by running -the Get-PSSessionConfiguration cmdlet and piping the returned data -to the Get-Member cmdlet: +Viewing the Properties of a Session Configuration The session configuration +objects that represent session configurations using session configuration +files have additional properties that make it easy to discover and analyze the +session configuration. (Note that the type name shown below includes a +formatted view definition.) You can view the properties by running the +Get-PSSessionConfiguration cmdlet and piping the returned data to the +Get-Member cmdlet: -PS C:> Get-PSSessionConfiguration NoLanguage | Get-Member +```powershell +Get-PSSessionConfiguration NoLanguage | Get-Member +``` + +```output TypeName: Microsoft.PowerShell.Commands.PSSessionConfigurationCommands #PSSessionConfiguration @@ -331,62 +343,64 @@ SupportsOptions NoteProperty System.String Suppor... xmlns NoteProperty System.String xmlns=... XmlRenderingType NoteProperty System.String XmlRen... Permission ScriptProperty System.Object Permis... +``` -These properties make it easy to search for specific session -configurations. For example, you can use the ExecutionPolicy -property to find a session configuration that supports sessions -with the RemoteSigned execution policy. Note that, because the -ExecutionPolicy property exists only on sessions that use session -configuration files, the command might not return all qualifying +These properties make it easy to search for specific session configurations. +For example, you can use the ExecutionPolicy property to find a session +configuration that supports sessions with the RemoteSigned execution policy. +Note that, because the ExecutionPolicy property exists only on sessions that +use session configuration files, the command might not return all qualifying session configurations. -PS C:> Get-PSSessionConfiguration | +```powershell +Get-PSSessionConfiguration | where {$_.ExecutionPolicy -eq "RemoteSigned"} +``` -The following command gets session configurations in which the -RunAsUser is the Exchange administrator. +The following command gets session configurations in which the RunAsUser is +the Exchange administrator. -PS C:> Get-PSSessionConfiguration | +```powershell + Get-PSSessionConfiguration | where {$_.RunAsUser -eq "Exchange01\Admin01"} +``` -To view information about the role definitions associated with -a configuration use the Get-PSSessionCapability cmdlet. This -cmdlet enables you to determine the commands and environment -available to specific users in specific endpoints. +To view information about the role definitions associated with a configuration +use the Get-PSSessionCapability cmdlet. This cmdlet enables you to determine +the commands and environment available to specific users in specific +endpoints. -# NOTES +## NOTES -Session configurations also support a type of session known as an -"empty" session. An Empty session type enables you to create -custom sessions with selected commands. If you do not add modules, -functions, or scripts to an empty session, the session is limited -to expressions and might not be of any practical use. The -SessionType property tells you whether or not you are working with -an empty session. +Session configurations also support a type of session known as an "empty" +session. An Empty session type enables you to create custom sessions with +selected commands. If you do not add modules, functions, or scripts to an +empty session, the session is limited to expressions and might not be of any +practical use. The SessionType property tells you whether or not you are +working with an empty session. -# SEE ALSO +## SEE ALSO [about_Session_Configurations](about_Session_Configurations.md) -New-PSSession - -Disable-PSSessionConfiguration +[New-PSSession](../New-PSSession.md) -Enable-PSSessionConfiguration +[Disable-PSSessionConfiguration](../Disable-PSSessionConfiguration.md) -Get-PSSessionConfiguration +[Enable-PSSessionConfiguration](../Enable-PSSessionConfiguration.md) -New-PSSessionConfigurationFile +[Get-PSSessionConfiguration](../Get-PSSessionConfiguration.md) -Register-PSSessionConfiguration +[New-PSSessionConfigurationFile](../New-PSSessionConfigurationFile.md) -Set-PSSessionConfiguration +[Register-PSSessionConfiguration](../Register-PSSessionConfiguration.md) -Test-PSSessionConfigurationFile +[Set-PSSessionConfiguration](../Set-PSSessionConfiguration.md) -Unregister-PSSessionConfiguration +[Test-PSSessionConfigurationFile](../Test-PSSessionConfigurationFile.md) -Get-PSSessionCapability +[Unregister-PSSessionConfiguration](../Unregister-PSSessionConfiguration.md) -New-PSRoleCapabilityFile +[Get-PSSessionCapability](../Get-PSSessionCapability.md) +[New-PSRoleCapabilityFile](../New-PSRoleCapabilityFile.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Signing.md index e5836ac5ec8e..f8c13a29566e 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Signing.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,81 +7,81 @@ title: about_Signing --- # About Signing -## about_Signing +## SHORT DESCRIPTION +Explains how to sign scripts so that they comply with the PowerShell execution +policies. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Explains how to sign scripts so that they comply with the Windows -PowerShell execution policies. +The Restricted execution policy does not permit any scripts to run. The +AllSigned and RemoteSigned execution policies prevent PowerShell from running +scripts that do not have a digital signature. -# LONG DESCRIPTION +This topic explains how to run selected scripts that are not signed, even +while the execution policy is RemoteSigned, and how to sign scripts for your +own use. -The Restricted execution policy does not permit any scripts to run. -The AllSigned and RemoteSigned execution policies prevent Windows -PowerShell from running scripts that do not have a digital signature. +For more information about PowerShell execution policies, see +[about_Execution_Policies](about_Execution_Policies.md). -This topic explains how to run selected scripts that are not signed, -even while the execution policy is RemoteSigned, and how to sign -scripts for your own use. +## TO PERMIT SIGNED SCRIPTS TO RUN -For more information about Windows PowerShell execution policies, -see about_Execution_Policy. - -# TO PERMIT SIGNED SCRIPTS TO RUN - -------------------------------- -When you start Windows PowerShell on a computer for the first time, the -Restricted execution policy (the default) is likely to be in effect. +When you start PowerShell on a computer for the first time, the Restricted +execution policy (the default) is likely to be in effect. The Restricted policy does not permit any scripts to run. To find the effective execution policy on your computer, type: +```powershell Get-ExecutionPolicy +``` -To run unsigned scripts that you write on your local computer and -signed scripts from other users, start Windows PowerShell with the -Run as Administrator option and then use the following command to -change the execution policy on the computer to RemoteSigned: +To run unsigned scripts that you write on your local computer and signed +scripts from other users, start PowerShell with the Run as Administrator +option and then use the following command to change the execution policy on +the computer to RemoteSigned: +```powershell Set-ExecutionPolicy RemoteSigned +``` -For more information, see the help topic for the -Set-ExecutionPolicy cmdlet. +For more information, see the help topic for the Set-ExecutionPolicy cmdlet. -# RUNNING UNSIGNED SCRIPTS (REMOTESIGNED EXECUTION POLICY) +## RUNNING UNSIGNED SCRIPTS (REMOTESIGNED EXECUTION POLICY) --------------------------------------------------------- -If your Windows PowerShell execution policy is RemoteSigned, Windows +If your PowerShell execution policy is RemoteSigned, Windows PowerShell will not run unsigned scripts that are downloaded from the Internet, including unsigned scripts you receive through e-mail and instant messaging programs. -If you try to run a downloaded script, Windows PowerShell displays the +If you try to run a downloaded script, PowerShell displays the following error message: -The file cannot be loaded. The file - is not digitally signed. The script -will not execute on the system. Please see "Get-Help +```output +The file cannot be loaded. The file is not digitally +signed. The script will not execute on the system. Please see "Get-Help about_Signing" for more details. +``` Before you run the script, review the code to be sure that you trust it. Scripts have the same effect as any executable program. -To run an unsigned script, use the Unblock-File cmdlet or use the -Following procedure. +To run an unsigned script, use the Unblock-File cmdlet or use the following +procedure. 1. Save the script file on your computer. 2. Click Start, click My Computer, and locate the saved script file. 3. Right-click the script file, and then click Properties. 4. Click Unblock. -If a script that was downloaded from the Internet is digitally signed, but -you have not yet chosen to trust its publisher, Windows PowerShell displays -the following message: +If a script that was downloaded from the Internet is digitally signed, but you +have not yet chosen to trust its publisher, PowerShell displays the following +message: +```output Do you want to run software from this untrusted publisher? The file is published by CN=. This publisher is not trusted on your system. Only run scripts @@ -89,231 +89,206 @@ from trusted publishers. [V] Never run [D] Do not run [R] Run once [A] Always run [?] Help (default is "D"): +``` -If you trust the publisher, select "Run once" or "Always run." -If you do not trust the publisher, select either "Never run" or -"Do not run." If you select "Never run" or "Always run," Windows -PowerShell will not prompt you again for this publisher. +If you trust the publisher, select "Run once" or "Always run." If you do not +trust the publisher, select either "Never run" or "Do not run." If you select +"Never run" or "Always run," PowerShell will not prompt you again for +this publisher. -# METHODS OF SIGNING SCRIPTS +## METHODS OF SIGNING SCRIPTS --------------------------- -You can sign the scripts that you write and the scripts that you obtain -from other sources. Before you sign any script, examine each command -to verify that it is safe to run. +You can sign the scripts that you write and the +scripts that you obtain from other sources. Before you sign any script, +examine each command to verify that it is safe to run. -For best practices about code signing, see "Code-Signing -Best Practices" at http://go.microsoft.com/fwlink/?LinkId=119096. +For best practices about code signing, see +[Code-Signing Best Practices](http://go.microsoft.com/fwlink/?LinkId=119096). For more information about how to sign a script file, see Set-AuthenticodeSignature. -The New-SelfSignedCertificate cmdlet, introduced in the PKI module -in Windows PowerShell 3.0, creates a self-signed certificate that is -Appropriate for testing. For more information, see the help -topic for the New-SelfSignedCertificate cmdlet. - -To add a digital signature to a script, you must sign it with a code -signing certificate. Two types of certificates are suitable for signing -a script file: +The New-SelfSignedCertificate cmdlet, introduced in the PKI module in +PowerShell 3.0, creates a self-signed certificate that is Appropriate for +testing. For more information, see the help topic for the +New-SelfSignedCertificate cmdlet. --- Certificates that are created by a certification authority: +To add a digital signature to a script, you must sign it with a code signing +certificate. Two types of certificates are suitable for signing a script file: -For a fee, a public certification authority verifies your -identity and gives you a code signing certificate. When -you purchase your certificate from a reputable certification -authority, you are able to share your script with users -on other computers that are running Windows because those other -computers trust the certification authority. +- Certificates that are created by a certification authority: For a fee, a + public certification authority verifies your identity and gives you a code + signing certificate. When you purchase your certificate from a reputable + certification authority, you are able to share your script with users on + other computers that are running Windows because those other computers trust + the certification authority. --- Certificates that you create: +- Certificates that you create: You can create a self-signed certificate for + which your computer is the authority that creates the certificate. This + certificate is free of charge and enables you to write, sign, and run scripts + on your computer. However, a script signed by a self-signed certificate will + not run on other computers. -You can create a self-signed certificate for which -your computer is the authority that creates the certificate. -This certificate is free of charge and enables you to write, -sign, and run scripts on your computer. However, a script -signed by a self-signed certificate will not run on other -computers. +Typically, you would use a self-signed certificate only to sign scripts that +you write for your own use and to sign scripts that you get from other sources +that you have verified to be safe. It is not appropriate for scripts that will +be shared, even within an enterprise. -Typically, you would use a self-signed certificate only to sign -scripts that you write for your own use and to sign scripts that you get -from other sources that you have verified to be safe. It is not -appropriate for scripts that will be shared, even within an enterprise. +If you create a self-signed certificate, be sure to enable strong private key +protection on your certificate. This prevents malicious programs from signing +scripts on your behalf. The instructions are included at the end of this +topic. -If you create a self-signed certificate, be sure to enable strong -private key protection on your certificate. This prevents malicious -programs from signing scripts on your behalf. The instructions are -included at the end of this topic. +## CREATE A SELF-SIGNED CERTIFICATE -# CREATE A SELF-SIGNED CERTIFICATE - --------------------------------- To create a self-signed certificate in use the New-SelfSignedCertificate -cmdlet in the PKI module. This module is introduced in Windows PowerShell -3.0 and is included in Windows 8 and Windows Server 2012. For more -information, see the help topic for the New-SelfSignedCertificate cmdlet. +cmdlet in the PKI module. This module is introduced in PowerShell 3.0 and is +included in Windows 8 and Windows Server 2012. For more information, see the +help topic for the New-SelfSignedCertificate cmdlet. -To create a self-signed certificate in earlier versions of Windows, use -the Certificate Creation tool (MakeCert.exe). This tool is included in -the Microsoft .NET Framework SDK (versions 1.1 and later) and in the -Microsoft Windows SDK. +To create a self-signed certificate in earlier versions of Windows, use the +Certificate Creation tool (MakeCert.exe). This tool is included in the +Microsoft .NET Framework SDK (versions 1.1 and later) and in the Microsoft +Windows SDK. For more information about the syntax and the parameter descriptions of the -MakeCert.exe tool, see "Certificate Creation Tool (MakeCert.exe)" in the -MSDN (Microsoft Developer Network) library at -http://go.microsoft.com/fwlink/?LinkId=119097. +MakeCert.exe tool, see [Certificate Creation Tool (MakeCert.exe)](http://go.microsoft.com/fwlink/?LinkId=119097) +in the MSDN library. To use the MakeCert.exe tool to create a certificate, run the following commands in an SDK Command Prompt window. -Note: The first command creates a local certification authority for -your computer. The second command generates a personal -certificate from the certification authority. +Note: The first command creates a local certification authority for your +computer. The second command generates a personal certificate from the +certification authority. -Note: You can copy or type the commands exactly as they appear. -No substitutions are necessary, although you can change the -certificate name. +Note: You can copy or type the commands exactly as they appear. No +substitutions are necessary, although you can change the certificate name. +```powershell makecert -n "CN=PowerShell Local Certificate Root" -a sha1 ` -eku 1.3.6.1.5.5.7.3.3 -r -sv root.pvk root.cer ` -ss Root -sr localMachine makecert -pe -n "CN=PowerShell User" -ss MY -a sha1 ` -eku 1.3.6.1.5.5.7.3.3 -iv root.pvk -ic root.cer +``` -The MakeCert.exe tool will prompt you for a private key password. The -password ensures that no one can use or access the certificate without -your consent. Create and enter a password that you can remember. You will -use this password later to retrieve the certificate. +The MakeCert.exe tool will prompt you for a private key password. The password +ensures that no one can use or access the certificate without your consent. +Create and enter a password that you can remember. You will use this password +later to retrieve the certificate. -To verify that the certificate was generated correctly, use the -following command to get the certificate in the certificate -store on the computer. (You will not find a certificate file in the -file system directory.) +To verify that the certificate was generated correctly, use the following +command to get the certificate in the certificate store on the computer. (You +will not find a certificate file in the file system directory.) -At the Windows PowerShell prompt, type: +At the PowerShell prompt, type: +```powershell get-childitem cert:\CurrentUser\my -codesigning +``` -This command uses the Windows PowerShell Certificate provider to view -information about the certificate. +This command uses the PowerShell Certificate provider to view information +about the certificate. -If the certificate was created, the output shows the thumbprint -that identifies the certificate in a display that resembles the following: +If the certificate was created, the output shows the thumbprint that +identifies the certificate in a display that resembles the following: +```output Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My Thumbprint Subject ---------- ------- 4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ] +``` -# SIGN A SCRIPT - -------------- +## SIGN A SCRIPT -After you create a self-signed certificate, you can sign scripts. If you -use the AllSigned execution policy, signing a script permits you to run -the script on your computer. +After you create a self-signed certificate, you can sign scripts. If you use +the AllSigned execution policy, signing a script permits you to run the script +on your computer. -The following sample script, Add-Signature.ps1, signs a script. However, -if you are using the AllSigned execution policy, you must sign the +The following sample script, Add-Signature.ps1, signs a script. However, if +you are using the AllSigned execution policy, you must sign the Add-Signature.ps1 script before you run it. -To use this script, copy the following text into a text file, and -name it Add-Signature.ps1. - -Note: Be sure that the script file does not have a .txt file name -extension. If your text editor appends ".txt", enclose the file name -in quotation marks: "add-signature.ps1". +To use this script, copy the following text into a text file, and name it +Add-Signature.ps1. -## add-signature.ps1 +```powershell ## Signs a file param([string] $file=$(throw "Please specify a filename.")) $cert = @(Get-ChildItem cert:\CurrentUser\My -codesigning)[0] Set-AuthenticodeSignature $file $cert +``` -To sign the Add-Signature.ps1 script file, type the following commands at -the Windows PowerShell command prompt: +To sign the Add-Signature.ps1 script file, type the following commands at the +PowerShell command prompt: +```powershell $cert = @(Get-ChildItem cert:\CurrentUser\My -codesigning)[0] - Set-AuthenticodeSignature add-signature.ps1 $cert +``` -After the script is signed, you can run it on the local computer. -However, the script will not run on computers on which the Windows -PowerShell execution policy requires a digital signature from a -trusted authority. If you try, Windows PowerShell displays the following -error message: +After the script is signed, you can run it on the local computer. However, the +script will not run on computers on which the PowerShell execution +policy requires a digital signature from a trusted authority. If you try, +PowerShell displays the following error message: +```output The file C:\remote_file.ps1 cannot be loaded. The signature of the certificate cannot be verified. At line:1 char:15 + .\ remote_file.ps1 <<<< +``` -If Windows PowerShell displays this message when you run a -script that you did not write, treat the file as you would treat any -unsigned script. Review the code to determine whether you can trust the -script. - -# ENABLE STRONG PRIVATE KEY PROTECTION FOR YOUR CERTIFICATE +If PowerShell displays this message when you run a script that you did not +write, treat the file as you would treat any unsigned script. Review the code +to determine whether you can trust the script. ---------------------------------------------------------- +## ENABLE STRONG PRIVATE KEY PROTECTION FOR YOUR CERTIFICATE -If you have a private certificate on your computer, malicious -programs might be able to sign scripts on your behalf, which -authorizes Windows PowerShell to run them. +If you have a private certificate on your computer, malicious programs might +be able to sign scripts on your behalf, which authorizes PowerShell to run +them. -To prevent automated signing on your behalf, use Certificate -Manager (Certmgr.exe) to export your signing certificate to -a .pfx file. Certificate Manager is included in the Microsoft -.NET Framework SDK, the Microsoft Windows SDK, and in Internet -Explorer 5.0 and later versions. +To prevent automated signing on your behalf, use Certificate Manager +(Certmgr.exe) to export your signing certificate to a .pfx file. Certificate +Manager is included in the Microsoft .NET Framework SDK, the Microsoft Windows +SDK, and in Internet Explorer 5.0 and later versions. To export the certificate: 1. Start Certificate Manager. - 2. Select the certificate issued by PowerShell Local Certificate Root. - 3. Click Export to start the Certificate Export Wizard. - 4. Select "Yes, export the private key", and then click Next. - 5. Select "Enable strong protection." - 6. Type a password, and then type it again to confirm. - 7. Type a file name that has the .pfx file name extension. - 8. Click Finish. To re-import the certificate: 1. Start Certificate Manager. - 2. Click Import to start the Certificate Import Wizard. - -3. Open to the location of the .pfx file that you created during the -export process. - +3. Open to the location of the .pfx file that you created during the export + process. 4. On the Password page, select "Enable strong private key protection", -and then enter the password that you assigned during the export -process. - + and then enter the password that you assigned during the export + process. 5. Select the Personal certificate store. - 6. Click Finish. -# PREVENT THE SIGNATURE FROM EXPIRING +## PREVENT THE SIGNATURE FROM EXPIRING ------------------------------------ The digital signature in a script is valid until the signing certificate expires or as long as a time stamp server can verify that the script was signed while the signing certificate was valid. -Because most signing certificates are valid for one year only, using a -time stamp server ensures that users can use your script for many years -to come. +Because most signing certificates are valid for one year only, using a time +stamp server ensures that users can use your script for many years to come. # SEE ALSO @@ -321,13 +296,10 @@ to come. [about_Profiles](about_Profiles.md) -Get-ExecutionPolicy - -New-SelfSignedCertificate - -Set-ExecutionPolicy +[Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -Set-AuthenticodeSignature +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -"Introduction to Code Signing" (http://go.microsoft.com/fwlink/?LinkId=106296) +[Set-AuthenticodeSignature](../../Microsoft.PowerShell.Security/Set-AuthenticodeSignature.md) +[Introduction to Code Signing](http://go.microsoft.com/fwlink/?LinkId=106296) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md index 10b1d7bc00db..02d2b8d169e7 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,68 +7,61 @@ title: about_Splatting --- # About Splatting -## about_Splatting +## SHORT DESCRIPTION +Describes how to use splatting to pass parameters to commands in Windows +PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes how to use splatting to pass parameters to commands -in Windows PowerShell. +[This topic was contributed by Rohn Edwards of Gulfport, Mississippi, a system +administrator and the winner of the Advanced Division of the 2012 Scripting +Games. Revised for Windows PowerShell 3.0.] -# LONG DESCRIPTION +Splatting is a method of passing a collection of parameter values to a command +as unit. Windows PowerShell associates each value in the collection with a +command parameter. Splatted parameter values are stored in named splatting +variables, which look like standard variables, but begin with an At symbol (@) +instead of a dollar sign ($). The At symbol tells Windows PowerShell that you +are passing a collection of values, instead of a single value. -[This topic was contributed by Rohn Edwards of Gulfport, -Mississippi, a system administrator and the winner -of the Advanced Division of the 2012 Scripting Games. -Revised for Windows PowerShell 3.0.] +Splatting makes your commands shorter and easier to read. You can re-use the +splatting values in different command calls and use splatting to pass +parameter values from the `$PSBoundParameters` automatic variable to other +scripts and functions. -Splatting is a method of passing a collection of parameter -values to a command as unit. Windows PowerShell associates -each value in the collection with a command parameter. -Splatted parameter values are stored in named splatting -variables, which look like standard variables, but begin with -an At symbol (@) instead of a dollar sign ($). The At symbol -tells Windows PowerShell that you are passing a collection of -values, instead of a single value. +Beginning in Windows PowerShell 3.0, you can also use splatting to represent +all parameters of a command. -Splatting makes your commands shorter and easier to read. You -can re-use the splatting values in different command calls and -use splatting to pass parameter values from the `$PSBoundParameters` -automatic variable to other scripts and functions. +## SYNTAX -Beginning in Windows PowerShell 3.0, you can also use splatting -to represent all parameters of a command. - -# SYNTAX - -```powershell +``` @ @ ``` -To provide parameter values for positional parameters, in which -parameter names are not required, use the array syntax. To provide -parameter name and value pairs, use the hash table syntax. The -splatted value can appear anywhere in the parameter list. +To provide parameter values for positional parameters, in which parameter +names are not required, use the array syntax. To provide parameter name and +value pairs, use the hash table syntax. The splatted value can appear anywhere +in the parameter list. -When splatting, you do not need to use a hash table or an array to -pass all parameters. You may pass some parameters by using splatting -and pass others by position or by parameter name. Also, you can splat -multiple objects in a single command just so you pass no more than one -value for each parameter. +When splatting, you do not need to use a hash table or an array to pass all +parameters. You may pass some parameters by using splatting and pass others by +position or by parameter name. Also, you can splat multiple objects in a +single command just so you pass no more than one value for each parameter. -# SPLATTING WITH HASH TABLES +## SPLATTING WITH HASH TABLES -Use a hash table to splat parameter name and value pairs. You can use -this format for all parameter types, including positional and named -parameters and switch parameters. +Use a hash table to splat parameter name and value pairs. You can use this +format for all parameter types, including positional and named parameters and +switch parameters. -The following examples compare two `Copy-Item` commands that copy the -Test.txt file to the Test2.txt file in the same directory. +The following examples compare two `Copy-Item` commands that copy the Test.txt +file to the Test2.txt file in the same directory. -The first example uses the traditional format in which parameter names -are included. +The first example uses the traditional format in which parameter names are +included. ```powershell Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf @@ -76,9 +69,9 @@ Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf The second example uses hash table splatting. The first command creates a hash table of parameter-name and parameter-value pairs and stores it in the -\$HashArguments variable. The second command uses the `$HashArguments` variable -in a command with splatting. The At symbol (`@HashArguments`) replaces the -dollar sign (`$HashArguments`) in the command. +\$HashArguments variable. The second command uses the `$HashArguments` +variable in a command with splatting. The At symbol (`@HashArguments`) +replaces the dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. @@ -91,11 +84,11 @@ $HashArguments = @{ Copy-Item @HashArguments ``` -Note: In the first command, the At symbol (@) indicates a hash table, not -a splatted value. The syntax for hash tables in Windows PowerShell is: +Note: In the first command, the At symbol (@) indicates a hash table, not a +splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* -# SPLATTING WITH ARRAYS +## SPLATTING WITH ARRAYS Use an array to splat values for positional parameters, which do not require parameter names. The values must be in position-number order in the array. @@ -122,8 +115,7 @@ $ArrayArguments = "test.txt", "test2.txt" Copy-Item @ArrayArguments -WhatIf ``` -# EXAMPLES - +## EXAMPLES This example shows how to re-use splatted values in different commands. The commands in this example use the Write-Host cmdlet to write messages to the @@ -153,18 +145,16 @@ Write-Host "This is a test." @Colors Write-Host @Colors "This is another test." ``` -This example shows how to forward their parameters to other commands by -using splatting and the `$PSBoundParameters` automatic variable. +This example shows how to forward their parameters to other commands by using +splatting and the `$PSBoundParameters` automatic variable. -The $PSBoundParameters automatic variable is a dictionary -(System.Collections.Generic.Dictionary) that contains all of the -parameter names and values that are used when a script or function -is run. +The \$PSBoundParameters automatic variable is a dictionary +(System.Collections.Generic.Dictionary) that contains all of the parameter +names and values that are used when a script or function is run. -In the following example, we use the `$PSBoundParameters` variable to -forward the parameters values passed to a script or function from Test2 -function to the Test1 function. Both calls to the Test1 function from -Test2 use splatting. +In the following example, we use the `$PSBoundParameters` variable to forward +the parameters values passed to a script or function from Test2 function to +the Test1 function. Both calls to the Test1 function from Test2 use splatting. ```powershell function Test1 @@ -188,7 +178,9 @@ function Test2 $LimitedParameters.Remove("a") | Out-Null Test1 @LimitedParameters } +``` +```output Test2 -a 1 -b 2 -c 3 1 2 @@ -197,7 +189,7 @@ Test2 -a 1 -b 2 -c 3 3 ``` -# SPLATTING COMMAND PARAMETERS +## SPLATTING COMMAND PARAMETERS You can use splatting to represent the parameters of a command. This technique is useful when you are creating a proxy function, that is, a function that @@ -207,8 +199,8 @@ To splat the parameters of a command, use `@Args` to represent the command parameters. This technique is easier than enumerating command parameters and it works without revision even if the parameters of the called command change. -The feature uses the `$Args` automatic variable, which contains -all unassigned parameter values. +The feature uses the `$Args` automatic variable, which contains all unassigned +parameter values. For example, the following function calls the Get-Process cmdlet. In this function, `@Args` represents all of the parameters of the Get-Process cmdlet. @@ -217,19 +209,24 @@ function, `@Args` represents all of the parameters of the Get-Process cmdlet. function Get-MyProcess { Get-Process @Args } ``` -When you use the Get-MyProcess function, all unassigned -parameters and parameter values are passed to `@Args`, as -shown in the following commands. +When you use the Get-MyProcess function, all unassigned parameters and +parameter values are passed to `@Args`, as shown in the following commands. ```powershell Get-MyProcess -Name PowerShell +``` +```output Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 463 46 225484 237196 719 15.86 3228 powershell +``` +```powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo +``` +```output ProductVersion FileVersion FileName -------------- ----------- -------- 6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... @@ -248,7 +245,9 @@ function Get-MyCommand } Get-MyCommand -P -C -Name PowerShell +``` +```output Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Transactions.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Transactions.md index e93860f24d7f..5c292571cdac 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Transactions.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Transactions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,445 +7,454 @@ title: about_Transactions --- # About Transactions -## about_Transactions +## SHORT DESCRIPTION +Describes how to manage transacted operations in PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes how to manage transacted operations in Windows PowerShell. +Transactions are supported in PowerShell beginning in PowerShell 2.0. This +feature enables you to start a transaction, to indicate which commands are +part of the transaction, and to commit or roll back a transaction. -# LONG DESCRIPTION +## ABOUT TRANSACTIONS -Transactions are supported in Windows PowerShell beginning -in Windows PowerShell 2.0. This feature enables you to start -a transaction, to indicate which commands are part of the -transaction, and to commit or roll back a transaction. +In PowerShell, a transaction is a set of one or more commands that are managed +as a logical unit. A transaction can be completed ("committed"), which changes +data affected by the transaction. Or, a transaction can be completely undone +("rolled back") so that the affected data is not changed by the transaction. -# ABOUT TRANSACTIONS +Because the commands in a transaction are managed as a unit, either all +commands are committed, or all commands are rolled back. +Transactions are widely used in data processing, most notably in database +operations and for financial transactions. Transactions are most often used +when the worst-case scenario for a set of commands is not that they all fail, +but that some commands succeed while others fail, leaving the system in a +damaged, false, or uninterpretable state that is difficult to repair. -In Windows PowerShell, a transaction is a set of one or more -commands that are managed as a logical unit. A transaction can -be completed ("committed"), which changes data affected by the -transaction. Or, a transaction can be completely undone ("rolled back") -so that the affected data is not changed by the transaction. +## TRANSACTION CMDLETS -Because the commands in a transaction are managed as a unit, -either all commands are committed, or all commands are rolled -back. +PowerShell includes several cmdlets designed for managing transactions. -Transactions are widely used in data processing, most notably -in database operations and for financial transactions. Transactions -are most often used when the worst-case scenario for a set of -commands is not that they all fail, but that some commands succeed -while others fail, leaving the system in a damaged, false, or -uninterpretable state that is difficult to repair. - -# TRANSACTION CMDLETS - - -Windows PowerShell includes several cmdlets designed for managing -transactions. - -Cmdlet Description --------------- --------------------------------- -Start-Transaction Starts a new transaction. - -Use-Transaction Adds a command or expression to the -transaction. The command must use -transaction-enabled objects. - -Undo-Transaction Rolls back the transaction so that -no data is changed by the transaction. - -Complete-Transaction Commits the transaction. The data -affected by the transaction is changed. - -Get-Transaction Gets information about the active -transaction. +- Start-Transaction: Starts a new transaction. +- Use-Transaction: Adds a command or expression to the transaction. The + command must use transaction-enabled objects. +- Undo-Transaction: Rolls back the transaction so that no data is changed by + the transaction. +- Complete-Transaction: Commits the transaction. The data affected by the + transaction is changed. +- Get-Transaction: Gets information about the active transaction. For a list of transaction cmdlets, type: +```powershell get-command *transaction +``` For detailed information about the cmdlets, type: -get-help -detailed - -For example: - +```powershell get-help use-transaction -detailed +``` -# TRANSACTION-ENABLED ELEMENTS - +## TRANSACTION-ENABLED ELEMENTS -To participate in a transaction, both the cmdlet and the provider -must support transactions. This feature is built in to the objects -that are affected by the transaction. +To participate in a transaction, both the cmdlet and the provider must support +transactions. This feature is built in to the objects that are affected by the +transaction. -The Windows PowerShell Registry provider supports transactions -in Windows Vista. The TransactedString object -(Microsoft.PowerShell.Commands.Management.TransactedString) works -with any operating system that runs Windows PowerShell. +The PowerShell Registry provider supports transactions in Windows Vista. The +TransactedString object +(Microsoft.PowerShell.Commands.Management.TransactedString) works with any +operating system that runs PowerShell. -Other Windows PowerShell providers can support transactions. To -find the Windows PowerShell providers in your session that support -transactions, use the following command to find the "Transactions" -value in the Capabilities property of providers: +Other PowerShell providers can support transactions. To find the PowerShell +providers in your session that support transactions, use the following command +to find the "Transactions" value in the Capabilities property of providers: +```powershell get-psprovider | where {$_.Capabilities -like "transactions"} +``` -For more information about a provider, see the Help for the provider. -To get provider Help, type: +For more information about a provider, see the Help for the provider. To get +provider Help, type: +``` get-help +``` For example, to get Help for the Registry provider, type: +```powershell get-help registry +``` -# THE USETRANSACTION PARAMETER - +## THE USETRANSACTION PARAMETER -Cmdlets that can support transactions have a UseTransaction -parameter. This parameter includes the command in the active -transaction. You can use the full parameter name or its alias, -"usetx". +Cmdlets that can support transactions have a UseTransaction parameter. This +parameter includes the command in the active transaction. You can use the full +parameter name or its alias, "usetx". -The parameter can be used only when the session contains an -active transaction. If you enter a command with the UseTransaction -parameter when there is no active transaction, the command fails. +The parameter can be used only when the session contains an active +transaction. If you enter a command with the UseTransaction parameter when +there is no active transaction, the command fails. To find cmdlets with the UseTransaction parameter, type: +```powershell get-help * -parameter UseTransaction +``` -In Windows PowerShell core, all of the cmdlets designed to work -with Windows PowerShell providers support transactions. As a -result, you can use the provider cmdlets to manage transactions. +In PowerShell core, all of the cmdlets designed to work with PowerShell +providers support transactions. As a result, you can use the provider cmdlets +to manage transactions. -For more information about Windows PowerShell providers, -see about_Providers. +For more information about PowerShell providers, see [about_Providers](about_Providers.md). -# THE TRANSACTION OBJECT +## THE TRANSACTION OBJECT - -Transactions are represented in Windows PowerShell by a -transaction object, System.Management.Automation.Transaction. +Transactions are represented in PowerShell by a transaction object, +System.Management.Automation.Transaction. The object has the following properties: -RollbackPreference: -Contains the rollback preference set for the current -transaction. You can set the rollback preference when you -use Start-Transaction to start the transaction. +- RollbackPreference: Contains the rollback preference set for the current + transaction. You can set the rollback preference when you use + Start-Transaction to start the transaction. -The rollback preference determines the conditions under -which the transaction is rolled back automatically. Valid -values are Error, TerminatingError, and Never. The default -value is Error. + The rollback preference determines the conditions under which the transaction + is rolled back automatically. Valid values are Error, TerminatingError, and + Never. The default value is Error. -Status: -Contains the current status of the transaction. Valid -values are Active, Committed, and RolledBack. +- Status: Contains the current status of the transaction. Valid values are + Active, Committed, and RolledBack. -SubscriberCount: -Contains the number of subscribers to the transaction. A -subscriber is added to a transaction when you start a -transaction while another transaction is in progress. The -subscriber count is decremented when a subscriber commits -the transaction. +- SubscriberCount: Contains the number of subscribers to the transaction. A + subscriber is added to a transaction when you start a transaction while + another transaction is in progress. The subscriber count is decremented when + a subscriber commits the transaction. -# ACTIVE TRANSACTIONS +## ACTIVE TRANSACTIONS +In PowerShell, only one transaction is active at a time, and you can manage +only the active transaction. Multiple transactions can be in progress in the +same session at the same time, but only the most-recently started transaction +is active. -In Windows PowerShell, only one transaction is active at a -time, and you can manage only the active transaction. Multiple -transactions can be in progress in the same session at the same -time, but only the most-recently started transaction is active. +As a result, you cannot specify a particular transaction when using the +transaction cmdlets. Commands always apply to the active transaction. -As a result, you cannot specify a particular transaction when -using the transaction cmdlets. Commands always apply to the -active transaction. - -This is most evident in the behavior of the Get-Transaction cmdlet. -When you enter a Get-Transaction command, Get-Transaction always -gets only one transaction object. This object is the object that -represents the active transaction. +This is most evident in the behavior of the Get-Transaction cmdlet. When you +enter a Get-Transaction command, Get-Transaction always gets only one +transaction object. This object is the object that represents the active +transaction. To manage a different transaction, you must first finish the active -transaction, either by committing it or rolling it back. When you -do this, the previous transaction becomes active automatically. -Transactions become active in the reverse of order of which they are -started, so that the most recently started transaction is always -active. +transaction, either by committing it or rolling it back. When you do this, the +previous transaction becomes active automatically. Transactions become active +in the reverse of order of which they are started, so that the most recently +started transaction is always active. -# SUBSCRIBERS AND INDEPENDENT TRANSACTIONS +## SUBSCRIBERS AND INDEPENDENT TRANSACTIONS +If you start a transaction while another transaction is in progress, by +default, PowerShell does not start a new transaction. Instead, it adds a +"subscriber" to the current transaction. -If you start a transaction while another transaction is in progress, -by default, Windows PowerShell does not start a new transaction. -Instead, it adds a "subscriber" to the current transaction. +When a transaction has multiple subscribers, a single Undo-Transaction command +at any point rolls back the entire transaction for all subscribers. However, +to commit the transaction, you must enter a Complete-Transaction command for +every subscriber. -When a transaction has multiple subscribers, a single -Undo-Transaction command at any point rolls back the entire -transaction for all subscribers. However, to commit the transaction, -you must enter a Complete-Transaction command for every subscriber. - -To find the number of subscribers to a transaction, check the -SubscriberCount property of the transaction object. For example, -the following command uses the Get-Transaction cmdlet to get -the value of the SubscriberCount property of the active transaction: +To find the number of subscribers to a transaction, check the SubscriberCount +property of the transaction object. For example, the following command uses +the Get-Transaction cmdlet to get the value of the SubscriberCount property of +the active transaction: +```powershell (Get-Transaction).SubscriberCount +``` -Adding a subscriber is the default behavior because most transactions -that are started while another transaction is in progress are related -to the original transaction. In the typical model, a script that -contains a transaction calls a helper script that contains its own -transaction. Because the transactions are related, they should be -rolled back or committed as a unit. - -However, you can start a transaction that is independent of the -current transaction by using the Independent parameter of the -Start-Transaction cmdlet. +Adding a subscriber is the default behavior because most transactions that are +started while another transaction is in progress are related to the original +transaction. In the typical model, a script that contains a transaction calls +a helper script that contains its own transaction. Because the transactions +are related, they should be rolled back or committed as a unit. -When you start an independent transaction, Start-Transaction -creates a new transaction object, and the new transaction becomes -the active transaction. The independent transaction can be -committed or rolled back without affecting the original transaction. +However, you can start a transaction that is independent of the current +transaction by using the Independent parameter of the Start-Transaction +cmdlet. -When the independent transaction is finished (committed or rolled -back), the original transaction becomes the active transaction -again. +When you start an independent transaction, Start-Transaction creates a new +transaction object, and the new transaction becomes the active transaction. +The independent transaction can be committed or rolled back without affecting +the original transaction. -# CHANGING DATA +When the independent transaction is finished (committed or rolled back), the +original transaction becomes the active transaction again. +## CHANGING DATA -When you use transactions to change data, the data that is affected -by the transaction is not changed until you commit the transaction. -However, the same data can be changed by commands that are not -part of the transaction. +When you use transactions to change data, the data that is affected by the +transaction is not changed until you commit the transaction. However, the same +data can be changed by commands that are not part of the transaction. -Keep this in mind when you are using transactions to manage shared -data. Typically, databases have mechanisms that lock the data while -you are working on it, preventing other users, and other commands, -scripts, and functions, from changing it. +Keep this in mind when you are using transactions to manage shared data. +Typically, databases have mechanisms that lock the data while you are working +on it, preventing other users, and other commands, scripts, and functions, +from changing it. -However, the lock is a feature of the database. It is not related -to transactions. If you are working in a transaction-enabled -file system or other data store, the data can be changed while -the transaction is in progress. +However, the lock is a feature of the database. It is not related to +transactions. If you are working in a transaction-enabled file system or other +data store, the data can be changed while the transaction is in progress. -# EXAMPLES +## EXAMPLES -The examples in this section use the Windows PowerShell Registry -provider and assume that you are familiar with it. For information -about the Registry provider, type "get-help registry". +The examples in this section use the PowerShell Registry provider and assume +that you are familiar with it. For information about the Registry provider, +type "get-help registry". -# EXAMPLE 1: COMMITTING A TRANSACTION +### EXAMPLE 1: COMMITTING A TRANSACTION +To create a transaction, use the Start-Transaction cmdlet. The following +command starts a transaction with the default settings. -To create a transaction, use the Start-Transaction cmdlet. The -following command starts a transaction with the default settings. - +```powershell start-transaction +``` -To include commands in the transaction, use the UseTransaction -parameter of the cmdlet. By default, commands are not included -in the transaction, +To include commands in the transaction, use the UseTransaction parameter of +the cmdlet. By default, commands are not included in the transaction, -For example, the following command, which sets the current -location in the Software key of the HKCU: drive, is not included -in the transaction. +For example, the following command, which sets the current location in the +Software key of the HKCU: drive, is not included in the transaction. +```powershell cd hkcu:\Software +``` The following command, which creates the MyCompany key, uses the -UseTransaction parameter of the New-Item cmdlet to include the -command in the active transaction. +UseTransaction parameter of the New-Item cmdlet to include the command in the +active transaction. +```powershell new-item MyCompany -UseTransaction +``` -The command returns an object that represents the new key, but -because the command is part of the transaction, the registry -is not yet changed. +The command returns an object that represents the new key, but because the +command is part of the transaction, the registry is not yet changed. +``` Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -0 0 MyCompany {} + 0 0 MyCompany {} +``` -To commit the transaction, use the Complete-Transaction cmdlet. -Because it always affects the active transaction, you cannot specify -the transaction. +To commit the transaction, use the Complete-Transaction cmdlet. Because it +always affects the active transaction, you cannot specify the transaction. +```powershell complete-transaction +``` As a result, the MyCompany key is added to the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# EXAMPLE 2: ROLLING BACK A TRANSACTION +### EXAMPLE 2: ROLLING BACK A TRANSACTION +To create a transaction, use the Start-Transaction cmdlet. The following +command starts a transaction with the default settings. -To create a transaction, use the Start-Transaction cmdlet. The -following command starts a transaction with the default settings. - +```powershell start-transaction +``` The following command, which creates the MyOtherCompany key, uses the -UseTransaction parameter of the New-Item cmdlet to include the -command in the active transaction. +UseTransaction parameter of the New-Item cmdlet to include the command in the +active transaction. +```powershell new-item MyOtherCompany -UseTransaction +``` -The command returns an object that represents the new key, but -because the command is part of the transaction, the registry -is not yet changed. +The command returns an object that represents the new key, but because the +command is part of the transaction, the registry is not yet changed. +``` Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -0 0 MyOtherCompany {} + 0 0 MyOtherCompany {} +``` -To roll back the transaction, use the Undo-Transaction cmdlet. -Because it always affects the active transaction, you do not specify -the transaction. +To roll back the transaction, use the Undo-Transaction cmdlet. Because it +always affects the active transaction, you do not specify the transaction. +```powershell Undo-transaction +``` The result is that the MyOtherCompany key is not added to the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# EXAMPLE 3: PREVIEWING A TRANSACTION +### EXAMPLE 3: PREVIEWING A TRANSACTION +Typically, the commands used in a transaction change data. However, the +commands that get data are useful in a transaction, too, because they get data +inside of the transaction. This provides a preview of the changes that +committing the transaction would cause. -Typically, the commands used in a transaction change data. However, -the commands that get data are useful in a transaction, too, because -they get data inside of the transaction. This provides a preview of the -changes that committing the transaction would cause. - -The following example shows how to use the Get-ChildItem command -(the alias is "dir") to preview the changes in a transaction. +The following example shows how to use the Get-ChildItem command (the alias is +"dir") to preview the changes in a transaction. The following command starts a transaction. +```powershell start-transaction +``` -The following command uses the New-ItemProperty cmdlet to add the -MyKey registry entry to the MyCompany key. The command uses the -UseTransaction parameter to include the command in the transaction. +The following command uses the New-ItemProperty cmdlet to add the MyKey +registry entry to the MyCompany key. The command uses the UseTransaction +parameter to include the command in the transaction. +```powershell new-itemproperty -path MyCompany -Name MyKey -value 123 -UseTransaction +``` -The command returns an object representing the new registry entry, -but the registry entry is not changed. +The command returns an object representing the new registry entry, but the +registry entry is not changed. +``` MyKey ----- -# 123 - +123 +``` To get the items that are currently in the registry, use a Get-ChildItem -command ("dir") without the UseTransaction parameter. The following -command gets items that begin with "M." +command ("dir") without the UseTransaction parameter. The following command +gets items that begin with "M." +```powershell dir m* +``` The result shows that no entries have yet been added to the MyCompany key. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` To preview the effect of committing the transaction, enter a Get-ChildItem -("dir") command with the UseTransaction parameter. This command has a view -of the data from within the transaction. +("dir") command with the UseTransaction parameter. This command has a view of +the data from within the transaction. +```powershell dir m* -useTransaction +``` -The result shows that, if the transaction is committed, the MyKey entry -will be added to the MyCompany key. +The result shows that, if the transaction is committed, the MyKey entry will +be added to the MyCompany key. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 1 MyCompany {MyKey} - -# EXAMPLE 4: COMBINING TRANSACTED AND NON-TRANSACTED COMMANDS - + 83 1 Microsoft {(default)} + 0 1 MyCompany {MyKey} +``` -You can enter non-transacted commands during a transaction. The -non-transacted commands affect the data immediately, but they do -not affect the transaction. +### EXAMPLE 4: COMBINING TRANSACTED AND NON-TRANSACTED COMMANDS -The following command starts a transaction in the HKCU:\Software -registry key. +You can enter non-transacted commands during a transaction. The non-transacted +commands affect the data immediately, but they do not affect the transaction. +The following command starts a transaction in the HKCU:\Software registry key. +```powershell start-transaction +``` -The next three commands use the New-Item cmdlet to add keys to -the registry. The first and third commands use the UseTransaction -parameter to include the commands in the transaction. The second -command omits the parameter. Because the second command is not -included in the transaction, it is effective immediately. +The next three commands use the New-Item cmdlet to add keys to the registry. +The first and third commands use the UseTransaction parameter to include the +commands in the transaction. The second command omits the parameter. Because +the second command is not included in the transaction, it is effective +immediately. +```powershell new-item MyCompany1 -UseTransaction - new-item MyCompany2 - new-item MyCompany3 -UseTransaction +``` -To view the current state of the registry, use a Get-ChildItem ("dir") -command without the UseTransaction parameter. This command gets items -that begin with "M." +To view the current state of the registry, use a Get-ChildItem ("dir") command +without the UseTransaction parameter. This command gets items that begin with +"M." +```powershell dir m* +``` -The result shows that the MyCompany2 key is added to the registry, but -the MyCompany1 and MyCompany3 keys, which are part of the transaction, -are not added. +The result shows that the MyCompany2 key is added to the registry, but the +MyCompany1 and MyCompany3 keys, which are part of the transaction, are not +added. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany2 {} + 83 1 Microsoft {(default)} + 0 0 MyCompany2 {} +``` The following command commits the transaction. +```powershell complete-transaction +``` Now, the keys that were added as part of the transaction appear in the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property @@ -454,327 +463,389 @@ SKC VC Name Property 0 0 MyCompany1 {} 0 0 MyCompany2 {} 0 0 MyCompany3 {} +``` -# EXAMPLE 5: USING AUTOMATIC ROLLBACK +### EXAMPLE 5: USING AUTOMATIC ROLLBACK +When a command in a transaction generates an error of any kind, the +transaction is automatically rolled back. -When a command in a transaction generates an error -of any kind, the transaction is automatically rolled -back. - -This default behavior is designed for scripts that -run transactions. Scripts are typically well tested -and include error-handling logic, so errors are not +This default behavior is designed for scripts that run transactions. Scripts +are typically well tested and include error-handling logic, so errors are not expected and should terminate the transaction. -The first command starts a transaction in the HKCU:\Software -registry key. +The first command starts a transaction in the HKCU:\Software registry key. +```powershell start-transaction +``` -The following command uses the New-Item cmdlet to -add the MyCompany key to the registry. The command uses -the UseTransaction parameter (the alias is "usetx") to include -the command in the transaction. +The following command uses the New-Item cmdlet to add the MyCompany key to the +registry. The command uses the UseTransaction parameter (the alias is "usetx") +to include the command in the transaction. +```powershell New-Item MyCompany -UseTX +``` -Because the MyCompany key already exists in the registry, -the command fails, and the transaction is rolled back. +Because the MyCompany key already exists in the registry, the command fails, +and the transaction is rolled back. +```output New-Item : A key at this path already exists At line:1 char:9 + new-item <<<< MyCompany -usetx +``` -A Get-Transaction command confirms that the transaction -has been rolled back and that the SubscriberCount is 0. +A Get-Transaction command confirms that the transaction has been rolled back +and that the SubscriberCount is 0. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 0 RolledBack +``` -# EXAMPLE 6: CHANGING THE ROLLBACK PREFERENCE +### EXAMPLE 6: CHANGING THE ROLLBACK PREFERENCE - -If you want the transaction to be more error tolerant, -you can use the RollbackPreference parameter of -Start-Transaction to change the preference. +If you want the transaction to be more error tolerant, you can use the +RollbackPreference parameter of Start-Transaction to change the preference. The following command starts a transaction with a rollback preference of "Never". +```powershell start-transaction -rollbackpreference Never +``` -In this case, when the command fails, the transaction -is not automatically rolled back. +In this case, when the command fails, the transaction is not automatically +rolled back. +```powershell New-Item MyCompany -UseTX +``` +```output New-Item : A key at this path already exists At line:1 char:9 + new-item <<<< MyCompany -usetx +``` -Because the transaction is still active, you can -resubmit the command as part of the transaction. +Because the transaction is still active, you can resubmit the command as part +of the transaction. +```powershell New-Item MyOtherCompany -UseTX +``` -# EXAMPLE 7: USING THE USE-TRANSACTION CMDLET - +### EXAMPLE 7: USING THE USE-TRANSACTION CMDLET -The Use-Transaction cmdlet enables you to do direct scripting -against transaction-enabled Microsoft .NET Framework objects. -Use-Transaction takes a script block that can only contain commands -and expressions that use transaction-enabled .NET Framework objects, -such as instances of the +The Use-Transaction cmdlet enables you to do direct scripting against +transaction-enabled Microsoft .NET Framework objects. Use-Transaction takes a +script block that can only contain commands and expressions that use +transaction-enabled .NET Framework objects, such as instances of the Microsoft.PowerShell.Commands.Management.TransactedString class. The following command starts a transaction. +```powershell start-transaction +``` -The following New-Object command creates an instance of the -TransactedString class and saves it in the $t variable. +The following New-Object command creates an instance of the TransactedString +class and saves it in the $t variable. +```powershell $t = New-Object Microsoft.PowerShell.Commands.Management.TransactedString +``` -The following command uses the Append method of the TransactedString -object to add text to the string. Because the command is not part -of the transaction, the change is effective immediately. +The following command uses the Append method of the TransactedString object to +add text to the string. Because the command is not part of the transaction, +the change is effective immediately. +```powershell $t.append("Windows") +``` -The following command uses the same Append method to add text, but -it adds the text as part of the transaction. The command is enclosed -in braces, and it is set as the value of the ScriptBlock parameter of -Use-Transaction. The UseTransaction parameter (UseTx) is required. +The following command uses the same Append method to add text, but it adds the +text as part of the transaction. The command is enclosed in braces, and it is +set as the value of the ScriptBlock parameter of Use-Transaction. The +UseTransaction parameter (UseTx) is required. +```powershell use-transaction {$t.append(" PowerShell")} -usetx +``` -To see the current content of the transacted string in $t, use the -ToString method of the TransactedString object. +To see the current content of the transacted string in $t, use the ToString +method of the TransactedString object. +```powershell $t.tostring() +``` The output shows that only the non-transacted changes are effective. +```output Windows +``` -To see the current content of the transacted string in $t from within -the transaction, embed the expression in a Use-Transaction command. +To see the current content of the transacted string in $t from within the +transaction, embed the expression in a Use-Transaction command. +```powershell use-transaction {$s.tostring()} -usetx +``` The output shows the transaction view. -Windows PowerShell +```output +PowerShell +``` The following command commits the transaction. +```powershell complete-transaction +``` To see the final string: +``` $t.tostring() +PowerShell +``` -Windows PowerShell +### EXAMPLE 8: MANAGING MULTI-SUBSCRIBER TRANSACTIONS -# EXAMPLE 8: MANAGING MULTI-SUBSCRIBER TRANSACTIONS - - -When you start a transaction while another transaction is in -progress, Windows PowerShell does not create a second transaction -by default. Instead, it adds a subscriber to the current -transaction. +When you start a transaction while another transaction is in progress, +PowerShell does not create a second transaction by default. Instead, it adds a +subscriber to the current transaction. -This example shows how to view and manage a multi-subscriber -transaction. +This example shows how to view and manage a multi-subscriber transaction. Begin by starting a transaction in the HKCU:\Software key. +```powershell start-transaction +``` -The following command uses the Get-Transaction command to -get the active transaction. +The following command uses the Get-Transaction command to get the active +transaction. +```powershell get-transaction +``` The result shows the object that represents the active transaction. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The following command adds the MyCompany key to the registry. -The command uses the UseTransaction parameter to include the -command in the transaction. +The following command adds the MyCompany key to the registry. The command uses +the UseTransaction parameter to include the command in the transaction. +```powershell new-item MyCompany -UseTransaction +``` -The following command uses the Start-Transaction command to -start a transaction. Although this command is typed at the command -prompt, this scenario is more likely to happen when you run a -script that contains a transaction. +The following command uses the Start-Transaction command to start a +transaction. Although this command is typed at the command prompt, this +scenario is more likely to happen when you run a script that contains a +transaction. +```powershell start-transaction +``` -A Get-Transaction command shows that the subscriber count on the -transaction object is incremented. The value is now 2. +A Get-Transaction command shows that the subscriber count on the transaction +object is incremented. The value is now 2. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 2 Active +``` -The next command uses the New-ItemProperty cmdlet to add the -MyKey registry entry to the MyCompany key. It uses the UseTransaction -parameter to include the command in the transaction. +The next command uses the New-ItemProperty cmdlet to add the MyKey registry +entry to the MyCompany key. It uses the UseTransaction parameter to include +the command in the transaction. +```powershell new-itemproperty -path MyCompany -name MyKey -UseTransaction +``` -The MyCompany key does not exist in the registry, but this -command succeeds because the two commands are part of the -same transaction. +The MyCompany key does not exist in the registry, but this command succeeds +because the two commands are part of the same transaction. -The following command commits the transaction. If it rolled back -the transaction, the transaction would be rolled back for all the -subscribers. +The following command commits the transaction. If it rolled back the +transaction, the transaction would be rolled back for all the subscribers. +```powershell complete-transaction +``` -A Get-Transaction command shows that the subscriber count on the -transaction object is 1, but the value of Status is still Active -(not Committed). +A Get-Transaction command shows that the subscriber count on the transaction +object is 1, but the value of Status is still Active (not Committed). +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -To finish committing the transaction, enter a second Complete- -Transaction command. To commit a multi-subscriber transaction, -you must enter one Complete-Transaction command for each -Start-Transaction command. +To finish committing the transaction, enter a second Complete- Transaction +command. To commit a multi-subscriber transaction, you must enter one +Complete-Transaction command for each Start-Transaction command. +```powershell complete-transaction +``` -Another Get-Transaction command shows that the transaction -has been committed. +Another Get-Transaction command shows that the transaction has been committed. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 0 Committed +``` -# EXAMPLE 9: MANAGING INDEPENDENT TRANSACTIONS - +### EXAMPLE 9: MANAGING INDEPENDENT TRANSACTIONS -When you start a transaction while another transaction is in -progress, you can use the Independent parameter of Start-Transaction -to make the new transaction independent of the original transaction. +When you start a transaction while another transaction is in progress, you can +use the Independent parameter of Start-Transaction to make the new transaction +independent of the original transaction. -When you do, Start-Transaction creates a new transaction object -and makes the new transaction the active transaction. +When you do, Start-Transaction creates a new transaction object and makes the +new transaction the active transaction. -Begin by starting a transaction in the HKCU:\Software key. +Begin by starting a transaction in the HKCU:\\Software key. +```powershell start-transaction +``` -The following command uses the Get-Transaction command to -get the active transaction. +The following command uses the Get-Transaction command to get the active +transaction. +```powershell get-transaction +``` The result shows the object that represents the active transaction. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The following command adds the MyCompany registry key as part of -the transaction. It uses the UseTransaction parameter (UseTx) -to include the command in the active transaction. +The following command adds the MyCompany registry key as part of the +transaction. It uses the UseTransaction parameter (UseTx) to include the +command in the active transaction. +```powershell new-item MyCompany -use +``` -The following command starts a new transaction. The command uses -the Independent parameter to indicate that this transaction -is not a subscriber to the active transaction. +The following command starts a new transaction. The command uses the +Independent parameter to indicate that this transaction is not a subscriber to +the active transaction. +```powershell start-transaction -independent +``` -When you create an independent transaction, the new (most-recently -created) transaction becomes the active transaction. You can use -a Get-Transaction command to get the active transaction. +When you create an independent transaction, the new (most-recently created) +transaction becomes the active transaction. You can use a Get-Transaction +command to get the active transaction. +```powershell get-transaction +``` -Note that the SubscriberCount of the transaction is 1, indicating -that there are no other subscribers and that the transaction is -new. +Note that the SubscriberCount of the transaction is 1, indicating that there +are no other subscribers and that the transaction is new. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The new transaction must be finished (either committed or rolled -back) before you can manage the original transaction. +The new transaction must be finished (either committed or rolled back) before +you can manage the original transaction. -The following command adds the MyOtherCompany key to the registry. -It uses the UseTransaction parameter (UseTx) to include the command -in the active transaction. +The following command adds the MyOtherCompany key to the registry. It uses the +UseTransaction parameter (UseTx) to include the command in the active +transaction. +```powershell new-item MyOtherCompany -usetx +``` -Now, roll back the transaction. If there were a single -transaction with two subscribers, rolling back the transaction -would roll back the entire transaction for all the subscribers. +Now, roll back the transaction. If there were a single transaction with two +subscribers, rolling back the transaction would roll back the entire +transaction for all the subscribers. -However, because these transactions are independent, rolling -back the newest transaction cancels the registry changes and -makes the original transaction the active transaction. +However, because these transactions are independent, rolling back the newest +transaction cancels the registry changes and makes the original transaction +the active transaction. +```powershell undo-transaction +``` -A Get-Transaction command confirms that the original -transaction is still active in the session. +A Get-Transaction command confirms that the original transaction is still +active in the session. +```powershell get-transaction +``` +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` The following command commits the active transaction. +```powershell complete-transaction +``` -A Get-ChildItem command shows that the registry has been -changed. +A Get-ChildItem command shows that the registry has been changed. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# SEE ALSO +## SEE ALSO -Start-Transaction +[Start-Transaction](../../Microsoft.PowerShell.Management/Start-Transaction.md) -Get-Transaction +[Get-Transaction](../../Microsoft.PowerShell.Management/Get-Transaction.md) -Complete-Transaction +[Complete-Transaction](../../Microsoft.PowerShell.Management/Complete-Transaction.md) -Undo-Transaction +[Undo-Transaction](../../Microsoft.PowerShell.Management/Undo-Transaction.md) -Use-Transaction +[Use-Transaction](../../Microsoft.PowerShell.Management/Use-Transaction.md) -Registry (provider) +[Get-PSProvider](../../Microsoft.PowerShell.Management/Get-PSProvider.md) -[about_Providers](about_Providers.md) - -Get-PSProvider - -Get-ChildItem +[Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) +[about_Providers](about_Providers.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index 8c83f99a3472..7d45f6555135 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,487 +7,455 @@ title: about_Updatable_Help --- # About Updatable Help -## about_Updatable_Help +## SHORT DESCRIPTION +Describes the updatable help system in PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes the updatable help system in Windows PowerShell. +PowerShell provides several different ways to access the most up-to-date help +topics for PowerShell cmdlets and concepts. -# LONG DESCRIPTION +The Updatable Help system, introduced in PowerShell 3.0, is designed to assure +that you always have the newest help topics on your local computer so that you +can read them at the command line. It makes it easy to download and install +help files and to update them whenever newer help files become available. -Windows PowerShell provides several different ways to access -the most up-to-date help topics for Windows PowerShell cmdlets -and concepts. +To provide updated help for multiple computers in an enterprise and for +computers that do not have access to the Internet, Updatable Help lets you +download help files to a file system directory or file share, and then install +the help files from the file share. -The Updatable Help system, introduced in Windows PowerShell 3.0, -is designed to assure that you always have the newest help topics -on your local computer so that you can read them at the command -line. It makes it easy to download and install help files and -to update them whenever newer help files become available. +In PowerShell 4.0, the HelpInfoUri property is preserved over Windows +PowerShell remoting, which allows Save-Help to work for modules that are +installed on a remote computer, but are not necessarily installed on the local +computer. You can save a PSModuleInfo object to disk or removable media (such +as a USB drive) by running Export-Clixml on a computer that does not have +Internet access, importing the PSModuleInfo object on a computer that does +have Internet access, and then running Save-Help on the PSModuleInfo object. +The saved help can be copied to the remote, disconnected computer by using +removable media, and then installed by running Update-Help. These improvements +in Save-Help functionality let you install help on computers that are without +any kind of network access. For an example of how to use the new Save-Help +functionality, see "HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP" in this +topic. -To provide updated help for multiple computers in an enterprise -and for computers that do not have access to the Internet, Updatable -Help lets you download help files to a file system directory or file -share, and then install the help files from the file share. +Updatable Help also supports online access to the newest help topics and basic +help for cmdlets, even when there are no help files on the computer. -In Windows PowerShell 4.0, the HelpInfoUri property is preserved over -Windows PowerShell remoting, which allows Save-Help to work for -modules that are installed on a remote computer, but are not -necessarily installed on the local computer. You can save a PSModuleInfo -object to disk or removable media (such as a USB drive) by running -Export-Clixml on a computer that does not have Internet access, -importing the PSModuleInfo object on a computer that does have Internet -access, and then running Save-Help on the PSModuleInfo object. The -saved help can be copied to the remote, disconnected computer by using -removable media, and then installed by running Update-Help. These -improvements in Save-Help functionality let you install help on -computers that are without any kind of network access. For an example -of how to use the new Save-Help functionality, see "HOW TO UPDATE HELP -FROM A FILE SHARE: SAVE-HELP" in this topic. +PowerShell 3.0 does not come with Help files. You can use the Updatable Help +feature to install the help files for all of the commands that are included by +default in PowerShell and for all Windows modules. -Updatable Help also supports online access to the newest help topics -and basic help for cmdlets, even when there are no help files on the -computer. - -Windows PowerShell 3.0 does not come with Help files. You can use -the Updatable Help feature to install the help files for all of the -commands that are included by default in Windows PowerShell and for -all Windows modules. - -# UPDATABLE HELP CMDLETS - - -Update-Help: Downloads the newest help files from the Internet or -a file share, and installs them on the local computer. - -Save-Help: Downloads the newest help files from the Internet and -saves them in a file system directory or file share. To -install the help files on computers, use Update-Help. +## UPDATABLE HELP CMDLETS -Get-Help: -- Displays help topics at the command line. --- Gets help from the help files on the computer. --- Displays auto-generated help for cmdlets and functions -that do not have help files. --- Opens online help topics for cmdlets, functions, -scripts, and workflows in your default Internet -browser. +- Update-Help: Downloads the newest help files from the Internet or a file + share, and installs them on the local computer. -# UPDATE HELP IN WINDOWS POWERSHELL ISE +- Save-Help: Downloads the newest help files from the Internet and saves them in + a file system directory or file share. To install the help files on computers, + use Update-Help. -You can also update help by using the "Update Windows PowerShell -Help" item in the Help menu in Windows PowerShell Integrated -Scripting Environment (ISE). +- Get-Help: Displays help topics at the command line. Gets help from the + help files on the computer. Displays auto-generated help for cmdlets and + functions that do not have help files. Opens online help topics for + cmdlets, functions, scripts, and workflows in your default Internet browser. -The "Update Windows PowerShell Help" item runs an Update-Help -command without parameters. +## UPDATE HELP IN PowerShell ISE -# AUTO-GENERATED HELP: HELP WITHOUT HELP FILES +You can also update help by using the "Update PowerShell Help" item in the +Help menu in PowerShell Integrated Scripting Environment (ISE). +The "Update PowerShell Help" item runs an Update-Help command without +parameters. -If you do not have the help file for a cmdlet, function, -or workflow on the computer, the Get-Help cmdlet displays -auto-generated help and prompts you to download the help -files or read them online. +## AUTO-GENERATED HELP: HELP WITHOUT HELP FILES -Auto-generated help includes syntax and aliases, and remarks -that explain how to use the Updatable Help cmdlets and to -access the online help topics. +If you do not have the help file for a cmdlet, function, or workflow on the +computer, the Get-Help cmdlet displays auto-generated help and prompts you to +download the help files or read them online. -For example, the following command gets basic help for the -Get-Culture cmdlet. The output shows the Get-Help display -when there are no help files on the computer. +Auto-generated help includes syntax and aliases, and remarks that explain how +to use the Updatable Help cmdlets and to access the online help topics. -PS C:> Get-Help Get-Culture - -# NAME - -Get-Culture - -# SYNTAX +For example, the following command gets basic help for the Get-Culture cmdlet. +The output shows the Get-Help display when there are no help files on the +computer. -Get-Culture [] +```powershell +Get-Help Get-Culture +``` -# ALIASES +```output +NAME + Get-Culture -None +SYNTAX + Get-Culture [] -# REMARKS +ALIASES + None -To get the latest Help content including descriptions -and examples type: Update-Help. +REMARKS + To get the latest Help content including descriptions and examples + type: Update-Help. +``` -# HELP FILES FOR MODULES +## HELP FILES FOR MODULES +The smallest unit of Updatable Help is help for a module. Module help includes +help for all of the cmdlets, functions, workflows, providers, scripts, and +concepts in a module. You can update help for all modules that are installed +on the computer, even if they are not imported into the current session. -The smallest unit of Updatable Help is help for a module. Module -help includes help for all of the cmdlets, functions, workflows, -providers, scripts, and concepts in a module. You can update help -for all modules that are installed on the computer, even if they -are not imported into the current session. +You can update help for the entire module, but you cannot update help for +individual cmdlets. -You can update help for the entire module, but you cannot update -help for individual cmdlets. - -To find the module that contains a particular cmdlet, use the -following command format: +To find the module that contains a particular cmdlet, use the following +command format: +```powershell (Get-Command ).ModuleName +``` For example, to find the module that contains the Set-ExecutionPolicy cmdlet, type: +```powershell (Get-Command Set-ExecutionPolicy).ModuleName +``` To update help for a particular module, type: +```powershell Update-Help -Module +``` For example, to update help for the module that contains the Set-ExecutionPolicy cmdlet, type: +```powershell Update-Help -Module Microsoft.PowerShell.Security +``` -# PERMISSIONS FOR UPDATABLE HELP - - -To update help for the modules in the $pshome\Modules directory, -you must be member of the Administrators group on the computer. +## PERMISSIONS FOR UPDATABLE HELP -If you are not a member of the Administrators group, you cannot -update help for these modules; but if you have Internet access, -you can view help online in the TechNet Library. +To update help for the modules in the \$pshome\\Modules directory, you must be +member of the Administrators group on the computer. -Updating help for modules in the -$home\Documents\WindowsPowerShell\Modules -directory or modules in other subdirectories of the $home -directory do not require special permissions. +If you are not a member of the Administrators group, you cannot update help +for these modules; but if you have Internet access, you can view help online +in the TechNet Library. -The Update-Help and Save-Help cmdlets have a UseDefaultCredentials -parameter that provides the explicit credentials of the current -user. This parameter is designed for accessing secure Internet -locations. +Updating help for modules in the \$home\\Documents\\WindowsPowerShell\\Modules +directory or modules in other subdirectories of the \$home directory do not +require special permissions. -The Update-Help and Save-Help cmdlets also have a Credential -parameter that allows you to run the command on a remote -computer and access a file share on a third computer. The -Credential parameter is valid only when you use the SourcePath -or LiteralPath parameters of Update-Help and the DestinationPath -or LiteralPath parameters of Save-Help. +The Update-Help and Save-Help cmdlets have a UseDefaultCredentials parameter +that provides the explicit credentials of the current user. This parameter is +designed for accessing secure Internet locations. -# HOW TO INSTALL AND UPDATE HELP FILES +The Update-Help and Save-Help cmdlets also have a Credential parameter that +allows you to run the command on a remote computer and access a file share on +a third computer. The Credential parameter is valid only when you use the +SourcePath or LiteralPath parameters of Update-Help and the DestinationPath or +LiteralPath parameters of Save-Help. +## HOW TO INSTALL AND UPDATE HELP FILES -To download and install help files for the first time, or to update -the help files on your computer, use the Update-Help cmdlet. +To download and install help files for the first time, or to update the help +files on your computer, use the Update-Help cmdlet. -The Update-Help cmdlet does all of the hard work for you, including -the following tasks. +The Update-Help cmdlet does all of the hard work for you, including the +following tasks. --- Determines which modules support Updatable Help. --- Finds the Internet location where each module stores its -Updatable Help files. --- Compares the help files for each module on your computer to -the newest help files that are available for each module. --- Downloads the new files from the Internet. --- Unwraps the help file package. --- Verifies that the files are valid help files. --- Installs the help files in the language-specific subdirectory -of the module directory. +- Determines which modules support Updatable Help. +- Finds the Internet location where each module stores its Updatable Help files. +- Compares the help files for each module on your computer to the newest help + files that are available for each module. +- Downloads the new files from the Internet. +- Unwraps the help file package. +- Verifies that the files are valid help files. +- Installs the help files in the language-specific subdirectory of the module + directory. -To access the new help topics, use the Get-Help cmdlet. You do not -need to restart Windows PowerShell. +To access the new help topics, use the Get-Help cmdlet. You do not need to +restart PowerShell. -To install or update help for all modules on the computer that -supports Updatable Help, type: +To install or update help for all modules on the computer that supports +Updatable Help, type: +```powershell Update-Help +``` -To update help for particular modules, add the Module parameter -of Update-Help. Wildcard characters are permitted in the module name. +To update help for particular modules, add the Module parameter of +Update-Help. Wildcard characters are permitted in the module name. For example, to update help for the ServerManager module, type: +```powershell Update-Help -Module ServerManager - -# NOTES - -Without parameters, Update-Help updates help for all modules -in the session and for all installed modules that support -Updatable Help. To be included, modules must be installed in -directories that are listed in the value of the PSModulePath -environment variable. These are also modules that -are returned by a "Get-Help -ListAvailable" command. - -If the value of the Module parameter is * (all), Update-Help -attempts to update help for all installed modules, including -modules that do not support Updatable Help. This command -typically generates many errors as the cmdlet encounters modules -that do not support Updatable Help. - -# HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP - - -To support computers that are not connected to the Internet, -or to control or streamline help updating in an enterprise, -use the Save-Help cmdlet. The Save-Help cmdlet downloads help -files from the Internet and saves them in a file system directory -that you specify. - -Save-Help compares the help files in the specified directory to -the newest help files that are available for each module. If the -directory has no help files or newer help files are available for -the module, the Save-Help cmdlet downloads the new files from the -Internet. However, it does not unwrap or install the help files. - -To install or update the help files on a computer from help -files that were saved to a file system directory, use the -SourcePath parameter of the Update-Help cmdlet. The Update-Help -cmdlet identifies the newest help files, unwraps and validates them, -and installs them in the language-specific subdirectories of the -module directories. - -For example, to save help for all installed modules to the -\Server\Share directory, type: - -Save-Help -DestinationPath \Server\Share - -Then, to update help from the \Server\Share directory, type: - -Update-Help -SourcePath \Server\Share - -The following examples show the use of Save-Help to save help -for modules that are not installed on the local computer. In -this example, the administrator runs Save-Help to save the help -for the DhcpServer module from an Internet-connected client computer, -without installing the DhcpServer module or DHCP Server role on the -local computer. - -Option 1: Run Invoke-Command to get the PSModuleInfo object for -the remote module, save it in a variable, $m, and then run Save-Help -on the PSModuleInfo object by specifying the variable $m as the -module name. - +``` + +Without parameters, Update-Help updates help for all modules in the session +and for all installed modules that support Updatable Help. To be included, +modules must be installed in directories that are listed in the value of the +PSModulePath environment variable. These are also modules that are returned by +a "Get-Help -ListAvailable" command. + +If the value of the Module parameter is * (all), Update-Help attempts to +update help for all installed modules, including modules that do not support +Updatable Help. This command typically generates many errors as the cmdlet +encounters modules that do not support Updatable Help. + +## HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP + +To support computers that are not connected to the Internet, or to control or +streamline help updating in an enterprise, use the Save-Help cmdlet. The +Save-Help cmdlet downloads help files from the Internet and saves them in a +file system directory that you specify. + +Save-Help compares the help files in the specified directory to the newest +help files that are available for each module. If the directory has no help +files or newer help files are available for the module, the Save-Help cmdlet +downloads the new files from the Internet. However, it does not unwrap or +install the help files. + +To install or update the help files on a computer from help files that were +saved to a file system directory, use the SourcePath parameter of the +Update-Help cmdlet. The Update-Help cmdlet identifies the newest help files, +unwraps and validates them, and installs them in the language-specific +subdirectories of the module directories. + +For example, to save help for all installed modules to the \\\\Server\\Share +directory, type: + +```powershell +Save-Help -DestinationPath \\Server\Share +``` + +Then, to update help from the \\\\Server\\Share directory, type: + +```powershell +Update-Help -SourcePath \\Server\Share +``` + +The following examples show the use of Save-Help to save help for modules that +are not installed on the local computer. In this example, the administrator +runs Save-Help to save the help for the DhcpServer module from an +Internet-connected client computer, without installing the DhcpServer module +or DHCP Server role on the local computer. + +Option 1: Run Invoke-Command to get the PSModuleInfo object for the remote +module, save it in a variable, $m, and then run Save-Help on the PSModuleInfo +object by specifying the variable $m as the module name. + +```powershell $m = Invoke-Command -ComputerName RemoteServer -ScriptBlock { Get-Module -Name DhcpServer -ListAvailable } Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -Option 2: Open a PSSession, targeted at the computer that is -running the DHCP Server module, to get the PSModuleInfo object for -the module, save it in a variable $m, and then run Save-Help on the -object that is saved in the $m variable. +Option 2: Open a PSSession, targeted at the computer that is running the DHCP +Server module, to get the PSModuleInfo object for the module, save it in a +variable $m, and then run Save-Help on the object that is saved in the $m +variable. +```powershell $s = New-PSSession -ComputerName RemoteServer $m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -Option 3: Open a CIM session, targeted at the computer that is -running the DHCP Server module, to get the PSModuleInfo object for -the module, save it in a variable $m, and then run Save-Help on the -object that is saved in the $m variable. +Option 3: Open a CIM session, targeted at the computer that is running the +DHCP Server module, to get the PSModuleInfo object for the module, save it in +a variable $m, and then run Save-Help on the object that is saved in the $m +variable. +```powershell $c = New-CimSession -ComputerName RemoteServer $m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -In the following example, the administrator installs help for the -DHCP Server module on a computer that does not have network access. +In the following example, the administrator installs help for the DHCP Server +module on a computer that does not have network access. -First, run Export-Clixml to export the PSModuleInfo object to -a shared folder or to removable media. +First, run Export-Clixml to export the PSModuleInfo object to a shared folder +or to removable media. +```powershell $m = Get-Module -Name DhcpServer -ListAvailable Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m +``` -Next, transport the removable media to a computer that has -Internet access, and then import the PSModuleInfo object with -Import-Clixml. Run Save-Help to save the Help for the imported -DhcpServer module PSModuleInfo object. +Next, transport the removable media to a computer that has Internet access, +and then import the PSModuleInfo object with Import-Clixml. Run Save-Help to +save the Help for the imported DhcpServer module PSModuleInfo object. +```powershell $deserialized_m = Import-Clixml E:\UsbFlashDrive\DhcpModule.xml -Save-Help -Module $deserialized_m -DestinationPath -E:\UsbFlashDrive\SavedHelp - -Finally, transport the removable media back to the computer that -does not have network access, and then install the help by running -Update-Help. - -Update-Help -Module DhcpServer -SourcePath +Save-Help -Module $deserialized_m -DestinationPath ` E:\UsbFlashDrive\SavedHelp +``` -# NOTES: +Finally, transport the removable media back to the computer that does not have +network access, and then install the help by running Update-Help. -Without parameters, Save-Help downloads help for all modules -in the session and for all installed modules that support -Updatable Help. To be included, modules must be installed in -directories that are listed in the value of the PSModulePath -environment variable, on either the local computer or on a remote -computer for which you want to save help. These are also modules -that are returned by running a "Get-Help -ListAvailable" command. +```powershell +Update-Help -Module DhcpServer -SourcePath E:\UsbFlashDrive\SavedHelp +``` -# HOW TO UPDATE HELP FILES IN DIFFERENT LANGUAGES +Without parameters, Save-Help downloads help for all modules in the session +and for all installed modules that support Updatable Help. To be included, +modules must be installed in directories that are listed in the value of the +PSModulePath environment variable, on either the local computer or on a remote +computer for which you want to save help. These are also modules that are +returned by running a "Get-Help -ListAvailable" command. +## HOW TO UPDATE HELP FILES IN DIFFERENT LANGUAGES -By default, the Update-Help and Save-Help cmdlets download -help in the UI culture and language that is set for Windows -on the local computer. If help files for the specified modules -are not available in the local UI culture, Update-Help and -Save-Help use the Windows language fallback rules to find the +By default, the Update-Help and Save-Help cmdlets download help in the UI +culture and language that is set for Windows on the local computer. If help +files for the specified modules are not available in the local UI culture, +Update-Help and Save-Help use the Windows language fallback rules to find the best supported language. -However, you can use the UICulture parameters of the Update-Help -and Save-Help cmdlets to download and install help files in any -UI cultures in which they are available. +However, you can use the UICulture parameters of the Update-Help and Save-Help +cmdlets to download and install help files in any UI cultures in which they +are available. -For example, to save the newest help files for all modules on -the session in Japanese (Ja-jp) and French (fr-FR), type: +For example, to save the newest help files for all modules on the session in +Japanese (Ja-jp) and French (fr-FR), type: +```powershell Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr +``` -If help files for the modules are not available in the languages -that you specified, the Update-Help and Save-Help cmdlets return -an error message that lists the languages in which help for each -module is available so you can choose the alternative that best -meets your needs. +If help files for the modules are not available in the languages that you +specified, the Update-Help and Save-Help cmdlets return an error message that +lists the languages in which help for each module is available so you can +choose the alternative that best meets your needs. -# HOW TO UPDATE HELP AUTOMATICALLY +## HOW TO UPDATE HELP AUTOMATICALLY +To assure that you always have the newest help files, you can add an +Update-Help command to your PowerShell profile. -To assure that you always have the newest help files, you can -add an Update-Help command to your Windows PowerShell profile. +An internal quota prevents the Update-Help command from running more than once +each day. To override the once-per-day maximum, use the Force parameter. -An internal quota prevents the Update-Help command from running -more than once each day. To override the once-per-day maximum, -use the Force parameter. - -Use a command like the following one in your profile. This command -updates help for all installed modules in a background job so it -doesn't disturb your work. It uses an Out-Null command to suppress -the job that is returned and any error messages that would otherwise -appear when you use the command more than once per day. +Use a command like the following one in your profile. This command updates +help for all installed modules in a background job so it doesn't disturb your +work. It uses an Out-Null command to suppress the job that is returned and any +error messages that would otherwise appear when you use the command more than +once per day. +```powershell Start-Job {Update-Help} | Out-Null +``` -You can also create a scheduled job that runs the Update-Help or -Save-Help cmdlet at any interval. +You can also create a scheduled job that runs the Update-Help or Save-Help +cmdlet at any interval. For example, the following command creates a scheduled job that runs an -Update-Help help command every Friday at 5:00 AM. To run this command, -start Windows PowerShell with the "Run as administrator" option. +Update-Help help command every Friday at 5:00 AM. To run this command, start +PowerShell with the "Run as administrator" option. +```powershell Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} ` -Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM") +``` -For more information about scheduled jobs, see about_Scheduled_Jobs. - -# HOW TO USE ONLINE HELP - +## HOW TO USE ONLINE HELP -If you cannot or choose not to update the help files on your -local computer, you can still get the newest help files online. +If you cannot or choose not to update the help files on your local computer, +you can still get the newest help files online. -To open the online help topic for any cmdlet or function, use -the Online parameter of the Get-Help cmdlet. +To open the online help topic for any cmdlet or function, use the Online +parameter of the Get-Help cmdlet. -For example, the following command opens the online help topic -for the Get-Job cmdlet in your default Internet browser: +For example, the following command opens the online help topic for the Get-Job +cmdlet in your default Internet browser: +```powershell Get-Help Get-Job -Online --or- -Get-Help -on Get-Job - -To get online help for a script, use the Online parameter and -the full path to the script. - -The Online parameter does not work with About topics. To see -the about topics for Windows PowerShell Core, including help -topics about the Windows PowerShell language, see "Windows -PowerShell Core Module About Topics" at -http://go.microsoft.com/fwlink/?LinkID=113206. - -# HOW TO MINIMIZE OR PREVENT INTERNET DOWNLOADS - -To minimize Internet downloads and provide Updatable Help to -users who are not connected to the Internet, use the Save-Help -cmdlet. Download help from the Internet and save it to a network -share. Then, create a Group Policy setting or scheduled job that -runs an Update-Help command on all computers. Set the value of -the SourcePath parameter of the Update-Help cmdlet to the network -share. - -To prevent users who have Internet access from downloading Updatable -Help from the Internet, use the "Set the default source path for -Update-Help" Group Policy setting. +``` -This Group Policy setting implicitly adds the SourcePath parameter, -with the file system location that you specify, to every Update-Help -command on every affected computer. Users can use the SourcePath -parameter explicitly to specify a different file system location, but -they cannot exclude the SourcePath parameter and download help from -the Internet. +To get online help for a script, use the Online parameter and the full path to +the script. -NOTE: The "Set the default source path for Update-Help" group -policy setting appears under Computer Configuration and -User Configuration. However, only the policy setting -under Computer Configuration is effective. The policy -setting under User Configuration is ignored. +The Online parameter does not work with About topics. To see the about topics +for PowerShell Core, including help topics about the PowerShell language, see +[Windows PowerShell Core Module About Topics](http://go.microsoft.com/fwlink/?LinkID=113206). -For more information, see about_Group_Policy_Settings. +## HOW TO MINIMIZE OR PREVENT INTERNET DOWNLOADS -# HOW TO UPDATE HELP FOR NON-STANDARD MODULES +To minimize Internet downloads and provide Updatable Help to users who are not +connected to the Internet, use the Save-Help cmdlet. Download help from the +Internet and save it to a network share. Then, create a Group Policy setting +or scheduled job that runs an Update-Help command on all computers. Set the +value of the SourcePath parameter of the Update-Help cmdlet to the network +share. -To update or save help for a module that is not returned -by the ListAvailable parameter of the Get-Module cmdlet, -import the module into the current session before running -an Update-Help or Save-Help command. On a remote computer, -before running the Save-Help command, import the module into -the current CIM or PSSession--or Invoke-Command script block-- -that is connected to the remote computer. +To prevent users who have Internet access from downloading Updatable Help from +the Internet, use the "Set the default source path for Update-Help" Group +Policy setting. -When the module is in the current session, run the Update-Help -or Save-Help cmdlets without parameters, or use the Module -parameter to specify the module name. +This Group Policy setting implicitly adds the SourcePath parameter, with the +file system location that you specify, to every Update-Help command on every +affected computer. Users can use the SourcePath parameter explicitly to +specify a different file system location, but they cannot exclude the +SourcePath parameter and download help from the Internet. -The Module parameters of the Update-Help and Save-Help -cmdlets accept only a module name. They do not accept the -path to a module file. +NOTE: The "Set the default source path for Update-Help" group policy setting +appears under Computer Configuration and User Configuration. However, only the +policy setting under Computer Configuration is effective. The policy setting +under User Configuration is ignored. -Use this technique to update or save help for any module -that is not returned by the ListAvailable parameter of the -Get-Module cmdlet, such as a module that is installed in a -location that is not listed in the PSModulePath environment -variable, or a module that is not well-formed (the module -directory does not contain at least one file whose base name -is the same as the directory name). +For more information, see [about_Group_Policy_Settings](about_Group_Policy_Settings.md). -# HOW TO SUPPORT UPDATABLE HELP +## HOW TO UPDATE HELP FOR NON-STANDARD MODULES +To update or save help for a module that is not returned by the ListAvailable +parameter of the Get-Module cmdlet, import the module into the current session +before running an Update-Help or Save-Help command. On a remote computer, +before running the Save-Help command, import the module into the current CIM +or PSSession--or Invoke-Command script block-- that is connected to the remote +computer. -If you author a module, you can support online help and -Updatable Help for your modules. For more information, see -"Supporting Updatable Help" and "Supporting Online Help" -in the MSDN Library. +When the module is in the current session, run the Update-Help or Save-Help +cmdlets without parameters, or use the Module parameter to specify the module +name. -Updatable help not available for Windows PowerShell snap-ins -or comment-based help. +The Module parameters of the Update-Help and Save-Help cmdlets accept only a +module name. They do not accept the path to a module file. -# KEYWORDS +Use this technique to update or save help for any module that is not returned +by the ListAvailable parameter of the Get-Module cmdlet, such as a module that +is installed in a location that is not listed in the PSModulePath environment +variable, or a module that is not well-formed (the module directory does not +contain at least one file whose base name is the same as the directory name). -About_Updateable_Help +## HOW TO SUPPORT UPDATABLE HELP -# REMARKS +If you author a module, you can support online help and Updatable Help for +your modules. For more information, see "Supporting Updatable Help" and +"Supporting Online Help" in the MSDN Library. -The Update-Help and Save-Help cmdlets are not supported on -Windows Preinstallation Environment (Windows PE). +Updatable help not available for PowerShell snap-ins or comment-based help. -# SEE ALSO +# REMARKS -Get-Help +The Update-Help and Save-Help cmdlets are not supported on Windows +Preinstallation Environment (Windows PE). -Save-Help +## SEE ALSO -Update-Help +[Get-Help](../Get-Help.md) -Updatable Help Status Table (http://go.microsoft.com/fwlink/?LinkID=270007) +[Save-Help](../Save-Help.md) +[Update-Help](../Update-Help.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI.md index fe279908cfc3..bafb6c425a08 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_WMI.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,84 +7,104 @@ title: about_WMI --- # About WMI -## about_WMI - ## SHORT DESCRIPTION -Windows Management Instrumentation (WMI) uses the Common Information Model (CIM) to represent systems, applications, networks, devices, and other manageable components of the modern enterprise. +Windows Management Instrumentation (WMI) uses the Common Information Model +(CIM) to represent systems, applications, networks, devices, and other +manageable components of the modern enterprise. ## LONG DESCRIPTION -Windows Management Instrumentation (WMI) is Microsoft’s implementation of Web-Based Enterprise Management (WBEM), the industry standard. -Classic WMI uses DCOM to communicate with networked devices to manage remote systems. Windows PowerShell® 3.0 introduces a CIM provider model that uses WinRM to remove the dependency on DCOM. This CIM provider model also uses new WMI provider APIs that enable developers to write Windows PowerShell cmdlets in native code (C\+\+). +Windows Management Instrumentation (WMI) is Microsoft’s implementation of +Web-Based Enterprise Management (WBEM), the industry standard. -Do not confuse WMI providers with Windows PowerShell providers. Many Windows features have an associated WMI provider that exposes their management capabilities. To get WMI providers, run a WMI query that gets instances of the __Provider WMI class, such as the following query. +Classic WMI uses DCOM to communicate with networked devices to manage remote +systems. Windows PowerShell® 3.0 introduces a CIM provider model that uses +WinRM to remove the dependency on DCOM. This CIM provider model also uses new +WMI provider APIs that enable developers to write Windows PowerShell cmdlets +in native code (C\+\+). +Do not confuse WMI providers with Windows PowerShell providers. Many Windows +features have an associated WMI provider that exposes their management +capabilities. To get WMI providers, run a WMI query that gets instances of the +__Provider WMI class, such as the following query. -``` +```powershell Get-WmiObject -Class __Provider ``` - - ## THREE COMPONENTS OF WMI -The following three components of WMI interact with Windows PowerShell: Namespaces, Providers, and Classes. -WMI Namespaces organize WMI providers and WMI classes into groups of related components. In this way, they are similar to .NET Framework namespaces. Namespaces are not physical locations, but are more like logical databases. All WMI namespaces are instances of the __Namespace system class. The default WMI namespace is Root\/CIMV2 (since Microsoft Windows 2000). To use Windows PowerShell to get WMI namespaces in the current session, use a command with the following format. +The following three components of WMI interact with Windows PowerShell: +Namespaces, Providers, and Classes. +WMI Namespaces organize WMI providers and WMI classes into groups of related +components. In this way, they are similar to .NET Framework namespaces. +Namespaces are not physical locations, but are more like logical databases. +All WMI namespaces are instances of the __Namespace system class. The default +WMI namespace is Root\/CIMV2 (since Microsoft Windows 2000). To use Windows +PowerShell to get WMI namespaces in the current session, use a command with +the following format. -``` +```powershell Get-WmiObject -Class __Namespace ``` +To get WMI namespaces in other namespaces, use the Namespace parameter to +change the location of the search. The following command finds WMI namespaces +that reside in the Root/Cimv2/Applications namespace. -To get WMI namespaces in other namespaces, use the Namespace parameter to change the location of the search. The following command finds WMI namespaces that reside in the Root\/Cimv2\/Applications namespace. - - -``` -Get-WmiObject -Class __Namespace -Namespace -root/CIMv2/applications +```powershell +Get-WmiObject -Class __Namespace -Namespace root/CIMv2/applications ``` +WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces +on a particular system requires performing a recursive query starting at the +root namespace. -WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces on a particular system requires performing a recursive query starting at the root namespace. - -WMI Providers expose information about Windows manageable objects. A provider retrieves data from a component, and passes that data through WMI to a management application, such as Windows PowerShell. Most WMI providers are dynamic providers, which means that they obtain the data dynamically when it is requested through the management application. - +WMI Providers expose information about Windows manageable objects. A provider +retrieves data from a component, and passes that data through WMI to a +management application, such as Windows PowerShell. Most WMI providers are +dynamic providers, which means that they obtain the data dynamically when it +is requested through the management application. ## FINDING WMI CLASSES -In a default installation of Windows 8, there are more than 1,100 WMI classes in Root\/Cimv2. With this many WMI classes, the challenge becomes identifying the appropriate WMI class to use to perform a specific task. Windows PowerShell 3.0 provides two ways to find WMI classes that are related to a specific topic. -For example,to find WMI classes in the root\CIMV2 WMI namespace that are related to disks, you can use a query such as the one shown here. +In a default installation of Windows 8, there are more than 1,100 WMI classes +in Root\/Cimv2. With this many WMI classes, the challenge becomes identifying +the appropriate WMI class to use to perform a specific task. Windows +PowerShell 3.0 provides two ways to find WMI classes that are related to a +specific topic. +For example,to find WMI classes in the root\\CIMV2 WMI namespace that are +related to disks, you can use a query such as the one shown here. -``` +```powershell Get-WmiObject -List *disk* ``` +To find WMI classes that are related to memory, you might use a query such as +the one shown here. -To find WMI classes that are related to memory, you might use a query such as the one shown here. - - -``` +```powershell Get-WmiObject -List *memory* ``` +The CIM cmdlets also provide the ability to discover WMI classes. To do this, +use the Get-CIMClass cmdlet. The command shown here lists WMI classes related +to video. -The CIM cmdlets also provide the ability to discover WMI classes. To do this, use the Get-CIMClass cmdlet. The command shown here lists WMI classes related to video. - - -``` +```powershell Get-CimClass *video* ``` +Tab expansion works when changing WMI namespaces, and therefore use of tab +expansion makes sub-WMI namespaces easily discoverable. In the following +example, the Get-CimClass cmdlet lists WMI classes related to power settings. +To find it, type the `root/CIMV2/` namespace and then press the Tab key +several times until the power namespace appears. Here is the command: -Tab expansion works when changing WMI namespaces, and therefore use of tab expansion makes sub-WMI namespaces easily discoverable. In the following example, the Get-CimClass cmdlet lists WMI classes related to power settings. To find it, type the root\/CIMV2\/ WMI namespace, and then press type the root\/CIMV2\/ WMI namespace, and then press the Tab key several times until the power namespace appears. Here is the command: - - -``` +```powershell Get-CimClass *power* -Namespace root/cimv2/power ``` - - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_WQL.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_WQL.md index 4413e4b4bf38..5835819c2aeb 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_WQL.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_WQL.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,384 +7,356 @@ title: about_WQL --- # About WQL -## about_WQL +## SHORT DESCRIPTION +Describes WMI Query Language (WQL), which can be used to get WMI objects in +Windows PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes WMI Query Language (WQL), which can be -used to get WMI objects in Windows PowerShell. +WQL is the Windows Management Instrumentation (WMI) query language, which is +the language used to get information from WMI. -# LONG DESCRIPTION +You are not required to use WQL to perform a WMI query in Windows PowerShell. +Instead, you can use the parameters of the Get-WmiObject or Get-CimInstance +cmdlets. WQL queries are somewhat faster than standard Get-WmiObject commands +and the improved performance is evident when the commands run on hundreds of +systems. However, be sure that the time you spend to write a successful WQL +query doesn't outweigh the performance improvement. -WQL is the Windows Management Instrumentation (WMI) -query language, which is the language used to get -information from WMI. +The basic WQL statements you need to use WQL are Select, Where, and From. -You are not required to use WQL to perform a WMI -query in Windows PowerShell. Instead, you can -use the parameters of the Get-WmiObject or -Get-CimInstance cmdlets. WQL queries are somewhat -faster than standard Get-WmiObject commands and -the improved performance is evident when the commands -run on hundreds of systems. However, be sure that -the time you spend to write a successful WQL query -doesn't outweigh the performance improvement. +## WHEN TO USE WQL -The basic WQL statements you need to use WQL are -Select, Where, and From. +When working with WMI, and especially with WQL, do not forget that you are +also using Windows PowerShell. Often, if a WQL query does not work as +expected, it's easier to use a standard Windows PowerShell command than to +debug the WQL query. -# WHEN TO USE WQL - - -When working with WMI, and especially with WQL, -do not forget that you are also using Windows -PowerShell. Often, if a WQL query does not work as -expected, it's easier to use a standard Windows -PowerShell command than to debug the WQL query. - -Unless you are returning massive amounts of data -from across bandwidth-constrained remote systems, -it is rarely productive to spend hours trying to -perfect a complicated and convoluted WQL query -when there is a perfectly acceptable Windows -cmdlet that does the same thing, if a bit more +Unless you are returning massive amounts of data from across +bandwidth-constrained remote systems, it is rarely productive to spend hours +trying to perfect a complicated and convoluted WQL query when there is a +perfectly acceptable Windows cmdlet that does the same thing, if a bit more slowly. -# USING THE SELECT STATEMENT - +## USING THE SELECT STATEMENT -A typical WMI query begins with a Select statement -that gets all properties or particular properties -of a WMI class. To select all properties of a WMI -class, use an asterisk (*). The From keyword -specifies the WMI class. +A typical WMI query begins with a Select statement that gets all properties or +particular properties of a WMI class. To select all properties of a WMI class, +use an asterisk (*). The From keyword specifies the WMI class. A Select statement has the following format: +``` Select from +``` -For example, the following Select statement selects -all properties (*) from the instances of the Win32_Bios -WMI class. +For example, the following Select statement selects all properties (*) from +the instances of the Win32_Bios WMI class. +``` Select * from Win32_Bios +``` -To select a particular property of a WMI class, -place the property name between the Select and -From keywords. +To select a particular property of a WMI class, place the property name +between the Select and From keywords. -The following query selects only the name of -the BIOS from the Win32_Bios WMI class. The -command saves the query in the $queryName -variable. +The following query selects only the name of the BIOS from the Win32_Bios WMI +class. The command saves the query in the $queryName variable. +``` Select Name from Win32_Bios +``` -To select more than one property, use commas to -separate the property names. The following WMI -query selects the name and the version of the -Win32_Bios WMI class. The command saves the -query in the $queryNameVersion variable. +To select more than one property, use commas to separate the property names. +The following WMI query selects the name and the version of the Win32_Bios WMI +class. The command saves the query in the $queryNameVersion variable. +``` Select name, version from Win32_Bios +``` -# USING THE WQL QUERY +## USING THE WQL QUERY +There are three ways to use WQL query in Windows PowerShell command. -There are three ways to use WQL query in Windows -PowerShell command. +- Use the Get-WmiObject cmdlet +- Use the Get-CimInstance cmdlet +- Use the [wmisearcher] type accelerator. --- Use the Get-WmiObject cmdlet --- Use the Get-CimInstance cmdlet --- Use the [wmisearcher] type accelerator. +## USING THE GET-WMIOBJECT CMDLET -# USING THE GET-WMIOBJECT CMDLET +The most basic way to use the WQL query is to enclose it in quotation marks +(as a string) and then use the query string as the value of the Query +parameter of the Get-WmiObject cmdlet, as shown in the following example. -The most basic way to use the WQL query is to enclose -it in quotation marks (as a string) and then use the -query string as the value of the Query parameter of -the Get-WmiObject cmdlet, as shown in the following -example. - -PS C:> Get-WmiObject -Query "Select * from Win32_Bios" +```powershell +Get-WmiObject -Query "Select * from Win32_Bios" +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -You can also save the WQL statement in a variable -and then use the variable as the value of the Query -parameter, as shown in the following command. +You can also save the WQL statement in a variable and then use the variable as +the value of the Query parameter, as shown in the following command. -PS C:> $query = "Select * from Win32_Bios" -PS C:> Get-WmiObject -Query $query +```powershell +$query = "Select * from Win32_Bios" +Get-WmiObject -Query $query +``` -You can use either format with any WQL statement. -The following command uses the query in the -$queryName variable to get only the name and -version properties of the system BIOS. +You can use either format with any WQL statement. The following command uses +the query in the $queryName variable to get only the name and version +properties of the system BIOS. -PS C:> $queryNameVersion = "Select Name, Version from Win32_Bios" -PS C:> Get-WmiObject -Query $queryNameVersion - -# __GENUS : 2 +```powershell +$queryNameVersion = "Select Name, Version from Win32_Bios" +Get-WmiObject -Query $queryNameVersion +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS Version : LENOVO - 1360 +``` -Remember that you can use the parameters of the -Get-WmiObject cmdlet to get the same result. For -example, the following command also gets the values -of the Name and Version properties of instances of -the Win32_Bios WMI class. - -PS C:> Get-WmiObject -Class Win32_Bios -Property Name, Version +Remember that you can use the parameters of the Get-WmiObject cmdlet to get +the same result. For example, the following command also gets the values of +the Name and Version properties of instances of the Win32_Bios WMI class. -# __GENUS : 2 +```powershell +Get-WmiObject -Class Win32_Bios -Property Name, Version +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS Version : LENOVO - 1360 +``` -# USING THE GET-CIMINSTANCE CMDLET +## USING THE GET-CIMINSTANCE CMDLET +Beginning in Windows PowerShell 3.0, you can use the Get-CimInstance cmdlet to +run WQL queries. -Beginning in Windows PowerShell 3.0, you can use -the Get-CimInstance cmdlet to run WQL queries. +Get-CimInstance gets instances of CIM-compliant classes, including WMI +classes. The CIM cmdlets, introduced Windows PowerShell 3.0, perform the same +tasks as the WMI cmdlets. The CIM cmdlets comply with WS-Management (WSMan) +standards and with the Common Information Model (CIM) standard, which enables +the cmdlets to use the same techniques to manage Windows computers and +computers that are running other operating systems. -Get-CimInstance gets instances of CIM-compliant -classes, including WMI classes. The CIM cmdlets, -introduced Windows PowerShell 3.0, perform the same -tasks as the WMI cmdlets. The CIM cmdlets comply -with WS-Management (WSMan) standards and with the -Common Information Model (CIM) standard, which enables -the cmdlets to use the same techniques to manage -Windows computers and computers that are running -other operating systems. +The following command uses the Get-CimInstance cmdlet to run a WQL query. -The following command uses the Get-CimInstance -cmdlet to run a WQL query. +Any WQL query that can be used with Get-WmiObject can also be used with +Get-CimInstance. -Any WQL query that can be used with Get-WmiObject -can also be used with Get-CimInstance. - -PS C:> Get-CimInstance -Query "Select * from Win32_Bios" +```powershell +Get-CimInstance -Query "Select * from Win32_Bios" +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -Get-CimInstance returns a CimInstance object, instead of -the ManagementObject that Get-WmiObject returns, but -the objects are quite similar. +Get-CimInstance returns a CimInstance object, instead of the ManagementObject +that Get-WmiObject returns, but the objects are quite similar. -PS C:> (Get-CimInstance -Query "Select * from Win32_Bios").GetType().FullName +``` +(Get-CimInstance -Query "Select * from Win32_Bios").GetType().FullName Microsoft.Management.Infrastructure.CimInstance -PS C:> (Get-WmiObject -Query "Select * from Win32_Bios").GetType().FullName +(Get-WmiObject -Query "Select * from Win32_Bios").GetType().FullName System.Management.ManagementObject +``` -USING THE [wmisearcher] TYPE ACCELERATOR +## USING THE [wmisearcher] TYPE ACCELERATOR -The [wmisearcher] type accelerator creates a -ManagementObjectSearcher object from a WQL -statement string. The ManagementObjectSearcher -object has many properties and methods, but the -most basic method is the Get method, which -invokes the specified WMI query and returns -the resulting objects. +The [wmisearcher] type accelerator creates a ManagementObjectSearcher object +from a WQL statement string. The ManagementObjectSearcher object has many +properties and methods, but the most basic method is the Get method, which +invokes the specified WMI query and returns the resulting objects. -By using the [wmisearcher], you gain easy access -to the ManagementObjectSearcher .NET Framework class. -This lets you query WMI and to configure the way -the query is conducted. +By using the [wmisearcher], you gain easy access to the +ManagementObjectSearcher .NET Framework class. This lets you query WMI and to +configure the way the query is conducted. To use the [wmisearcher] type accelerator: -1. Cast the WQL string into a ManagementObjectSearcher -object. -2. Call the Get method of the ManagementObjectSearcher -object. +1. Cast the WQL string into a ManagementObjectSearcher object. +2. Call the Get method of the ManagementObjectSearcher object. -For example, the following command casts the "select -all" query, saves the result in the $bios variable, -and then calls the Get method of the ManagementObjectSearcher -object in the $bios variable. +For example, the following command casts the "select all" query, saves the +result in the $bios variable, and then calls the Get method of the +ManagementObjectSearcher object in the $bios variable. -PS C:> $bios = [wmisearcher]"Select * from Win32_Bios" -PS C:> $bios.Get() +```powershell +$bios = [wmisearcher]"Select * from Win32_Bios" +$bios.Get() +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -NOTE: Only selected object properties are displayed -by default. These properties are defined in the -Types.ps1xml file. +NOTE: Only selected object properties are displayed by default. These +properties are defined in the Types.ps1xml file. -You can use the [wmisearcher] type accelerator to -cast the query or the variable. In the following -example, the [wmisearcher] type accelerator is -used to cast the variable. The result is the same. +You can use the [wmisearcher] type accelerator to cast the query or the +variable. In the following example, the [wmisearcher] type accelerator is used +to cast the variable. The result is the same. -PS C:> [wmisearcher]$bios = "Select * from Win32_Bios" -PS C:> $bios.Get() +```powershell +[wmisearcher]$bios = "Select * from Win32_Bios" +$bios.Get() +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -When you use the [wmisearcher] type accelerator, it -changes the query string into a ManagementObjectSearcher -object, as shown in the following commands. +When you use the [wmisearcher] type accelerator, it changes the query string +into a ManagementObjectSearcher object, as shown in the following commands. -PS C:> $a = "Select * from Win32_Bios" -PS C:> $a.GetType().FullName +``` +$a = "Select * from Win32_Bios" +$a.GetType().FullName System.String -PS C:> $a = [wmisearcher]"Select * from Win32_Bios" -PS C:> $a.GetType().FullName +$a = [wmisearcher]"Select * from Win32_Bios" +$a.GetType().FullName System.Management.ManagementObjectSearcher +``` -This command format works on any query. The following -command gets the value of the Name property of the -Win32_Bios WMI class. - -PS C:> $biosname = [wmisearcher]"Select Name from Win32_Bios" -PS C:> $biosname.Get() +This command format works on any query. The following command gets the value +of the Name property of the Win32_Bios WMI class. -# __GENUS : 2 +```powershell +$biosname = [wmisearcher]"Select Name from Win32_Bios" +$biosname.Get() +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS +``` -You can perform this operation in a single command, -although the command is a bit more difficult to -interpret. +You can perform this operation in a single command, although the command is a +bit more difficult to interpret. -In this format, you use the [wmisearcher] type -accelerator to cast the WQL query string to a -ManagementObjectSearcher, and then call the Get -method on the object -- all in a single command. -The parentheses () that enclose the casted string -direct Windows PowerShell to cast the string before -calling the method. +In this format, you use the [wmisearcher] type accelerator to cast the WQL +query string to a ManagementObjectSearcher, and then call the Get method on +the object -- all in a single command. The parentheses () that enclose the +casted string direct Windows PowerShell to cast the string before calling the +method. -PS C:> ([wmisearcher]"Select name from Win32_Bios").Get() - -# __GENUS : 2 +```powershell +([wmisearcher]"Select name from Win32_Bios").Get() +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS +``` -# USING THE BASIC WQL WHERE STATEMENT - +## USING THE BASIC WQL WHERE STATEMENT -A Where statement establishes conditions -for the data that a Select statement returns. +A Where statement establishes conditions for the data that a Select statement +returns. The Where statement has the following format: +``` where +``` For example: +``` where Name = 'Notepad.exe' +``` -The Where statement is used with the Select -statement, as shown in the following example. +The Where statement is used with the Select statement, as shown in the +following example. +``` Select * from Win32_Process where Name = 'Notepad.exe' +``` -When using the Where statement, the property name -and value must be accurate. +When using the Where statement, the property name and value must be accurate. -For example, the following command gets the Notepad -processes on the local computer. +For example, the following command gets the Notepad processes on the local +computer. -PS C:> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad.exe'" +```powershell +Get-WmiObject -Query "Select * from Win32_Process where name='Notepad.exe'" +``` -However, the following command fails, because the -process name includes the ".exe" file name -extension. +However, the following command fails, because the process name includes the +".exe" file name extension. -PS C:> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad'" +```powershell +Get-WmiObject -Query "Select * from Win32_Process where name='Notepad'" +``` -# WHERE STATEMENT COMPARISON OPERATORS +## WHERE STATEMENT COMPARISON OPERATORS -The following operators are valid in a -WQL Where statement. +The following operators are valid in a WQL Where statement. +``` Operator Description ----------------------- = Equal @@ -398,334 +370,365 @@ LIKE Wildcard match IS Evaluates null ISNOT Evaluates not null ISA Evaluates a member of a WMI class +``` -There are other operators, but these are the ones -used for making comparisons. +There are other operators, but these are the ones used for making comparisons. -For example, the following query selects the Name -and Priority properties from processes in the -Win32_Process class where the process priority -is greater than or equal to 11. The Get-WmiObject -cmdlet runs the query. +For example, the following query selects the Name and Priority properties from +processes in the Win32_Process class where the process priority is greater +than or equal to 11. The Get-WmiObject cmdlet runs the query. -$highPriority = "Select Name, Priority from Win32_Process where Priority >= 11" +```powershell +$highPriority = "Select Name, Priority from Win32_Process " + + "where Priority >= 11" Get-WmiObject -Query $highPriority +``` -# USING THE WQL OPERATORS IN THE FILTER PARAMETER +## USING THE WQL OPERATORS IN THE FILTER PARAMETER +The WQL operators can also be used in the value of the Filter parameter of the +Get-WmiObject or Get-CimInstance cmdlets, as well as in the value of the Query +parameters of these cmdlets. -The WQL operators can also be used in the value -of the Filter parameter of the Get-WmiObject or -Get-CimInstance cmdlets, as well as in the value -of the Query parameters of these cmdlets. +For example, the following command gets the Name and ProcessID properties of +the last five processes that have ProcessID values greater than 1004. The +command uses the Filter parameter to specify the ProcessID condition. -For example, the following command gets the Name -and ProcessID properties of the last five processes -that have ProcessID values greater than 1004. The -command uses the Filter parameter to specify the -ProcessID condition. - -PS C:> Get-WmiObject -Class Win32_Process ` +```powershell +Get-WmiObject -Class Win32_Process ` -Property Name, ProcessID -Filter "ProcessID >= 1004" | Sort ProcessID | Select Name, ProcessID -Last 5 +``` +```output Name ProcessID ---- --------- SROSVC.exe 4220 -# WINWORD.EXE 4664 - +WINWORD.EXE 4664 TscHelp.exe 4744 SnagIt32.exe 4748 WmiPrvSE.exe 5056 +``` # USING THE LIKE OPERATOR -The Like operator lets you use wildcard characters -to filter the results of a WQL query. +The Like operator lets you use wildcard characters to filter the results of a +WQL query. +``` Like Operator Description -------------------------------------------------- [] Character in a range [a-f] or a set -of characters [abcdef]. The items in -a set do not need to be consecutive or -listed in alphabetical order. + of characters [abcdef]. The items in + a set do not need to be consecutive or + listed in alphabetical order. ^ Character not in a range [^a-f] or -not in a set [^abcdef]. The items in -a set do not need to be consecutive or -listed in alphabetical order. + not in a set [^abcdef]. The items in + a set do not need to be consecutive or + listed in alphabetical order. % A string of zero or more characters _ One character. -(underscore) NOTE: To use a literal underscore -in a query string, enclose it in -square brackets [_]. +(underscore) NOTE: To use a literal underscore + in a query string, enclose it in + square brackets [_]. +``` -When the Like operator is used without any wildcard -characters or range operators, it behaves like the -equality operator (=) and returns objects only +When the Like operator is used without any wildcard characters or range +operators, it behaves like the equality operator (=) and returns objects only when they are an exact match for the pattern. -You can combine the range operation with the percent -wildcard character to create simple, yet powerful -filters. +You can combine the range operation with the percent wildcard character to +create simple, yet powerful filters. -# LIKE OPERATOR EXAMPLES +### LIKE OPERATOR EXAMPLES +#### EXAMPLE 1: [] -EXAMPLE 1: [] -The following commands start Notepad and then -search for an instance of the Win32_Process -class that has a name that starts with a letter -between "H" and "N" (case-insensitive). +The following commands start Notepad and then search for an instance of the +Win32_Process class that has a name that starts with a letter between "H" and +"N" (case-insensitive). -The query should return any process from Hotpad.exe -through Notepad.exe. +The query should return any process from Hotpad.exe through Notepad.exe. -PS C:> Notepad # Starts Notepad -PS C:> $query = "Select * from win32_Process where Name LIKE '[H-N]otepad.exe'" -PS C:> Get-WmiObject -Query $query | Select Name, ProcessID +```powershell +Notepad # Starts Notepad +$query = "Select * from win32_Process where Name LIKE '[H-N]otepad.exe'" +Get-WmiObject -Query $query | Select Name, ProcessID +``` +```output Name ProcessID ---- --------- notepad.exe 1740 +``` + +#### EXAMPLE 2: [] and % -EXAMPLE 2: [] and % -The following commands select all process -that have a name that begins with a letter between -A and P (case-insensitive) followed by zero or more -letters in any combination. +The following commands select all process that have a name that begins with a +letter between A and P (case-insensitive) followed by zero or more letters in +any combination. -The Get-WmiObject cmdlet runs the query, the -Select-Object cmdlet gets the Name and ProcessID -properties, and the Sort-Object cmdlet sorts the -results in alphabetical order by name. +The Get-WmiObject cmdlet runs the query, the Select-Object cmdlet gets the +Name and ProcessID properties, and the Sort-Object cmdlet sorts the results in +alphabetical order by name. -PS C:> $query = "Select * from win32_Process where name LIKE '[A-P]%'" -PS C:> Get-WmiObject -Query $query | +```powershell +$query = "Select * from win32_Process where name LIKE '[A-P]%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID | Sort-Object -Property Name +``` -EXAMPLE 3: Not in Range (^) -The following command gets processes whose names -do not begin with any of the following letters: -# A, S, W, P, R, C, U, N +#### EXAMPLE 3: Not in Range (^) + +The following command gets processes whose names do not begin with any of the +following letters: A, S, W, P, R, C, U, N and followed zero or more letters. -PS C:> $query = "Select * from win32_Process where name LIKE '[^ASWPRCUN]%'" -PS C:> Get-WmiObject -Query $query | +```powershell +$query = "Select * from win32_Process where name LIKE '[^ASWPRCUN]%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID | Sort-Object -Property Name +``` + +#### EXAMPLE 4: Any characters -- or none (%) -EXAMPLE 4: Any characters -- or none (%) -The following commands get processes that have -names that begin with "calc". The % symbol in -WQL is equivalent to the asterisk (*) symbol in -regular expressions. +The following commands get processes that have names that begin with "calc". +The % symbol in WQL is equivalent to the asterisk (*) symbol in regular +expressions. -PS C:> $query = "Select * from win32_Process where Name LIKE 'calc%'" -PS C:> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +```powershell +$query = "Select * from win32_Process where Name LIKE 'calc%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +``` +```output Name ProcessID ---- --------- calc.exe 4424 +``` -EXAMPLE 5: One character (_) -The following commands get processes that -have names that have the following pattern, -"c_lc.exe" where the underscore character -represents any one character. This pattern -matches any name from calc.exe through -czlc.exe, or c9lc.exe, but does not match -names in which the "c" and "l" are separated -by more than one character. +#### EXAMPLE 5: One character (_) -PS C:> $query = "Select * from Win32_Process where Name LIKE 'c_lc.exe'" -PS C:> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +The following commands get processes that have names that have the following +pattern, "c_lc.exe" where the underscore character represents any one +character. This pattern matches any name from calc.exe through czlc.exe, or +c9lc.exe, but does not match names in which the "c" and "l" are separated by +more than one character. +```powershell +$query = "Select * from Win32_Process where Name LIKE 'c_lc.exe'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +``` + +```output Name ProcessID ---- --------- calc.exe 4424 +``` + +#### EXAMPLE 6: Exact match -EXAMPLE 6: Exact match -The following commands get processes named -WLIDSVC.exe. Even though the query uses the -Like keyword, it requires an exact match, -because the value does not include any -wildcard characters. +The following commands get processes named WLIDSVC.exe. Even though the query +uses the Like keyword, it requires an exact match, because the value does not +include any wildcard characters. +```powershell $query = "Select * from win32_Process where name LIKE 'WLIDSVC.exe'" Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +```powershell +```output Name ProcessID ---- --------- WLIDSVC.exe 84 +``` -# USING THE OR OPERATOR +## USING THE OR OPERATOR -To specify multiple independent conditions, use the Or -keyword. The Or keyword appears in the Where clause. It -performs an inclusive OR operation on two (or more) -conditions and returns items that meet any of the -conditions. +To specify multiple independent conditions, use the Or keyword. The Or keyword +appears in the Where clause. It performs an inclusive OR operation on two (or +more) conditions and returns items that meet any of the conditions. The Or operator has the following format: +``` Where or ... +``` -For example, the following commands get all instances -of the Win32_Process WMI class but returns them -only if the process name is winword.exe or excel.exe. +For example, the following commands get all instances of the Win32_Process WMI +class but returns them only if the process name is winword.exe or excel.exe. -PS C:> $q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe'" -PS C:> Get-WmiObject -Query $q +```powershell +$q = "Select * from Win32_Process where Name='winword.exe'" + + " or Name='excel.exe'" +Get-WmiObject -Query $q +``` -The Or statement can be used with more than two -conditions. In the following query, the Or statement -gets Winword.exe, Excel.exe, or Powershell.exe. +The Or statement can be used with more than two conditions. In the following +query, the Or statement gets Winword.exe, Excel.exe, or Powershell.exe. -$q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe' or Name = 'powershell.exe'" +```powershell +$q = "Select * from Win32_Process where Name='winword.exe'" + + " or Name='excel.exe' or Name='powershell.exe'" +``` -# USING THE AND OPERATOR +## USING THE AND OPERATOR -To specify multiple related conditions, use the And -keyword. The And keyword appears in the Where clause. It -returns items that meet all of the conditions. +To specify multiple related conditions, use the And keyword. The And keyword +appears in the Where clause. It returns items that meet all of the conditions. The And operator has the following format: +``` Where and ... +``` -For example, the following commands get processes -that have a name of "Winword.exe" and the process -ID of 6512. +For example, the following commands get processes that have a name of +"Winword.exe" and the process ID of 6512. Note that the commands use the Get-CimInstance cmdlet. -PS C:> $q = "Select * from Win32_Process where Name = 'winword.exe' and ProcessID =6512" -PS C:> Get-CimInstance -Query $q - -ProcessId Name HandleCount WorkingSetSize VirtualSize ---------- ---- ----------- -------------- ----------- -# 6512 WINWORD.EXE 768 117170176 633028608 +```powershell +$q = "Select * from Win32_Process where Name = 'winword.exe' " + + "and ProcessID =6512" +Get-CimInstance -Query $q +``` +```output +ProcessId Name HandleCount WorkingSetSize VirtualSize +--------- ---- ----------- -------------- ----------- +# 6512 WINWORD.EXE 768 117170176 633028608 +``` -All operators, including the Like operators are -valid with the Or and And operators. And, you can -combine the Or and And operators in a single query -with parentheses that tell Windows PowerShell which -clauses to process first. +All operators, including the Like operators are valid with the Or and And +operators. And, you can combine the Or and And operators in a single query +with parentheses that tell Windows PowerShell which clauses to process first. -This command uses the Windows PowerShell continuation -character (`) divide the command into two lines. +This command uses the Windows PowerShell continuation character (`) divide the +command into two lines. -PS C:> $q = "Select * from Win32_Process ` +```powershell +$q = "Select * from Win32_Process ` where (Name = 'winword.exe' or Name = 'excel.exe') and HandleCount > 700" +Get-CimInstance -Query $q +``` -PS C:> Get-CimInstance -Query $q -ProcessId Name HandleCount WorkingSetSize VirtualSize ---------- ---- ----------- -------------- ----------- -# 6512 WINWORD.EXE 797 117268480 634425344 +```output +ProcessId Name HandleCount WorkingSetSize VirtualSize +--------- ---- ----------- -------------- ----------- + 6512 WINWORD.EXE 797 117268480 634425344 + 9610 EXCEL.EXE 727 38858752 323227648 +``` -# 9610 EXCEL.EXE 727 38858752 323227648 +## SEARCHING FOR NULL VALUES +Searching for null values in WMI is challenging, because it can lead to +unpredictable results. Null is not zero and it is not equivalent or to an +empty string. Some WMI class properties are initialized and others are not, so +a search for null might not work for all properties. -# SEARCHING FOR NULL VALUES +To search for null values, use the Is operator with a value of "null". -Searching for null values in WMI is challenging, -because it can lead to unpredictable results. Null -is not zero and it is not equivalent or to an empty -string. Some WMI class properties are initialized and -others are not, so a search for null might not work -for all properties. +For example, the following commands get processes that have a null value for +the IntallDate property. The commands return many processes. -To search for null values, use the Is operator with -a value of "null". +```powershell +$q = "Select * from Win32_Process where InstallDate is null" +Get-WmiObject -Query $q +``` -For example, the following commands get processes -that have a null value for the IntallDate property. -The commands return many processes. +In contrast, the following command, gets user accounts that have a null value +for the Description property. This command does not return any user accounts, +even though most user accounts do not have any value for the Description +property. -PS C:> $q = "Select * from Win32_Process where InstallDate is null" -PS C:> Get-WmiObject -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Description is null" +Get-WmiObject -Query $q +``` -In contrast, the following command, gets user -accounts that have a null value for the Description -property. This command does not return any user -accounts, even though most user accounts do not have -any value for the Description property. - -PS C:> $q = "Select * from Win32_UserAccount where Description is null" -PS C:> Get-WmiObject -Query $q - -To find the user accounts that have no value for -the Description property, use the equality operator -to get an empty string. To represent the empty string, +To find the user accounts that have no value for the Description property, use +the equality operator to get an empty string. To represent the empty string, use two consecutive single quotation marks. +```powershell $q = "Select * from Win32_UserAccount where Description = '' " +``` -# USING TRUE OR FALSE +## USING TRUE OR FALSE -To get Boolean values in the properties of WMI -objects, use True and False. They are not case -sensitive. +To get Boolean values in the properties of WMI objects, use True and False. +They are not case sensitive. -The following WQL query returns only local user -accounts from a domain joined computer. +The following WQL query returns only local user accounts from a domain joined +computer. -PS C:> $q = "Select * from Win32_UserAccount where LocalAccount = True" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where LocalAccount = True" +Get-CimInstance -Query $q +``` + +To find domain accounts, use a value of False, as shown in the following +example. -To find domain accounts, use a value of False, -as shown in the following example. +```powershell +$q = "Select * from Win32_UserAccount where LocalAccount = False" +Get-CimInstance -Query $q +``` -PS C:> $q = "Select * from Win32_UserAccount where LocalAccount = False" -PS C:> Get-CimInstance -Query $q +## USING THE ESCAPE CHARACTER -# USING THE ESCAPE CHARACTER +WQL uses the backslash (\) as its escape character. This is different from +Windows PowerShell, which uses the backtick character (`). -WQL uses the backslash () as its escape -character. This is different from Windows -PowerShell, which uses the backtick -character (`). +Quotation marks, and the characters used for quotation marks, often need to be +escaped so that they are not misinterpreted. -Quotation marks, and the characters used for -quotation marks, often need to be escaped so -that they are not misinterpreted. +To find a user whose name includes a single quotation mark, use a backslash to +escape the single quotation mark, as shown in the following command. -To find a user whose name includes a single quotation -mark, use a backslash to escape the single quotation -mark, as shown in the following command. +```powershell +$q = "Select * from Win32_UserAccount where Name = 'Tim O\'Brian'" +Get-CimInstance -Query $q +``` -PS C:> $q = "Select * from Win32_UserAccount where Name = 'Tim O\'Brian'" -PS C:> Get-CimInstance -Query $q +```output Name Caption AccountType SID Domain ---- ------- ----------- --- ------ Tim O'Brian FABRIKAM\TimO 512 S-1-5-21-1457... FABRIKAM +``` -In some case, the backslash also needs to be -escaped. For example, the following commands -generate an Invalid Query error due to the -backslash in the Caption value. +In some case, the backslash also needs to be escaped. For example, the +following commands generate an Invalid Query error due to the backslash in the +Caption value. -PS C:> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" +Get-CimInstance -Query $q +``` + +```output Get-CimInstance : Invalid query At line:1 char:1 + Get-CimInstance -Query $q -# +!INCLUDE[]~~~~~~~~~~~ - -+ CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimException -+ FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastructure.CimCmdlets ++ ~~~~~~~~~~~ + + CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimExcep + + FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastr +``` -To escape the backslash, use a second backslash -character, as shown in the following command. +To escape the backslash, use a second backslash character, as shown in the +following command. -PS C:> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\\TimO'" +Get-CimInstance -Query $q +``` # SEE ALSO @@ -736,4 +739,3 @@ PS C:> Get-CimInstance -Query $q [about_WMI](about_WMI.md) [about_WMI_Cmdlets](about_WMI_Cmdlets.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md index 52e7e3216836..1c09f4504b20 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,108 +7,104 @@ title: about_Windows_PowerShell_ISE --- # About Windows PowerShell ISE -## about_Windows_PowerShell_ISE - - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes the features and system requirements of Windows PowerShell Integrated Scripting Environment (ISE). -# LONG DESCRIPTION +## LONG DESCRIPTION -Windows PowerShell ISE is a graphical host application for Windows -PowerShell. In Windows PowerShell ISE, you can run commands and write, -test, and debug scripts in a single Windows-based graphical user -interface. Its features include Intellisense, multiline editing, tab -completion, auto-save, syntax coloring, selective execution, -context-sensitive help, Show Command (compose commands in a window) -and support for double-byte character sets and right-to-left languages. +Windows PowerShell ISE is a graphical host application for Windows PowerShell. +In Windows PowerShell ISE, you can run commands and write, test, and debug +scripts in a single Windows-based graphical user interface. Its features +include Intellisense, multiline editing, tab completion, auto-save, syntax +coloring, selective execution, context-sensitive help, Show Command (compose +commands in a window) and support for double-byte character sets and +right-to-left languages. -Windows PowerShell ISE is an excellent tool for beginners. The Show -Command window and New Remote PowerShell Tab guide you through tasks -so that you can be successful on the first try. Snippets and error -indicators help you learn the Windows PowerShell language as you work. +Windows PowerShell ISE is an excellent tool for beginners. The Show Command +window and New Remote PowerShell Tab guide you through tasks so that you can +be successful on the first try. Snippets and error indicators help you learn +the Windows PowerShell language as you work. -Advanced users can take advantage of the sophisticated debugging -features, add-ons, and the Windows PowerShell ISE object model. +Advanced users can take advantage of the sophisticated debugging features, +add-ons, and the Windows PowerShell ISE object model. What's New in Windows PowerShell ISE in Windows PowerShell 4.0 -Windows PowerShell ISE introduces two new features in Windows -PowerShell 4.0. +Windows PowerShell ISE introduces two new features in Windows PowerShell 4.0. --- Windows PowerShell ISE now supports both Windows PowerShell -Workflow debugging and remote script debugging. For more -Information, see about_Debuggers. --- IntelliSense support has been added for Windows PowerShell Desired -State Configuration providers and configurations. +- Windows PowerShell ISE now supports both Windows PowerShell Workflow + debugging and remote script debugging. For more Information, see + about_Debuggers. -Starting Windows PowerShell ISE +- IntelliSense support has been added for Windows PowerShell Desired State + Configuration providers and configurations. + +## Starting Windows PowerShell ISE Windows PowerShell ISE is installed, enabled, and ready to use in all supported versions of Windows. -- In Windows 8.1, Windows 8, Windows Server 2012 R2, and Windows Server -2012, on the Start screen, type PowerShell_ISE, and then click -PowerShell_ISE or Windows PowerShell ISE. +- In Windows 8.1, Windows 8, Windows Server 2012 R2, and Windows Server 2012, + on the Start screen, type PowerShell_ISE, and then click PowerShell_ISE or + Windows PowerShell ISE. -- In Windows Server 2012 R2 and Windows Server 2012, in Server Manager, -on the Tools menu, click Windows PowerShell ISE. +- In Windows Server 2012 R2 and Windows Server 2012, in Server Manager, on the + Tools menu, click Windows PowerShell ISE. - In earlier versions of Windows, click Start, All Programs, Accessories, -Windows PowerShell, and then click Windows PowerShell ISE. + Windows PowerShell, and then click Windows PowerShell ISE. -- In a Windows PowerShell console, Cmd.exe, or the Run or Search box -in Windows, type "PowerShell_ise.exe". You can also use the command-line -parameters, including the NoProfile switch. For more information, see -PowerShell_ISE.exe Console Help -(http://go.microsoft.com/fwlink/?LinkId=243055). +- In a Windows PowerShell console, Cmd.exe, or the Run or Search box in + Windows, type "PowerShell_ise.exe". You can also use the command-line + parameters, including the NoProfile switch. For more information, see + [PowerShell_ISE.exe Console Help](http://go.microsoft.com/fwlink/?LinkId=243055). -Running Interactive Commands +## Running Interactive Commands -You can run any Windows PowerShell expression or command in Windows -PowerShell ISE. You can use cmdlets, providers, snap-ins, and modules as -you would use them in the Windows PowerShell console. +You can run any Windows PowerShell expression or command in Windows PowerShell +ISE. You can use cmdlets, providers, snap-ins, and modules as you would use +them in the Windows PowerShell console. You can type or paste interactive commands in the Console pane. To run the commands, you can use buttons, menu items, and keyboard shortcuts. -You can use the multiline editing feature to type or paste several lines -of code into the Console pane at once. When you press the UP ARROW key to -recall the previous command, all the lines in the command are recalled. -When you type commands, press SHIFT+ENTER to make a new blank line appear -under the current line. +You can use the multiline editing feature to type or paste several lines of +code into the Console pane at once. When you press the UP ARROW key to recall +the previous command, all the lines in the command are recalled. When you type +commands, press SHIFT+ENTER to make a new blank line appear under the current +line. -Viewing Output +## Viewing Output -The results of commands and scripts are displayed in the Console pane. You -can move or copy the results from the Console pane by using keyboard -shortcuts or the Copy button on the toolbar, and you can paste the results -in the Script pane or Console panes or other programs. To clear the Console -pane, click the "Clear Output Pane" button or type one of the following -commands: +The results of commands and scripts are displayed in the Console pane. You can +move or copy the results from the Console pane by using keyboard shortcuts or +the Copy button on the toolbar, and you can paste the results in the Script +pane or Console panes or other programs. To clear the Console pane, click the +"Clear Output Pane" button or type one of the following commands: +``` Clear-Host cls +``` -Writing Scripts and Functions +## Writing Scripts and Functions -In the Script pane, you can open, compose, edit, and run scripts. The -Script pane lets you edit scripts by using buttons and keyboard shortcuts. -You can also copy, cut, and paste text between the Script pane and the -Console pane. +In the Script pane, you can open, compose, edit, and run scripts. The Script +pane lets you edit scripts by using buttons and keyboard shortcuts. You can +also copy, cut, and paste text between the Script pane and the Console pane. -You can use the selective run feature to run all or part of a script. To -run part of a script, select the text you want to run, and then click the -Run Selection button or press F8. By default, F8 runs the current line. +You can use the selective run feature to run all or part of a script. To run +part of a script, select the text you want to run, and then click the Run +Selection button or press F8. By default, F8 runs the current line. Advanced editing features include brace-matching, expand-collapse, line numbers, error indicators, block editing and indenting, rich copy, and case conversion. -Getting Help +## Getting Help Windows PowerShell ISE includes help topics that describe its use. In addition, all installed help files are accessible from the Script and Command @@ -116,101 +112,99 @@ panes. Windows PowerShell ISE also supports context-sensitive help. To get help about a particular cmdlet, provider, or keyword, place the cursor in the name of the -item and press F1. To search the help topics, press F1 and type the search term. +item and press F1. To search the help topics, press F1 and type the search +term. To update the help topics on the computer, use the Update Windows PowerShell -Help item in the Help menu. This item updates help for the modules in the current -session in the current UI culture. It is equivalent to running the Update-Help -cmdlet without parameters. To update help for the cmdlets that come with Windows -PowerShell, start Windows PowerShell ISE with the "Run as administrator" option. +Help item in the Help menu. This item updates help for the modules in the +current session in the current UI culture. It is equivalent to running the +Update-Help cmdlet without parameters. To update help for the cmdlets that +come with Windows PowerShell, start Windows PowerShell ISE with the "Run as +administrator" option. You can also use the Get-Help, Save-Help, and Update-Help cmdlets in Windows PowerShell ISE, just as you use it in the Windows PowerShell console. However, in Windows PowerShell ISE, the Help function displays the entire help topic, -not one page at a time. +not one page at a time. -Debugging Scripts +## Debugging Scripts -You can use the Windows PowerShell ISE debugger to debug a Windows -PowerShell script or function. When you debug a script, you can use menu -items and shortcut keys to perform many of the same tasks that you would -perform in the Windows PowerShell console. For example, to set a line -breakpoint in a script, right-click the line of code, and then click -Toggle Breakpoint. +You can use the Windows PowerShell ISE debugger to debug a Windows PowerShell +script or function. When you debug a script, you can use menu items and +shortcut keys to perform many of the same tasks that you would perform in the +Windows PowerShell console. For example, to set a line breakpoint in a script, +right-click the line of code, and then click Toggle Breakpoint. -As you step through a script while debugging, the debugging highlighter -shows precisely which part of the command is running and automatically -opens files that include called functions and scripts. +As you step through a script while debugging, the debugging highlighter shows +precisely which part of the command is running and automatically opens files +that include called functions and scripts. -By default, the Toggle Breakpoint menu item sets a breakpoint on an -entire line in a script, but you can set a breakpoint on a variable -or command name. You can also set a breakpoint on a command by line -and column number, making it easier to debug long pipeline commands. +By default, the Toggle Breakpoint menu item sets a breakpoint on an entire +line in a script, but you can set a breakpoint on a variable or command name. +You can also set a breakpoint on a command by line and column number, making +it easier to debug long pipeline commands. -Often, you can debug syntax errors in a script just by opening the -script file in Windows PowerShell ISE. The error indicators identify -syntax errors and the outlining features let you collapse parts of the -script to focus on trouble spots. +Often, you can debug syntax errors in a script just by opening the script file +in Windows PowerShell ISE. The error indicators identify syntax errors and the +outlining features let you collapse parts of the script to focus on trouble +spots. -You can also use the Windows PowerShell debugger cmdlets in the Command -pane just as you would use them in the console. +You can also use the Windows PowerShell debugger cmdlets in the Command pane +just as you would use them in the console. -Running Remote Commands +## Running Remote Commands -The New Remote PowerShell Tab feature makes it easy to establish a -persistent user-managed Windows PowerShell session ("PSSession") to -the local computer or a remote computer. The command opens a pop-up -window that prompts you for a computer name and for the user account -that has permission to run commands on the remote computer. +The New Remote PowerShell Tab feature makes it easy to establish a persistent +user-managed Windows PowerShell session ("PSSession") to the local computer or +a remote computer. The command opens a pop-up window that prompts you for a +computer name and for the user account that has permission to run commands on +the remote computer. -Customizing the View +## Customizing the View -You can use Windows PowerShell ISE features to move and to resize the -Console pane and the Script pane. You can show and hide either pane, -and you can change the text size in all the panes. +You can use Windows PowerShell ISE features to move and to resize the Console +pane and the Script pane. You can show and hide either pane, and you can +change the text size in all the panes. -You can also use the Options window to customize the appearance and -operation of Windows PowerShell ISE. In addition, Windows PowerShell -ISE has a custom host variable, $psISE, that you can use to customize -Windows PowerShell ISE, including adding menus and menu items. +You can also use the Options window to customize the appearance and operation +of Windows PowerShell ISE. In addition, Windows PowerShell ISE has a custom +host variable, $psISE, that you can use to customize Windows PowerShell ISE, +including adding menus and menu items. -Windows PowerShell ISE Profile +## Windows PowerShell ISE Profile Windows PowerShell ISE has its own Windows PowerShell profile, -Microsoft.PowerShellISE_profile.ps1. In this profile, you can store -functions, aliases, variables, and commands that you use in Windows -PowerShell ISE. +Microsoft.PowerShellISE_profile.ps1. In this profile, you can store functions, +aliases, variables, and commands that you use in Windows PowerShell ISE. -Items in the Windows PowerShell AllHosts profiles (CurrentUser\AllHosts -and AllUsers\AllHosts) are also available in Windows PowerShell ISE, just -as they are in any Windows PowerShell host program. However, the items -in your Windows PowerShell console profiles are not available in Windows -PowerShell ISE. +Items in the Windows PowerShell AllHosts profiles (CurrentUser\\AllHosts and +AllUsers\\AllHosts) are also available in Windows PowerShell ISE, just as they +are in any Windows PowerShell host program. However, the items in your Windows +PowerShell console profiles are not available in Windows PowerShell ISE. Instructions for moving and reconfiguring your profiles are available in Windows PowerShell ISE Help and in about_Profiles. -# NOTES +## NOTES -Windows PowerShell ISE is an optional Windows Feature that is turned on -by default on client and server versions of Windows. To enable and disable +Windows PowerShell ISE is an optional Windows Feature that is turned on by +default on client and server versions of Windows. To enable and disable Windows PowerShell ISE in client versions of Windows, use Turn Windows -Features On or Off in Control Panel. To enable and disable Windows -PowerShell ISE in server versions of Windows, use the Add Roles -and Features Wizard in Server Manager. - -Because Windows PowerShell ISE requires a user interface, it does not work -on Server Core installations of Windows Server. However, if you add the -Windows PowerShell ISE feature, the installation automatically converts -to Server with a GUI. - -Windows PowerShell ISE is built on the Windows Presentation Foundation -(WPF). If the graphical elements of Windows PowerShell ISE do not render -correctly on your system, you might resolve the problem by adding or -adjusting the "Disable WPF Hardware acceleration" graphics rendering -settings on your system. For more information, see "Graphics Rendering -Registry Settings" in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=144711. +Features On or Off in Control Panel. To enable and disable Windows PowerShell +ISE in server versions of Windows, use the Add Roles and Features Wizard in +Server Manager. + +Because Windows PowerShell ISE requires a user interface, it does not work on +Server Core installations of Windows Server. However, if you add the Windows +PowerShell ISE feature, the installation automatically converts to Server with +a GUI. + +Windows PowerShell ISE is built on the Windows Presentation Foundation (WPF). +If the graphical elements of Windows PowerShell ISE do not render correctly on +your system, you might resolve the problem by adding or adjusting the "Disable +WPF Hardware acceleration" graphics rendering settings on your system. For +more information, see [Graphics Rendering Registry Settings](http://go.microsoft.com/fwlink/?LinkId=144711) +in the MSDN library. # SEE ALSO @@ -220,17 +214,16 @@ http://go.microsoft.com/fwlink/?LinkId=144711. [about_Updatable_Help](about_Updatable_Help.md) -Get-Help - -Get-IseSnippet +[Get-Help](../Get-Help.md) -Import-IseSnippet +[Get-IseSnippet](../../ISE/Get-IseSnippet.md) -New-IseSnippet +[Import-IseSnippet](../../ISE/Import-IseSnippet.md) -Save-Help +[New-IseSnippet](../../ISE/New-IseSnippet.md) -Show-Command +[Save-Help](../Save-Help.md) -Update-Help +[Show-Command](../../Microsoft.PowerShell.Utility/Show-Command.md) +[Update-Help](../Update-Help.md) \ No newline at end of file diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md index 7dbc9d843db6..26c1585936bf 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,48 +7,60 @@ title: about_Windows_RT --- # About Windows RT -## about_Windows_RT - ## SHORT DESCRIPTION -Explains limitations of Windows PowerShell?4.0 on Windows RT 8.1. +Explains limitations of Windows PowerShell® 4.0 on Windows RT 8.1. ## LONG DESCRIPTION -The Windows RT 8.1 operating system is installed on computers and devices (such as Microsoft Surface 2, on which it is the operating system that ships with the computer) that use Advanced RISC Machine (ARM) processors. - -Windows PowerShell 4.0 is included in Windows RT 8.1. All cmdlets, providers, and modules, and most scripts designed for Windows PowerShell 2.0 and later releases run on Windows RT 8.1 without changes. - -Because Windows RT 8.1 does not include all Windows features, some Windows PowerShell features work differently or do not work on Windows RT-based devices. The following list explains the differences. - --- Windows PowerShell ISE is not included in and cannot run on Windows RT 8.1. Windows PowerShell ISE requires Windows Presentation Foundation, which is not included in Windows RT 8.1. - --- Windows PowerShell remoting and the WinRM service are disabled by default. To enable remoting, run the Enable-PSRemoting cmdlet. Also, run the Set-Service cmdlet to set the startup type of the WinRM service to Automatic, or Automatic (Delayed Start). -While remoting is disabled, you can use Windows PowerShell remoting to run commands on other computers, but other computers cannot run commands on the Windows RT device. Also, implicit remoting—that is, remoting that is built in to a cmdlet or script, and not explicitly requested with added parameters—does not work in Windows PowerShell running on Windows RT 8.1. +The Windows RT 8.1 operating system is installed on computers and devices +(such as Microsoft Surface 2, on which it is the operating system that ships +with the computer) that use Advanced RISC Machine (ARM) processors. --- Domain-joined computing and Kerberos authentication are not supported on Windows RT 8.1. You cannot use Windows PowerShell to add or manage these features. +Windows PowerShell 4.0 is included in Windows RT 8.1. All cmdlets, providers, +and modules, and most scripts designed for Windows PowerShell 2.0 and later +releases run on Windows RT 8.1 without changes. --- Microsoft .NET Framework classes that are not supported on Windows RT 8.1 are also not supported by Windows PowerShell on Windows RT 8.1. +Because Windows RT 8.1 does not include all Windows features, some Windows +PowerShell features work differently or do not work on Windows RT-based +devices. The following list explains the differences. --- Transactions are not enabled on Windows RT 8.1. Transaction cmdlets, such as Start-Transaction, and transaction parameters, such as UseTransaction, do not work properly. +- Windows PowerShell ISE is not included in and cannot run on Windows RT 8.1. + Windows PowerShell ISE requires Windows Presentation Foundation, which is not + included in Windows RT 8.1. --- All Windows PowerShell sessions on Windows RT 8.1 devices use the ConstrainedLanguage language mode. ConstrainedLanguage language mode is a companion to User Mode Code Integrity (UMCI). It permits all Windows cmdlets and Windows PowerShell language elements, but restricts types to ensure that users cannot use Windows PowerShell to circumvent or violate the UMCI protections. +- Windows PowerShell remoting and the WinRM service are disabled by default. + To enable remoting, run the Enable-PSRemoting cmdlet. Also, run the + Set-Service cmdlet to set the startup type of the WinRM service to Automatic, + or Automatic (Delayed Start). -For more information about ConstrainedLanguage language mode, see about_Language_Modes. + While remoting is disabled, you can use Windows PowerShell remoting to run + commands on other computers, but other computers cannot run commands on the + Windows RT device. Also, implicit remoting—that is, remoting that is built in + to a cmdlet or script, and not explicitly requested with added parameters—does + not work in Windows PowerShell running on Windows RT 8.1. +- Domain-joined computing and Kerberos authentication are not supported on + Windows RT 8.1. You cannot use Windows PowerShell to add or manage these + features. -## KEYWORDS -about_ARM +- Microsoft .NET Framework classes that are not supported on Windows RT 8.1 + are also not supported by Windows PowerShell on Windows RT 8.1. -about_PowerShell_on_ARM +- Transactions are not enabled on Windows RT 8.1. Transaction cmdlets, such + as Start-Transaction, and transaction parameters, such as UseTransaction, do + not work properly. -about_PowerShell_on_Surface - -about_Windows_RT_8.1 - -about_WindowsRT +- All Windows PowerShell sessions on Windows RT 8.1 devices use the + ConstrainedLanguage language mode. ConstrainedLanguage language mode is a + companion to User Mode Code Integrity (UMCI). It permits all Windows cmdlets + and Windows PowerShell language elements, but restricts types to ensure that + users cannot use Windows PowerShell to circumvent or violate the UMCI + protections. +For more information about ConstrainedLanguage language mode, see +[about_Language_Modes](about_Language_Modes.md). ## SEE ALSO @@ -57,8 +69,3 @@ about_WindowsRT [about_Remote](about_Remote.md) [about_Windows_PowerShell_ISE](about_Windows_PowerShell_ISE.md) - -about_Workflows - -Windows PowerShell System Requirements: http://technet.microsoft.com/library/hh857337.aspx) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md index 8322188c9328..986f4d855fbc 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,158 +7,166 @@ title: about_DesiredStateConfiguration --- # about_DesiredStateConfiguration -``` -TOPIC - about_Desired_State_Configuration - -SHORT DESCRIPTION - Provides a brief introduction to the Windows - PowerShell Desired State Configuration (DSC) feature. - -LONG DESCRIPTION - DSC is a management platform in Windows PowerShell that enables deploying - and managing configuration data for software services, and managing the - environment in which these services run. - - DSC provides a set of Windows PowerShell language extensions, - new cmdlets, and resources that you can use to declaratively specify - how you want the state of your software environment to be configured. It - also provides a means to maintain and manage existing configurations. - - DSC is introduced in Windows PowerShell 4.0. - - For detailed information about DSC, see - "Windows PowerShell Desired State Configuration Overview" in the TechNet - Library at http://go.microsoft.com/fwlink/?LinkId=311940. - -DEVELOPING DSC RESOURCES WITH CLASSES - Starting in Windows PowerShell 5.0, you can develop DSC resources by using - classes. For more information, see about_Classes, and "Writing a custom - DSC resource with PowerShell classes" on Microsoft TechNet - (http://technet.microsoft.com/library/dn948461.aspx). - -USING DSC - To use DSC to configure your environment, first define a Windows - PowerShell script block using the Configuration keyword, followed by an - identifier, which is in turn followed by the pair of curly braces delimiting - the block. Inside the configuration block you can define node blocks that - specify the desired configuration state for each node (computer) in the - environment. A node block starts with the Node keyword, followed by the name - of the target computer, which can be a variable. After the computer name, come - the curly braces that delimit the node block. Inside the node block, you can - define resource blocks to configure specific resources. A resource block starts - with the type name of the resource, followed by the identifier you want to - specify for that block, followed by the curly braces that delimit the block, - as shown in the following example. - - Configuration MyWebConfig - { - # Parameters are optional - param ($MachineName, $WebsiteFilePath) - - # A Configuration block can have one or more Node blocks - Node $MachineName - { - # Next, specify one or more resource blocks - # WindowsFeature is one of the resources you can use in a Node block - # This example ensures the Web Server (IIS) role is installed - WindowsFeature IIS - { - # To ensure that the role is not installed, set Ensure to "Absent" - Ensure = "Present" - Name = "Web-Server" # Use the Name property from Get-WindowsFeature - } - - # You can use the File resource to create files and folders - # "WebDirectory" is the name you want to use to refer to this instance - File WebDirectory - { - Ensure = "Present" # You can also set Ensure to "Absent“ - Type = "Directory“ # Default is “File” - Recurse = $true - SourcePath = $WebsiteFilePath - DestinationPath = "C:\inetpub\wwwroot" - - # Ensure that the IIS block is successfully run first before - # configuring this resource - Requires = "[WindowsFeature]IIS" # Use Requires for dependencies - } - } - } - - To create a configuration, invoke the Configuration block the same way you would - invoke a Windows PowerShell function, passing in any expected parameters you may - have defined (two in the example above). For example, in this case: - - MyWebConfig -MachineName "TestMachine" –WebsiteFilePath "\\filesrv\WebFiles" ` - -OutputPath "C:\Windows\system32\temp" # OutputPath is optional - - This generates a MOF file per node at the path you specify. These MOF files specify - the desired configuration for each node. Next, use the following cmdlet to parse the - configuration MOF files, send each node its corresponding configuration, and enact - those configurations. Note that you do not need to create a separate MOF file for - class-based DSC resources. - - Start-DscConfiguration –Verbose -Wait -Path "C:\Windows\system32\temp" - -USING DSC TO MAINTAIN CONFIGURATION STATE - With DSC, configuration is idempotent. This means that if you use DSC to enact the - same configuration more than once, the resulting configuration state will always - be the same. Because of this, if you suspect that any nodes in your environment - may have drifted from the desired state of configuration, you can enact the same - DSC configuration again to bring them back to the desired state. You do not need - to modify the configuration script to address only those resources whose state has - drifted from the desired state. - - The following example shows how you can verify whether the actual state of - configuration on a given node has drifted from the last DSC configuration enacted - on the node. In this example we are checking the configuration of the local computer. - - $session = New-CimSession -ComputerName "localhost" - Test-DscConfiguration -CimSession $session - -BUILT-IN DSC RESOURCES - You can use the following built-in resources in your configuration scripts: - - Name Properties - ---- ---------- - File {DestinationPath, Attributes, Checksum, Contents...} - Archive {Destination, Path, Checksum, Credential...} - Environment {Name, DependsOn, Ensure, Path...} - Group {GroupName, Credential, DependsOn, Description...} - Log {Message, DependsOn, PsDscRunAsCredential} - Package {Name, Path, ProductId, Arguments...} - Registry {Key, ValueName, DependsOn, Ensure...} - Script {GetScript, SetScript, TestScript, Credential...} - Service {Name, BuiltInAccount, Credential, Dependencies...} - User {UserName, DependsOn, Description, Disabled...} - WaitForAll {NodeName, ResourceName, DependsOn, PsDscRunAsCredential...} - WaitForAny {NodeName, ResourceName, DependsOn, PsDscRunAsCredential...} - WaitForSome {NodeCount, NodeName, ResourceName, DependsOn...} - WindowsFeature {Name, Credential, DependsOn, Ensure...} - WindowsOptionalFeature {Name, DependsOn, Ensure, LogLevel...} - WindowsProcess {Arguments, Path, Credential, DependsOn...} - - To get a list of available DSC resources on your system, run the - Get-DscResource cmdlet. - - The example in this topic demonstrates how to use the File and WindowsFeature - resources. To see all properties that you can use with a resource, insert the - cursor in the resource keyword (for example, File) within your configuration - script in Windows PowerShell ISE, hold down CTRL, and then press SPACEBAR. - -FIND MORE RESOURCES - You can download, install, and learn about many other available DSC resources that - have been created by the PowerShell and DSC user community, and by Microsoft. - Visit the [PowerShell Gallery](https://www.powershellgallery.com/) to browse and learn - about available DSC resources. - -SEE ALSO - "Windows PowerShell Desired State Configuration Overview" - (http://go.microsoft.com/fwlink/?LinkId=311940) - "Built-In Windows PowerShell Desired State Configuration Resources" - (http://technet.microsoft.com/library/dn249921.aspx) - "Build Custom Windows PowerShell Desired State Configuration Resources" - (http://technet.microsoft.com/library/dn249927.aspx) + +## SHORT DESCRIPTION + +Provides a brief introduction to the PowerShell Desired State +Configuration (DSC) feature. + +## LONG DESCRIPTION + +DSC is a management platform in PowerShell that enables deploying and managing +configuration data for software services, and managing the environment in +which these services run. + +DSC provides a set of PowerShell language extensions, new cmdlets, and +resources that you can use to declaratively specify how you want the state of +your software environment to be configured. It also provides a means to +maintain and manage existing configurations. + +DSC is introduced in PowerShell 4.0. + +For detailed information about DSC, see +[PowerShell Desired State Configuration Overview](http://go.microsoft.com/fwlink/?LinkId=311940) +in the TechNet Library. + +## DEVELOPING DSC RESOURCES WITH CLASSES + +Starting in PowerShell 5.0, you can develop DSC resources by using classes. +For more information, see [about_Classes](about_Classes.md), and +[Writing a custom DSC resource with PowerShell classes](http://technet.microsoft.com/library/dn948461.aspx) +on Microsoft TechNet. + +## USING DSC + +To use DSC to configure your environment, first define a PowerShell +script block using the Configuration keyword, followed by an identifier, which +is in turn followed by the pair of curly braces delimiting the block. Inside +the configuration block you can define node blocks that specify the desired +configuration state for each node (computer) in the environment. A node block +starts with the Node keyword, followed by the name of the target computer, +which can be a variable. After the computer name, come the curly braces that +delimit the node block. Inside the node block, you can define resource blocks +to configure specific resources. A resource block starts with the type name of +the resource, followed by the identifier you want to specify for that block, +followed by the curly braces that delimit the block, as shown in the following +example. Configuration MyWebConfig { # Parameters are optional param +($MachineName, $WebsiteFilePath) + +```powershell +# A Configuration block can have one or more Node blocks +Node $MachineName +{ + # Next, specify one or more resource blocks + # WindowsFeature is one of the resources you can use in a Node block + # This example ensures the Web Server (IIS) role is installed + WindowsFeature IIS + { + # To ensure that the role is not installed, set Ensure to "Absent" + Ensure = "Present" + Name = "Web-Server" # Use the Name property from Get-WindowsFeature + } + + # You can use the File resource to create files and folders + # "WebDirectory" is the name you want to use to refer to this instance + File WebDirectory + { + Ensure = "Present" # You can also set Ensure to "Absent“ + Type = "Directory“ # Default is “File” + Recurse = $true + SourcePath = $WebsiteFilePath + DestinationPath = "C:\inetpub\wwwroot" + + # Ensure that the IIS block is successfully run first before + # configuring this resource + Requires = "[WindowsFeature]IIS" # Use Requires for dependencies + } +} +} ``` +To create a configuration, invoke the Configuration block the same way you +would invoke a PowerShell function, passing in any expected parameters you may +have defined (two in the example above). For example, in this case: + +```powershell +MyWebConfig -MachineName "TestMachine" –WebsiteFilePath ` + "\\filesrv\WebFiles" -OutputPath "C:\Windows\system32\temp" +# OutputPath is optional +``` + +This generates a MOF file per node at the path you specify. These MOF files +specify the desired configuration for each node. Next, use the following +cmdlet to parse the configuration MOF files, send each node its corresponding +configuration, and enact those configurations. Note that you do not need to +create a separate MOF file for class-based DSC resources. + +```powershell +Start-DscConfiguration –Verbose -Wait -Path "C:\Windows\system32\temp" +``` + +## USING DSC TO MAINTAIN CONFIGURATION STATE + +With DSC, configuration is idempotent. This means that if you use DSC to enact +the same configuration more than once, the resulting configuration state will +always be the same. Because of this, if you suspect that any nodes in your +environment may have drifted from the desired state of configuration, you can +enact the same DSC configuration again to bring them back to the desired +state. You do not need to modify the configuration script to address only +those resources whose state has drifted from the desired state. + +The following example shows how you can verify whether the actual state of +configuration on a given node has drifted from the last DSC configuration +enacted on the node. In this example we are checking the configuration of the +local computer. + +```powershell +$session = New-CimSession -ComputerName "localhost" +Test-DscConfiguration -CimSession $session +``` + +## BUILT-IN DSC RESOURCES + +You can use the following built-in resources in your configuration scripts: + +|Name |Properties | +|----------------------|---------------------------------------------------| +|File |{DestinationPath, Attributes, Checksum, Content...}| +|Archive |{Destination, Path, Checksum, Credential...} | +|Environment |{Name, DependsOn, Ensure, Path...} | +|Group |{GroupName, Credential, DependsOn, Description...} | +|Log |{Message, DependsOn, PsDscRunAsCredential} | +|Package |{Name, Path, ProductId, Arguments...} | +|Registry |{Key, ValueName, DependsOn, Ensure...} | +|Script |{GetScript, SetScript, TestScript, Credential...} | +|Service |{Name, BuiltInAccount, Credential, Dependencies...}| +|User |{UserName, DependsOn, Description, Disabled...} | +|WaitForAll |{NodeName, ResourceName, DependsOn, PsDscRunAsC...}| +|WaitForAny |{NodeName, ResourceName, DependsOn, PsDscRunAsC...}| +|WaitForSome |{NodeCount, NodeName, ResourceName, DependsOn...} | +|WindowsFeature |{Name, Credential, DependsOn, Ensure...} | +|WindowsOptionalFeature|{Name, DependsOn, Ensure, LogLevel...} | +|WindowsProcess |{Arguments, Path, Credential, DependsOn...} | + +To get a list of available DSC resources on your system, run the +Get-DscResource cmdlet. + +The example in this topic demonstrates how to use the File and WindowsFeature +resources. To see all properties that you can use with a resource, insert the +cursor in the resource keyword (for example, File) within your configuration +script in PowerShell ISE, hold down CTRL, and then press SPACEBAR. + +## FIND MORE RESOURCES + +You can download, install, and learn about many other available DSC resources +that have been created by the PowerShell and DSC user community, and by +Microsoft. Visit the [PowerShell Gallery](https://www.powershellgallery.com/) +to browse and learn about available DSC resources. + +## SEE ALSO + +[PowerShell Desired State Configuration Overview](/powershell/dsc/overview) + +[Built-In PowerShell Desired State Configuration Resources](/powershell/dsc/builtinresource) + +[Build Custom PowerShell Desired State Configuration Resources](/powershell/dsc/authoringResource) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_dsclogresource.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_dsclogresource.md index d36402cd23c9..2c3c38df824b 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_dsclogresource.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_dsclogresource.md @@ -7,19 +7,12 @@ title: about_DSCLogResource --- # about_DSCLogResource -``` -TOPIC - about_DSCLogResource - -SHORT DESCRIPTION - Provides a brief introduction to the Windows - PowerShell Desired State Configuration (DSC) Log Resource. - -LONG DESCRIPTION - - ABOUT THE DSC LOG RESOURCE - - HOW TO USE THE DSC LOG RESOURCE - -``` +## SHORT DESCRIPTION + +Provides a brief introduction to the PowerShell Desired State Configuration +(DSC) Log Resource. LONG DESCRIPTION + +## LONG DESCRIPTION + +## HOW TO USE THE DSC LOG RESOURCE diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_hidden.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_hidden.md index 1cb2645eeec1..50b1758d40d5 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_hidden.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_hidden.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,122 +7,148 @@ title: about_Hidden --- # about_Hidden -## TOPIC - about\_Hidden - -## SHORT DESCRIPTION - Describes the Hidden keyword, which hides class members from default Get\-Member results. - -## LONG DESCRIPTION - When you use the Hidden keyword in a script, you hide the members of a class by default. The Hidden keyword can hide properties, methods \(including constructors, events, alias properties, and other member types, including static members, from the default results of the Get\-Member cmdlet, and from IntelliSense and tab completion results. To display members that you have hidden with the Hidden keyword, add the \-Force parameter to a Get\-Member command. - - Hidden members are not displayed by using tab completion or IntelliSense, unless the completion occurs in the class that defines the hidden member. - - A new attribute, System.Management.Automation.HiddenAttribute, has been added, so that C\# code can have the same semantics within Windows PowerShell. - - The Hidden keyword is useful for creating properties and methods within a class that you do not necessarily want other users of the class to see, or readily be able to edit. - - The Hidden keyword has no effect on how you can view or make changes to members of a class. Like all language keywords in Windows PowerShell, Hidden is not case\-sensitive, and hidden members are still public. - - Hidden, along with custom classes, was introduced in Windows PowerShell 5.0. - -## EXAMPLE - The following example shows how to use the Hidden keyword in a class definition. The Car class method, Drive, has a property, rides, that does not need to be viewed or changed \(it merely tallies the number of times that Drive is called on the Car class, a metric that is not important to users of the class; consider, for example, that when you are buying a car, you do not ask the seller on how many drives the car has been taken\). - - Because there is little need for users of the class to change this property, we can hide the property from Get\-Member and automatic completion results by using the Hidden keyword. - - Add the Hidden keyword by entering it on the same statement line as the property and its data type. Although the keyword can be in any order on this line, starting the statement with the Hidden keyword makes it easier for you later to identify all members that you have hidden. - -``` -class Car -{ - # Properties - [String] $Color - [String] $ModelYear - [int] $Distance - - # Method - [int] Drive ([int]$miles) - { - $this.Distance += $miles - $this.rides++ - return $this.Distance - } - - # Hidden property of the Drive method - hidden [int] $rides = 0 -} - -``` - - Now, create a new instance of the Car class, and save it in a variable, $TestCar. - -``` - -$TestCar = [Car]::new() - -``` - - After you create the new instance, pipe the contents of the $TestCar variable to Get\-Member. Observe that the rides property is not among the members listed in the Get\-Member command results. - -``` -PS C:\Windows\system32> $TestCar | Get-Member - - TypeName: Car - -Name MemberType Definition ----- ---------- ---------- -Drive Method int Drive(int miles) -Equals Method bool Equals(System.Object obj) -GetHashCode Method int GetHashCode() -GetType Method type GetType() -ToString Method string ToString() -Color Property string Color {get;set;} -Distance Property int Distance {get;set;} -ModelYear Property string ModelYear {get;set;} - -``` - - Now, try running Get\-Member again, but this time, add the –Force parameter. Note that the results contain the hidden rides property, among other members that are hidden by default. - -``` -PS C:\Windows\system32> $TestCar | Get-Member -Force - - TypeName: Car - -Name MemberType Definition ----- ---------- ---------- -pstypenames CodeProperty System.Collections.ObjectModel.Collection`1… -psadapted MemberSet psadapted {Color, ModelYear, Distance, -psbase MemberSet psbase {Color, ModelYear, Distance,... -psextended MemberSet psextended {} -psobject MemberSet psobject {BaseObject, Members,... -Drive Method int Drive(int miles) -Equals Method bool Equals(System.Object obj) -GetHashCode Method int GetHashCode() -GetType Method type GetType() -get_Color Method string get_Color() -get_Distance Method int get_Distance() -get_ModelYear Method string get_ModelYear() -get_rides Method int get_rides() -set_Color Method void set_Color(string ) -set_Distance Method void set_Distance(int ) -set_ModelYear Method void set_ModelYear(string ) -set_rides Method void set_rides(int ) -ToString Method string ToString() -Color Property string Color {get;set;} -Distance Property int Distance {get;set;} -ModelYear Property string ModelYear {get;set;} -rides Property int rides {get;set;} - -``` - -## SEE ALSO - about\_Classes - - about\_Language\_Keywords - - about\_Wildcards - - Get\-Member +## SHORT DESCRIPTION + +Describes the Hidden keyword, which hides class members from default +Get-Member results. + +## LONG DESCRIPTION + +When you use the Hidden keyword in a script, you hide the members of a class +by default. The Hidden keyword can hide properties, methods (including +constructors, events, alias properties, and other member types, including +static members, from the default results of the Get-Member cmdlet, and from +IntelliSense and tab completion results. To display members that you have +hidden with the Hidden keyword, add the -Force parameter to a Get-Member +command. + +Hidden members are not displayed by using tab completion or IntelliSense, +unless the completion occurs in the class that defines the hidden member. + +A new attribute, System.Management.Automation.HiddenAttribute, has been added, +so that C\# code can have the same semantics within PowerShell. + +The Hidden keyword is useful for creating properties and methods within a +class that you do not necessarily want other users of the class to see, or +readily be able to edit. + +The Hidden keyword has no effect on how you can view or make changes to +members of a class. Like all language keywords in PowerShell, Hidden is not +case-sensitive, and hidden members are still public. + +Hidden, along with custom classes, was introduced in PowerShell 5.0. + +## EXAMPLE + +The following example shows how to use the Hidden keyword in a class +definition. The Car class method, Drive, has a property, rides, that does not +need to be viewed or changed (it merely tallies the number of times that Drive +is called on the Car class, a metric that is not important to users of the +class; consider, for example, that when you are buying a car, you do not ask +the seller on how many drives the car has been taken. + +Because there is little need for users of the class to change this property, +we can hide the property from Get-Member and automatic completion results by +using the Hidden keyword. + +Add the Hidden keyword by entering it on the same statement line as the +property and its data type. Although the keyword can be in any order on this +line, starting the statement with the Hidden keyword makes it easier for you +later to identify all members that you have hidden. + +```powershell +class Car +{ + # Properties + [String] $Color + [String] $ModelYear + [int] $Distance + + # Method + [int] Drive ([int]$miles) + { + $this.Distance += $miles + $this.rides++ + return $this.Distance + } + + # Hidden property of the Drive method + hidden [int] $rides = 0 +} +``` + +Now, create a new instance of the Car class, and save it in a variable, +\$TestCar. + +```powershell +$TestCar = [Car]::new() +``` + +After you create the new instance, pipe the contents of the $TestCar variable +to Get-Member. Observe that the rides property is not among the members listed +in the Get-Member command results. + +```output +PS C:\Windows\system32> $TestCar | Get-Member + + TypeName: Car + +Name MemberType Definition +---- ---------- ---------- +Drive Method int Drive(int miles) +Equals Method bool Equals(System.Object obj) +GetHashCode Method int GetHashCode() +GetType Method type GetType() +ToString Method string ToString() +Color Property string Color {get;set;} +Distance Property int Distance {get;set;} +ModelYear Property string ModelYear {get;set;} + +``` + +Now, try running Get-Member again, but this time, add the –Force parameter. +Note that the results contain the hidden rides property, among other members +that are hidden by default. + +```output +PS C:\Windows\system32> $TestCar | Get-Member -Force + + TypeName: Car + +Name MemberType Definition +---- ---------- ---------- +pstypenames CodeProperty System.Collections.ObjectModel.Collection`1… +psadapted MemberSet psadapted {Color, ModelYear, Distance, +psbase MemberSet psbase {Color, ModelYear, Distance,... +psextended MemberSet psextended {} +psobject MemberSet psobject {BaseObject, Members,... +Drive Method int Drive(int miles) +Equals Method bool Equals(System.Object obj) +GetHashCode Method int GetHashCode() +GetType Method type GetType() +get_Color Method string get_Color() +get_Distance Method int get_Distance() +get_ModelYear Method string get_ModelYear() +get_rides Method int get_rides() +set_Color Method void set_Color(string ) +set_Distance Method void set_Distance(int ) +set_ModelYear Method void set_ModelYear(string ) +set_rides Method void set_rides(int ) +ToString Method string ToString() +Color Property string Color {get;set;} +Distance Property int Distance {get;set;} +ModelYear Property string ModelYear {get;set;} +rides Property int rides {get;set;} + +``` + +## SEE ALSO + +[about_Classes](about_Classes.md) + +[about_Language_Keywords](about_Language_Keywords.md) + +[about_Wildcards](about_Wildcards.md) + +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_logical_operators.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_logical_operators.md index cafeedc3d3f5..7d9280a26f85 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_logical_operators.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_logical_operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,13 +14,13 @@ Describes the operators that connect statements in PowerShell. ## LONG DESCRIPTION -The PowerShell logical operators connect expressions and statements, -allowing you to use a single expression to test for multiple conditions. +The PowerShell logical operators connect expressions and statements, allowing +you to use a single expression to test for multiple conditions. -For example, the following statement uses the and operator and the or -operator to connect three conditional statements. The statement is true -only when the value of $a is greater than the value of $b, and either $a or -$b is less than 20. +For example, the following statement uses the and operator and the or operator +to connect three conditional statements. The statement is true only when the +value of $a is greater than the value of $b, and either $a or $b is less than +20. ```powershell ($a -gt $b) -and (($a -lt 20) -or ($b -lt 20)) @@ -28,38 +28,43 @@ $b is less than 20. PowerShell supports the following logical operators. -|Operator|Description|Example| -|---|---|---| -|`-and`|Logical and. TRUE only when both statements are TRUE.|`(1 -eq 1) -and (1 -eq 2)`
`False`| -|`-or`|Logical or. TRUE when either or both statements are TRUE.|`(1 -eq 1) -or (1 -eq 2)`
`True`| -|`-xor`|Logical exclusive or. TRUE only when one of the statements is TRUE and the other is FALSE.|`(1 -eq 1) -xor (2 -eq 2)`
`False`| -|`-not`|Logical not. Negates the statement that follows it.|`-not (1 -eq 1)`
`False`| -|`!`|Logical not. Negates the statement that follows it. (Same as -not)|`!(1 -eq 1)`
`False`| +|Operator|Description |Example | +|--------|-----------------------------------|--------------------------| +|`-and` |Logical AND. TRUE when both |`(1 -eq 1) -and (1 -eq 2)`| +| |statements are TRUE. |`False` | +|`-or` |Logical OR. TRUE when either |`(1 -eq 1) -or (1 -eq 2)` | +| |statement is TRUE. |`True` | +|`-xor` |Logical EXCLUSIVE OR. TRUE when |`(1 -eq 1) -xor (2 -eq 2) | +| |only one statement is TRUE |`False` | +|`-not` |Logical not. Negates the statement |`-not (1 -eq 1)` | +| |that follows. |`False` | +|`!` |Same as `-not` |`!(1 -eq 1)` | +| | |`False` | Note: - The previous examples also use the equal to comparison operator `-eq`. For - more information, see about_Comparison_Operators. The examples also use - the Boolean values of integers. The integer 0 has a value of FALSE. All - other integers have a value of TRUE. +The previous examples also use the equal to comparison operator `-eq`. For +more information, see +[about_Comparison_Operators](about_Comparison_Operators.md). The examples also +use the Boolean values of integers. The integer 0 has a value of FALSE. All +other integers have a value of TRUE. - The syntax of the logical operators is as follows: +The syntax of the logical operators is as follows: -```powershell +``` {-AND | -OR | -XOR} {! | -NOT} ``` - Statements that use the logical operators return Boolean (TRUE or FALSE) - values. +Statements that use the logical operators return Boolean (TRUE or FALSE) +values. - The PowerShell logical operators evaluate only the statements required to - determine the truth value of the statement. If the left operand in a - statement that contains the and operator is FALSE, the right operand is - not evaluated. If the left operand in a statement that contains the or - statement is TRUE, the right operand is not evaluated. As a result, you - can use these statements in the same way that you would use the If - statement. +The PowerShell logical operators evaluate only the statements required to +determine the truth value of the statement. If the left operand in a statement +that contains the and operator is FALSE, the right operand is not evaluated. +If the left operand in a statement that contains the or statement is TRUE, the +right operand is not evaluated. As a result, you can use these statements in +the same way that you would use the If statement. ## SEE ALSO diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md index 7933f7f0a80e..8b66745260b0 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md @@ -106,22 +106,22 @@ PackageManagement project on GitHub at https://oneget.org. # SEE ALSO -Get-PackageProvider +[Get-PackageProvider](../../PackageManagement/Get-PackageProvider.md) -Get-PackageSource +[Get-PackageSource](../../PackageManagement/Get-PackageSource.md) -Register-PackageSource +[Register-PackageSource](../../PackageManagement/Register-PackageSource.md) -Set-PackageSource +[Set-PackageSource](../../PackageManagement/Set-PackageSource.md) -Unregister-PackageSource +[Unregister-PackageSource](../../PackageManagement/Unregister-PackageSource.md) -Get-Package +[Get-Package](../../PackageManagement/Get-Package.md) -Find-Package +[Find-Package](../../PackageManagement/Find-Package.md) -Install-Package +[Install-Package](../../PackageManagement/Install-Package.md) -Save-Package +[Save-Package](../../PackageManagement/Save-Package.md) -Uninstall-Package +[Uninstall-Package](../../PackageManagement/Uninstall-Package.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md index 660b7694d8d0..ea1e83939845 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,36 +7,49 @@ title: about_PSConsoleHostReadLine --- # about_PSConsoleHostReadLine -## TOPIC - about\_PSConsoleHostReadLine - -## SHORT DESCRIPTION - Explains how to create a customize how Windows PowerShell® reads input at the console prompt. - -## LONG DESCRIPTION - Starting in Windows PowerShell V3, you can write a function named PSConsoleHostReadLine that overrides the default way that console input is processed. - -### EXAMPLES - The following example launches Notepad and gets input from a text File that the user creates: - -``` - function PSConsoleHostReadLine - { -    $inputFile = Join-Path $env:TEMP PSConsoleHostReadLine -    Set-Content $inputFile "PS > " - -    ## Notepad opens. Enter your command in it, save the file, -    ## and then exit. -    notepad $inputFile | Out-Null -    $userInput = Get-Content $inputFile -    $resultingCommand = $userInput.Replace("PS >", "") -    $resultingCommand - } -``` - -### REMARKS - By default, Windows PowerShell reads input from the console in what is known as “Cooked Mode”—in which the Windows console subsystem handles all the keypresses, F7 menus, and other input. When you press Enter or Tab, Windows PowerShell gets the text that you have typed up to that point. There is no way for it to know that you pressed Ctrl\-R, Ctrl\-A, Ctrl\-E, or any other keys before pressing Enter or Tab. In Windows PowerShell version 3, the PSConsoleHostReadLine function solves this issue. When you define a function named PSConsoleHostReadline in the Windows PowerShell console host, Windows PowerShell calls that function instead of the “Cooked Mode” input mechanism. - -### SEE ALSO - about\_Prompts +## SHORT DESCRIPTION + +Explains how to create a customize how PowerShell reads input at the console +prompt. + +## LONG DESCRIPTION + +Starting in Windows PowerShell V3, you can write a function named +PSConsoleHostReadLine that overrides the default way that console input is +processed. + +### EXAMPLES + +The following example launches Notepad and gets input from a text File that +the user creates: + +```powershell +function PSConsoleHostReadLine +{ + $inputFile = Join-Path $env:TEMP PSConsoleHostReadLine + Set-Content $inputFile "PS > " + + # Notepad opens. Enter your command in it, save the file, and then exit. + notepad $inputFile | Out-Null + $userInput = Get-Content $inputFile + $resultingCommand = $userInput.Replace("PS >", "") + $resultingCommand +} +``` + +### REMARKS + +By default, PowerShell reads input from the console in what is known as +"Cooked Mode" -- in which the Windows console subsystem handles all the +keypresses, F7 menus, and other input. When you press Enter or Tab, Windows +PowerShell gets the text that you have typed up to that point. There is no way +for it to know that you pressed Ctrl-R, Ctrl-A, Ctrl-E, or any other keys +before pressing Enter or Tab. In Windows PowerShell version 3, the +PSConsoleHostReadLine function solves this issue. When you define a function +named PSConsoleHostReadline in the Windows PowerShell console host, Windows +PowerShell calls that function instead of the "Cooked Mode" input mechanism. + +### SEE ALSO + +[about_Prompts](about_Prompts.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_psreadline.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_psreadline.md index d0c6cabb5b81..c21c0d7a2995 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_psreadline.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_psreadline.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,649 +7,668 @@ title: about_PSReadline --- # about_PSReadline -``` -TOPIC - about_PSReadline - -SHORT DESCRIPTION - - PSReadline provides an improved command line editing experience in - the Windows PowerShell console. - -LONG DESCRIPTION - - PSReadline, introduced in Windows PowerShell 5.0, provides a powerful - command line editing experience for the Windows PowerShell console. - It provides: - - * Syntax coloring of the command line - * A visual indication of syntax errors - * A better multi-line experience (both editing and history) - * Customizable key bindings - * Cmd and Emacs modes - * Many configuration options - * Bash style completion (optional in Cmd mode, default in Emacs mode) - * Emacs yank/kill ring - * Windows PowerShell token based "word" movement and kill - - The following functions are available in the class [PSConsoleUtilities.PSConsoleReadLine]: - - Cursor movement - --------------- - - EndOfLine (Cmd: Emacs: or ) - - If the input has multiple lines, move to the end of the current line, - or if already at the end of the line, move to the end of the input. - If the input has a single line, move to the end of the input. - - BeginningOfLine (Cmd: Emacs: or ) - - If the input has multiple lines, move to the start of the current line, - or if already at the start of the line, move to the start of the input. - If the input has a single line, move to the start of the input. - - NextLine (Cmd: unbound Emacs: unbound) - - Move the cursor to the next line if the input has multiple lines. - - PreviousLine (Cmd: unbound Emacs: unbound) - - Move the cursor to the previous line if the input has multiple lines. - - ForwardChar (Cmd: Emacs: or ) - - Move the cursor one character to the right. This might move the cursor to the next - line of multi-line input. - - BackwardChar (Cmd: Emacs: or ) - - Move the cursor one character to the left. This might move the cursor to the previous - line of multi-line input. - - ForwardWord (Cmd: unbound Emacs: ) - - Move the cursor forward to the end of the current word, or if between words, - to the end of the next word. You can set word delimiter characters with: - - Set-PSReadlineOption -WordDelimiters - - NextWord (Cmd: Emacs: unbound) - - Move the cursor forward to the start of the next word. You can set word - delimiter characters with: - - Set-PSReadlineOption -WordDelimiters - - BackwardWord (Cmd: Emacs: ) - - Move the cursor back to the start of the current word, or if between words, - the start of the previous word. You can set word delimiter characters with: - - Set-PSReadlineOption -WordDelimiters - - ShellForwardWord (Cmd: unbound Emacs: unbound) - - Like ForwardWord except word boundaries are defined by Windows PowerShell - token boundaries. - - ShellNextWord (Cmd: unbound Emacs: unbound) - - Like NextWord except word boundaries are defined by Windows PowerShell - token boundaries. - - ShellBackwardWord (Cmd: unbound Emacs: unbound) - - Like BackwardWord except word boundaries are defined by Windows PowerShell - token boundaries. - - GotoBrace (Cmd: Emacs: unbound) - - Go to the matching parenthesis, curly brace, or square bracket. - - AddLine (Cmd: Emacs: ) - - The continuation prompt is displayed on the next line and PSReadline waits for - keys to edit the current input. This is useful to enter multi-line input as - a single command even when a single line is complete input by itself. - - Basic editing - ------------- - - CancelLine (Cmd: unbound Emacs: unbound) - - Cancel all editing to the line, leave the line of input on the screen but - return from PSReadline without executing the input. - - RevertLine (Cmd: Emacs: ) - - Reverts all of the input since the last input was accepted and run. - This is equivalent to using the Undo command until there is nothing - left to undo. - - BackwardDeleteChar (Cmd: Emacs: or ) - - Delete the character before the cursor. - - DeleteChar (Cmd: Emacs: ) - - Delete the character under the cursor. - - DeleteCharOrExit (Cmd: unbound Emacs: ) - - Like DeleteChar, unless the line is empty, in which case exit the process. - - AcceptLine (Cmd: Emacs: or ) - - Attempt to execute the current input. If the current input is incomplete (for - example, there is a missing closing parenthesis, bracket, or quote), then the - continuation prompt is displayed on the next line, and PSReadline waits for - keys to edit the current input. - - AcceptAndGetNext (Cmd: unbound Emacs: ) - - Like AcceptLine, but after the line completes, start editing the next line - from history. - - ValidateAndAcceptLine (Cmd: unbound Emacs: unbound) - - Like AcceptLine but performs additional validation including: - - * Checks for additional parse errors - * Validates that command names are all found - * If you are running Windows PowerShell 4.0 or newer, - validates the parameters and arguments - - If there are any errors, the error message is displayed and not accepted nor added - to the history unless you either correct the command line or execute AcceptLine or - ValidateAndAcceptLine again while the error message is displayed. - - BackwardDeleteLine (Cmd: Emacs: unbound) - - Delete the text from the start of the input to the cursor. - - ForwardDeleteLine (Cmd: Emacs: unbound) - - Delete the text from the cursor to the end of the input. - - SelectBackwardChar (Cmd: Emacs: ) - - Adjust the current selection to include the previous character. - - SelectForwardChar (Cmd: Emacs: ) - - Adjust the current selection to include the next character. - - SelectBackwardWord (Cmd: Emacs: ) - - Adjust the current selection to include the previous word. - - SelectForwardWord (Cmd: unbound Emacs: ) - - Adjust the current selection to include the next word using ForwardWord. - - SelectNextWord (Cmd: Emacs: unbound) - - Adjust the current selection to include the next word using NextWord. - - SelectShellForwardWord (Cmd: unbound Emacs: unbound) - - Adjust the current selection to include the next word using ShellForwardWord. - - SelectShellNextWord (Cmd: unbound Emacs: unbound) - - Adjust the current selection to include the next word using ShellNextWord. - - SelectShellBackwardWord (Cmd: unbound Emacs: unbound) - - Adjust the current selection to include the previous word using ShellBackwardWord. - - SelectBackwardsLine (Cmd: Emacs: ) - - Adjust the current selection to include from the cursor to the start of the line. - - SelectLine (Cmd: Emacs: ) - - Adjust the current selection to include from the cursor to the end of the line. - - SelectAll (Cmd: Emacs: unbound) - - Select the entire line. Moves the cursor to the end of the line. - - SelfInsert (Cmd: , , ... Emacs: , , ...) - - Insert the key entered. - - Redo (Cmd: Emacs: unbound) - - Redo an insertion or deletion that was undone by Undo. - - Undo (Cmd: Emacs: ) - - Undo a previous insertion or deletion. - - History - ------- - - ClearHistory (Cmd: Alt+F7 Emacs: unbound) - - Clears history in PSReadline. This does not affect Windows PowerShell - history. - - PreviousHistory (Cmd: Emacs: or ) - - Replace the current input with the previous item from PSReadline history. - - NextHistory (Cmd: Emacs: or ) - - Replace the current input with the next item from PSReadline history. - - ForwardSearchHistory (Cmd: Emacs: ) - - Search forward from the current history line interactively. - - ReverseSearchHistory (Cmd: Emacs: ) - - Search backward from the current history line interactively. - - HistorySearchBackward (Cmd: Emacs: unbound) - - Replace the current input with the previous item from PSReadline history - that matches the characters between the start and the input and the cursor. - - HistorySearchForward (Cmd: Emacs: unbound) - - Replace the current input with the next item from PSReadline history - that matches the characters between the start and the input and the cursor. - - BeginningOfHistory (Cmd: unbound Emacs: ) - - Replace the current input with the last item from PSReadline history. - - EndOfHistory (Cmd: unbound Emacs: >) - - Replace the current input with the last item in PSReadline history, which - is the possibly empty input that was entered before any history commands. - - Tab Completion - -------------- - - TabCompleteNext (Cmd: Emacs: unbound) - - Attempt to complete the text surrounding the cursor with the next - available completion. - - TabCompletePrevious (Cmd: Emacs: unbound) - - Attempt to complete the text surrounding the cursor with the next - previous completion. - - Complete (Cmd: unbound Emacs: ) - - Attempt to perform completion on the text surrounding the cursor. - If there are multiple possible completions, the longest unambiguous - prefix is used for completion. If you are trying to complete the longest - unambiguous completion, a list of possible completions is displayed. - - MenuComplete (Cmd: Emacs: ) - - Attempt to perform completion on the text surrounding the cursor. - If there are multiple possible completions, a list of possible - completions is displayed, and you can select the correct completion - by using the arrow keys, or Tab/Shift+Tab. Escape and Ctrl+G cancel - the menu selection, and revert the line to the state before invoking - MenuComplete. - - PossibleCompletions (Cmd: unbound Emacs: ) - - Display the list of possible completions. - - SetMark (Cmd: unbound Emacs: ) - - Mark the current location of the cursor for use in a subsequent editing command. - - ExchangePointAndMark (Cmd: unbound Emacs: ) - - The cursor is placed at the location of the mark and the mark is moved - to the location of the cursor. - - Kill/Yank - --------- - - Kill and Yank operate on a clipboard in the PSReadline module. There is a ring - buffer called the kill ring - killed text is added to the kill ring up - and yank will copy text from the most recent kill. YankPop cycles through - items in the kill ring. When the kill ring is full, new items replace the - oldest items. A kill operation that is immediately preceded by another kill operation - appends the previous kill, instead of adding a new item or replacing an item - in the kill ring. This is how you can cut a part of a line, for example, with multiple - KillWord operations, then yank them back elsewhere as a single yank. - - KillLine (Cmd: unbound Emacs: ) - - Clear the input from the cursor to the end of the line. The cleared text is placed - in the kill ring. - - BackwardKillLine (Cmd: unbound Emacs: or ) - - Clear the input from the start of the input to the cursor. The cleared text is placed - in the kill ring. - - KillWord (Cmd: unbound Emacs: ) - - Clear the input from the cursor to the end of the current word. If the cursor - is between words, the input is cleared from the cursor to the end of the next word. - The cleared text is placed in the kill ring. - - BackwardKillWord (Cmd: unbound Emacs: ) - - Clear the input from the start of the current word to the cursor. If the cursor - is between words, the input is cleared from the start of the previous word to the - cursor. The cleared text is placed in the kill ring. - - ShellKillWord (Cmd: unbound Emacs: unbound) - - Like KillWord, except word boundaries are defined by Windows PowerShell - token boundaries. - - ShellBackwardKillWord (Cmd: unbound Emacs: unbound) - - Like BackwardKillWord, except word boundaries are defined by Windows PowerShell - token boundaries. - - UnixWordRubout (Cmd: unbound Emacs: ) - - Like BackwardKillWord, except word boundaries are defined by white space. - - KillRegion (Cmd: unbound Emacs: unbound) - - Kill the text between the cursor and the mark. - - Copy (Cmd: Emacs: unbound) - - Copy selected region to the system clipboard. If no region is selected, copy the whole line. - - CopyOrCancelLine (Cmd: Emacs: ) - - Either copy selected text to the clipboard, or if no text is selected, cancel editing - the line with CancelLine. - - Cut (Cmd: Emacs: unbound) - - Delete selected region placing deleted text in the system clipboard. - - Yank (Cmd: unbound Emacs: ) - - Add the most-recently killed text to the input. - - YankPop (Cmd: unbound Emacs: ) - - If the previous operation was Yank or YankPop, replace the previously-yanked - text with the next killed text from the kill ring. - - ClearKillRing (Cmd: unbound Emacs: unbound) - - The contents of the kill ring are cleared. - - Paste (Cmd: Emacs: unbound) - - This is similar to Yank, but uses the system clipboard instead of the kill ring. - - YankLastArg (Cmd: Emacs: , ) - - Insert the last argument from the previous command in history. Repeated operations - replace the last inserted argument with the last argument from the previous - command (so Alt+. Alt+. will insert the last argument of the second to last history - line). - - With an argument, the first time YankLastArg behaves like YankNthArg. A negative - argument on subsequent YankLastArg calls changes the direction while going - through history. For example, if you press Alt+. one too many times, you can type - Alt+- Alt+. to reverse the direction. - - Arguments are based on Windows PowerShell tokens. - - YankNthArg (Cmd: unbound Emacs: ) - - Insert the first argument (not the command name) of the previous command in history. - - With an argument, insert the nth argument where 0 is typically the command. Negative - arguments start from the end. - - Arguments are based on Windows PowerShell tokens. - - Miscellaneous - ------------- - - Abort (Cmd: unbound Emacs: ) - - Abort the current action; for example, stop interactive history search. - Does not cancel input like CancelLine. - - CharacterSearch (Cmd: Emacs: ) - - Read a key and search forwards for that character. With an argument, search - forwards for the nth occurrence of that argument. With a negative argument, - searches backwards. - - CharacterSearchBackward (Cmd: Emacs: ) - - Like CharacterSearch, but searches backwards. With a negative argument, searches - forwards. - - ClearScreen (Cmd: Emacs: ) - - Clears the screen and displays the current prompt and input at the top of the screen. - - DigitArgument (Cmd: unbound Emacs: ,,) - - Used to pass numeric arguments to functions like CharacterSearch or YankNthArg. - Alt+- toggles the argument to be negative/non-negative. To enter 80 '*' characters, - you could type Alt+8 Alt+0 *. - - CaptureScreen (Cmd: unbound Emacs: unbound) - - Copies selected lines to the clipboard in both text and RTF formats. Use up/down - arrow keys to the first line to select, then Shift+UpArrow/Shift+DownArrow to select - multiple lines. After selecting, press Enter to copy the text. Escape/Ctrl+C/Ctrl+G - cancel the operation, so nothing is copied to the clipboard. - - InvokePrompt (Cmd: unbound Emacs: unbound) - - Erases the current prompt and calls the prompt function to redisplay - the prompt. Useful for custom key handlers that change state, such as - changing the current directory. - - WhatIsKey (Cmd: Emacs: ) - - Read a key or chord and display the key binding. - - ShowKeyBindings (Cmd: Emacs: ) - - Show all of the currently-bound keys. - - ScrollDisplayUp (Cmd: Emacs: ) - - Scroll the display up one screen. - - ScrollDisplayUpLine (Cmd: Emacs: ) - - Scroll the display up one line. - - ScrollDisplayDown (Cmd: Emacs: ) - - Scroll the display down one screen. - - ScrollDisplayDownLine (Cmd: Emacs: ) - - Scroll the display down one line. - - ScrollDisplayTop (Cmd: unbound Emacs: ) - - Scroll the display to the top. - - ScrollDisplayToCursor (Cmd: unbound Emacs: ) - - Scroll the display to the cursor. - - Custom Key Bindings - ------------------- - - PSReadline supports custom key bindings using the cmdlet Set-PSReadlineKeyHandler. Most - custom key bindings call one of the above functions, for example: - - Set-PSReadlineKeyHandler -Key UpArrow -Function HistorySearchBackward - - You can bind a ScriptBlock to a key. The ScriptBlock can do virtually anything you want. - Some useful examples include: - - * edit the command line - * opening a new window (e.g. help) - * change directories without changing the command line - - The ScriptBlock is passed two arguments: - - * $key - A [ConsoleKeyInfo] that is the key that triggered the custom binding. If you bind - the same ScriptBlock to multiple keys and need to perform different actions depending - on the key, you can check $key. Many custom bindings ignore this argument. - * $arg - An arbitrary argument. Most often, this would be an integer argument that the user - passes from the key bindings DigitArgument. If your binding doesn't accept arguments, - it's reasonable to ignore this argument. - - Let's take a look at an example that adds a command line to history without executing it. This is - useful when you realize you forgot to do something, but don't want to re-enter the command line - you've already entered. - - Set-PSReadlineKeyHandler -Key Alt+w ` - -BriefDescription SaveInHistory ` - -LongDescription "Save current line in history but do not execute" ` - -ScriptBlock { - param($key, $arg) # The arguments are ignored in this example - - # We need the command line, GetBufferState gives us that (with the cursor position) - $line = $null - $cursor = $null - [PSConsoleUtilities.PSConsoleReadLine]::GetBufferState([ref]$line, [ref]$cursor) - - # AddToHistory saves the line in history, but does not execute the line. - [PSConsoleUtilities.PSConsoleReadLine]::AddToHistory($line) - - # RevertLine is like pressing Escape. - [PSConsoleUtilities.PSConsoleReadLine]::RevertLine() - } - - You can see many more examples in the file SamplePSReadlineProfile.ps1 which is installed in the - PSReadline module folder. - - Most key bindings will want to take advantage of some helper functions for editing the command - line those APIs are documented in the next section. - - Custom Key Binding Support APIs - ------------------------------- - - The following functions are public in PSConsoleUtilities.PSConsoleReadline, but cannot be directly - bound to a key. Most are useful in custom key bindings. - - void AddToHistory(string command) - - Add a command line to history without executing it. - - void ClearKillRing() - - Clear the kill ring. This is mostly used for testing. - - void Delete(int start, int length) - - Delete length characters from start. This operation supports undo and redo. - - void Ding() - - Perform the Ding action based on the user’s preference. - - void GetBufferState([ref] string input, [ref] int cursor) - void GetBufferState([ref] Ast ast, [ref] Token[] tokens, [ref] ParseError[] parseErrors, [ref] int cursor) - - These two functions retrieve useful information about the current state of - the input buffer. The first is more commonly used for simple cases. The - second is used if your binding is doing something more advanced with the Ast. - - IEnumerable[PSConsoleUtilities.KeyHandler] GetKeyHandlers(bool includeBound, bool includeUnbound) - - This function is used by Get-PSReadlineKeyHandler and probably isn't useful in a custom - key binding. - - PSConsoleUtilities.PSConsoleReadlineOptions GetOptions() - - This function is used by Get-PSReadlineOption and probably isn't too useful in a custom - key binding. - - void GetSelectionState([ref] int start, [ref] int length) - - If there is no selection on the command line, -1 is returned in both start and length. - If there is a selection on the command line, the start and length of the selection are returned. - - void Insert(char c) - void Insert(string s) - - Insert a character or string at the cursor. This operation supports undo and redo. - - string ReadLine(runspace remoteRunspace, System.Management.Automation.EngineIntrinsics engineIntrinsics) - - This is the main entry point to PSReadline. It does not support recursion, so is not useful - in a custom key binding. - - void RemoveKeyHandler(string[] key) - - This function is used by Remove-PSReadlineKeyHandler and probably isn't too useful in a - custom key binding. - - void Replace(int start, int length, string replacement) - - Replace some of the input. This operation supports undo and redo. - This is preferred over Delete followed by Insert because it is treated as a single action - for undo. - - void SetCursorPosition(int cursor) - - Move the cursor to the given offset. Cursor movement is not tracked for undo. - - void SetOptions(PSConsoleUtilities.SetPSReadlineOption options) - - This function is a helper method used by the cmdlet Set-PSReadlineOption, but might be - useful to a custom key binding that wants to temporarily change a setting. - - bool TryGetArgAsInt(System.Object arg, [ref] int numericArg, int defaultNumericArg) - - This helper method is used for custom bindings that honor DigitArgument. A typical call - looks like: - - [int]$numericArg = 0 - [PSConsoleUtilities.PSConsoleReadLine]::TryGetArgAsInt($arg, [ref]$numericArg, 1) - -WINDOWS POWERSHELL COMPATIBILITY - - PSReadline requires Windows PowerShell 3.0 or newer, and the console host. It - does not work in Windows PowerShell ISE. - -FEEDBACK - - https://github.com/lzybkr/PSReadline - -CONTRIBUTING TO PSREADLINE - - Feel free to submit a pull request or submit feedback on the PSReadline - GitHub page (https://github.com/lzybkr/PSReadLine). - -SEE ALSO - - PSReadline is heavily influenced by the GNU Readline library: - http://tiswww.case.edu/php/chet/readline/rltop.html - - Get-PSReadlineKeyHandler - Get-PSReadlineOption - Remove-PSReadlineKeyHandler - Set-PSReadlineKeyHandler - Set-PSReadlineOption - + +## SHORT DESCRIPTION + +PSReadline provides an improved command line editing experience in the +PowerShell console. + +## LONG DESCRIPTION + +PSReadline, introduced in PowerShell 5.0, provides a powerful command line +editing experience for the PowerShell console. It provides: + +- Syntax coloring of the command line +- A visual indication of syntax errors +- A better multi-line experience (both editing and history) +- Customizable key bindings +- Cmd and Emacs modes +- Many configuration options +- Bash style completion (optional in Cmd mode, default in Emacs mode) +- Emacs yank/kill ring +- PowerShell token based "word" movement and kill + +The following functions are available in the class +[PSConsoleUtilities.PSConsoleReadLine]: + +## Cursor movement + +- EndOfLine (Cmd: Emacs: or ) + + If the input has multiple lines, move to the end of the current line, or if + already at the end of the line, move to the end of the input. If the input + has a single line, move to the end of the input. + +- BeginningOfLine (Cmd: Emacs: or ) + + If the input has multiple lines, move to the start of the current line, or + if already at the start of the line, move to the start of the input. If the + input has a single line, move to the start of the input. + +- NextLine (Cmd: unbound Emacs: unbound) + + Move the cursor to the next line if the input has multiple lines. + +- PreviousLine (Cmd: unbound Emacs: unbound) + + Move the cursor to the previous line if the input has multiple lines. + +- ForwardChar (Cmd: Emacs: or ) + + Move the cursor one character to the right. This might move the cursor to + the next line of multi-line input. + +- BackwardChar (Cmd: Emacs: or ) + + Move the cursor one character to the left. This might move the cursor to the + previous line of multi-line input. + +- ForwardWord (Cmd: unbound Emacs: ) + + Move the cursor forward to the end of the current word, or if between words, + to the end of the next word. You can set word delimiter characters with: + + ```powershell + Set-PSReadlineOption -WordDelimiters + ``` + +- NextWord (Cmd: Emacs: unbound) + + Move the cursor forward to the start of the next word. You can set word + delimiter characters with: + + ```powershell + Set-PSReadlineOption -WordDelimiters + ``` + +- BackwardWord (Cmd: Emacs: ) + + Move the cursor back to the start of the current word, or if between words, + the start of the previous word. You can set word delimiter characters with: + + ```powershell + Set-PSReadlineOption -WordDelimiters + ``` + +- ShellForwardWord (Cmd: unbound Emacs: unbound) + + Like ForwardWord except word boundaries are defined by PowerShell token + boundaries. + +- ShellNextWord (Cmd: unbound Emacs: unbound) + + Like NextWord except word boundaries are defined by PowerShell token + boundaries. + +- ShellBackwardWord (Cmd: unbound Emacs: unbound) + + Like BackwardWord except word boundaries are defined by PowerShell token + boundaries. + +- GotoBrace (Cmd: Emacs: unbound) + + Go to the matching parenthesis, curly brace, or square bracket. + +- AddLine (Cmd: Emacs: ) + + The continuation prompt is displayed on the next line and PSReadline waits + for keys to edit the current input. This is useful to enter multi-line input + as a single command even when a single line is complete input by itself. + +## Basic editing + +- CancelLine (Cmd: unbound Emacs: unbound) + + Cancel all editing to the line, leave the line of input on the screen but + return from PSReadline without executing the input. + +- RevertLine (Cmd: Emacs: ) + + Reverts all of the input since the last input was accepted and run. This is + equivalent to using the Undo command until there is nothing left to undo. + +- BackwardDeleteChar (Cmd: Emacs: or ) + + Delete the character before the cursor. + +- DeleteChar (Cmd: Emacs: ) + + Delete the character under the cursor. + +- DeleteCharOrExit (Cmd: unbound Emacs: ) + + Like DeleteChar, unless the line is empty, in which case exit the process. + +- AcceptLine (Cmd: Emacs: or ) + + Attempt to execute the current input. If the current input is incomplete + (for example, there is a missing closing parenthesis, bracket, or quote), + then the continuation prompt is displayed on the next line, and PSReadline + waits for keys to edit the current input. + +- AcceptAndGetNext (Cmd: unbound Emacs: ) + + Like AcceptLine, but after the line completes, start editing the next line + from history. + +- ValidateAndAcceptLine (Cmd: unbound Emacs: unbound) + + Like AcceptLine but performs additional validation including: + + * Checks for additional parse errors + * Validates that command names are all found + * If you are running PowerShell 4.0 or newer, validates the parameters and + arguments + + If there are any errors, the error message is displayed and not accepted nor + added to the history unless you either correct the command line or execute + AcceptLine or ValidateAndAcceptLine again while the error message is + displayed. + +- BackwardDeleteLine (Cmd: Emacs: unbound) + + Delete the text from the start of the input to the cursor. + +- ForwardDeleteLine (Cmd: Emacs: unbound) + + Delete the text from the cursor to the end of the input. + +- SelectBackwardChar (Cmd: Emacs: ) + + Adjust the current selection to include the previous character. + +- SelectForwardChar (Cmd: Emacs: ) + + Adjust the current selection to include the next character. + +- SelectBackwardWord (Cmd: Emacs: ) + + Adjust the current selection to include the previous word. + +- SelectForwardWord (Cmd: unbound Emacs: ) + + Adjust the current selection to include the next word using ForwardWord. + +- SelectNextWord (Cmd: Emacs: unbound) + + Adjust the current selection to include the next word using NextWord. + +- SelectShellForwardWord (Cmd: unbound Emacs: unbound) + + Adjust the current selection to include the next word using + ShellForwardWord. + +- SelectShellNextWord (Cmd: unbound Emacs: unbound) + + Adjust the current selection to include the next word using ShellNextWord. + +- SelectShellBackwardWord (Cmd: unbound Emacs: unbound) + + Adjust the current selection to include the previous word using + ShellBackwardWord. + +- SelectBackwardsLine (Cmd: Emacs: ) + + Adjust the current selection to include from the cursor to the start of the + line. + +- SelectLine (Cmd: Emacs: ) + + Adjust the current selection to include from the cursor to the end of the + line. + +- SelectAll (Cmd: Emacs: unbound) + + Select the entire line. Moves the cursor to the end of the line. + +- SelfInsert (Cmd: , , ... Emacs: , , ...) + + Insert the key entered. + +- Redo (Cmd: Emacs: unbound) + + Redo an insertion or deletion that was undone by Undo. + +- Undo (Cmd: Emacs: ) + + Undo a previous insertion or deletion. + +## History + +- ClearHistory (Cmd: Alt+F7 Emacs: unbound) + + Clears history in PSReadline. This does not affect PowerShell + history. + +- PreviousHistory (Cmd: Emacs: or ) + + Replace the current input with the previous item from PSReadline history. + +- NextHistory (Cmd: Emacs: or ) + + Replace the current input with the next item from PSReadline history. + +- ForwardSearchHistory (Cmd: Emacs: ) + + Search forward from the current history line interactively. + +- ReverseSearchHistory (Cmd: Emacs: ) + + Search backward from the current history line interactively. + +- HistorySearchBackward (Cmd: Emacs: unbound) + + Replace the current input with the previous item from PSReadline history + that matches the characters between the start and the input and the cursor. + +- HistorySearchForward (Cmd: Emacs: unbound) + + Replace the current input with the next item from PSReadline history that + matches the characters between the start and the input and the cursor. + +- BeginningOfHistory (Cmd: unbound Emacs: ) + + Replace the current input with the last item from PSReadline history. + +- EndOfHistory (Cmd: unbound Emacs: >) + + Replace the current input with the last item in PSReadline history, which is + the possibly empty input that was entered before any history commands. + +## Tab Completion + +- TabCompleteNext (Cmd: Emacs: unbound) + + Attempt to complete the text surrounding the cursor with the next + available completion. + +- TabCompletePrevious (Cmd: Emacs: unbound) + + Attempt to complete the text surrounding the cursor with the next + previous completion. + +- Complete (Cmd: unbound Emacs: ) + + Attempt to perform completion on the text surrounding the cursor. If there + are multiple possible completions, the longest unambiguous prefix is used + for completion. If you are trying to complete the longest unambiguous + completion, a list of possible completions is displayed. + +- MenuComplete (Cmd: Emacs: ) + + Attempt to perform completion on the text surrounding the cursor. If there + are multiple possible completions, a list of possible completions is + displayed, and you can select the correct completion by using the arrow + keys, or Tab/Shift+Tab. Escape and Ctrl+G cancel the menu selection, and + revert the line to the state before invoking MenuComplete. + +- PossibleCompletions (Cmd: unbound Emacs: ) + + Display the list of possible completions. + +- SetMark (Cmd: unbound Emacs: ) + + Mark the current location of the cursor for use in a subsequent editing + command. + +- ExchangePointAndMark (Cmd: unbound Emacs: ) + + The cursor is placed at the location of the mark and the mark is moved + to the location of the cursor. + +## Kill/Yank + +Kill and Yank operate on a clipboard in the PSReadline module. There is a ring +buffer called the kill ring - killed text is added to the kill ring up and +yank will copy text from the most recent kill. YankPop cycles through items in +the kill ring. When the kill ring is full, new items replace the oldest items. +A kill operation that is immediately preceded by another kill operation +appends the previous kill, instead of adding a new item or replacing an item +in the kill ring. This is how you can cut a part of a line, for example, with +multiple KillWord operations, then yank them back elsewhere as a single yank. + +- KillLine (Cmd: unbound Emacs: ) + + Clear the input from the cursor to the end of the line. The cleared text is + placed in the kill ring. + +- BackwardKillLine (Cmd: unbound Emacs: or ) + + Clear the input from the start of the input to the cursor. The cleared text + is placed in the kill ring. + +- KillWord (Cmd: unbound Emacs: ) + + Clear the input from the cursor to the end of the current word. If the + cursor is between words, the input is cleared from the cursor to the end of + the next word. The cleared text is placed in the kill ring. + +- BackwardKillWord (Cmd: unbound Emacs: ) + + Clear the input from the start of the current word to the cursor. If the + cursor is between words, the input is cleared from the start of the previous + word to the cursor. The cleared text is placed in the kill ring. + +- ShellKillWord (Cmd: unbound Emacs: unbound) + + Like KillWord, except word boundaries are defined by PowerShell + token boundaries. + +- ShellBackwardKillWord (Cmd: unbound Emacs: unbound) + + Like BackwardKillWord, except word boundaries are defined by PowerShell + token boundaries. + +- UnixWordRubout (Cmd: unbound Emacs: ) + + Like BackwardKillWord, except word boundaries are defined by white space. + +- KillRegion (Cmd: unbound Emacs: unbound) + + Kill the text between the cursor and the mark. + +- Copy (Cmd: Emacs: unbound) + + Copy selected region to the system clipboard. If no region is selected, copy + the whole line. + +- CopyOrCancelLine (Cmd: Emacs: ) + + Either copy selected text to the clipboard, or if no text is selected, + cancel editing the line with CancelLine. + +- Cut (Cmd: Emacs: unbound) + + Delete selected region placing deleted text in the system clipboard. + +- Yank (Cmd: unbound Emacs: ) + + Add the most-recently killed text to the input. + +- YankPop (Cmd: unbound Emacs: ) + + If the previous operation was Yank or YankPop, replace the previously-yanked + text with the next killed text from the kill ring. + +- ClearKillRing (Cmd: unbound Emacs: unbound) + + The contents of the kill ring are cleared. + +- Paste (Cmd: Emacs: unbound) + + This is similar to Yank, but uses the system clipboard instead of the kill + ring. + +- YankLastArg (Cmd: Emacs: , ) + + Insert the last argument from the previous command in history. Repeated + operations replace the last inserted argument with the last argument from + the previous command (so Alt+. Alt+. will insert the last argument of the + second to last history line). + + With an argument, the first time YankLastArg behaves like YankNthArg. A + negative argument on subsequent YankLastArg calls changes the direction + while going through history. For example, if you press Alt+. one too many + times, you can type Alt+- Alt+. to reverse the direction. + + Arguments are based on PowerShell tokens. + +- YankNthArg (Cmd: unbound Emacs: ) + + Insert the first argument (not the command name) of the previous command in + history. + + With an argument, insert the nth argument where 0 is typically the command. + Negative arguments start from the end. + + Arguments are based on PowerShell tokens. + +## Miscellaneous + +- Abort (Cmd: unbound Emacs: ) + + Abort the current action; for example, stop interactive history search. Does + not cancel input like CancelLine. + +- CharacterSearch (Cmd: Emacs: ) + + Read a key and search forwards for that character. With an argument, search + forwards for the nth occurrence of that argument. With a negative argument, + searches backwards. + +- CharacterSearchBackward (Cmd: Emacs: ) + + Like CharacterSearch, but searches backwards. With a negative argument, + searches forwards. + +- ClearScreen (Cmd: Emacs: ) + + Clears the screen and displays the current prompt and input at the top of + the screen. + +- DigitArgument (Cmd: unbound Emacs: ,,) + + Used to pass numeric arguments to functions like CharacterSearch or + YankNthArg. Alt+- toggles the argument to be negative/non-negative. To enter + 80 '*' characters, you could type Alt+8 Alt+0 *. + +- CaptureScreen (Cmd: unbound Emacs: unbound) + + Copies selected lines to the clipboard in both text and RTF formats. Use + up/down arrow keys to the first line to select, then + Shift+UpArrow/Shift+DownArrow to select multiple lines. After selecting, + press Enter to copy the text. Escape/Ctrl+C/Ctrl+G cancel the operation, so + nothing is copied to the clipboard. + +- InvokePrompt (Cmd: unbound Emacs: unbound) + + Erases the current prompt and calls the prompt function to redisplay the + prompt. Useful for custom key handlers that change state, such as changing + the current directory. + +- WhatIsKey (Cmd: Emacs: ) + + Read a key or chord and display the key binding. + +- ShowKeyBindings (Cmd: Emacs: ) + + Show all of the currently-bound keys. + +- ScrollDisplayUp (Cmd: Emacs: ) + + Scroll the display up one screen. + +- ScrollDisplayUpLine (Cmd: Emacs: ) + + Scroll the display up one line. + +- ScrollDisplayDown (Cmd: Emacs: ) + + Scroll the display down one screen. + +- ScrollDisplayDownLine (Cmd: Emacs: ) + + Scroll the display down one line. + +- ScrollDisplayTop (Cmd: unbound Emacs: ) + + Scroll the display to the top. + +- ScrollDisplayToCursor (Cmd: unbound Emacs: ) + + Scroll the display to the cursor. + +## Custom Key Bindings + +PSReadline supports custom key bindings using the cmdlet +Set-PSReadlineKeyHandler. Most custom key bindings call one of the above +functions, for example: + +```powershell +Set-PSReadlineKeyHandler -Key UpArrow -Function HistorySearchBackward ``` +You can bind a ScriptBlock to a key. The ScriptBlock can do virtually anything +you want. Some useful examples include: + +* edit the command line +* opening a new window (e.g. help) +* change directories without changing the command line + +The ScriptBlock is passed two arguments: + +* $key - A [ConsoleKeyInfo] that is the key that triggered the custom binding. + If you bind the same ScriptBlock to multiple keys and need to perform + different actions depending on the key, you can check $key. Many custom + bindings ignore this argument. +* $arg - An arbitrary argument. Most often, this would be an integer argument + that the user passes from the key bindings DigitArgument. If your binding + doesn't accept arguments, it's reasonable to ignore this argument. + +Let's take a look at an example that adds a command line to history without +executing it. This is useful when you realize you forgot to do something, but +don't want to re-enter the command line you've already entered. + +```powershell +Set-PSReadlineKeyHandler -Key Alt+w ` + -BriefDescription SaveInHistory ` + -LongDescription "Save current line in history but do not execute" ` + -ScriptBlock { + param($key, $arg) # The arguments are ignored in this example + + # GetBufferState gives us the command line (with the cursor position) + $line = $null + $cursor = $null + [PSConsoleUtilities.PSConsoleReadLine]::GetBufferState([ref]$line, + [ref]$cursor) + + # AddToHistory saves the line in history, but does not execute the line. + [PSConsoleUtilities.PSConsoleReadLine]::AddToHistory($line) + + # RevertLine is like pressing Escape. + [PSConsoleUtilities.PSConsoleReadLine]::RevertLine() +} +``` + +You can see many more examples in the file SamplePSReadlineProfile.ps1 which +is installed in the PSReadline module folder. + +Most key bindings will want to take advantage of some helper functions for +editing the command line those APIs are documented in the next section. + +## Custom Key Binding Support APIs + +The following functions are public in PSConsoleUtilities.PSConsoleReadline, +but cannot be directly bound to a key. Most are useful in custom key bindings. + +- void AddToHistory(string command) + + Add a command line to history without executing it. + +- void ClearKillRing() + + Clear the kill ring. This is mostly used for testing. + +- void Delete(int start, int length) + + Delete length characters from start. This operation supports undo and redo. + +void Ding() + + Perform the Ding action based on the user’s preference. + +- void GetBufferState([ref] string input, [ref] int cursor) +- void GetBufferState([ref] Ast ast, [ref] Token[] tokens, [ref] ParseError[] + parseErrors, [ref] int cursor) + + These two functions retrieve useful information about the current state of + the input buffer. The first is more commonly used for simple cases. The + second is used if your binding is doing something more advanced with the + Ast. + +- IEnumerable[PSConsoleUtilities.KeyHandler] GetKeyHandlers(bool includeBound, + bool includeUnbound) + + This function is used by Get-PSReadlineKeyHandler and probably isn't useful + in a custom key binding. + +- PSConsoleUtilities.PSConsoleReadlineOptions GetOptions() + + This function is used by Get-PSReadlineOption and probably isn't too useful + in a custom key binding. + +- void GetSelectionState([ref] int start, [ref] int length) + + If there is no selection on the command line, -1 is returned in both start + and length. If there is a selection on the command line, the start and + length of the selection are returned. + +- void Insert(char c) +- void Insert(string s) + + Insert a character or string at the cursor. This operation supports undo and + redo. + +- string ReadLine(runspace remoteRunspace, + System.Management.Automation.EngineIntrinsics engineIntrinsics) + + This is the main entry point to PSReadline. It does not support recursion, + so is not useful in a custom key binding. + +- void RemoveKeyHandler(string[] key) + + This function is used by Remove-PSReadlineKeyHandler and probably isn't too + useful in a custom key binding. + +- void Replace(int start, int length, string replacement) + + Replace some of the input. This operation supports undo and redo. This is + preferred over Delete followed by Insert because it is treated as a single + action for undo. + +- void SetCursorPosition(int cursor) + + Move the cursor to the given offset. Cursor movement is not tracked for + undo. + +- void SetOptions(PSConsoleUtilities.SetPSReadlineOption options) + + This function is a helper method used by the cmdlet Set-PSReadlineOption, + but might be useful to a custom key binding that wants to temporarily change + a setting. + +- bool TryGetArgAsInt(System.Object arg, [ref] int numericArg, + int defaultNumericArg) + + This helper method is used for custom bindings that honor DigitArgument. A + typical call looks like: + + ```powershell + [int]$numericArg = 0 + [PSConsoleUtilities.PSConsoleReadLine]::TryGetArgAsInt($arg, + [ref]$numericArg, 1) + ``` +## POWERSHELL COMPATIBILITY + +PSReadline requires PowerShell 3.0 or newer, and the console host. It +does not work in PowerShell ISE. + +## FEEDBACK AND CONTRIBUTING TO PSREADLINE + +Feel free to submit a pull request or submit feedback on the PSReadline +GitHub page (https://github.com/lzybkr/PSReadLine). + +## SEE ALSO + +PSReadline is heavily influenced by the GNU Readline library: +http://tiswww.case.edu/php/chet/readline/rltop.html + +[Get-PSReadlineKeyHandler](../../PSReadline/Get-PSReadlineKeyHandler.md) + +[Get-PSReadlineOption](../../PSReadline/Get-PSReadlineOption.md) + +[Remove-PSReadlineKeyHandler](../../PSReadline/Remove-PSReadlineKeyHandler.md) + +[Set-PSReadlineKeyHandler](../../PSReadline/Set-PSReadlineKeyHandler.md) + +[Set-PSReadlineOption](../../PSReadline/Set-PSReadlineOption.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_scopes.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_scopes.md index caab8e08c0de..92f18f04064d 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_scopes.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_scopes.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-08 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,118 +7,108 @@ title: about_scopes --- # About Scopes -## about_Scopes - about_Scopes -# SHORT DESCRIPTION +## SHORT DESCRIPTION -Explains the concept of scope in Windows PowerShell and shows how to set -and change the scope of elements. +Explains the concept of scope in PowerShell and shows how to set and change +the scope of elements. -# LONG DESCRIPTION +## LONG DESCRIPTION -Windows PowerShell protects access to variables, aliases, functions, and -Windows PowerShell drives (PSDrives) by limiting where they can be read and -changed. By enforcing a few simple rules for scope, Windows PowerShell -helps to ensure that you do not inadvertently change an item that should -not be changed. +PowerShell protects access to variables, aliases, functions, and PowerShell +drives (PSDrives) by limiting where they can be read and changed. By enforcing +a few simple rules for scope, PowerShell helps to ensure that you do not +inadvertently change an item that should not be changed. The following are the basic rules of scope: -- An item you include in a scope is visible in the scope in which it -was created and in any child scope, unless you explicitly make it -private. You can place variables, aliases, functions, or Windows -PowerShell drives in one or more scopes. - -- An item that you created within a scope can be changed only in the -scope in which it was created, unless you explicitly specify a -different scope. - -If you create an item in a scope, and the item shares its name with an -item in a different scope, the original item might be hidden under the -new item. But, it is not overridden or changed. - -Windows PowerShell Scopes - -Scopes in Windows PowerShell have both names and numbers. The named -scopes specify an absolute scope. The numbers are relative and reflect -the relationship between scopes. - -Global: -The scope that is in effect when Windows PowerShell -starts. Variables and functions that are present when -Windows PowerShell starts have been created in the -global scope. This includes automatic variables and -preference variables. This also includes the variables, aliases, -and functions that are in your Windows PowerShell -profiles. - -Local: -The current scope. The local scope can be the global -scope or any other scope. - -Script: -The scope that is created while a script file runs. Only -the commands in the script run in the script scope. To -the commands in a script, the script scope is the local -scope. +- An item you include in a scope is visible in the scope in which it was +created and in any child scope, unless you explicitly make it private. You can +place variables, aliases, functions, or PowerShell drives in one or +more scopes. + +- An item that you created within a scope can be changed only in the scope in +which it was created, unless you explicitly specify a different scope. -Private: -Items in private scope cannot be seen outside of the current -scope. You can use private scope to create a private version -of an item with the same name in another scope. - -Numbered Scopes: -You can refer to scopes by name or by a number that -describes the relative position of one scope to another. -Scope 0 represents the current, or local, scope. Scope 1 -indicates the immediate parent scope. Scope 2 indicates the -parent of the parent scope, and so on. Numbered scopes -are useful if you have created many recursive +If you create an item in a scope, and the item shares its name with an item in +a different scope, the original item might be hidden under the new item. But, +it is not overridden or changed. + +## PowerShell Scopes + +Scopes in PowerShell have both names and numbers. The named scopes specify an +absolute scope. The numbers are relative and reflect the relationship between scopes. -Parent and Child Scopes +- Global: The scope that is in effect when PowerShell starts. Variables and +functions that are present when PowerShell starts have been created in the +global scope. This includes automatic variables and preference variables. This +also includes the variables, aliases, and functions that are in your +PowerShell profiles. + +- Local: The current scope. The local scope can be the global scope or any +other scope. -You can create a new scope by running a script or function, by creating -a session, or by starting a new instance of Windows PowerShell. When you -create a new scope, the result is a parent scope (the original scope) and -a child scope (the scope that you created). +- Script: The scope that is created while a script file runs. Only the +commands in the script run in the script scope. To the commands in a script, +the script scope is the local scope. -In Windows PowerShell, all scopes are child scopes of the global scope, -but you can create many scopes and many recursive scopes. +- Private: Items in private scope cannot be seen outside of the current scope. +You can use private scope to create a private version of an item with the same +name in another scope. + +- Numbered Scopes: You can refer to scopes by name or by a number that describes +the relative position of one scope to another. Scope 0 represents the current, +or local, scope. Scope 1 indicates the immediate parent scope. Scope 2 +indicates the parent of the parent scope, and so on. Numbered scopes are +useful if you have created many recursive scopes. + +## Parent and Child Scopes + +You can create a new scope by running a script or function, by creating a +session, or by starting a new instance of PowerShell. When you create a new +scope, the result is a parent scope (the original scope) and a child scope +(the scope that you created). + +In PowerShell, all scopes are child scopes of the global scope, but you can +create many scopes and many recursive scopes. Unless you explicitly make the items private, the items in the parent scope -are available to the child scope. However, items that you create and change -in the child scope do not affect the parent scope, unless you explicitly -specify the scope when you create the items. +are available to the child scope. However, items that you create and change in +the child scope do not affect the parent scope, unless you explicitly specify +the scope when you create the items. -Inheritance +## Inheritance -A child scope does not inherit the variables, aliases, and functions from -the parent scope. Unless an item is private, the child scope can view the -items in the parent scope. And, it can change the items by explicitly -specifying the parent scope, but the items are not part of the child scope. +A child scope does not inherit the variables, aliases, and functions from the +parent scope. Unless an item is private, the child scope can view the items in +the parent scope. And, it can change the items by explicitly specifying the +parent scope, but the items are not part of the child scope. -However, a child scope is created with a set of items. Typically, it -includes all the aliases that have the AllScope option. This option is -discussed later in this topic. It includes all the variables that have the -AllScope option, plus some variables that can be used to customize the -scope, such as MaximumFunctionCount. +However, a child scope is created with a set of items. Typically, it includes +all the aliases that have the AllScope option. This option is discussed later +in this topic. It includes all the variables that have the AllScope option, +plus some variables that can be used to customize the scope, such as +MaximumFunctionCount. To find the items in a particular scope, use the Scope parameter of Get-Variable or Get-Alias. For example, to get all the variables in the local scope, type: +```powershell get-variable -scope local +``` To get all the variables in the global scope, type: +```powershell get-variable -scope global +``` -Scope Modifiers +## Scope Modifiers To specify the scope of a new variable, alias, or function, use a scope modifier. The valid values of a modifier are Global, Local, Private, and @@ -126,362 +116,411 @@ Script. The syntax for a scope modifier in a variable is: +``` $[]: = +``` The syntax for a scope modifier in a function is: +``` function []: {} +``` The default scope for scripts is the script scope. The default scope for functions and aliases is the local scope, even if they are defined in a script. -The following command, which does not use a scope modifier, creates a -variable in the current or local scope: +The following command, which does not use a scope modifier, creates a variable +in the current or local scope: +```powershell $a = "one" +``` To create the same variable in the global scope, use the Global scope modifier: +```powershell $global:a = "one" +``` -To create the same variable in the script scope, use the script -scope modifier: +To create the same variable in the script scope, use the script scope +modifier: +```powershell $script:a = "one" +``` You can also use a scope modifier in functions. The following function definition creates a function in the global scope: -function global:Hello -{ -write-host "Hello, World" +```powershell +function global:Hello { + write-host "Hello, World" } +``` -You can also use scope modifiers to refer to a variable in a different -scope. The following command refers to the $test variable, first in the -local scope and then in the global scope: +You can also use scope modifiers to refer to a variable in a different scope. +The following command refers to the $test variable, first in the local scope +and then in the global scope: +```powershell $test - $global:test +``` -The Using scope modifier +### The Using scope modifier -Using is a special scope modifier that identifies a local -variable in a remote command. By default, variables in remote -commands are assumed to be defined in the remote session. +Using is a special scope modifier that identifies a local variable in a remote +command. By default, variables in remote commands are assumed to be defined in +the remote session. -The Using scope modifier is introduced in Windows PowerShell 3.0. +The Using scope modifier is introduced in PowerShell 3.0. -For more information, see about_Remote_Variables. +For more information, see [about_Remote_Variables](about_Remote_Variables.md). -The AllScope Option +### The AllScope Option Variables and aliases have an Option property that can take a value of AllScope. Items that have the AllScope property become part of any child scopes that you create, although they are not retroactively inherited by parent scopes. -An item that has the AllScope property is visible in the child scope, and -it is part of that scope. Changes to the item in any scope affect all the -scopes in which the variable is defined. +An item that has the AllScope property is visible in the child scope, and it +is part of that scope. Changes to the item in any scope affect all the scopes +in which the variable is defined. -Managing Scope +### Managing Scope -Several cmdlets have a Scope parameter that lets you get or set (create -and change) items in a particular scope. Use the following command to find -all the cmdlets in your session that have a Scope parameter: +Several cmdlets have a Scope parameter that lets you get or set (create and +change) items in a particular scope. Use the following command to find all the +cmdlets in your session that have a Scope parameter: +```powershell get-help * -parameter scope +``` -To find the variables that are visible in a particular scope, use the -Scope parameter of Get-Variable. The visible parameters include global -parameters, parameters in the parent scope, and parameters in the current -scope. +To find the variables that are visible in a particular scope, use the Scope +parameter of Get-Variable. The visible parameters include global parameters, +parameters in the parent scope, and parameters in the current scope. -For example, the following command gets the variables that are visible in -the local scope: +For example, the following command gets the variables that are visible in the +local scope: +```powershell get-variable -scope local +``` -To create a variable in a particular scope, use a scope modifier or the -Scope parameter of Set-Variable. The following command creates a variable -in the global scope: +To create a variable in a particular scope, use a scope modifier or the Scope +parameter of Set-Variable. The following command creates a variable in the +global scope: +```powershell new-variable -scope global -name a -value "One" +``` -You can also use the Scope parameter of the New-Alias, Set-Alias, or -Get-Alias cmdlets to specify the scope. The following command creates an -alias in the global scope: +You can also use the Scope parameter of the New-Alias, Set-Alias, or Get-Alias +cmdlets to specify the scope. The following command creates an alias in the +global scope: +```powershell new-alias -scope global -name np -value Notepad.exe +``` -To get the functions in a particular scope, use the Get-Item cmdlet when -you are in the scope. The Get-Item cmdlet does not have a scope parameter. +To get the functions in a particular scope, use the Get-Item cmdlet when you +are in the scope. The Get-Item cmdlet does not have a scope parameter. -Using Dot Source Notation with Scope +### Using Dot Source Notation with Scope Scripts and functions follow all the rules of scope. You create them in a particular scope, and they affect only that scope unless you use a cmdlet parameter or a scope modifier to change that scope. -But, you can add a script or function to the current scope by using dot -source notation. Then, when a script runs in the current scope, any -functions, aliases, and variables that the script creates are available -in the current scope. +But, you can add a script or function to the current scope by using dot source +notation. Then, when a script runs in the current scope, any functions, +aliases, and variables that the script creates are available in the current +scope. -To add a function to the current scope, type a dot (.) and a space before -the path and name of the function in the function call. +To add a function to the current scope, type a dot (.) and a space before the +path and name of the function in the function call. -For example, to run the Sample.ps1 script from the C:\Scripts directory in -the script scope (the default for scripts), use the following command: +For example, to run the Sample.ps1 script from the C:\Scripts directory in the +script scope (the default for scripts), use the following command: +```powershell c:\scripts\sample.ps1 +``` To run the Sample.ps1 script in the local scope, use the following command: +```powershell . c:\scripts.sample.ps1 +``` When you use the call operator (&) to run a function or script, it is not added to the current scope. The following example uses the call operator: +```powershell & c:\scripts.sample.ps1 +``` + +Any aliases, functions, or variables that the Sample.ps1 script creates are +not available in the current scope. + +### Restricting Without Scope + +A few PowerShell concepts are similar to scope or interact with scope. These +concepts may be confused with scope or the behavior of scope. + +Sessions, modules, and nested prompts are self-contained environments, but +they are not child scopes of the global scope in the session. + +- Sessions: A session is an environment in which PowerShell runs. When you + create a session on a remote computer, PowerShell establishes a + persistent connection to the remote computer. The persistent connection lets + you use the session for multiple related commands. + + Because a session is a contained environment, it has its own scope, but a + session is not a child scope of the session in which is was created. The + session starts with its own global scope. This scope is independent of the + global scope of the session. You can create child scopes in the session. For + example, you can run a script to create a child scope in a session. + +- Modules: You can use a PowerShell module to share and deliver PowerShell + tools. A module is a unit that can contain cmdlets, scripts, functions, + variables, aliases, and other useful items. Unless explicitly defined, the + items in a module are not accessible outside the module. Therefore, you can + add the module to your session and use the public items without worrying that + the other items might override the cmdlets, scripts, functions, and other + items in your session. -Any aliases, functions, or variables that the Sample.ps1 script creates -are not available in the current scope. - -Restricting Without Scope - -A few Windows PowerShell concepts are similar to scope or interact with -scope. These concepts may be confused with scope or the behavior of scope. - -Sessions, modules, and nested prompts are self-contained environments, -but they are not child scopes of the global scope in the session. - -Sessions: -A session is an environment in which Windows PowerShell runs. -When you create a session on a remote computer, Windows -PowerShell establishes a persistent connection to the remote -computer. The persistent connection lets you use the session for -multiple related commands. - -Because a session is a contained environment, it has its own -scope, but a session is not a child scope of the session in -which is was created. The session starts with its own global -scope. This scope is independent of the global scope of the session. -You can create child scopes in the session. For example, you can run -a script to create a child scope in a session. - -Modules: -You can use a Windows PowerShell module to share and deliver -Windows PowerShell tools. A module is a unit that can contain -cmdlets, scripts, functions, variables, aliases, and other useful -items. Unless explicitly defined, the items in a module are not -accessible outside the module. Therefore, you can add the module to -your session and use the public items without worrying that the -other items might override the cmdlets, scripts, functions, and other -items in your session. - -The privacy of a module behaves like a scope, but adding a module -to a session does not change the scope. And, the module does not have -its own scope, although the scripts in the module, like all Windows -PowerShell scripts, do have their own scope. - -Nested Prompts: -Similarly, nested prompts do not have their own scope. When you enter -a nested prompt, the nested prompt is a subset of the environment. -But, you remain within the local scope. - -Scripts do have their own scope. If you are debugging a script, and -you reach a breakpoint in the script, you enter the script scope. - -Private Option: -Aliases and variables have an Option property that can take a value -of Private. Items that have the Private option can be viewed and -changed in the scope in which they are created, but they cannot be -viewed or changed outside that scope. - -For example, if you create a variable that has a private option in the -global scope and then run a script, Get-Variable commands in the script -do not display the private variable. This occurs even if you use -the global scope modifier. - -You can use the Option parameter of the New-Variable, Set-Variable, -New-Alias, and Set-Alias cmdlets to set the value of the Option -property to Private. - -Visibility: -The Visibility property of a variable or alias determines whether you -can see the item outside the container, such as a module, in which it -was created. Visibility is designed for containers in the same way that -the Private value of the Option property is designed for scopes. - -The Visibility property takes the Public and Private values. Items -that have private visibility can be viewed and changed only in the -container in which they were created. If the container is added or -imported, the items that have private visibility cannot be viewed or -changed. - -Because Visibility is designed for containers, it works differently -in a scope. If you create an item that has private visibility in the -global scope, you cannot view or change the item in any scope. If you -try to view or change the value of a variable that has private -visibility, Windows PowerShell returns an error message. - -You can use the New-Variable and Set-Variable cmdlets to create a -variable that has private visibility. - -# EXAMPLES - - -Example 1: Change a Variable Value Only in a Script - -The following command changes the value of the $ConfirmPreference -variable in a script. The change does not affect the global scope. - -First, to display the value of the $ConfirmPreference variable in -the local scope, use the following command: + The privacy of a module behaves like a scope, but adding a module to a session + does not change the scope. And, the module does not have its own scope, + although the scripts in the module, like all PowerShell scripts, do + have their own scope. +- Nested Prompts: Similarly, nested prompts do not have their own scope. When + you enter a nested prompt, the nested prompt is a subset of the environment. + But, you remain within the local scope. + + Scripts do have their own scope. If you are debugging a script, and you reach + a breakpoint in the script, you enter the script scope. + +- Private Option: Aliases and variables have an Option property that can take a + value of Private. Items that have the Private option can be viewed and changed + in the scope in which they are created, but they cannot be viewed or changed + outside that scope. + + For example, if you create a variable that has a private option in the global + scope and then run a script, Get-Variable commands in the script do not + display the private variable. This occurs even if you use the global scope + modifier. + + You can use the Option parameter of the New-Variable, Set-Variable, New-Alias, + and Set-Alias cmdlets to set the value of the Option property to Private. + +- Visibility: The Visibility property of a variable or alias determines whether + you can see the item outside the container, such as a module, in which it was + created. Visibility is designed for containers in the same way that the + Private value of the Option property is designed for scopes. + + The Visibility property takes the Public and Private values. Items that have + private visibility can be viewed and changed only in the container in which + they were created. If the container is added or imported, the items that have + private visibility cannot be viewed or changed. + + Because Visibility is designed for containers, it works differently in a + scope. If you create an item that has private visibility in the global scope, + you cannot view or change the item in any scope. If you try to view or change + the value of a variable that has private visibility, PowerShell returns an + error message. + + You can use the New-Variable and Set-Variable cmdlets to create a variable + that has private visibility. + +## EXAMPLES + +### Example 1: Change a Variable Value Only in a Script + +The following command changes the value of the \$ConfirmPreference variable in +a script. The change does not affect the global scope. + +First, to display the value of the \$ConfirmPreference variable in the local +scope, use the following command: + +``` C:\PS> $ConfirmPreference High +``` Create a Scope.ps1 script that contains the following commands: +```powershell $ConfirmPreference = "Low" "The value of `$ConfirmPreference is $ConfirmPreference." +``` -Run the script. The script changes the value of the $ConfirmPreference -variable and then reports its value in the script scope. The output -should resemble the following output: +Run the script. The script changes the value of the \$ConfirmPreference +variable and then reports its value in the script scope. The output should +resemble the following output: +```output The value of $ConfirmPreference is Low. +``` -Next, test the current value of the $ConfirmPreference variable in the -current scope. +Next, test the current value of the \$ConfirmPreference variable in the current +scope. +``` C:\PS> $ConfirmPreference High +``` -This example shows that changes to the value of a variable in the script -scope do not affect the value of that variable in the parent scope. +This example shows that changes to the value of a variable in the script scope +do not affect the value of that variable in the parent scope. -Example 2: View a Variable Value in Different Scopes +### Example 2: View a Variable Value in Different Scopes -You can use scope modifiers to view the value of a variable in the local -scope and in a parent scope. +You can use scope modifiers to view the value of a variable in the local scope +and in a parent scope. First, define a $test variable in the global scope. +```powershell $test = "Global" +``` -Next, create a Sample.ps1 script that defines the $test -variable. In the script, use a scope modifier to refer -to either the global or local versions of the $test variable. +Next, create a Sample.ps1 script that defines the \$test variable. In the +script, use a scope modifier to refer to either the global or local versions +of the \$test variable. -In Sample.ps1 +In Sample.ps1: +```powershell $test = "Local" "The local value of `$test is $test." "The global value of `$test is $global:test." +``` When you run Sample.ps1, the output should resemble the following output: +```output The local value of $test is Local. The global value of $test is Global. +``` -When the script is complete, only the global value of $test is defined -in the session. +When the script is complete, only the global value of \$test is defined in the +session. +``` C:\PS> $test Global +``` -Example 3: Change the Value of a Variable in a Parent Scope +### Example 3: Change the Value of a Variable in a Parent Scope -Unless you protect an item by using the Private option or another -method, you can view and change the value of a variable in a parent -scope. +Unless you protect an item by using the Private option or another method, you +can view and change the value of a variable in a parent scope. -First, define a $test variable in the global scope. +First, define a \$test variable in the global scope. +```powershell $test = "Global" +``` -Next, create a Sample.ps1 script that defines the $test variable. In the -script, use a scope modifier to refer to either the global or local -versions of the $test variable. +Next, create a Sample.ps1 script that defines the \$test variable. In the +script, use a scope modifier to refer to either the global or local versions +of the \$test variable. -In Sample.ps1 +In Sample.ps1: +```powershell $global:test = "Local" "The global value of `$test is $global:test." +``` -When the script is complete, the global value of $test is changed. +When the script is complete, the global value of \$test is changed. +``` C:\PS> $test Local +``` -Example 4: Creating a Private Variable +### Example 4: Creating a Private Variable -A private variable is a variable that has an Option property that has a -value of Private. Private variables are inherited by the child scope, but -they can be viewed or changed only in the scope in which they were -created. +A private variable is a variable that has an Option property that has a value +of Private. Private variables are inherited by the child scope, but they can +be viewed or changed only in the scope in which they were created. -The following command creates a private variable called $ptest in the -local scope. +The following command creates a private variable called \$ptest in the local +scope. +```powershell New-Variable -Name ptest -Value 1 -Option private +``` -You can display and change the value of $ptest in the local scope. +You can display and change the value of \$ptest in the local scope. +``` C:\PS> $ptest -# 1 +1 C:\PS> $ptest = 2 C:\PS> $ptest -# 2 - +2 +``` -Next, create a Sample.ps1 script that contains the following commands. -The command tries to display and change the value of $ptest. +Next, create a Sample.ps1 script that contains the following commands. The +command tries to display and change the value of \$ptest. -In Sample.ps1 +In Sample.ps1: +```powershell "The value of `$Ptest is $Ptest." "The value of `$Ptest is $global:Ptest." +``` -Because the $ptest variable is not visible in the script scope, the -output is empty. +Because the $ptest variable is not visible in the script scope, the output is +empty. +```powershell "The value of $Ptest is ." "The value of $Ptest is ." +``` -Example 5: Using a Local Variable in a Remote Command +### Example 5: Using a Local Variable in a Remote Command -To indicate that a variable in a remote command was created in the -local session, use the Using scope modifier. By default, Windows -PowerShell assumes that the variables in remote commands were created -in the remote session. +To indicate that a variable in a remote command was created in the local +session, use the Using scope modifier. By default, PowerShell assumes +that the variables in remote commands were created in the remote session. The syntax is: + +``` $Using: +``` -For example, the following commands create a $Cred variable in the -local session and then use the $Cred variable in a remote command: +For example, the following commands create a $Cred variable in the local +session and then use the $Cred variable in a remote command: +```powershell $Cred = Get-Credential Invoke-Command $s {Remove-Item .\Test*.ps1 -Credential $Using:Cred} +``` -The Using scope was introduced in Windows PowerShell 3.0. - -In Windows PowerShell 2.0, to indicate that a variable was created in -the local session, use the following command format. +The Using scope was introduced in PowerShell 3.0. In PowerShell 2.0, to +indicate that a variable was created in the local session, use the following +command format. +```powershell $Cred = Get-Credential -Invoke-Command $s {param($c) Remove-Item .\Test*.ps1 -Credential $c} -ArgumentList $Cred +Invoke-Command $s { + param($c) + Remove-Item .\Test*.ps1 -Credential $c +} -ArgumentList $Cred +``` -# SEE ALSO +## SEE ALSO [about_Variables](about_Variables.md) @@ -490,4 +529,3 @@ Invoke-Command $s {param($c) Remove-Item .\Test*.ps1 -Credential $c} -ArgumentLi [about_Functions](about_Functions.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_type_accelerators.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_type_accelerators.md deleted file mode 100644 index c74bfdb2b108..000000000000 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_type_accelerators.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_Type_Accelerators ---- - -# about_Type_Accelerators -Insert introduction here. - -## Section Heading - Insert section body here. - -### Subsection Heading - Insert subsection body here. - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_windows_powershell_5.0.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_windows_powershell_5.0.md index 695415d38e56..7fc47e85d48f 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_windows_powershell_5.0.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_windows_powershell_5.0.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,282 +7,338 @@ title: about_Windows_PowerShell_5.0 --- # about_Windows_PowerShell_5.0 -``` -TOPIC - about_Windows_PowerShell_5.0 - -SHORT DESCRIPTION - Describes new features that are included in - Windows PowerShell 5.0. - -LONG DESCRIPTION - - Windows PowerShell 5.0 includes significant new features that extend its - use, improve its usability, and allow you to control and manage Windows-based - environments more easily and comprehensively. - - Windows PowerShell 5.0 is backward-compatible. Cmdlets, providers, modules, - snap-ins, scripts, functions, and profiles that were designed for Windows - PowerShell 4.0, Windows PowerShell 3.0, and Windows PowerShell 2.0 generally - work in Windows PowerShell 5.0 without changes. - - Windows PowerShell 5.0 is installed by default on Windows Server Technical - Preview and Windows Technical Preview. To install Windows PowerShell 5.0 on - Windows Server 2012 R2, Windows 8.1 Enterprise, or Windows 8.1 Pro, download - and install Windows Management Framework 5.0 Preview. - (http://www.microsoft.com/download/details.aspx?id=44070) - Be sure to read the download details, and meet all system requirements, - before you install Windows Management Framework 5.0 Preview. - - You can also read about changes to Windows PowerShell 5.0 in the Microsoft - TechNet topic, "What's New in Windows PowerShell." - (http://go.microsoft.com/fwlink/?LinkID=512808) - -NEW FEATURES - - New features in Windows PowerShell - - -- Starting in Windows PowerShell 5.0, you can develop by using classes, - by using formal syntax and semantics that are similar to other object-oriented - programming languages. Class, Enum, and other keywords have been added to the - Windows PowerShell language to support the new feature. For more information - about working with classes, see about_Classes. - -- In collaboration with Microsoft Research, a new cmdlet, ConvertFrom-String, - has been added. ConvertFrom-String lets you extract and parse structured - objects from the content of text strings. For more information, see - ConvertFrom-String. - -- A new module, Microsoft.PowerShell.Archive, includes cmdlets that let you - compress files and folders into archive (also known as ZIP) files, extract - files from existing ZIP files, and update ZIP files with newer versions - of files compressed within them. - -- A new module, OneGet, lets you discover and install software packages on - the Internet. The OneGet module is a manager or multiplexer of existing - package managers (also called package providers) to unify Windows package - management with a single Windows PowerShell interface. - -- A new module, PowerShellGet, lets you find, install, publish, and update - modules and DSC resources on the PowerShell Resource Gallery, or on an internal - module repository that you can set up by running the Register-PSRepository cmdlet. - -- New-Item, Remove-Item, and Get-ChildItem have been enhanced to support - creating and managing symbolic links. The ItemType parameter for New-Item - accepts a new value, SymbolicLink. Now you can create symbolic links in a - single line by running the New-Item cmdlet. - -- Windows PowerShell transcription has been improved to apply to all hosting - applications (such as Windows PowerShell ISE) in addition to the console host - (powershell.exe). Transcription options (including enabling a system-wide - transcript) can be configured by enabling the Turn on PowerShell Transcription - Group Policy setting, found in - Administrative Templates/Windows Components/Windows PowerShell. - -- A new detailed script tracing feature lets you enable detailed tracking and - analysis of Windows PowerShell scripting use on a system. After you enable - detailed script tracing, Windows PowerShell logs all script blocks to the - Event Tracing for Windows (ETW) event log, Microsoft-Windows-PowerShell/Operational. - -- Starting in Windows PowerShell 5.0, new Cryptographic Message Syntax cmdlets - support encryption and decryption of content by using the IETF standard format - for cryptographically protecting messages as documented by [RFC5652](https://tools.ietf.org/html/rfc5652). The Get-CmsMessage, Protect-CmsMessage, - and Unprotect-CmsMessage cmdlets have been added to the - Microsoft.PowerShell.Security module. - -- New cmdlets in the Microsoft.PowerShell.Utility module, Get-Runspace, - Debug-Runspace, Get-RunspaceDebug, Enable-RunspaceDebug, and - Disable-RunspaceDebug, let you set debug options on a runspace, and start - and stop debugging on a runspace. For debugging arbitrary runspaces—that is, - runspaces that are not the default runspace for a Windows PowerShell console - or Windows PowerShell ISE session—Windows PowerShell lets you set breakpoints - in a script, and have added breakpoints stop the script from running until - you can attach a debugger to debug the runspace script. Nested debugging - support for arbitrary runspaces has been added to the Windows PowerShell - script debugger for runspaces. - -- New cmdlets Enter-PSHostProcess and Exit-PSHostProcess let you debug - Windows PowerShell scripts in processes separate from the current process - that is running in the Windows PowerShell console. Run Enter-PSHostProcess - to enter, or attach to, a specific process ID, and then run Get-Runspace to - return the active runspaces within the process. Run Exit-PSHostProcess to - detach from the process when you are finished debugging the script within - the process. - -- A new Wait-Debugger cmdlet has been added to the Microsoft.PowerShell.Utility - module. You can run Wait-Debugger to stop a script in the debugger before - running the next statement in the script. - -- The Windows PowerShell Workflow debugger now supports command or tab completion, - and you can debug nested workflow functions. You can now press Ctrl+Break to - enter the debugger in a running script, in both local and remote sessions, and - in a workflow script. - -- A Debug-Job cmdlet has been added to the Microsoft.PowerShell.Core module to - debug running job scripts for Windows PowerShell Workflow, background, and - jobs running in remote sessions. - -- A new state, AtBreakpoint, has been added for Windows PowerShell jobs. The - AtBreakpoint state applies when a job is running a script that includes set - breakpoints, and the script has hit a breakpoint. When a job is stopped at a - debug breakpoint, you must debug the job by running the Debug-Job cmdlet. - -- Windows PowerShell 5.0 implements support for multiple versions of a single - Windows PowerShell module in the same folder in $PSModulePath. A - RequiredVersion property has been added to the ModuleSpecification class to - help you get the desired version of a module; this property is - mutually-exclusive with the ModuleVersion property. RequiredVersion is now - supported as part of the value of the FullyQualifiedName parameter of the - Get-Module, Import-Module, and Remove-Module cmdlets. - -- You can now perform module version validation by running the - Test-ModuleManifest cmdlet. - -- Results of the Get-Command cmdlet now display a Version column; a new Version - property has been added to the CommandInfo class. Get-Command shows commands - from multiple versions of the same module. The Version property is also part - of derived classes of CmdletInfo: CmdletInfo and ApplicationInfo. - -- A new Get-ItemPropertyValue cmdlet lets you get the value of a property without - using dot notation. For example, in older releases of Windows PowerShell, you - can run the following command to get the value of the Application Base property - of the PowerShellEngine registry key: (Get-ItemProperty -Path HKLM:\SOFTWARE\ - Microsoft\PowerShell\3\PowerShellEngine -Name ApplicationBase).ApplicationBase. - Starting in Windows PowerShell 5.0, you can run Get-ItemPropertyValue -Path HKLM: - \SOFTWARE\Microsoft\PowerShell\3\PowerShellEngine -Name ApplicationBase. - -- A new NetworkSwitch module contains cmdlets that enable you to apply switch, - virtual LAN (VLAN), and basic Layer 2 network switch port configuration to - Windows Server 2012 R2 (and later releases) logo-certified network switches. - -- The FullyQualifiedName parameter has been added to Import-Module and - Remove-Module cmdlets, to support storing multiple versions of a single module. - -- Save-Help, Update-Help, Import-PSSession, Export-PSSession, and Get-Command - have a new parameter, FullyQualifiedModule, of type ModuleSpecification. Add - this parameter to specify a module by its fully qualified name. - -- The value of $PSVersionTable.PSVersion has been updated to 5.0. - - New features in Windows PowerShell Desired State Configuration - - -- Windows PowerShell language enhancements let you define Windows PowerShell - Desired State Configuration (DSC) resources by using classes. - Import-DscResource is now a true dynamic keyword; Windows PowerShell parses - the specified module’s root module, searching for classes that contain the - DscResource attribute. You can now use classes to define DSC resources, - in which neither a MOF file nor a DSCResource subfolder in the module - folder is required. A Windows PowerShell module file can contain multiple - DSC resource classes. - -- A new parameter, ThrottleLimit, has been added to the following cmdlets in - the PSDesiredStateConfiguration module. Add the ThrottleLimit parameter - to specify the number of target computers or devices on which you want the - command to work at the same time. - -- Get-DscConfiguration - -- Get-DscConfigurationStatus - -- Get-DscLocalConfigurationManager - -- Restore-DscConfiguration - -- Test-DscConfiguration - -- Compare-DscConfiguration - -- Publish-DscConfiguration - -- Set-DscLocalConfigurationManager - -- Start-DscConfiguration - -- Update-DscConfiguration - -- With centralized DSC error reporting, rich error information is not only - logged in the event log, but it can be sent to a central location for later - analysis. You can use this central location to store DSC configuration errors - that have occurred for any server in their environment. After the report - server is defined in the meta-configuration, all errors are sent to the - report server, and then stored in a database. You can set up this functionality - regardless of whether or not a target node is configured to pull configurations - from a pull server. - -- Improvements to Windows PowerShell ISE ease DSC resource authoring. You can - now do the following. - -- List all DSC resources within a configuration or node block by entering - Ctrl+Space on a blank line within the block. - -- Automatic completion on resource properties of the enumeration type. - -- Automatic completion on the DependsOn property of DSC resources, based - on other resource instances in the configuration. - -- Improved tab completion of resource property values. - -- A new DscLocalConfigurationManager attribute designates a configuration block - as a meta-configuration, which is used to configure the DSC Local Configuration - Manager. This attribute restricts a configuration to containing only items - which configure the DSC Local Configuration Manager. During processing, - this configuration generates a *.meta.mof file that is then sent to the - appropriate target nodes by running the Set-DscLocalConfigurationManager cmdlet. - -- Partial configurations are now allowed in Windows PowerShell 5.0. You can - deliver configuration documents to a node in fragments. For a node to receive - multiple fragments of a configuration document, the node’s Local Configuration - Manager must be first set to specify the expected fragments. - -- Cross-computer synchronization is new in DSC in Windows PowerShell 5.0. By - using the built-in WaitFor* resources (WaitForAll, WaitForAny, and - WaitForSome), you can now specify dependencies across computers during - configuration runs, without external orchestrations. These resources provide - node-to-node synchronization by using CIM connections over the WS-Man protocol. - A configuration can wait for another computer’s specific resource state to change. - -- Just Enough Administration (JEA), a new delegation security feature, leverages - DSC and Windows PowerShell constrained runspaces to help secure enterprises - from data loss or compromise by employees, whether intentional or unintentional. - For more information about JEA, including where you can download the xJEA DSC - resource, see Just Enough Administration, Step by Step. - (http://ppe.blogs.technet.com/b/privatecloud/archive/2014/05/14/just-enough-administration-step-by-step.aspx) - -- The following new cmdlets have been added to the PSDesiredStateConfiguration - module. - -- A new Get-DscConfigurationStatus cmdlet gets high-level information about - configuration status from a target node. You can obtain the status of the - last, or of all configurations. - -- A new Compare-DscConfiguration cmdlet compares a specified configuration - with the actual state of one or more target nodes. - -- A new Publish-DscConfiguration cmdlet copies a configuration MOF file to - a target node, but does not apply the configuration. The configuration is - applied during the next consistency pass, or when you run the - Update-DscConfiguration cmdlet. - -- A new Test-DscConfiguration cmdlet lets you verify that a resulting - configuration matches the desired configuration, returning either True if - the configuration matches the desired configuration, or False if the actual - configuration does not match the desired configuration. - -- A new Update-DscConfiguration cmdlet forces a configuration to be processed. - If the Local Configuration Manager is in pull mode, the cmdlet gets the - configuration from the pull server before applying it. - - New features in Windows PowerShell ISE - -- You can now edit remote Windows PowerShell scripts and files in a local copy of - Windows PowerShell ISE, by running Enter-PSSession to start a remote session on - the computer that’s storing the files you want to edit, and then running PSEdit - . This feature eases editing Windows - PowerShell files that are stored on the Server Core installation option of - Windows Server, where Windows PowerShell ISE cannot run. - -- The Start-Transcript cmdlet is now supported in Windows PowerShell ISE. - -- You can now debug remote scripts in Windows PowerShell ISE. - -- A new menu command, Break All (Ctrl+B), breaks into the debugger for both - local and remotely-running scripts. - - New features in Windows PowerShell Web Services (Management OData IIS Extension) - -- Starting in Windows PowerShell 5.0, you can generate a set of Windows PowerShell - cmdlets based on the functionality exposed by a given OData endpoint, by - running the Export-ODataEndpointProxy cmdlet. - - Notable bug fixes in Windows PowerShell 5.0 - -- Windows PowerShell 5.0 includes a new COM implementation, which offers - significant performance improvements when you are working with COM objects. - For a video demonstration of the effect, see Com_Perf_Improvements. - (http://1drv.ms/1qu3UPZ) - - For more information about Windows PowerShell 5.0, visit the following web - sites: - - -- Windows PowerShell Scripting website - http://go.microsoft.com/fwlink/?LinkID=106031 - - -- Windows PowerShell Team Blog: - http://go.microsoft.com/fwlink/?LinkId=143696 - - -- Windows PowerShell Web Access - http://technet.microsoft.com/library/hh831611.aspx - -SEE ALSO - about_Classes - about_Debuggers - about_Desired_State_Configuration - about_Scheduled_Jobs - about_Updatable_Help - Add-Computer - ConvertFrom-String - Debug-Job - Disable-JobTrigger - Enable-JobTrigger - Get-Module - Get-Process - Invoke-RestMethod - New-JobTrigger - Register-ScheduledJob - Remove-Computer - Save-Help - Set-ExecutionPolicy - Set-JobTrigger - Set-ScheduledJob - Update-Help - -KEYWORDS - What's New in Windows PowerShell 5.0 - -``` +## SHORT DESCRIPTION + +Describes new features that are included in Windows PowerShell 5.0. + +## LONG DESCRIPTION + +Windows PowerShell 5.0 includes significant new features that extend its use, +improve its usability, and allow you to control and manage Windows-based +environments more easily and comprehensively. + +Windows PowerShell 5.0 is backward-compatible. Cmdlets, providers, modules, +snap-ins, scripts, functions, and profiles that were designed for Windows +PowerShell 4.0, Windows PowerShell 3.0, and Windows PowerShell 2.0 generally +work in Windows PowerShell 5.0 without changes. + +Windows PowerShell 5.0 is installed by default on Windows Server Technical +Preview and Windows Technical Preview. To install Windows PowerShell 5.0 on +Windows Server 2012 R2, Windows 8.1 Enterprise, or Windows 8.1 Pro, download +and install +[Windows Management Framework 5.0](/powershell/scripting/whats-new/what-s-new-with-powershell). +Be sure to read the download details, and meet all system requirements, before +you install Windows Management Framework 5.0 Preview. + +You can also read about changes to Windows PowerShell 5.0 in +[What's New in Windows PowerShell](/powershell/scripting/whats-new/what-s-new-with-powershell). + +## NEW FEATURES + +### New features in Windows PowerShell + +- Starting in Windows PowerShell 5.0, you can develop by using classes, by + using formal syntax and semantics that are similar to other object-oriented + programming languages. Class, Enum, and other keywords have been added to the + Windows PowerShell language to support the new feature. For more information + about working with classes, see about_Classes. + +- In collaboration with Microsoft Research, a new cmdlet, ConvertFrom-String, + has been added. ConvertFrom-String lets you extract and parse structured + objects from the content of text strings. For more information, see + ConvertFrom-String. + +- A new module, Microsoft.PowerShell.Archive, includes cmdlets that let you + compress files and folders into archive (also known as ZIP) files, extract + files from existing ZIP files, and update ZIP files with newer versions of + files compressed within them. + +- A new module, OneGet, lets you discover and install software packages on the + Internet. The OneGet module is a manager or multiplexer of existing package + managers (also called package providers) to unify Windows package management + with a single Windows PowerShell interface. + +- A new module, PowerShellGet, lets you find, install, publish, and update + modules and DSC resources on the PowerShell Resource Gallery, or on an + internal module repository that you can set up by running the + Register-PSRepository cmdlet. + +- New-Item, Remove-Item, and Get-ChildItem have been enhanced to support + creating and managing symbolic links. The ItemType parameter for New-Item + accepts a new value, SymbolicLink. Now you can create symbolic links in a + single line by running the New-Item cmdlet. + +- Windows PowerShell transcription has been improved to apply to all hosting + applications (such as Windows PowerShell ISE) in addition to the console + host (powershell.exe). Transcription options (including enabling a + system-wide transcript) can be configured by enabling the Turn on PowerShell + Transcription Group Policy setting, found in Administrative + Templates/Windows Components/Windows PowerShell. + +- A new detailed script tracing feature lets you enable detailed tracking and + analysis of Windows PowerShell scripting use on a system. After you enable + detailed script tracing, Windows PowerShell logs all script blocks to the + Event Tracing for Windows (ETW) event log, + Microsoft-Windows-PowerShell/Operational. + +- Starting in Windows PowerShell 5.0, new Cryptographic Message Syntax cmdlets + support encryption and decryption of content by using the IETF standard + format for cryptographically protecting messages as documented by + [RFC5652](https://tools.ietf.org/html/rfc5652). The Get-CmsMessage, + Protect-CmsMessage, and Unprotect-CmsMessage cmdlets have been added to the + Microsoft.PowerShell.Security module. + +- New cmdlets in the Microsoft.PowerShell.Utility module, Get-Runspace, + Debug-Runspace, Get-RunspaceDebug, Enable-RunspaceDebug, and + Disable-RunspaceDebug, let you set debug options on a runspace, and start + and stop debugging on a runspace. For debugging arbitrary runspaces—that is, + runspaces that are not the default runspace for a Windows PowerShell console + or Windows PowerShell ISE session—Windows PowerShell lets you set + breakpoints in a script, and have added breakpoints stop the script from + running until you can attach a debugger to debug the runspace script. Nested + debugging support for arbitrary runspaces has been added to the Windows + PowerShell script debugger for runspaces. + +- New cmdlets Enter-PSHostProcess and Exit-PSHostProcess let you debug Windows + PowerShell scripts in processes separate from the current process that is + running in the Windows PowerShell console. Run Enter-PSHostProcess to enter, + or attach to, a specific process ID, and then run Get-Runspace to return the + active runspaces within the process. Run Exit-PSHostProcess to detach from + the process when you are finished debugging the script within the process. + +- A new Wait-Debugger cmdlet has been added to the + Microsoft.PowerShell.Utility module. You can run Wait-Debugger to stop a + script in the debugger before running the next statement in the script. + +- The Windows PowerShell Workflow debugger now supports command or tab + completion, and you can debug nested workflow functions. You can now press + Ctrl+Break to enter the debugger in a running script, in both local and + remote sessions, and in a workflow script. + +- A Debug-Job cmdlet has been added to the Microsoft.PowerShell.Core module to + debug running job scripts for Windows PowerShell Workflow, background, and + jobs running in remote sessions. + +- A new state, AtBreakpoint, has been added for Windows PowerShell jobs. The + AtBreakpoint state applies when a job is running a script that includes set + breakpoints, and the script has hit a breakpoint. When a job is stopped at a + debug breakpoint, you must debug the job by running the Debug-Job cmdlet. + +- Windows PowerShell 5.0 implements support for multiple versions of a single + Windows PowerShell module in the same folder in $PSModulePath. A + RequiredVersion property has been added to the ModuleSpecification class to + help you get the desired version of a module; this property is + mutually-exclusive with the ModuleVersion property. RequiredVersion is now + supported as part of the value of the FullyQualifiedName parameter of the + Get-Module, Import-Module, and Remove-Module cmdlets. + +- You can now perform module version validation by running the + Test-ModuleManifest cmdlet. + +- Results of the Get-Command cmdlet now display a Version column; a new + Version property has been added to the CommandInfo class. Get-Command shows + commands from multiple versions of the same module. The Version property is + also part of derived classes of CmdletInfo: CmdletInfo and ApplicationInfo. + +- A new Get-ItemPropertyValue cmdlet lets you get the value of a property + without using dot notation. For example, in older releases of Windows + PowerShell, you can run the following command to get the value of the + Application Base property of the PowerShellEngine registry key: + + ```powershell + $keypath = 'HKLM:\SOFTWARE\Microsoft\PowerShell\3\PowerShellEngine' + (Get-ItemProperty -Path $keypath -Name ApplicationBase).ApplicationBase + ``` + + Starting in Windows PowerShell 5.0, you can run + + ```powershell + $keypath = 'HKLM:\SOFTWARE\Microsoft\PowerShell\3\PowerShellEngine' + Get-ItemPropertyValue -Path $keypath -Name ApplicationBase + ``` + +- A new NetworkSwitch module contains cmdlets that enable you to apply switch, + virtual LAN (VLAN), and basic Layer 2 network switch port configuration to + Windows Server 2012 R2 (and later releases) logo-certified network switches. + +- The FullyQualifiedName parameter has been added to Import-Module and + Remove-Module cmdlets, to support storing multiple versions of a single + module. + +- Save-Help, Update-Help, Import-PSSession, Export-PSSession, and Get-Command + have a new parameter, FullyQualifiedModule, of type ModuleSpecification. Add + this parameter to specify a module by its fully qualified name. + +- The value of $PSVersionTable.PSVersion has been updated to 5.0. + +### New features in Windows PowerShell Desired State Configuration + +- Windows PowerShell language enhancements let you define Windows PowerShell + Desired State Configuration (DSC) resources by using classes. + Import-DscResource is now a true dynamic keyword; Windows PowerShell parses + the specified module’s root module, searching for classes that contain the + DscResource attribute. You can now use classes to define DSC resources, in + which neither a MOF file nor a DSCResource subfolder in the module folder is + required. A Windows PowerShell module file can contain multiple DSC resource + classes. + +- A new parameter, ThrottleLimit, has been added to the following cmdlets in + the PSDesiredStateConfiguration module. Add the ThrottleLimit parameter to + specify the number of target computers or devices on which you want the + command to work at the same time. + + - Get-DscConfiguration + - Get-DscConfigurationStatus + - Get-DscLocalConfigurationManager + - Restore-DscConfiguration + - Test-DscConfiguration + - Compare-DscConfiguration + - Publish-DscConfiguration + - Set-DscLocalConfigurationManager + - Start-DscConfiguration + - Update-DscConfiguration + +- With centralized DSC error reporting, rich error information is not only + logged in the event log, but it can be sent to a central location for later + analysis. You can use this central location to store DSC configuration + errors that have occurred for any server in their environment. After the + report server is defined in the meta-configuration, all errors are sent to + the report server, and then stored in a database. You can set up this + functionality regardless of whether or not a target node is configured to + pull configurations from a pull server. + +- Improvements to Windows PowerShell ISE ease DSC resource authoring. You can + now do the following. + - List all DSC resources within a configuration or node block by entering + Ctrl+Space on a blank line within the block. + - Automatic completion on resource properties of the enumeration type. + - Automatic completion on the DependsOn property of DSC resources, based on + other resource instances in the configuration. + - Improved tab completion of resource property values. + +- A new DscLocalConfigurationManager attribute designates a configuration + block as a meta-configuration, which is used to configure the DSC Local + Configuration Manager. This attribute restricts a configuration to + containing only items which configure the DSC Local Configuration Manager. + During processing, this configuration generates a *.meta.mof file that is + then sent to the appropriate target nodes by running the + Set-DscLocalConfigurationManager cmdlet. + +- Partial configurations are now allowed in Windows PowerShell 5.0. You can + deliver configuration documents to a node in fragments. For a node to + receive multiple fragments of a configuration document, the node’s Local + Configuration Manager must be first set to specify the expected fragments. + +- Cross-computer synchronization is new in DSC in Windows PowerShell 5.0. By + using the built-in WaitFor* resources (WaitForAll, WaitForAny, and + WaitForSome), you can now specify dependencies across computers during + configuration runs, without external orchestrations. These resources provide + node-to-node synchronization by using CIM connections over the WS-Man + protocol. A configuration can wait for another computer’s specific resource + state to change. + +- Just Enough Administration (JEA), a new delegation security feature, + leverages DSC and Windows PowerShell constrained runspaces to help secure + enterprises from data loss or compromise by employees, whether intentional + or unintentional. For more information about JEA, including where you can + download the xJEA DSC resource, see [Just Enough Administration](/powershell/jea/overview). + +- The following new cmdlets have been added to the PSDesiredStateConfiguration + module. + - A new Get-DscConfigurationStatus cmdlet gets high-level information about + configuration status from a target node. You can obtain the status of the + last, or of all configurations. + - A new Compare-DscConfiguration cmdlet compares a specified configuration + with the actual state of one or more target nodes. + - A new Publish-DscConfiguration cmdlet copies a configuration MOF file to a + target node, but does not apply the configuration. The configuration is + applied during the next consistency pass, or when you run the + Update-DscConfiguration cmdlet. + - A new Test-DscConfiguration cmdlet lets you verify that a resulting + configuration matches the desired configuration, returning either True if + the configuration matches the desired configuration, or False if the actual + configuration does not match the desired configuration. + - A new Update-DscConfiguration cmdlet forces a configuration to be + processed. If the Local Configuration Manager is in pull mode, the cmdlet + gets the configuration from the pull server before applying it. + +### New features in Windows PowerShell ISE + +- You can now edit remote Windows PowerShell scripts and files in a local copy + of Windows PowerShell ISE, by running Enter-PSSession to start a remote + session on the computer that’s storing the files you want to edit, and then + running PSEdit . This feature eases + editing Windows PowerShell files that are stored on the Server Core + installation option of Windows Server, where Windows PowerShell ISE cannot + run. +- The Start-Transcript cmdlet is now supported in Windows PowerShell ISE. +- You can now debug remote scripts in Windows PowerShell ISE. +- A new menu command, Break All (Ctrl+B), breaks into the debugger for both + local and remotely-running scripts. + +### New features in Windows PowerShell Web Services (Management OData IIS Extension) + +- Starting in Windows PowerShell 5.0, you can generate a set of Windows + PowerShell cmdlets based on the functionality exposed by a given OData + endpoint, by running the Export-ODataEndpointProxy cmdlet. + +### Notable bug fixes in Windows PowerShell 5.0 + +- Windows PowerShell 5.0 includes a new COM implementation, which offers + significant performance improvements when you are working with COM objects. + For a video demonstration of the effect, see + [Com_Perf_Improvements](http://1drv.ms/1qu3UPZ). + +For more information about Windows PowerShell 5.0, visit the following web +sites: + +- [Windows PowerShell Scripting website](/powershell/scripting/powershell-scripting) +- [Windows PowerShell Team Blog](http://go.microsoft.com/fwlink/?LinkId=143696) +- [Windows PowerShell Web Access](/powershell/scripting/core-powershell/web-access) + +## SEE ALSO + +[about_Classes](about_Classes.md) + +[about_Debuggers](about_Debuggers.md) + +[about_Desired_State_Configuration](about_desiredstateconfiguration.md) + +[about_Updatable_Help](about_Updatable_Help.md) + +[Save-Help](../Save-Help.md) + +[Get-Module](../Get-Module.md) + +[Debug-Job](../Debug-Job.md) + +[Update-Help](../Update-Help.md) + +[Get-Process](../../Microsoft.PowerShell.Management/Get-Process.md) + +[Remove-Computer](../../Microsoft.PowerShell.Management/Remove-Computer.md) + +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) + +[Add-Computer](../../Microsoft.PowerShell.Management/Add-Computer.md) + +[ConvertFrom-String](../../Microsoft.PowerShell.Utility/ConvertFrom-String.md) + +[Invoke-RestMethod](../../Microsoft.PowerShell.Utility/Invoke-RestMethod.md) + +[Set-JobTrigger](../../PSScheduledJob/Set-JobTrigger.md) + +[Set-ScheduledJob](../../PSScheduledJob/Set-ScheduledJob.md) + +[New-JobTrigger](../../PSScheduledJob/New-JobTrigger.md) + +[Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) + +[Enable-JobTrigger](../../PSScheduledJob/Enable-JobTrigger.md) + +[Disable-JobTrigger](../../PSScheduledJob/Disable-JobTrigger.md) + +## KEYWORDS + +What's New in Windows PowerShell 5.0 \ No newline at end of file From 95d400595838b46c25627cbe35d42ec952378874 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 4 Jan 2018 14:42:14 -0800 Subject: [PATCH 154/188] v5.1 about scrub missed files (#2009) --- .../About/about_For.md | 2 +- .../About/about_Debuggers.md | 661 +++++---- .../About/about_Functions_Advanced_Methods.md | 270 ++-- .../about_Functions_OutputTypeAttribute.md | 54 +- .../About/about_Language_Keywords.md | 2 +- .../About/about_PSSessions.md | 189 ++- .../About/about_PSSnapins.md | 189 ++- .../About/about_PackageManagement.md | 22 +- .../About/about_Parameters.md | 237 +-- .../About/about_PowerShell_exe.md | 253 ++-- .../About/about_Providers.md | 301 ++-- .../About/about_Quoting_Rules.md | 257 ++-- .../About/about_Remote.md | 238 +-- .../About/about_Remote_Requirements.md | 244 ++- .../About/about_Remote_Variables.md | 148 +- .../About/about_Requires.md | 5 +- .../About/about_Reserved_Words.md | 2 +- .../About/about_Return.md | 107 +- .../About/about_Run_With_PowerShell.md | 68 +- .../About/about_Scopes.md | 504 +++---- .../about_Script_Internationalization.md | 179 ++- .../about_Session_Configuration_Files.md | 506 +++---- .../About/about_Signing.md | 326 ++-- .../About/about_Splatting.md | 137 +- .../About/about_Transactions.md | 847 ++++++----- .../About/about_Updatable_Help.md | 664 ++++----- .../About/about_WMI.md | 99 +- .../About/about_WQL.md | 892 +++++------ .../About/about_Windows_PowerShell_ISE.md | 271 ++-- .../About/about_Windows_RT.md | 63 +- .../About/about_desiredstateconfiguration.md | 316 ++-- .../About/about_dsclogresource.md | 23 +- .../About/about_hidden.md | 264 ++-- .../About/about_logical_operators.md | 63 +- .../About/about_psconsolehostreadline.md | 79 +- .../About/about_psreadline.md | 1309 +++++++++-------- .../About/about_type_accelerators.md | 17 - .../About/about_windows_powershell_5.1.md | 614 ++++---- 38 files changed, 5365 insertions(+), 5057 deletions(-) delete mode 100644 reference/5.1/Microsoft.PowerShell.Core/About/about_type_accelerators.md diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_For.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_For.md index c8343e7483e3..5c8f723bb156 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_For.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_For.md @@ -25,7 +25,7 @@ all the values in an array, consider using a Foreach statement. The following shows the For statement syntax. ```powershell -for (>init>; ; ) +for (; ; ) {} ``` diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Debuggers.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Debuggers.md index 8ea961ecdfe8..c7b464110d8d 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Debuggers.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Debuggers.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-11-27 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,64 +7,55 @@ title: about_Debuggers --- # About Debuggers -## about_Debuggers - - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes the Windows PowerShell debugger. -# LONG DESCRIPTION - -Debugging is the process of examining a script while it is running to -identify and correct errors in the script instructions. The -Windows PowerShell debugger can help you examine and identify -errors and inefficiencies in your scripts, functions, commands, Windows -PowerShell workflows, Windows PowerShell Desired State Configuration (DSC) -configurations, or expressions. - -Starting in Windows PowerShell 5.0, the Windows PowerShell debugger has been updated -to debug scripts, functions, workflows, commands, configurations, or expressions that are -running in either the console or Windows PowerShell ISE on remote computers. -You can run Enter-PSSession to start an interactive remote PowerShell session -in which you can set breakpoints and debug script files and commands on the -remote computer. Enter-PSSession functionality has been updated to let you -reconnect to and enter a disconnected session that is running a script or -command on a remote computer. If the running script hits a breakpoint, -your client session automatically starts the debugger. If the disconnected -session that is running a script has already hit a breakpoint, and is stopped -at the breakpoint, Enter-PSSession automatically starts the command-line -debugger, after you reconnect to the session. - -The Windows PowerShell debugger can also be used to debug Windows -PowerShell workflows, in either the Windows PowerShell console, or in -Windows PowerShell ISE. Starting in Windows PowerShell 5.0, you can debug -within running jobs or processes, either locally or remotely. +## LONG DESCRIPTION + +Debugging is the process of examining a script while it is running to identify +and correct errors in the script instructions. The Windows PowerShell debugger +can help you examine and identify errors and inefficiencies in your scripts, +functions, commands, Windows PowerShell workflows, Windows PowerShell Desired +State Configuration (DSC) configurations, or expressions. + +Starting in Windows PowerShell 5.0, the Windows PowerShell debugger has been +updated to debug scripts, functions, workflows, commands, configurations, or +expressions that are running in either the console or Windows PowerShell ISE +on remote computers. You can run Enter-PSSession to start an interactive +remote PowerShell session in which you can set breakpoints and debug script +files and commands on the remote computer. Enter-PSSession functionality has +been updated to let you reconnect to and enter a disconnected session that is +running a script or command on a remote computer. If the running script hits a +breakpoint, your client session automatically starts the debugger. If the +disconnected session that is running a script has already hit a breakpoint, +and is stopped at the breakpoint, Enter-PSSession automatically starts the +command-line debugger, after you reconnect to the session. + +The Windows PowerShell debugger can also be used to debug Windows PowerShell +workflows, in either the Windows PowerShell console, or in Windows PowerShell +ISE. Starting in Windows PowerShell 5.0, you can debug within running jobs or +processes, either locally or remotely. You can use the features of the Windows PowerShell debugger to examine a -Windows PowerShell script, function, command, workflow, or expression -while it is running. The Windows PowerShell debugger includes a set of -cmdlets that let you set breakpoints, manage breakpoints, and view the call -stack. - -Debugger Cmdlets -The Windows PowerShell debugger includes the following set of cmdlets: +Windows PowerShell script, function, command, workflow, or expression while it +is running. The Windows PowerShell debugger includes a set of cmdlets that let +you set breakpoints, manage breakpoints, and view the call stack. -Set-PsBreakpoint: Sets breakpoints on lines, variables, and -commands. +## Debugger Cmdlets -Get-PsBreakpoint: Gets breakpoints in the current session. - -Disable-PsBreakpoint: Turns off breakpoints in the current session. - -Enable-PsBreakpoint: Re-enables breakpoints in the current session. +The Windows PowerShell debugger includes the following set of cmdlets: -Remove-PsBreakpoint: Deletes breakpoints from the current session. +- `Set-PsBreakpoint`: Sets breakpoints on lines, variables, and commands. +- `Get-PsBreakpoint`: Gets breakpoints in the current session. +- `Disable-PsBreakpoint`: Turns off breakpoints in the current session. +- `Enable-PsBreakpoint`: Re-enables breakpoints in the current session. +- `Remove-PsBreakpoint`: Deletes breakpoints from the current session. +- `Get-PsCallStack`: Displays the current call stack. -Get-PsCallStack: Displays the current call stack. +## Starting and Stopping the Debugger -Starting and Stopping the Debugger To start the debugger, set one or more breakpoints. Then, run the script, command, or function that you want to debug. @@ -72,89 +63,85 @@ When you reach a breakpoint, execution stops, and control is turned over to the debugger. To stop the debugger, run the script, command, or function until it is -complete. Or, type "stop" or "t". +complete. Or, type `stop` or `t`. -Debugger Commands -When you use the debugger in the Windows PowerShell console, use the -following commands to control the execution. In Windows PowerShell ISE, -use commands on the Debug menu. +### Debugger Commands + +When you use the debugger in the Windows PowerShell console, use the following +commands to control the execution. In Windows PowerShell ISE, use commands on +the Debug menu. Note: For information about how to use the debugger in other host applications, see the host application documentation. -s, StepInto Executes the next statement and then stops. +- `s`, `StepInto`: Executes the next statement and then stops. -v, StepOver Executes the next statement, but skips functions -and invocations. The skipped statements are -executed, but not stepped through. +- `v`, `StepOver`: Executes the next statement, but skips functions and + invocations. The skipped statements are executed, but not stepped through. -Ctrl+Break -(Break All in ISE) Breaks into a running script within either the -Windows PowerShell console, or Windows PowerShell ISE. -Note that Ctrl+Break in Windows PowerShell 2.0, 3.0, -and 4.0 closes the program. Break All works on both -local and remote interactively-running scripts. +- `Ctrl+Break`: (Break All in ISE) Breaks into a running script within either + the Windows PowerShell console, or Windows PowerShell ISE. Note that + Ctrl+Break in Windows PowerShell 2.0, 3.0, and 4.0 closes the program. Break + All works on both local and remote interactively-running scripts. -o, StepOut Steps out of the current function; up one level -if nested. If in the main body, it continues to -the end or the next breakpoint. The skipped -statements are executed, but not stepped through. +- `o`, `StepOut`: Steps out of the current function; up one level if nested. + If in the main body, it continues to the end or the next breakpoint. The + skipped statements are executed, but not stepped through. -c, Continue Continues to run until the script is complete or -until the next breakpoint is reached. The skipped -statements are executed, but not stepped through. +- `c`, `Continue`: Continues to run until the script is complete or until the + next breakpoint is reached. The skipped statements are executed, but not + stepped through. -l, List Displays the part of the script that is executing. -By default, it displays the current line, five -previous lines, and 10 subsequent lines. To continue -listing the script, press ENTER. +- `l`, `List`: Displays the part of the script that is executing. By default, + it displays the current line, five previous lines, and 10 subsequent lines. + To continue listing the script, press ENTER. -l , List Displays 16 lines of the script beginning with the -line number specified by . +- `l `, `List`: Displays 16 lines of the script beginning with the line + number specified by ``. -l , List Displays lines of the script, beginning with the -line number specified by . +- `l `, `List`: Displays `` lines of the script, beginning with the + line number specified by ``. -q, Stop, Exit Stops executing the script, and exits the debugger. If you -are debugging a job by running the Debug-Job cmdlet, the Exit -command detaches the debugger, and allows the job to continue -running. +- `q`, `Stop`, `Exit`: Stops executing the script, and exits the debugger. If + you are debugging a job by running the Debug-Job cmdlet, the Exit command + detaches the debugger, and allows the job to continue running. -k, Get-PsCallStack Displays the current call stack. +- `k`, `Get-PsCallStack`: Displays the current call stack. - Repeats the last command if it was Step (s), -StepOver (v), or List (l). Otherwise, represents a -submit action. +- ``: Repeats the last command if it was Step (s), StepOver (v), or + List (l). Otherwise, represents a submit action. -?, h Displays the debugger command Help. +- `?`, `h`: Displays the debugger command Help. To exit the debugger, you can use Stop (q). + Starting in Windows PowerShell 5.0, you can run the Exit command to exit a nested debugging session that you started by running either Debug-Job or Debug-Runspace. -By using these debugger commands, you can run a script, stop on a point -of concern, examine the values of variables and the state of the system, -and continue running the script until you have identified a problem. +By using these debugger commands, you can run a script, stop on a point of +concern, examine the values of variables and the state of the system, and +continue running the script until you have identified a problem. -NOTE: If you step into a statement with a redirection operator, -such as ">", the Windows PowerShell debugger steps over all -remaining statements in the script. +NOTE: If you step into a statement with a redirection operator, such as ">", +the Windows PowerShell debugger steps over all remaining statements in the +script. Displaying the Values of script Variables -While you are in the debugger, you can also enter commands, display the -value of variables, use cmdlets, and run scripts at the command line. +While you are in the debugger, you can also enter commands, display the value +of variables, use cmdlets, and run scripts at the command line. -You can display the current value of all variables in the script that is -being debugged, except for the following automatic variables: - -# $_ +You can display the current value of all variables in the script that is being +debugged, except for the following automatic variables: +```powershell +$_ $Args $Input $MyInvocation $PSBoundParameters +``` If you try to display the value of any of these variables, you get the value of that variable for in an internal pipeline the debugger uses, not @@ -166,15 +153,20 @@ Then you can display the value of the new variable. For example, +```powershell $scriptArgs = $Args $scriptArgs +``` In the example in this topic, the value of the $MyInvocation variable is reassigned as follows: +```powershell $scriptname = $MyInvocation.MyCommand.Path +``` + +## The Debugger Environment -The Debugger Environment When you reach a breakpoint, you enter the debugger environment. The command prompt changes so that it begins with "[DBG]:". If you are debugging a workflow, the prompt is "[WFDBG]". You can customize @@ -189,87 +181,98 @@ command prompt. For example, the following is the default debugging prompt in the Windows PowerShell console: +``` [DBG]: PS (get-location)>>> +``` -You can find the nesting level by using the $NestedPromptLevel +You can find the nesting level by using the \$NestedPromptLevel automatic variable. -Additionally, an automatic variable, $PSDebugContext, is defined in -the local scope. You can use the presence of the $PsDebugContext +Additionally, an automatic variable, \$PSDebugContext, is defined in +the local scope. You can use the presence of the \$PsDebugContext variable to determine whether you are in the debugger. For example: +```powershell if ($psdebugcontext) {"Debugging"} else {"Not Debugging"} +``` -You can use the value of the $PSDebugContext variable in your +You can use the value of the \$PSDebugContext variable in your debugging. +``` [DBG]: PS>>> $psdebugcontext.invocationinfo Name CommandLineParameters UnboundArguments Location ---- --------------------- ---------------- -------- = {} {} C:\ps-test\vote.ps1 (1) +``` + +## Debugging and Scope -Debugging and Scope -Breaking into the debugger does not change the scope in which -you are operating, but when you reach a breakpoint in a script, -you move into the script scope. The script scope is a child -of the scope in which you ran the debugger. +Breaking into the debugger does not change the scope in which you are +operating, but when you reach a breakpoint in a script, you move into the +script scope. The script scope is a child of the scope in which you ran the +debugger. -To find the variables and aliases that are defined in the -script scope, use the Scope parameter of the Get-Alias or -Get-Variable cmdlets. +To find the variables and aliases that are defined in the script scope, use +the Scope parameter of the Get-Alias or Get-Variable cmdlets. -For example, the following command gets the variables in the -local (script) scope: +For example, the following command gets the variables in the local (script) +scope: +```powershell get-variable -scope 0 +``` You can abbreviate the command as: +```powershell gv -s 0 +``` -This is a useful way to see only the variables that you defined in the -script and that you defined while debugging. +This is a useful way to see only the variables that you defined in the script +and that you defined while debugging. Debugging at the Command Line -When you set a variable breakpoint or a command breakpoint, you can set -the breakpoint only in a script file. However, by default, the breakpoint -is set on anything that runs in the current session. - -For example, if you set a breakpoint on the $name variable, the debugger -breaks on any $name variable in any script, command, function, script -cmdlet or expression that you run until you disable or remove the -breakpoint. - -This allows you to debug your scripts in a more realistic context in -which they might be affected by functions, variables, and other scripts -in the session and in the user's profile. - -Line breakpoints are specific to script files, so they are set only in -script files. - -Debugging Workflows -The Windows PowerShell 4.0 debugger can be used to debug Windows -PowerShell workflows, either in the Windows PowerShell console, or in -Windows PowerShell ISE. There are some limitations with using -the Windows PowerShell debugger to debug workflows. - --- You can view workflow variables while you are in the debugger, but -setting workflow variables from within the debugger is not supported. --- Tab completion when stopped in the workflow debugger is not -available. --- Workflow debugging works only with synchronous running of workflows from -a Windows PowerShell script. You cannot debug workflows if they are -running as a job (with the -AsJob parameter). --- Other nested debugging scenarios--such as a workflow calling another -workflow, or a workflow calling a script--are not implemented. - -The following example demonstrates debugging a workflow. Note that when -the debugger steps into the workflow function, the debugger prompt changes -to [WFDBG]. +When you set a variable breakpoint or a command breakpoint, you can set the +breakpoint only in a script file. However, by default, the breakpoint is set +on anything that runs in the current session. + +For example, if you set a breakpoint on the \$name variable, the debugger +breaks on any \$name variable in any script, command, function, script cmdlet +or expression that you run until you disable or remove the breakpoint. + +This allows you to debug your scripts in a more realistic context in which +they might be affected by functions, variables, and other scripts in the +session and in the user's profile. + +Line breakpoints are specific to script files, so they are set only in script +files. + +## Debugging Workflows + +The Windows PowerShell 4.0 debugger can be used to debug Windows PowerShell +workflows, either in the Windows PowerShell console, or in Windows PowerShell +ISE. There are some limitations with using the Windows PowerShell debugger to +debug workflows. + +- You can view workflow variables while you are in the debugger, but setting + workflow variables from within the debugger is not supported. +- Tab completion when stopped in the workflow debugger is not available. +- Workflow debugging works only with synchronous running of workflows from a + Windows PowerShell script. You cannot debug workflows if they are running as a + job (with the **-AsJob** parameter). +- Other nested debugging scenarios--such as a workflow calling another + workflow, or a workflow calling a script--are not implemented. + +The following example demonstrates debugging a workflow. Note that when the +debugger steps into the workflow function, the debugger prompt changes to +[WFDBG]. + +```powershell PS C:> Set-PSBreakpoint -Script C:\TestWFDemo1.ps1 -Line 8 ID Script Line Command Variable Action @@ -350,32 +353,32 @@ At C:\TestWFDemo1.ps1:11 char:5 [WFDBG:localhost]: PS C:>> stepOut Get PowerShell process: -Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName PSComputerName -------- ------ ----- ----- ----- ------ -- ----------- -------------- -433 35 106688 128392 726 2.67 7124 powershell localhost -499 44 134244 172096 787 2.79 7452 powershell localhost +Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName +------- ------ ----- ----- ----- ------ -- ----------- + 433 35 106688 128392 726 2.67 7124 powershell + 499 44 134244 172096 787 2.79 7452 powershell + Workflow function complete. +``` + +## Debugging Functions -Debugging Functions When you set a breakpoint on a function that has Begin, Process, and End sections, the debugger breaks at the first line of each section. For example: -function test-cmdlet -{ -begin -{ -write-output "Begin" -} -process -{ -write-output "Process" -} -end -{ -write-output "End" -} +```powershell +function test-cmdlet { + begin { + write-output "Begin" + } + process { + write-output "Process" + } + end { + write-output "End" + } } C:\PS> set-psbreakpoint -command test-cmdlet @@ -406,20 +409,24 @@ Hit Command breakpoint on 'prompt:test-cmdlet' test-cmdlet # [DBG]: C:\PS> +``` +## Debugging Remote Scripts -Debugging Remote Scripts -Starting in Windows PowerShell 5.0, you can run the Windows PowerShell debugger in -a remote session, in either the console, or Windows PowerShell ISE. Enter-PSSession -functionality has been updated to let you reconnect to and enter a disconnected -session that is running on a remote computer, and currently running a script. -If the running script hits a breakpoint, your client session automatically -starts the debugger. The following is an example that shows how this works, -with breakpoints set in a script at lines 6, 11, 22, and 25. Note that in the -example, when the debugger starts, there are two identifying prompts: the -name of the computer on which the session is running, and the DBG prompt that -lets you know you are in debugging mode. +Starting in Windows PowerShell 5.0, you can run the Windows PowerShell +debugger in a remote session, in either the console, or Windows PowerShell +ISE. Enter-PSSession functionality has been updated to let you reconnect to +and enter a disconnected session that is running on a remote computer, and +currently running a script. If the running script hits a breakpoint, your +client session automatically starts the debugger. +The following is an example that shows how this works, with breakpoints set in +a script at lines 6, 11, 22, and 25. Note that in the example, when the +debugger starts, there are two identifying prompts: the name of the computer +on which the session is running, and the DBG prompt that lets you know you are +in debugging mode. + +```powershell Enter-Pssession -Cn localhost [localhost]: PS C:\psscripts> Set-PSBreakpoint .\ttest19.ps1 6,11,22,25 @@ -468,45 +475,54 @@ At C:\psscripts\ttest19.ps1:12 char:1 [localhost]: [DBG]: PS C:\psscripts>> quit [localhost]: PS C:\psscripts> Exit-PSSession PS C:\psscripts> +``` + +## Examples -Examples This test script detects the version of the operating system and displays a system-appropriate message. It includes a function, a function call, and a variable. The following command displays the contents of the test script file: +```powershell c:>\PS-test> get-content test.ps1 function psversion { -"Windows PowerShell " + $psversiontable.psversion -if ($psversiontable.psversion.major -lt 2) { -"Upgrade to Windows PowerShell 2.0!" -} -else { -"Have you run a background job today (start-job)?" -} + "Windows PowerShell " + $psversiontable.psversion + if ($psversiontable.psversion.major -lt 6) { + "Upgrade to Windows PowerShell 6.0!" + } + else { + "Have you run a background job today (start-job)?" + } } $scriptname = $MyInvocation.MyCommand.Path psversion "Done $scriptname." +``` -To start, set a breakpoint at a point of interest in the script, such -as a line, command, variable, or function. +To start, set a breakpoint at a point of interest in the script, such as a +line, command, variable, or function. -Start by creating a line breakpoint on the first line of the Test.ps1 -script in the current directory. +Start by creating a line breakpoint on the first line of the Test.ps1 script +in the current directory. +```powershell PS C:\ps-test> set-psbreakpoint -line 1 -script test.ps1 +``` You can abbreviate this command as: +```powershell PS C:\ps-test> spb 1 -s test.ps1 +``` The command returns a line-breakpoint object (System.Management.Automation.LineBreakpoint). +``` Column : 0 Line : 1 Action : @@ -515,150 +531,181 @@ HitCount : 0 Id : 0 Script : C:\ps-test\test.ps1 ScriptName : C:\ps-test\test.ps1 +``` Now, start the script. +```powershell PS C:\ps-test> .\test.ps1 +``` -When the script reaches the first breakpoint, the breakpoint message -indicates that the debugger is active. It describes the breakpoint and -previews the first line of the script, which is a function declaration. -The command prompt also changes to indicate that the debugger has -control. +When the script reaches the first breakpoint, the breakpoint message indicates +that the debugger is active. It describes the breakpoint and previews the +first line of the script, which is a function declaration. The command prompt +also changes to indicate that the debugger has control. -The preview line includes the script name and the line number of the -previewed command. +The preview line includes the script name and the line number of the previewed +command. +```powershell Entering debug mode. Use h or ? for help. Hit Line breakpoint on 'C:\ps-test\test.ps1:1' test.ps1:1 function psversion { # DBG> +``` +Use the Step command (s) to execute the first statement in the script and to +preview the next statement. The next statement uses the $MyInvocation +automatic variable to set the value of the $ScriptName variable to the path +and file name of the script file. -Use the Step command (s) to execute the first statement in the script -and to preview the next statement. The next statement uses the -$MyInvocation automatic variable to set the value of the $ScriptName -variable to the path and file name of the script file. - +```powershell DBG> s test.ps1:11 $scriptname = $MyInvocation.MyCommand.Path +``` -At this point, the $ScriptName variable is not populated, but you can +At this point, the \$ScriptName variable is not populated, but you can verify the value of the variable by displaying its value. In this case, -the value is $null. +the value is \$null. +```powershell DBG> $scriptname # DBG> - +``` Use another Step command (s) to execute the current statement and to preview the next statement in the script. The next statement calls the PsVersion function. +```powershell DBG> s test.ps1:12 psversion +``` At this point, the $ScriptName variable is populated, but you verify the value of the variable by displaying its value. In this case, the value is set to the script path. +```powershell DBG> $scriptname C:\ps-test\test.ps1 +``` Use another Step command to execute the function call. Press ENTER, or type "s" for Step. +```powershell DBG> s test.ps1:2 "Windows PowerShell " + $psversiontable.psversion +``` -The debug message includes a preview of the statement in the function. -To execute this statement and to preview the next statement in the -function, you can use a Step command. But, in this case, use a StepOut -command (o). It completes the execution of the function (unless it -reaches a breakpoint) and steps to the next statement in the script. +The debug message includes a preview of the statement in the function. To +execute this statement and to preview the next statement in the function, you +can use a Step command. But, in this case, use a StepOut command (o). It +completes the execution of the function (unless it reaches a breakpoint) and +steps to the next statement in the script. +```powershell DBG> o Windows PowerShell 2.0 Have you run a background job today (start-job)? test.ps1:13 "Done $scriptname" +``` -Because we are on the last statement in the script, the Step, StepOut, -and Continue commands have the same effect. In this case, use -StepOut (o). +Because we are on the last statement in the script, the Step, StepOut, and +Continue commands have the same effect. In this case, use StepOut (o). +```powershell Done C:\ps-test\test.ps1 PS C:\ps-test> +``` -The StepOut command executes the last command. The standard command -prompt indicates that the debugger has exited and returned control to the -command processor. +The StepOut command executes the last command. The standard command prompt +indicates that the debugger has exited and returned control to the command +processor. -Now, run the debugger again. First, to delete the current -breakpoint, use the Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. -(If you think you might reuse the breakpoint, use the -Disable-PsBreakpoint cmdlet instead of Remove-PsBreakpoint.) +Now, run the debugger again. First, to delete the current breakpoint, use the +Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. (If you think you might +reuse the breakpoint, use the Disable-PsBreakpoint cmdlet instead of +Remove-PsBreakpoint.) +```powershell PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint +``` You can abbreviate this command as: +```powershell PS C:\ps-test> gbp | rbp +``` Or, run the command by writing a function, such as the following function: +```powershell function delbr { gbp | rbp } +``` -Now, create a breakpoint on the $scriptname variable. +Now, create a breakpoint on the \$scriptname variable. +```powershell PS C:\ps-test> set-psbreakpoint -variable scriptname -script test.ps1 +``` You can abbreviate the command as: +```powershell PS C:\ps-test> sbp -v scriptname -s test.ps1 +``` Now, start the script. The script reaches the variable breakpoint. The default mode is Write, so execution stops just before the statement that changes the value of the variable. +```powershell PS C:\ps-test> .\test.ps1 Hit Variable breakpoint on 'C:\ps-test\test.ps1:$scriptname' (Write access) test.ps1:11 $scriptname = $MyInvocation.mycommand.path # DBG> +``` +Display the current value of the \$scriptname variable, which is \$null. -Display the current value of the $scriptname variable, which -is $null. - +```powershell DBG> $scriptname # DBG> +``` +Use a Step command (s) to execute the statement that populates the variable. +Then, display the new value of the \$scriptname variable. -Use a Step command (s) to execute the statement that populates -the variable. Then, display the new value of the $scriptname -variable. - +```powershell DBG> $scriptname C:\ps-test\test.ps1 +```powershell Use a Step command (s) to preview the next statement in the script. +```powershell DBG> s test.ps1:12 psversion +``` -The next statement is a call to the PsVersion function. To skip the -function but still execute it, use a StepOver command (v). If you are -already in the function when you use StepOver, it is not effective. The -function call is displayed, but it is not executed. +The next statement is a call to the PsVersion function. To skip the function +but still execute it, use a StepOver command (v). If you are already in the +function when you use StepOver, it is not effective. The function call is +displayed, but it is not executed. +```powershell DBG> v Windows PowerShell 2.0 Have you run a background job today (start-job)? test.ps1:13 "Done $scriptname" +``` The StepOver command executes the function, and it previews the next statement in the script, which prints the final line. @@ -666,42 +713,50 @@ statement in the script, which prints the final line. Use a Stop command (t) to exit the debugger. The command prompt reverts to the standard command prompt. +```powershell C:\ps-test> +``` To delete the breakpoints, use the Get-PsBreakpoint and Remove-PsBreakpoint cmdlets. +```powershell PS C:\ps-test> Get-PsBreakpoint | Remove-PSBreakpoint +``` Create a new command breakpoint on the PsVersion function. +```powershell PS C:\ps-test> Set-PsBreakpoint -command psversion -script test.ps1 +``` You can abbreviate this command to: +```powershell PS C:\ps-test> sbp -c psversion -s test.ps1 +``` Now, run the script. +```powershell PS C:\ps-test> .\test.ps1 Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion' test.ps1:12 psversion # DBG> +``` - -The script reaches the breakpoint at the function call. At this point, -the function has not yet been called. This gives you the opportunity -to use the Action parameter of Set-PsBreakpoint to set conditions for -the execution of the breakpoint or to perform preparatory or diagnostic -tasks, such as starting a log or invoking a diagnostic or security -script. +The script reaches the breakpoint at the function call. At this point, the +function has not yet been called. This gives you the opportunity to use the +Action parameter of Set-PsBreakpoint to set conditions for the execution of +the breakpoint or to perform preparatory or diagnostic tasks, such as starting +a log or invoking a diagnostic or security script. To set an action, use a Continue command (c) to exit the script, and a -Remove-PsBreakpoint command to delete the current breakpoint. -(Breakpoints are read-only, so you cannot add an action to the current -breakpoint.) +Remove-PsBreakpoint command to delete the current breakpoint. (Breakpoints are +read-only, so you cannot add an action to the current breakpoint.) +```powershell DBG> c Windows PowerShell 2.0 Have you run a background job today (start-job)? @@ -709,104 +764,102 @@ Done C:\ps-test\test.ps1 PS C:\ps-test> get-psbreakpoint | remove-psbreakpoint PS C:\ps-test> +``` -Now, create a new command breakpoint with an action. The following -command sets a command breakpoint with an action that logs the value -of the $scriptname variable when the function is called. Because the -Break keyword is not used in the action, execution does not stop. (The -backtick (`) is the line-continuation character.) +Now, create a new command breakpoint with an action. The following command +sets a command breakpoint with an action that logs the value of the +\$scriptname variable when the function is called. Because the Break keyword is +not used in the action, execution does not stop. (The backtick (`) is the +line-continuation character.) +```powershell PS C:\ps-test> set-psbreakpoint -command psversion -script test.ps1 ` -action { add-content "The value of `$scriptname is $scriptname." ` -path action.log} +``` -You can also add actions that set conditions for the breakpoint. In -the following command, the command breakpoint is executed only if the -execution policy is set to RemoteSigned, the most restrictive policy -that still permits you to run scripts. (The backtick (`) is the -continuation character.) +You can also add actions that set conditions for the breakpoint. In the +following command, the command breakpoint is executed only if the execution +policy is set to RemoteSigned, the most restrictive policy that still permits +you to run scripts. (The backtick (`) is the continuation character.) +```powershell PS C:\ps-test> set-psbreakpoint -script test.ps1 -command psversion ` -action { if ((get-executionpolicy) -eq "RemoteSigned") { break }} +``` The Break keyword in the action directs the debugger to execute the -breakpoint. You can also use the Continue keyword to direct the debugger -to execute without breaking. Because the default keyword is Continue, -you must specify Break to stop execution. +breakpoint. You can also use the Continue keyword to direct the debugger to +execute without breaking. Because the default keyword is Continue, you must +specify Break to stop execution. Now, run the script. +```powershell PS C:\ps-test> .\test.ps1 Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion' test.ps1:12 psversion +```powershell Because the execution policy is set to RemoteSigned, execution stops at the function call. -At this point, you might want to check the call stack. Use the -Get-PsCallStack cmdlet or the Get-PsCallStack debugger command (k). -The following command gets the current call stack. +At this point, you might want to check the call stack. Use the Get-PsCallStack +cmdlet or the Get-PsCallStack debugger command (k). The following command gets +the current call stack. +```powershell DBG> k 2: prompt 1: .\test.ps1: $args=[] 0: prompt: $args=[] +``` This example demonstrates just a few of the many ways to use the Windows PowerShell debugger. -For more information about the debugger cmdlets, type the following -command: +For more information about the debugger cmdlets, type the following command: +```powershell help -full +``` For example, type: +```powershell help set-psbreakpoint -full +``` -Other Debugging Features in Windows PowerShell +## Other Debugging Features in Windows PowerShell In addition to the Windows PowerShell debugger, Windows PowerShell includes several other features that you can use to debug scripts and functions. --- Windows PowerShell Integrated Scripting Environment (ISE) includes -an interactive graphical debugger. For more information, start Windows -PowerShell ISE and press F1. - --- The Set-PSDebug cmdlet offers very basic script debugging features, -including stepping and tracing. - --- Use the Set-StrictMode cmdlet to detect references to -uninitialized variables, to references to non-existent properties -of an object, and to function syntax that is not valid. - --- Add diagnostic statements to a script, such as statements that -display the value of variables, statements that read input from -the command line, or statements that report the current -instruction. Use the cmdlets that contain the Write verb for -this task, such as Write-Host, Write-Debug, Write-Warning, and -Write-Verbose. - -# SEE ALSO - -Disable-PsBreakpoint - -Enable-PsBreakpoint - -Get-PsBreakpoint - -Get-PsCallStack - -Remove-PsBreakpoint - -Set-PsBreakpoint - -Set-PsDebug - -Set-Strictmode - -Write-Debug - -Write-Verbose - +- Windows PowerShell Integrated Scripting Environment (ISE) includes an + interactive graphical debugger. For more information, start PowerShell ISE + and press F1. + +- The Set-PSDebug cmdlet offers very basic script debugging features, + including stepping and tracing. + +- Use the Set-StrictMode cmdlet to detect references to uninitialized + variables, to references to non-existent properties of an object, and to + function syntax that is not valid. + +- Add diagnostic statements to a script, such as statements that display the + value of variables, statements that read input from the command line, or + statements that report the current instruction. Use the cmdlets that contain + the Write verb for this task, such as Write-Host, Write-Debug, Write-Warning, + and Write-Verbose. + +## SEE ALSO + +- [Disable-PsBreakpoint](../../Microsoft.PowerShell.Utility/Disable-PsBreakpoint.md) +- [Enable-PsBreakpoint](../../Microsoft.PowerShell.Utility/Enable-PsBreakpoint.md) +- [Get-PsBreakpoint](../../Microsoft.PowerShell.Utility/Get-PsBreakpoint.md) +- [Get-PsCallStack](../../Microsoft.PowerShell.Utility/Get-PsCallStack.md) +- [Remove-PsBreakpoint](../../Microsoft.PowerShell.Utility/Remove-PsBreakpoint.md) +- [Set-PsBreakpoint](../../Microsoft.PowerShell.Utility/Set-PsBreakpoint.md) +- [Write-Debug](../../Microsoft.PowerShell.Utility/Write-Debug.md) +- [Write-Verbose](../../Microsoft.PowerShell.Utility/Write-Verbose.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md index 3e4a5424b207..fbcfc30ca802 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,77 +7,72 @@ title: about_Functions_Advanced_Methods --- # About Functions Advanced Methods -## about_Functions_Advanced_Methods +## SHORT DESCRIPTION -# SHORT DESCRIPTION - -Describes how functions that specify the `CmdletBinding` attribute can use -the methods and properties that are available to compiled cmdlets. +Describes how functions that specify the `CmdletBinding` attribute can use the +methods and properties that are available to compiled cmdlets. # LONG DESCRIPTION Functions that specify the `CmdletBinding` attribute can access a number of -methods and properties through the `$pscmdlet` variable. These methods -include the following methods: +methods and properties through the `$pscmdlet` variable. These methods include +the following methods: - Input-processing methods that compiled cmdlets use to do their work. - - The `ShouldProcess` and `ShouldContinue` methods that are used to get -user feedback before an action is performed. - + user feedback before an action is performed. - The `ThrowTerminatingError` method for generating error records. - - Several Write methods that return different types of output. All the methods and properties of the `PSCmdlet` class are available to -advanced functions. For more information about these methods and -properties, see `System.Management.Automation.PSCmdlet` in the MSDN -(Microsoft Developer Network) library at -http://go.microsoft.com/fwlink/?LinkId=142139. - -# Input Processing Methods - -The methods described in this section are referred to as the input -processing methods. For functions, these three methods are represented -by the `Begin`, `Process`, and `End` blocks of the function. Each function -must include one or more of these blocks. The Windows PowerShell runtime -uses the code within these blocks when it is running a function. (These -blocks are also available to functions that do not use the `CmdletBinding` -attribute.) - -## Begin +advanced functions. For more information about these methods and properties, +see `System.Management.Automation.PSCmdlet` in the MSDN (Microsoft Developer +Network) library at http://go.microsoft.com/fwlink/?LinkId=142139. + +### Input Processing Methods + +The methods described in this section are referred to as the input processing +methods. For functions, these three methods are represented by the `Begin`, +`Process`, and `End` blocks of the function. Each function must include one or +more of these blocks. The Windows PowerShell runtime uses the code within +these blocks when it is running a function. (These blocks are also available +to functions that do not use the `CmdletBinding` attribute.) + +#### Begin + This block is used to provide optional one-time preprocessing for the -function. The Windows PowerShell runtime uses the code in this block one -time for each instance of the function in the pipeline. - -## Process -This block is used to provide record-by-record processing for the -function. This block might be used any number of times, or not at all, -depending on the input to the function. For example, if the function is -the first command in the pipeline, the `Process` block will be used one -time. If the function is not the first command in the pipeline, the -`Process` block is used one time for every input that the function -receives from the pipeline. If there is no pipeline input, the `Process` -block is not used. - -This block must be defined if a function parameter is set to accept -pipeline input. If this block is not defined and the parameter accepts -input from the pipeline, the function will miss the values that are -passed to the function through the pipeline. +function. The Windows PowerShell runtime uses the code in this block one time +for each instance of the function in the pipeline. + +#### Process + +This block is used to provide record-by-record processing for the function. +This block might be used any number of times, or not at all, depending on the +input to the function. For example, if the function is the first command in +the pipeline, the `Process` block will be used one time. If the function is +not the first command in the pipeline, the `Process` block is used one time +for every input that the function receives from the pipeline. If there is no +pipeline input, the `Process` block is not used. + +This block must be defined if a function parameter is set to accept pipeline +input. If this block is not defined and the parameter accepts input from the +pipeline, the function will miss the values that are passed to the function +through the pipeline. Also, when the function supports confirmation requests (when the `SupportsShouldProcess` parameter of the Parameter attribute is set to -`$True`), the call to the `ShouldProcess` method must be made from within -the Process block. +`$True`), the call to the `ShouldProcess` method must be made from within the +Process block. + +#### End -## End -This block is used to provide optional one-time post-processing for -the function. +This block is used to provide optional one-time post-processing for the +function. -The following example shows the outline of a function that contains a -`Begin` block for one-time preprocessing, a `Process` block for multiple -record processing, and an `End` block for one-time post-processing. +The following example shows the outline of a function that contains a `Begin` +block for one-time preprocessing, a `Process` block for multiple record +processing, and an `End` block for one-time post-processing. ```powershell Function Test-ScriptCmdlet @@ -90,119 +85,125 @@ Function Test-ScriptCmdlet } ``` -# Confirmation Methods +### Confirmation Methods + +#### ShouldProcess -## ShouldProcess This method is called to request confirmation from the user before the -function performs an action that would change the system. The function -can continue based on the Boolean value returned by the method. This -method can be called only from within the `Process{}` block of the -function. And, the `CmdletBinding` attribute must declare that the -function supports `ShouldProcess` (as shown in the previous example). +function performs an action that would change the system. The function can +continue based on the Boolean value returned by the method. This method can be +called only from within the `Process{}` block of the function. And, the +`CmdletBinding` attribute must declare that the function supports +`ShouldProcess` (as shown in the previous example). For more information about this method, see -`System.Management.Automation.Cmdlet.ShouldProcess` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142142. +[`System.Management.Automation.Cmdlet.ShouldProcess`](http://go.microsoft.com/fwlink/?LinkId=142142) +in the MSDN library. For more information about how to request confirmation, see -"Requesting Confirmation" in the MSDN library at -http://go.microsoft.com/fwlink/?LinkID=136658. +[Requesting Confirmation](http://go.microsoft.com/fwlink/?LinkID=136658) +in the MSDN library. + +#### ShouldContinue -## ShouldContinue -This method is called to request a second confirmation message. It -should be called when the `ShouldProcess` method returns `$true`. For more -information about this method, see -`System.Management.Automation.Cmdlet.ShouldContinue` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142143. +This method is called to request a second confirmation message. It should be +called when the `ShouldProcess` method returns `$true`. For more information +about this method, see `System.Management.Automation.Cmdlet.ShouldContinue` in +the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142143. -# Error Methods +### Error Methods Functions can call two different methods when errors occur. When a -nonterminating error occurs, the function should call the `WriteError` -method, which is described in the "Write Methods" section. When a -terminating error occurs and the function cannot continue, it should call -the `ThrowTerminatingError` method. You can also use the `Throw` statement for +nonterminating error occurs, the function should call the `WriteError` method, +which is described in the "Write Methods" section. When a terminating error +occurs and the function cannot continue, it should call the +`ThrowTerminatingError` method. You can also use the `Throw` statement for terminating errors and the `Write-Error` cmdlet for nonterminating errors. -For more information, see `System.Management.Automation.Cmdlet.ThrowTerminatingError` -in the MSDN libray at -http://go.microsoft.com/fwlink/?LinkId=142144. +For more information, see +[`System.Management.Automation.Cmdlet.ThrowTerminatingError`](http://go.microsoft.com/fwlink/?LinkId=142144) +in the MSDN libray. -# Write Methods +### Write Methods -A function can call the following methods to return different types of -output. Notice that not all the output goes to the next command in the -pipeline. You can also use the various Write cmdlets, such as -Write-Error. +A function can call the following methods to return different types of output. +Notice that not all the output goes to the next command in the pipeline. You +can also use the various Write cmdlets, such as Write-Error. + +#### WriteCommandDetail -## WriteCommandDetail For information about the `WriteCommandDetails` method, see -`System.Management.Automation.Cmdlet.WriteCommandDetail` in the MSDN -library at http://go.microsoft.com/fwlink/?LinkId=142155. - -## WriteDebug -To provide information that can be used to troubleshoot a function, -make the function call the `WriteDebug` method. This displays debug -messages to the user. For more information, see -`System.Management.Automation.Cmdlet.WriteDebug` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142156. - -## WriteError -Functions should call this method when nonterminating errors occur and -the function is designed to continue processing records. For more -information, see `System.Management.Automation.Cmdlet.WriteError` in the -MSDN library at http://go.microsoft.com/fwlink/?LinkId=142157. +[`System.Management.Automation.Cmdlet.WriteCommandDetail`](http://go.microsoft.com/fwlink/?LinkId=142155) +in the MSDN library. + +#### WriteDebug + +To provide information that can be used to troubleshoot a function, make the +function call the `WriteDebug` method. This displays debug messages to the +user. For more information, see +[`System.Management.Automation.Cmdlet.WriteDebug`](http://go.microsoft.com/fwlink/?LinkId=142156) +in the MSDN library. + +#### WriteError + +Functions should call this method when nonterminating errors occur and the +function is designed to continue processing records. For more information, see +[`System.Management.Automation.Cmdlet.WriteError`](http://go.microsoft.com/fwlink/?LinkId=142157) +in the MSDN library. Note: If a terminating error occurs, the function should call the `ThrowTerminatingError` method. -## WriteObject -This method allows the function to send an object to the next command in -the pipeline. In most cases, this is the method to use when the function -returns data. For more information, see -`System.Management.Automation.PSCmdlet.WriteObject` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142158. - -## WriteProgress -For functions whose actions take a long time to complete, this method -allows the function to call the `WriteProgress` method so that progress -information is displayed. For example, you can display the percent -completed. For more information, see -`System.Management.Automation.PSCmdlet.WriteProgress` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142160. - -## WriteVerbose -To provide detailed information about what the function is doing, make -the function call the `WriteVerbose` method to display verbose messages to -the user. By default, verbose messages are not displayed. For more -information, see `System.Management.Automation.PSCmdlet.WriteVerbose` -in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142162. - -## WriteWarning -To provide information about conditions that may cause unexpected -results, make the function call the WriteWarning method to display -warning messages to the user. By default, warning messages are displayed. -For more information, see -`System.Management.Automation.PSCmdlet.WriteWarning` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142164. +#### WriteObject + +This method allows the function to send an object to the next command in the +pipeline. In most cases, this is the method to use when the function returns +data. For more information, see +[`System.Management.Automation.PSCmdlet.WriteObject`](http://go.microsoft.com/fwlink/?LinkId=142158) +in the MSDN library. + +#### WriteProgress + +For functions whose actions take a long time to complete, this method allows +the function to call the `WriteProgress` method so that progress information +is displayed. For example, you can display the percent completed. For more +information, see [`System.Management.Automation.PSCmdlet.WriteProgress`](http://go.microsoft.com/fwlink/?LinkId=142160) +in the MSDN library. + +#### WriteVerbose + +To provide detailed information about what the function is doing, make the +function call the `WriteVerbose` method to display verbose messages to the +user. By default, verbose messages are not displayed. For more information, +see +[`System.Management.Automation.PSCmdlet.WriteVerbose`](http://go.microsoft.com/fwlink/?LinkId=142162) +in the MSDN library. + +#### WriteWarning + +To provide information about conditions that may cause unexpected results, +make the function call the WriteWarning method to display warning messages to +the user. By default, warning messages are displayed. For more information, +see [`System.Management.Automation.PSCmdlet.WriteWarning`](http://go.microsoft.com/fwlink/?LinkId=142164) +in the MSDN library. Note: You can also display warning messages by configuring the `WarningPreference` variable or by using the `Verbose` and `Debug` command-line options. -# Other Methods and Properties +### Other Methods and Properties For information about the other methods and properties that can be accessed through the `$PSCmdlet` variable, see -`System.Management.Automation.PSCmdlet` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142139. +[`System.Management.Automation.PSCmdlet`](http://go.microsoft.com/fwlink/?LinkId=142139) +in the MSDN library. For example, the `ParameterSetName` property allows you to see the parameter set that is being used. Parameter sets allow you to create a function that -performs different tasks based on the parameters that are specified when -the function is run. +performs different tasks based on the parameters that are specified when the +function is run. -# SEE ALSO +## SEE ALSO [about_Functions](about_Functions.md) @@ -213,4 +214,3 @@ the function is run. [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) [about_Functions_OutputTypeAttribute](about_Functions_OutputTypeAttribute.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md index 546fe9f1e0aa..f5f40dd0d876 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,13 @@ title: about_Functions_OutputTypeAttribute --- # About Functions OutputTypeAttribute -## about_Functions_OutputTypeAttribute - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes an attribute that reports the type of object that the function returns. -# LONG DESCRIPTION +## LONG DESCRIPTION The OutputType attribute lists the .NET types of objects that the functions returns. You can use its optional ParameterSetName parameter to list different @@ -32,25 +30,27 @@ The OutputType attribute value is only a documentation note. It is not derived from the function code or compared to the actual function output. As such, the value might be inaccurate. -# SYNTAX +## SYNTAX The OutputType attribute of functions has the following syntax: -```powershell +``` [OutputType([], ParameterSetName="")] [OutputType("", ParameterSetName="")] ``` + The ParameterSetName parameter is optional. You can list multiple types in the OutputType attribute. -```powershell +``` [OutputType([],[],[])] ``` + You can use the ParameterSetName parameter to indicate that different parameter sets return different types. -```powershell +``` [OutputType([], ParameterSetName="","")] [OutputType([], ParameterSetName="")] ``` @@ -80,9 +80,11 @@ function AdvancedFunction1 [OutputType([])] Param ( [parameter(Mandatory=$true)] - [String[]] $Parameter1 + [String[]] + $Parameter1 ) - + + } @@ -92,16 +94,17 @@ function AdvancedFunction2 [OutputType([])] Param ( [parameter(Mandatory=$true)] - [String[]] $Parameter1 + [String[]] + $Parameter1 ) + } ``` # EXAMPLES - The following function uses the OutputType attribute to indicate that it returns a string value. @@ -111,13 +114,13 @@ function Send-Greeting [OutputType([String])] Param ($Name) - Hello, $Name + "Hello, $Name" } ``` To see the resulting output type property, use the Get-Command cmdlet. -```bash +``` PS C:> (Get-Command Send-Greeting).OutputType Name Type @@ -139,12 +142,15 @@ function Get-User Param ( [parameter(Mandatory=$true, ParameterSetName="ID")] - [Int[]] $UserID, + [Int[]] + $UserID, [parameter(Mandatory=$true, ParameterSetName="Name")] - [String[]] $UserName + [String[]] + $UserName ) + } ``` @@ -160,19 +166,18 @@ that it returns a System.DateTime object. function Get-Time { [OutputType([DateTime])] - Param - ( + Param ( [parameter(Mandatory=$true)] - [Datetime] $DateTime + [Datetime]$DateTime ) - + $DateTime.ToShortTimeString() } ``` The Get-Type method confirms that the function returns a string. -```bash +``` PS C:> (Get-Time -DateTime (Get-Date)).Gettype().FullName System.String ``` @@ -180,7 +185,7 @@ System.String However, the OutputType property, which gets its value from the OutputType attribute, reports that the function returns a DateTime object. -```bash +``` PS C:> (Get-Command Get-Time).OutputType Name Type @@ -188,7 +193,7 @@ Name Type System.DateTime System.DateTime ``` -# NOTES +## NOTES The value of the OutputType property of a FunctionInfo object is an array of System.Management.Automation.PSTypeName objects, each of which have Name and @@ -216,4 +221,3 @@ of an object. [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md) [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Keywords.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Keywords.md index 4588722728a4..a8db7aa4cd39 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Keywords.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Language_Keywords.md @@ -584,7 +584,7 @@ Syntax: do {} while () ``` -# SEE ALSO +## SEE ALSO - [about_Special_Characters](about_Special_Characters.md) - [about_Wildcards](about_Wildcards.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSessions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSessions.md index 196d7fddf1b9..a96bb8e474f6 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSessions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSessions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,63 +10,120 @@ title: about_PSSessions ## Short Description -Describes Windows PowerShell sessions (PSSessions) and explains how to establish a persistent connection to a remote computer. +Describes Windows PowerShell sessions (PSSessions) and explains how to +establish a persistent connection to a remote computer. ## Long Description -To run Windows PowerShell commands on a remote computer, you can use the **ComputerName** parameter of a cmdlet, or you can create a Windows PowerShell session (PSSession) and run commands in the PSSession. +To run Windows PowerShell commands on a remote computer, you can use the +**ComputerName** parameter of a cmdlet, or you can create a Windows PowerShell +session (PSSession) and run commands in the PSSession. -When you create a PSSession, Windows PowerShell establishes a persistent connection to the remote computer. Use a PSSession to run a series of related commands on a remote computer. Commands that run in the same PSSession can share data, such as the values of variables, aliases, and functions. +When you create a PSSession, Windows PowerShell establishes a persistent +connection to the remote computer. Use a PSSession to run a series of related +commands on a remote computer. Commands that run in the same PSSession can +share data, such as the values of variables, aliases, and functions. -You can also create a PSSession on the local computer and run commands in it. A local PSSession uses the Windows PowerShell remoting infrastructure to create and maintain the PSSession. +You can also create a PSSession on the local computer and run commands in it. +A local PSSession uses the Windows PowerShell remoting infrastructure to +create and maintain the PSSession. -Beginning in Windows PowerShell 3.0, PSSessions are independent of the sessions in which they are created. Active PSSessions are maintained on the remote computer (or the computer at the remote end or "server-side" of the connection). As a result, you can disconnect from the PSSession and reconnect to it at a later time from the same computer or from a different computer. +Beginning in Windows PowerShell 3.0, PSSessions are independent of the +sessions in which they are created. Active PSSessions are maintained on the +remote computer (or the computer at the remote end or "server-side" of the +connection). As a result, you can disconnect from the PSSession and reconnect +to it at a later time from the same computer or from a different computer. -This topic explains how to create, use, get, and delete PSSessions. For more advanced information, see [about_PSSession_Details](about_PSSession_Details.md). +This topic explains how to create, use, get, and delete PSSessions. For more +advanced information, see +[about_PSSession_Details](about_PSSession_Details.md). -Note: PSSessions use the Windows PowerShell remoting infrastructure. To use PSSessions, the local and remote computers must be configured for remoting. For more information, see [about_Remote_Requirements](about_Remote_Requirements.md). +Note: PSSessions use the Windows PowerShell remoting infrastructure. To use +PSSessions, the local and remote computers must be configured for remoting. +For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). -In Windows Vista and later versions of Windows, to create a PSSession on a local computer, you must start Windows PowerShell with the "Run as administrator" option. +In Windows Vista and later versions of Windows, to create a PSSession on a +local computer, you must start Windows PowerShell with the "Run as +administrator" option. ## What Is a Session? A session is an environment in which Windows PowerShell runs. -Each time you start Windows PowerShell, a session is created for you, and you can run commands in the session. You can also add items to your session, such as modules and snap-ins, and you can create items, such as variables, functions, and aliases. These items exist only in the session and are deleted when the session ends. - -You can also create user-managed sessions, known as " Windows PowerShell sessions" or "PSSessions," on the local computer or on a remote computer. Like the default session, you can run commands in a PSSession and add and create items. - -However, unlike the session that starts automatically, you can control the PSSessions that you create. You can get, create, configure, and remove them, disconnect and reconnect to them, and run multiple commands in the same PSSession. The PSSession remains available until you delete it or it times out. - -Typically, you create a PSSession to run a series of related commands on a remote computer. When you create a PSSession on a remote computer, Windows PowerShell establishes a persistent connection to the remote computer to support the session. - -If you use the **ComputerName** parameter of the `Invoke-Command` or `Enter-PSSession` cmdlet to run a remote command or to start an interactive session, Windows PowerShell creates a temporary session on the remote computer and closes the session as soon as the command is complete or as soon as the interactive session ends. You cannot control these temporary sessions, and you cannot use them for more than a single command or a single interactive session. - -In Windows PowerShell, the "current session" is the session that you are working in. The "current session" can refer to any session, including a temporary session or a PSSession. +Each time you start Windows PowerShell, a session is created for you, and you +can run commands in the session. You can also add items to your session, such +as modules and snap-ins, and you can create items, such as variables, +functions, and aliases. These items exist only in the session and are deleted +when the session ends. + +You can also create user-managed sessions, known as " Windows PowerShell +sessions" or "PSSessions," on the local computer or on a remote computer. Like +the default session, you can run commands in a PSSession and add and create +items. However, unlike the session that starts automatically, you can control +the PSSessions that you create. You can get, create, configure, and remove +them, disconnect and reconnect to them, and run multiple commands in the same +PSSession. The PSSession remains available until you delete it or it times +out. + +Typically, you create a PSSession to run a series of related commands on a +remote computer. When you create a PSSession on a remote computer, Windows +PowerShell establishes a persistent connection to the remote computer to +support the session. + +If you use the **ComputerName** parameter of the `Invoke-Command` or +`Enter-PSSession` cmdlet to run a remote command or to start an interactive +session, Windows PowerShell creates a temporary session on the remote computer +and closes the session as soon as the command is complete or as soon as the +interactive session ends. You cannot control these temporary sessions, and you +cannot use them for more than a single command or a single interactive +session. + +In Windows PowerShell, the "current session" is the session that you are +working in. The "current session" can refer to any session, including a +temporary session or a PSSession. ## Why Use a PSSession? -Use a PSSession when you need a persistent connection to a remote computer. With a PSSession, you can run a series of commands that share data, such as the value of variables, the contents of a function, or the definition of an alias. +Use a PSSession when you need a persistent connection to a remote computer. +With a PSSession, you can run a series of commands that share data, such as +the value of variables, the contents of a function, or the definition of an +alias. -You can run remote commands without creating a PSSession. Use the **ComputerName** parameter of remote-enabled cmdlets to run a single command or a series of unrelated commands on one or many computers. +You can run remote commands without creating a PSSession. Use the +**ComputerName** parameter of remote-enabled cmdlets to run a single command +or a series of unrelated commands on one or many computers. -When you use the **ComputerName** parameter of `Invoke-Command` or `Enter-PSSession`, Windows PowerShell establishes a temporary connection to the remote computer and then closes the connection as soon as the command is complete. Any data elements that you create are lost when the connection is closed. +When you use the **ComputerName** parameter of `Invoke-Command` or +`Enter-PSSession`, Windows PowerShell establishes a temporary connection to +the remote computer and then closes the connection as soon as the command is +complete. Any data elements that you create are lost when the connection is +closed. -Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` and `Get-WmiObject`, use different remoting technologies to gather data. None create a persistent connection like a PSSession. +Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` +and `Get-WmiObject`, use different remoting technologies to gather data. None +create a persistent connection like a PSSession. ## How to Create a PSSession -To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession on a remote computer, use the **ComputerName** parameter of the `New-PSSession` cmdlet. +To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession +on a remote computer, use the **ComputerName** parameter of the +`New-PSSession` cmdlet. -For example, the following command creates a new PSSession on the Server01 computer. +For example, the following command creates a new PSSession on the Server01 +computer. ```powershell New-PSSession -ComputerName Server01 ``` -When you submit the command, `New-PSSession` creates the PSSession and returns an object that represents the PSSession. You can save the object in a variable when you create the PSSession, or you can use a `Get-PSSession` command to get the PSSession at a later time. +When you submit the command, `New-PSSession` creates the PSSession and returns +an object that represents the PSSession. You can save the object in a variable +when you create the PSSession, or you can use a `Get-PSSession` command to get +the PSSession at a later time. -For example, the following command creates a new PSSession on the Server01 computer and saves the resulting object in the $ps variable. +For example, the following command creates a new PSSession on the Server01 +computer and saves the resulting object in the $ps variable. ```powershell $ps = New-PSSession -ComputerName Server01 @@ -74,9 +131,12 @@ $ps = New-PSSession -ComputerName Server01 ## How to Create PSSessions on Multiple Computers -To create PSSessions on multiple computers, use the **ComputerName** parameter of the `New-PSSession` cmdlet. Type the names of the remote computers in a comma-separated list. +To create PSSessions on multiple computers, use the **ComputerName** parameter +of the `New-PSSession` cmdlet. Type the names of the remote computers in a +comma-separated list. -For example, to create PSSessions on the Server01, Server02, and Server03 computers, type: +For example, to create PSSessions on the Server01, Server02, and Server03 +computers, type: ```powershell New-PSSession -ComputerName Server01, Server02, Server03 @@ -86,7 +146,9 @@ New-PSSession -ComputerName Server01, Server02, Server03 ## How to Get PSSessions -To get the PSSessions that were created in your current session, use the `Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` returns the same type of object that `New-PSSession` returns. +To get the PSSessions that were created in your current session, use the +`Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` +returns the same type of object that `New-PSSession` returns. The following command gets all the PSSessions that were created in the current session. @@ -94,9 +156,10 @@ The following command gets all the PSSessions that were created in the current s Get-PSSession ``` -The default display of the PSSessions shows their ID and a default display name. You can assign an alternate display name when you create the session. +The default display of the PSSessions shows their ID and a default display +name. You can assign an alternate display name when you create the session. -``` +```output Id Name ComputerName State ConfigurationName --- ---- ------------ ----- --------------------- 1 Session1 Server01 Opened Microsoft.PowerShell @@ -104,31 +167,45 @@ Id Name ComputerName State ConfigurationName 3 Session3 Server03 Opened Microsoft.PowerShell ``` -You can also save the PSSessions in a variable. The following command gets the PSSessions and saves them in the $ps123 variable. +You can also save the PSSessions in a variable. The following command gets the +PSSessions and saves them in the \$ps123 variable. ```powershell $ps123 = Get-PSSession ``` -When using the PSSession cmdlets, you can refer to a PSSession by its ID, by its name, or by its instance ID (a GUID). The following command gets a PSSession by its ID and saves it in the $ps01 variable. +When using the PSSession cmdlets, you can refer to a PSSession by its ID, by +its name, or by its instance ID (a GUID). The following command gets a +PSSession by its ID and saves it in the \$ps01 variable. ```powershell $ps01 = Get-PSSession -Id 1 ``` -Beginning in Windows PowerShell 3.0, PSSessions are maintained on the remote computer. To get PSSessions that you created on particular remote computers, use the **ComputerName** parameter of the `Get-PSSession` cmdlet. The following command gets the PSSessions that you created on the Server01 remote computer. This includes PSSessions created in the current session and in other sessions on the local computer or other computers. +Beginning in Windows PowerShell 3.0, PSSessions are maintained on the remote +computer. To get PSSessions that you created on particular remote computers, +use the **ComputerName** parameter of the `Get-PSSession` cmdlet. The +following command gets the PSSessions that you created on the Server01 remote +computer. This includes PSSessions created in the current session and in other +sessions on the local computer or other computers. ```powershell Get-PSSession -ComputerName Server01 ``` -In Windows PowerShell 2.0, `Get-PSSession` gets only the PSSessions that were created in the current session. It does not get PSSessions that were created in other sessions or on other computers, even if the sessions are connected to and are running commands on the local computer. +In Windows PowerShell 2.0, `Get-PSSession` gets only the PSSessions that were +created in the current session. It does not get PSSessions that were created +in other sessions or on other computers, even if the sessions are connected to +and are running commands on the local computer. ## How to Run Commands in a PSSession -To run a command in one or more PSSessions, use the `Invoke-Command` cmdlet. Use the Session parameter to specify the PSSessions and the **ScriptBlock** parameter to specify the command. +To run a command in one or more PSSessions, use the `Invoke-Command` cmdlet. +Use the Session parameter to specify the PSSessions and the **ScriptBlock** +parameter to specify the command. -For example, to run a `Get-ChildItem` ("dir") command in each of the three PSSessions saved in the $ps123 variable, type: +For example, to run a `Get-ChildItem` ("dir") command in each of the three +PSSessions saved in the $ps123 variable, type: ```powershell Invoke-Command -Session $ps123 -ScriptBlock { Get-ChildItem } @@ -136,7 +213,8 @@ Invoke-Command -Session $ps123 -ScriptBlock { Get-ChildItem } ## How to Delete PSSessions -When you are finished with the PSSession, use the `Remove-PSSession` cmdlet to delete the PSSession and to release the resources that it was using. +When you are finished with the PSSession, use the `Remove-PSSession` cmdlet to +delete the PSSession and to release the resources that it was using. ```powershell Remove-PSSession -Session $ps @@ -148,35 +226,38 @@ or Remove-PSSession -Id 1 ``` -To remove a PSSession from a remote computer, use the **ComputerName** parameter of the `Remove-PSSession` cmdlet. +To remove a PSSession from a remote computer, use the **ComputerName** +parameter of the `Remove-PSSession` cmdlet. ```powershell Remove-PSSession -ComputerName Server01 -Id 1 ``` -If you do not delete the PSSession, the PSSession remains available for use until it times out. +If you do not delete the PSSession, the PSSession remains available for use +until it times out. -You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` cmdlet to set an expiration time for an idle PSSession. For more information, see [New-PSSessionOption](../New-PSSessionOption.md). +You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` +cmdlet to set an expiration time for an idle PSSession. For more information, +see [New-PSSessionOption](../New-PSSessionOption.md). ## The PSSession Cmdlets -| Cmdlet | Description | -| -------------------- | --------------------------------------------------------------- | -| Connect-PSSession | Connects a PSSession to the current session | -| Disconnect-PSSession | Disconnects a PSSession from the current session | -| Enter-PSSession | Starts an interactive session | -| Exit-PSSession | Ends an interactive session | -| Get-PSSession | Gets the PSSessions in the current session | -| New-PSSession | Creates a new PSSession on a local or remote computer | -| Receive-PSSession | Gets the results of commands that ran in a disconnected session | -| Remove-PSSession | Deletes the PSSessions in the current session | - For a list of PSSession cmdlets, type: ```powershell Get-Help *-PSSession ``` +- Connect-PSSession: Connects a PSSession to the current session +- Disconnect-PSSession: Disconnects a PSSession from the current session +- Enter-PSSession: Starts an interactive session +- Exit-PSSession: Ends an interactive session +- Get-PSSession: Gets the PSSessions in the current session +- New-PSSession: Creates a new PSSession on a local or remote computer +- Receive-PSSession: Gets the results of commands that ran in a disconnected + session +- Remove-PSSession: Deletes the PSSessions in the current session + ## For More Information For more information about PSSessions, see [about_PSSession_Details](about_PSSession_Details.md). diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSnapins.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSnapins.md index bab6da6892d1..a30c4841c8e3 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSnapins.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSSnapins.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,175 +7,212 @@ title: about_PSSnapins --- # About PSSnapins -## about_PSSnapins - ## SHORT DESCRIPTION -Describes Windows PowerShell snap-ins and shows how to use and manage them. +Describes Windows PowerShell® snap-ins and shows how to use and manage them. ## LONG DESCRIPTION -A Windows PowerShell snap-in is a Microsoft .NET Framework assembly that contains Windows PowerShell providers and\/or cmdlets. Windows PowerShell includes a set of basic snap-ins, but you can extend the power and value of Windows PowerShell by adding snap-ins that contain providers and cmdlets that you create or get from others. -When you add a snap-in, the cmdlets and providers that it contains are immediately available for use in the current session, but the change affects only the current session. +A Windows PowerShell snap-in is a Microsoft .NET Framework assembly that +contains Windows PowerShell providers and\/or cmdlets. Windows PowerShell +includes a set of basic snap-ins, but you can extend the power and value of +Windows PowerShell by adding snap-ins that contain providers and cmdlets that +you create or get from others. -To add the snap-in to all future sessions, save it in your Windows PowerShell profile. You can also use the Export-Console cmdlet to save the snap-in names to a console file and then use it in future sessions. You can even save multiple console files, each with a different set of snap-ins. +When you add a snap-in, the cmdlets and providers that it contains are +immediately available for use in the current session, but the change affects +only the current session. -NOTE: Windows PowerShell snap-ins (PSSnapins) are available for use in Windows PowerShell 3.0 and Windows PowerShell 2.0. They might be altered or unavailable in subsequent versions. To package Windows PowerShell cmdlets and providers, use modules. For information about creating modules and converting snap-ins to modules, see "Writing a Windows PowerShell Module" in MSDN at http:\/\/go.microsoft.com\/fwlink\/?LinkID\=141556. +To add the snap-in to all future sessions, save it in your Windows PowerShell +profile. You can also use the Export-Console cmdlet to save the snap-in names +to a console file and then use it in future sessions. You can even save +multiple console files, each with a different set of snap-ins. +NOTE: Windows PowerShell snap-ins (PSSnapins) are available for use in Windows +PowerShell 3.0 and Windows PowerShell 2.0. They might be altered or +unavailable in subsequent versions. To package Windows PowerShell cmdlets and +providers, use modules. For information about creating modules and converting +snap-ins to modules, see [Writing a Windows PowerShell Module](http://go.microsoft.com/fwlink/?LinkID=141556) +in the MSDN library. ### FINDING SNAP-INS -To get a list of the Windows PowerShell snap-ins on your computer, type: +To get a list of the Windows PowerShell snap-ins on your computer, type: -``` +```powershell get-pssnapin ``` - To get the snap-in for each Windows PowerShell provider, type: - -``` +```powershell get-psprovider | format-list name, pssnapin ``` - To get a list of the cmdlets in a Windows PowerShell snap-in, type: - -``` +```powershell get-command -module ``` - - ### INSTALLING A SNAP-IN -The built-in snap-ins are registered in the system and added to the default session when you start Windows PowerShell. However, you have to register snap-ins that you create or obtain from others and then add the snap-ins to your session. +The built-in snap-ins are registered in the system and added to the default +session when you start Windows PowerShell. However, you have to register +snap-ins that you create or obtain from others and then add the snap-ins to +your session. ### REGISTERING A SNAP-IN -A Windows PowerShell snap-in is a program written in a .NET Framework language that is compiled into a .dll file. To use the providers and cmdlets in a snap-in, you must first register the snap-in (add it to the registry). -Most snap-ins include an installation program (an .exe or .msi file) that registers the .dll file for you. However, if you receive a snap-in as a .dll file, you can register it on your system. For more information, see [How to Register Cmdlets, Providers, and Host Applications](https://go.microsoft.com/fwlink/?LinkID=143619) in the MSDN library. +A Windows PowerShell snap-in is a program written in a .NET Framework language +that is compiled into a .dll file. To use the providers and cmdlets in a +snap-in, you must first register the snap-in (add it to the registry). -To get all the registered snap-ins on your system or to verify that a snap-in is registered, type: +Most snap-ins include an installation program (an .exe or .msi file) that +registers the .dll file for you. However, if you receive a snap-in as a .dll +file, you can register it on your system. For more information, see +[How to Register Cmdlets, Providers, and Host Applications](https://go.microsoft.com/fwlink/?LinkID=143619) +in the MSDN library. +To get all the registered snap-ins on your system or to verify that a snap-in +is registered, type: -``` +```powershell get-pssnapin -registered ``` - - ### ADDING THE SNAP-IN TO THE CURRENT SESSION -To add a registered snap-in to the current session, use the Add-PsSnapin cmdlet. For example, to add the Microsoft SQL Server snap-in to the session, type: +To add a registered snap-in to the current session, use the Add-PsSnapin +cmdlet. For example, to add the Microsoft SQL Server snap-in to the session, +type: -``` +```powershell add-pssnapin sql ``` - -After the command is completed, the providers and cmdlets in the snap-in are available in the session. However, they are available only in the current session unless you save them. - +After the command is completed, the providers and cmdlets in the snap-in are +available in the session. However, they are available only in the current +session unless you save them. ### SAVING THE SNAP-INS -To use a snap-in in future Windows PowerShell sessions, add the Add-PsSnapin command to your Windows PowerShell profile. Or, export the snap-in names to a console file. -If you add the Add-PSSnapin command to your profile, it is available in all future Windows PowerShell sessions. If you export the names of the snap-ins in your session, you can use the export file only when you need the snap-ins. +To use a snap-in in future Windows PowerShell sessions, add the Add-PsSnapin +command to your Windows PowerShell profile. Or, export the snap-in names to a +console file. -To add the Add-PsSnapin command to your Windows PowerShell profile, open your profile, paste or type the command, and then save the profile. For more information, see about_Profiles. +If you add the Add-PSSnapin command to your profile, it is available in all +future Windows PowerShell sessions. If you export the names of the snap-ins in +your session, you can use the export file only when you need the snap-ins. -To save the snap-ins from a session in console file (.psc1), use the Export-Console cmdlet. For example, to save the snap-ins in the current session configuration to the NewConsole.psc1 file in the current directory, type: +To add the Add-PsSnapin command to your Windows PowerShell profile, open your +profile, paste or type the command, and then save the profile. For more +information, see about_Profiles. +To save the snap-ins from a session in console file (.psc1), use the +Export-Console cmdlet. For example, to save the snap-ins in the current +session configuration to the NewConsole.psc1 file in the current directory, +type: -``` +```powershell export-console NewConsole ``` - For more information, see Export-Console. - ### OPENING WINDOWS POWERSHELL WITH A CONSOLE FILE -To use a console file that includes the snap-in, start Windows PowerShell (PowerShell.exe) from the command prompt in Cmd.exe or in another Windows PowerShell session. Use the PsConsoleFile parameter to specify the console file that includes the snap-in. For example, the following command starts Windows PowerShell with the NewConsole.psc1 console file: +To use a console file that includes the snap-in, start Windows PowerShell +(PowerShell.exe) from the command prompt in Cmd.exe or in another Windows +PowerShell session. Use the PsConsoleFile parameter to specify the console +file that includes the snap-in. For example, the following command starts +Windows PowerShell with the NewConsole.psc1 console file: -``` +```powershell PowerShell.exe -psconsolefile NewConsole.psc1 ``` - The providers and cmdlets in the snapin are now available for use in the session. - ### REMOVING A SNAP-IN -To remove a Windows PowerShell snap-in from the current session, use the Remove-PsSnapin cmdlet. For example, to remove the SQL Server snap-in from the current session, type: +To remove a Windows PowerShell snap-in from the current session, use the +Remove-PsSnapin cmdlet. For example, to remove the SQL Server snap-in from the +current session, type: -``` +```powershell remove-pssnapin sql ``` - -This cmdlet removes the snap-in from the session. The snap-in is still loaded, but the providers and cmdlets that it supports are no longer available. - +This cmdlet removes the snap-in from the session. The snap-in is still loaded, +but the providers and cmdlets that it supports are no longer available. ### BUILT-IN COMMANDS -In Windows PowerShell 2.0 and in older-style host programs in Windows PowerShell 3.0 and later, the built-in commands that are installed with Windows PowerShell are packaged in snap-ins that are added automatically to every Windows PowerShell session. - -Beginning in Windows PowerShell 3.0, in newer-style host programs -- those that start sessions by using the InitialSessionState.CreateDefault2 method -- the built-in commands are packaged in modules. The exception is Microsoft.PowerShell.Core, which always appears as a snap-in. The Core snap-in is included in every session by default. The built-in modules are loaded automatically on first-use. -NOTE: Remote sessions, including sessions that are started by using the New-PSSession cmdlet, are older-style sessions in which the built-in commands are packaged in snap-ins. +In Windows PowerShell 2.0 and in older-style host programs in Windows +PowerShell 3.0 and later, the built-in commands that are installed with +Windows PowerShell are packaged in snap-ins that are added automatically to +every Windows PowerShell session. -The following snap-ins (or modules) are installed with Windows PowerShell. - -Microsoft.PowerShell.Core - -Contains providers and cmdlets used to manage the basic features of Windows PowerShell. It includes the FileSystem, Registry, Alias, Environment, Function, and Variable providers and basic cmdlets like Get-Help, Get-Command, and Get-History. - -Microsoft.PowerShell.Host - -Contains cmdlets used by the Windows PowerShell host, such as Start-Transcript and Stop-Transcript. +Beginning in Windows PowerShell 3.0, in newer-style host programs -- those +that start sessions by using the InitialSessionState.CreateDefault2 method -- +the built-in commands are packaged in modules. The exception is +Microsoft.PowerShell.Core, which always appears as a snap-in. The Core snap-in +is included in every session by default. The built-in modules are loaded +automatically on first-use. -Microsoft.PowerShell.Management +NOTE: Remote sessions, including sessions that are started by using the +New-PSSession cmdlet, are older-style sessions in which the built-in commands +are packaged in snap-ins. -Contains cmdlets such as Get-Service and Get-ChildItem that are used to manage Windows-based features. - -Microsoft.PowerShell.Security +The following snap-ins (or modules) are installed with Windows PowerShell. -Contains the Certificate provider and cmdlets used to manage Windows PowerShell security, such as Get-Acl, Get-AuthenticodeSignature, and ConvertTo-SecureString. +- Microsoft.PowerShell.Core - Contains providers and cmdlets used to manage + the basic features of Windows PowerShell. It includes the FileSystem, + Registry, Alias, Environment, Function, and Variable providers and basic + cmdlets like Get-Help, Get-Command, and Get-History. -Microsoft.PowerShell.Utility +- Microsoft.PowerShell.Host - Contains cmdlets used by the Windows PowerShell + host, such as Start-Transcript and Stop-Transcript. -Contains cmdlets used to manipulate objects and data, such as Get-Member, Write-Host, and Format-List. +- Microsoft.PowerShell.Management - Contains cmdlets such as Get-Service and + Get-ChildItem that are used to manage Windows-based features. -Microsoft.WSMan.Management +- Microsoft.PowerShell.Security - Contains the Certificate provider and + cmdlets used to manage Windows PowerShell security, such as Get-Acl, + Get-AuthenticodeSignature, and ConvertTo-SecureString. -Contains the WSMan provider and cmdlets that manage the Windows Remote Management service, such as Connect-WSMan and Enable-WSManCredSSP. +- Microsoft.PowerShell.Utility - Contains cmdlets used to manipulate objects + and data, such as Get-Member, Write-Host, and Format-List. +- Microsoft.WSMan.Management - Contains the WSMan provider and cmdlets that + manage the Windows Remote Management service, such as Connect-WSMan and + Enable-WSManCredSSP. ## LOGGING SNAP-IN EVENTS -Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets in Windows PowerShell modules and snap-ins by setting the LogPipelineExecutionDetails property of modules and snap-ins to TRUE. For more information, see about_EventLogs (http:\/\/go.microsoft.com\/fwlink\/?LinkID\=113224). +Beginning in Windows PowerShell 3.0, you can record execution events for the +cmdlets in Windows PowerShell modules and snap-ins by setting the +LogPipelineExecutionDetails property of modules and snap-ins to TRUE. For more +information, see [about_EventLogs](about_EventLogs.md). ## SEE ALSO -Add-PsSnapin +[Add-PsSnapin](../Add-PsSnapin.md) -Get-PsSnapin +[Get-PsSnapin](../Get-PsSnapin.md) -Remove-PsSnapin +[Remove-PsSnapin](../Remove-PsSnapin.md) -Export-Console +[Export-Console](../Export-Console.md) -Get-Command +[Get-Command](../Get-Command.md) [about_Profiles](about_Profiles.md) [about_Modules](about_Modules.md) -## KEYWORDS: -about_Snapins, about_Snap_ins, about_Snap-ins +## KEYWORDS +about_Snapins, about_Snap_ins, about_Snap-ins diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_PackageManagement.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_PackageManagement.md index 7933f7f0a80e..32789dca75ab 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_PackageManagement.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_PackageManagement.md @@ -104,24 +104,24 @@ For more information about the PackageManagement open development project, including how to create a PackageManagement package provider, see the PackageManagement project on GitHub at https://oneget.org. -# SEE ALSO +## SEE ALSO -Get-PackageProvider +[Get-PackageProvider](../../PackageManagement/Get-PackageProvider.md) -Get-PackageSource +[Get-PackageSource](../../PackageManagement/Get-PackageSource.md) -Register-PackageSource +[Register-PackageSource](../../PackageManagement/Register-PackageSource.md) -Set-PackageSource +[Set-PackageSource](../../PackageManagement/Set-PackageSource.md) -Unregister-PackageSource +[Unregister-PackageSource](../../PackageManagement/Unregister-PackageSource.md) -Get-Package +[Get-Package](../../PackageManagement/Get-Package.md) -Find-Package +[Find-Package](../../PackageManagement/Find-Package.md) -Install-Package +[Install-Package](../../PackageManagement/Install-Package.md) -Save-Package +[Save-Package](../../PackageManagement/Save-Package.md) -Uninstall-Package +[Uninstall-Package](../../PackageManagement/Uninstall-Package.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters.md index 37c6f1b3c26e..b74b7e5b0cb0 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,197 +7,227 @@ title: about_Parameters --- # About Parameters -## about_Parameters - ## SHORT DESCRIPTION -Describes how to work with command parameters in Windows PowerShell. +Describes how to work with command parameters in PowerShell. ## LONG DESCRIPTION -Most Windows PowerShell commands, such as cmdlets, functions, and scripts, rely on parameters to allow users to select options or provide input. The parameters follow the command name and have the following form: +Most PowerShell commands, such as cmdlets, functions, and scripts, +rely on parameters to allow users to select options or provide input. The +parameters follow the command name and have the following form: ``` - ``` +The name of the parameter is preceded by a hyphen (-), which signals to +Windows PowerShell that the word following the hyphen is a parameter name. +Some parameters do not require or accept a parameter value. Other parameters +require a value, but do not require the parameter name in the command. -The name of the parameter is preceded by a hyphen (-), which signals to Windows PowerShell that the word following the hyphen is a parameter name. Some parameters do not require or accept a parameter value. Other parameters require a value, but do not require the parameter name in the command. - -The type of parameters and the requirements for those parameters vary. To find information about the parameters of a command, use the Get-Help cmdlet. For example, to find information about the parameters of the Get-ChildItem cmdlet, type: +The type of parameters and the requirements for those parameters vary. To find +information about the parameters of a command, use the Get-Help cmdlet. For +example, to find information about the parameters of the Get-ChildItem cmdlet, +type: -``` +```powershell Get-Help Get-ChildItem ``` +To find information about the parameters of a script, use the full path to the +script file. For example: -To find information about the parameters of a script, use the full path to the script file. For example: - - -``` +```powershell Get-Help $home\Documents\Scripts\Get-Function.ps1 ``` +The Get-Help cmdlet returns various details about the command, including a +description, the command syntax, information about the parameters, and +examples showing how to use the parameters in a command. -The Get-Help cmdlet returns various details about the command, including a description, the command syntax, information about the parameters, and examples showing how to use the parameters in a command. - -You can also use the Parameter parameter of the Get-Help cmdlet to find information about a particular parameter. Or, you can use the Parameter parameter with the wildcard character (\*) value to find information about all parameters of the command. For example, the following command gets information about all parameters of the Get-Member cmdlet: +You can also use the Parameter parameter of the Get-Help cmdlet to find +information about a particular parameter. Or, you can use the Parameter +parameter with the wildcard character (\*) value to find information about all +parameters of the command. For example, the following command gets information +about all parameters of the Get-Member cmdlet: -``` +```powershell Get-Help Get-Member -Parameter * ``` ### DEFAULT PARAMETER VALUES -Optional parameters have a default value, which is the value that is used or assumed when the parameter is not specified in the command. -For example, the default value of the ComputerName parameter of many cmdlets is the name of the local computer. As a result, the local computer name is used in the command unless the ComputerName parameter is specified. +Optional parameters have a default value, which is the value that is used or +assumed when the parameter is not specified in the command. -To find the default parameter value, see help topic for the cmdlet. The parameter description should include the default value. +For example, the default value of the ComputerName parameter of many cmdlets +is the name of the local computer. As a result, the local computer name is +used in the command unless the ComputerName parameter is specified. -You can also set a custom default value for any parameter of a cmdlet or advanced function. For information about setting custom default values, see about_Parameters_Default_Values. +To find the default parameter value, see help topic for the cmdlet. The +parameter description should include the default value. +You can also set a custom default value for any parameter of a cmdlet or +advanced function. For information about setting custom default values, see +[about_Parameters_Default_Values](about_Parameters_Default_Values.md). ### PARAMETER ATTRIBUTE TABLE -When you use the Full, Parameter, or Online parameters of the Get-Help cmdlet, Get-Help displays a parameter attribute table with detailed information about the parameter. -This information includes the details you need to know to use the parameter. For example, the help topic for the Get-ChildItem cmdlet includes the following details about its Path parameter: +When you use the Full, Parameter, or Online parameters of the Get-Help cmdlet, +Get-Help displays a parameter attribute table with detailed information about +the parameter. + +This information includes the details you need to know to use the parameter. +For example, the help topic for the Get-ChildItem cmdlet includes the +following details about its Path parameter: ``` --path - Specifies a path of one or more locations. Wildcard characters are +-path + Specifies a path of one or more locations. Wildcard characters are permitted. The default location is the current directory (.). -``` - - -``` -Required? false -Position? 1 -Default value Current directory -Accept pipeline input? true (ByValue, ByPropertyName) +Required? false +Position? 1 +Default value Current directory +Accept pipeline input? true (ByValue, ByPropertyName) Accept wildcard characters? true ``` +The parameter information includes the parameter syntax, a description of the +parameter, and the parameter attributes. The following sections describe the +parameter attributes. -The parameter information includes the parameter syntax, a description of the parameter, and the parameter attributes. The following sections describe the parameter attributes. +#### Parameter Required? -Parameter Required? +This setting indicates whether the parameter is mandatory, that is, whether +all commands that use this cmdlet must include this parameter. When the value +is "True" and the parameter is missing from the command, Windows PowerShell +prompts you for a value for the parameter. -This setting indicates whether the parameter is mandatory, that is, whether all commands that use this cmdlet must include this parameter. When the value is "True" and the parameter is missing from the command, Windows PowerShell prompts you for a value for the parameter. +#### Parameter Position? -Parameter Position? +This setting indicates whether you can supply a parameter's value without +preceding it with the parameter name. If set to "0" or "named," a parameter +name is required. This type of parameter is referred to as a named parameter. +A named parameter can be listed in any position after the cmdlet name. -This setting indicates whether you can supply a parameter's value without preceding it with the parameter name. If set to "0" or "named," a parameter name is required. This type of parameter is referred to as a named parameter. A named parameter can be listed in any position after the cmdlet name. +If the "Parameter position?" setting is set to an integer other than 0, the +parameter name is not required. This type of parameter is referred to as a +positional parameter, and the number indicates the position in which the +parameter must appear in relation to other positional parameters. If you +include the parameter name for a positional parameter, the parameter can be +listed in any position after the cmdlet name. -If the "Parameter position?" setting is set to an integer other than 0, the parameter name is not required. This type of parameter is referred to as a positional parameter, and the number indicates the position in which the parameter must appear in relation to other positional parameters. If you include the parameter name for a positional parameter, the parameter can be listed in any position after the cmdlet name. +For example, the Get-ChildItem cmdlet has Path and Exclude parameters. The +"Parameter position?" setting for Path is 1, which means that it is a +positional parameter. The "Parameter position?" setting for Exclude is 0, +which means that it is a named parameter. -For example, the Get-ChildItem cmdlet has Path and Exclude parameters. The "Parameter position?" setting for Path is 1, which means that it is a positional parameter. The "Parameter position?" setting for Exclude is 0, which means that it is a named parameter. +This means that Path does not require the parameter name, but its parameter +value must be the first or only unnamed parameter value in the command. +However, because the Exclude parameter is a named parameter, you can place it +in any position in the command. -This means that Path does not require the parameter name, but its parameter value must be the first or only unnamed parameter value in the command. However, because the Exclude parameter is a named parameter, you can place it in any position in the command. +As a result of the "Parameter position?" settings for these two parameters, +you can use any of the following commands: -As a result of the "Parameter position?" settings for these two parameters, you can use any of the following commands: - -``` -Get-ChildItem -path c:\techdocs -exclude *.ppt -Get-ChildItem c:\techdocs -exclude *.ppt -Get-ChildItem -exclude *.ppt -path c:\techdocs +```powershell +Get-ChildItem -path c:\techdocs -exclude *.ppt +Get-ChildItem c:\techdocs -exclude *.ppt +Get-ChildItem -exclude *.ppt -path c:\techdocs Get-ChildItem -exclude *.ppt c:\techdocs ``` +If you were to include another positional parameter without including the +parameter name, that parameter would have to be placed in the order specified +by the "Parameter position?" setting. -If you were to include another positional parameter without including the parameter name, that parameter would have to be placed in the order specified by the "Parameter position?" setting. +#### Parameter Type -Parameter Type +This setting specifies the Microsoft .NET Framework type of the parameter +value. For example, if the type is Int32, the parameter value must be an +integer. If the type is string, the parameter value must be a character +string. If the string contains spaces, the value must be enclosed in quotation +marks, or the spaces must be preceded by the escape character (`). -This setting specifies the Microsoft .NET Framework type of the parameter value. For example, if the type is Int32, the parameter value must be an integer. If the type is string, the parameter value must be a character string. If the string contains spaces, the value must be enclosed in quotation marks, or the spaces must be preceded by the escape character (`). +#### Default Value -Default Value +This setting specifies the value that the parameter will assume if no other +value is provided. For example, the default value of the Path parameter is +often the current directory. Required parameters never have a default value. +For many optional parameters, there is no default because the parameter has no +effect if it is not used. -This setting specifies the value that the parameter will assume if no other value is provided. For example, the default value of the Path parameter is often the current directory. Required parameters never have a default value. For many optional parameters, there is no default because the parameter has no effect if it is not used. +#### Accepts Multiple Values? -Accepts Multiple Values? +This setting indicates whether a parameter accepts multiple parameter values. +When a parameter accepts multiple values, you can type a comma-separated list +as the value of the parameter in the command, or save a comma-separated list +(an array) in a variable, and then specify the variable as the parameter +value. -This setting indicates whether a parameter accepts multiple parameter values. When a parameter accepts multiple values, you can type a comma-separated list as the value of the parameter in the command, or save a comma-separated list (an array) in a variable, and then specify the variable as the parameter value. +For example, the ServiceName parameter of the Get-Service cmdlet accepts +multiple values. The following commands are both valid: -For example, the ServiceName parameter of the Get-Service cmdlet accepts multiple values. The following commands are both valid: - - -``` +```powershell get-service -servicename winrm, netlogon ``` - - -``` -$s = "winrm", "netlogon" +```powershell +$s = "winrm", "netlogon" get-service -servicename $s ``` +#### Accepts Pipeline Input? -Accepts Pipeline Input? - -This setting indicates whether you can use the pipeline operator (|) to send a value to the parameter. - +This setting indicates whether you can use the pipeline operator (|) to +send a value to the parameter. ``` -Value Description ------ ----------- -False Indicates that you cannot pipe a value to the +Value Description +----- ----------- +False Indicates that you cannot pipe a value to the parameter. -``` - - -``` -True (by Value) Indicates that you can pipe any value to the - parameter, just so the value has the .NET - Framework type specified for the parameter or the - value can be converted to the specified .NET +True (by Value) Indicates that you can pipe any value to the + parameter, just so the value has the .NET + Framework type specified for the parameter or the + value can be converted to the specified .NET Framework type. ``` - - -``` -When a parameter is "True (by Value)", Windows -PowerShell tries to associate any piped values -with that parameter before it tries other methods -to interpret the command. -``` - - +When a parameter is "True (by Value)", Windows PowerShell tries to associate +any piped values with that parameter before it tries other methods to +interpret the command. ``` -True (by Property Name) Indicates that you can pipe a value to the - parameter, but the .NET Framework type of the - parameter must include a property with the same +True (by Property Name) Indicates that you can pipe a value to the + parameter, but the .NET Framework type of the + parameter must include a property with the same name as the parameter. ``` +For example, you can pipe a value to a Name parameter only when the value has +a property called "Name". +#### Accepts Wildcard Characters? -``` -For example, you can pipe a value to a Name -parameter only when the value has a property -called "Name". -``` - - -Accepts Wildcard Characters? - -This setting indicates whether the parameter's value can contain wildcard characters so that the parameter value can be matched to more than one existing item in the target container. +This setting indicates whether the parameter's value can contain wildcard +characters so that the parameter value can be matched to more than one +existing item in the target container. -Common Parameters - -Common parameters are parameters that you can use with any cmdlet. For more information about common parameters, see about_CommonParameters +#### Common Parameters +Common parameters are parameters that you can use with any cmdlet. For more +information about common parameters, see [about_CommonParameters](about_CommonParameters.md). ## SEE ALSO @@ -212,4 +242,3 @@ Common parameters are parameters that you can use with any cmdlet. For more info [about_Pipelines](about_Pipelines.md) [about_Wildcards](about_Wildcards.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md index be2c22398e80..39bf01d2725e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,21 +7,20 @@ title: about_PowerShell_exe --- # About PowerShell.exe -## about_PowerShell.exe +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use the PowerShell.exe command-line tool. Displays the syntax +and describes the command-line switches. -Explains how to use the PowerShell.exe command-line tool. Displays -the syntax and describes the command-line switches. +PowerShell.exe starts a Windows PowerShell session. You can use it in Cmd.exe +and in Windows PowerShell. -PowerShell.exe starts a Windows PowerShell session. You can use it -in Cmd.exe and in Windows PowerShell. +## LONG DESCRIPTION -# LONG DESCRIPTION - -# SYNTAX +### SYNTAX +``` PowerShell[.exe] [-EncodedCommand ] [-ExecutionPolicy ] @@ -39,137 +38,143 @@ PowerShell[.exe] [-Command { - | [-args ] | [] } ] PowerShell[.exe] -Help | -? | /? +``` + +### PARAMETERS + +#### -EncodedCommand + +Accepts a base-64-encoded string version of a command. Use this parameter to +submit commands to Windows PowerShell that require complex quotation marks or +curly braces. + +#### -ExecutionPolicy + +Sets the default execution policy for the current session and saves it in the +$env:PSExecutionPolicyPreference environment variable. This parameter does not +change the Windows PowerShell execution policy that is set in the registry. +For information about Windows PowerShell execution policies, including a list +of valid values, see [about_Execution_Policies](about_Execution_Policies.md). + +#### -File [] + +Runs the specified script in the local scope ("dot-sourced"), so that the +functions and variables that the script creates are available in the current +session. Enter the script file path and any parameters. File must be the last +parameter in the command, because all characters typed after the File +parameter name are interpreted as the script file path followed by the script +parameters. + +You can include the parameters of a script, and parameter values, in the value +of the File parameter. For example: -File .\\Get-Script.ps1 -Domain Central + +Typically, the switch parameters of a script are either included or omitted. +For example, the following command uses the All parameter of the +Get-Script.ps1 script file: -File .\\Get-Script.ps1 -All + +In rare cases, you might need to provide a Boolean value for a switch +parameter. To provide a Boolean value for a switch parameter in the value of +the File parameter, enclose the parameter name and value in curly braces, such +as the following: -File .\\Get-Script.ps1 {-All:$False}. + +#### -InputFormat {Text | XML} + +Describes the format of data sent to Windows PowerShell. Valid values are +"Text" (text strings) or "XML" (serialized CLIXML format). + +#### -Mta + +Starts Windows PowerShell using a multi-threaded apartment. This parameter is +introduced in Windows PowerShell 3.0. In Windows PowerShell 2.0, +multi-threaded apartment (MTA) is the default. In Windows PowerShell 3.0, +single-threaded apartment (STA) is the default. + +#### -NoExit -# PARAMETERS - - --EncodedCommand -Accepts a base-64-encoded string version of a command. -Use this parameter to submit commands to Windows PowerShell -that require complex quotation marks or curly braces. - --ExecutionPolicy -Sets the default execution policy for the current session -and saves it in the $env:PSExecutionPolicyPreference environment -variable. This parameter does not change the Windows PowerShell -execution policy that is set in the registry. For information -about Windows PowerShell execution policies, including a list -of valid values, see about_Execution_Policies -(http://go.microsoft.com/fwlink/?LinkID=135170). - --File [] -Runs the specified script in the local scope ("dot-sourced"), -so that the functions and variables that the script creates -are available in the current session. Enter the script file -path and any parameters. File must be the last parameter in -the command, because all characters typed after the File -parameter name are interpreted as the script file path followed -by the script parameters. - -You can include the parameters of a script, and parameter -values, in the value of the File parameter. For example: --File .\Get-Script.ps1 -Domain Central - -Typically, the switch parameters of a script are either -included or omitted. For example, the following command -uses the All parameter of the Get-Script.ps1 script file: --File .\Get-Script.ps1 -All - -In rare cases, you might need to provide a Boolean value -for a switch parameter. To provide a Boolean value for a -switch parameter in the value of the File parameter, -enclose the parameter name and value in curly braces, -such as the following: --File .\Get-Script.ps1 {-All:$False}. - --InputFormat {Text | XML} -Describes the format of data sent to Windows PowerShell. Valid -values are "Text" (text strings) or "XML" (serialized CLIXML format). - --Mta -Starts Windows PowerShell using a multi-threaded apartment. This -parameter is introduced in Windows PowerShell 3.0. In Windows -PowerShell 2.0, multi-threaded apartment (MTA) is the default. -In Windows PowerShell 3.0, single-threaded apartment (STA) is -the default. - --NoExit Does not exit after running startup commands. --NoLogo +#### -NoLogo + Hides the copyright banner at startup. --NonInteractive +#### -NonInteractive + Does not present an interactive prompt to the user. --NoProfile +#### -NoProfile + Does not load the Windows PowerShell profile. --OutputFormat {Text | XML} -Determines how output from Windows PowerShell is formatted. -Valid values are "Text" (text strings) or "XML" (serialized -CLIXML format). - --PSConsoleFile -Loads the specified Windows PowerShell console file. Enter -the path and name of the console file. To create a console file, -use the Export-Console cmdlet in Windows PowerShell. - --Sta -Starts Windows PowerShell using a single-threaded apartment. In -Windows PowerShell 2.0, multi-threaded apartment (MTA) is the default. -In Windows PowerShell 3.0, single-threaded apartment (STA) is the -default. - --Version -Starts the specified version of Windows PowerShell. Valid values -are 2.0 and 3.0. The version that you specify must be installed -on the system. If Windows PowerShell 3.0 is installed on the -computer, "3.0" is the default version. Otherwise, "2.0" is the -default version. For more information, see "Installing Windows -PowerShell" in the Windows PowerShell Getting Started Guide. - --WindowStyle -Sets the window style for the session. Valid values are Normal, -Minimized, Maximized and Hidden. - --Command -Executes the specified commands (and any parameters) as though -they were typed at the Windows PowerShell command prompt, and -then exits, unless the NoExit parameter is specified. - -The value of Command can be "-", a string. or a script block. If -the value of Command is "-", the command text is read from standard -input. - -Script blocks must be enclosed in braces ({}). You can specify a -script block only when running PowerShell.exe in Windows PowerShell. -The results of the script are returned to the parent shell as -deserialized XML objects, not live objects. - -If the value of Command is a string, Command must be the last -parameter in the command , because any characters typed after -the command are interpreted as the command arguments. +#### -OutputFormat {Text | XML} + +Determines how output from Windows PowerShell is formatted. Valid values are +"Text" (text strings) or "XML" (serialized CLIXML format). + +#### -PSConsoleFile + +Loads the specified Windows PowerShell console file. Enter the path and name +of the console file. To create a console file, use the Export-Console cmdlet +in Windows PowerShell. + +#### -Sta + +Starts Windows PowerShell using a single-threaded apartment. In Windows +PowerShell 2.0, multi-threaded apartment (MTA) is the default. In Windows +PowerShell 3.0, single-threaded apartment (STA) is the default. + +#### -Version + +Starts the specified version of Windows PowerShell. Valid values are 2.0 and +3.0. The version that you specify must be installed on the system. If Windows +PowerShell 3.0 is installed on the computer, "3.0" is the default version. +Otherwise, "2.0" is the default version. For more information, see "Installing +Windows PowerShell" in the Windows PowerShell Getting Started Guide. + +#### -WindowStyle + +Sets the window style for the session. Valid values are Normal, Minimized, +Maximized and Hidden. + +#### -Command + +Executes the specified commands (and any parameters) as though they were typed +at the Windows PowerShell command prompt, and then exits, unless the NoExit +parameter is specified. + +The value of Command can be "-", a string. or a script block. If the value of +Command is "-", the command text is read from standard input. + +Script blocks must be enclosed in braces ({}). You can specify a script block +only when running PowerShell.exe in Windows PowerShell. The results of the +script are returned to the parent shell as deserialized XML objects, not live +objects. + +If the value of Command is a string, Command must be the last parameter in the +command , because any characters typed after the command are interpreted as +the command arguments. To write a string that runs a Windows PowerShell command, use the format: + "& {}" -where the quotation marks indicate a string and the invoke operator -(&) causes the command to be executed. --Help, -?, /? -Displays help for PowerShell.exe. If you are typing a PowerShell.exe -command in Windows PowerShell, prepend the command parameters with a -hyphen (-), not a forward slash (/). You can use either a hyphen or -forward slash in Cmd.exe. +where the quotation marks indicate a string and the invoke operator (&) causes +the command to be executed. + +#### -Help, -?, /? -# REMARKS: +Displays help for PowerShell.exe. If you are typing a PowerShell.exe command +in Windows PowerShell, prepend the command parameters with a hyphen (-), not a +forward slash (/). You can use either a hyphen or forward slash in Cmd.exe. -Troubleshooting note: In Windows PowerShell 2.0, starting some programs -from the Windows PowerShell console fails with a LastExitCode of 0xc0000142. +### REMARKS -# EXAMPLES +Troubleshooting note: In Windows PowerShell 2.0, starting some programs from +the Windows PowerShell console fails with a LastExitCode of 0xc0000142. +### EXAMPLES + +```powershell PowerShell -PSConsoleFile sqlsnapin.psc1 PowerShell -Version 2.0 -NoLogo -InputFormat text -OutputFormat XML @@ -177,4 +182,4 @@ PowerShell -Version 2.0 -NoLogo -InputFormat text -OutputFormat XML PowerShell -Command {Get-EventLog -LogName security} PowerShell -Command "& {Get-EventLog -LogName security}" - +``` \ No newline at end of file diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Providers.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Providers.md index 063ae703a6be..8080f77944b9 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Providers.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Providers.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,61 +7,58 @@ title: about_Providers --- # About Providers -## about_Providers - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes how Windows PowerShell providers provide access to data and -components that would not otherwise be easily accessible at the command -line. The data is presented in a consistent format that resembles a file -system drive. - -# LONG DESCRIPTION - -Windows PowerShell providers are Microsoft .NET Framework-based programs -that make the data in a specialized data store available in Windows -PowerShell so that you can view and manage it. - -The data that a provider exposes appears in a drive, and you access the -data in a path like you would on a hard disk drive. You can use any of the -built-in cmdlets that the provider supports to manage the data in the -provider drive. And, you can use custom cmdlets that are designed -especially for the data. - -The providers can also add dynamic parameters to the built-in cmdlets. -These are parameters that are available only when you use the cmdlet with -the provider data. - -# BUILT-IN PROVIDERS - -Windows PowerShell includes a set of built-in providers that you can use -to access the different types of data stores. - -| Provider | Drive | Data store | -| ----------- | ------------ | ------------------------------------------ | -| Alias | Alias: | Windows PowerShell aliases | -| Certificate | Cert: | x509 certificates for digital signatures | -| Environment | Env: | Windows environment variables | -| FileSystem | (*) | File system drives, directories, and files | -| Function | Function: | Windows PowerShell functions | -| Registry | HKLM:, HKCU: | Windows registry | -| Variable | Variable: | Windows PowerShell variables | -| WSMan | WSMan: | WS-Management configuration information | +components that would not otherwise be easily accessible at the command line. +The data is presented in a consistent format that resembles a file system +drive. + +## LONG DESCRIPTION + +Windows PowerShell providers are Microsoft .NET Framework-based programs that +make the data in a specialized data store available in Windows PowerShell so +that you can view and manage it. + +The data that a provider exposes appears in a drive, and you access the data +in a path like you would on a hard disk drive. You can use any of the built-in +cmdlets that the provider supports to manage the data in the provider drive. +And, you can use custom cmdlets that are designed especially for the data. + +The providers can also add dynamic parameters to the built-in cmdlets. These +are parameters that are available only when you use the cmdlet with the +provider data. + +## BUILT-IN PROVIDERS + +Windows PowerShell includes a set of built-in providers that you can use to +access the different types of data stores. + +|Provider |Drive |Data store | +|------------|-------------|-------------------------------------------| +|Alias |Alias: |Windows PowerShell aliases | +|Certificate |Cert: |x509 certificates for digital signatures | +|Environment |Env: |Windows environment variables | +|FileSystem |(*) |File system drives, directories, and files | +|Function |Function: |Windows PowerShell functions | +|Registry |HKLM:, HKCU: |Windows registry | +|Variable |Variable: |Windows PowerShell variables | +|WSMan |WSMan: |WS-Management configuration information | (*) The FileSystem drives vary on each system. -You can also create your own Windows PowerShell providers, and you can -install providers that others develop. To list the providers that are -available in your session, type: +You can also create your own Windows PowerShell providers, and you can install +providers that others develop. To list the providers that are available in +your session, type: -Get-PSProvider +get-psprovider -# INSTALLING AND REMOVING PROVIDERS +## INSTALLING AND REMOVING PROVIDERS Windows PowerShell providers are delivered to you in Windows PowerShell -modules, which are .NET Framework-based programs that are compiled -into .dll files. The snap-ins can include providers and cmdlets. +snap-ins, which are .NET Framework-based programs that are compiled into .dll +files. The snap-ins can include providers and cmdlets. Before you use the provider features, you have to install the snap-in and then add it to your Windows PowerShell session. For more information, see @@ -69,103 +66,106 @@ about_PSSnapins. You cannot uninstall a provider, although you can remove the Windows PowerShell snap-in for the provider from the current session. If you do, -you remove all the contents of the snap-in, including its cmdlets. +you will remove all the contents of the snap-in, including its cmdlets. To remove a provider from the current session, use the Remove-PSSnapin cmdlet. This cmdlet does not uninstall the provider, but it makes the provider unavailable in the session. You can also use the Remove-PSDrive cmdlet to remove any drive from the -current session. This data on the drive is not affected, but the drive is -no longer available in that session. +current session. This data on the drive is not affected, but the drive is no +longer available in that session. -# VIEWING PROVIDERS +## VIEWING PROVIDERS To view the Windows PowerShell providers on your computer, type: -Get-PSProvider +```powershell +get-psprovider +``` -The output lists the built-in providers and the providers that you added -to the session. +The output lists the built-in providers and the providers that you added to +the session. -# THE PROVIDER CMDLETS +## THE PROVIDER CMDLETS -The following cmdlets are designed to work with the data exposed by -any provider. You can use the same cmdlets in the same way to manage -the different types of data that providers expose. After you -learn to manage the data of one provider, you can use the same -procedures with the data from any provider. +The following cmdlets are designed to work with the data exposed by any +provider. You can use the same cmdlets in the same way to manage the different +types of data that providers expose. After you learn to manage the data of one +provider, you can use the same procedures with the data from any provider. -For example, the New-Item cmdlet creates a new item. In the C: drive that -is supported by the FileSystem provider, you can use New-Item to create a -new file or folder. In the drives that are supported by the Registry -provider, you can use New-Item to create a new registry key. In the Alias: -drive, you can use New-Item to create a new alias. +For example, the New-Item cmdlet creates a new item. In the C: drive that is +supported by the FileSystem provider, you can use New-Item to create a new +file or folder. In the drives that are supported by the Registry provider, you +can use New-Item to create a new registry key. In the Alias: drive, you can +use New-Item to create a new alias. For detailed information about any of the following cmdlets, type: -Get-Help -Detailed +``` +get-help -detailed +``` -# CHILDITEM CMDLETS +### CHILDITEM CMDLETS -Get-ChildItem +- Get-ChildItem -# CONTENT CMDLETS +### CONTENT CMDLETS -Add-Content -Clear-Content -Get-Content -Set-Content +- Add-Content +- Clear-Content +- Get-Content +- Set-Content -# ITEM CMDLETS +### ITEM CMDLETS -Clear-Item -Copy-Item -Get-Item -Invoke-Item -Move-Item -New-Item -Remove-Item -Rename-Item -Set-Item +- Clear-Item +- Copy-Item +- Get-Item +- Invoke-Item +- Move-Item +- New-Item +- Remove-Item +- Rename-Item +- Set-Item -# ITEMPROPERTY CMDLETS +### ITEMPROPERTY CMDLETS -Clear-ItemProperty -Copy-ItemProperty -Get-ItemProperty -Move-ItemProperty -New-ItemProperty -Remove-ItemProperty -Rename-ItemProperty -Set-ItemProperty +- Clear-ItemProperty +- Copy-ItemProperty +- Get-ItemProperty +- Move-ItemProperty +- New-ItemProperty +- Remove-ItemProperty +- Rename-ItemProperty +- Set-ItemProperty -# LOCATION CMDLETS +### LOCATION CMDLETS -Get-Location -Pop-Location -Push-Location -Set-Location +- Get-Location +- Pop-Location +- Push-Location +- Set-Location -# PATH CMDLETS +### PATH CMDLETS -Join-Path -Convert-Path -Split-Path -Resolve-Path -Test-Path +- Join-Path +- Convert-Path +- Split-Path +- Resolve-Path +- Test-Path -# PSDRIVE CMDLETS +### PSDRIVE CMDLETS -Get-PSDrive -New-PSDrive -Remove-PSDrive +- Get-PSDrive +- New-PSDrive +- Remove-PSDrive -# PSPROVIDER CMDLETS +### PSPROVIDER CMDLETS -Get-PSProvider +- Get-PSProvider -# VIEWING PROVIDER DATA +## VIEWING PROVIDER DATA The primary benefit of a provider is that it exposes its data in a familiar and consistent way. The model for data presentation is a file system @@ -181,7 +181,7 @@ but you can get information about the provider drive by using the Get-PSDrive cmdlet. For example, to get all the properties of the Function: drive, type: -Get-PSDrive Function | Format-List * +get-psdrive Function | format-list * You can view and move through the data in a provider drive just as you would on a file system drive. @@ -190,85 +190,108 @@ To view the contents of a provider drive, use the Get-Item or Get-ChildItem cmdlets. Type the drive name followed by a colon (:). For example, to view the contents of the Alias: drive, type: -Get-Item Alias: +```powershell +get-item alias: +``` You can view and manage the data in any drive from another drive by including the drive name in the path. For example, to view the HKLM\Software registry key in the HKLM: drive from another drive, type: -Get-ChildItem HKLM:\SOFTWARE +```powershell +get-childitem hklm:\software +``` To open the drive, use the Set-Location cmdlet. Remember the colon when you specify the drive path. For example, to change your location to the root directory of the Cert: drive, type: -Set-Location Cert: +```powershell +set-location cert: +``` Then, to view the contents of the Cert: drive, type: -Get-ChildItem +```powershell +get-childitem +``` -# MOVING THROUGH HIERARCHICAL DATA +## MOVING THROUGH HIERARCHICAL DATA You can move through a provider drive just as you would a hard disk drive. If the data is arranged in a hierarchy of items within items, use a backslash () to indicate a child item. Use the following format: +``` drive:\location\child-location\... +``` For example, to change your location to the HKLM\Software registry key, type a Set-Location command, such as: -Set-Location HKLM:\SOFTWARE +```powershell +set-location hklm:\software +``` You can also use relative references to locations. A dot (.) represents the current location. For example, if you are in the HKLM:\Software\Microsoft registry key, and you want to list the registry subkeys in the HKLM:\Software\Microsoft\PowerShell key, type the following command: -Get-ChildItem .\PowerShell +```powershell +get-childitem .\PowerShell +``` -# FINDING DYNAMIC PARAMETERS +## FINDING DYNAMIC PARAMETERS -Dynamic parameters are cmdlet parameters that are added to a cmdlet -by a provider. These parameters are available only when the cmdlet is -used with the provider that added them. +Dynamic parameters are cmdlet parameters that are added to a cmdlet by a +provider. These parameters are available only when the cmdlet is used with the +provider that added them. -For example, the Cert: drive adds the CodeSigningCert parameter -to the Get-Item and Get-ChildItem cmdlets. You can use this parameter -only when you use Get-Item or Get-ChildItem in the Cert: drive. +For example, the Cert: drive adds the CodeSigningCert parameter to the +Get-Item and Get-ChildItem cmdlets. You can use this parameter only when you +use Get-Item or Get-ChildItem in the Cert: drive. -For a list of the dynamic parameters that a provider supports, see the -Help file for the provider. Type: +For a list of the dynamic parameters that a provider supports, see the Help +file for the provider. Type: -Get-Help +``` +get-help +``` For example: -Get-Help Certificate +```powershell +get-help certificate +``` -# LEARNING ABOUT PROVIDERS +## LEARNING ABOUT PROVIDERS -Although all provider data appears in drives, and you use the same methods -to move through them, the similarity stops there. The data stores that -the provider exposes can be as varied as Active Directory locations and -Microsoft Exchange Server mailboxes. +Although all provider data appears in drives, and you use the same methods to +move through them, the similarity stops there. The data stores that the +provider exposes can be as varied as Active Directory locations and Microsoft +Exchange Server mailboxes. For information about individual Windows PowerShell providers, type: -Get-Help +``` +get-help +``` For example: -Get-Help Registry +```powershell +get-help registry +``` For a list of Help topics about the providers, type: -Get-Help * -Category provider +```powershell +get-help * -category provider +``` -# SEE ALSO +## SEE ALSO -about_Locations +[about_Locations](about_Locations.md) [about_Path_Syntax](about_Path_Syntax.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 8e8248c24f78..8df82dca043b 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,290 +7,272 @@ title: about_Quoting_Rules --- # About Quoting Rules -## about_Quoting_Rules - ## SHORT DESCRIPTION -Describes rules for using single and double quotation marks in Windows PowerShell. +Describes rules for using single and double quotation marks in PowerShell. ## LONG DESCRIPTION -Quotation marks are used to specify a literal string. You can enclose a string in single quotation marks (') or double quotation marks ("). -Quotation marks are also used to create a here-string. A here-string is a single-quoted or double-quoted string in which quotation marks are interpreted literally. A here-string can span multiple lines. All the lines in a here-string are interpreted as strings, even though they are not enclosed in quotation marks. +Quotation marks are used to specify a literal string. You can enclose a string +in single quotation marks (') or double quotation marks ("). -In commands to remote computers, quotation marks define the parts of the command that are run on the remote computer. In a remote session, quotation marks also determine whether the variables in a command are interpreted first on the local computer or on the remote computer. +Quotation marks are also used to create a here-string. A here-string is a +single-quoted or double-quoted string in which quotation marks are interpreted +literally. A here-string can span multiple lines. All the lines in a +here-string are interpreted as strings, even though they are not enclosed in +quotation marks. +In commands to remote computers, quotation marks define the parts of the +command that are run on the remote computer. In a remote session, quotation +marks also determine whether the variables in a command are interpreted first +on the local computer or on the remote computer. ### SINGLE AND DOUBLE-QUOTED STRINGS -When you enclose a string in double quotation marks (a double-quoted string), variable names that are preceded by a dollar sign ($) are replaced with the variable's value before the string is passed to the command for processing. -For example: +When you enclose a string in double quotation marks (a double-quoted string), +variable names that are preceded by a dollar sign ($) are replaced with the +variable's value before the string is passed to the command for processing. +For example: -``` +```powershell $i = 5 "The value of $i is $i." ``` - The output of this command is: - -``` +```output The value of 5 is 5. ``` +Also, in a double-quoted string, expressions are evaluated, and the result is +inserted in the string. For example: -Also, in a double-quoted string, expressions are evaluated, and the result is inserted in the string. For example: - - -``` +```powershell "The value of $(2+3) is 5." ``` - The output of this command is: - -``` +```output The value of 5 is 5. ``` +When you enclose a string in single-quotation marks (a single-quoted string), +the string is passed to the command exactly as you type it. No substitution is +performed. For example: -When you enclose a string in single-quotation marks (a single-quoted string), the string is passed to the command exactly as you type it. No substitution is performed. For example: - - -``` +```powershell $i = 5 'The value of $i is $i.' ``` - The output of this command is: - -``` +```output The value $i is $i. ``` +Similarly, expressions in single-quoted strings are not evaluated. They are +interpreted as literals. For example: -Similarly, expressions in single-quoted strings are not evaluated. They are interpreted as literals. For example: - - -``` +```powershell 'The value of $(2+3) is 5.' ``` - The output of this command is: - -``` +```output The value of $(2+3) is 5. ``` +To prevent the substitution of a variable value in a double-quoted string, use +the backtick character (`)(ASCII 96), which is the Windows PowerShell escape +character. -To prevent the substitution of a variable value in a double-quoted string, use the backtick character (`)(ASCII 96), which is the Windows PowerShell escape character. - -In the following example, the backtick character that precedes the first $i variable prevents Windows PowerShell from replacing the variable name with its value. For example: - +In the following example, the backtick character that precedes the first $i +variable prevents Windows PowerShell from replacing the variable name with its +value. For example: -``` +```powershell $i = 5 "The value of `$i is $i." ``` - The output of this command is: - -``` +```output The value $i is 5. ``` +To make double-quotation marks appear in a string, enclose the entire string +in single quotation marks. For example: -To make double-quotation marks appear in a string, enclose the entire string in single quotation marks. For example: - - -``` +```powershell 'As they say, "live and learn."' ``` - The output of this command is: - -``` +```output As they say, "live and learn." ``` +You can also enclose a single-quoted string in a double-quoted string. For +example: -You can also enclose a single-quoted string in a double-quoted string. For example: - - -``` +```powershell "As they say, 'live and learn.'" ``` - The output of this command is: - -``` +```output As they say, 'live and learn.' ``` - Or, double the quotation marks around a double-quoted phrase. For example: - -``` +```powershell "As they say, ""live and learn.""" ``` - The output of this command is: - -``` +```output As they say, "live and learn." ``` +To include a single quotation mark in a single-quoted string, use a second +consecutive single quote. For example: -To include a single quotation mark in a single-quoted string, use a second consecutive single quote. For example: - - -``` +```powershell 'don''t' ``` - The output of this command is: - -``` +```output don't ``` +To force Windows PowerShell to interpret a double quotation mark literally, +use a backtick character. This prevents Windows PowerShell from interpreting +the quotation mark as a string delimiter. For example: -To force Windows PowerShell to interpret a double quotation mark literally, use a backtick character. This prevents Windows PowerShell from interpreting the quotation mark as a string delimiter. For example: - - -``` +```powershell "Use a quotation mark (`") to begin a string." ``` +Because the contents of single-quoted strings are interpreted literally, you +cannot use the backtick character to force a literal character interpretation +in a single-quoted string. -Because the contents of single-quoted strings are interpreted literally, you cannot use the backtick character to force a literal character interpretation in a single-quoted string. - -For example, the following command generates an error because Windows PowerShell does not recognize the escape character. Instead, it interprets the second quotation mark as the end of the string. - +For example, the following command generates an error because Windows +PowerShell does not recognize the escape character. Instead, it interprets the +second quotation mark as the end of the string. -``` +```output PS C:\> 'Use a quotation mark (`') to begin a string.' Unexpected token ')' in expression or statement. At line:1 char:27 + 'Use a quotation mark (`') <<<< to begin a string.' ``` - - ### HERE-STRINGS + The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation marks are interpreted literally. A here-string can span multiple lines. All the lines in a here-string are interpreted as strings even though they are not enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string in which quotation +marks are interpreted literally. A here-string can span multiple lines. All +the lines in a here-string are interpreted as strings even though they are not +enclosed in quotation marks. -Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by their values. +Like regular strings, variables are replaced by their values in double-quoted +here-strings. In single-quoted here-strings, variables are not replaced by +their values. -You can use here-strings for any text, but they are particularly useful for the following kinds of text: +You can use here-strings for any text, but they are particularly useful for +the following kinds of text: --- Text that contains literal quotation marks --- Multiple lines of text, such as the text in an HTML or XML --- The Help text for a script or function document +- Text that contains literal quotation marks +- Multiple lines of text, such as the text in an HTML or XML +- The Help text for a script or function document -A here-string can have either of the following formats, where represents the linefeed or newline hidden character that is added when you press the ENTER key. +A here-string can have either of the following formats, where \ +represents the linefeed or newline hidden character that is added when you +press the ENTER key. +Double-quotes: ``` -Double-quotes: - @" - [string] ... - "@ +@" + [string] ... +"@ ``` - - -``` Single-quotes: - @' - [string] ... - '@ +``` +@' + [string] ... +'@ ``` +In either format, the closing quotation mark must be the first character in +the line. -In either format, the closing quotation mark must be the first character in the line. - -A here-string contains all the text between the two hidden characters. In the here-string, all quotation marks are interpreted literally. For example: - +A here-string contains all the text between the two hidden characters. In the +here-string, all quotation marks are interpreted literally. For example: -``` +```powershell @" For help, type "get-help" "@ ``` - The output of this command is: - -``` +```output For help, type "get-help" ``` - Using a here-string can simplify using a string in a command. For example: - -``` +```powershell @" Use a quotation mark (') to begin a string. "@ ``` - The output of this command is: - -``` +```output Use a quotation mark (') to begin a string. ``` +In single-quoted here-strings, variables are interpreted literally and +reproduced exactly. For example: -In single-quoted here-strings, variables are interpreted literally and reproduced exactly. For example: - - -``` +```powershell @' The $profile variable contains the path of your Windows PowerShell profile. '@ ``` - The output of this command is: - -``` +```output The $profile variable contains the path of your Windows PowerShell profile. ``` +In double-quoted here-strings, variables are replaced by their values. For +example: -In double-quoted here-strings, variables are replaced by their values. For example: - - -``` +```powershell @" Even if you have not created a profile, the path of the profile file is: @@ -298,21 +280,19 @@ $profile. "@ ``` - The output of this command is: - -``` +```output Even if you have not created a profile, the path of the profile file is: -C:\Users\User01\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1. +C:\Users\User1\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1. ``` +Here-strings are typically used to assign multiple lines to a variable. For +example, the following here-string assigns a page of XML to the $page +variable. -Here-strings are typically used to assign multiple lines to a variable. For example, the following here-string assigns a page of XML to the $page variable. - - -``` +```powershell $page = [XML] @" "@ ``` - -Here-strings are also a convenient format for input to the ConvertFrom-StringData cmdlet, which converts here-strings to hash tables. For more information, see ConvertFrom-StringData. - - -## KEYWORDS -about_Here-Strings - -about_Quotes - -about_Quotation_Marks - +Here-strings are also a convenient format for input to the +ConvertFrom-StringData cmdlet, which converts here-strings to hash tables. For +more information, see ConvertFrom-StringData. ## SEE ALSO [about_Special_Characters](about_Special_Characters.md) -ConvertFrom-StringData - +[ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote.md index ac5e0c6fa90a..36455b275f7e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,73 +7,74 @@ title: about_Remote --- # About Remote -## about_Remote - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes how to run remote commands in Windows PowerShell. -# LONG DESCRIPTION - -You can run remote commands on a single computer or on multiple -computers by using a temporary or persistent connection. You can also -start an interactive session with a single remote computer. +## LONG DESCRIPTION -This topic provides a series of examples to show you how to -run different types of remote command. After you try these basic -commands, read the Help topics that describe each cmdlet that is -used in these commands. The topics provide the details and explain -how you can modify the commands to meet your needs. +You can run remote commands on a single computer or on multiple computers by +using a temporary or persistent connection. You can also start an interactive +session with a single remote computer. -Note: To use Windows PowerShell remoting, the local and remote computers -must be configured for remoting. For more information, see -about_Remote_Requirements. +This topic provides a series of examples to show you how to run different +types of remote command. After you try these basic commands, read the Help +topics that describe each cmdlet that is used in these commands. The topics +provide the details and explain how you can modify the commands to meet your +needs. -# HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION) +Note: To use Windows PowerShell remoting, the local and remote computers must +be configured for remoting. For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). +## HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION) -The easiest way to run remote commands is to start an -interactive session with a remote computer. +The easiest way to run remote commands is to start an interactive session with +a remote computer. -When the session starts, the commands that you type run on the -remote computer, just as though you typed them directly -on the remote computer. You can connect to only one -computer in each interactive session. +When the session starts, the commands that you type run on the remote +computer, just as though you typed them directly on the remote computer. You +can connect to only one computer in each interactive session. -To start an interactive session, use the Enter-PSSession -cmdlet. The following command starts an interactive session -with the Server01 computer: +To start an interactive session, use the Enter-PSSession cmdlet. The following +command starts an interactive session with the Server01 computer: +```powershell Enter-PSSession Server01 +``` -The command prompt changes to indicate that you are connected -to the Server01 computer. +The command prompt changes to indicate that you are connected to the Server01 +computer. +``` Server01\PS> +``` Now, you can type commands on the Server01 computer. To end the interactive session, type: +```powershell Exit-PSSession +``` For more information, see Enter-PSSession. -# HOW TO USE CMDLETS THAT HAVE A COMPUTERNAME PARAMETER TO GET REMOTE DATA +## HOW TO USE CMDLETS THAT HAVE A COMPUTERNAME PARAMETER TO GET REMOTE DATA - -Several cmdlets have a ComputerName parameter that lets you -get objects from remote computers. +Several cmdlets have a ComputerName parameter that lets you get objects from +remote computers. Because these cmdlets do not use WS-Management-based Windows PowerShell remoting, you can use the ComputerName parameter of these cmdlets on any -computer that is running Windows PowerShell. The computers do not have to -be configured for Windows PowerShell remoting, and the computers do not -have to meet the system requirements for remoting. +computer that is running Windows PowerShell. The computers do not have to be +configured for Windows PowerShell remoting, and the computers do not have to +meet the system requirements for remoting. The following cmdlets have a ComputerName parameter: +``` Clear-EventLog Limit-EventLog Get-Counter New-EventLog Get-EventLog Remove-EventLog @@ -82,15 +83,18 @@ Get-Process Show-EventLog Get-Service Stop-Computer Get-WinEvent Test-Connection Get-WmiObject Write-EventLog +``` For example, the following command gets the services on the Server01 remote computer: +```powershell Get-Service -ComputerName Server01 +``` -Typically, cmdlets that support remoting without special configuration -have a **ComputerName** parameter and do not have a **Session** parameter. -To find these cmdlets in your session, type: +Typically, cmdlets that support remoting without special configuration have a +**ComputerName** parameter and do not have a **Session** parameter. To find +these cmdlets in your session, type: ```powershell Get-Command | Where-Object { @@ -99,131 +103,134 @@ Get-Command | Where-Object { } ``` -# HOW TO RUN A REMOTE COMMAND +## HOW TO RUN A REMOTE COMMAND +To run other commands on remote computers, use the Invoke-Command cmdlet. -To run other commands on remote computers, use the -Invoke-Command cmdlet. +To run a single command or a few unrelated commands, use the ComputerName +parameter of Invoke-Command to specify the remote computers. Use the +ScriptBlock parameter to specify the command. -To run a single command or a few unrelated commands, use the -ComputerName parameter of Invoke-Command to specify the remote -computers. Use the ScriptBlock parameter to specify the command. - -For example, the following command runs a Get-Culture command -on the Server01 computer. +For example, the following command runs a Get-Culture command on the Server01 +computer. +```powershell Invoke-Command -ComputerName Server01 -ScriptBlock {Get-Culture} +``` -The ComputerName parameter is designed for situation in which you run -a single command or several unrelated commands on one or many computers. -To establish a persistent connection to a remote computer, use -the Session parameter. - -# HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION) +The ComputerName parameter is designed for situation in which you run a single +command or several unrelated commands on one or many computers. To establish a +persistent connection to a remote computer, use the Session parameter. +## HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION) -When you use the ComputerName parameter of the Invoke-Command -cmdlet, Windows PowerShell establishes a connection just for the -command. Then, it closes the connection when the command is complete. Any -variables or functions that are defined in the command are lost. +When you use the ComputerName parameter of the Invoke-Command cmdlet, Windows +PowerShell establishes a connection just for the command. Then, it closes the +connection when the command is complete. Any variables or functions that are +defined in the command are lost. -To create a persistent connection to a remote computer, use the -New-PSSession cmdlet. For example, the following command creates -PSSessions on the Server01 and Server02 computers and then saves the -PSSessions in the $s variable. +To create a persistent connection to a remote computer, use the New-PSSession +cmdlet. For example, the following command creates PSSessions on the Server01 +and Server02 computers and then saves the PSSessions in the $s variable. +```powershell $s = New-PSSession -ComputerName Server01, Server02 +``` -# HOW TO RUN COMMANDS IN A PSSESSION - +## HOW TO RUN COMMANDS IN A PSSESSION -With a PSSession, you can run a series of remote commands that -share data, like functions, aliases, and the values of variables. -To run commands in a PSSession, use the Session parameter of the -Invoke-Command cmdlet. +With a PSSession, you can run a series of remote commands that share data, +like functions, aliases, and the values of variables. To run commands in a +PSSession, use the Session parameter of the Invoke-Command cmdlet. -For example, the following command uses the Invoke-Command cmdlet -to run a Get-Process command in the PSSessions on the Server01 -and Server02 computers. The command saves the processes in a $p -variable in each PSSession. +For example, the following command uses the Invoke-Command cmdlet to run a +Get-Process command in the PSSessions on the Server01 and Server02 computers. +The command saves the processes in a $p variable in each PSSession. +```powershell Invoke-Command -Session $s -ScriptBlock {$p = Get-Process} +``` -Because the PSSession uses a persistent connection, you can run -another command in the same PSSession that uses the $p variable. -The following command counts the number of processes saved in $p. +Because the PSSession uses a persistent connection, you can run another +command in the same PSSession that uses the $p variable. The following command +counts the number of processes saved in $p. +```powershell Invoke-Command -Session $s -ScriptBlock {$p.count} +``` -# HOW TO RUN A REMOTE COMMAND ON MULTIPLE COMPUTERS - +## HOW TO RUN A REMOTE COMMAND ON MULTIPLE COMPUTERS -To run a remote command on multiple computers, type all of -the computer names in the value of the ComputerName parameter of -Invoke-Command. Separate the names with commas. +To run a remote command on multiple computers, type all of the computer names +in the value of the ComputerName parameter of Invoke-Command. Separate the +names with commas. -For example, the following command runs a Get-Culture command -on three computers: +For example, the following command runs a Get-Culture command on three +computers: +```powershell Invoke-Command -ComputerName S1, S2, S3 -ScriptBlock {Get-Culture} +``` -You can also run a command in multiple PSSessions. The following -commands create PSSessions on the Server01, Server02, and Server03 -computers and then run a Get-Culture command in each of the PSSessions. +You can also run a command in multiple PSSessions. The following commands +create PSSessions on the Server01, Server02, and Server03 computers and then +run a Get-Culture command in each of the PSSessions. +```powershell $s = New-PSSession -ComputerName S1, S2, S3 Invoke-Command -Session $s -ScriptBlock {Get-Culture} +``` To include the local computer list of computers, type the name of the local computer, type a dot (.), or type "localhost". +```powershell Invoke-Command -ComputerName S1, S2, S3, localhost -ScriptBlock {Get-Culture} +``` -# HOW TO RUN A SCRIPT ON REMOTE COMPUTERS - +## HOW TO RUN A SCRIPT ON REMOTE COMPUTERS -To run a local script on remote computers, use the -FilePath parameter of Invoke-Command. +To run a local script on remote computers, use the FilePath parameter of +Invoke-Command. -For example, the following command runs the Sample.ps1 script -on the S1 and S2 computers: +For example, the following command runs the Sample.ps1 script on the S1 and S2 +computers: +```powershell Invoke-Command -ComputerName S1, S2 -FilePath C:\Test\Sample.ps1 +``` -The results of the script are returned to the local computer. You -do not need to copy any files. - -# HOW TO STOP A REMOTE COMMAND - +The results of the script are returned to the local computer. You do not need +to copy any files. -To interrupt a command, press CTRL+C. The interrupt request is -passed to the remote computer where it terminates the remote command. +## HOW TO STOP A REMOTE COMMAND -# FOR MORE INFORMATION +To interrupt a command, press CTRL+C. The interrupt request is passed to the +remote computer where it terminates the remote command. +## FOR MORE INFORMATION --- For information about the system requirements for remoting, -see about_Remote_Requirements. +- For information about the system requirements for remoting, see + [about_Remote_Requirements](about_Remote_Requirements.md). --- For help in formatting remote output, see about_Remote_Output. +- For help in formatting remote output, see [about_Remote_Output](about_Remote_Output.md). --- For information about how remoting works, how to manage remote -data, special configurations, security issues, and other frequently -asked questions, see about_Remote_FAQ. +- For information about how remoting works, how to manage remote data, special + configurations, security issues, and other frequently asked questions, see + [about_Remote_FAQ](about_Remote_FAQ.md). --- For help in resolving remoting errors, see about_Remote_Troubleshooting. +- For help in resolving remoting errors, see about_Remote_Troubleshooting. --- For information about PSSessions and persistent connections, see -about_PSSessions. +- For information about PSSessions and persistent connections, see + [about_PSSessions](about_PSSessions.md). --- For information about Windows PowerShell background jobs, see -about_Jobs. +- For information about Windows PowerShell background jobs, see [about_Jobs](about_Jobs.md). -# KEYWORDS +## KEYWORDS about_Remoting -# SEE ALSO +## SEE ALSO [about_PSSessions](about_PSSessions.md) @@ -237,9 +244,8 @@ about_Remoting [about_Remote_Variables](about_Remote_Variables.md) -Enter-PSSession - -Invoke-Command +[Enter-PSSession](../Enter-PSSession.md) -New-PSSession +[Invoke-Command](../Invoke-Command.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md index eda447268fcd..445c1fa6f6b9 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,77 +7,71 @@ title: about_Remote_Requirements --- # About Remote Requirements -## about_Remote_Requirements +## SHORT DESCRIPTION +Describes the system requirements and configuration requirements for running +remote commands in Windows PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes the system requirements and configuration requirements for -running remote commands in Windows PowerShell. - -# LONG DESCRIPTION - -This topic describes the system requirements, user requirements, and -resource requirements for establishing remote connections and running -remote commands in Windows PowerShell. It also provides instructions for -configuring remote operations. +This topic describes the system requirements, user requirements, and resource +requirements for establishing remote connections and running remote commands +in Windows PowerShell. It also provides instructions for configuring remote +operations. Note: Many cmdlets (including the Get-Service, Get-Process, Get-WMIObject, -Get-EventLog, and Get-WinEvent cmdlets) get objects from remote -computers by using Microsoft .NET Framework methods to retrieve the -objects. They do not use the Windows PowerShell remoting -infrastructure. The requirements in this document do not apply to -these cmdlets. +Get-EventLog, and Get-WinEvent cmdlets) get objects from remote computers by +using Microsoft .NET Framework methods to retrieve the objects. They do not +use the Windows PowerShell remoting infrastructure. The requirements in this +document do not apply to these cmdlets. -To find the cmdlets that have a ComputerName parameter but do not use -Windows PowerShell remoting, read the description of the ComputerName -parameter of the cmdlets. - -# SYSTEM REQUIREMENTS +To find the cmdlets that have a ComputerName parameter but do not use Windows +PowerShell remoting, read the description of the ComputerName parameter of the +cmdlets. +## SYSTEM REQUIREMENTS To run remote sessions on Windows PowerShell 3.0, the local and remote computers must have the following: --- Windows PowerShell 3.0 or later --- The Microsoft .NET Framework 4 or later --- Windows Remote Management 3.0 +- Windows PowerShell 3.0 or later +- The Microsoft .NET Framework 4 or later +- Windows Remote Management 3.0 -To run remote sessions on Windows PowerShell 2.0, the local and remote computers -must have the following: +To run remote sessions on Windows PowerShell 2.0, the local and remote +computers must have the following: --- Windows PowerShell 2.0 or later --- The Microsoft .NET Framework 2.0 or later --- Windows Remote Management 2.0 +- Windows PowerShell 2.0 or later +- The Microsoft .NET Framework 2.0 or later +- Windows Remote Management 2.0 -You can create remote sessions between computers running Windows PowerShell 2.0 -and Windows PowerShell 3.0. However, features that run only on Windows -PowerShell 3.0, such as the ability to disconnect and reconnect to sessions, are -available only when both computers are running Windows PowerShell 3.0. +You can create remote sessions between computers running Windows PowerShell +2.0 and Windows PowerShell 3.0. However, features that run only on Windows +PowerShell 3.0, such as the ability to disconnect and reconnect to sessions, +are available only when both computers are running Windows PowerShell 3.0. To find the version number of an installed version of Windows PowerShell, use the $PSVersionTable automatic variable. -Windows Remote Management (WinRM) 3.0 and Microsoft .NET Framework 4 are included -in Windows 8, Windows Server 2012, and newer releases of the Windows operating -system. WinRM 3.0 is included in Windows Management Framework 3.0 for older -operating systems. If the computer does not have the required version of -WinRM or the Microsoft .NET Framework, the installation fails. - -# USER PERMISSIONS +Windows Remote Management (WinRM) 3.0 and Microsoft .NET Framework 4 are +included in Windows 8, Windows Server 2012, and newer releases of the Windows +operating system. WinRM 3.0 is included in Windows Management Framework 3.0 +for older operating systems. If the computer does not have the required +version of WinRM or the Microsoft .NET Framework, the installation fails. +## USER PERMISSIONS To create remote sessions and run remote commands, by default, the current user must be a member of the Administrators group on the remote computer or provide the credentials of an administrator. Otherwise, the command fails. The permissions required to create sessions and run commands on a remote -computer (or in a remote session on the local computer) are established by -the session configuration (also known as an "endpoint") on the remote -computer to which the session connects. Specifically, the security -descriptor on the session configuration determines who has access to the -session configuration and who can use it to connect. +computer (or in a remote session on the local computer) are established by the +session configuration (also known as an "endpoint") on the remote computer to +which the session connects. Specifically, the security descriptor on the +session configuration determines who has access to the session configuration +and who can use it to connect. The security descriptors on the default session configurations, Microsoft.PowerShell, Microsoft.PowerShell32, and @@ -85,48 +79,50 @@ Microsoft.PowerShell.Workflow, allow access only to members of the Administrators group. If the current user doesn't have permission to use the session configuration, -the command to run a command (which uses a temporary session) or create -a persistent session on the remote computer fails. The user can use the +the command to run a command (which uses a temporary session) or create a +persistent session on the remote computer fails. The user can use the ConfigurationName parameter of cmdlets that create sessions to select a different session configuration, if one is available. Members of the Administrators group on a computer can determine who has permission to connect to the computer remotely by changing the security -descriptors on the default session configurations and by creating new -session configurations with different security descriptors. +descriptors on the default session configurations and by creating new session +configurations with different security descriptors. For more informations about session configurations, see -about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). +[about_Session_Configurations](about_Session_Configurations.md). -# WINDOWS NETWORK LOCATIONS +## WINDOWS NETWORK LOCATIONS Beginning in Windows PowerShell 3.0, the Enable-PSRemoting cmdlet can enable remoting on client and server versions of Windows on private, domain, and public networks. On server versions of Windows with private and domain networks, the -Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted -remote access. It also creates a firewall rule for public networks that -allows remote access only from computers in the same local subnet. This -local subnet firewall rule is enabled by default on server versions of -Windows on public networks, but Enable-PSRemoting reapplies the rule in -case it was changed or deleted. - -On client versions of Windows with private and domain networks, by -default, the Enable-PSRemoting cmdlet creates firewall rules that -allow unrestricted remote access. - -To enable remoting on client versions of Windows with public networks, -use the SkipNetworkProfileCheck parameter of the Enable-PSRemoting cmdlet. -It creates a firewall rule that that allows remote access only from -computers in the same local subnet. +Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted remote +access. It also creates a firewall rule for public networks that allows remote +access only from computers in the same local subnet. This local subnet +firewall rule is enabled by default on server versions of Windows on public +networks, but Enable-PSRemoting reapplies the rule in case it was changed or +deleted. + +On client versions of Windows with private and domain networks, by default, +the Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted +remote access. + +To enable remoting on client versions of Windows with public networks, use the +SkipNetworkProfileCheck parameter of the Enable-PSRemoting cmdlet. It creates +a firewall rule that that allows remote access only from computers in the same +local subnet. To remove the local subnet restriction on public networks and allow remote -access from all locations on client and server versions of Windows, use -the Set-NetFirewallRule cmdlet in the NetSecurity module. Run the following +access from all locations on client and server versions of Windows, use the +Set-NetFirewallRule cmdlet in the NetSecurity module. Run the following command: +```powershell Set-NetFirewallRule -Name "WINRM-HTTP-In-TCP-PUBLIC" -RemoteAddress Any +``` In Windows PowerShell 2.0, on server versions of Windows, Enable-PSRemoting creates firewall rules that permit remote access on all networks. @@ -134,64 +130,55 @@ creates firewall rules that permit remote access on all networks. In Windows PowerShell 2.0, on client versions of Windows, Enable-PSRemoting creates firewall rules only on private and domain networks. If the network location is public, Enable-PSRemoting fails. -# . - -# RUN AS ADMINISTRATOR +## RUN AS ADMINISTRATOR +Administrator privileges are required for the following remoting operations: -Administrator privileges are required for the following remoting -operations: +- Establishing a remote connection to the local computer. This is commonly + known as a "loopback" scenario. --- Establishing a remote connection to the local computer. This is -commonly known as a "loopback" scenario. +- Managing session configurations on the local computer. --- Managing session configurations on the local computer. +- Viewing and changing WS-Management settings on the local computer. These are + the settings in the LocalHost node of the WSMAN: drive. --- Viewing and changing WS-Management settings on the local computer. -These are the settings in the LocalHost node of the WSMAN: drive. +To perform these tasks, you must start Windows PowerShell with the "Run as +administrator" option even if you are a member of the Administrators group on +the local computer. -To perform these tasks, you must start Windows PowerShell with the "Run -as administrator" option even if you are a member of the Administrators -group on the local computer. - -In Windows 7 and in Windows Server 2008 R2, to start Windows PowerShell -with the "Run as administrator" option: +In Windows 7 and in Windows Server 2008 R2, to start Windows PowerShell with +the "Run as administrator" option: 1. Click Start, click All Programs, click Accessories, and then click -the Windows PowerShell folder. - -2. Right-click Windows PowerShell, and then click -"Run as administrator". + the Windows PowerShell folder. +2. Right-click Windows PowerShell, and then click "Run as administrator". To start Windows PowerShell with the "Run as administrator" option: -1. Click Start, click All Programs, and then click the Windows -PowerShell folder. +1. Click Start, click All Programs, and then click the Windows PowerShell + folder. +2. Right-click Windows PowerShell, and then click "Run as administrator". -2. Right-click Windows PowerShell, and then click -"Run as administrator". - -The "Run as administrator" option is also available in other Windows -Explorer entries for Windows PowerShell, including shortcuts. Just -right-click the item, and then click "Run as administrator". +The "Run as administrator" option is also available in other Windows Explorer +entries for Windows PowerShell, including shortcuts. Just right-click the +item, and then click "Run as administrator". When you start Windows PowerShell from another program such as Cmd.exe, use the "Run as administrator" option to start the program. -# HOW TO CONFIGURE YOUR COMPUTER FOR REMOTING - +## HOW TO CONFIGURE YOUR COMPUTER FOR REMOTING Computers running all supported versions of Windows can establish remote connections to and run remote commands in Windows PowerShell without any configuration. However, to receive connections, and allow users to create -local and remote user-managed Windows PowerShell sessions ("PSSessions") -and run commands on the local computer, you must enable Windows PowerShell +local and remote user-managed Windows PowerShell sessions ("PSSessions") and +run commands on the local computer, you must enable Windows PowerShell remoting on the computer. Windows Server 2012 and newer releases of Windows Server are enabled for -Windows PowerShell remoting by default. If the settings are changed, -you can restore the default settings by running the Enable-PSRemoting cmdlet. +Windows PowerShell remoting by default. If the settings are changed, you can +restore the default settings by running the Enable-PSRemoting cmdlet. On all other supported versions of Windows, you need to run the Enable-PSRemoting cmdlet to enable Windows PowerShell remoting. @@ -199,45 +186,43 @@ Enable-PSRemoting cmdlet to enable Windows PowerShell remoting. The remoting features of Windows PowerShell are supported by the WinRM service, which is the Microsoft implementation of the Web Services for Management (WS-Management) protocol. When you enable Windows PowerShell -remoting, you change the default configuration of WS-Management and add -system configuration that allow users to connect to WS-Management. +remoting, you change the default configuration of WS-Management and add system +configuration that allow users to connect to WS-Management. To configure Windows PowerShell to receive remote commands: -1. Start Windows PowerShell with the "Run as administrator" -option. - -2. At the command prompt, type: -Enable-PSRemoting +1. Start Windows PowerShell with the "Run as administrator" option. +2. At the command prompt, type: `Enable-PSRemoting` To verify that remoting is configured correctly, run a test command such as -the following command, which creates a remote session on the local -computer. +the following command, which creates a remote session on the local computer. +```powershell New-PSSession +``` -If remoting is configured correctly, the command will create a session on -the local computer and return an object that represents the session. The -output should resemble the following sample output: - -C:\PS> new-pssession +If remoting is configured correctly, the command will create a session on the +local computer and return an object that represents the session. The output +should resemble the following sample output: +```output Id Name ComputerName State ConfigurationName -- ---- ------------ ----- ----- 1 Session1 localhost Opened Microsoft.PowerShell +``` -If the command fails, for assistance, see about_Remote_Troubleshooting. +If the command fails, for assistance, see +[about_Remote_Troubleshooting](about_Remote_Troubleshooting.md). -# UNDERSTAND POLICIES +## UNDERSTAND POLICIES +When you work remotely, you use two instances of Windows PowerShell, one on +the local computer and one on the remote computer. As a result, your work is +affected by the Windows policies and the Windows PowerShell policies on the +local and remote computers. -When you work remotely, you use two instances of Windows PowerShell, one -on the local computer and one on the remote computer. As a result, your -work is affected by the Windows policies and the Windows PowerShell -policies on the local and remote computers. - -In general, before you connect and as you are establishing the connection, -the policies on the local computer are in effect. When you are using the +In general, before you connect and as you are establishing the connection, the +policies on the local computer are in effect. When you are using the connection, the policies on the remote computer are in effect. # SEE ALSO @@ -248,9 +233,8 @@ connection, the policies on the remote computer are in effect. [about_PSSessions](about_PSSessions.md) -Invoke-Command - -Enter-PSSession +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 33bf188649a7..cdd13115f8e0 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,108 +7,109 @@ title: about_Remote_Variables --- # About Remote Variables -## about_Remote_Variables +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use local and remote variables in remote commands. -Explains how to use local and remote variables in remote -commands. +## LONG DESCRIPTION -# LONG DESCRIPTION - -You can use variables in commands that you run on remote -computers. Simply assign a value to the variable and then -use the variable in place of the value. - -By default, the variables in remote commands are assumed -to be defined in the session in which the command runs. You -can also use variables that are defined in the local session, -but you must identify them as local -variables in the command. - -# USING REMOTE VARIABLES - - -Windows PowerShell assumes that the variables used in remote -commands are defined in the session in which the command runs. +You can use variables in commands that you run on remote computers. Simply +assign a value to the variable and then use the variable in place of the +value. -In the following example, the $ps variable is defined in the -temporary session in which the Get-WinEvent command runs. +By default, the variables in remote commands are assumed to be defined in the +session in which the command runs. You can also use variables that are defined +in the local session, but you must identify them as local variables in the +command. -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"; Get-WinEvent -LogName $ps} +## USING REMOTE VARIABLES -Similarly, when the command runs in a persistent session (PSSession), -the remote variable must be defined in the same PSSession. +Windows PowerShell assumes that the variables used in remote commands are +defined in the session in which the command runs. -PS C:> $s = New-PSSession -ComputerName S1 +In the following example, the \$ps variable is defined in the temporary session +in which the Get-WinEvent command runs. -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"} +```powershell +Invoke-Command -ComputerName S1 -ScriptBlock { + $ps = "Windows PowerShell"; Get-WinEvent -LogName $ps +} +``` -PS C:> Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $ps} +Similarly, when the command runs in a persistent session (PSSession), the +remote variable must be defined in the same PSSession. -# USING LOCAL VARIABLES +```powershell +$s = New-PSSession -ComputerName S1 +Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"} +Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $ps} +``` +## USING LOCAL VARIABLES -You can also use local variables in remote commands, but you must -indicate that the variable is defined in the local session. +You can also use local variables in remote commands, but you must indicate +that the variable is defined in the local session. -Beginning in Windows PowerShell 3.0, you can use the Using scope -modifier to identify a local variable in a remote command. +Beginning in Windows PowerShell 3.0, you can use the Using scope modifier to +identify a local variable in a remote command. The syntax of Using is as follows: -The syntax is: +``` $Using: +``` -In the following example, the $ps variable is created in the local -session, but is used in the session in which the command runs. The -Using scope modifier identifies $ps as a local variable. +In the following example, the $ps variable is created in the local session, +but is used in the session in which the command runs. The Using scope modifier +identifies $ps as a local variable. -PS C:> $ps = "Windows PowerShell" -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {Get-WinEvent -LogName $Using:ps} +```powershell +$ps = "Windows PowerShell" +Invoke-Command -ComputerName S1 -ScriptBlock { + Get-WinEvent -LogName $Using:ps +} +``` You can also use the Using scope modifier in PSSessions. -PS C:> $s = New-PSSession -ComputerName S1 - -PS C:> $ps = "Windows PowerShell" +```powershell +$s = New-PSSession -ComputerName S1 +$ps = "Windows PowerShell" +Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +``` -PS C:> Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +## USING LOCAL VARIABLES IN WINDOWS POWERSHELL 2.0 -# USING LOCAL VARIABLES IN WINDOWS POWERSHELL 2.0 +You can use local variables in a remote command by defining parameters for the +remote command and using the ArgumentList parameter of the Invoke-Command +cmdlet to specify the local variable as the parameter value. +This command format is valid on Windows PowerShell 2.0 and later versions of +Windows PowerShell. -You can use local variables in a remote command by defining parameters -for the remote command and using the ArgumentList parameter of the -Invoke-Command cmdlet to specify the local variable as the parameter -value. - -This command format is valid on Windows PowerShell 2.0 and later versions -of Windows PowerShell. +- Use the param keyword to define parameters for the remote command. The + parameter names are placeholders that do not need to match the name of the + local variable. --- Use the param keyword to define parameters for the remote command. -The parameter names are placeholders that do not need to match the -name of the local variable. +- Use the parameters defined by the param keyword in the command. --- Use the parameters defined by the param keyword in the command. - --- Use the ArgumentList parameter of the Invoke-Command cmdlet to -specify the local variable as the parameter value. +- Use the ArgumentList parameter of the Invoke-Command cmdlet to specify the + local variable as the parameter value. For example, the following commands define the $ps variable in the local -session and then use it in a remote command. The command uses $log as -the parameter name and the local variable, $ps, as its value. - -C:\PS>$ps = "Windows PowerShell" +session and then use it in a remote command. The command uses $log as the +parameter name and the local variable, $ps, as its value. -C:\PS>Invoke-Command -ComputerName S1 -ScriptBlock {param($log) Get-WinEvent -logname $log} -ArgumentList $ps +```powershell +$ps = "Windows PowerShell" +Invoke-Command -ComputerName S1 -ScriptBlock { + param($log) + Get-WinEvent -logname $log +} -ArgumentList $ps +``` -# KEYWORDS - -about_Using - -# SEE ALSO +## SEE ALSO [about_Remote](about_Remote.md) @@ -116,9 +117,8 @@ about_Using [about_Scopes](about_Scopes.md) -Enter-PSSession - -Invoke-Command +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md index 4ae85a982fc2..c2e71e2f1753 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -145,5 +145,4 @@ always a snap-in. [about_PSSnapins](about_PSSnapins.md) -Get-PSSnapin - +[Get-PSSnapin](../Get-PSSnapin.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Reserved_Words.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Reserved_Words.md index 874a7e5fd8a1..4c2f92e8b5fc 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Reserved_Words.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Reserved_Words.md @@ -70,8 +70,8 @@ Get-Help ## SEE ALSO - [about_Command_Syntax](about_Command_Syntax.md) -- [about_Special_Characters](about_Special_Characters.md) - [about_Language_Keywords](about_Language_Keywords.md) - [about_Parsing](about_Parsing.md) - [about_Quoting_Rules](about_Quoting_Rules.md) - [about_Script_Blocks](about_Script_Blocks.md) +- [about_Special_Characters](about_Special_Characters.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Return.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Return.md index ff684edeef37..bcb1e40e8d25 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Return.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Return.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,118 +7,115 @@ title: about_Return --- # About Return -## about_Return - ## SHORT DESCRIPTION -Exits the current scope, which can be a function, script, or script block. +Exits the current scope, which can be a function, script, or script block. ## LONG DESCRIPTION -The Return keyword exits a function, script, or script block. It can be used to exit a scope at a specific point, to return a value, or to indicate that the end of the scope has been reached. -Users who are familiar with languages like C or C\# might want to use the Return keyword to make the logic of leaving a scope explicit. + The Return keyword exits a function, script, or script block. It can be used + to exit a scope at a specific point, to return a value, or to indicate that + the end of the scope has been reached. -In Windows PowerShell, the results of each statement are returned as output, even without a statement that contains the Return keyword. Languages like C or C\# return only the value or values that are specified by the Return keyword. +Users who are familiar with languages like C or C\# might want to use the +Return keyword to make the logic of leaving a scope explicit. +In PowerShell, the results of each statement are returned as output, +even without a statement that contains the Return keyword. Languages like C or +C\# return only the value or values that are specified by the Return keyword. ### SYNTAX -The syntax for the Return keyword is as follows: +The syntax for the Return keyword is as follows: ``` return [] ``` - -The Return keyword can appear alone, or it can be followed by a value or expression, as follows: - +The Return keyword can appear alone, or it can be followed by a value or +expression, as follows: ``` -return -return $a +return +return $a return (2 + $a) ``` - ### EXAMPLES -The following example uses the Return keyword to exit a function at a specific point if a conditional is met: +The following example uses the Return keyword to exit a function at a specific +point if a conditional is met: ``` -function ScreenPassword($instance) -{ - if (!($instance.screensaversecure)) {return $instance.name} - -} - +function ScreenPassword($instance) +{ + if (!($instance.screensaversecure)) {return $instance.name} + +} + foreach ($a in @(get-wmiobject win32_desktop)) { ScreenPassword($a) } ``` +This script checks each user account. The ScreenPassword function returns the +name of any user account that does not have a password-protected screen saver. +If the screen saver is password protected, the function completes any other +statements to be run, and PowerShell does not return any value. -This script checks each user account. The ScreenPassword function returns the name of any user account that does not have a password-protected screen saver. If the screen saver is password protected, the function completes any other statements to be run, and Windows PowerShell does not return any value. - -In Windows PowerShell, values can be returned even if the Return keyword is not used. The results of each statement are returned. For example, the following statements return the value of the $a variable: - +In PowerShell, values can be returned even if the Return keyword is not used. +The results of each statement are returned. For example, the following +statements return the value of the \$a variable: ``` -$a +$a return ``` - The following statement also returns the value of $a: - ``` return $a ``` +The following example includes a statement intended to let the user know that +the function is performing a calculation: -The following example includes a statement intended to let the user know that the function is performing a calculation: +```powershell +function calculation { + param ($value) - -``` -function calculation { - param ($value) - - "Please wait. Working on calculation..." - $value += 73 - return $value - } + "Please wait. Working on calculation..." + $value += 73 + return $value +} ``` +Running this function and assigning the result to a variable has the following +effect: -Running this function and assigning the result to a variable has the following effect: - - -``` -C:\PS> $a = calculation 14 -C:\PS> +```powershell +$a = calculation 14 ``` +The "Please wait. Working on calculation..." string is not displayed. Instead, +it is assigned to the $a variable, as in the following example: -The "Please wait. Working on calculation..." string is not displayed. Instead, it is assigned to the $a variable, as in the following example: - - -``` -C:\PS> $a -Please wait. Working on calculation... +```output +C:\PS> $a +Please wait. Working on calculation... 87 ``` - -Both the informational string and the result of the calculation are returned by the function and assigned to the $a variable. - +Both the informational string and the result of the calculation are returned +by the function and assigned to the \$a variable. ## SEE ALSO -Exit keyword in [about_Language_Keywords](about_Language_Keywords.md) +[about_Language_Keywords](about_Language_Keywords.md) [about_Functions](about_Functions.md) [about_Scopes](about_Scopes.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md index 43445a359c43..2e47af3dba57 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,62 +7,56 @@ title: about_Run_With_PowerShell --- # About Run With PowerShell -## about_Run_With_PowerShell +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use the "Run with PowerShell" feature to run a script from a +file system drive. -Explains how to use the "Run with PowerShell" feature to run -a script from a file system drive. +## LONG DESCRIPTION -# LONG DESCRIPTION +Beginning in Windows PowerShell 3.0, you can use the "Run with PowerShell" +feature to run scripts from File Explorer in Windows 8 and Windows Server 2012 +and from Windows Explorer in earlier versions of Windows. -Beginning in Windows PowerShell 3.0, you can use the "Run with -PowerShell" feature to run scripts from File Explorer in Windows 8 -and Windows Server 2012 and from Windows Explorer in earlier -versions of Windows. +The "Run with PowerShell" feature is designed to run scripts that do not have +required parameters and do not return output to the command prompt. -The "Run with PowerShell" feature is designed to run scripts -that do not have required parameters and do not return output -to the command prompt. - -When you use the "Run with PowerShell" feature, the Windows -PowerShell console window appears only briefly, if at all. -You cannot interact with it. +When you use the "Run with PowerShell" feature, the Windows PowerShell console +window appears only briefly, if at all. You cannot interact with it. To use the "Run with PowerShell" feature: -In File Explorer (or Windows Explorer), right-click the -script file name and then select "Run with PowerShell". +In File Explorer (or Windows Explorer), right-click the script file name and +then select "Run with PowerShell". -The "Run with PowerShell" feature starts a Windows PowerShell -session that has an execution policy of Bypass, runs the -script, and closes the session. +The "Run with PowerShell" feature starts a Windows PowerShell session that has +an execution policy of Bypass, runs the script, and closes the session. It runs a command that has the following format: + +``` PowerShell.exe -File -ExecutionPolicy Bypass +``` -"Run with PowerShell" sets the Bypass execution policy only -for the session (the current instance of the PowerShell process) -in which the script runs. This feature does not change the execution -policy for the computer or the user. +"Run with PowerShell" sets the Bypass execution policy only for the session +(the current instance of the PowerShell process) in which the script runs. +This feature does not change the execution policy for the computer or the +user. -The "Run with PowerShell" feature is affected only by the AllSigned -execution policy. If the AllSigned execution policy is effective for -the computer or the user, "Run with PowerShell" runs only signed -scripts. "Run with PowerShell" is not affected by any other execution -policy. For more information, see about_Execution_Policies. +The "Run with PowerShell" feature is affected only by the AllSigned execution +policy. If the AllSigned execution policy is effective for the computer or the +user, "Run with PowerShell" runs only signed scripts. "Run with PowerShell" is +not affected by any other execution policy. For more information, see +[about_Execution_Policies](about_Execution_Policies.md). -Troubleshooting Note: Run with PowerShell command might prompt you -to confirm the execution policy change. +Troubleshooting Note: Run with PowerShell command might prompt you to confirm +the execution policy change. -# SEE ALSO +## SEE ALSO [about_Execution_Policies](about_Execution_Policies.md) [about_Group_Policy_Settings](about_Group_Policy_Settings.md) [about_Scripts](about_Scripts.md) - -"Running Scripts" (http://go.microsoft.com/fwlink/?LinkId=257680) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md index 5085f0488ccc..92f18f04064d 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -1,111 +1,97 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-08 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet -title: about_Scopes +title: about_scopes --- # About Scopes -## about_Scopes - about_Scopes -# SHORT DESCRIPTION +## SHORT DESCRIPTION -Explains the concept of scope in Windows PowerShell and shows how to set -and change the scope of elements. +Explains the concept of scope in PowerShell and shows how to set and change +the scope of elements. -# LONG DESCRIPTION +## LONG DESCRIPTION -Windows PowerShell protects access to variables, aliases, functions, and -Windows PowerShell drives (PSDrives) by limiting where they can be read and -changed. By enforcing a few simple rules for scope, Windows PowerShell -helps to ensure that you do not inadvertently change an item that should -not be changed. +PowerShell protects access to variables, aliases, functions, and PowerShell +drives (PSDrives) by limiting where they can be read and changed. By enforcing +a few simple rules for scope, PowerShell helps to ensure that you do not +inadvertently change an item that should not be changed. The following are the basic rules of scope: -- An item you include in a scope is visible in the scope in which it -was created and in any child scope, unless you explicitly make it -private. You can place variables, aliases, functions, or Windows -PowerShell drives in one or more scopes. - -- An item that you created within a scope can be changed only in the -scope in which it was created, unless you explicitly specify a -different scope. - -If you create an item in a scope, and the item shares its name with an -item in a different scope, the original item might be hidden under the -new item. But, it is not overridden or changed. - -## Windows PowerShell Scopes - -Scopes in Windows PowerShell have both names and numbers. The named -scopes specify an absolute scope. The numbers are relative and reflect -the relationship between scopes. - -### Global -The scope that is in effect when Windows PowerShell -starts. Variables and functions that are present when -Windows PowerShell starts have been created in the -global scope. This includes automatic variables and -preference variables. This also includes the variables, aliases, -and functions that are in your Windows PowerShell -profiles. - -### Local -The current scope. The local scope can be the global -scope or any other scope. - -### Script -The scope that is created while a script file runs. Only -the commands in the script run in the script scope. To -the commands in a script, the script scope is the local -scope. +- An item you include in a scope is visible in the scope in which it was +created and in any child scope, unless you explicitly make it private. You can +place variables, aliases, functions, or PowerShell drives in one or +more scopes. + +- An item that you created within a scope can be changed only in the scope in +which it was created, unless you explicitly specify a different scope. + +If you create an item in a scope, and the item shares its name with an item in +a different scope, the original item might be hidden under the new item. But, +it is not overridden or changed. -### Private -Items in private scope cannot be seen outside of the current -scope. You can use private scope to create a private version -of an item with the same name in another scope. - -### Numbered Scopes -You can refer to scopes by name or by a number that -describes the relative position of one scope to another. -Scope 0 represents the current, or local, scope. Scope 1 -indicates the immediate parent scope. Scope 2 indicates the -parent of the parent scope, and so on. Numbered scopes -are useful if you have created many recursive +## PowerShell Scopes + +Scopes in PowerShell have both names and numbers. The named scopes specify an +absolute scope. The numbers are relative and reflect the relationship between scopes. +- Global: The scope that is in effect when PowerShell starts. Variables and +functions that are present when PowerShell starts have been created in the +global scope. This includes automatic variables and preference variables. This +also includes the variables, aliases, and functions that are in your +PowerShell profiles. + +- Local: The current scope. The local scope can be the global scope or any +other scope. + +- Script: The scope that is created while a script file runs. Only the +commands in the script run in the script scope. To the commands in a script, +the script scope is the local scope. + +- Private: Items in private scope cannot be seen outside of the current scope. +You can use private scope to create a private version of an item with the same +name in another scope. + +- Numbered Scopes: You can refer to scopes by name or by a number that describes +the relative position of one scope to another. Scope 0 represents the current, +or local, scope. Scope 1 indicates the immediate parent scope. Scope 2 +indicates the parent of the parent scope, and so on. Numbered scopes are +useful if you have created many recursive scopes. + ## Parent and Child Scopes -You can create a new scope by running a script or function, by creating -a session, or by starting a new instance of Windows PowerShell. When you -create a new scope, the result is a parent scope (the original scope) and -a child scope (the scope that you created). +You can create a new scope by running a script or function, by creating a +session, or by starting a new instance of PowerShell. When you create a new +scope, the result is a parent scope (the original scope) and a child scope +(the scope that you created). -In Windows PowerShell, all scopes are child scopes of the global scope, -but you can create many scopes and many recursive scopes. +In PowerShell, all scopes are child scopes of the global scope, but you can +create many scopes and many recursive scopes. Unless you explicitly make the items private, the items in the parent scope -are available to the child scope. However, items that you create and change -in the child scope do not affect the parent scope, unless you explicitly -specify the scope when you create the items. +are available to the child scope. However, items that you create and change in +the child scope do not affect the parent scope, unless you explicitly specify +the scope when you create the items. ## Inheritance -A child scope does not inherit the variables, aliases, and functions from -the parent scope. Unless an item is private, the child scope can view the -items in the parent scope. And, it can change the items by explicitly -specifying the parent scope, but the items are not part of the child scope. +A child scope does not inherit the variables, aliases, and functions from the +parent scope. Unless an item is private, the child scope can view the items in +the parent scope. And, it can change the items by explicitly specifying the +parent scope, but the items are not part of the child scope. -However, a child scope is created with a set of items. Typically, it -includes all the aliases that have the AllScope option. This option is -discussed later in this topic. It includes all the variables that have the -AllScope option, plus some variables that can be used to customize the -scope, such as MaximumFunctionCount. +However, a child scope is created with a set of items. Typically, it includes +all the aliases that have the AllScope option. This option is discussed later +in this topic. It includes all the variables that have the AllScope option, +plus some variables that can be used to customize the scope, such as +MaximumFunctionCount. To find the items in a particular scope, use the Scope parameter of Get-Variable or Get-Alias. @@ -144,8 +130,8 @@ The default scope for scripts is the script scope. The default scope for functions and aliases is the local scope, even if they are defined in a script. -The following command, which does not use a scope modifier, creates a -variable in the current or local scope: +The following command, which does not use a scope modifier, creates a variable +in the current or local scope: ```powershell $a = "one" @@ -158,8 +144,8 @@ modifier: $global:a = "one" ``` -To create the same variable in the script scope, use the script -scope modifier: +To create the same variable in the script scope, use the script scope +modifier: ```powershell $script:a = "one" @@ -169,259 +155,246 @@ You can also use a scope modifier in functions. The following function definition creates a function in the global scope: ```powershell -function global:Hello -{ - write-host "Hello, World" +function global:Hello { + write-host "Hello, World" } ``` -You can also use scope modifiers to refer to a variable in a different -scope. The following command refers to the $test variable, first in the -local scope and then in the global scope: +You can also use scope modifiers to refer to a variable in a different scope. +The following command refers to the $test variable, first in the local scope +and then in the global scope: ```powershell $test $global:test ``` -## The Using scope modifier +### The Using scope modifier -Using is a special scope modifier that identifies a local -variable in a remote command. By default, variables in remote -commands are assumed to be defined in the remote session. +Using is a special scope modifier that identifies a local variable in a remote +command. By default, variables in remote commands are assumed to be defined in +the remote session. -The Using scope modifier is introduced in Windows PowerShell 3.0. +The Using scope modifier is introduced in PowerShell 3.0. For more information, see [about_Remote_Variables](about_Remote_Variables.md). -## The AllScope Option +### The AllScope Option Variables and aliases have an Option property that can take a value of AllScope. Items that have the AllScope property become part of any child scopes that you create, although they are not retroactively inherited by parent scopes. -An item that has the AllScope property is visible in the child scope, and -it is part of that scope. Changes to the item in any scope affect all the -scopes in which the variable is defined. +An item that has the AllScope property is visible in the child scope, and it +is part of that scope. Changes to the item in any scope affect all the scopes +in which the variable is defined. -## Managing Scope +### Managing Scope -Several cmdlets have a Scope parameter that lets you get or set (create -and change) items in a particular scope. Use the following command to find -all the cmdlets in your session that have a Scope parameter: +Several cmdlets have a Scope parameter that lets you get or set (create and +change) items in a particular scope. Use the following command to find all the +cmdlets in your session that have a Scope parameter: ```powershell get-help * -parameter scope ``` -To find the variables that are visible in a particular scope, use the -Scope parameter of Get-Variable. The visible parameters include global -parameters, parameters in the parent scope, and parameters in the current -scope. +To find the variables that are visible in a particular scope, use the Scope +parameter of Get-Variable. The visible parameters include global parameters, +parameters in the parent scope, and parameters in the current scope. -For example, the following command gets the variables that are visible in -the local scope: +For example, the following command gets the variables that are visible in the +local scope: ```powershell get-variable -scope local ``` -To create a variable in a particular scope, use a scope modifier or the -Scope parameter of Set-Variable. The following command creates a variable -in the global scope: +To create a variable in a particular scope, use a scope modifier or the Scope +parameter of Set-Variable. The following command creates a variable in the +global scope: -``` +```powershell new-variable -scope global -name a -value "One" ``` -You can also use the Scope parameter of the New-Alias, Set-Alias, or -Get-Alias cmdlets to specify the scope. The following command creates an -alias in the global scope: +You can also use the Scope parameter of the New-Alias, Set-Alias, or Get-Alias +cmdlets to specify the scope. The following command creates an alias in the +global scope: -``` +```powershell new-alias -scope global -name np -value Notepad.exe ``` -To get the functions in a particular scope, use the Get-Item cmdlet when -you are in the scope. The Get-Item cmdlet does not have a scope parameter. +To get the functions in a particular scope, use the Get-Item cmdlet when you +are in the scope. The Get-Item cmdlet does not have a scope parameter. -## Using Dot Source Notation with Scope +### Using Dot Source Notation with Scope Scripts and functions follow all the rules of scope. You create them in a particular scope, and they affect only that scope unless you use a cmdlet parameter or a scope modifier to change that scope. -But, you can add a script or function to the current scope by using dot -source notation. Then, when a script runs in the current scope, any -functions, aliases, and variables that the script creates are available -in the current scope. +But, you can add a script or function to the current scope by using dot source +notation. Then, when a script runs in the current scope, any functions, +aliases, and variables that the script creates are available in the current +scope. -To add a function to the current scope, type a dot (.) and a space before -the path and name of the function in the function call. +To add a function to the current scope, type a dot (.) and a space before the +path and name of the function in the function call. -For example, to run the `Sample.ps1` script from the `C:\Scripts` directory in -the script scope (the default for scripts), use the following command: +For example, to run the Sample.ps1 script from the C:\Scripts directory in the +script scope (the default for scripts), use the following command: ```powershell c:\scripts\sample.ps1 ``` -To run the `Sample.ps1` script in the local scope, use the following command: +To run the Sample.ps1 script in the local scope, use the following command: ```powershell . c:\scripts.sample.ps1 ``` -When you use the call operator `&` to run a function or script, it is not +When you use the call operator (&) to run a function or script, it is not added to the current scope. The following example uses the call operator: ```powershell & c:\scripts.sample.ps1 ``` -Any aliases, functions, or variables that the Sample.ps1 script creates -are not available in the current scope. - -## Restricting Without Scope +Any aliases, functions, or variables that the Sample.ps1 script creates are +not available in the current scope. -A few Windows PowerShell concepts are similar to scope or interact with -scope. These concepts may be confused with scope or the behavior of scope. +### Restricting Without Scope -Sessions, modules, and nested prompts are self-contained environments, -but they are not child scopes of the global scope in the session. +A few PowerShell concepts are similar to scope or interact with scope. These +concepts may be confused with scope or the behavior of scope. -### Sessions -A session is an environment in which Windows PowerShell runs. -When you create a session on a remote computer, Windows -PowerShell establishes a persistent connection to the remote -computer. The persistent connection lets you use the session for -multiple related commands. +Sessions, modules, and nested prompts are self-contained environments, but +they are not child scopes of the global scope in the session. -Because a session is a contained environment, it has its own -scope, but a session is not a child scope of the session in -which is was created. The session starts with its own global -scope. This scope is independent of the global scope of the session. -You can create child scopes in the session. For example, you can run -a script to create a child scope in a session. +- Sessions: A session is an environment in which PowerShell runs. When you + create a session on a remote computer, PowerShell establishes a + persistent connection to the remote computer. The persistent connection lets + you use the session for multiple related commands. -### Modules -You can use a Windows PowerShell module to share and deliver -Windows PowerShell tools. A module is a unit that can contain -cmdlets, scripts, functions, variables, aliases, and other useful -items. Unless explicitly defined, the items in a module are not -accessible outside the module. Therefore, you can add the module to -your session and use the public items without worrying that the -other items might override the cmdlets, scripts, functions, and other -items in your session. + Because a session is a contained environment, it has its own scope, but a + session is not a child scope of the session in which is was created. The + session starts with its own global scope. This scope is independent of the + global scope of the session. You can create child scopes in the session. For + example, you can run a script to create a child scope in a session. -The privacy of a module behaves like a scope, but adding a module -to a session does not change the scope. And, the module does not have -its own scope, although the scripts in the module, like all Windows -PowerShell scripts, do have their own scope. +- Modules: You can use a PowerShell module to share and deliver PowerShell + tools. A module is a unit that can contain cmdlets, scripts, functions, + variables, aliases, and other useful items. Unless explicitly defined, the + items in a module are not accessible outside the module. Therefore, you can + add the module to your session and use the public items without worrying that + the other items might override the cmdlets, scripts, functions, and other + items in your session. -### Nested Prompts -Similarly, nested prompts do not have their own scope. When you enter -a nested prompt, the nested prompt is a subset of the environment. -But, you remain within the local scope. + The privacy of a module behaves like a scope, but adding a module to a session + does not change the scope. And, the module does not have its own scope, + although the scripts in the module, like all PowerShell scripts, do + have their own scope. -Scripts do have their own scope. If you are debugging a script, and -you reach a breakpoint in the script, you enter the script scope. +- Nested Prompts: Similarly, nested prompts do not have their own scope. When + you enter a nested prompt, the nested prompt is a subset of the environment. + But, you remain within the local scope. -### Private Option -Aliases and variables have an Option property that can take a value -of Private. Items that have the Private option can be viewed and -changed in the scope in which they are created, but they cannot be -viewed or changed outside that scope. + Scripts do have their own scope. If you are debugging a script, and you reach + a breakpoint in the script, you enter the script scope. -For example, if you create a variable that has a private option in the -global scope and then run a script, Get-Variable commands in the script -do not display the private variable. This occurs even if you use -the global scope modifier. +- Private Option: Aliases and variables have an Option property that can take a + value of Private. Items that have the Private option can be viewed and changed + in the scope in which they are created, but they cannot be viewed or changed + outside that scope. -You can use the Option parameter of the `New-Variable`, `Set-Variable`, -`New-Alias`, and `Set-Alias` cmdlets to set the value of the Option -property to Private. + For example, if you create a variable that has a private option in the global + scope and then run a script, Get-Variable commands in the script do not + display the private variable. This occurs even if you use the global scope + modifier. -### Visibility -The Visibility property of a variable or alias determines whether you -can see the item outside the container, such as a module, in which it -was created. Visibility is designed for containers in the same way that -the Private value of the Option property is designed for scopes. + You can use the Option parameter of the New-Variable, Set-Variable, New-Alias, + and Set-Alias cmdlets to set the value of the Option property to Private. -The Visibility property takes the Public and Private values. Items -that have private visibility can be viewed and changed only in the -container in which they were created. If the container is added or -imported, the items that have private visibility cannot be viewed or -changed. +- Visibility: The Visibility property of a variable or alias determines whether + you can see the item outside the container, such as a module, in which it was + created. Visibility is designed for containers in the same way that the + Private value of the Option property is designed for scopes. -Because Visibility is designed for containers, it works differently -in a scope. If you create an item that has private visibility in the -global scope, you cannot view or change the item in any scope. If you -try to view or change the value of a variable that has private -visibility, Windows PowerShell returns an error message. + The Visibility property takes the Public and Private values. Items that have + private visibility can be viewed and changed only in the container in which + they were created. If the container is added or imported, the items that have + private visibility cannot be viewed or changed. -You can use the New-Variable and Set-Variable cmdlets to create a -variable that has private visibility. + Because Visibility is designed for containers, it works differently in a + scope. If you create an item that has private visibility in the global scope, + you cannot view or change the item in any scope. If you try to view or change + the value of a variable that has private visibility, PowerShell returns an + error message. -# EXAMPLES + You can use the New-Variable and Set-Variable cmdlets to create a variable + that has private visibility. +## EXAMPLES -## Example 1: Change a Variable Value Only in a Script +### Example 1: Change a Variable Value Only in a Script -The following command changes the value of the $ConfirmPreference -variable in a script. The change does not affect the global scope. +The following command changes the value of the \$ConfirmPreference variable in +a script. The change does not affect the global scope. -First, to display the value of the $ConfirmPreference variable in -the local scope, use the following command: +First, to display the value of the \$ConfirmPreference variable in the local +scope, use the following command: ``` C:\PS> $ConfirmPreference High ``` -Create a `Scope.ps1` script that contains the following commands: +Create a Scope.ps1 script that contains the following commands: ```powershell $ConfirmPreference = "Low" "The value of `$ConfirmPreference is $ConfirmPreference." ``` -Run the script. The script changes the value of the $ConfirmPreference -variable and then reports its value in the script scope. The output -should resemble the following output: +Run the script. The script changes the value of the \$ConfirmPreference +variable and then reports its value in the script scope. The output should +resemble the following output: -``` +```output The value of $ConfirmPreference is Low. ``` -Next, test the current value of the $ConfirmPreference variable in the -current scope. +Next, test the current value of the \$ConfirmPreference variable in the current +scope. ``` C:\PS> $ConfirmPreference High ``` -This example shows that changes to the value of a variable in the script -scope do not affect the value of that variable in the parent scope. +This example shows that changes to the value of a variable in the script scope +do not affect the value of that variable in the parent scope. -## Example 2: View a Variable Value in Different Scopes +### Example 2: View a Variable Value in Different Scopes -You can use scope modifiers to view the value of a variable in the local -scope and in a parent scope. +You can use scope modifiers to view the value of a variable in the local scope +and in a parent scope. -First, define a `$test` variable in the global scope. +First, define a $test variable in the global scope. ```powershell $test = "Global" ``` -Next, create a `Sample.ps1` script that defines the `$test` -variable. In the script, use a scope modifier to refer -to either the global or local versions of the $test variable. +Next, create a Sample.ps1 script that defines the \$test variable. In the +script, use a scope modifier to refer to either the global or local versions +of the \$test variable. -In Sample.ps1 +In Sample.ps1: ```powershell $test = "Local" @@ -429,125 +402,125 @@ $test = "Local" "The global value of `$test is $global:test." ``` -When you run `Sample.ps1`, the output should resemble the following output: +When you run Sample.ps1, the output should resemble the following output: -``` +```output The local value of $test is Local. The global value of $test is Global. ``` -When the script is complete, only the global value of `$test` is defined -in the session. +When the script is complete, only the global value of \$test is defined in the +session. ``` C:\PS> $test Global ``` -## Example 3: Change the Value of a Variable in a Parent Scope +### Example 3: Change the Value of a Variable in a Parent Scope -Unless you protect an item by using the Private option or another -method, you can view and change the value of a variable in a parent -scope. +Unless you protect an item by using the Private option or another method, you +can view and change the value of a variable in a parent scope. -First, define a $test variable in the global scope. +First, define a \$test variable in the global scope. ```powershell $test = "Global" ``` -Next, create a `Sample.ps1` script that defines the $test variable. In the -script, use a scope modifier to refer to either the global or local -versions of the `$test` variable. +Next, create a Sample.ps1 script that defines the \$test variable. In the +script, use a scope modifier to refer to either the global or local versions +of the \$test variable. -In Sample.ps1 +In Sample.ps1: ```powershell $global:test = "Local" "The global value of `$test is $global:test." ``` -When the script is complete, the global value of $test is changed. +When the script is complete, the global value of \$test is changed. ``` C:\PS> $test Local ``` -## Example 4: Creating a Private Variable +### Example 4: Creating a Private Variable -A private variable is a variable that has an Option property that has a -value of Private. Private variables are inherited by the child scope, but -they can be viewed or changed only in the scope in which they were -created. +A private variable is a variable that has an Option property that has a value +of Private. Private variables are inherited by the child scope, but they can +be viewed or changed only in the scope in which they were created. -The following command creates a private variable called $ptest in the -local scope. +The following command creates a private variable called \$ptest in the local +scope. ```powershell New-Variable -Name ptest -Value 1 -Option private ``` -You can display and change the value of $ptest in the local scope. +You can display and change the value of \$ptest in the local scope. ``` C:\PS> $ptest -# 1 +1 C:\PS> $ptest = 2 C:\PS> $ptest -# 2 +2 ``` -Next, create a `Sample.ps1` script that contains the following commands. -The command tries to display and change the value of $ptest. +Next, create a Sample.ps1 script that contains the following commands. The +command tries to display and change the value of \$ptest. -In Sample.ps1 +In Sample.ps1: -``` +```powershell "The value of `$Ptest is $Ptest." "The value of `$Ptest is $global:Ptest." ``` -Because the `$ptest` variable is not visible in the script scope, the -output is empty. +Because the $ptest variable is not visible in the script scope, the output is +empty. -``` +```powershell "The value of $Ptest is ." "The value of $Ptest is ." ``` -## Example 5: Using a Local Variable in a Remote Command +### Example 5: Using a Local Variable in a Remote Command -To indicate that a variable in a remote command was created in the -local session, use the Using scope modifier. By default, Windows -PowerShell assumes that the variables in remote commands were created -in the remote session. +To indicate that a variable in a remote command was created in the local +session, use the Using scope modifier. By default, PowerShell assumes +that the variables in remote commands were created in the remote session. The syntax is: + ``` $Using: ``` -For example, the following commands create a `$Cred` variable in the -local session and then use the $Cred variable in a remote command: +For example, the following commands create a $Cred variable in the local +session and then use the $Cred variable in a remote command: ```powershell $Cred = Get-Credential Invoke-Command $s {Remove-Item .\Test*.ps1 -Credential $Using:Cred} ``` -The Using scope was introduced in Windows PowerShell 3.0. - -In Windows PowerShell 2.0, to indicate that a variable was created in -the local session, use the following command format. +The Using scope was introduced in PowerShell 3.0. In PowerShell 2.0, to +indicate that a variable was created in the local session, use the following +command format. ```powershell $Cred = Get-Credential -Invoke-Command $s {param($c) Remove-Item .\Test*.ps1 -Credential $c} -ArgumentList $Cred +Invoke-Command $s { + param($c) + Remove-Item .\Test*.ps1 -Credential $c +} -ArgumentList $Cred ``` -# SEE ALSO +## SEE ALSO [about_Variables](about_Variables.md) @@ -556,4 +529,3 @@ Invoke-Command $s {param($c) Remove-Item .\Test*.ps1 -Credential $c} -ArgumentLi [about_Functions](about_Functions.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md index a4409d59d90f..06219eb3961e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,63 +10,63 @@ title: about_Script_Internationalization ## Short Description -Describes the script internationalization features that make it easy for scripts to display -messages and instructions to users in their user interface (UI) language. +Describes the script internationalization features that make it easy for +scripts to display messages and instructions to users in their user interface +(UI) language. ## Long Description The Windows PowerShell script internationalization features allow you to -better serve users throughout the world by displaying Help and user -messages for scripts and functions in the user's UI language. +better serve users throughout the world by displaying Help and user messages +for scripts and functions in the user's UI language. -The script internationalization features query the UI culture of the -operating system during execution, import the appropriate -translated text strings, and display them to the user. The Data section -lets you store text strings separate from code so they are easily -identified and extracted. A new cmdlet, `ConvertFrom-StringData`, -converts text strings into dictionary-like hash tables to facilitate -translation. +The script internationalization features query the UI culture of the operating +system during execution, import the appropriate translated text strings, and +display them to the user. The Data section lets you store text strings +separate from code so they are easily identified and extracted. A new cmdlet, +`ConvertFrom-StringData`, converts text strings into dictionary-like hash +tables to facilitate translation. -To support international Help text, Windows PowerShell includes the -following features: +To support international Help text, Windows PowerShell includes the following +features: -* A Data section that separates text strings from code instructions. For -more information about the Data section, see [about_Data_Sections](about_Data_Sections.md). +* A Data section that separates text strings from code instructions. For more + information about the Data section, see + [aout_Data_Sections](about_Data_Sections.md). -* New automatic variables, $PSCulture and $PSUICulture. $PSCulture stores -the name of the UI language used on the system for elements such as -the date, time, and currency. The $PSUICulture variable stores the -name of the UI language used on the system for user interface elements -such as menus and text strings. +* New automatic variables, \$PSCulture and \$PSUICulture. \$PSCulture stores the + name of the UI language used on the system for elements such as the date, + time, and currency. The $PSUICulture variable stores the name of the UI + language used on the system for user interface elements such as menus and text + strings. * A cmdlet, `ConvertFrom-StringData`, that converts text strings into -dictionary-like hash tables to facilitate translation. For more -information, see [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md). + dictionary-like hash tables to facilitate translation. For more information, + see [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md). -* A new file type, .psd1, that stores translated text strings. The .psd1 -files are stored in language-specific subdirectories of the script -directory. +* A new file type, .psd1, that stores translated text strings. The .psd1 files + are stored in language-specific subdirectories of the script directory. -* A cmdlet, `Import-LocalizedData`, that imports translated text strings -for a specified language into a script at runtime. This cmdlet recognizes -and imports strings in any Windows-supported language. For more -information see [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md). +* A cmdlet, `Import-LocalizedData`, that imports translated text strings for a + specified language into a script at runtime. This cmdlet recognizes and + imports strings in any Windows-supported language. For more information see + [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md). ### The Data Section: Storing Default Strings -Use a Data section in the script to store the text strings in the default language. -Arrange the strings in key/value pairs in a here-string. Each key/value pair must -be on a separate line. If you include comments, the comments must be on separate -lines. +Use a Data section in the script to store the text strings in the default +language. Arrange the strings in key/value pairs in a here-string. Each +key/value pair must be on a separate line. If you include comments, the +comments must be on separate lines. -The `ConvertFrom-StringData` cmdlet converts the key/value pairs in the here-string -into a dictionary-like hash table that is stored in the value of the Data section -variable. +The `ConvertFrom-StringData` cmdlet converts the key/value pairs in the +here-string into a dictionary-like hash table that is stored in the value of +the Data section variable. In the following example, the Data section of the World.ps1 script includes the English-United States (en-US) set of prompt messages for a script. The -`ConvertFrom-StringData` cmdlet converts the strings into a hash table and stores -them in the $msgtable variable. +`ConvertFrom-StringData` cmdlet converts the strings into a hash table and +stores them in the $msgtable variable. ```powershell $msgTable = Data { @@ -79,21 +79,22 @@ $msgTable = Data { } ``` -For more information about here-strings, see [about_Quoting_Rules](about_Quoting_Rules.md). +For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). ### PSD1 Files: Storing Translated Strings -Save the script messages for each UI language in separate text files with -the same name as the script and the .psd1 file name extension. Store the files -in subdirectories of the script directory with names of cultures in the following +Save the script messages for each UI language in separate text files with the +same name as the script and the .psd1 file name extension. Store the files in +subdirectories of the script directory with names of cultures in the following format: \-\ Examples: de-DE, ar-SA, and zh-Hans -For example, if the World.ps1 script is stored in the C:\Scripts directory, you -would create a file directory structure that resembles the following: +For example, if the World.ps1 script is stored in the C:\Scripts directory, +you would create a file directory structure that resembles the following: ``` C:\Scripts @@ -104,8 +105,8 @@ C:\Scripts\zh-CN\World.psd1 ... ``` -The World.psd1 file in the de-DE subdirectory of the script directory -might include the following statement: +The World.psd1 file in the de-DE subdirectory of the script directory might +include the following statement: ```powershell ConvertFrom-StringData -StringData @' @@ -115,8 +116,8 @@ promptMsg = Please enter your user name (in German). '@ ``` -Similarly, the World.psd1 file in the ar-SA subdirectory of the script directory -might includes the following statement: +Similarly, the World.psd1 file in the ar-SA subdirectory of the script +directory might includes the following statement: ```powershell ConvertFrom-StringData -StringData @' @@ -128,70 +129,63 @@ promptMsg = Please enter your user name (in Arabic). ### Import-LocalizedData: Dynamic Retrieval of Translated Strings -To retrieve the strings in the UI language of the current user, use -the `Import-LocalizedData` cmdlet. +To retrieve the strings in the UI language of the current user, use the +`Import-LocalizedData` cmdlet. -`Import-LocalizedData` finds the value of the $PSUICulture automatic -variable and imports the content of the \.psd1 files in -the subdirectory that matches the $PSUICulture value. Then, it saves -the imported content in the variable specified by the value of the -**BindingVariable** parameter. +`Import-LocalizedData` finds the value of the \$PSUICulture automatic variable +and imports the content of the \.psd1 files in the subdirectory +that matches the \$PSUICulture value. Then, it saves the imported content in +the variable specified by the value of the **BindingVariable** parameter. ```powershell Import-LocalizedData -BindingVariable msgTable ``` For example, if the `Import-LocalizedData` command appears in the -C:\Scripts\World.ps1 script and the value of $PSUICulture is -"ar-SA", `Import-LocalizedData` finds the following file: +C:\\Scripts\\World.ps1 script and the value of $PSUICulture is "ar-SA", +`Import-LocalizedData` finds the following file: -C:\Scripts\ar-SA\World.psd1 +C:\\Scripts\\ar-SA\\World.psd1 -Then, it imports the Arabic text strings from the file into -the $msgTable variable, replacing any default strings that might -be defined in the Data section of the World.ps1 script. +Then, it imports the Arabic text strings from the file into the $msgTable +variable, replacing any default strings that might be defined in the Data +section of the World.ps1 script. -As a result, when the script uses the $msgTable variable -to display user messages, the messages are displayed in -Arabic. +As a result, when the script uses the $msgTable variable to display user +messages, the messages are displayed in Arabic. -For example, the following script displays the "Please enter your user -name" message in Arabic: +For example, the following script displays the "Please enter your user name" +message in Arabic: ```powershell if (!($username)) { $msgTable.promptMsg } ``` -If `Import-LocalizedData` cannot find a .psd1 file that matches the -value of $PSUIculture, the value of $msgTable is not replaced, -and the call to $msgTable.promptMsg displays the fallback en-US -strings. +If `Import-LocalizedData` cannot find a .psd1 file that matches the value of +\$PSUIculture, the value of \$msgTable is not replaced, and the call to +\$msgTable.promptMsg displays the fallback en-US strings. ## Examples -This example shows how the script internationalization features -are used in a script to display a day of the week to users -in the language that is set on the computer. +This example shows how the script internationalization features are used in a +script to display a day of the week to users in the language that is set on +the computer. -The following is a complete listing of the Sample1.ps1 script -file. +The following is a complete listing of the Sample1.ps1 script file. -The script begins with a Data section named Day ($Day) that -contains a `ConvertFrom-StringData` command. The expression -submitted to `ConvertFrom-StringData` is a here-string that -contains the day names in the default UI culture, en-US, in -key/value pairs. The `ConvertFrom-StringData` cmdlet converts -the key/value pairs in the here-string into a hash table and +The script begins with a Data section named Day ($Day) that contains a +`ConvertFrom-StringData` command. The expression submitted to +`ConvertFrom-StringData` is a here-string that contains the day names in the +default UI culture, en-US, in key/value pairs. The `ConvertFrom-StringData` +cmdlet converts the key/value pairs in the here-string into a hash table and then saves it in the value of the $Day variable. -The `Import-LocalizedData` command imports the contents of the -.psd1 file in the directory that matches the value of the -$PSUICulture automatic variable and then saves it in the $Day -variable, replacing the values of $Day that are defined in the -Data section. +The `Import-LocalizedData` command imports the contents of the .psd1 file in +the directory that matches the value of the $PSUICulture automatic variable +and then saves it in the $Day variable, replacing the values of $Day that are +defined in the Data section. -The remaining commands load the strings into an array and display -them. +The remaining commands load the strings into an array and display them. ```powershell $Day = Data { @@ -239,10 +233,10 @@ ConvertFrom-StringData @' '@ ``` -As a result, when you run Sample.ps1 on a system on which the value -of $PSUICulture is de-DE, the output of the script is: +As a result, when you run Sample.ps1 on a system on which the value of +\$PSUICulture is de-DE, the output of the script is: -``` +```output Today is Friday (in German) ``` @@ -254,4 +248,3 @@ Today is Friday (in German) * [about_Quoting_Rules](about_Quoting_Rules.md) * [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md) * [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md index fe470e6bc5b4..b3d7fc0d56e2 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,284 +7,296 @@ title: about_Session_Configuration_Files --- # About Session Configuration Files -## about_Session_Configuration_Files +## SHORT DESCRIPTION +Describes session configuration files, which are used in a session +configuration (also known as an "endpoint") to define the environment of +sessions that use the session configuration. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes session configuration files, which are used in a -session configuration (also known as an "endpoint") to define the -environment of sessions that use the session configuration. - -# LONG DESCRIPTION - -A "session configuration file" is a text file with a .pssc file -name extension that contains a hash table of session configuration -properties and values. You can use a session configuration file to -set the properties of a session configuration. Doing so defines -the environment of any Windows PowerShell sessions that use that -session configuration. +A "session configuration file" is a text file with a .pssc file name extension +that contains a hash table of session configuration properties and values. You +can use a session configuration file to set the properties of a session +configuration. Doing so defines the environment of any Windows PowerShell +sessions that use that session configuration. Session configuration files make it easy to create custom session configurations without using complex C# assemblies or scripts. -A "session configuration" or "endpoint" is a collection of local -computer settings that determine such things as which users can -create sessions on the computer; which commands users can run in -those sessions; and whether the session should run as a privileged -virtual account. For more information about session configurations, -see about_Session_Configurations -(http://go.microsoft.com/fwlink/?LinkID=145152). - -Session configurations were introduced in Windows PowerShell 2.0, -and session configuration files were introduced in Windows -PowerShell 3.0. You must use Windows PowerShell 3.0 to include a -session configuration file in a session configuration. However, -users of Windows PowerShell 2.0 (and later) are affected by the -settings in the session configuration. - -Creating Custom Sessions -You can customize many features of a Windows PowerShell session -by specifying session properties in a session configuration. You -can customize a session by writing a C# program that defines a -custom runspace, or you can use a session configuration file to -define the properties of sessions created by using the session -configuration. As a general rule, it is easier to use the session +A "session configuration" or "endpoint" is a collection of local computer +settings that determine such things as which users can create sessions on the +computer; which commands users can run in those sessions; and whether the +session should run as a privileged virtual account. For more information about +session configurations, see [about_Session_Configurations](about_Session_Configurations.md). + +Session configurations were introduced in Windows PowerShell 2.0, and session +configuration files were introduced in Windows PowerShell 3.0. You must use +Windows PowerShell 3.0 to include a session configuration file in a session +configuration. However, users of Windows PowerShell 2.0 (and later) are +affected by the settings in the session configuration. + +## Creating Custom Sessions + +You can customize many features of a Windows PowerShell session by specifying +session properties in a session configuration. You can customize a session by +writing a C# program that defines a custom runspace, or you can use a session +configuration file to define the properties of sessions created by using the +session configuration. As a general rule, it is easier to use the session configuration file than to write a C# program. You can use a session configuration file to create items such as -fully-functioning sessions for highly trusted users; locked-down -sessions that allow minimal access; sessions designed for -particular and that contain only the modules required for those -tasks; and sessions where unprivileged users can only run -specific commands as a privileged account. - -In addition to that, you can manage whether users of the -session can use Windows PowerShell language elements such as -script blocks, or whether they can only run commands. You can -manage the version of Windows PowerShell users can run in the -session; manage which modules are imported into the session; and -manage which cmdlets, functions, and aliases session users can -run. When using the RoleDefinitions field, you can give users -different capabilities in the session based on group membership. - -For more information about RoleDefinitions and how to define this -Value, see the help topic for the New-PSRoleCapabilityFile -Cmdlet. - -Creating a Session Configuration File -The easiest way to create a session configuration file is by -using the New-PSSessionConfigurationFile cmdlet. This cmdlet -generates a file that uses the correct syntax and format, and -that automatically verifies many of the configuration file -property values. - -For detailed descriptions of the properties that you can set in -a session configuration file, see the help topic for the -New-PSSessionConfigurationFile cmdlet. - -The following command creates a session configuration file that -uses the default values. The resulting configuration file uses only -the default values because no parameters other than the Path -parameter (which specifies the file path) are included: - -PS C:> New-PSSessionConfigurationFile -Path .\Defaults.pssc - -To view the new configuration file in your default text editor, -use the following command: - -PS C:> Invoke-Item -Path .\Defaults.pssc - -To create a session configuration for sessions in which -user can run commands, but not use other elements of the Windows -PowerShell language, type: - -PS C:> New-PSSessionConfigurationFile -LanguageMode NoLanguage +fully-functioning sessions for highly trusted users; locked-down sessions that +allow minimal access; sessions designed for particular and that contain only +the modules required for those tasks; and sessions where unprivileged users +can only run specific commands as a privileged account. + +In addition to that, you can manage whether users of the session can use +Windows PowerShell language elements such as script blocks, or whether they +can only run commands. You can manage the version of Windows PowerShell users +can run in the session; manage which modules are imported into the session; +and manage which cmdlets, functions, and aliases session users can run. When +using the RoleDefinitions field, you can give users different capabilities in +the session based on group membership. + +For more information about RoleDefinitions and how to define this Value, see +the help topic for the New-PSRoleCapabilityFile Cmdlet. + +## Creating a Session Configuration File + +The easiest way to create a session configuration file is by using the +New-PSSessionConfigurationFile cmdlet. This cmdlet generates a file that uses +the correct syntax and format, and that automatically verifies many of the +configuration file property values. + +For detailed descriptions of the properties that you can set in a session +configuration file, see the help topic for the New-PSSessionConfigurationFile +cmdlet. + +The following command creates a session configuration file that uses the +default values. The resulting configuration file uses only the default values +because no parameters other than the Path parameter (which specifies the file +path) are included: + +```powershell +New-PSSessionConfigurationFile -Path .\Defaults.pssc +``` + +To view the new configuration file in your default text editor, use the +following command: + +```powershell +Invoke-Item -Path .\Defaults.pssc +``` + +To create a session configuration for sessions in which user can run commands, +but not use other elements of the Windows PowerShell language, type: + +```powershell +New-PSSessionConfigurationFile -LanguageMode NoLanguage -Path .\NoLanguage.pssc +``` -In the preceding command, setting the LanguageMode parameter to -NoLanguage prevents users from doing such things as writing or -running scripts, or using variables. +In the preceding command, setting the LanguageMode parameter to NoLanguage +prevents users from doing such things as writing or running scripts, or using +variables. -To create a session configuration for sessions in which users can -use only Get cmdlets, type: +To create a session configuration for sessions in which users can use only Get +cmdlets, type: -PS C:> New-PSSessionConfigurationFile -VisibleCmdlets Get-* +```powershell +New-PSSessionConfigurationFile -VisibleCmdlets Get-* -Path .\GetSessions.pssc +``` -In the preceding example, setting the VisibleCmdlets parameter to -Get-* limits users to cmdlets that have names that start with the -string value "Get-". +In the preceding example, setting the VisibleCmdlets parameter to Get-* limits +users to cmdlets that have names that start with the string value "Get-". -To create a session configuration for sessions that run under a -privileged virtual account instead of the user's credentials, type: +To create a session configuration for sessions that run under a privileged +virtual account instead of the user's credentials, type: -PS C:> New-PSSessionConfigurationFile -RunAsVirtualAccount +```powershell +New-PSSessionConfigurationFile -RunAsVirtualAccount -Path .\VirtualAccount.pssc +``` -To create a session configuration for sessions in which the -commands visible to the user are specified in a role capabilities -file, type: +To create a session configuration for sessions in which the commands visible +to the user are specified in a role capabilities file, type: -PS C:> New-PSSessionConfigurationFile -RoleDefinitions +```powershell +New-PSSessionConfigurationFile -RoleDefinitions @{ 'CONTOSO\User' = @{ RoleCapabilities = 'Maintenance' }} -Path .\Maintenance.pssc +``` -Using a Session Configuration File -You can include a session configuration file when you create a -session configuration or add you can add a file to the session -configuration at a later time. +### Using a Session Configuration File -To include a session configuration file when creating a session -configuration, use the Path parameter of the -Register-PSSessionConfiguration cmdlet. +You can include a session configuration file when you create a session +configuration or add you can add a file to the session configuration at a +later time. -For example, the following command uses the NoLanguage.pssc file -when it creates a NoLanguage session configuration. +To include a session configuration file when creating a session configuration, +use the Path parameter of the Register-PSSessionConfiguration cmdlet. -PS C:> Register-PSSessionConfiguration -Name NoLanguage +For example, the following command uses the NoLanguage.pssc file when it +creates a NoLanguage session configuration. + +```powershell +Register-PSSessionConfiguration -Name NoLanguage -Path .\NoLanguage.pssc +``` -When a new NoLanguage session starts, users will only have access -to Windows PowerShell commands. +When a new NoLanguage session starts, users will only have access to Windows +PowerShell commands. -To add a session configuration file to an existing session -configuration, use the Set-PSSessionConfiguration cmdlet and the -Path parameter. This affects any new sessions created with the -specified session configuration. Note that the -Set-PSSessionConfiguration cmdlet changes the session itself and -does not modify the session configuration file. +To add a session configuration file to an existing session configuration, use +the Set-PSSessionConfiguration cmdlet and the Path parameter. This affects any +new sessions created with the specified session configuration. Note that the +Set-PSSessionConfiguration cmdlet changes the session itself and does not +modify the session configuration file. -For example, the following command adds the NoLanguage.pssc file -to the LockedDown session configuration. +For example, the following command adds the NoLanguage.pssc file to the +LockedDown session configuration. -PS C:> Set-PSSessionConfiguration -Name LockedDown +```powershell +Set-PSSessionConfiguration -Name LockedDown -Path .\NoLanguage.pssc +``` -When users use the LockedDown session configuration to create a -session, they will be able to run cmdlets but they will not be -able to create or use variables, assign values, or use other -Windows PowerShell language elements. +When users use the LockedDown session configuration to create a session, they +will be able to run cmdlets but they will not be able to create or use +variables, assign values, or use other Windows PowerShell language elements. -The following command uses the New-PSSession cmdlet to create a -session on the computer Srv01 that uses the LockedDown session -configuration, saving an object reference to the session in the $s -variable. The ACL (access control list) of the session -configuration determines who can use it to create a session. +The following command uses the New-PSSession cmdlet to create a session on the +computer Srv01 that uses the LockedDown session configuration, saving an +object reference to the session in the $s variable. The ACL (access control +list) of the session configuration determines who can use it to create a +session. -PS C:> $s = New-PSSession -ComputerName Srv01 +```powershell +$s = New-PSSession -ComputerName Srv01 -ConfigurationName LockedDown - -Because the NoLanguage constraints were added to the LockedDown -session configuration, users in LockedDown sessions will only be -able to run Windows PowerShell commands and cmdlets. For example, -the following two commands use the Invoke-Command cmdlet to run -commands in the session referenced in the $s variable. The first -command, which runs the Get-UICulture cmdlet and does not use any -variables, succeeds. The second command, which gets the value of -the $PSUICulture variable, fails. - -PS C:> Invoke-Command -Session $s {Get-UICulture} +``` + +Because the NoLanguage constraints were added to the LockedDown session +configuration, users in LockedDown sessions will only be able to run Windows +PowerShell commands and cmdlets. For example, the following two commands use +the Invoke-Command cmdlet to run commands in the session referenced in the $s +variable. The first command, which runs the Get-UICulture cmdlet and does not +use any variables, succeeds. The second command, which gets the value of the +$PSUICulture variable, fails. + +``` +Invoke-Command -Session $s {Get-UICulture} en-US -PS C:> Invoke-Command -Session $s {$PSUICulture} +Invoke-Command -Session $s {$PSUICulture} The syntax is not supported by this runspace. This might be because it is in no-language mode. + CategoryInfo : ParserError: ($PSUICulture:String) [], ParseException + FullyQualifiedErrorId : ScriptsNotAllowed +``` + +## Editing a Session Configuration File -Editing a Session Configuration File -All settings in a session configuration except for -RunAsVirtualAccount and RunAsVirtualAccountGroups can be modified -by editing the session configuration file used by the session -configuration. To do this, begin by locating the active copy of the -session configuration file. +All settings in a session configuration except for RunAsVirtualAccount and +RunAsVirtualAccountGroups can be modified by editing the session configuration +file used by the session configuration. To do this, begin by locating the +active copy of the session configuration file. -When you use a session configuration file in a session -configuration, Windows PowerShell creates an active copy of the -session configuration file and stores it in the -$pshome\SessionConfig directory on the local computer. +When you use a session configuration file in a session configuration, Windows +PowerShell creates an active copy of the session configuration file and stores +it in the \$pshome\\SessionConfig directory on the local computer. -The location of the active copy of a session configuration file is -stored in the ConfigFilePath property of the session configuration -object. +The location of the active copy of a session configuration file is stored in +the ConfigFilePath property of the session configuration object. -The following command gets the location of the session -configuration file for the NoLanguage session configuration. +The following command gets the location of the session configuration file for +the NoLanguage session configuration. -PS C:> (Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath +```powershell +(Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath +``` That command returns a file path similar to the following: +``` C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc +``` -You can edit the .pssc file in any text editor. After the file is -saved it will be employed by any new sessions that use the session -configuration. +You can edit the .pssc file in any text editor. After the file is saved it +will be employed by any new sessions that use the session configuration. -If you need to modify the RunAsVirtualAccount or the -RunAsVirtualAccountGroups settings, you must un-register the -session configuration and re-register a session configuration file -that includes the edited values. +If you need to modify the RunAsVirtualAccount or the RunAsVirtualAccountGroups +settings, you must un-register the session configuration and re-register a +session configuration file that includes the edited values. -Testing a Session Configuration File -Use the Test-PSSessionConfigurationFile cmdlet to test manually -edited session configuration files. That's important: if the file -syntax and values are not valid users will not be able to use the -session configuration to create a session. +## Testing a Session Configuration File -For example, the following command tests the active session -configuration file of the NoLanguage session configuration. +Use the Test-PSSessionConfigurationFile cmdlet to test manually edited session +configuration files. That's important: if the file syntax and values are not +valid users will not be able to use the session configuration to create a +session. -PS C:> Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\ +For example, the following command tests the active session configuration file +of the NoLanguage session configuration. + +```powershell +Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\ WindowsPowerShell\v1.0\SessionConfig\ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc +``` If the syntax and values in the configuration file are valid -Test-PSSessionConfigurationFile returns True. If the syntax and -values are not valid then the cmdlet returns False. - -You can use Test-PSSessionConfigurationFile to test any session -configuration file, including files that the -New-PSSessionConfiguration cmdlet creates. For more information, -see the help topic for the Test-PSSessionConfigurationFile cmdlet. - -Removing a Session Configuration File -You cannot remove a session configuration file from a session -configuration. However, you can replace the file with a new file -that uses the default settings. This effectively cancels the -settings used by the original configuration file. - -To replace a session configuration file, create a new session -configuration file that uses the default settings, then use the -Set-PSSessionConfiguration cmdlet to replace the custom session -configuration file with the new file. - -For example, the following commands create a Default session -configuration file and then replace the active session -configuration file in the NoLanguage session configuration. - -PS C:> New-PSSessionConfigurationFile -Path .\Default.pssc -PS C:> Set-PSSessionConfiguration -Name NoLanguage +Test-PSSessionConfigurationFile returns True. If the syntax and values are not +valid then the cmdlet returns False. + +You can use Test-PSSessionConfigurationFile to test any session configuration +file, including files that the New-PSSessionConfiguration cmdlet creates. For +more information, see the help topic for the Test-PSSessionConfigurationFile +cmdlet. + +## Removing a Session Configuration File + +You cannot remove a session configuration file from a session configuration. +However, you can replace the file with a new file that uses the default +settings. This effectively cancels the settings used by the original +configuration file. + +To replace a session configuration file, create a new session configuration +file that uses the default settings, then use the Set-PSSessionConfiguration +cmdlet to replace the custom session configuration file with the new file. + +For example, the following commands create a Default session configuration +file and then replace the active session configuration file in the NoLanguage +session configuration. + +```powershell +New-PSSessionConfigurationFile -Path .\Default.pssc +Set-PSSessionConfiguration -Name NoLanguage -Path .\Default.pssc +``` -When these commands finish, the NoLanguage session configuration -will actually provide full language support (the default setting) -for all sessions created with that session configuration. +When these commands finish, the NoLanguage session configuration will actually +provide full language support (the default setting) for all sessions created +with that session configuration. -Viewing the Properties of a Session Configuration -The session configuration objects that represent session -configurations using session configuration files have additional -properties that make it easy to discover and analyze the session -configuration. (Note that the type name shown below includes a -formatted view definition.) You can view the properties by running -the Get-PSSessionConfiguration cmdlet and piping the returned data -to the Get-Member cmdlet: +Viewing the Properties of a Session Configuration The session configuration +objects that represent session configurations using session configuration +files have additional properties that make it easy to discover and analyze the +session configuration. (Note that the type name shown below includes a +formatted view definition.) You can view the properties by running the +Get-PSSessionConfiguration cmdlet and piping the returned data to the +Get-Member cmdlet: -PS C:> Get-PSSessionConfiguration NoLanguage | Get-Member +```powershell +Get-PSSessionConfiguration NoLanguage | Get-Member +``` + +```output TypeName: Microsoft.PowerShell.Commands.PSSessionConfigurationCommands #PSSessionConfiguration @@ -331,62 +343,64 @@ SupportsOptions NoteProperty System.String Suppor... xmlns NoteProperty System.String xmlns=... XmlRenderingType NoteProperty System.String XmlRen... Permission ScriptProperty System.Object Permis... +``` -These properties make it easy to search for specific session -configurations. For example, you can use the ExecutionPolicy -property to find a session configuration that supports sessions -with the RemoteSigned execution policy. Note that, because the -ExecutionPolicy property exists only on sessions that use session -configuration files, the command might not return all qualifying +These properties make it easy to search for specific session configurations. +For example, you can use the ExecutionPolicy property to find a session +configuration that supports sessions with the RemoteSigned execution policy. +Note that, because the ExecutionPolicy property exists only on sessions that +use session configuration files, the command might not return all qualifying session configurations. -PS C:> Get-PSSessionConfiguration | +```powershell +Get-PSSessionConfiguration | where {$_.ExecutionPolicy -eq "RemoteSigned"} +``` -The following command gets session configurations in which the -RunAsUser is the Exchange administrator. +The following command gets session configurations in which the RunAsUser is +the Exchange administrator. -PS C:> Get-PSSessionConfiguration | +```powershell + Get-PSSessionConfiguration | where {$_.RunAsUser -eq "Exchange01\Admin01"} +``` -To view information about the role definitions associated with -a configuration use the Get-PSSessionCapability cmdlet. This -cmdlet enables you to determine the commands and environment -available to specific users in specific endpoints. +To view information about the role definitions associated with a configuration +use the Get-PSSessionCapability cmdlet. This cmdlet enables you to determine +the commands and environment available to specific users in specific +endpoints. -# NOTES +## NOTES -Session configurations also support a type of session known as an -"empty" session. An Empty session type enables you to create -custom sessions with selected commands. If you do not add modules, -functions, or scripts to an empty session, the session is limited -to expressions and might not be of any practical use. The -SessionType property tells you whether or not you are working with -an empty session. +Session configurations also support a type of session known as an "empty" +session. An Empty session type enables you to create custom sessions with +selected commands. If you do not add modules, functions, or scripts to an +empty session, the session is limited to expressions and might not be of any +practical use. The SessionType property tells you whether or not you are +working with an empty session. -# SEE ALSO +## SEE ALSO [about_Session_Configurations](about_Session_Configurations.md) -New-PSSession - -Disable-PSSessionConfiguration +[New-PSSession](../New-PSSession.md) -Enable-PSSessionConfiguration +[Disable-PSSessionConfiguration](../Disable-PSSessionConfiguration.md) -Get-PSSessionConfiguration +[Enable-PSSessionConfiguration](../Enable-PSSessionConfiguration.md) -New-PSSessionConfigurationFile +[Get-PSSessionConfiguration](../Get-PSSessionConfiguration.md) -Register-PSSessionConfiguration +[New-PSSessionConfigurationFile](../New-PSSessionConfigurationFile.md) -Set-PSSessionConfiguration +[Register-PSSessionConfiguration](../Register-PSSessionConfiguration.md) -Test-PSSessionConfigurationFile +[Set-PSSessionConfiguration](../Set-PSSessionConfiguration.md) -Unregister-PSSessionConfiguration +[Test-PSSessionConfigurationFile](../Test-PSSessionConfigurationFile.md) -Get-PSSessionCapability +[Unregister-PSSessionConfiguration](../Unregister-PSSessionConfiguration.md) -New-PSRoleCapabilityFile +[Get-PSSessionCapability](../Get-PSSessionCapability.md) +[New-PSRoleCapabilityFile](../New-PSRoleCapabilityFile.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md index 72d6fcce99a7..f8c13a29566e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,81 +7,81 @@ title: about_Signing --- # About Signing -## about_Signing +## SHORT DESCRIPTION +Explains how to sign scripts so that they comply with the PowerShell execution +policies. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Explains how to sign scripts so that they comply with the Windows -PowerShell execution policies. +The Restricted execution policy does not permit any scripts to run. The +AllSigned and RemoteSigned execution policies prevent PowerShell from running +scripts that do not have a digital signature. -# LONG DESCRIPTION +This topic explains how to run selected scripts that are not signed, even +while the execution policy is RemoteSigned, and how to sign scripts for your +own use. -The Restricted execution policy does not permit any scripts to run. -The AllSigned and RemoteSigned execution policies prevent Windows -PowerShell from running scripts that do not have a digital signature. +For more information about PowerShell execution policies, see +[about_Execution_Policies](about_Execution_Policies.md). -This topic explains how to run selected scripts that are not signed, -even while the execution policy is RemoteSigned, and how to sign -scripts for your own use. +## TO PERMIT SIGNED SCRIPTS TO RUN -For more information about Windows PowerShell execution policies, -see about_Execution_Policy. - -# TO PERMIT SIGNED SCRIPTS TO RUN - -------------------------------- -When you start Windows PowerShell on a computer for the first time, the -Restricted execution policy (the default) is likely to be in effect. +When you start PowerShell on a computer for the first time, the Restricted +execution policy (the default) is likely to be in effect. The Restricted policy does not permit any scripts to run. To find the effective execution policy on your computer, type: +```powershell Get-ExecutionPolicy +``` -To run unsigned scripts that you write on your local computer and -signed scripts from other users, start Windows PowerShell with the -Run as Administrator option and then use the following command to -change the execution policy on the computer to RemoteSigned: +To run unsigned scripts that you write on your local computer and signed +scripts from other users, start PowerShell with the Run as Administrator +option and then use the following command to change the execution policy on +the computer to RemoteSigned: +```powershell Set-ExecutionPolicy RemoteSigned +``` -For more information, see the help topic for the -Set-ExecutionPolicy cmdlet. +For more information, see the help topic for the Set-ExecutionPolicy cmdlet. -# RUNNING UNSIGNED SCRIPTS (REMOTESIGNED EXECUTION POLICY) +## RUNNING UNSIGNED SCRIPTS (REMOTESIGNED EXECUTION POLICY) --------------------------------------------------------- -If your Windows PowerShell execution policy is RemoteSigned, Windows +If your PowerShell execution policy is RemoteSigned, Windows PowerShell will not run unsigned scripts that are downloaded from the Internet, including unsigned scripts you receive through e-mail and instant messaging programs. -If you try to run a downloaded script, Windows PowerShell displays the +If you try to run a downloaded script, PowerShell displays the following error message: -The file cannot be loaded. The file - is not digitally signed. The script -will not execute on the system. Please see "Get-Help +```output +The file cannot be loaded. The file is not digitally +signed. The script will not execute on the system. Please see "Get-Help about_Signing" for more details. +``` Before you run the script, review the code to be sure that you trust it. Scripts have the same effect as any executable program. -To run an unsigned script, use the Unblock-File cmdlet or use the -Following procedure. +To run an unsigned script, use the Unblock-File cmdlet or use the following +procedure. 1. Save the script file on your computer. 2. Click Start, click My Computer, and locate the saved script file. 3. Right-click the script file, and then click Properties. 4. Click Unblock. -If a script that was downloaded from the Internet is digitally signed, but -you have not yet chosen to trust its publisher, Windows PowerShell displays -the following message: +If a script that was downloaded from the Internet is digitally signed, but you +have not yet chosen to trust its publisher, PowerShell displays the following +message: +```output Do you want to run software from this untrusted publisher? The file is published by CN=. This publisher is not trusted on your system. Only run scripts @@ -89,231 +89,206 @@ from trusted publishers. [V] Never run [D] Do not run [R] Run once [A] Always run [?] Help (default is "D"): +``` -If you trust the publisher, select "Run once" or "Always run." -If you do not trust the publisher, select either "Never run" or -"Do not run." If you select "Never run" or "Always run," Windows -PowerShell will not prompt you again for this publisher. +If you trust the publisher, select "Run once" or "Always run." If you do not +trust the publisher, select either "Never run" or "Do not run." If you select +"Never run" or "Always run," PowerShell will not prompt you again for +this publisher. -# METHODS OF SIGNING SCRIPTS +## METHODS OF SIGNING SCRIPTS --------------------------- -You can sign the scripts that you write and the scripts that you obtain -from other sources. Before you sign any script, examine each command -to verify that it is safe to run. +You can sign the scripts that you write and the +scripts that you obtain from other sources. Before you sign any script, +examine each command to verify that it is safe to run. -For best practices about code signing, see "Code-Signing -Best Practices" at http://download.microsoft.com/download/a/f/7/af7777e5-7dcd-4800-8a0a-b18336565f5b/best_practices.doc. +For best practices about code signing, see +[Code-Signing Best Practices](http://go.microsoft.com/fwlink/?LinkId=119096). For more information about how to sign a script file, see Set-AuthenticodeSignature. -The New-SelfSignedCertificate cmdlet, introduced in the PKI module -in Windows PowerShell 3.0, creates a self-signed certificate that is -Appropriate for testing. For more information, see the help -topic for the New-SelfSignedCertificate cmdlet. - -To add a digital signature to a script, you must sign it with a code -signing certificate. Two types of certificates are suitable for signing -a script file: +The New-SelfSignedCertificate cmdlet, introduced in the PKI module in +PowerShell 3.0, creates a self-signed certificate that is Appropriate for +testing. For more information, see the help topic for the +New-SelfSignedCertificate cmdlet. --- Certificates that are created by a certification authority: +To add a digital signature to a script, you must sign it with a code signing +certificate. Two types of certificates are suitable for signing a script file: -For a fee, a public certification authority verifies your -identity and gives you a code signing certificate. When -you purchase your certificate from a reputable certification -authority, you are able to share your script with users -on other computers that are running Windows because those other -computers trust the certification authority. +- Certificates that are created by a certification authority: For a fee, a + public certification authority verifies your identity and gives you a code + signing certificate. When you purchase your certificate from a reputable + certification authority, you are able to share your script with users on + other computers that are running Windows because those other computers trust + the certification authority. --- Certificates that you create: +- Certificates that you create: You can create a self-signed certificate for + which your computer is the authority that creates the certificate. This + certificate is free of charge and enables you to write, sign, and run scripts + on your computer. However, a script signed by a self-signed certificate will + not run on other computers. -You can create a self-signed certificate for which -your computer is the authority that creates the certificate. -This certificate is free of charge and enables you to write, -sign, and run scripts on your computer. However, a script -signed by a self-signed certificate will not run on other -computers. +Typically, you would use a self-signed certificate only to sign scripts that +you write for your own use and to sign scripts that you get from other sources +that you have verified to be safe. It is not appropriate for scripts that will +be shared, even within an enterprise. -Typically, you would use a self-signed certificate only to sign -scripts that you write for your own use and to sign scripts that you get -from other sources that you have verified to be safe. It is not -appropriate for scripts that will be shared, even within an enterprise. +If you create a self-signed certificate, be sure to enable strong private key +protection on your certificate. This prevents malicious programs from signing +scripts on your behalf. The instructions are included at the end of this +topic. -If you create a self-signed certificate, be sure to enable strong -private key protection on your certificate. This prevents malicious -programs from signing scripts on your behalf. The instructions are -included at the end of this topic. +## CREATE A SELF-SIGNED CERTIFICATE -# CREATE A SELF-SIGNED CERTIFICATE - --------------------------------- To create a self-signed certificate in use the New-SelfSignedCertificate -cmdlet in the PKI module. This module is introduced in Windows PowerShell -3.0 and is included in Windows 8 and Windows Server 2012. For more -information, see the help topic for the New-SelfSignedCertificate cmdlet. +cmdlet in the PKI module. This module is introduced in PowerShell 3.0 and is +included in Windows 8 and Windows Server 2012. For more information, see the +help topic for the New-SelfSignedCertificate cmdlet. -To create a self-signed certificate in earlier versions of Windows, use -the Certificate Creation tool (MakeCert.exe). This tool is included in -the Microsoft .NET Framework SDK (versions 1.1 and later) and in the -Microsoft Windows SDK. +To create a self-signed certificate in earlier versions of Windows, use the +Certificate Creation tool (MakeCert.exe). This tool is included in the +Microsoft .NET Framework SDK (versions 1.1 and later) and in the Microsoft +Windows SDK. For more information about the syntax and the parameter descriptions of the -MakeCert.exe tool, see "Certificate Creation Tool (MakeCert.exe)" in the -MSDN (Microsoft Developer Network) library at -http://go.microsoft.com/fwlink/?LinkId=119097. +MakeCert.exe tool, see [Certificate Creation Tool (MakeCert.exe)](http://go.microsoft.com/fwlink/?LinkId=119097) +in the MSDN library. To use the MakeCert.exe tool to create a certificate, run the following commands in an SDK Command Prompt window. -Note: The first command creates a local certification authority for -your computer. The second command generates a personal -certificate from the certification authority. +Note: The first command creates a local certification authority for your +computer. The second command generates a personal certificate from the +certification authority. -Note: You can copy or type the commands exactly as they appear. -No substitutions are necessary, although you can change the -certificate name. +Note: You can copy or type the commands exactly as they appear. No +substitutions are necessary, although you can change the certificate name. +```powershell makecert -n "CN=PowerShell Local Certificate Root" -a sha1 ` -eku 1.3.6.1.5.5.7.3.3 -r -sv root.pvk root.cer ` -ss Root -sr localMachine makecert -pe -n "CN=PowerShell User" -ss MY -a sha1 ` -eku 1.3.6.1.5.5.7.3.3 -iv root.pvk -ic root.cer +``` -The MakeCert.exe tool will prompt you for a private key password. The -password ensures that no one can use or access the certificate without -your consent. Create and enter a password that you can remember. You will -use this password later to retrieve the certificate. +The MakeCert.exe tool will prompt you for a private key password. The password +ensures that no one can use or access the certificate without your consent. +Create and enter a password that you can remember. You will use this password +later to retrieve the certificate. -To verify that the certificate was generated correctly, use the -following command to get the certificate in the certificate -store on the computer. (You will not find a certificate file in the -file system directory.) +To verify that the certificate was generated correctly, use the following +command to get the certificate in the certificate store on the computer. (You +will not find a certificate file in the file system directory.) -At the Windows PowerShell prompt, type: +At the PowerShell prompt, type: +```powershell get-childitem cert:\CurrentUser\my -codesigning +``` -This command uses the Windows PowerShell Certificate provider to view -information about the certificate. +This command uses the PowerShell Certificate provider to view information +about the certificate. -If the certificate was created, the output shows the thumbprint -that identifies the certificate in a display that resembles the following: +If the certificate was created, the output shows the thumbprint that +identifies the certificate in a display that resembles the following: +```output Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My Thumbprint Subject ---------- ------- 4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ] +``` -# SIGN A SCRIPT - -------------- +## SIGN A SCRIPT -After you create a self-signed certificate, you can sign scripts. If you -use the AllSigned execution policy, signing a script permits you to run -the script on your computer. +After you create a self-signed certificate, you can sign scripts. If you use +the AllSigned execution policy, signing a script permits you to run the script +on your computer. -The following sample script, Add-Signature.ps1, signs a script. However, -if you are using the AllSigned execution policy, you must sign the +The following sample script, Add-Signature.ps1, signs a script. However, if +you are using the AllSigned execution policy, you must sign the Add-Signature.ps1 script before you run it. -To use this script, copy the following text into a text file, and -name it Add-Signature.ps1. - -Note: Be sure that the script file does not have a .txt file name -extension. If your text editor appends ".txt", enclose the file name -in quotation marks: "add-signature.ps1". +To use this script, copy the following text into a text file, and name it +Add-Signature.ps1. -## add-signature.ps1 +```powershell ## Signs a file param([string] $file=$(throw "Please specify a filename.")) $cert = @(Get-ChildItem cert:\CurrentUser\My -codesigning)[0] Set-AuthenticodeSignature $file $cert +``` -To sign the Add-Signature.ps1 script file, type the following commands at -the Windows PowerShell command prompt: +To sign the Add-Signature.ps1 script file, type the following commands at the +PowerShell command prompt: +```powershell $cert = @(Get-ChildItem cert:\CurrentUser\My -codesigning)[0] - Set-AuthenticodeSignature add-signature.ps1 $cert +``` -After the script is signed, you can run it on the local computer. -However, the script will not run on computers on which the Windows -PowerShell execution policy requires a digital signature from a -trusted authority. If you try, Windows PowerShell displays the following -error message: +After the script is signed, you can run it on the local computer. However, the +script will not run on computers on which the PowerShell execution +policy requires a digital signature from a trusted authority. If you try, +PowerShell displays the following error message: +```output The file C:\remote_file.ps1 cannot be loaded. The signature of the certificate cannot be verified. At line:1 char:15 + .\ remote_file.ps1 <<<< +``` -If Windows PowerShell displays this message when you run a -script that you did not write, treat the file as you would treat any -unsigned script. Review the code to determine whether you can trust the -script. - -# ENABLE STRONG PRIVATE KEY PROTECTION FOR YOUR CERTIFICATE +If PowerShell displays this message when you run a script that you did not +write, treat the file as you would treat any unsigned script. Review the code +to determine whether you can trust the script. ---------------------------------------------------------- +## ENABLE STRONG PRIVATE KEY PROTECTION FOR YOUR CERTIFICATE -If you have a private certificate on your computer, malicious -programs might be able to sign scripts on your behalf, which -authorizes Windows PowerShell to run them. +If you have a private certificate on your computer, malicious programs might +be able to sign scripts on your behalf, which authorizes PowerShell to run +them. -To prevent automated signing on your behalf, use Certificate -Manager (Certmgr.exe) to export your signing certificate to -a .pfx file. Certificate Manager is included in the Microsoft -.NET Framework SDK, the Microsoft Windows SDK, and in Internet -Explorer 5.0 and later versions. +To prevent automated signing on your behalf, use Certificate Manager +(Certmgr.exe) to export your signing certificate to a .pfx file. Certificate +Manager is included in the Microsoft .NET Framework SDK, the Microsoft Windows +SDK, and in Internet Explorer 5.0 and later versions. To export the certificate: 1. Start Certificate Manager. - 2. Select the certificate issued by PowerShell Local Certificate Root. - 3. Click Export to start the Certificate Export Wizard. - 4. Select "Yes, export the private key", and then click Next. - 5. Select "Enable strong protection." - 6. Type a password, and then type it again to confirm. - 7. Type a file name that has the .pfx file name extension. - 8. Click Finish. To re-import the certificate: 1. Start Certificate Manager. - 2. Click Import to start the Certificate Import Wizard. - -3. Open to the location of the .pfx file that you created during the -export process. - +3. Open to the location of the .pfx file that you created during the export + process. 4. On the Password page, select "Enable strong private key protection", -and then enter the password that you assigned during the export -process. - + and then enter the password that you assigned during the export + process. 5. Select the Personal certificate store. - 6. Click Finish. -# PREVENT THE SIGNATURE FROM EXPIRING +## PREVENT THE SIGNATURE FROM EXPIRING ------------------------------------ The digital signature in a script is valid until the signing certificate expires or as long as a time stamp server can verify that the script was signed while the signing certificate was valid. -Because most signing certificates are valid for one year only, using a -time stamp server ensures that users can use your script for many years -to come. +Because most signing certificates are valid for one year only, using a time +stamp server ensures that users can use your script for many years to come. # SEE ALSO @@ -321,13 +296,10 @@ to come. [about_Profiles](about_Profiles.md) -Get-ExecutionPolicy - -New-SelfSignedCertificate - -Set-ExecutionPolicy +[Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -Set-AuthenticodeSignature +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -"Introduction to Code Signing" (http://go.microsoft.com/fwlink/?LinkId=106296) +[Set-AuthenticodeSignature](../../Microsoft.PowerShell.Security/Set-AuthenticodeSignature.md) +[Introduction to Code Signing](http://go.microsoft.com/fwlink/?LinkId=106296) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md index 10b1d7bc00db..02d2b8d169e7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,68 +7,61 @@ title: about_Splatting --- # About Splatting -## about_Splatting +## SHORT DESCRIPTION +Describes how to use splatting to pass parameters to commands in Windows +PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes how to use splatting to pass parameters to commands -in Windows PowerShell. +[This topic was contributed by Rohn Edwards of Gulfport, Mississippi, a system +administrator and the winner of the Advanced Division of the 2012 Scripting +Games. Revised for Windows PowerShell 3.0.] -# LONG DESCRIPTION +Splatting is a method of passing a collection of parameter values to a command +as unit. Windows PowerShell associates each value in the collection with a +command parameter. Splatted parameter values are stored in named splatting +variables, which look like standard variables, but begin with an At symbol (@) +instead of a dollar sign ($). The At symbol tells Windows PowerShell that you +are passing a collection of values, instead of a single value. -[This topic was contributed by Rohn Edwards of Gulfport, -Mississippi, a system administrator and the winner -of the Advanced Division of the 2012 Scripting Games. -Revised for Windows PowerShell 3.0.] +Splatting makes your commands shorter and easier to read. You can re-use the +splatting values in different command calls and use splatting to pass +parameter values from the `$PSBoundParameters` automatic variable to other +scripts and functions. -Splatting is a method of passing a collection of parameter -values to a command as unit. Windows PowerShell associates -each value in the collection with a command parameter. -Splatted parameter values are stored in named splatting -variables, which look like standard variables, but begin with -an At symbol (@) instead of a dollar sign ($). The At symbol -tells Windows PowerShell that you are passing a collection of -values, instead of a single value. +Beginning in Windows PowerShell 3.0, you can also use splatting to represent +all parameters of a command. -Splatting makes your commands shorter and easier to read. You -can re-use the splatting values in different command calls and -use splatting to pass parameter values from the `$PSBoundParameters` -automatic variable to other scripts and functions. +## SYNTAX -Beginning in Windows PowerShell 3.0, you can also use splatting -to represent all parameters of a command. - -# SYNTAX - -```powershell +``` @ @ ``` -To provide parameter values for positional parameters, in which -parameter names are not required, use the array syntax. To provide -parameter name and value pairs, use the hash table syntax. The -splatted value can appear anywhere in the parameter list. +To provide parameter values for positional parameters, in which parameter +names are not required, use the array syntax. To provide parameter name and +value pairs, use the hash table syntax. The splatted value can appear anywhere +in the parameter list. -When splatting, you do not need to use a hash table or an array to -pass all parameters. You may pass some parameters by using splatting -and pass others by position or by parameter name. Also, you can splat -multiple objects in a single command just so you pass no more than one -value for each parameter. +When splatting, you do not need to use a hash table or an array to pass all +parameters. You may pass some parameters by using splatting and pass others by +position or by parameter name. Also, you can splat multiple objects in a +single command just so you pass no more than one value for each parameter. -# SPLATTING WITH HASH TABLES +## SPLATTING WITH HASH TABLES -Use a hash table to splat parameter name and value pairs. You can use -this format for all parameter types, including positional and named -parameters and switch parameters. +Use a hash table to splat parameter name and value pairs. You can use this +format for all parameter types, including positional and named parameters and +switch parameters. -The following examples compare two `Copy-Item` commands that copy the -Test.txt file to the Test2.txt file in the same directory. +The following examples compare two `Copy-Item` commands that copy the Test.txt +file to the Test2.txt file in the same directory. -The first example uses the traditional format in which parameter names -are included. +The first example uses the traditional format in which parameter names are +included. ```powershell Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf @@ -76,9 +69,9 @@ Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf The second example uses hash table splatting. The first command creates a hash table of parameter-name and parameter-value pairs and stores it in the -\$HashArguments variable. The second command uses the `$HashArguments` variable -in a command with splatting. The At symbol (`@HashArguments`) replaces the -dollar sign (`$HashArguments`) in the command. +\$HashArguments variable. The second command uses the `$HashArguments` +variable in a command with splatting. The At symbol (`@HashArguments`) +replaces the dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. @@ -91,11 +84,11 @@ $HashArguments = @{ Copy-Item @HashArguments ``` -Note: In the first command, the At symbol (@) indicates a hash table, not -a splatted value. The syntax for hash tables in Windows PowerShell is: +Note: In the first command, the At symbol (@) indicates a hash table, not a +splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* -# SPLATTING WITH ARRAYS +## SPLATTING WITH ARRAYS Use an array to splat values for positional parameters, which do not require parameter names. The values must be in position-number order in the array. @@ -122,8 +115,7 @@ $ArrayArguments = "test.txt", "test2.txt" Copy-Item @ArrayArguments -WhatIf ``` -# EXAMPLES - +## EXAMPLES This example shows how to re-use splatted values in different commands. The commands in this example use the Write-Host cmdlet to write messages to the @@ -153,18 +145,16 @@ Write-Host "This is a test." @Colors Write-Host @Colors "This is another test." ``` -This example shows how to forward their parameters to other commands by -using splatting and the `$PSBoundParameters` automatic variable. +This example shows how to forward their parameters to other commands by using +splatting and the `$PSBoundParameters` automatic variable. -The $PSBoundParameters automatic variable is a dictionary -(System.Collections.Generic.Dictionary) that contains all of the -parameter names and values that are used when a script or function -is run. +The \$PSBoundParameters automatic variable is a dictionary +(System.Collections.Generic.Dictionary) that contains all of the parameter +names and values that are used when a script or function is run. -In the following example, we use the `$PSBoundParameters` variable to -forward the parameters values passed to a script or function from Test2 -function to the Test1 function. Both calls to the Test1 function from -Test2 use splatting. +In the following example, we use the `$PSBoundParameters` variable to forward +the parameters values passed to a script or function from Test2 function to +the Test1 function. Both calls to the Test1 function from Test2 use splatting. ```powershell function Test1 @@ -188,7 +178,9 @@ function Test2 $LimitedParameters.Remove("a") | Out-Null Test1 @LimitedParameters } +``` +```output Test2 -a 1 -b 2 -c 3 1 2 @@ -197,7 +189,7 @@ Test2 -a 1 -b 2 -c 3 3 ``` -# SPLATTING COMMAND PARAMETERS +## SPLATTING COMMAND PARAMETERS You can use splatting to represent the parameters of a command. This technique is useful when you are creating a proxy function, that is, a function that @@ -207,8 +199,8 @@ To splat the parameters of a command, use `@Args` to represent the command parameters. This technique is easier than enumerating command parameters and it works without revision even if the parameters of the called command change. -The feature uses the `$Args` automatic variable, which contains -all unassigned parameter values. +The feature uses the `$Args` automatic variable, which contains all unassigned +parameter values. For example, the following function calls the Get-Process cmdlet. In this function, `@Args` represents all of the parameters of the Get-Process cmdlet. @@ -217,19 +209,24 @@ function, `@Args` represents all of the parameters of the Get-Process cmdlet. function Get-MyProcess { Get-Process @Args } ``` -When you use the Get-MyProcess function, all unassigned -parameters and parameter values are passed to `@Args`, as -shown in the following commands. +When you use the Get-MyProcess function, all unassigned parameters and +parameter values are passed to `@Args`, as shown in the following commands. ```powershell Get-MyProcess -Name PowerShell +``` +```output Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 463 46 225484 237196 719 15.86 3228 powershell +``` +```powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo +``` +```output ProductVersion FileVersion FileName -------------- ----------- -------- 6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... @@ -248,7 +245,9 @@ function Get-MyCommand } Get-MyCommand -P -C -Name PowerShell +``` +```output Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Transactions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Transactions.md index e93860f24d7f..5c292571cdac 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Transactions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Transactions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,445 +7,454 @@ title: about_Transactions --- # About Transactions -## about_Transactions +## SHORT DESCRIPTION +Describes how to manage transacted operations in PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes how to manage transacted operations in Windows PowerShell. +Transactions are supported in PowerShell beginning in PowerShell 2.0. This +feature enables you to start a transaction, to indicate which commands are +part of the transaction, and to commit or roll back a transaction. -# LONG DESCRIPTION +## ABOUT TRANSACTIONS -Transactions are supported in Windows PowerShell beginning -in Windows PowerShell 2.0. This feature enables you to start -a transaction, to indicate which commands are part of the -transaction, and to commit or roll back a transaction. +In PowerShell, a transaction is a set of one or more commands that are managed +as a logical unit. A transaction can be completed ("committed"), which changes +data affected by the transaction. Or, a transaction can be completely undone +("rolled back") so that the affected data is not changed by the transaction. -# ABOUT TRANSACTIONS +Because the commands in a transaction are managed as a unit, either all +commands are committed, or all commands are rolled back. +Transactions are widely used in data processing, most notably in database +operations and for financial transactions. Transactions are most often used +when the worst-case scenario for a set of commands is not that they all fail, +but that some commands succeed while others fail, leaving the system in a +damaged, false, or uninterpretable state that is difficult to repair. -In Windows PowerShell, a transaction is a set of one or more -commands that are managed as a logical unit. A transaction can -be completed ("committed"), which changes data affected by the -transaction. Or, a transaction can be completely undone ("rolled back") -so that the affected data is not changed by the transaction. +## TRANSACTION CMDLETS -Because the commands in a transaction are managed as a unit, -either all commands are committed, or all commands are rolled -back. +PowerShell includes several cmdlets designed for managing transactions. -Transactions are widely used in data processing, most notably -in database operations and for financial transactions. Transactions -are most often used when the worst-case scenario for a set of -commands is not that they all fail, but that some commands succeed -while others fail, leaving the system in a damaged, false, or -uninterpretable state that is difficult to repair. - -# TRANSACTION CMDLETS - - -Windows PowerShell includes several cmdlets designed for managing -transactions. - -Cmdlet Description --------------- --------------------------------- -Start-Transaction Starts a new transaction. - -Use-Transaction Adds a command or expression to the -transaction. The command must use -transaction-enabled objects. - -Undo-Transaction Rolls back the transaction so that -no data is changed by the transaction. - -Complete-Transaction Commits the transaction. The data -affected by the transaction is changed. - -Get-Transaction Gets information about the active -transaction. +- Start-Transaction: Starts a new transaction. +- Use-Transaction: Adds a command or expression to the transaction. The + command must use transaction-enabled objects. +- Undo-Transaction: Rolls back the transaction so that no data is changed by + the transaction. +- Complete-Transaction: Commits the transaction. The data affected by the + transaction is changed. +- Get-Transaction: Gets information about the active transaction. For a list of transaction cmdlets, type: +```powershell get-command *transaction +``` For detailed information about the cmdlets, type: -get-help -detailed - -For example: - +```powershell get-help use-transaction -detailed +``` -# TRANSACTION-ENABLED ELEMENTS - +## TRANSACTION-ENABLED ELEMENTS -To participate in a transaction, both the cmdlet and the provider -must support transactions. This feature is built in to the objects -that are affected by the transaction. +To participate in a transaction, both the cmdlet and the provider must support +transactions. This feature is built in to the objects that are affected by the +transaction. -The Windows PowerShell Registry provider supports transactions -in Windows Vista. The TransactedString object -(Microsoft.PowerShell.Commands.Management.TransactedString) works -with any operating system that runs Windows PowerShell. +The PowerShell Registry provider supports transactions in Windows Vista. The +TransactedString object +(Microsoft.PowerShell.Commands.Management.TransactedString) works with any +operating system that runs PowerShell. -Other Windows PowerShell providers can support transactions. To -find the Windows PowerShell providers in your session that support -transactions, use the following command to find the "Transactions" -value in the Capabilities property of providers: +Other PowerShell providers can support transactions. To find the PowerShell +providers in your session that support transactions, use the following command +to find the "Transactions" value in the Capabilities property of providers: +```powershell get-psprovider | where {$_.Capabilities -like "transactions"} +``` -For more information about a provider, see the Help for the provider. -To get provider Help, type: +For more information about a provider, see the Help for the provider. To get +provider Help, type: +``` get-help +``` For example, to get Help for the Registry provider, type: +```powershell get-help registry +``` -# THE USETRANSACTION PARAMETER - +## THE USETRANSACTION PARAMETER -Cmdlets that can support transactions have a UseTransaction -parameter. This parameter includes the command in the active -transaction. You can use the full parameter name or its alias, -"usetx". +Cmdlets that can support transactions have a UseTransaction parameter. This +parameter includes the command in the active transaction. You can use the full +parameter name or its alias, "usetx". -The parameter can be used only when the session contains an -active transaction. If you enter a command with the UseTransaction -parameter when there is no active transaction, the command fails. +The parameter can be used only when the session contains an active +transaction. If you enter a command with the UseTransaction parameter when +there is no active transaction, the command fails. To find cmdlets with the UseTransaction parameter, type: +```powershell get-help * -parameter UseTransaction +``` -In Windows PowerShell core, all of the cmdlets designed to work -with Windows PowerShell providers support transactions. As a -result, you can use the provider cmdlets to manage transactions. +In PowerShell core, all of the cmdlets designed to work with PowerShell +providers support transactions. As a result, you can use the provider cmdlets +to manage transactions. -For more information about Windows PowerShell providers, -see about_Providers. +For more information about PowerShell providers, see [about_Providers](about_Providers.md). -# THE TRANSACTION OBJECT +## THE TRANSACTION OBJECT - -Transactions are represented in Windows PowerShell by a -transaction object, System.Management.Automation.Transaction. +Transactions are represented in PowerShell by a transaction object, +System.Management.Automation.Transaction. The object has the following properties: -RollbackPreference: -Contains the rollback preference set for the current -transaction. You can set the rollback preference when you -use Start-Transaction to start the transaction. +- RollbackPreference: Contains the rollback preference set for the current + transaction. You can set the rollback preference when you use + Start-Transaction to start the transaction. -The rollback preference determines the conditions under -which the transaction is rolled back automatically. Valid -values are Error, TerminatingError, and Never. The default -value is Error. + The rollback preference determines the conditions under which the transaction + is rolled back automatically. Valid values are Error, TerminatingError, and + Never. The default value is Error. -Status: -Contains the current status of the transaction. Valid -values are Active, Committed, and RolledBack. +- Status: Contains the current status of the transaction. Valid values are + Active, Committed, and RolledBack. -SubscriberCount: -Contains the number of subscribers to the transaction. A -subscriber is added to a transaction when you start a -transaction while another transaction is in progress. The -subscriber count is decremented when a subscriber commits -the transaction. +- SubscriberCount: Contains the number of subscribers to the transaction. A + subscriber is added to a transaction when you start a transaction while + another transaction is in progress. The subscriber count is decremented when + a subscriber commits the transaction. -# ACTIVE TRANSACTIONS +## ACTIVE TRANSACTIONS +In PowerShell, only one transaction is active at a time, and you can manage +only the active transaction. Multiple transactions can be in progress in the +same session at the same time, but only the most-recently started transaction +is active. -In Windows PowerShell, only one transaction is active at a -time, and you can manage only the active transaction. Multiple -transactions can be in progress in the same session at the same -time, but only the most-recently started transaction is active. +As a result, you cannot specify a particular transaction when using the +transaction cmdlets. Commands always apply to the active transaction. -As a result, you cannot specify a particular transaction when -using the transaction cmdlets. Commands always apply to the -active transaction. - -This is most evident in the behavior of the Get-Transaction cmdlet. -When you enter a Get-Transaction command, Get-Transaction always -gets only one transaction object. This object is the object that -represents the active transaction. +This is most evident in the behavior of the Get-Transaction cmdlet. When you +enter a Get-Transaction command, Get-Transaction always gets only one +transaction object. This object is the object that represents the active +transaction. To manage a different transaction, you must first finish the active -transaction, either by committing it or rolling it back. When you -do this, the previous transaction becomes active automatically. -Transactions become active in the reverse of order of which they are -started, so that the most recently started transaction is always -active. +transaction, either by committing it or rolling it back. When you do this, the +previous transaction becomes active automatically. Transactions become active +in the reverse of order of which they are started, so that the most recently +started transaction is always active. -# SUBSCRIBERS AND INDEPENDENT TRANSACTIONS +## SUBSCRIBERS AND INDEPENDENT TRANSACTIONS +If you start a transaction while another transaction is in progress, by +default, PowerShell does not start a new transaction. Instead, it adds a +"subscriber" to the current transaction. -If you start a transaction while another transaction is in progress, -by default, Windows PowerShell does not start a new transaction. -Instead, it adds a "subscriber" to the current transaction. +When a transaction has multiple subscribers, a single Undo-Transaction command +at any point rolls back the entire transaction for all subscribers. However, +to commit the transaction, you must enter a Complete-Transaction command for +every subscriber. -When a transaction has multiple subscribers, a single -Undo-Transaction command at any point rolls back the entire -transaction for all subscribers. However, to commit the transaction, -you must enter a Complete-Transaction command for every subscriber. - -To find the number of subscribers to a transaction, check the -SubscriberCount property of the transaction object. For example, -the following command uses the Get-Transaction cmdlet to get -the value of the SubscriberCount property of the active transaction: +To find the number of subscribers to a transaction, check the SubscriberCount +property of the transaction object. For example, the following command uses +the Get-Transaction cmdlet to get the value of the SubscriberCount property of +the active transaction: +```powershell (Get-Transaction).SubscriberCount +``` -Adding a subscriber is the default behavior because most transactions -that are started while another transaction is in progress are related -to the original transaction. In the typical model, a script that -contains a transaction calls a helper script that contains its own -transaction. Because the transactions are related, they should be -rolled back or committed as a unit. - -However, you can start a transaction that is independent of the -current transaction by using the Independent parameter of the -Start-Transaction cmdlet. +Adding a subscriber is the default behavior because most transactions that are +started while another transaction is in progress are related to the original +transaction. In the typical model, a script that contains a transaction calls +a helper script that contains its own transaction. Because the transactions +are related, they should be rolled back or committed as a unit. -When you start an independent transaction, Start-Transaction -creates a new transaction object, and the new transaction becomes -the active transaction. The independent transaction can be -committed or rolled back without affecting the original transaction. +However, you can start a transaction that is independent of the current +transaction by using the Independent parameter of the Start-Transaction +cmdlet. -When the independent transaction is finished (committed or rolled -back), the original transaction becomes the active transaction -again. +When you start an independent transaction, Start-Transaction creates a new +transaction object, and the new transaction becomes the active transaction. +The independent transaction can be committed or rolled back without affecting +the original transaction. -# CHANGING DATA +When the independent transaction is finished (committed or rolled back), the +original transaction becomes the active transaction again. +## CHANGING DATA -When you use transactions to change data, the data that is affected -by the transaction is not changed until you commit the transaction. -However, the same data can be changed by commands that are not -part of the transaction. +When you use transactions to change data, the data that is affected by the +transaction is not changed until you commit the transaction. However, the same +data can be changed by commands that are not part of the transaction. -Keep this in mind when you are using transactions to manage shared -data. Typically, databases have mechanisms that lock the data while -you are working on it, preventing other users, and other commands, -scripts, and functions, from changing it. +Keep this in mind when you are using transactions to manage shared data. +Typically, databases have mechanisms that lock the data while you are working +on it, preventing other users, and other commands, scripts, and functions, +from changing it. -However, the lock is a feature of the database. It is not related -to transactions. If you are working in a transaction-enabled -file system or other data store, the data can be changed while -the transaction is in progress. +However, the lock is a feature of the database. It is not related to +transactions. If you are working in a transaction-enabled file system or other +data store, the data can be changed while the transaction is in progress. -# EXAMPLES +## EXAMPLES -The examples in this section use the Windows PowerShell Registry -provider and assume that you are familiar with it. For information -about the Registry provider, type "get-help registry". +The examples in this section use the PowerShell Registry provider and assume +that you are familiar with it. For information about the Registry provider, +type "get-help registry". -# EXAMPLE 1: COMMITTING A TRANSACTION +### EXAMPLE 1: COMMITTING A TRANSACTION +To create a transaction, use the Start-Transaction cmdlet. The following +command starts a transaction with the default settings. -To create a transaction, use the Start-Transaction cmdlet. The -following command starts a transaction with the default settings. - +```powershell start-transaction +``` -To include commands in the transaction, use the UseTransaction -parameter of the cmdlet. By default, commands are not included -in the transaction, +To include commands in the transaction, use the UseTransaction parameter of +the cmdlet. By default, commands are not included in the transaction, -For example, the following command, which sets the current -location in the Software key of the HKCU: drive, is not included -in the transaction. +For example, the following command, which sets the current location in the +Software key of the HKCU: drive, is not included in the transaction. +```powershell cd hkcu:\Software +``` The following command, which creates the MyCompany key, uses the -UseTransaction parameter of the New-Item cmdlet to include the -command in the active transaction. +UseTransaction parameter of the New-Item cmdlet to include the command in the +active transaction. +```powershell new-item MyCompany -UseTransaction +``` -The command returns an object that represents the new key, but -because the command is part of the transaction, the registry -is not yet changed. +The command returns an object that represents the new key, but because the +command is part of the transaction, the registry is not yet changed. +``` Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -0 0 MyCompany {} + 0 0 MyCompany {} +``` -To commit the transaction, use the Complete-Transaction cmdlet. -Because it always affects the active transaction, you cannot specify -the transaction. +To commit the transaction, use the Complete-Transaction cmdlet. Because it +always affects the active transaction, you cannot specify the transaction. +```powershell complete-transaction +``` As a result, the MyCompany key is added to the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# EXAMPLE 2: ROLLING BACK A TRANSACTION +### EXAMPLE 2: ROLLING BACK A TRANSACTION +To create a transaction, use the Start-Transaction cmdlet. The following +command starts a transaction with the default settings. -To create a transaction, use the Start-Transaction cmdlet. The -following command starts a transaction with the default settings. - +```powershell start-transaction +``` The following command, which creates the MyOtherCompany key, uses the -UseTransaction parameter of the New-Item cmdlet to include the -command in the active transaction. +UseTransaction parameter of the New-Item cmdlet to include the command in the +active transaction. +```powershell new-item MyOtherCompany -UseTransaction +``` -The command returns an object that represents the new key, but -because the command is part of the transaction, the registry -is not yet changed. +The command returns an object that represents the new key, but because the +command is part of the transaction, the registry is not yet changed. +``` Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -0 0 MyOtherCompany {} + 0 0 MyOtherCompany {} +``` -To roll back the transaction, use the Undo-Transaction cmdlet. -Because it always affects the active transaction, you do not specify -the transaction. +To roll back the transaction, use the Undo-Transaction cmdlet. Because it +always affects the active transaction, you do not specify the transaction. +```powershell Undo-transaction +``` The result is that the MyOtherCompany key is not added to the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# EXAMPLE 3: PREVIEWING A TRANSACTION +### EXAMPLE 3: PREVIEWING A TRANSACTION +Typically, the commands used in a transaction change data. However, the +commands that get data are useful in a transaction, too, because they get data +inside of the transaction. This provides a preview of the changes that +committing the transaction would cause. -Typically, the commands used in a transaction change data. However, -the commands that get data are useful in a transaction, too, because -they get data inside of the transaction. This provides a preview of the -changes that committing the transaction would cause. - -The following example shows how to use the Get-ChildItem command -(the alias is "dir") to preview the changes in a transaction. +The following example shows how to use the Get-ChildItem command (the alias is +"dir") to preview the changes in a transaction. The following command starts a transaction. +```powershell start-transaction +``` -The following command uses the New-ItemProperty cmdlet to add the -MyKey registry entry to the MyCompany key. The command uses the -UseTransaction parameter to include the command in the transaction. +The following command uses the New-ItemProperty cmdlet to add the MyKey +registry entry to the MyCompany key. The command uses the UseTransaction +parameter to include the command in the transaction. +```powershell new-itemproperty -path MyCompany -Name MyKey -value 123 -UseTransaction +``` -The command returns an object representing the new registry entry, -but the registry entry is not changed. +The command returns an object representing the new registry entry, but the +registry entry is not changed. +``` MyKey ----- -# 123 - +123 +``` To get the items that are currently in the registry, use a Get-ChildItem -command ("dir") without the UseTransaction parameter. The following -command gets items that begin with "M." +command ("dir") without the UseTransaction parameter. The following command +gets items that begin with "M." +```powershell dir m* +``` The result shows that no entries have yet been added to the MyCompany key. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` To preview the effect of committing the transaction, enter a Get-ChildItem -("dir") command with the UseTransaction parameter. This command has a view -of the data from within the transaction. +("dir") command with the UseTransaction parameter. This command has a view of +the data from within the transaction. +```powershell dir m* -useTransaction +``` -The result shows that, if the transaction is committed, the MyKey entry -will be added to the MyCompany key. +The result shows that, if the transaction is committed, the MyKey entry will +be added to the MyCompany key. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 1 MyCompany {MyKey} - -# EXAMPLE 4: COMBINING TRANSACTED AND NON-TRANSACTED COMMANDS - + 83 1 Microsoft {(default)} + 0 1 MyCompany {MyKey} +``` -You can enter non-transacted commands during a transaction. The -non-transacted commands affect the data immediately, but they do -not affect the transaction. +### EXAMPLE 4: COMBINING TRANSACTED AND NON-TRANSACTED COMMANDS -The following command starts a transaction in the HKCU:\Software -registry key. +You can enter non-transacted commands during a transaction. The non-transacted +commands affect the data immediately, but they do not affect the transaction. +The following command starts a transaction in the HKCU:\Software registry key. +```powershell start-transaction +``` -The next three commands use the New-Item cmdlet to add keys to -the registry. The first and third commands use the UseTransaction -parameter to include the commands in the transaction. The second -command omits the parameter. Because the second command is not -included in the transaction, it is effective immediately. +The next three commands use the New-Item cmdlet to add keys to the registry. +The first and third commands use the UseTransaction parameter to include the +commands in the transaction. The second command omits the parameter. Because +the second command is not included in the transaction, it is effective +immediately. +```powershell new-item MyCompany1 -UseTransaction - new-item MyCompany2 - new-item MyCompany3 -UseTransaction +``` -To view the current state of the registry, use a Get-ChildItem ("dir") -command without the UseTransaction parameter. This command gets items -that begin with "M." +To view the current state of the registry, use a Get-ChildItem ("dir") command +without the UseTransaction parameter. This command gets items that begin with +"M." +```powershell dir m* +``` -The result shows that the MyCompany2 key is added to the registry, but -the MyCompany1 and MyCompany3 keys, which are part of the transaction, -are not added. +The result shows that the MyCompany2 key is added to the registry, but the +MyCompany1 and MyCompany3 keys, which are part of the transaction, are not +added. +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany2 {} + 83 1 Microsoft {(default)} + 0 0 MyCompany2 {} +``` The following command commits the transaction. +```powershell complete-transaction +``` Now, the keys that were added as part of the transaction appear in the registry. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property @@ -454,327 +463,389 @@ SKC VC Name Property 0 0 MyCompany1 {} 0 0 MyCompany2 {} 0 0 MyCompany3 {} +``` -# EXAMPLE 5: USING AUTOMATIC ROLLBACK +### EXAMPLE 5: USING AUTOMATIC ROLLBACK +When a command in a transaction generates an error of any kind, the +transaction is automatically rolled back. -When a command in a transaction generates an error -of any kind, the transaction is automatically rolled -back. - -This default behavior is designed for scripts that -run transactions. Scripts are typically well tested -and include error-handling logic, so errors are not +This default behavior is designed for scripts that run transactions. Scripts +are typically well tested and include error-handling logic, so errors are not expected and should terminate the transaction. -The first command starts a transaction in the HKCU:\Software -registry key. +The first command starts a transaction in the HKCU:\Software registry key. +```powershell start-transaction +``` -The following command uses the New-Item cmdlet to -add the MyCompany key to the registry. The command uses -the UseTransaction parameter (the alias is "usetx") to include -the command in the transaction. +The following command uses the New-Item cmdlet to add the MyCompany key to the +registry. The command uses the UseTransaction parameter (the alias is "usetx") +to include the command in the transaction. +```powershell New-Item MyCompany -UseTX +``` -Because the MyCompany key already exists in the registry, -the command fails, and the transaction is rolled back. +Because the MyCompany key already exists in the registry, the command fails, +and the transaction is rolled back. +```output New-Item : A key at this path already exists At line:1 char:9 + new-item <<<< MyCompany -usetx +``` -A Get-Transaction command confirms that the transaction -has been rolled back and that the SubscriberCount is 0. +A Get-Transaction command confirms that the transaction has been rolled back +and that the SubscriberCount is 0. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 0 RolledBack +``` -# EXAMPLE 6: CHANGING THE ROLLBACK PREFERENCE +### EXAMPLE 6: CHANGING THE ROLLBACK PREFERENCE - -If you want the transaction to be more error tolerant, -you can use the RollbackPreference parameter of -Start-Transaction to change the preference. +If you want the transaction to be more error tolerant, you can use the +RollbackPreference parameter of Start-Transaction to change the preference. The following command starts a transaction with a rollback preference of "Never". +```powershell start-transaction -rollbackpreference Never +``` -In this case, when the command fails, the transaction -is not automatically rolled back. +In this case, when the command fails, the transaction is not automatically +rolled back. +```powershell New-Item MyCompany -UseTX +``` +```output New-Item : A key at this path already exists At line:1 char:9 + new-item <<<< MyCompany -usetx +``` -Because the transaction is still active, you can -resubmit the command as part of the transaction. +Because the transaction is still active, you can resubmit the command as part +of the transaction. +```powershell New-Item MyOtherCompany -UseTX +``` -# EXAMPLE 7: USING THE USE-TRANSACTION CMDLET - +### EXAMPLE 7: USING THE USE-TRANSACTION CMDLET -The Use-Transaction cmdlet enables you to do direct scripting -against transaction-enabled Microsoft .NET Framework objects. -Use-Transaction takes a script block that can only contain commands -and expressions that use transaction-enabled .NET Framework objects, -such as instances of the +The Use-Transaction cmdlet enables you to do direct scripting against +transaction-enabled Microsoft .NET Framework objects. Use-Transaction takes a +script block that can only contain commands and expressions that use +transaction-enabled .NET Framework objects, such as instances of the Microsoft.PowerShell.Commands.Management.TransactedString class. The following command starts a transaction. +```powershell start-transaction +``` -The following New-Object command creates an instance of the -TransactedString class and saves it in the $t variable. +The following New-Object command creates an instance of the TransactedString +class and saves it in the $t variable. +```powershell $t = New-Object Microsoft.PowerShell.Commands.Management.TransactedString +``` -The following command uses the Append method of the TransactedString -object to add text to the string. Because the command is not part -of the transaction, the change is effective immediately. +The following command uses the Append method of the TransactedString object to +add text to the string. Because the command is not part of the transaction, +the change is effective immediately. +```powershell $t.append("Windows") +``` -The following command uses the same Append method to add text, but -it adds the text as part of the transaction. The command is enclosed -in braces, and it is set as the value of the ScriptBlock parameter of -Use-Transaction. The UseTransaction parameter (UseTx) is required. +The following command uses the same Append method to add text, but it adds the +text as part of the transaction. The command is enclosed in braces, and it is +set as the value of the ScriptBlock parameter of Use-Transaction. The +UseTransaction parameter (UseTx) is required. +```powershell use-transaction {$t.append(" PowerShell")} -usetx +``` -To see the current content of the transacted string in $t, use the -ToString method of the TransactedString object. +To see the current content of the transacted string in $t, use the ToString +method of the TransactedString object. +```powershell $t.tostring() +``` The output shows that only the non-transacted changes are effective. +```output Windows +``` -To see the current content of the transacted string in $t from within -the transaction, embed the expression in a Use-Transaction command. +To see the current content of the transacted string in $t from within the +transaction, embed the expression in a Use-Transaction command. +```powershell use-transaction {$s.tostring()} -usetx +``` The output shows the transaction view. -Windows PowerShell +```output +PowerShell +``` The following command commits the transaction. +```powershell complete-transaction +``` To see the final string: +``` $t.tostring() +PowerShell +``` -Windows PowerShell +### EXAMPLE 8: MANAGING MULTI-SUBSCRIBER TRANSACTIONS -# EXAMPLE 8: MANAGING MULTI-SUBSCRIBER TRANSACTIONS - - -When you start a transaction while another transaction is in -progress, Windows PowerShell does not create a second transaction -by default. Instead, it adds a subscriber to the current -transaction. +When you start a transaction while another transaction is in progress, +PowerShell does not create a second transaction by default. Instead, it adds a +subscriber to the current transaction. -This example shows how to view and manage a multi-subscriber -transaction. +This example shows how to view and manage a multi-subscriber transaction. Begin by starting a transaction in the HKCU:\Software key. +```powershell start-transaction +``` -The following command uses the Get-Transaction command to -get the active transaction. +The following command uses the Get-Transaction command to get the active +transaction. +```powershell get-transaction +``` The result shows the object that represents the active transaction. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The following command adds the MyCompany key to the registry. -The command uses the UseTransaction parameter to include the -command in the transaction. +The following command adds the MyCompany key to the registry. The command uses +the UseTransaction parameter to include the command in the transaction. +```powershell new-item MyCompany -UseTransaction +``` -The following command uses the Start-Transaction command to -start a transaction. Although this command is typed at the command -prompt, this scenario is more likely to happen when you run a -script that contains a transaction. +The following command uses the Start-Transaction command to start a +transaction. Although this command is typed at the command prompt, this +scenario is more likely to happen when you run a script that contains a +transaction. +```powershell start-transaction +``` -A Get-Transaction command shows that the subscriber count on the -transaction object is incremented. The value is now 2. +A Get-Transaction command shows that the subscriber count on the transaction +object is incremented. The value is now 2. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 2 Active +``` -The next command uses the New-ItemProperty cmdlet to add the -MyKey registry entry to the MyCompany key. It uses the UseTransaction -parameter to include the command in the transaction. +The next command uses the New-ItemProperty cmdlet to add the MyKey registry +entry to the MyCompany key. It uses the UseTransaction parameter to include +the command in the transaction. +```powershell new-itemproperty -path MyCompany -name MyKey -UseTransaction +``` -The MyCompany key does not exist in the registry, but this -command succeeds because the two commands are part of the -same transaction. +The MyCompany key does not exist in the registry, but this command succeeds +because the two commands are part of the same transaction. -The following command commits the transaction. If it rolled back -the transaction, the transaction would be rolled back for all the -subscribers. +The following command commits the transaction. If it rolled back the +transaction, the transaction would be rolled back for all the subscribers. +```powershell complete-transaction +``` -A Get-Transaction command shows that the subscriber count on the -transaction object is 1, but the value of Status is still Active -(not Committed). +A Get-Transaction command shows that the subscriber count on the transaction +object is 1, but the value of Status is still Active (not Committed). +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -To finish committing the transaction, enter a second Complete- -Transaction command. To commit a multi-subscriber transaction, -you must enter one Complete-Transaction command for each -Start-Transaction command. +To finish committing the transaction, enter a second Complete- Transaction +command. To commit a multi-subscriber transaction, you must enter one +Complete-Transaction command for each Start-Transaction command. +```powershell complete-transaction +``` -Another Get-Transaction command shows that the transaction -has been committed. +Another Get-Transaction command shows that the transaction has been committed. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 0 Committed +``` -# EXAMPLE 9: MANAGING INDEPENDENT TRANSACTIONS - +### EXAMPLE 9: MANAGING INDEPENDENT TRANSACTIONS -When you start a transaction while another transaction is in -progress, you can use the Independent parameter of Start-Transaction -to make the new transaction independent of the original transaction. +When you start a transaction while another transaction is in progress, you can +use the Independent parameter of Start-Transaction to make the new transaction +independent of the original transaction. -When you do, Start-Transaction creates a new transaction object -and makes the new transaction the active transaction. +When you do, Start-Transaction creates a new transaction object and makes the +new transaction the active transaction. -Begin by starting a transaction in the HKCU:\Software key. +Begin by starting a transaction in the HKCU:\\Software key. +```powershell start-transaction +``` -The following command uses the Get-Transaction command to -get the active transaction. +The following command uses the Get-Transaction command to get the active +transaction. +```powershell get-transaction +``` The result shows the object that represents the active transaction. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The following command adds the MyCompany registry key as part of -the transaction. It uses the UseTransaction parameter (UseTx) -to include the command in the active transaction. +The following command adds the MyCompany registry key as part of the +transaction. It uses the UseTransaction parameter (UseTx) to include the +command in the active transaction. +```powershell new-item MyCompany -use +``` -The following command starts a new transaction. The command uses -the Independent parameter to indicate that this transaction -is not a subscriber to the active transaction. +The following command starts a new transaction. The command uses the +Independent parameter to indicate that this transaction is not a subscriber to +the active transaction. +```powershell start-transaction -independent +``` -When you create an independent transaction, the new (most-recently -created) transaction becomes the active transaction. You can use -a Get-Transaction command to get the active transaction. +When you create an independent transaction, the new (most-recently created) +transaction becomes the active transaction. You can use a Get-Transaction +command to get the active transaction. +```powershell get-transaction +``` -Note that the SubscriberCount of the transaction is 1, indicating -that there are no other subscribers and that the transaction is -new. +Note that the SubscriberCount of the transaction is 1, indicating that there +are no other subscribers and that the transaction is new. +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` -The new transaction must be finished (either committed or rolled -back) before you can manage the original transaction. +The new transaction must be finished (either committed or rolled back) before +you can manage the original transaction. -The following command adds the MyOtherCompany key to the registry. -It uses the UseTransaction parameter (UseTx) to include the command -in the active transaction. +The following command adds the MyOtherCompany key to the registry. It uses the +UseTransaction parameter (UseTx) to include the command in the active +transaction. +```powershell new-item MyOtherCompany -usetx +``` -Now, roll back the transaction. If there were a single -transaction with two subscribers, rolling back the transaction -would roll back the entire transaction for all the subscribers. +Now, roll back the transaction. If there were a single transaction with two +subscribers, rolling back the transaction would roll back the entire +transaction for all the subscribers. -However, because these transactions are independent, rolling -back the newest transaction cancels the registry changes and -makes the original transaction the active transaction. +However, because these transactions are independent, rolling back the newest +transaction cancels the registry changes and makes the original transaction +the active transaction. +```powershell undo-transaction +``` -A Get-Transaction command confirms that the original -transaction is still active in the session. +A Get-Transaction command confirms that the original transaction is still +active in the session. +```powershell get-transaction +``` +```output RollbackPreference SubscriberCount Status ------------------ --------------- ------ Error 1 Active +``` The following command commits the active transaction. +```powershell complete-transaction +``` -A Get-ChildItem command shows that the registry has been -changed. +A Get-ChildItem command shows that the registry has been changed. +```powershell dir m* +``` +```output Hive: HKEY_CURRENT_USER\Software SKC VC Name Property --- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} + 83 1 Microsoft {(default)} + 0 0 MyCompany {} +``` -# SEE ALSO +## SEE ALSO -Start-Transaction +[Start-Transaction](../../Microsoft.PowerShell.Management/Start-Transaction.md) -Get-Transaction +[Get-Transaction](../../Microsoft.PowerShell.Management/Get-Transaction.md) -Complete-Transaction +[Complete-Transaction](../../Microsoft.PowerShell.Management/Complete-Transaction.md) -Undo-Transaction +[Undo-Transaction](../../Microsoft.PowerShell.Management/Undo-Transaction.md) -Use-Transaction +[Use-Transaction](../../Microsoft.PowerShell.Management/Use-Transaction.md) -Registry (provider) +[Get-PSProvider](../../Microsoft.PowerShell.Management/Get-PSProvider.md) -[about_Providers](about_Providers.md) - -Get-PSProvider - -Get-ChildItem +[Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) +[about_Providers](about_Providers.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index 8c83f99a3472..7d45f6555135 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,487 +7,455 @@ title: about_Updatable_Help --- # About Updatable Help -## about_Updatable_Help +## SHORT DESCRIPTION +Describes the updatable help system in PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes the updatable help system in Windows PowerShell. +PowerShell provides several different ways to access the most up-to-date help +topics for PowerShell cmdlets and concepts. -# LONG DESCRIPTION +The Updatable Help system, introduced in PowerShell 3.0, is designed to assure +that you always have the newest help topics on your local computer so that you +can read them at the command line. It makes it easy to download and install +help files and to update them whenever newer help files become available. -Windows PowerShell provides several different ways to access -the most up-to-date help topics for Windows PowerShell cmdlets -and concepts. +To provide updated help for multiple computers in an enterprise and for +computers that do not have access to the Internet, Updatable Help lets you +download help files to a file system directory or file share, and then install +the help files from the file share. -The Updatable Help system, introduced in Windows PowerShell 3.0, -is designed to assure that you always have the newest help topics -on your local computer so that you can read them at the command -line. It makes it easy to download and install help files and -to update them whenever newer help files become available. +In PowerShell 4.0, the HelpInfoUri property is preserved over Windows +PowerShell remoting, which allows Save-Help to work for modules that are +installed on a remote computer, but are not necessarily installed on the local +computer. You can save a PSModuleInfo object to disk or removable media (such +as a USB drive) by running Export-Clixml on a computer that does not have +Internet access, importing the PSModuleInfo object on a computer that does +have Internet access, and then running Save-Help on the PSModuleInfo object. +The saved help can be copied to the remote, disconnected computer by using +removable media, and then installed by running Update-Help. These improvements +in Save-Help functionality let you install help on computers that are without +any kind of network access. For an example of how to use the new Save-Help +functionality, see "HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP" in this +topic. -To provide updated help for multiple computers in an enterprise -and for computers that do not have access to the Internet, Updatable -Help lets you download help files to a file system directory or file -share, and then install the help files from the file share. +Updatable Help also supports online access to the newest help topics and basic +help for cmdlets, even when there are no help files on the computer. -In Windows PowerShell 4.0, the HelpInfoUri property is preserved over -Windows PowerShell remoting, which allows Save-Help to work for -modules that are installed on a remote computer, but are not -necessarily installed on the local computer. You can save a PSModuleInfo -object to disk or removable media (such as a USB drive) by running -Export-Clixml on a computer that does not have Internet access, -importing the PSModuleInfo object on a computer that does have Internet -access, and then running Save-Help on the PSModuleInfo object. The -saved help can be copied to the remote, disconnected computer by using -removable media, and then installed by running Update-Help. These -improvements in Save-Help functionality let you install help on -computers that are without any kind of network access. For an example -of how to use the new Save-Help functionality, see "HOW TO UPDATE HELP -FROM A FILE SHARE: SAVE-HELP" in this topic. +PowerShell 3.0 does not come with Help files. You can use the Updatable Help +feature to install the help files for all of the commands that are included by +default in PowerShell and for all Windows modules. -Updatable Help also supports online access to the newest help topics -and basic help for cmdlets, even when there are no help files on the -computer. - -Windows PowerShell 3.0 does not come with Help files. You can use -the Updatable Help feature to install the help files for all of the -commands that are included by default in Windows PowerShell and for -all Windows modules. - -# UPDATABLE HELP CMDLETS - - -Update-Help: Downloads the newest help files from the Internet or -a file share, and installs them on the local computer. - -Save-Help: Downloads the newest help files from the Internet and -saves them in a file system directory or file share. To -install the help files on computers, use Update-Help. +## UPDATABLE HELP CMDLETS -Get-Help: -- Displays help topics at the command line. --- Gets help from the help files on the computer. --- Displays auto-generated help for cmdlets and functions -that do not have help files. --- Opens online help topics for cmdlets, functions, -scripts, and workflows in your default Internet -browser. +- Update-Help: Downloads the newest help files from the Internet or a file + share, and installs them on the local computer. -# UPDATE HELP IN WINDOWS POWERSHELL ISE +- Save-Help: Downloads the newest help files from the Internet and saves them in + a file system directory or file share. To install the help files on computers, + use Update-Help. -You can also update help by using the "Update Windows PowerShell -Help" item in the Help menu in Windows PowerShell Integrated -Scripting Environment (ISE). +- Get-Help: Displays help topics at the command line. Gets help from the + help files on the computer. Displays auto-generated help for cmdlets and + functions that do not have help files. Opens online help topics for + cmdlets, functions, scripts, and workflows in your default Internet browser. -The "Update Windows PowerShell Help" item runs an Update-Help -command without parameters. +## UPDATE HELP IN PowerShell ISE -# AUTO-GENERATED HELP: HELP WITHOUT HELP FILES +You can also update help by using the "Update PowerShell Help" item in the +Help menu in PowerShell Integrated Scripting Environment (ISE). +The "Update PowerShell Help" item runs an Update-Help command without +parameters. -If you do not have the help file for a cmdlet, function, -or workflow on the computer, the Get-Help cmdlet displays -auto-generated help and prompts you to download the help -files or read them online. +## AUTO-GENERATED HELP: HELP WITHOUT HELP FILES -Auto-generated help includes syntax and aliases, and remarks -that explain how to use the Updatable Help cmdlets and to -access the online help topics. +If you do not have the help file for a cmdlet, function, or workflow on the +computer, the Get-Help cmdlet displays auto-generated help and prompts you to +download the help files or read them online. -For example, the following command gets basic help for the -Get-Culture cmdlet. The output shows the Get-Help display -when there are no help files on the computer. +Auto-generated help includes syntax and aliases, and remarks that explain how +to use the Updatable Help cmdlets and to access the online help topics. -PS C:> Get-Help Get-Culture - -# NAME - -Get-Culture - -# SYNTAX +For example, the following command gets basic help for the Get-Culture cmdlet. +The output shows the Get-Help display when there are no help files on the +computer. -Get-Culture [] +```powershell +Get-Help Get-Culture +``` -# ALIASES +```output +NAME + Get-Culture -None +SYNTAX + Get-Culture [] -# REMARKS +ALIASES + None -To get the latest Help content including descriptions -and examples type: Update-Help. +REMARKS + To get the latest Help content including descriptions and examples + type: Update-Help. +``` -# HELP FILES FOR MODULES +## HELP FILES FOR MODULES +The smallest unit of Updatable Help is help for a module. Module help includes +help for all of the cmdlets, functions, workflows, providers, scripts, and +concepts in a module. You can update help for all modules that are installed +on the computer, even if they are not imported into the current session. -The smallest unit of Updatable Help is help for a module. Module -help includes help for all of the cmdlets, functions, workflows, -providers, scripts, and concepts in a module. You can update help -for all modules that are installed on the computer, even if they -are not imported into the current session. +You can update help for the entire module, but you cannot update help for +individual cmdlets. -You can update help for the entire module, but you cannot update -help for individual cmdlets. - -To find the module that contains a particular cmdlet, use the -following command format: +To find the module that contains a particular cmdlet, use the following +command format: +```powershell (Get-Command ).ModuleName +``` For example, to find the module that contains the Set-ExecutionPolicy cmdlet, type: +```powershell (Get-Command Set-ExecutionPolicy).ModuleName +``` To update help for a particular module, type: +```powershell Update-Help -Module +``` For example, to update help for the module that contains the Set-ExecutionPolicy cmdlet, type: +```powershell Update-Help -Module Microsoft.PowerShell.Security +``` -# PERMISSIONS FOR UPDATABLE HELP - - -To update help for the modules in the $pshome\Modules directory, -you must be member of the Administrators group on the computer. +## PERMISSIONS FOR UPDATABLE HELP -If you are not a member of the Administrators group, you cannot -update help for these modules; but if you have Internet access, -you can view help online in the TechNet Library. +To update help for the modules in the \$pshome\\Modules directory, you must be +member of the Administrators group on the computer. -Updating help for modules in the -$home\Documents\WindowsPowerShell\Modules -directory or modules in other subdirectories of the $home -directory do not require special permissions. +If you are not a member of the Administrators group, you cannot update help +for these modules; but if you have Internet access, you can view help online +in the TechNet Library. -The Update-Help and Save-Help cmdlets have a UseDefaultCredentials -parameter that provides the explicit credentials of the current -user. This parameter is designed for accessing secure Internet -locations. +Updating help for modules in the \$home\\Documents\\WindowsPowerShell\\Modules +directory or modules in other subdirectories of the \$home directory do not +require special permissions. -The Update-Help and Save-Help cmdlets also have a Credential -parameter that allows you to run the command on a remote -computer and access a file share on a third computer. The -Credential parameter is valid only when you use the SourcePath -or LiteralPath parameters of Update-Help and the DestinationPath -or LiteralPath parameters of Save-Help. +The Update-Help and Save-Help cmdlets have a UseDefaultCredentials parameter +that provides the explicit credentials of the current user. This parameter is +designed for accessing secure Internet locations. -# HOW TO INSTALL AND UPDATE HELP FILES +The Update-Help and Save-Help cmdlets also have a Credential parameter that +allows you to run the command on a remote computer and access a file share on +a third computer. The Credential parameter is valid only when you use the +SourcePath or LiteralPath parameters of Update-Help and the DestinationPath or +LiteralPath parameters of Save-Help. +## HOW TO INSTALL AND UPDATE HELP FILES -To download and install help files for the first time, or to update -the help files on your computer, use the Update-Help cmdlet. +To download and install help files for the first time, or to update the help +files on your computer, use the Update-Help cmdlet. -The Update-Help cmdlet does all of the hard work for you, including -the following tasks. +The Update-Help cmdlet does all of the hard work for you, including the +following tasks. --- Determines which modules support Updatable Help. --- Finds the Internet location where each module stores its -Updatable Help files. --- Compares the help files for each module on your computer to -the newest help files that are available for each module. --- Downloads the new files from the Internet. --- Unwraps the help file package. --- Verifies that the files are valid help files. --- Installs the help files in the language-specific subdirectory -of the module directory. +- Determines which modules support Updatable Help. +- Finds the Internet location where each module stores its Updatable Help files. +- Compares the help files for each module on your computer to the newest help + files that are available for each module. +- Downloads the new files from the Internet. +- Unwraps the help file package. +- Verifies that the files are valid help files. +- Installs the help files in the language-specific subdirectory of the module + directory. -To access the new help topics, use the Get-Help cmdlet. You do not -need to restart Windows PowerShell. +To access the new help topics, use the Get-Help cmdlet. You do not need to +restart PowerShell. -To install or update help for all modules on the computer that -supports Updatable Help, type: +To install or update help for all modules on the computer that supports +Updatable Help, type: +```powershell Update-Help +``` -To update help for particular modules, add the Module parameter -of Update-Help. Wildcard characters are permitted in the module name. +To update help for particular modules, add the Module parameter of +Update-Help. Wildcard characters are permitted in the module name. For example, to update help for the ServerManager module, type: +```powershell Update-Help -Module ServerManager - -# NOTES - -Without parameters, Update-Help updates help for all modules -in the session and for all installed modules that support -Updatable Help. To be included, modules must be installed in -directories that are listed in the value of the PSModulePath -environment variable. These are also modules that -are returned by a "Get-Help -ListAvailable" command. - -If the value of the Module parameter is * (all), Update-Help -attempts to update help for all installed modules, including -modules that do not support Updatable Help. This command -typically generates many errors as the cmdlet encounters modules -that do not support Updatable Help. - -# HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP - - -To support computers that are not connected to the Internet, -or to control or streamline help updating in an enterprise, -use the Save-Help cmdlet. The Save-Help cmdlet downloads help -files from the Internet and saves them in a file system directory -that you specify. - -Save-Help compares the help files in the specified directory to -the newest help files that are available for each module. If the -directory has no help files or newer help files are available for -the module, the Save-Help cmdlet downloads the new files from the -Internet. However, it does not unwrap or install the help files. - -To install or update the help files on a computer from help -files that were saved to a file system directory, use the -SourcePath parameter of the Update-Help cmdlet. The Update-Help -cmdlet identifies the newest help files, unwraps and validates them, -and installs them in the language-specific subdirectories of the -module directories. - -For example, to save help for all installed modules to the -\Server\Share directory, type: - -Save-Help -DestinationPath \Server\Share - -Then, to update help from the \Server\Share directory, type: - -Update-Help -SourcePath \Server\Share - -The following examples show the use of Save-Help to save help -for modules that are not installed on the local computer. In -this example, the administrator runs Save-Help to save the help -for the DhcpServer module from an Internet-connected client computer, -without installing the DhcpServer module or DHCP Server role on the -local computer. - -Option 1: Run Invoke-Command to get the PSModuleInfo object for -the remote module, save it in a variable, $m, and then run Save-Help -on the PSModuleInfo object by specifying the variable $m as the -module name. - +``` + +Without parameters, Update-Help updates help for all modules in the session +and for all installed modules that support Updatable Help. To be included, +modules must be installed in directories that are listed in the value of the +PSModulePath environment variable. These are also modules that are returned by +a "Get-Help -ListAvailable" command. + +If the value of the Module parameter is * (all), Update-Help attempts to +update help for all installed modules, including modules that do not support +Updatable Help. This command typically generates many errors as the cmdlet +encounters modules that do not support Updatable Help. + +## HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP + +To support computers that are not connected to the Internet, or to control or +streamline help updating in an enterprise, use the Save-Help cmdlet. The +Save-Help cmdlet downloads help files from the Internet and saves them in a +file system directory that you specify. + +Save-Help compares the help files in the specified directory to the newest +help files that are available for each module. If the directory has no help +files or newer help files are available for the module, the Save-Help cmdlet +downloads the new files from the Internet. However, it does not unwrap or +install the help files. + +To install or update the help files on a computer from help files that were +saved to a file system directory, use the SourcePath parameter of the +Update-Help cmdlet. The Update-Help cmdlet identifies the newest help files, +unwraps and validates them, and installs them in the language-specific +subdirectories of the module directories. + +For example, to save help for all installed modules to the \\\\Server\\Share +directory, type: + +```powershell +Save-Help -DestinationPath \\Server\Share +``` + +Then, to update help from the \\\\Server\\Share directory, type: + +```powershell +Update-Help -SourcePath \\Server\Share +``` + +The following examples show the use of Save-Help to save help for modules that +are not installed on the local computer. In this example, the administrator +runs Save-Help to save the help for the DhcpServer module from an +Internet-connected client computer, without installing the DhcpServer module +or DHCP Server role on the local computer. + +Option 1: Run Invoke-Command to get the PSModuleInfo object for the remote +module, save it in a variable, $m, and then run Save-Help on the PSModuleInfo +object by specifying the variable $m as the module name. + +```powershell $m = Invoke-Command -ComputerName RemoteServer -ScriptBlock { Get-Module -Name DhcpServer -ListAvailable } Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -Option 2: Open a PSSession, targeted at the computer that is -running the DHCP Server module, to get the PSModuleInfo object for -the module, save it in a variable $m, and then run Save-Help on the -object that is saved in the $m variable. +Option 2: Open a PSSession, targeted at the computer that is running the DHCP +Server module, to get the PSModuleInfo object for the module, save it in a +variable $m, and then run Save-Help on the object that is saved in the $m +variable. +```powershell $s = New-PSSession -ComputerName RemoteServer $m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -Option 3: Open a CIM session, targeted at the computer that is -running the DHCP Server module, to get the PSModuleInfo object for -the module, save it in a variable $m, and then run Save-Help on the -object that is saved in the $m variable. +Option 3: Open a CIM session, targeted at the computer that is running the +DHCP Server module, to get the PSModuleInfo object for the module, save it in +a variable $m, and then run Save-Help on the object that is saved in the $m +variable. +```powershell $c = New-CimSession -ComputerName RemoteServer $m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -In the following example, the administrator installs help for the -DHCP Server module on a computer that does not have network access. +In the following example, the administrator installs help for the DHCP Server +module on a computer that does not have network access. -First, run Export-Clixml to export the PSModuleInfo object to -a shared folder or to removable media. +First, run Export-Clixml to export the PSModuleInfo object to a shared folder +or to removable media. +```powershell $m = Get-Module -Name DhcpServer -ListAvailable Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m +``` -Next, transport the removable media to a computer that has -Internet access, and then import the PSModuleInfo object with -Import-Clixml. Run Save-Help to save the Help for the imported -DhcpServer module PSModuleInfo object. +Next, transport the removable media to a computer that has Internet access, +and then import the PSModuleInfo object with Import-Clixml. Run Save-Help to +save the Help for the imported DhcpServer module PSModuleInfo object. +```powershell $deserialized_m = Import-Clixml E:\UsbFlashDrive\DhcpModule.xml -Save-Help -Module $deserialized_m -DestinationPath -E:\UsbFlashDrive\SavedHelp - -Finally, transport the removable media back to the computer that -does not have network access, and then install the help by running -Update-Help. - -Update-Help -Module DhcpServer -SourcePath +Save-Help -Module $deserialized_m -DestinationPath ` E:\UsbFlashDrive\SavedHelp +``` -# NOTES: +Finally, transport the removable media back to the computer that does not have +network access, and then install the help by running Update-Help. -Without parameters, Save-Help downloads help for all modules -in the session and for all installed modules that support -Updatable Help. To be included, modules must be installed in -directories that are listed in the value of the PSModulePath -environment variable, on either the local computer or on a remote -computer for which you want to save help. These are also modules -that are returned by running a "Get-Help -ListAvailable" command. +```powershell +Update-Help -Module DhcpServer -SourcePath E:\UsbFlashDrive\SavedHelp +``` -# HOW TO UPDATE HELP FILES IN DIFFERENT LANGUAGES +Without parameters, Save-Help downloads help for all modules in the session +and for all installed modules that support Updatable Help. To be included, +modules must be installed in directories that are listed in the value of the +PSModulePath environment variable, on either the local computer or on a remote +computer for which you want to save help. These are also modules that are +returned by running a "Get-Help -ListAvailable" command. +## HOW TO UPDATE HELP FILES IN DIFFERENT LANGUAGES -By default, the Update-Help and Save-Help cmdlets download -help in the UI culture and language that is set for Windows -on the local computer. If help files for the specified modules -are not available in the local UI culture, Update-Help and -Save-Help use the Windows language fallback rules to find the +By default, the Update-Help and Save-Help cmdlets download help in the UI +culture and language that is set for Windows on the local computer. If help +files for the specified modules are not available in the local UI culture, +Update-Help and Save-Help use the Windows language fallback rules to find the best supported language. -However, you can use the UICulture parameters of the Update-Help -and Save-Help cmdlets to download and install help files in any -UI cultures in which they are available. +However, you can use the UICulture parameters of the Update-Help and Save-Help +cmdlets to download and install help files in any UI cultures in which they +are available. -For example, to save the newest help files for all modules on -the session in Japanese (Ja-jp) and French (fr-FR), type: +For example, to save the newest help files for all modules on the session in +Japanese (Ja-jp) and French (fr-FR), type: +```powershell Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr +``` -If help files for the modules are not available in the languages -that you specified, the Update-Help and Save-Help cmdlets return -an error message that lists the languages in which help for each -module is available so you can choose the alternative that best -meets your needs. +If help files for the modules are not available in the languages that you +specified, the Update-Help and Save-Help cmdlets return an error message that +lists the languages in which help for each module is available so you can +choose the alternative that best meets your needs. -# HOW TO UPDATE HELP AUTOMATICALLY +## HOW TO UPDATE HELP AUTOMATICALLY +To assure that you always have the newest help files, you can add an +Update-Help command to your PowerShell profile. -To assure that you always have the newest help files, you can -add an Update-Help command to your Windows PowerShell profile. +An internal quota prevents the Update-Help command from running more than once +each day. To override the once-per-day maximum, use the Force parameter. -An internal quota prevents the Update-Help command from running -more than once each day. To override the once-per-day maximum, -use the Force parameter. - -Use a command like the following one in your profile. This command -updates help for all installed modules in a background job so it -doesn't disturb your work. It uses an Out-Null command to suppress -the job that is returned and any error messages that would otherwise -appear when you use the command more than once per day. +Use a command like the following one in your profile. This command updates +help for all installed modules in a background job so it doesn't disturb your +work. It uses an Out-Null command to suppress the job that is returned and any +error messages that would otherwise appear when you use the command more than +once per day. +```powershell Start-Job {Update-Help} | Out-Null +``` -You can also create a scheduled job that runs the Update-Help or -Save-Help cmdlet at any interval. +You can also create a scheduled job that runs the Update-Help or Save-Help +cmdlet at any interval. For example, the following command creates a scheduled job that runs an -Update-Help help command every Friday at 5:00 AM. To run this command, -start Windows PowerShell with the "Run as administrator" option. +Update-Help help command every Friday at 5:00 AM. To run this command, start +PowerShell with the "Run as administrator" option. +```powershell Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} ` -Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM") +``` -For more information about scheduled jobs, see about_Scheduled_Jobs. - -# HOW TO USE ONLINE HELP - +## HOW TO USE ONLINE HELP -If you cannot or choose not to update the help files on your -local computer, you can still get the newest help files online. +If you cannot or choose not to update the help files on your local computer, +you can still get the newest help files online. -To open the online help topic for any cmdlet or function, use -the Online parameter of the Get-Help cmdlet. +To open the online help topic for any cmdlet or function, use the Online +parameter of the Get-Help cmdlet. -For example, the following command opens the online help topic -for the Get-Job cmdlet in your default Internet browser: +For example, the following command opens the online help topic for the Get-Job +cmdlet in your default Internet browser: +```powershell Get-Help Get-Job -Online --or- -Get-Help -on Get-Job - -To get online help for a script, use the Online parameter and -the full path to the script. - -The Online parameter does not work with About topics. To see -the about topics for Windows PowerShell Core, including help -topics about the Windows PowerShell language, see "Windows -PowerShell Core Module About Topics" at -http://go.microsoft.com/fwlink/?LinkID=113206. - -# HOW TO MINIMIZE OR PREVENT INTERNET DOWNLOADS - -To minimize Internet downloads and provide Updatable Help to -users who are not connected to the Internet, use the Save-Help -cmdlet. Download help from the Internet and save it to a network -share. Then, create a Group Policy setting or scheduled job that -runs an Update-Help command on all computers. Set the value of -the SourcePath parameter of the Update-Help cmdlet to the network -share. - -To prevent users who have Internet access from downloading Updatable -Help from the Internet, use the "Set the default source path for -Update-Help" Group Policy setting. +``` -This Group Policy setting implicitly adds the SourcePath parameter, -with the file system location that you specify, to every Update-Help -command on every affected computer. Users can use the SourcePath -parameter explicitly to specify a different file system location, but -they cannot exclude the SourcePath parameter and download help from -the Internet. +To get online help for a script, use the Online parameter and the full path to +the script. -NOTE: The "Set the default source path for Update-Help" group -policy setting appears under Computer Configuration and -User Configuration. However, only the policy setting -under Computer Configuration is effective. The policy -setting under User Configuration is ignored. +The Online parameter does not work with About topics. To see the about topics +for PowerShell Core, including help topics about the PowerShell language, see +[Windows PowerShell Core Module About Topics](http://go.microsoft.com/fwlink/?LinkID=113206). -For more information, see about_Group_Policy_Settings. +## HOW TO MINIMIZE OR PREVENT INTERNET DOWNLOADS -# HOW TO UPDATE HELP FOR NON-STANDARD MODULES +To minimize Internet downloads and provide Updatable Help to users who are not +connected to the Internet, use the Save-Help cmdlet. Download help from the +Internet and save it to a network share. Then, create a Group Policy setting +or scheduled job that runs an Update-Help command on all computers. Set the +value of the SourcePath parameter of the Update-Help cmdlet to the network +share. -To update or save help for a module that is not returned -by the ListAvailable parameter of the Get-Module cmdlet, -import the module into the current session before running -an Update-Help or Save-Help command. On a remote computer, -before running the Save-Help command, import the module into -the current CIM or PSSession--or Invoke-Command script block-- -that is connected to the remote computer. +To prevent users who have Internet access from downloading Updatable Help from +the Internet, use the "Set the default source path for Update-Help" Group +Policy setting. -When the module is in the current session, run the Update-Help -or Save-Help cmdlets without parameters, or use the Module -parameter to specify the module name. +This Group Policy setting implicitly adds the SourcePath parameter, with the +file system location that you specify, to every Update-Help command on every +affected computer. Users can use the SourcePath parameter explicitly to +specify a different file system location, but they cannot exclude the +SourcePath parameter and download help from the Internet. -The Module parameters of the Update-Help and Save-Help -cmdlets accept only a module name. They do not accept the -path to a module file. +NOTE: The "Set the default source path for Update-Help" group policy setting +appears under Computer Configuration and User Configuration. However, only the +policy setting under Computer Configuration is effective. The policy setting +under User Configuration is ignored. -Use this technique to update or save help for any module -that is not returned by the ListAvailable parameter of the -Get-Module cmdlet, such as a module that is installed in a -location that is not listed in the PSModulePath environment -variable, or a module that is not well-formed (the module -directory does not contain at least one file whose base name -is the same as the directory name). +For more information, see [about_Group_Policy_Settings](about_Group_Policy_Settings.md). -# HOW TO SUPPORT UPDATABLE HELP +## HOW TO UPDATE HELP FOR NON-STANDARD MODULES +To update or save help for a module that is not returned by the ListAvailable +parameter of the Get-Module cmdlet, import the module into the current session +before running an Update-Help or Save-Help command. On a remote computer, +before running the Save-Help command, import the module into the current CIM +or PSSession--or Invoke-Command script block-- that is connected to the remote +computer. -If you author a module, you can support online help and -Updatable Help for your modules. For more information, see -"Supporting Updatable Help" and "Supporting Online Help" -in the MSDN Library. +When the module is in the current session, run the Update-Help or Save-Help +cmdlets without parameters, or use the Module parameter to specify the module +name. -Updatable help not available for Windows PowerShell snap-ins -or comment-based help. +The Module parameters of the Update-Help and Save-Help cmdlets accept only a +module name. They do not accept the path to a module file. -# KEYWORDS +Use this technique to update or save help for any module that is not returned +by the ListAvailable parameter of the Get-Module cmdlet, such as a module that +is installed in a location that is not listed in the PSModulePath environment +variable, or a module that is not well-formed (the module directory does not +contain at least one file whose base name is the same as the directory name). -About_Updateable_Help +## HOW TO SUPPORT UPDATABLE HELP -# REMARKS +If you author a module, you can support online help and Updatable Help for +your modules. For more information, see "Supporting Updatable Help" and +"Supporting Online Help" in the MSDN Library. -The Update-Help and Save-Help cmdlets are not supported on -Windows Preinstallation Environment (Windows PE). +Updatable help not available for PowerShell snap-ins or comment-based help. -# SEE ALSO +# REMARKS -Get-Help +The Update-Help and Save-Help cmdlets are not supported on Windows +Preinstallation Environment (Windows PE). -Save-Help +## SEE ALSO -Update-Help +[Get-Help](../Get-Help.md) -Updatable Help Status Table (http://go.microsoft.com/fwlink/?LinkID=270007) +[Save-Help](../Save-Help.md) +[Update-Help](../Update-Help.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI.md index 816338a248a5..bafb6c425a08 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_WMI.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,83 +7,104 @@ title: about_WMI --- # About WMI -## about_WMI - ## SHORT DESCRIPTION -Windows Management Instrumentation (WMI) uses the Common Information Model (CIM) to represent systems, applications, networks, devices, and other manageable components of the modern enterprise. +Windows Management Instrumentation (WMI) uses the Common Information Model +(CIM) to represent systems, applications, networks, devices, and other +manageable components of the modern enterprise. ## LONG DESCRIPTION -Windows Management Instrumentation (WMI) is Microsoft’s implementation of Web-Based Enterprise Management (WBEM), the industry standard. -Classic WMI uses DCOM to communicate with networked devices to manage remote systems. Windows PowerShell 3.0 introduces a CIM provider model that uses WinRM to remove the dependency on DCOM. This CIM provider model also uses new WMI provider APIs that enable developers to write Windows PowerShell cmdlets in native code (C\+\+). +Windows Management Instrumentation (WMI) is Microsoft’s implementation of +Web-Based Enterprise Management (WBEM), the industry standard. -Do not confuse WMI providers with Windows PowerShell providers. Many Windows features have an associated WMI provider that exposes their management capabilities. To get WMI providers, run a WMI query that gets instances of the __Provider WMI class, such as the following query. +Classic WMI uses DCOM to communicate with networked devices to manage remote +systems. Windows PowerShell® 3.0 introduces a CIM provider model that uses +WinRM to remove the dependency on DCOM. This CIM provider model also uses new +WMI provider APIs that enable developers to write Windows PowerShell cmdlets +in native code (C\+\+). +Do not confuse WMI providers with Windows PowerShell providers. Many Windows +features have an associated WMI provider that exposes their management +capabilities. To get WMI providers, run a WMI query that gets instances of the +__Provider WMI class, such as the following query. -``` +```powershell Get-WmiObject -Class __Provider ``` - - ## THREE COMPONENTS OF WMI -The following three components of WMI interact with Windows PowerShell: Namespaces, Providers, and Classes. -WMI Namespaces organize WMI providers and WMI classes into groups of related components. In this way, they are similar to .NET Framework namespaces. Namespaces are not physical locations, but are more like logical databases. All WMI namespaces are instances of the __Namespace system class. The default WMI namespace is Root\/CIMV2 (since Microsoft Windows 2000). To use Windows PowerShell to get WMI namespaces in the current session, use a command with the following format. +The following three components of WMI interact with Windows PowerShell: +Namespaces, Providers, and Classes. +WMI Namespaces organize WMI providers and WMI classes into groups of related +components. In this way, they are similar to .NET Framework namespaces. +Namespaces are not physical locations, but are more like logical databases. +All WMI namespaces are instances of the __Namespace system class. The default +WMI namespace is Root\/CIMV2 (since Microsoft Windows 2000). To use Windows +PowerShell to get WMI namespaces in the current session, use a command with +the following format. -``` +```powershell Get-WmiObject -Class __Namespace ``` +To get WMI namespaces in other namespaces, use the Namespace parameter to +change the location of the search. The following command finds WMI namespaces +that reside in the Root/Cimv2/Applications namespace. -To get WMI namespaces in other namespaces, use the Namespace parameter to change the location of the search. The following command finds WMI namespaces that reside in the Root\/Cimv2\/Applications namespace. - - -``` -Get-WmiObject -Class __Namespace -Namespace -root/CIMv2/applications +```powershell +Get-WmiObject -Class __Namespace -Namespace root/CIMv2/applications ``` +WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces +on a particular system requires performing a recursive query starting at the +root namespace. -WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces on a particular system requires performing a recursive query starting at the root namespace. - -WMI Providers expose information about Windows manageable objects. A provider retrieves data from a component, and passes that data through WMI to a management application, such as Windows PowerShell. Most WMI providers are dynamic providers, which means that they obtain the data dynamically when it is requested through the management application. - +WMI Providers expose information about Windows manageable objects. A provider +retrieves data from a component, and passes that data through WMI to a +management application, such as Windows PowerShell. Most WMI providers are +dynamic providers, which means that they obtain the data dynamically when it +is requested through the management application. ## FINDING WMI CLASSES -In a default installation of Windows 8, there are more than 1,100 WMI classes in Root\/Cimv2. With this many WMI classes, the challenge becomes identifying the appropriate WMI class to use to perform a specific task. Windows PowerShell 3.0 provides two ways to find WMI classes that are related to a specific topic. -For example,to find WMI classes in the root\CIMV2 WMI namespace that are related to disks, you can use a query such as the one shown here. +In a default installation of Windows 8, there are more than 1,100 WMI classes +in Root\/Cimv2. With this many WMI classes, the challenge becomes identifying +the appropriate WMI class to use to perform a specific task. Windows +PowerShell 3.0 provides two ways to find WMI classes that are related to a +specific topic. +For example,to find WMI classes in the root\\CIMV2 WMI namespace that are +related to disks, you can use a query such as the one shown here. -``` +```powershell Get-WmiObject -List *disk* ``` +To find WMI classes that are related to memory, you might use a query such as +the one shown here. -To find WMI classes that are related to memory, you might use a query such as the one shown here. - - -``` +```powershell Get-WmiObject -List *memory* ``` +The CIM cmdlets also provide the ability to discover WMI classes. To do this, +use the Get-CIMClass cmdlet. The command shown here lists WMI classes related +to video. -The CIM cmdlets also provide the ability to discover WMI classes. To do this, use the Get-CIMClass cmdlet. The command shown here lists WMI classes related to video. - - -``` +```powershell Get-CimClass *video* ``` +Tab expansion works when changing WMI namespaces, and therefore use of tab +expansion makes sub-WMI namespaces easily discoverable. In the following +example, the Get-CimClass cmdlet lists WMI classes related to power settings. +To find it, type the `root/CIMV2/` namespace and then press the Tab key +several times until the power namespace appears. Here is the command: -Tab expansion works when changing WMI namespaces, and therefore use of tab expansion makes sub-WMI namespaces easily discoverable. In the following example, the Get-CimClass cmdlet lists WMI classes related to power settings. To find it, type the root\/CIMV2\/ WMI namespace, and then press type the root\/CIMV2\/ WMI namespace, and then press the Tab key several times until the power namespace appears. Here is the command: - - -``` +```powershell Get-CimClass *power* -Namespace root/cimv2/power ``` - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_WQL.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_WQL.md index 4413e4b4bf38..5835819c2aeb 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_WQL.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_WQL.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,384 +7,356 @@ title: about_WQL --- # About WQL -## about_WQL +## SHORT DESCRIPTION +Describes WMI Query Language (WQL), which can be used to get WMI objects in +Windows PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes WMI Query Language (WQL), which can be -used to get WMI objects in Windows PowerShell. +WQL is the Windows Management Instrumentation (WMI) query language, which is +the language used to get information from WMI. -# LONG DESCRIPTION +You are not required to use WQL to perform a WMI query in Windows PowerShell. +Instead, you can use the parameters of the Get-WmiObject or Get-CimInstance +cmdlets. WQL queries are somewhat faster than standard Get-WmiObject commands +and the improved performance is evident when the commands run on hundreds of +systems. However, be sure that the time you spend to write a successful WQL +query doesn't outweigh the performance improvement. -WQL is the Windows Management Instrumentation (WMI) -query language, which is the language used to get -information from WMI. +The basic WQL statements you need to use WQL are Select, Where, and From. -You are not required to use WQL to perform a WMI -query in Windows PowerShell. Instead, you can -use the parameters of the Get-WmiObject or -Get-CimInstance cmdlets. WQL queries are somewhat -faster than standard Get-WmiObject commands and -the improved performance is evident when the commands -run on hundreds of systems. However, be sure that -the time you spend to write a successful WQL query -doesn't outweigh the performance improvement. +## WHEN TO USE WQL -The basic WQL statements you need to use WQL are -Select, Where, and From. +When working with WMI, and especially with WQL, do not forget that you are +also using Windows PowerShell. Often, if a WQL query does not work as +expected, it's easier to use a standard Windows PowerShell command than to +debug the WQL query. -# WHEN TO USE WQL - - -When working with WMI, and especially with WQL, -do not forget that you are also using Windows -PowerShell. Often, if a WQL query does not work as -expected, it's easier to use a standard Windows -PowerShell command than to debug the WQL query. - -Unless you are returning massive amounts of data -from across bandwidth-constrained remote systems, -it is rarely productive to spend hours trying to -perfect a complicated and convoluted WQL query -when there is a perfectly acceptable Windows -cmdlet that does the same thing, if a bit more +Unless you are returning massive amounts of data from across +bandwidth-constrained remote systems, it is rarely productive to spend hours +trying to perfect a complicated and convoluted WQL query when there is a +perfectly acceptable Windows cmdlet that does the same thing, if a bit more slowly. -# USING THE SELECT STATEMENT - +## USING THE SELECT STATEMENT -A typical WMI query begins with a Select statement -that gets all properties or particular properties -of a WMI class. To select all properties of a WMI -class, use an asterisk (*). The From keyword -specifies the WMI class. +A typical WMI query begins with a Select statement that gets all properties or +particular properties of a WMI class. To select all properties of a WMI class, +use an asterisk (*). The From keyword specifies the WMI class. A Select statement has the following format: +``` Select from +``` -For example, the following Select statement selects -all properties (*) from the instances of the Win32_Bios -WMI class. +For example, the following Select statement selects all properties (*) from +the instances of the Win32_Bios WMI class. +``` Select * from Win32_Bios +``` -To select a particular property of a WMI class, -place the property name between the Select and -From keywords. +To select a particular property of a WMI class, place the property name +between the Select and From keywords. -The following query selects only the name of -the BIOS from the Win32_Bios WMI class. The -command saves the query in the $queryName -variable. +The following query selects only the name of the BIOS from the Win32_Bios WMI +class. The command saves the query in the $queryName variable. +``` Select Name from Win32_Bios +``` -To select more than one property, use commas to -separate the property names. The following WMI -query selects the name and the version of the -Win32_Bios WMI class. The command saves the -query in the $queryNameVersion variable. +To select more than one property, use commas to separate the property names. +The following WMI query selects the name and the version of the Win32_Bios WMI +class. The command saves the query in the $queryNameVersion variable. +``` Select name, version from Win32_Bios +``` -# USING THE WQL QUERY +## USING THE WQL QUERY +There are three ways to use WQL query in Windows PowerShell command. -There are three ways to use WQL query in Windows -PowerShell command. +- Use the Get-WmiObject cmdlet +- Use the Get-CimInstance cmdlet +- Use the [wmisearcher] type accelerator. --- Use the Get-WmiObject cmdlet --- Use the Get-CimInstance cmdlet --- Use the [wmisearcher] type accelerator. +## USING THE GET-WMIOBJECT CMDLET -# USING THE GET-WMIOBJECT CMDLET +The most basic way to use the WQL query is to enclose it in quotation marks +(as a string) and then use the query string as the value of the Query +parameter of the Get-WmiObject cmdlet, as shown in the following example. -The most basic way to use the WQL query is to enclose -it in quotation marks (as a string) and then use the -query string as the value of the Query parameter of -the Get-WmiObject cmdlet, as shown in the following -example. - -PS C:> Get-WmiObject -Query "Select * from Win32_Bios" +```powershell +Get-WmiObject -Query "Select * from Win32_Bios" +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -You can also save the WQL statement in a variable -and then use the variable as the value of the Query -parameter, as shown in the following command. +You can also save the WQL statement in a variable and then use the variable as +the value of the Query parameter, as shown in the following command. -PS C:> $query = "Select * from Win32_Bios" -PS C:> Get-WmiObject -Query $query +```powershell +$query = "Select * from Win32_Bios" +Get-WmiObject -Query $query +``` -You can use either format with any WQL statement. -The following command uses the query in the -$queryName variable to get only the name and -version properties of the system BIOS. +You can use either format with any WQL statement. The following command uses +the query in the $queryName variable to get only the name and version +properties of the system BIOS. -PS C:> $queryNameVersion = "Select Name, Version from Win32_Bios" -PS C:> Get-WmiObject -Query $queryNameVersion - -# __GENUS : 2 +```powershell +$queryNameVersion = "Select Name, Version from Win32_Bios" +Get-WmiObject -Query $queryNameVersion +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS Version : LENOVO - 1360 +``` -Remember that you can use the parameters of the -Get-WmiObject cmdlet to get the same result. For -example, the following command also gets the values -of the Name and Version properties of instances of -the Win32_Bios WMI class. - -PS C:> Get-WmiObject -Class Win32_Bios -Property Name, Version +Remember that you can use the parameters of the Get-WmiObject cmdlet to get +the same result. For example, the following command also gets the values of +the Name and Version properties of instances of the Win32_Bios WMI class. -# __GENUS : 2 +```powershell +Get-WmiObject -Class Win32_Bios -Property Name, Version +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS Version : LENOVO - 1360 +``` -# USING THE GET-CIMINSTANCE CMDLET +## USING THE GET-CIMINSTANCE CMDLET +Beginning in Windows PowerShell 3.0, you can use the Get-CimInstance cmdlet to +run WQL queries. -Beginning in Windows PowerShell 3.0, you can use -the Get-CimInstance cmdlet to run WQL queries. +Get-CimInstance gets instances of CIM-compliant classes, including WMI +classes. The CIM cmdlets, introduced Windows PowerShell 3.0, perform the same +tasks as the WMI cmdlets. The CIM cmdlets comply with WS-Management (WSMan) +standards and with the Common Information Model (CIM) standard, which enables +the cmdlets to use the same techniques to manage Windows computers and +computers that are running other operating systems. -Get-CimInstance gets instances of CIM-compliant -classes, including WMI classes. The CIM cmdlets, -introduced Windows PowerShell 3.0, perform the same -tasks as the WMI cmdlets. The CIM cmdlets comply -with WS-Management (WSMan) standards and with the -Common Information Model (CIM) standard, which enables -the cmdlets to use the same techniques to manage -Windows computers and computers that are running -other operating systems. +The following command uses the Get-CimInstance cmdlet to run a WQL query. -The following command uses the Get-CimInstance -cmdlet to run a WQL query. +Any WQL query that can be used with Get-WmiObject can also be used with +Get-CimInstance. -Any WQL query that can be used with Get-WmiObject -can also be used with Get-CimInstance. - -PS C:> Get-CimInstance -Query "Select * from Win32_Bios" +```powershell +Get-CimInstance -Query "Select * from Win32_Bios" +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -Get-CimInstance returns a CimInstance object, instead of -the ManagementObject that Get-WmiObject returns, but -the objects are quite similar. +Get-CimInstance returns a CimInstance object, instead of the ManagementObject +that Get-WmiObject returns, but the objects are quite similar. -PS C:> (Get-CimInstance -Query "Select * from Win32_Bios").GetType().FullName +``` +(Get-CimInstance -Query "Select * from Win32_Bios").GetType().FullName Microsoft.Management.Infrastructure.CimInstance -PS C:> (Get-WmiObject -Query "Select * from Win32_Bios").GetType().FullName +(Get-WmiObject -Query "Select * from Win32_Bios").GetType().FullName System.Management.ManagementObject +``` -USING THE [wmisearcher] TYPE ACCELERATOR +## USING THE [wmisearcher] TYPE ACCELERATOR -The [wmisearcher] type accelerator creates a -ManagementObjectSearcher object from a WQL -statement string. The ManagementObjectSearcher -object has many properties and methods, but the -most basic method is the Get method, which -invokes the specified WMI query and returns -the resulting objects. +The [wmisearcher] type accelerator creates a ManagementObjectSearcher object +from a WQL statement string. The ManagementObjectSearcher object has many +properties and methods, but the most basic method is the Get method, which +invokes the specified WMI query and returns the resulting objects. -By using the [wmisearcher], you gain easy access -to the ManagementObjectSearcher .NET Framework class. -This lets you query WMI and to configure the way -the query is conducted. +By using the [wmisearcher], you gain easy access to the +ManagementObjectSearcher .NET Framework class. This lets you query WMI and to +configure the way the query is conducted. To use the [wmisearcher] type accelerator: -1. Cast the WQL string into a ManagementObjectSearcher -object. -2. Call the Get method of the ManagementObjectSearcher -object. +1. Cast the WQL string into a ManagementObjectSearcher object. +2. Call the Get method of the ManagementObjectSearcher object. -For example, the following command casts the "select -all" query, saves the result in the $bios variable, -and then calls the Get method of the ManagementObjectSearcher -object in the $bios variable. +For example, the following command casts the "select all" query, saves the +result in the $bios variable, and then calls the Get method of the +ManagementObjectSearcher object in the $bios variable. -PS C:> $bios = [wmisearcher]"Select * from Win32_Bios" -PS C:> $bios.Get() +```powershell +$bios = [wmisearcher]"Select * from Win32_Bios" +$bios.Get() +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -NOTE: Only selected object properties are displayed -by default. These properties are defined in the -Types.ps1xml file. +NOTE: Only selected object properties are displayed by default. These +properties are defined in the Types.ps1xml file. -You can use the [wmisearcher] type accelerator to -cast the query or the variable. In the following -example, the [wmisearcher] type accelerator is -used to cast the variable. The result is the same. +You can use the [wmisearcher] type accelerator to cast the query or the +variable. In the following example, the [wmisearcher] type accelerator is used +to cast the variable. The result is the same. -PS C:> [wmisearcher]$bios = "Select * from Win32_Bios" -PS C:> $bios.Get() +```powershell +[wmisearcher]$bios = "Select * from Win32_Bios" +$bios.Get() +``` +```output SMBIOSBIOSVersion : 8BET56WW (1.36 ) Manufacturer : LENOVO Name : Default System BIOS SerialNumber : R9FPY3P Version : LENOVO - 1360 +``` -When you use the [wmisearcher] type accelerator, it -changes the query string into a ManagementObjectSearcher -object, as shown in the following commands. +When you use the [wmisearcher] type accelerator, it changes the query string +into a ManagementObjectSearcher object, as shown in the following commands. -PS C:> $a = "Select * from Win32_Bios" -PS C:> $a.GetType().FullName +``` +$a = "Select * from Win32_Bios" +$a.GetType().FullName System.String -PS C:> $a = [wmisearcher]"Select * from Win32_Bios" -PS C:> $a.GetType().FullName +$a = [wmisearcher]"Select * from Win32_Bios" +$a.GetType().FullName System.Management.ManagementObjectSearcher +``` -This command format works on any query. The following -command gets the value of the Name property of the -Win32_Bios WMI class. - -PS C:> $biosname = [wmisearcher]"Select Name from Win32_Bios" -PS C:> $biosname.Get() +This command format works on any query. The following command gets the value +of the Name property of the Win32_Bios WMI class. -# __GENUS : 2 +```powershell +$biosname = [wmisearcher]"Select Name from Win32_Bios" +$biosname.Get() +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS +``` -You can perform this operation in a single command, -although the command is a bit more difficult to -interpret. +You can perform this operation in a single command, although the command is a +bit more difficult to interpret. -In this format, you use the [wmisearcher] type -accelerator to cast the WQL query string to a -ManagementObjectSearcher, and then call the Get -method on the object -- all in a single command. -The parentheses () that enclose the casted string -direct Windows PowerShell to cast the string before -calling the method. +In this format, you use the [wmisearcher] type accelerator to cast the WQL +query string to a ManagementObjectSearcher, and then call the Get method on +the object -- all in a single command. The parentheses () that enclose the +casted string direct Windows PowerShell to cast the string before calling the +method. -PS C:> ([wmisearcher]"Select name from Win32_Bios").Get() - -# __GENUS : 2 +```powershell +([wmisearcher]"Select name from Win32_Bios").Get() +``` +```output +__GENUS : 2 __CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - +__SUPERCLASS : +__DYNASTY : +__RELPATH : +__PROPERTY_COUNT : 1 __DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - +__SERVER : +__NAMESPACE : +__PATH : Name : Default System BIOS +``` -# USING THE BASIC WQL WHERE STATEMENT - +## USING THE BASIC WQL WHERE STATEMENT -A Where statement establishes conditions -for the data that a Select statement returns. +A Where statement establishes conditions for the data that a Select statement +returns. The Where statement has the following format: +``` where +``` For example: +``` where Name = 'Notepad.exe' +``` -The Where statement is used with the Select -statement, as shown in the following example. +The Where statement is used with the Select statement, as shown in the +following example. +``` Select * from Win32_Process where Name = 'Notepad.exe' +``` -When using the Where statement, the property name -and value must be accurate. +When using the Where statement, the property name and value must be accurate. -For example, the following command gets the Notepad -processes on the local computer. +For example, the following command gets the Notepad processes on the local +computer. -PS C:> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad.exe'" +```powershell +Get-WmiObject -Query "Select * from Win32_Process where name='Notepad.exe'" +``` -However, the following command fails, because the -process name includes the ".exe" file name -extension. +However, the following command fails, because the process name includes the +".exe" file name extension. -PS C:> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad'" +```powershell +Get-WmiObject -Query "Select * from Win32_Process where name='Notepad'" +``` -# WHERE STATEMENT COMPARISON OPERATORS +## WHERE STATEMENT COMPARISON OPERATORS -The following operators are valid in a -WQL Where statement. +The following operators are valid in a WQL Where statement. +``` Operator Description ----------------------- = Equal @@ -398,334 +370,365 @@ LIKE Wildcard match IS Evaluates null ISNOT Evaluates not null ISA Evaluates a member of a WMI class +``` -There are other operators, but these are the ones -used for making comparisons. +There are other operators, but these are the ones used for making comparisons. -For example, the following query selects the Name -and Priority properties from processes in the -Win32_Process class where the process priority -is greater than or equal to 11. The Get-WmiObject -cmdlet runs the query. +For example, the following query selects the Name and Priority properties from +processes in the Win32_Process class where the process priority is greater +than or equal to 11. The Get-WmiObject cmdlet runs the query. -$highPriority = "Select Name, Priority from Win32_Process where Priority >= 11" +```powershell +$highPriority = "Select Name, Priority from Win32_Process " + + "where Priority >= 11" Get-WmiObject -Query $highPriority +``` -# USING THE WQL OPERATORS IN THE FILTER PARAMETER +## USING THE WQL OPERATORS IN THE FILTER PARAMETER +The WQL operators can also be used in the value of the Filter parameter of the +Get-WmiObject or Get-CimInstance cmdlets, as well as in the value of the Query +parameters of these cmdlets. -The WQL operators can also be used in the value -of the Filter parameter of the Get-WmiObject or -Get-CimInstance cmdlets, as well as in the value -of the Query parameters of these cmdlets. +For example, the following command gets the Name and ProcessID properties of +the last five processes that have ProcessID values greater than 1004. The +command uses the Filter parameter to specify the ProcessID condition. -For example, the following command gets the Name -and ProcessID properties of the last five processes -that have ProcessID values greater than 1004. The -command uses the Filter parameter to specify the -ProcessID condition. - -PS C:> Get-WmiObject -Class Win32_Process ` +```powershell +Get-WmiObject -Class Win32_Process ` -Property Name, ProcessID -Filter "ProcessID >= 1004" | Sort ProcessID | Select Name, ProcessID -Last 5 +``` +```output Name ProcessID ---- --------- SROSVC.exe 4220 -# WINWORD.EXE 4664 - +WINWORD.EXE 4664 TscHelp.exe 4744 SnagIt32.exe 4748 WmiPrvSE.exe 5056 +``` # USING THE LIKE OPERATOR -The Like operator lets you use wildcard characters -to filter the results of a WQL query. +The Like operator lets you use wildcard characters to filter the results of a +WQL query. +``` Like Operator Description -------------------------------------------------- [] Character in a range [a-f] or a set -of characters [abcdef]. The items in -a set do not need to be consecutive or -listed in alphabetical order. + of characters [abcdef]. The items in + a set do not need to be consecutive or + listed in alphabetical order. ^ Character not in a range [^a-f] or -not in a set [^abcdef]. The items in -a set do not need to be consecutive or -listed in alphabetical order. + not in a set [^abcdef]. The items in + a set do not need to be consecutive or + listed in alphabetical order. % A string of zero or more characters _ One character. -(underscore) NOTE: To use a literal underscore -in a query string, enclose it in -square brackets [_]. +(underscore) NOTE: To use a literal underscore + in a query string, enclose it in + square brackets [_]. +``` -When the Like operator is used without any wildcard -characters or range operators, it behaves like the -equality operator (=) and returns objects only +When the Like operator is used without any wildcard characters or range +operators, it behaves like the equality operator (=) and returns objects only when they are an exact match for the pattern. -You can combine the range operation with the percent -wildcard character to create simple, yet powerful -filters. +You can combine the range operation with the percent wildcard character to +create simple, yet powerful filters. -# LIKE OPERATOR EXAMPLES +### LIKE OPERATOR EXAMPLES +#### EXAMPLE 1: [] -EXAMPLE 1: [] -The following commands start Notepad and then -search for an instance of the Win32_Process -class that has a name that starts with a letter -between "H" and "N" (case-insensitive). +The following commands start Notepad and then search for an instance of the +Win32_Process class that has a name that starts with a letter between "H" and +"N" (case-insensitive). -The query should return any process from Hotpad.exe -through Notepad.exe. +The query should return any process from Hotpad.exe through Notepad.exe. -PS C:> Notepad # Starts Notepad -PS C:> $query = "Select * from win32_Process where Name LIKE '[H-N]otepad.exe'" -PS C:> Get-WmiObject -Query $query | Select Name, ProcessID +```powershell +Notepad # Starts Notepad +$query = "Select * from win32_Process where Name LIKE '[H-N]otepad.exe'" +Get-WmiObject -Query $query | Select Name, ProcessID +``` +```output Name ProcessID ---- --------- notepad.exe 1740 +``` + +#### EXAMPLE 2: [] and % -EXAMPLE 2: [] and % -The following commands select all process -that have a name that begins with a letter between -A and P (case-insensitive) followed by zero or more -letters in any combination. +The following commands select all process that have a name that begins with a +letter between A and P (case-insensitive) followed by zero or more letters in +any combination. -The Get-WmiObject cmdlet runs the query, the -Select-Object cmdlet gets the Name and ProcessID -properties, and the Sort-Object cmdlet sorts the -results in alphabetical order by name. +The Get-WmiObject cmdlet runs the query, the Select-Object cmdlet gets the +Name and ProcessID properties, and the Sort-Object cmdlet sorts the results in +alphabetical order by name. -PS C:> $query = "Select * from win32_Process where name LIKE '[A-P]%'" -PS C:> Get-WmiObject -Query $query | +```powershell +$query = "Select * from win32_Process where name LIKE '[A-P]%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID | Sort-Object -Property Name +``` -EXAMPLE 3: Not in Range (^) -The following command gets processes whose names -do not begin with any of the following letters: -# A, S, W, P, R, C, U, N +#### EXAMPLE 3: Not in Range (^) + +The following command gets processes whose names do not begin with any of the +following letters: A, S, W, P, R, C, U, N and followed zero or more letters. -PS C:> $query = "Select * from win32_Process where name LIKE '[^ASWPRCUN]%'" -PS C:> Get-WmiObject -Query $query | +```powershell +$query = "Select * from win32_Process where name LIKE '[^ASWPRCUN]%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID | Sort-Object -Property Name +``` + +#### EXAMPLE 4: Any characters -- or none (%) -EXAMPLE 4: Any characters -- or none (%) -The following commands get processes that have -names that begin with "calc". The % symbol in -WQL is equivalent to the asterisk (*) symbol in -regular expressions. +The following commands get processes that have names that begin with "calc". +The % symbol in WQL is equivalent to the asterisk (*) symbol in regular +expressions. -PS C:> $query = "Select * from win32_Process where Name LIKE 'calc%'" -PS C:> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +```powershell +$query = "Select * from win32_Process where Name LIKE 'calc%'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +``` +```output Name ProcessID ---- --------- calc.exe 4424 +``` -EXAMPLE 5: One character (_) -The following commands get processes that -have names that have the following pattern, -"c_lc.exe" where the underscore character -represents any one character. This pattern -matches any name from calc.exe through -czlc.exe, or c9lc.exe, but does not match -names in which the "c" and "l" are separated -by more than one character. +#### EXAMPLE 5: One character (_) -PS C:> $query = "Select * from Win32_Process where Name LIKE 'c_lc.exe'" -PS C:> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +The following commands get processes that have names that have the following +pattern, "c_lc.exe" where the underscore character represents any one +character. This pattern matches any name from calc.exe through czlc.exe, or +c9lc.exe, but does not match names in which the "c" and "l" are separated by +more than one character. +```powershell +$query = "Select * from Win32_Process where Name LIKE 'c_lc.exe'" +Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +``` + +```output Name ProcessID ---- --------- calc.exe 4424 +``` + +#### EXAMPLE 6: Exact match -EXAMPLE 6: Exact match -The following commands get processes named -WLIDSVC.exe. Even though the query uses the -Like keyword, it requires an exact match, -because the value does not include any -wildcard characters. +The following commands get processes named WLIDSVC.exe. Even though the query +uses the Like keyword, it requires an exact match, because the value does not +include any wildcard characters. +```powershell $query = "Select * from win32_Process where name LIKE 'WLIDSVC.exe'" Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID +```powershell +```output Name ProcessID ---- --------- WLIDSVC.exe 84 +``` -# USING THE OR OPERATOR +## USING THE OR OPERATOR -To specify multiple independent conditions, use the Or -keyword. The Or keyword appears in the Where clause. It -performs an inclusive OR operation on two (or more) -conditions and returns items that meet any of the -conditions. +To specify multiple independent conditions, use the Or keyword. The Or keyword +appears in the Where clause. It performs an inclusive OR operation on two (or +more) conditions and returns items that meet any of the conditions. The Or operator has the following format: +``` Where or ... +``` -For example, the following commands get all instances -of the Win32_Process WMI class but returns them -only if the process name is winword.exe or excel.exe. +For example, the following commands get all instances of the Win32_Process WMI +class but returns them only if the process name is winword.exe or excel.exe. -PS C:> $q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe'" -PS C:> Get-WmiObject -Query $q +```powershell +$q = "Select * from Win32_Process where Name='winword.exe'" + + " or Name='excel.exe'" +Get-WmiObject -Query $q +``` -The Or statement can be used with more than two -conditions. In the following query, the Or statement -gets Winword.exe, Excel.exe, or Powershell.exe. +The Or statement can be used with more than two conditions. In the following +query, the Or statement gets Winword.exe, Excel.exe, or Powershell.exe. -$q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe' or Name = 'powershell.exe'" +```powershell +$q = "Select * from Win32_Process where Name='winword.exe'" + + " or Name='excel.exe' or Name='powershell.exe'" +``` -# USING THE AND OPERATOR +## USING THE AND OPERATOR -To specify multiple related conditions, use the And -keyword. The And keyword appears in the Where clause. It -returns items that meet all of the conditions. +To specify multiple related conditions, use the And keyword. The And keyword +appears in the Where clause. It returns items that meet all of the conditions. The And operator has the following format: +``` Where and ... +``` -For example, the following commands get processes -that have a name of "Winword.exe" and the process -ID of 6512. +For example, the following commands get processes that have a name of +"Winword.exe" and the process ID of 6512. Note that the commands use the Get-CimInstance cmdlet. -PS C:> $q = "Select * from Win32_Process where Name = 'winword.exe' and ProcessID =6512" -PS C:> Get-CimInstance -Query $q - -ProcessId Name HandleCount WorkingSetSize VirtualSize ---------- ---- ----------- -------------- ----------- -# 6512 WINWORD.EXE 768 117170176 633028608 +```powershell +$q = "Select * from Win32_Process where Name = 'winword.exe' " + + "and ProcessID =6512" +Get-CimInstance -Query $q +``` +```output +ProcessId Name HandleCount WorkingSetSize VirtualSize +--------- ---- ----------- -------------- ----------- +# 6512 WINWORD.EXE 768 117170176 633028608 +``` -All operators, including the Like operators are -valid with the Or and And operators. And, you can -combine the Or and And operators in a single query -with parentheses that tell Windows PowerShell which -clauses to process first. +All operators, including the Like operators are valid with the Or and And +operators. And, you can combine the Or and And operators in a single query +with parentheses that tell Windows PowerShell which clauses to process first. -This command uses the Windows PowerShell continuation -character (`) divide the command into two lines. +This command uses the Windows PowerShell continuation character (`) divide the +command into two lines. -PS C:> $q = "Select * from Win32_Process ` +```powershell +$q = "Select * from Win32_Process ` where (Name = 'winword.exe' or Name = 'excel.exe') and HandleCount > 700" +Get-CimInstance -Query $q +``` -PS C:> Get-CimInstance -Query $q -ProcessId Name HandleCount WorkingSetSize VirtualSize ---------- ---- ----------- -------------- ----------- -# 6512 WINWORD.EXE 797 117268480 634425344 +```output +ProcessId Name HandleCount WorkingSetSize VirtualSize +--------- ---- ----------- -------------- ----------- + 6512 WINWORD.EXE 797 117268480 634425344 + 9610 EXCEL.EXE 727 38858752 323227648 +``` -# 9610 EXCEL.EXE 727 38858752 323227648 +## SEARCHING FOR NULL VALUES +Searching for null values in WMI is challenging, because it can lead to +unpredictable results. Null is not zero and it is not equivalent or to an +empty string. Some WMI class properties are initialized and others are not, so +a search for null might not work for all properties. -# SEARCHING FOR NULL VALUES +To search for null values, use the Is operator with a value of "null". -Searching for null values in WMI is challenging, -because it can lead to unpredictable results. Null -is not zero and it is not equivalent or to an empty -string. Some WMI class properties are initialized and -others are not, so a search for null might not work -for all properties. +For example, the following commands get processes that have a null value for +the IntallDate property. The commands return many processes. -To search for null values, use the Is operator with -a value of "null". +```powershell +$q = "Select * from Win32_Process where InstallDate is null" +Get-WmiObject -Query $q +``` -For example, the following commands get processes -that have a null value for the IntallDate property. -The commands return many processes. +In contrast, the following command, gets user accounts that have a null value +for the Description property. This command does not return any user accounts, +even though most user accounts do not have any value for the Description +property. -PS C:> $q = "Select * from Win32_Process where InstallDate is null" -PS C:> Get-WmiObject -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Description is null" +Get-WmiObject -Query $q +``` -In contrast, the following command, gets user -accounts that have a null value for the Description -property. This command does not return any user -accounts, even though most user accounts do not have -any value for the Description property. - -PS C:> $q = "Select * from Win32_UserAccount where Description is null" -PS C:> Get-WmiObject -Query $q - -To find the user accounts that have no value for -the Description property, use the equality operator -to get an empty string. To represent the empty string, +To find the user accounts that have no value for the Description property, use +the equality operator to get an empty string. To represent the empty string, use two consecutive single quotation marks. +```powershell $q = "Select * from Win32_UserAccount where Description = '' " +``` -# USING TRUE OR FALSE +## USING TRUE OR FALSE -To get Boolean values in the properties of WMI -objects, use True and False. They are not case -sensitive. +To get Boolean values in the properties of WMI objects, use True and False. +They are not case sensitive. -The following WQL query returns only local user -accounts from a domain joined computer. +The following WQL query returns only local user accounts from a domain joined +computer. -PS C:> $q = "Select * from Win32_UserAccount where LocalAccount = True" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where LocalAccount = True" +Get-CimInstance -Query $q +``` + +To find domain accounts, use a value of False, as shown in the following +example. -To find domain accounts, use a value of False, -as shown in the following example. +```powershell +$q = "Select * from Win32_UserAccount where LocalAccount = False" +Get-CimInstance -Query $q +``` -PS C:> $q = "Select * from Win32_UserAccount where LocalAccount = False" -PS C:> Get-CimInstance -Query $q +## USING THE ESCAPE CHARACTER -# USING THE ESCAPE CHARACTER +WQL uses the backslash (\) as its escape character. This is different from +Windows PowerShell, which uses the backtick character (`). -WQL uses the backslash () as its escape -character. This is different from Windows -PowerShell, which uses the backtick -character (`). +Quotation marks, and the characters used for quotation marks, often need to be +escaped so that they are not misinterpreted. -Quotation marks, and the characters used for -quotation marks, often need to be escaped so -that they are not misinterpreted. +To find a user whose name includes a single quotation mark, use a backslash to +escape the single quotation mark, as shown in the following command. -To find a user whose name includes a single quotation -mark, use a backslash to escape the single quotation -mark, as shown in the following command. +```powershell +$q = "Select * from Win32_UserAccount where Name = 'Tim O\'Brian'" +Get-CimInstance -Query $q +``` -PS C:> $q = "Select * from Win32_UserAccount where Name = 'Tim O\'Brian'" -PS C:> Get-CimInstance -Query $q +```output Name Caption AccountType SID Domain ---- ------- ----------- --- ------ Tim O'Brian FABRIKAM\TimO 512 S-1-5-21-1457... FABRIKAM +``` -In some case, the backslash also needs to be -escaped. For example, the following commands -generate an Invalid Query error due to the -backslash in the Caption value. +In some case, the backslash also needs to be escaped. For example, the +following commands generate an Invalid Query error due to the backslash in the +Caption value. -PS C:> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" +Get-CimInstance -Query $q +``` + +```output Get-CimInstance : Invalid query At line:1 char:1 + Get-CimInstance -Query $q -# +!INCLUDE[]~~~~~~~~~~~ - -+ CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimException -+ FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastructure.CimCmdlets ++ ~~~~~~~~~~~ + + CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimExcep + + FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastr +``` -To escape the backslash, use a second backslash -character, as shown in the following command. +To escape the backslash, use a second backslash character, as shown in the +following command. -PS C:> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" -PS C:> Get-CimInstance -Query $q +```powershell +$q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\\TimO'" +Get-CimInstance -Query $q +``` # SEE ALSO @@ -736,4 +739,3 @@ PS C:> Get-CimInstance -Query $q [about_WMI](about_WMI.md) [about_WMI_Cmdlets](about_WMI_Cmdlets.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md index 52e7e3216836..1c09f4504b20 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Windows_PowerShell_ISE.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,108 +7,104 @@ title: about_Windows_PowerShell_ISE --- # About Windows PowerShell ISE -## about_Windows_PowerShell_ISE - - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes the features and system requirements of Windows PowerShell Integrated Scripting Environment (ISE). -# LONG DESCRIPTION +## LONG DESCRIPTION -Windows PowerShell ISE is a graphical host application for Windows -PowerShell. In Windows PowerShell ISE, you can run commands and write, -test, and debug scripts in a single Windows-based graphical user -interface. Its features include Intellisense, multiline editing, tab -completion, auto-save, syntax coloring, selective execution, -context-sensitive help, Show Command (compose commands in a window) -and support for double-byte character sets and right-to-left languages. +Windows PowerShell ISE is a graphical host application for Windows PowerShell. +In Windows PowerShell ISE, you can run commands and write, test, and debug +scripts in a single Windows-based graphical user interface. Its features +include Intellisense, multiline editing, tab completion, auto-save, syntax +coloring, selective execution, context-sensitive help, Show Command (compose +commands in a window) and support for double-byte character sets and +right-to-left languages. -Windows PowerShell ISE is an excellent tool for beginners. The Show -Command window and New Remote PowerShell Tab guide you through tasks -so that you can be successful on the first try. Snippets and error -indicators help you learn the Windows PowerShell language as you work. +Windows PowerShell ISE is an excellent tool for beginners. The Show Command +window and New Remote PowerShell Tab guide you through tasks so that you can +be successful on the first try. Snippets and error indicators help you learn +the Windows PowerShell language as you work. -Advanced users can take advantage of the sophisticated debugging -features, add-ons, and the Windows PowerShell ISE object model. +Advanced users can take advantage of the sophisticated debugging features, +add-ons, and the Windows PowerShell ISE object model. What's New in Windows PowerShell ISE in Windows PowerShell 4.0 -Windows PowerShell ISE introduces two new features in Windows -PowerShell 4.0. +Windows PowerShell ISE introduces two new features in Windows PowerShell 4.0. --- Windows PowerShell ISE now supports both Windows PowerShell -Workflow debugging and remote script debugging. For more -Information, see about_Debuggers. --- IntelliSense support has been added for Windows PowerShell Desired -State Configuration providers and configurations. +- Windows PowerShell ISE now supports both Windows PowerShell Workflow + debugging and remote script debugging. For more Information, see + about_Debuggers. -Starting Windows PowerShell ISE +- IntelliSense support has been added for Windows PowerShell Desired State + Configuration providers and configurations. + +## Starting Windows PowerShell ISE Windows PowerShell ISE is installed, enabled, and ready to use in all supported versions of Windows. -- In Windows 8.1, Windows 8, Windows Server 2012 R2, and Windows Server -2012, on the Start screen, type PowerShell_ISE, and then click -PowerShell_ISE or Windows PowerShell ISE. +- In Windows 8.1, Windows 8, Windows Server 2012 R2, and Windows Server 2012, + on the Start screen, type PowerShell_ISE, and then click PowerShell_ISE or + Windows PowerShell ISE. -- In Windows Server 2012 R2 and Windows Server 2012, in Server Manager, -on the Tools menu, click Windows PowerShell ISE. +- In Windows Server 2012 R2 and Windows Server 2012, in Server Manager, on the + Tools menu, click Windows PowerShell ISE. - In earlier versions of Windows, click Start, All Programs, Accessories, -Windows PowerShell, and then click Windows PowerShell ISE. + Windows PowerShell, and then click Windows PowerShell ISE. -- In a Windows PowerShell console, Cmd.exe, or the Run or Search box -in Windows, type "PowerShell_ise.exe". You can also use the command-line -parameters, including the NoProfile switch. For more information, see -PowerShell_ISE.exe Console Help -(http://go.microsoft.com/fwlink/?LinkId=243055). +- In a Windows PowerShell console, Cmd.exe, or the Run or Search box in + Windows, type "PowerShell_ise.exe". You can also use the command-line + parameters, including the NoProfile switch. For more information, see + [PowerShell_ISE.exe Console Help](http://go.microsoft.com/fwlink/?LinkId=243055). -Running Interactive Commands +## Running Interactive Commands -You can run any Windows PowerShell expression or command in Windows -PowerShell ISE. You can use cmdlets, providers, snap-ins, and modules as -you would use them in the Windows PowerShell console. +You can run any Windows PowerShell expression or command in Windows PowerShell +ISE. You can use cmdlets, providers, snap-ins, and modules as you would use +them in the Windows PowerShell console. You can type or paste interactive commands in the Console pane. To run the commands, you can use buttons, menu items, and keyboard shortcuts. -You can use the multiline editing feature to type or paste several lines -of code into the Console pane at once. When you press the UP ARROW key to -recall the previous command, all the lines in the command are recalled. -When you type commands, press SHIFT+ENTER to make a new blank line appear -under the current line. +You can use the multiline editing feature to type or paste several lines of +code into the Console pane at once. When you press the UP ARROW key to recall +the previous command, all the lines in the command are recalled. When you type +commands, press SHIFT+ENTER to make a new blank line appear under the current +line. -Viewing Output +## Viewing Output -The results of commands and scripts are displayed in the Console pane. You -can move or copy the results from the Console pane by using keyboard -shortcuts or the Copy button on the toolbar, and you can paste the results -in the Script pane or Console panes or other programs. To clear the Console -pane, click the "Clear Output Pane" button or type one of the following -commands: +The results of commands and scripts are displayed in the Console pane. You can +move or copy the results from the Console pane by using keyboard shortcuts or +the Copy button on the toolbar, and you can paste the results in the Script +pane or Console panes or other programs. To clear the Console pane, click the +"Clear Output Pane" button or type one of the following commands: +``` Clear-Host cls +``` -Writing Scripts and Functions +## Writing Scripts and Functions -In the Script pane, you can open, compose, edit, and run scripts. The -Script pane lets you edit scripts by using buttons and keyboard shortcuts. -You can also copy, cut, and paste text between the Script pane and the -Console pane. +In the Script pane, you can open, compose, edit, and run scripts. The Script +pane lets you edit scripts by using buttons and keyboard shortcuts. You can +also copy, cut, and paste text between the Script pane and the Console pane. -You can use the selective run feature to run all or part of a script. To -run part of a script, select the text you want to run, and then click the -Run Selection button or press F8. By default, F8 runs the current line. +You can use the selective run feature to run all or part of a script. To run +part of a script, select the text you want to run, and then click the Run +Selection button or press F8. By default, F8 runs the current line. Advanced editing features include brace-matching, expand-collapse, line numbers, error indicators, block editing and indenting, rich copy, and case conversion. -Getting Help +## Getting Help Windows PowerShell ISE includes help topics that describe its use. In addition, all installed help files are accessible from the Script and Command @@ -116,101 +112,99 @@ panes. Windows PowerShell ISE also supports context-sensitive help. To get help about a particular cmdlet, provider, or keyword, place the cursor in the name of the -item and press F1. To search the help topics, press F1 and type the search term. +item and press F1. To search the help topics, press F1 and type the search +term. To update the help topics on the computer, use the Update Windows PowerShell -Help item in the Help menu. This item updates help for the modules in the current -session in the current UI culture. It is equivalent to running the Update-Help -cmdlet without parameters. To update help for the cmdlets that come with Windows -PowerShell, start Windows PowerShell ISE with the "Run as administrator" option. +Help item in the Help menu. This item updates help for the modules in the +current session in the current UI culture. It is equivalent to running the +Update-Help cmdlet without parameters. To update help for the cmdlets that +come with Windows PowerShell, start Windows PowerShell ISE with the "Run as +administrator" option. You can also use the Get-Help, Save-Help, and Update-Help cmdlets in Windows PowerShell ISE, just as you use it in the Windows PowerShell console. However, in Windows PowerShell ISE, the Help function displays the entire help topic, -not one page at a time. +not one page at a time. -Debugging Scripts +## Debugging Scripts -You can use the Windows PowerShell ISE debugger to debug a Windows -PowerShell script or function. When you debug a script, you can use menu -items and shortcut keys to perform many of the same tasks that you would -perform in the Windows PowerShell console. For example, to set a line -breakpoint in a script, right-click the line of code, and then click -Toggle Breakpoint. +You can use the Windows PowerShell ISE debugger to debug a Windows PowerShell +script or function. When you debug a script, you can use menu items and +shortcut keys to perform many of the same tasks that you would perform in the +Windows PowerShell console. For example, to set a line breakpoint in a script, +right-click the line of code, and then click Toggle Breakpoint. -As you step through a script while debugging, the debugging highlighter -shows precisely which part of the command is running and automatically -opens files that include called functions and scripts. +As you step through a script while debugging, the debugging highlighter shows +precisely which part of the command is running and automatically opens files +that include called functions and scripts. -By default, the Toggle Breakpoint menu item sets a breakpoint on an -entire line in a script, but you can set a breakpoint on a variable -or command name. You can also set a breakpoint on a command by line -and column number, making it easier to debug long pipeline commands. +By default, the Toggle Breakpoint menu item sets a breakpoint on an entire +line in a script, but you can set a breakpoint on a variable or command name. +You can also set a breakpoint on a command by line and column number, making +it easier to debug long pipeline commands. -Often, you can debug syntax errors in a script just by opening the -script file in Windows PowerShell ISE. The error indicators identify -syntax errors and the outlining features let you collapse parts of the -script to focus on trouble spots. +Often, you can debug syntax errors in a script just by opening the script file +in Windows PowerShell ISE. The error indicators identify syntax errors and the +outlining features let you collapse parts of the script to focus on trouble +spots. -You can also use the Windows PowerShell debugger cmdlets in the Command -pane just as you would use them in the console. +You can also use the Windows PowerShell debugger cmdlets in the Command pane +just as you would use them in the console. -Running Remote Commands +## Running Remote Commands -The New Remote PowerShell Tab feature makes it easy to establish a -persistent user-managed Windows PowerShell session ("PSSession") to -the local computer or a remote computer. The command opens a pop-up -window that prompts you for a computer name and for the user account -that has permission to run commands on the remote computer. +The New Remote PowerShell Tab feature makes it easy to establish a persistent +user-managed Windows PowerShell session ("PSSession") to the local computer or +a remote computer. The command opens a pop-up window that prompts you for a +computer name and for the user account that has permission to run commands on +the remote computer. -Customizing the View +## Customizing the View -You can use Windows PowerShell ISE features to move and to resize the -Console pane and the Script pane. You can show and hide either pane, -and you can change the text size in all the panes. +You can use Windows PowerShell ISE features to move and to resize the Console +pane and the Script pane. You can show and hide either pane, and you can +change the text size in all the panes. -You can also use the Options window to customize the appearance and -operation of Windows PowerShell ISE. In addition, Windows PowerShell -ISE has a custom host variable, $psISE, that you can use to customize -Windows PowerShell ISE, including adding menus and menu items. +You can also use the Options window to customize the appearance and operation +of Windows PowerShell ISE. In addition, Windows PowerShell ISE has a custom +host variable, $psISE, that you can use to customize Windows PowerShell ISE, +including adding menus and menu items. -Windows PowerShell ISE Profile +## Windows PowerShell ISE Profile Windows PowerShell ISE has its own Windows PowerShell profile, -Microsoft.PowerShellISE_profile.ps1. In this profile, you can store -functions, aliases, variables, and commands that you use in Windows -PowerShell ISE. +Microsoft.PowerShellISE_profile.ps1. In this profile, you can store functions, +aliases, variables, and commands that you use in Windows PowerShell ISE. -Items in the Windows PowerShell AllHosts profiles (CurrentUser\AllHosts -and AllUsers\AllHosts) are also available in Windows PowerShell ISE, just -as they are in any Windows PowerShell host program. However, the items -in your Windows PowerShell console profiles are not available in Windows -PowerShell ISE. +Items in the Windows PowerShell AllHosts profiles (CurrentUser\\AllHosts and +AllUsers\\AllHosts) are also available in Windows PowerShell ISE, just as they +are in any Windows PowerShell host program. However, the items in your Windows +PowerShell console profiles are not available in Windows PowerShell ISE. Instructions for moving and reconfiguring your profiles are available in Windows PowerShell ISE Help and in about_Profiles. -# NOTES +## NOTES -Windows PowerShell ISE is an optional Windows Feature that is turned on -by default on client and server versions of Windows. To enable and disable +Windows PowerShell ISE is an optional Windows Feature that is turned on by +default on client and server versions of Windows. To enable and disable Windows PowerShell ISE in client versions of Windows, use Turn Windows -Features On or Off in Control Panel. To enable and disable Windows -PowerShell ISE in server versions of Windows, use the Add Roles -and Features Wizard in Server Manager. - -Because Windows PowerShell ISE requires a user interface, it does not work -on Server Core installations of Windows Server. However, if you add the -Windows PowerShell ISE feature, the installation automatically converts -to Server with a GUI. - -Windows PowerShell ISE is built on the Windows Presentation Foundation -(WPF). If the graphical elements of Windows PowerShell ISE do not render -correctly on your system, you might resolve the problem by adding or -adjusting the "Disable WPF Hardware acceleration" graphics rendering -settings on your system. For more information, see "Graphics Rendering -Registry Settings" in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=144711. +Features On or Off in Control Panel. To enable and disable Windows PowerShell +ISE in server versions of Windows, use the Add Roles and Features Wizard in +Server Manager. + +Because Windows PowerShell ISE requires a user interface, it does not work on +Server Core installations of Windows Server. However, if you add the Windows +PowerShell ISE feature, the installation automatically converts to Server with +a GUI. + +Windows PowerShell ISE is built on the Windows Presentation Foundation (WPF). +If the graphical elements of Windows PowerShell ISE do not render correctly on +your system, you might resolve the problem by adding or adjusting the "Disable +WPF Hardware acceleration" graphics rendering settings on your system. For +more information, see [Graphics Rendering Registry Settings](http://go.microsoft.com/fwlink/?LinkId=144711) +in the MSDN library. # SEE ALSO @@ -220,17 +214,16 @@ http://go.microsoft.com/fwlink/?LinkId=144711. [about_Updatable_Help](about_Updatable_Help.md) -Get-Help - -Get-IseSnippet +[Get-Help](../Get-Help.md) -Import-IseSnippet +[Get-IseSnippet](../../ISE/Get-IseSnippet.md) -New-IseSnippet +[Import-IseSnippet](../../ISE/Import-IseSnippet.md) -Save-Help +[New-IseSnippet](../../ISE/New-IseSnippet.md) -Show-Command +[Save-Help](../Save-Help.md) -Update-Help +[Show-Command](../../Microsoft.PowerShell.Utility/Show-Command.md) +[Update-Help](../Update-Help.md) \ No newline at end of file diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Windows_RT.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Windows_RT.md index 848859487fe3..26c1585936bf 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Windows_RT.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Windows_RT.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,35 +7,60 @@ title: about_Windows_RT --- # About Windows RT -## about_Windows_RT - ## SHORT DESCRIPTION -Explains limitations of Windows PowerShell 4.0 on Windows RT 8.1. +Explains limitations of Windows PowerShell® 4.0 on Windows RT 8.1. ## LONG DESCRIPTION -The Windows RT 8.1 operating system is installed on computers and devices (such as Microsoft Surface 2, on which it is the operating system that ships with the computer) that use Advanced RISC Machine (ARM) processors. -Windows PowerShell 4.0 is included in Windows RT 8.1. All cmdlets, providers, and modules, and most scripts designed for Windows PowerShell 2.0 and later releases run on Windows RT 8.1 without changes. +The Windows RT 8.1 operating system is installed on computers and devices +(such as Microsoft Surface 2, on which it is the operating system that ships +with the computer) that use Advanced RISC Machine (ARM) processors. + +Windows PowerShell 4.0 is included in Windows RT 8.1. All cmdlets, providers, +and modules, and most scripts designed for Windows PowerShell 2.0 and later +releases run on Windows RT 8.1 without changes. -Because Windows RT 8.1 does not include all Windows features, some Windows PowerShell features work differently or do not work on Windows RT-based devices. The following list explains the differences. +Because Windows RT 8.1 does not include all Windows features, some Windows +PowerShell features work differently or do not work on Windows RT-based +devices. The following list explains the differences. --- Windows PowerShell ISE is not included in and cannot run on Windows RT 8.1. Windows PowerShell ISE requires Windows Presentation Foundation, which is not included in Windows RT 8.1. +- Windows PowerShell ISE is not included in and cannot run on Windows RT 8.1. + Windows PowerShell ISE requires Windows Presentation Foundation, which is not + included in Windows RT 8.1. --- Windows PowerShell remoting and the WinRM service are disabled by default. To enable remoting, run the Enable-PSRemoting cmdlet. Also, run the Set-Service cmdlet to set the startup type of the WinRM service to Automatic, or Automatic (Delayed Start). +- Windows PowerShell remoting and the WinRM service are disabled by default. + To enable remoting, run the Enable-PSRemoting cmdlet. Also, run the + Set-Service cmdlet to set the startup type of the WinRM service to Automatic, + or Automatic (Delayed Start). -While remoting is disabled, you can use Windows PowerShell remoting to run commands on other computers, but other computers cannot run commands on the Windows RT device. Also, implicit remoting—that is, remoting that is built in to a cmdlet or script, and not explicitly requested with added parameters—does not work in Windows PowerShell running on Windows RT 8.1. + While remoting is disabled, you can use Windows PowerShell remoting to run + commands on other computers, but other computers cannot run commands on the + Windows RT device. Also, implicit remoting—that is, remoting that is built in + to a cmdlet or script, and not explicitly requested with added parameters—does + not work in Windows PowerShell running on Windows RT 8.1. --- Domain-joined computing and Kerberos authentication are not supported on Windows RT 8.1. You cannot use Windows PowerShell to add or manage these features. +- Domain-joined computing and Kerberos authentication are not supported on + Windows RT 8.1. You cannot use Windows PowerShell to add or manage these + features. --- Microsoft .NET Framework classes that are not supported on Windows RT 8.1 are also not supported by Windows PowerShell on Windows RT 8.1. +- Microsoft .NET Framework classes that are not supported on Windows RT 8.1 + are also not supported by Windows PowerShell on Windows RT 8.1. --- Transactions are not enabled on Windows RT 8.1. Transaction cmdlets, such as Start-Transaction, and transaction parameters, such as UseTransaction, do not work properly. +- Transactions are not enabled on Windows RT 8.1. Transaction cmdlets, such + as Start-Transaction, and transaction parameters, such as UseTransaction, do + not work properly. --- All Windows PowerShell sessions on Windows RT 8.1 devices use the ConstrainedLanguage language mode. ConstrainedLanguage language mode is a companion to User Mode Code Integrity (UMCI). It permits all Windows cmdlets and Windows PowerShell language elements, but restricts types to ensure that users cannot use Windows PowerShell to circumvent or violate the UMCI protections. +- All Windows PowerShell sessions on Windows RT 8.1 devices use the + ConstrainedLanguage language mode. ConstrainedLanguage language mode is a + companion to User Mode Code Integrity (UMCI). It permits all Windows cmdlets + and Windows PowerShell language elements, but restricts types to ensure that + users cannot use Windows PowerShell to circumvent or violate the UMCI + protections. -For more information about ConstrainedLanguage language mode, see about_Language_Modes. +For more information about ConstrainedLanguage language mode, see +[about_Language_Modes](about_Language_Modes.md). ## SEE ALSO @@ -44,11 +69,3 @@ For more information about ConstrainedLanguage language mode, see about_Language [about_Remote](about_Remote.md) [about_Windows_PowerShell_ISE](about_Windows_PowerShell_ISE.md) - -about_Workflows - -Windows PowerShell System Requirements: (http://technet.microsoft.com/library/hh857337.aspx) - -## KEYWORDS -about_ARM, about_PowerShell_on_ARM, about_PowerShell_on_Surface, about_Windows_RT_8.1 about_WindowsRT - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md index 8322188c9328..986f4d855fbc 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,158 +7,166 @@ title: about_DesiredStateConfiguration --- # about_DesiredStateConfiguration -``` -TOPIC - about_Desired_State_Configuration - -SHORT DESCRIPTION - Provides a brief introduction to the Windows - PowerShell Desired State Configuration (DSC) feature. - -LONG DESCRIPTION - DSC is a management platform in Windows PowerShell that enables deploying - and managing configuration data for software services, and managing the - environment in which these services run. - - DSC provides a set of Windows PowerShell language extensions, - new cmdlets, and resources that you can use to declaratively specify - how you want the state of your software environment to be configured. It - also provides a means to maintain and manage existing configurations. - - DSC is introduced in Windows PowerShell 4.0. - - For detailed information about DSC, see - "Windows PowerShell Desired State Configuration Overview" in the TechNet - Library at http://go.microsoft.com/fwlink/?LinkId=311940. - -DEVELOPING DSC RESOURCES WITH CLASSES - Starting in Windows PowerShell 5.0, you can develop DSC resources by using - classes. For more information, see about_Classes, and "Writing a custom - DSC resource with PowerShell classes" on Microsoft TechNet - (http://technet.microsoft.com/library/dn948461.aspx). - -USING DSC - To use DSC to configure your environment, first define a Windows - PowerShell script block using the Configuration keyword, followed by an - identifier, which is in turn followed by the pair of curly braces delimiting - the block. Inside the configuration block you can define node blocks that - specify the desired configuration state for each node (computer) in the - environment. A node block starts with the Node keyword, followed by the name - of the target computer, which can be a variable. After the computer name, come - the curly braces that delimit the node block. Inside the node block, you can - define resource blocks to configure specific resources. A resource block starts - with the type name of the resource, followed by the identifier you want to - specify for that block, followed by the curly braces that delimit the block, - as shown in the following example. - - Configuration MyWebConfig - { - # Parameters are optional - param ($MachineName, $WebsiteFilePath) - - # A Configuration block can have one or more Node blocks - Node $MachineName - { - # Next, specify one or more resource blocks - # WindowsFeature is one of the resources you can use in a Node block - # This example ensures the Web Server (IIS) role is installed - WindowsFeature IIS - { - # To ensure that the role is not installed, set Ensure to "Absent" - Ensure = "Present" - Name = "Web-Server" # Use the Name property from Get-WindowsFeature - } - - # You can use the File resource to create files and folders - # "WebDirectory" is the name you want to use to refer to this instance - File WebDirectory - { - Ensure = "Present" # You can also set Ensure to "Absent“ - Type = "Directory“ # Default is “File” - Recurse = $true - SourcePath = $WebsiteFilePath - DestinationPath = "C:\inetpub\wwwroot" - - # Ensure that the IIS block is successfully run first before - # configuring this resource - Requires = "[WindowsFeature]IIS" # Use Requires for dependencies - } - } - } - - To create a configuration, invoke the Configuration block the same way you would - invoke a Windows PowerShell function, passing in any expected parameters you may - have defined (two in the example above). For example, in this case: - - MyWebConfig -MachineName "TestMachine" –WebsiteFilePath "\\filesrv\WebFiles" ` - -OutputPath "C:\Windows\system32\temp" # OutputPath is optional - - This generates a MOF file per node at the path you specify. These MOF files specify - the desired configuration for each node. Next, use the following cmdlet to parse the - configuration MOF files, send each node its corresponding configuration, and enact - those configurations. Note that you do not need to create a separate MOF file for - class-based DSC resources. - - Start-DscConfiguration –Verbose -Wait -Path "C:\Windows\system32\temp" - -USING DSC TO MAINTAIN CONFIGURATION STATE - With DSC, configuration is idempotent. This means that if you use DSC to enact the - same configuration more than once, the resulting configuration state will always - be the same. Because of this, if you suspect that any nodes in your environment - may have drifted from the desired state of configuration, you can enact the same - DSC configuration again to bring them back to the desired state. You do not need - to modify the configuration script to address only those resources whose state has - drifted from the desired state. - - The following example shows how you can verify whether the actual state of - configuration on a given node has drifted from the last DSC configuration enacted - on the node. In this example we are checking the configuration of the local computer. - - $session = New-CimSession -ComputerName "localhost" - Test-DscConfiguration -CimSession $session - -BUILT-IN DSC RESOURCES - You can use the following built-in resources in your configuration scripts: - - Name Properties - ---- ---------- - File {DestinationPath, Attributes, Checksum, Contents...} - Archive {Destination, Path, Checksum, Credential...} - Environment {Name, DependsOn, Ensure, Path...} - Group {GroupName, Credential, DependsOn, Description...} - Log {Message, DependsOn, PsDscRunAsCredential} - Package {Name, Path, ProductId, Arguments...} - Registry {Key, ValueName, DependsOn, Ensure...} - Script {GetScript, SetScript, TestScript, Credential...} - Service {Name, BuiltInAccount, Credential, Dependencies...} - User {UserName, DependsOn, Description, Disabled...} - WaitForAll {NodeName, ResourceName, DependsOn, PsDscRunAsCredential...} - WaitForAny {NodeName, ResourceName, DependsOn, PsDscRunAsCredential...} - WaitForSome {NodeCount, NodeName, ResourceName, DependsOn...} - WindowsFeature {Name, Credential, DependsOn, Ensure...} - WindowsOptionalFeature {Name, DependsOn, Ensure, LogLevel...} - WindowsProcess {Arguments, Path, Credential, DependsOn...} - - To get a list of available DSC resources on your system, run the - Get-DscResource cmdlet. - - The example in this topic demonstrates how to use the File and WindowsFeature - resources. To see all properties that you can use with a resource, insert the - cursor in the resource keyword (for example, File) within your configuration - script in Windows PowerShell ISE, hold down CTRL, and then press SPACEBAR. - -FIND MORE RESOURCES - You can download, install, and learn about many other available DSC resources that - have been created by the PowerShell and DSC user community, and by Microsoft. - Visit the [PowerShell Gallery](https://www.powershellgallery.com/) to browse and learn - about available DSC resources. - -SEE ALSO - "Windows PowerShell Desired State Configuration Overview" - (http://go.microsoft.com/fwlink/?LinkId=311940) - "Built-In Windows PowerShell Desired State Configuration Resources" - (http://technet.microsoft.com/library/dn249921.aspx) - "Build Custom Windows PowerShell Desired State Configuration Resources" - (http://technet.microsoft.com/library/dn249927.aspx) + +## SHORT DESCRIPTION + +Provides a brief introduction to the PowerShell Desired State +Configuration (DSC) feature. + +## LONG DESCRIPTION + +DSC is a management platform in PowerShell that enables deploying and managing +configuration data for software services, and managing the environment in +which these services run. + +DSC provides a set of PowerShell language extensions, new cmdlets, and +resources that you can use to declaratively specify how you want the state of +your software environment to be configured. It also provides a means to +maintain and manage existing configurations. + +DSC is introduced in PowerShell 4.0. + +For detailed information about DSC, see +[PowerShell Desired State Configuration Overview](http://go.microsoft.com/fwlink/?LinkId=311940) +in the TechNet Library. + +## DEVELOPING DSC RESOURCES WITH CLASSES + +Starting in PowerShell 5.0, you can develop DSC resources by using classes. +For more information, see [about_Classes](about_Classes.md), and +[Writing a custom DSC resource with PowerShell classes](http://technet.microsoft.com/library/dn948461.aspx) +on Microsoft TechNet. + +## USING DSC + +To use DSC to configure your environment, first define a PowerShell +script block using the Configuration keyword, followed by an identifier, which +is in turn followed by the pair of curly braces delimiting the block. Inside +the configuration block you can define node blocks that specify the desired +configuration state for each node (computer) in the environment. A node block +starts with the Node keyword, followed by the name of the target computer, +which can be a variable. After the computer name, come the curly braces that +delimit the node block. Inside the node block, you can define resource blocks +to configure specific resources. A resource block starts with the type name of +the resource, followed by the identifier you want to specify for that block, +followed by the curly braces that delimit the block, as shown in the following +example. Configuration MyWebConfig { # Parameters are optional param +($MachineName, $WebsiteFilePath) + +```powershell +# A Configuration block can have one or more Node blocks +Node $MachineName +{ + # Next, specify one or more resource blocks + # WindowsFeature is one of the resources you can use in a Node block + # This example ensures the Web Server (IIS) role is installed + WindowsFeature IIS + { + # To ensure that the role is not installed, set Ensure to "Absent" + Ensure = "Present" + Name = "Web-Server" # Use the Name property from Get-WindowsFeature + } + + # You can use the File resource to create files and folders + # "WebDirectory" is the name you want to use to refer to this instance + File WebDirectory + { + Ensure = "Present" # You can also set Ensure to "Absent“ + Type = "Directory“ # Default is “File” + Recurse = $true + SourcePath = $WebsiteFilePath + DestinationPath = "C:\inetpub\wwwroot" + + # Ensure that the IIS block is successfully run first before + # configuring this resource + Requires = "[WindowsFeature]IIS" # Use Requires for dependencies + } +} +} ``` +To create a configuration, invoke the Configuration block the same way you +would invoke a PowerShell function, passing in any expected parameters you may +have defined (two in the example above). For example, in this case: + +```powershell +MyWebConfig -MachineName "TestMachine" –WebsiteFilePath ` + "\\filesrv\WebFiles" -OutputPath "C:\Windows\system32\temp" +# OutputPath is optional +``` + +This generates a MOF file per node at the path you specify. These MOF files +specify the desired configuration for each node. Next, use the following +cmdlet to parse the configuration MOF files, send each node its corresponding +configuration, and enact those configurations. Note that you do not need to +create a separate MOF file for class-based DSC resources. + +```powershell +Start-DscConfiguration –Verbose -Wait -Path "C:\Windows\system32\temp" +``` + +## USING DSC TO MAINTAIN CONFIGURATION STATE + +With DSC, configuration is idempotent. This means that if you use DSC to enact +the same configuration more than once, the resulting configuration state will +always be the same. Because of this, if you suspect that any nodes in your +environment may have drifted from the desired state of configuration, you can +enact the same DSC configuration again to bring them back to the desired +state. You do not need to modify the configuration script to address only +those resources whose state has drifted from the desired state. + +The following example shows how you can verify whether the actual state of +configuration on a given node has drifted from the last DSC configuration +enacted on the node. In this example we are checking the configuration of the +local computer. + +```powershell +$session = New-CimSession -ComputerName "localhost" +Test-DscConfiguration -CimSession $session +``` + +## BUILT-IN DSC RESOURCES + +You can use the following built-in resources in your configuration scripts: + +|Name |Properties | +|----------------------|---------------------------------------------------| +|File |{DestinationPath, Attributes, Checksum, Content...}| +|Archive |{Destination, Path, Checksum, Credential...} | +|Environment |{Name, DependsOn, Ensure, Path...} | +|Group |{GroupName, Credential, DependsOn, Description...} | +|Log |{Message, DependsOn, PsDscRunAsCredential} | +|Package |{Name, Path, ProductId, Arguments...} | +|Registry |{Key, ValueName, DependsOn, Ensure...} | +|Script |{GetScript, SetScript, TestScript, Credential...} | +|Service |{Name, BuiltInAccount, Credential, Dependencies...}| +|User |{UserName, DependsOn, Description, Disabled...} | +|WaitForAll |{NodeName, ResourceName, DependsOn, PsDscRunAsC...}| +|WaitForAny |{NodeName, ResourceName, DependsOn, PsDscRunAsC...}| +|WaitForSome |{NodeCount, NodeName, ResourceName, DependsOn...} | +|WindowsFeature |{Name, Credential, DependsOn, Ensure...} | +|WindowsOptionalFeature|{Name, DependsOn, Ensure, LogLevel...} | +|WindowsProcess |{Arguments, Path, Credential, DependsOn...} | + +To get a list of available DSC resources on your system, run the +Get-DscResource cmdlet. + +The example in this topic demonstrates how to use the File and WindowsFeature +resources. To see all properties that you can use with a resource, insert the +cursor in the resource keyword (for example, File) within your configuration +script in PowerShell ISE, hold down CTRL, and then press SPACEBAR. + +## FIND MORE RESOURCES + +You can download, install, and learn about many other available DSC resources +that have been created by the PowerShell and DSC user community, and by +Microsoft. Visit the [PowerShell Gallery](https://www.powershellgallery.com/) +to browse and learn about available DSC resources. + +## SEE ALSO + +[PowerShell Desired State Configuration Overview](/powershell/dsc/overview) + +[Built-In PowerShell Desired State Configuration Resources](/powershell/dsc/builtinresource) + +[Build Custom PowerShell Desired State Configuration Resources](/powershell/dsc/authoringResource) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_dsclogresource.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_dsclogresource.md index d36402cd23c9..2c3c38df824b 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_dsclogresource.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_dsclogresource.md @@ -7,19 +7,12 @@ title: about_DSCLogResource --- # about_DSCLogResource -``` -TOPIC - about_DSCLogResource - -SHORT DESCRIPTION - Provides a brief introduction to the Windows - PowerShell Desired State Configuration (DSC) Log Resource. - -LONG DESCRIPTION - - ABOUT THE DSC LOG RESOURCE - - HOW TO USE THE DSC LOG RESOURCE - -``` +## SHORT DESCRIPTION + +Provides a brief introduction to the PowerShell Desired State Configuration +(DSC) Log Resource. LONG DESCRIPTION + +## LONG DESCRIPTION + +## HOW TO USE THE DSC LOG RESOURCE diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_hidden.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_hidden.md index 1cb2645eeec1..50b1758d40d5 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_hidden.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_hidden.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,122 +7,148 @@ title: about_Hidden --- # about_Hidden -## TOPIC - about\_Hidden - -## SHORT DESCRIPTION - Describes the Hidden keyword, which hides class members from default Get\-Member results. - -## LONG DESCRIPTION - When you use the Hidden keyword in a script, you hide the members of a class by default. The Hidden keyword can hide properties, methods \(including constructors, events, alias properties, and other member types, including static members, from the default results of the Get\-Member cmdlet, and from IntelliSense and tab completion results. To display members that you have hidden with the Hidden keyword, add the \-Force parameter to a Get\-Member command. - - Hidden members are not displayed by using tab completion or IntelliSense, unless the completion occurs in the class that defines the hidden member. - - A new attribute, System.Management.Automation.HiddenAttribute, has been added, so that C\# code can have the same semantics within Windows PowerShell. - - The Hidden keyword is useful for creating properties and methods within a class that you do not necessarily want other users of the class to see, or readily be able to edit. - - The Hidden keyword has no effect on how you can view or make changes to members of a class. Like all language keywords in Windows PowerShell, Hidden is not case\-sensitive, and hidden members are still public. - - Hidden, along with custom classes, was introduced in Windows PowerShell 5.0. - -## EXAMPLE - The following example shows how to use the Hidden keyword in a class definition. The Car class method, Drive, has a property, rides, that does not need to be viewed or changed \(it merely tallies the number of times that Drive is called on the Car class, a metric that is not important to users of the class; consider, for example, that when you are buying a car, you do not ask the seller on how many drives the car has been taken\). - - Because there is little need for users of the class to change this property, we can hide the property from Get\-Member and automatic completion results by using the Hidden keyword. - - Add the Hidden keyword by entering it on the same statement line as the property and its data type. Although the keyword can be in any order on this line, starting the statement with the Hidden keyword makes it easier for you later to identify all members that you have hidden. - -``` -class Car -{ - # Properties - [String] $Color - [String] $ModelYear - [int] $Distance - - # Method - [int] Drive ([int]$miles) - { - $this.Distance += $miles - $this.rides++ - return $this.Distance - } - - # Hidden property of the Drive method - hidden [int] $rides = 0 -} - -``` - - Now, create a new instance of the Car class, and save it in a variable, $TestCar. - -``` - -$TestCar = [Car]::new() - -``` - - After you create the new instance, pipe the contents of the $TestCar variable to Get\-Member. Observe that the rides property is not among the members listed in the Get\-Member command results. - -``` -PS C:\Windows\system32> $TestCar | Get-Member - - TypeName: Car - -Name MemberType Definition ----- ---------- ---------- -Drive Method int Drive(int miles) -Equals Method bool Equals(System.Object obj) -GetHashCode Method int GetHashCode() -GetType Method type GetType() -ToString Method string ToString() -Color Property string Color {get;set;} -Distance Property int Distance {get;set;} -ModelYear Property string ModelYear {get;set;} - -``` - - Now, try running Get\-Member again, but this time, add the –Force parameter. Note that the results contain the hidden rides property, among other members that are hidden by default. - -``` -PS C:\Windows\system32> $TestCar | Get-Member -Force - - TypeName: Car - -Name MemberType Definition ----- ---------- ---------- -pstypenames CodeProperty System.Collections.ObjectModel.Collection`1… -psadapted MemberSet psadapted {Color, ModelYear, Distance, -psbase MemberSet psbase {Color, ModelYear, Distance,... -psextended MemberSet psextended {} -psobject MemberSet psobject {BaseObject, Members,... -Drive Method int Drive(int miles) -Equals Method bool Equals(System.Object obj) -GetHashCode Method int GetHashCode() -GetType Method type GetType() -get_Color Method string get_Color() -get_Distance Method int get_Distance() -get_ModelYear Method string get_ModelYear() -get_rides Method int get_rides() -set_Color Method void set_Color(string ) -set_Distance Method void set_Distance(int ) -set_ModelYear Method void set_ModelYear(string ) -set_rides Method void set_rides(int ) -ToString Method string ToString() -Color Property string Color {get;set;} -Distance Property int Distance {get;set;} -ModelYear Property string ModelYear {get;set;} -rides Property int rides {get;set;} - -``` - -## SEE ALSO - about\_Classes - - about\_Language\_Keywords - - about\_Wildcards - - Get\-Member +## SHORT DESCRIPTION + +Describes the Hidden keyword, which hides class members from default +Get-Member results. + +## LONG DESCRIPTION + +When you use the Hidden keyword in a script, you hide the members of a class +by default. The Hidden keyword can hide properties, methods (including +constructors, events, alias properties, and other member types, including +static members, from the default results of the Get-Member cmdlet, and from +IntelliSense and tab completion results. To display members that you have +hidden with the Hidden keyword, add the -Force parameter to a Get-Member +command. + +Hidden members are not displayed by using tab completion or IntelliSense, +unless the completion occurs in the class that defines the hidden member. + +A new attribute, System.Management.Automation.HiddenAttribute, has been added, +so that C\# code can have the same semantics within PowerShell. + +The Hidden keyword is useful for creating properties and methods within a +class that you do not necessarily want other users of the class to see, or +readily be able to edit. + +The Hidden keyword has no effect on how you can view or make changes to +members of a class. Like all language keywords in PowerShell, Hidden is not +case-sensitive, and hidden members are still public. + +Hidden, along with custom classes, was introduced in PowerShell 5.0. + +## EXAMPLE + +The following example shows how to use the Hidden keyword in a class +definition. The Car class method, Drive, has a property, rides, that does not +need to be viewed or changed (it merely tallies the number of times that Drive +is called on the Car class, a metric that is not important to users of the +class; consider, for example, that when you are buying a car, you do not ask +the seller on how many drives the car has been taken. + +Because there is little need for users of the class to change this property, +we can hide the property from Get-Member and automatic completion results by +using the Hidden keyword. + +Add the Hidden keyword by entering it on the same statement line as the +property and its data type. Although the keyword can be in any order on this +line, starting the statement with the Hidden keyword makes it easier for you +later to identify all members that you have hidden. + +```powershell +class Car +{ + # Properties + [String] $Color + [String] $ModelYear + [int] $Distance + + # Method + [int] Drive ([int]$miles) + { + $this.Distance += $miles + $this.rides++ + return $this.Distance + } + + # Hidden property of the Drive method + hidden [int] $rides = 0 +} +``` + +Now, create a new instance of the Car class, and save it in a variable, +\$TestCar. + +```powershell +$TestCar = [Car]::new() +``` + +After you create the new instance, pipe the contents of the $TestCar variable +to Get-Member. Observe that the rides property is not among the members listed +in the Get-Member command results. + +```output +PS C:\Windows\system32> $TestCar | Get-Member + + TypeName: Car + +Name MemberType Definition +---- ---------- ---------- +Drive Method int Drive(int miles) +Equals Method bool Equals(System.Object obj) +GetHashCode Method int GetHashCode() +GetType Method type GetType() +ToString Method string ToString() +Color Property string Color {get;set;} +Distance Property int Distance {get;set;} +ModelYear Property string ModelYear {get;set;} + +``` + +Now, try running Get-Member again, but this time, add the –Force parameter. +Note that the results contain the hidden rides property, among other members +that are hidden by default. + +```output +PS C:\Windows\system32> $TestCar | Get-Member -Force + + TypeName: Car + +Name MemberType Definition +---- ---------- ---------- +pstypenames CodeProperty System.Collections.ObjectModel.Collection`1… +psadapted MemberSet psadapted {Color, ModelYear, Distance, +psbase MemberSet psbase {Color, ModelYear, Distance,... +psextended MemberSet psextended {} +psobject MemberSet psobject {BaseObject, Members,... +Drive Method int Drive(int miles) +Equals Method bool Equals(System.Object obj) +GetHashCode Method int GetHashCode() +GetType Method type GetType() +get_Color Method string get_Color() +get_Distance Method int get_Distance() +get_ModelYear Method string get_ModelYear() +get_rides Method int get_rides() +set_Color Method void set_Color(string ) +set_Distance Method void set_Distance(int ) +set_ModelYear Method void set_ModelYear(string ) +set_rides Method void set_rides(int ) +ToString Method string ToString() +Color Property string Color {get;set;} +Distance Property int Distance {get;set;} +ModelYear Property string ModelYear {get;set;} +rides Property int rides {get;set;} + +``` + +## SEE ALSO + +[about_Classes](about_Classes.md) + +[about_Language_Keywords](about_Language_Keywords.md) + +[about_Wildcards](about_Wildcards.md) + +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_logical_operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_logical_operators.md index cafeedc3d3f5..7d9280a26f85 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_logical_operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_logical_operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,13 +14,13 @@ Describes the operators that connect statements in PowerShell. ## LONG DESCRIPTION -The PowerShell logical operators connect expressions and statements, -allowing you to use a single expression to test for multiple conditions. +The PowerShell logical operators connect expressions and statements, allowing +you to use a single expression to test for multiple conditions. -For example, the following statement uses the and operator and the or -operator to connect three conditional statements. The statement is true -only when the value of $a is greater than the value of $b, and either $a or -$b is less than 20. +For example, the following statement uses the and operator and the or operator +to connect three conditional statements. The statement is true only when the +value of $a is greater than the value of $b, and either $a or $b is less than +20. ```powershell ($a -gt $b) -and (($a -lt 20) -or ($b -lt 20)) @@ -28,38 +28,43 @@ $b is less than 20. PowerShell supports the following logical operators. -|Operator|Description|Example| -|---|---|---| -|`-and`|Logical and. TRUE only when both statements are TRUE.|`(1 -eq 1) -and (1 -eq 2)`
`False`| -|`-or`|Logical or. TRUE when either or both statements are TRUE.|`(1 -eq 1) -or (1 -eq 2)`
`True`| -|`-xor`|Logical exclusive or. TRUE only when one of the statements is TRUE and the other is FALSE.|`(1 -eq 1) -xor (2 -eq 2)`
`False`| -|`-not`|Logical not. Negates the statement that follows it.|`-not (1 -eq 1)`
`False`| -|`!`|Logical not. Negates the statement that follows it. (Same as -not)|`!(1 -eq 1)`
`False`| +|Operator|Description |Example | +|--------|-----------------------------------|--------------------------| +|`-and` |Logical AND. TRUE when both |`(1 -eq 1) -and (1 -eq 2)`| +| |statements are TRUE. |`False` | +|`-or` |Logical OR. TRUE when either |`(1 -eq 1) -or (1 -eq 2)` | +| |statement is TRUE. |`True` | +|`-xor` |Logical EXCLUSIVE OR. TRUE when |`(1 -eq 1) -xor (2 -eq 2) | +| |only one statement is TRUE |`False` | +|`-not` |Logical not. Negates the statement |`-not (1 -eq 1)` | +| |that follows. |`False` | +|`!` |Same as `-not` |`!(1 -eq 1)` | +| | |`False` | Note: - The previous examples also use the equal to comparison operator `-eq`. For - more information, see about_Comparison_Operators. The examples also use - the Boolean values of integers. The integer 0 has a value of FALSE. All - other integers have a value of TRUE. +The previous examples also use the equal to comparison operator `-eq`. For +more information, see +[about_Comparison_Operators](about_Comparison_Operators.md). The examples also +use the Boolean values of integers. The integer 0 has a value of FALSE. All +other integers have a value of TRUE. - The syntax of the logical operators is as follows: +The syntax of the logical operators is as follows: -```powershell +``` {-AND | -OR | -XOR} {! | -NOT} ``` - Statements that use the logical operators return Boolean (TRUE or FALSE) - values. +Statements that use the logical operators return Boolean (TRUE or FALSE) +values. - The PowerShell logical operators evaluate only the statements required to - determine the truth value of the statement. If the left operand in a - statement that contains the and operator is FALSE, the right operand is - not evaluated. If the left operand in a statement that contains the or - statement is TRUE, the right operand is not evaluated. As a result, you - can use these statements in the same way that you would use the If - statement. +The PowerShell logical operators evaluate only the statements required to +determine the truth value of the statement. If the left operand in a statement +that contains the and operator is FALSE, the right operand is not evaluated. +If the left operand in a statement that contains the or statement is TRUE, the +right operand is not evaluated. As a result, you can use these statements in +the same way that you would use the If statement. ## SEE ALSO diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md index 660b7694d8d0..ea1e83939845 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,36 +7,49 @@ title: about_PSConsoleHostReadLine --- # about_PSConsoleHostReadLine -## TOPIC - about\_PSConsoleHostReadLine - -## SHORT DESCRIPTION - Explains how to create a customize how Windows PowerShell® reads input at the console prompt. - -## LONG DESCRIPTION - Starting in Windows PowerShell V3, you can write a function named PSConsoleHostReadLine that overrides the default way that console input is processed. - -### EXAMPLES - The following example launches Notepad and gets input from a text File that the user creates: - -``` - function PSConsoleHostReadLine - { -    $inputFile = Join-Path $env:TEMP PSConsoleHostReadLine -    Set-Content $inputFile "PS > " - -    ## Notepad opens. Enter your command in it, save the file, -    ## and then exit. -    notepad $inputFile | Out-Null -    $userInput = Get-Content $inputFile -    $resultingCommand = $userInput.Replace("PS >", "") -    $resultingCommand - } -``` - -### REMARKS - By default, Windows PowerShell reads input from the console in what is known as “Cooked Mode”—in which the Windows console subsystem handles all the keypresses, F7 menus, and other input. When you press Enter or Tab, Windows PowerShell gets the text that you have typed up to that point. There is no way for it to know that you pressed Ctrl\-R, Ctrl\-A, Ctrl\-E, or any other keys before pressing Enter or Tab. In Windows PowerShell version 3, the PSConsoleHostReadLine function solves this issue. When you define a function named PSConsoleHostReadline in the Windows PowerShell console host, Windows PowerShell calls that function instead of the “Cooked Mode” input mechanism. - -### SEE ALSO - about\_Prompts +## SHORT DESCRIPTION + +Explains how to create a customize how PowerShell reads input at the console +prompt. + +## LONG DESCRIPTION + +Starting in Windows PowerShell V3, you can write a function named +PSConsoleHostReadLine that overrides the default way that console input is +processed. + +### EXAMPLES + +The following example launches Notepad and gets input from a text File that +the user creates: + +```powershell +function PSConsoleHostReadLine +{ + $inputFile = Join-Path $env:TEMP PSConsoleHostReadLine + Set-Content $inputFile "PS > " + + # Notepad opens. Enter your command in it, save the file, and then exit. + notepad $inputFile | Out-Null + $userInput = Get-Content $inputFile + $resultingCommand = $userInput.Replace("PS >", "") + $resultingCommand +} +``` + +### REMARKS + +By default, PowerShell reads input from the console in what is known as +"Cooked Mode" -- in which the Windows console subsystem handles all the +keypresses, F7 menus, and other input. When you press Enter or Tab, Windows +PowerShell gets the text that you have typed up to that point. There is no way +for it to know that you pressed Ctrl-R, Ctrl-A, Ctrl-E, or any other keys +before pressing Enter or Tab. In Windows PowerShell version 3, the +PSConsoleHostReadLine function solves this issue. When you define a function +named PSConsoleHostReadline in the Windows PowerShell console host, Windows +PowerShell calls that function instead of the "Cooked Mode" input mechanism. + +### SEE ALSO + +[about_Prompts](about_Prompts.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_psreadline.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_psreadline.md index d0c6cabb5b81..c21c0d7a2995 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_psreadline.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_psreadline.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,649 +7,668 @@ title: about_PSReadline --- # about_PSReadline -``` -TOPIC - about_PSReadline - -SHORT DESCRIPTION - - PSReadline provides an improved command line editing experience in - the Windows PowerShell console. - -LONG DESCRIPTION - - PSReadline, introduced in Windows PowerShell 5.0, provides a powerful - command line editing experience for the Windows PowerShell console. - It provides: - - * Syntax coloring of the command line - * A visual indication of syntax errors - * A better multi-line experience (both editing and history) - * Customizable key bindings - * Cmd and Emacs modes - * Many configuration options - * Bash style completion (optional in Cmd mode, default in Emacs mode) - * Emacs yank/kill ring - * Windows PowerShell token based "word" movement and kill - - The following functions are available in the class [PSConsoleUtilities.PSConsoleReadLine]: - - Cursor movement - --------------- - - EndOfLine (Cmd: Emacs: or ) - - If the input has multiple lines, move to the end of the current line, - or if already at the end of the line, move to the end of the input. - If the input has a single line, move to the end of the input. - - BeginningOfLine (Cmd: Emacs: or ) - - If the input has multiple lines, move to the start of the current line, - or if already at the start of the line, move to the start of the input. - If the input has a single line, move to the start of the input. - - NextLine (Cmd: unbound Emacs: unbound) - - Move the cursor to the next line if the input has multiple lines. - - PreviousLine (Cmd: unbound Emacs: unbound) - - Move the cursor to the previous line if the input has multiple lines. - - ForwardChar (Cmd: Emacs: or ) - - Move the cursor one character to the right. This might move the cursor to the next - line of multi-line input. - - BackwardChar (Cmd: Emacs: or ) - - Move the cursor one character to the left. This might move the cursor to the previous - line of multi-line input. - - ForwardWord (Cmd: unbound Emacs: ) - - Move the cursor forward to the end of the current word, or if between words, - to the end of the next word. You can set word delimiter characters with: - - Set-PSReadlineOption -WordDelimiters - - NextWord (Cmd: Emacs: unbound) - - Move the cursor forward to the start of the next word. You can set word - delimiter characters with: - - Set-PSReadlineOption -WordDelimiters - - BackwardWord (Cmd: Emacs: ) - - Move the cursor back to the start of the current word, or if between words, - the start of the previous word. You can set word delimiter characters with: - - Set-PSReadlineOption -WordDelimiters - - ShellForwardWord (Cmd: unbound Emacs: unbound) - - Like ForwardWord except word boundaries are defined by Windows PowerShell - token boundaries. - - ShellNextWord (Cmd: unbound Emacs: unbound) - - Like NextWord except word boundaries are defined by Windows PowerShell - token boundaries. - - ShellBackwardWord (Cmd: unbound Emacs: unbound) - - Like BackwardWord except word boundaries are defined by Windows PowerShell - token boundaries. - - GotoBrace (Cmd: Emacs: unbound) - - Go to the matching parenthesis, curly brace, or square bracket. - - AddLine (Cmd: Emacs: ) - - The continuation prompt is displayed on the next line and PSReadline waits for - keys to edit the current input. This is useful to enter multi-line input as - a single command even when a single line is complete input by itself. - - Basic editing - ------------- - - CancelLine (Cmd: unbound Emacs: unbound) - - Cancel all editing to the line, leave the line of input on the screen but - return from PSReadline without executing the input. - - RevertLine (Cmd: Emacs: ) - - Reverts all of the input since the last input was accepted and run. - This is equivalent to using the Undo command until there is nothing - left to undo. - - BackwardDeleteChar (Cmd: Emacs: or ) - - Delete the character before the cursor. - - DeleteChar (Cmd: Emacs: ) - - Delete the character under the cursor. - - DeleteCharOrExit (Cmd: unbound Emacs: ) - - Like DeleteChar, unless the line is empty, in which case exit the process. - - AcceptLine (Cmd: Emacs: or ) - - Attempt to execute the current input. If the current input is incomplete (for - example, there is a missing closing parenthesis, bracket, or quote), then the - continuation prompt is displayed on the next line, and PSReadline waits for - keys to edit the current input. - - AcceptAndGetNext (Cmd: unbound Emacs: ) - - Like AcceptLine, but after the line completes, start editing the next line - from history. - - ValidateAndAcceptLine (Cmd: unbound Emacs: unbound) - - Like AcceptLine but performs additional validation including: - - * Checks for additional parse errors - * Validates that command names are all found - * If you are running Windows PowerShell 4.0 or newer, - validates the parameters and arguments - - If there are any errors, the error message is displayed and not accepted nor added - to the history unless you either correct the command line or execute AcceptLine or - ValidateAndAcceptLine again while the error message is displayed. - - BackwardDeleteLine (Cmd: Emacs: unbound) - - Delete the text from the start of the input to the cursor. - - ForwardDeleteLine (Cmd: Emacs: unbound) - - Delete the text from the cursor to the end of the input. - - SelectBackwardChar (Cmd: Emacs: ) - - Adjust the current selection to include the previous character. - - SelectForwardChar (Cmd: Emacs: ) - - Adjust the current selection to include the next character. - - SelectBackwardWord (Cmd: Emacs: ) - - Adjust the current selection to include the previous word. - - SelectForwardWord (Cmd: unbound Emacs: ) - - Adjust the current selection to include the next word using ForwardWord. - - SelectNextWord (Cmd: Emacs: unbound) - - Adjust the current selection to include the next word using NextWord. - - SelectShellForwardWord (Cmd: unbound Emacs: unbound) - - Adjust the current selection to include the next word using ShellForwardWord. - - SelectShellNextWord (Cmd: unbound Emacs: unbound) - - Adjust the current selection to include the next word using ShellNextWord. - - SelectShellBackwardWord (Cmd: unbound Emacs: unbound) - - Adjust the current selection to include the previous word using ShellBackwardWord. - - SelectBackwardsLine (Cmd: Emacs: ) - - Adjust the current selection to include from the cursor to the start of the line. - - SelectLine (Cmd: Emacs: ) - - Adjust the current selection to include from the cursor to the end of the line. - - SelectAll (Cmd: Emacs: unbound) - - Select the entire line. Moves the cursor to the end of the line. - - SelfInsert (Cmd: , , ... Emacs: , , ...) - - Insert the key entered. - - Redo (Cmd: Emacs: unbound) - - Redo an insertion or deletion that was undone by Undo. - - Undo (Cmd: Emacs: ) - - Undo a previous insertion or deletion. - - History - ------- - - ClearHistory (Cmd: Alt+F7 Emacs: unbound) - - Clears history in PSReadline. This does not affect Windows PowerShell - history. - - PreviousHistory (Cmd: Emacs: or ) - - Replace the current input with the previous item from PSReadline history. - - NextHistory (Cmd: Emacs: or ) - - Replace the current input with the next item from PSReadline history. - - ForwardSearchHistory (Cmd: Emacs: ) - - Search forward from the current history line interactively. - - ReverseSearchHistory (Cmd: Emacs: ) - - Search backward from the current history line interactively. - - HistorySearchBackward (Cmd: Emacs: unbound) - - Replace the current input with the previous item from PSReadline history - that matches the characters between the start and the input and the cursor. - - HistorySearchForward (Cmd: Emacs: unbound) - - Replace the current input with the next item from PSReadline history - that matches the characters between the start and the input and the cursor. - - BeginningOfHistory (Cmd: unbound Emacs: ) - - Replace the current input with the last item from PSReadline history. - - EndOfHistory (Cmd: unbound Emacs: >) - - Replace the current input with the last item in PSReadline history, which - is the possibly empty input that was entered before any history commands. - - Tab Completion - -------------- - - TabCompleteNext (Cmd: Emacs: unbound) - - Attempt to complete the text surrounding the cursor with the next - available completion. - - TabCompletePrevious (Cmd: Emacs: unbound) - - Attempt to complete the text surrounding the cursor with the next - previous completion. - - Complete (Cmd: unbound Emacs: ) - - Attempt to perform completion on the text surrounding the cursor. - If there are multiple possible completions, the longest unambiguous - prefix is used for completion. If you are trying to complete the longest - unambiguous completion, a list of possible completions is displayed. - - MenuComplete (Cmd: Emacs: ) - - Attempt to perform completion on the text surrounding the cursor. - If there are multiple possible completions, a list of possible - completions is displayed, and you can select the correct completion - by using the arrow keys, or Tab/Shift+Tab. Escape and Ctrl+G cancel - the menu selection, and revert the line to the state before invoking - MenuComplete. - - PossibleCompletions (Cmd: unbound Emacs: ) - - Display the list of possible completions. - - SetMark (Cmd: unbound Emacs: ) - - Mark the current location of the cursor for use in a subsequent editing command. - - ExchangePointAndMark (Cmd: unbound Emacs: ) - - The cursor is placed at the location of the mark and the mark is moved - to the location of the cursor. - - Kill/Yank - --------- - - Kill and Yank operate on a clipboard in the PSReadline module. There is a ring - buffer called the kill ring - killed text is added to the kill ring up - and yank will copy text from the most recent kill. YankPop cycles through - items in the kill ring. When the kill ring is full, new items replace the - oldest items. A kill operation that is immediately preceded by another kill operation - appends the previous kill, instead of adding a new item or replacing an item - in the kill ring. This is how you can cut a part of a line, for example, with multiple - KillWord operations, then yank them back elsewhere as a single yank. - - KillLine (Cmd: unbound Emacs: ) - - Clear the input from the cursor to the end of the line. The cleared text is placed - in the kill ring. - - BackwardKillLine (Cmd: unbound Emacs: or ) - - Clear the input from the start of the input to the cursor. The cleared text is placed - in the kill ring. - - KillWord (Cmd: unbound Emacs: ) - - Clear the input from the cursor to the end of the current word. If the cursor - is between words, the input is cleared from the cursor to the end of the next word. - The cleared text is placed in the kill ring. - - BackwardKillWord (Cmd: unbound Emacs: ) - - Clear the input from the start of the current word to the cursor. If the cursor - is between words, the input is cleared from the start of the previous word to the - cursor. The cleared text is placed in the kill ring. - - ShellKillWord (Cmd: unbound Emacs: unbound) - - Like KillWord, except word boundaries are defined by Windows PowerShell - token boundaries. - - ShellBackwardKillWord (Cmd: unbound Emacs: unbound) - - Like BackwardKillWord, except word boundaries are defined by Windows PowerShell - token boundaries. - - UnixWordRubout (Cmd: unbound Emacs: ) - - Like BackwardKillWord, except word boundaries are defined by white space. - - KillRegion (Cmd: unbound Emacs: unbound) - - Kill the text between the cursor and the mark. - - Copy (Cmd: Emacs: unbound) - - Copy selected region to the system clipboard. If no region is selected, copy the whole line. - - CopyOrCancelLine (Cmd: Emacs: ) - - Either copy selected text to the clipboard, or if no text is selected, cancel editing - the line with CancelLine. - - Cut (Cmd: Emacs: unbound) - - Delete selected region placing deleted text in the system clipboard. - - Yank (Cmd: unbound Emacs: ) - - Add the most-recently killed text to the input. - - YankPop (Cmd: unbound Emacs: ) - - If the previous operation was Yank or YankPop, replace the previously-yanked - text with the next killed text from the kill ring. - - ClearKillRing (Cmd: unbound Emacs: unbound) - - The contents of the kill ring are cleared. - - Paste (Cmd: Emacs: unbound) - - This is similar to Yank, but uses the system clipboard instead of the kill ring. - - YankLastArg (Cmd: Emacs: , ) - - Insert the last argument from the previous command in history. Repeated operations - replace the last inserted argument with the last argument from the previous - command (so Alt+. Alt+. will insert the last argument of the second to last history - line). - - With an argument, the first time YankLastArg behaves like YankNthArg. A negative - argument on subsequent YankLastArg calls changes the direction while going - through history. For example, if you press Alt+. one too many times, you can type - Alt+- Alt+. to reverse the direction. - - Arguments are based on Windows PowerShell tokens. - - YankNthArg (Cmd: unbound Emacs: ) - - Insert the first argument (not the command name) of the previous command in history. - - With an argument, insert the nth argument where 0 is typically the command. Negative - arguments start from the end. - - Arguments are based on Windows PowerShell tokens. - - Miscellaneous - ------------- - - Abort (Cmd: unbound Emacs: ) - - Abort the current action; for example, stop interactive history search. - Does not cancel input like CancelLine. - - CharacterSearch (Cmd: Emacs: ) - - Read a key and search forwards for that character. With an argument, search - forwards for the nth occurrence of that argument. With a negative argument, - searches backwards. - - CharacterSearchBackward (Cmd: Emacs: ) - - Like CharacterSearch, but searches backwards. With a negative argument, searches - forwards. - - ClearScreen (Cmd: Emacs: ) - - Clears the screen and displays the current prompt and input at the top of the screen. - - DigitArgument (Cmd: unbound Emacs: ,,) - - Used to pass numeric arguments to functions like CharacterSearch or YankNthArg. - Alt+- toggles the argument to be negative/non-negative. To enter 80 '*' characters, - you could type Alt+8 Alt+0 *. - - CaptureScreen (Cmd: unbound Emacs: unbound) - - Copies selected lines to the clipboard in both text and RTF formats. Use up/down - arrow keys to the first line to select, then Shift+UpArrow/Shift+DownArrow to select - multiple lines. After selecting, press Enter to copy the text. Escape/Ctrl+C/Ctrl+G - cancel the operation, so nothing is copied to the clipboard. - - InvokePrompt (Cmd: unbound Emacs: unbound) - - Erases the current prompt and calls the prompt function to redisplay - the prompt. Useful for custom key handlers that change state, such as - changing the current directory. - - WhatIsKey (Cmd: Emacs: ) - - Read a key or chord and display the key binding. - - ShowKeyBindings (Cmd: Emacs: ) - - Show all of the currently-bound keys. - - ScrollDisplayUp (Cmd: Emacs: ) - - Scroll the display up one screen. - - ScrollDisplayUpLine (Cmd: Emacs: ) - - Scroll the display up one line. - - ScrollDisplayDown (Cmd: Emacs: ) - - Scroll the display down one screen. - - ScrollDisplayDownLine (Cmd: Emacs: ) - - Scroll the display down one line. - - ScrollDisplayTop (Cmd: unbound Emacs: ) - - Scroll the display to the top. - - ScrollDisplayToCursor (Cmd: unbound Emacs: ) - - Scroll the display to the cursor. - - Custom Key Bindings - ------------------- - - PSReadline supports custom key bindings using the cmdlet Set-PSReadlineKeyHandler. Most - custom key bindings call one of the above functions, for example: - - Set-PSReadlineKeyHandler -Key UpArrow -Function HistorySearchBackward - - You can bind a ScriptBlock to a key. The ScriptBlock can do virtually anything you want. - Some useful examples include: - - * edit the command line - * opening a new window (e.g. help) - * change directories without changing the command line - - The ScriptBlock is passed two arguments: - - * $key - A [ConsoleKeyInfo] that is the key that triggered the custom binding. If you bind - the same ScriptBlock to multiple keys and need to perform different actions depending - on the key, you can check $key. Many custom bindings ignore this argument. - * $arg - An arbitrary argument. Most often, this would be an integer argument that the user - passes from the key bindings DigitArgument. If your binding doesn't accept arguments, - it's reasonable to ignore this argument. - - Let's take a look at an example that adds a command line to history without executing it. This is - useful when you realize you forgot to do something, but don't want to re-enter the command line - you've already entered. - - Set-PSReadlineKeyHandler -Key Alt+w ` - -BriefDescription SaveInHistory ` - -LongDescription "Save current line in history but do not execute" ` - -ScriptBlock { - param($key, $arg) # The arguments are ignored in this example - - # We need the command line, GetBufferState gives us that (with the cursor position) - $line = $null - $cursor = $null - [PSConsoleUtilities.PSConsoleReadLine]::GetBufferState([ref]$line, [ref]$cursor) - - # AddToHistory saves the line in history, but does not execute the line. - [PSConsoleUtilities.PSConsoleReadLine]::AddToHistory($line) - - # RevertLine is like pressing Escape. - [PSConsoleUtilities.PSConsoleReadLine]::RevertLine() - } - - You can see many more examples in the file SamplePSReadlineProfile.ps1 which is installed in the - PSReadline module folder. - - Most key bindings will want to take advantage of some helper functions for editing the command - line those APIs are documented in the next section. - - Custom Key Binding Support APIs - ------------------------------- - - The following functions are public in PSConsoleUtilities.PSConsoleReadline, but cannot be directly - bound to a key. Most are useful in custom key bindings. - - void AddToHistory(string command) - - Add a command line to history without executing it. - - void ClearKillRing() - - Clear the kill ring. This is mostly used for testing. - - void Delete(int start, int length) - - Delete length characters from start. This operation supports undo and redo. - - void Ding() - - Perform the Ding action based on the user’s preference. - - void GetBufferState([ref] string input, [ref] int cursor) - void GetBufferState([ref] Ast ast, [ref] Token[] tokens, [ref] ParseError[] parseErrors, [ref] int cursor) - - These two functions retrieve useful information about the current state of - the input buffer. The first is more commonly used for simple cases. The - second is used if your binding is doing something more advanced with the Ast. - - IEnumerable[PSConsoleUtilities.KeyHandler] GetKeyHandlers(bool includeBound, bool includeUnbound) - - This function is used by Get-PSReadlineKeyHandler and probably isn't useful in a custom - key binding. - - PSConsoleUtilities.PSConsoleReadlineOptions GetOptions() - - This function is used by Get-PSReadlineOption and probably isn't too useful in a custom - key binding. - - void GetSelectionState([ref] int start, [ref] int length) - - If there is no selection on the command line, -1 is returned in both start and length. - If there is a selection on the command line, the start and length of the selection are returned. - - void Insert(char c) - void Insert(string s) - - Insert a character or string at the cursor. This operation supports undo and redo. - - string ReadLine(runspace remoteRunspace, System.Management.Automation.EngineIntrinsics engineIntrinsics) - - This is the main entry point to PSReadline. It does not support recursion, so is not useful - in a custom key binding. - - void RemoveKeyHandler(string[] key) - - This function is used by Remove-PSReadlineKeyHandler and probably isn't too useful in a - custom key binding. - - void Replace(int start, int length, string replacement) - - Replace some of the input. This operation supports undo and redo. - This is preferred over Delete followed by Insert because it is treated as a single action - for undo. - - void SetCursorPosition(int cursor) - - Move the cursor to the given offset. Cursor movement is not tracked for undo. - - void SetOptions(PSConsoleUtilities.SetPSReadlineOption options) - - This function is a helper method used by the cmdlet Set-PSReadlineOption, but might be - useful to a custom key binding that wants to temporarily change a setting. - - bool TryGetArgAsInt(System.Object arg, [ref] int numericArg, int defaultNumericArg) - - This helper method is used for custom bindings that honor DigitArgument. A typical call - looks like: - - [int]$numericArg = 0 - [PSConsoleUtilities.PSConsoleReadLine]::TryGetArgAsInt($arg, [ref]$numericArg, 1) - -WINDOWS POWERSHELL COMPATIBILITY - - PSReadline requires Windows PowerShell 3.0 or newer, and the console host. It - does not work in Windows PowerShell ISE. - -FEEDBACK - - https://github.com/lzybkr/PSReadline - -CONTRIBUTING TO PSREADLINE - - Feel free to submit a pull request or submit feedback on the PSReadline - GitHub page (https://github.com/lzybkr/PSReadLine). - -SEE ALSO - - PSReadline is heavily influenced by the GNU Readline library: - http://tiswww.case.edu/php/chet/readline/rltop.html - - Get-PSReadlineKeyHandler - Get-PSReadlineOption - Remove-PSReadlineKeyHandler - Set-PSReadlineKeyHandler - Set-PSReadlineOption - + +## SHORT DESCRIPTION + +PSReadline provides an improved command line editing experience in the +PowerShell console. + +## LONG DESCRIPTION + +PSReadline, introduced in PowerShell 5.0, provides a powerful command line +editing experience for the PowerShell console. It provides: + +- Syntax coloring of the command line +- A visual indication of syntax errors +- A better multi-line experience (both editing and history) +- Customizable key bindings +- Cmd and Emacs modes +- Many configuration options +- Bash style completion (optional in Cmd mode, default in Emacs mode) +- Emacs yank/kill ring +- PowerShell token based "word" movement and kill + +The following functions are available in the class +[PSConsoleUtilities.PSConsoleReadLine]: + +## Cursor movement + +- EndOfLine (Cmd: Emacs: or ) + + If the input has multiple lines, move to the end of the current line, or if + already at the end of the line, move to the end of the input. If the input + has a single line, move to the end of the input. + +- BeginningOfLine (Cmd: Emacs: or ) + + If the input has multiple lines, move to the start of the current line, or + if already at the start of the line, move to the start of the input. If the + input has a single line, move to the start of the input. + +- NextLine (Cmd: unbound Emacs: unbound) + + Move the cursor to the next line if the input has multiple lines. + +- PreviousLine (Cmd: unbound Emacs: unbound) + + Move the cursor to the previous line if the input has multiple lines. + +- ForwardChar (Cmd: Emacs: or ) + + Move the cursor one character to the right. This might move the cursor to + the next line of multi-line input. + +- BackwardChar (Cmd: Emacs: or ) + + Move the cursor one character to the left. This might move the cursor to the + previous line of multi-line input. + +- ForwardWord (Cmd: unbound Emacs: ) + + Move the cursor forward to the end of the current word, or if between words, + to the end of the next word. You can set word delimiter characters with: + + ```powershell + Set-PSReadlineOption -WordDelimiters + ``` + +- NextWord (Cmd: Emacs: unbound) + + Move the cursor forward to the start of the next word. You can set word + delimiter characters with: + + ```powershell + Set-PSReadlineOption -WordDelimiters + ``` + +- BackwardWord (Cmd: Emacs: ) + + Move the cursor back to the start of the current word, or if between words, + the start of the previous word. You can set word delimiter characters with: + + ```powershell + Set-PSReadlineOption -WordDelimiters + ``` + +- ShellForwardWord (Cmd: unbound Emacs: unbound) + + Like ForwardWord except word boundaries are defined by PowerShell token + boundaries. + +- ShellNextWord (Cmd: unbound Emacs: unbound) + + Like NextWord except word boundaries are defined by PowerShell token + boundaries. + +- ShellBackwardWord (Cmd: unbound Emacs: unbound) + + Like BackwardWord except word boundaries are defined by PowerShell token + boundaries. + +- GotoBrace (Cmd: Emacs: unbound) + + Go to the matching parenthesis, curly brace, or square bracket. + +- AddLine (Cmd: Emacs: ) + + The continuation prompt is displayed on the next line and PSReadline waits + for keys to edit the current input. This is useful to enter multi-line input + as a single command even when a single line is complete input by itself. + +## Basic editing + +- CancelLine (Cmd: unbound Emacs: unbound) + + Cancel all editing to the line, leave the line of input on the screen but + return from PSReadline without executing the input. + +- RevertLine (Cmd: Emacs: ) + + Reverts all of the input since the last input was accepted and run. This is + equivalent to using the Undo command until there is nothing left to undo. + +- BackwardDeleteChar (Cmd: Emacs: or ) + + Delete the character before the cursor. + +- DeleteChar (Cmd: Emacs: ) + + Delete the character under the cursor. + +- DeleteCharOrExit (Cmd: unbound Emacs: ) + + Like DeleteChar, unless the line is empty, in which case exit the process. + +- AcceptLine (Cmd: Emacs: or ) + + Attempt to execute the current input. If the current input is incomplete + (for example, there is a missing closing parenthesis, bracket, or quote), + then the continuation prompt is displayed on the next line, and PSReadline + waits for keys to edit the current input. + +- AcceptAndGetNext (Cmd: unbound Emacs: ) + + Like AcceptLine, but after the line completes, start editing the next line + from history. + +- ValidateAndAcceptLine (Cmd: unbound Emacs: unbound) + + Like AcceptLine but performs additional validation including: + + * Checks for additional parse errors + * Validates that command names are all found + * If you are running PowerShell 4.0 or newer, validates the parameters and + arguments + + If there are any errors, the error message is displayed and not accepted nor + added to the history unless you either correct the command line or execute + AcceptLine or ValidateAndAcceptLine again while the error message is + displayed. + +- BackwardDeleteLine (Cmd: Emacs: unbound) + + Delete the text from the start of the input to the cursor. + +- ForwardDeleteLine (Cmd: Emacs: unbound) + + Delete the text from the cursor to the end of the input. + +- SelectBackwardChar (Cmd: Emacs: ) + + Adjust the current selection to include the previous character. + +- SelectForwardChar (Cmd: Emacs: ) + + Adjust the current selection to include the next character. + +- SelectBackwardWord (Cmd: Emacs: ) + + Adjust the current selection to include the previous word. + +- SelectForwardWord (Cmd: unbound Emacs: ) + + Adjust the current selection to include the next word using ForwardWord. + +- SelectNextWord (Cmd: Emacs: unbound) + + Adjust the current selection to include the next word using NextWord. + +- SelectShellForwardWord (Cmd: unbound Emacs: unbound) + + Adjust the current selection to include the next word using + ShellForwardWord. + +- SelectShellNextWord (Cmd: unbound Emacs: unbound) + + Adjust the current selection to include the next word using ShellNextWord. + +- SelectShellBackwardWord (Cmd: unbound Emacs: unbound) + + Adjust the current selection to include the previous word using + ShellBackwardWord. + +- SelectBackwardsLine (Cmd: Emacs: ) + + Adjust the current selection to include from the cursor to the start of the + line. + +- SelectLine (Cmd: Emacs: ) + + Adjust the current selection to include from the cursor to the end of the + line. + +- SelectAll (Cmd: Emacs: unbound) + + Select the entire line. Moves the cursor to the end of the line. + +- SelfInsert (Cmd: , , ... Emacs: , , ...) + + Insert the key entered. + +- Redo (Cmd: Emacs: unbound) + + Redo an insertion or deletion that was undone by Undo. + +- Undo (Cmd: Emacs: ) + + Undo a previous insertion or deletion. + +## History + +- ClearHistory (Cmd: Alt+F7 Emacs: unbound) + + Clears history in PSReadline. This does not affect PowerShell + history. + +- PreviousHistory (Cmd: Emacs: or ) + + Replace the current input with the previous item from PSReadline history. + +- NextHistory (Cmd: Emacs: or ) + + Replace the current input with the next item from PSReadline history. + +- ForwardSearchHistory (Cmd: Emacs: ) + + Search forward from the current history line interactively. + +- ReverseSearchHistory (Cmd: Emacs: ) + + Search backward from the current history line interactively. + +- HistorySearchBackward (Cmd: Emacs: unbound) + + Replace the current input with the previous item from PSReadline history + that matches the characters between the start and the input and the cursor. + +- HistorySearchForward (Cmd: Emacs: unbound) + + Replace the current input with the next item from PSReadline history that + matches the characters between the start and the input and the cursor. + +- BeginningOfHistory (Cmd: unbound Emacs: ) + + Replace the current input with the last item from PSReadline history. + +- EndOfHistory (Cmd: unbound Emacs: >) + + Replace the current input with the last item in PSReadline history, which is + the possibly empty input that was entered before any history commands. + +## Tab Completion + +- TabCompleteNext (Cmd: Emacs: unbound) + + Attempt to complete the text surrounding the cursor with the next + available completion. + +- TabCompletePrevious (Cmd: Emacs: unbound) + + Attempt to complete the text surrounding the cursor with the next + previous completion. + +- Complete (Cmd: unbound Emacs: ) + + Attempt to perform completion on the text surrounding the cursor. If there + are multiple possible completions, the longest unambiguous prefix is used + for completion. If you are trying to complete the longest unambiguous + completion, a list of possible completions is displayed. + +- MenuComplete (Cmd: Emacs: ) + + Attempt to perform completion on the text surrounding the cursor. If there + are multiple possible completions, a list of possible completions is + displayed, and you can select the correct completion by using the arrow + keys, or Tab/Shift+Tab. Escape and Ctrl+G cancel the menu selection, and + revert the line to the state before invoking MenuComplete. + +- PossibleCompletions (Cmd: unbound Emacs: ) + + Display the list of possible completions. + +- SetMark (Cmd: unbound Emacs: ) + + Mark the current location of the cursor for use in a subsequent editing + command. + +- ExchangePointAndMark (Cmd: unbound Emacs: ) + + The cursor is placed at the location of the mark and the mark is moved + to the location of the cursor. + +## Kill/Yank + +Kill and Yank operate on a clipboard in the PSReadline module. There is a ring +buffer called the kill ring - killed text is added to the kill ring up and +yank will copy text from the most recent kill. YankPop cycles through items in +the kill ring. When the kill ring is full, new items replace the oldest items. +A kill operation that is immediately preceded by another kill operation +appends the previous kill, instead of adding a new item or replacing an item +in the kill ring. This is how you can cut a part of a line, for example, with +multiple KillWord operations, then yank them back elsewhere as a single yank. + +- KillLine (Cmd: unbound Emacs: ) + + Clear the input from the cursor to the end of the line. The cleared text is + placed in the kill ring. + +- BackwardKillLine (Cmd: unbound Emacs: or ) + + Clear the input from the start of the input to the cursor. The cleared text + is placed in the kill ring. + +- KillWord (Cmd: unbound Emacs: ) + + Clear the input from the cursor to the end of the current word. If the + cursor is between words, the input is cleared from the cursor to the end of + the next word. The cleared text is placed in the kill ring. + +- BackwardKillWord (Cmd: unbound Emacs: ) + + Clear the input from the start of the current word to the cursor. If the + cursor is between words, the input is cleared from the start of the previous + word to the cursor. The cleared text is placed in the kill ring. + +- ShellKillWord (Cmd: unbound Emacs: unbound) + + Like KillWord, except word boundaries are defined by PowerShell + token boundaries. + +- ShellBackwardKillWord (Cmd: unbound Emacs: unbound) + + Like BackwardKillWord, except word boundaries are defined by PowerShell + token boundaries. + +- UnixWordRubout (Cmd: unbound Emacs: ) + + Like BackwardKillWord, except word boundaries are defined by white space. + +- KillRegion (Cmd: unbound Emacs: unbound) + + Kill the text between the cursor and the mark. + +- Copy (Cmd: Emacs: unbound) + + Copy selected region to the system clipboard. If no region is selected, copy + the whole line. + +- CopyOrCancelLine (Cmd: Emacs: ) + + Either copy selected text to the clipboard, or if no text is selected, + cancel editing the line with CancelLine. + +- Cut (Cmd: Emacs: unbound) + + Delete selected region placing deleted text in the system clipboard. + +- Yank (Cmd: unbound Emacs: ) + + Add the most-recently killed text to the input. + +- YankPop (Cmd: unbound Emacs: ) + + If the previous operation was Yank or YankPop, replace the previously-yanked + text with the next killed text from the kill ring. + +- ClearKillRing (Cmd: unbound Emacs: unbound) + + The contents of the kill ring are cleared. + +- Paste (Cmd: Emacs: unbound) + + This is similar to Yank, but uses the system clipboard instead of the kill + ring. + +- YankLastArg (Cmd: Emacs: , ) + + Insert the last argument from the previous command in history. Repeated + operations replace the last inserted argument with the last argument from + the previous command (so Alt+. Alt+. will insert the last argument of the + second to last history line). + + With an argument, the first time YankLastArg behaves like YankNthArg. A + negative argument on subsequent YankLastArg calls changes the direction + while going through history. For example, if you press Alt+. one too many + times, you can type Alt+- Alt+. to reverse the direction. + + Arguments are based on PowerShell tokens. + +- YankNthArg (Cmd: unbound Emacs: ) + + Insert the first argument (not the command name) of the previous command in + history. + + With an argument, insert the nth argument where 0 is typically the command. + Negative arguments start from the end. + + Arguments are based on PowerShell tokens. + +## Miscellaneous + +- Abort (Cmd: unbound Emacs: ) + + Abort the current action; for example, stop interactive history search. Does + not cancel input like CancelLine. + +- CharacterSearch (Cmd: Emacs: ) + + Read a key and search forwards for that character. With an argument, search + forwards for the nth occurrence of that argument. With a negative argument, + searches backwards. + +- CharacterSearchBackward (Cmd: Emacs: ) + + Like CharacterSearch, but searches backwards. With a negative argument, + searches forwards. + +- ClearScreen (Cmd: Emacs: ) + + Clears the screen and displays the current prompt and input at the top of + the screen. + +- DigitArgument (Cmd: unbound Emacs: ,,) + + Used to pass numeric arguments to functions like CharacterSearch or + YankNthArg. Alt+- toggles the argument to be negative/non-negative. To enter + 80 '*' characters, you could type Alt+8 Alt+0 *. + +- CaptureScreen (Cmd: unbound Emacs: unbound) + + Copies selected lines to the clipboard in both text and RTF formats. Use + up/down arrow keys to the first line to select, then + Shift+UpArrow/Shift+DownArrow to select multiple lines. After selecting, + press Enter to copy the text. Escape/Ctrl+C/Ctrl+G cancel the operation, so + nothing is copied to the clipboard. + +- InvokePrompt (Cmd: unbound Emacs: unbound) + + Erases the current prompt and calls the prompt function to redisplay the + prompt. Useful for custom key handlers that change state, such as changing + the current directory. + +- WhatIsKey (Cmd: Emacs: ) + + Read a key or chord and display the key binding. + +- ShowKeyBindings (Cmd: Emacs: ) + + Show all of the currently-bound keys. + +- ScrollDisplayUp (Cmd: Emacs: ) + + Scroll the display up one screen. + +- ScrollDisplayUpLine (Cmd: Emacs: ) + + Scroll the display up one line. + +- ScrollDisplayDown (Cmd: Emacs: ) + + Scroll the display down one screen. + +- ScrollDisplayDownLine (Cmd: Emacs: ) + + Scroll the display down one line. + +- ScrollDisplayTop (Cmd: unbound Emacs: ) + + Scroll the display to the top. + +- ScrollDisplayToCursor (Cmd: unbound Emacs: ) + + Scroll the display to the cursor. + +## Custom Key Bindings + +PSReadline supports custom key bindings using the cmdlet +Set-PSReadlineKeyHandler. Most custom key bindings call one of the above +functions, for example: + +```powershell +Set-PSReadlineKeyHandler -Key UpArrow -Function HistorySearchBackward ``` +You can bind a ScriptBlock to a key. The ScriptBlock can do virtually anything +you want. Some useful examples include: + +* edit the command line +* opening a new window (e.g. help) +* change directories without changing the command line + +The ScriptBlock is passed two arguments: + +* $key - A [ConsoleKeyInfo] that is the key that triggered the custom binding. + If you bind the same ScriptBlock to multiple keys and need to perform + different actions depending on the key, you can check $key. Many custom + bindings ignore this argument. +* $arg - An arbitrary argument. Most often, this would be an integer argument + that the user passes from the key bindings DigitArgument. If your binding + doesn't accept arguments, it's reasonable to ignore this argument. + +Let's take a look at an example that adds a command line to history without +executing it. This is useful when you realize you forgot to do something, but +don't want to re-enter the command line you've already entered. + +```powershell +Set-PSReadlineKeyHandler -Key Alt+w ` + -BriefDescription SaveInHistory ` + -LongDescription "Save current line in history but do not execute" ` + -ScriptBlock { + param($key, $arg) # The arguments are ignored in this example + + # GetBufferState gives us the command line (with the cursor position) + $line = $null + $cursor = $null + [PSConsoleUtilities.PSConsoleReadLine]::GetBufferState([ref]$line, + [ref]$cursor) + + # AddToHistory saves the line in history, but does not execute the line. + [PSConsoleUtilities.PSConsoleReadLine]::AddToHistory($line) + + # RevertLine is like pressing Escape. + [PSConsoleUtilities.PSConsoleReadLine]::RevertLine() +} +``` + +You can see many more examples in the file SamplePSReadlineProfile.ps1 which +is installed in the PSReadline module folder. + +Most key bindings will want to take advantage of some helper functions for +editing the command line those APIs are documented in the next section. + +## Custom Key Binding Support APIs + +The following functions are public in PSConsoleUtilities.PSConsoleReadline, +but cannot be directly bound to a key. Most are useful in custom key bindings. + +- void AddToHistory(string command) + + Add a command line to history without executing it. + +- void ClearKillRing() + + Clear the kill ring. This is mostly used for testing. + +- void Delete(int start, int length) + + Delete length characters from start. This operation supports undo and redo. + +void Ding() + + Perform the Ding action based on the user’s preference. + +- void GetBufferState([ref] string input, [ref] int cursor) +- void GetBufferState([ref] Ast ast, [ref] Token[] tokens, [ref] ParseError[] + parseErrors, [ref] int cursor) + + These two functions retrieve useful information about the current state of + the input buffer. The first is more commonly used for simple cases. The + second is used if your binding is doing something more advanced with the + Ast. + +- IEnumerable[PSConsoleUtilities.KeyHandler] GetKeyHandlers(bool includeBound, + bool includeUnbound) + + This function is used by Get-PSReadlineKeyHandler and probably isn't useful + in a custom key binding. + +- PSConsoleUtilities.PSConsoleReadlineOptions GetOptions() + + This function is used by Get-PSReadlineOption and probably isn't too useful + in a custom key binding. + +- void GetSelectionState([ref] int start, [ref] int length) + + If there is no selection on the command line, -1 is returned in both start + and length. If there is a selection on the command line, the start and + length of the selection are returned. + +- void Insert(char c) +- void Insert(string s) + + Insert a character or string at the cursor. This operation supports undo and + redo. + +- string ReadLine(runspace remoteRunspace, + System.Management.Automation.EngineIntrinsics engineIntrinsics) + + This is the main entry point to PSReadline. It does not support recursion, + so is not useful in a custom key binding. + +- void RemoveKeyHandler(string[] key) + + This function is used by Remove-PSReadlineKeyHandler and probably isn't too + useful in a custom key binding. + +- void Replace(int start, int length, string replacement) + + Replace some of the input. This operation supports undo and redo. This is + preferred over Delete followed by Insert because it is treated as a single + action for undo. + +- void SetCursorPosition(int cursor) + + Move the cursor to the given offset. Cursor movement is not tracked for + undo. + +- void SetOptions(PSConsoleUtilities.SetPSReadlineOption options) + + This function is a helper method used by the cmdlet Set-PSReadlineOption, + but might be useful to a custom key binding that wants to temporarily change + a setting. + +- bool TryGetArgAsInt(System.Object arg, [ref] int numericArg, + int defaultNumericArg) + + This helper method is used for custom bindings that honor DigitArgument. A + typical call looks like: + + ```powershell + [int]$numericArg = 0 + [PSConsoleUtilities.PSConsoleReadLine]::TryGetArgAsInt($arg, + [ref]$numericArg, 1) + ``` +## POWERSHELL COMPATIBILITY + +PSReadline requires PowerShell 3.0 or newer, and the console host. It +does not work in PowerShell ISE. + +## FEEDBACK AND CONTRIBUTING TO PSREADLINE + +Feel free to submit a pull request or submit feedback on the PSReadline +GitHub page (https://github.com/lzybkr/PSReadLine). + +## SEE ALSO + +PSReadline is heavily influenced by the GNU Readline library: +http://tiswww.case.edu/php/chet/readline/rltop.html + +[Get-PSReadlineKeyHandler](../../PSReadline/Get-PSReadlineKeyHandler.md) + +[Get-PSReadlineOption](../../PSReadline/Get-PSReadlineOption.md) + +[Remove-PSReadlineKeyHandler](../../PSReadline/Remove-PSReadlineKeyHandler.md) + +[Set-PSReadlineKeyHandler](../../PSReadline/Set-PSReadlineKeyHandler.md) + +[Set-PSReadlineOption](../../PSReadline/Set-PSReadlineOption.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_type_accelerators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_type_accelerators.md deleted file mode 100644 index c74bfdb2b108..000000000000 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_type_accelerators.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_Type_Accelerators ---- - -# about_Type_Accelerators -Insert introduction here. - -## Section Heading - Insert section body here. - -### Subsection Heading - Insert subsection body here. - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_windows_powershell_5.1.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_windows_powershell_5.1.md index 695415d38e56..7fc47e85d48f 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_windows_powershell_5.1.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_windows_powershell_5.1.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,282 +7,338 @@ title: about_Windows_PowerShell_5.0 --- # about_Windows_PowerShell_5.0 -``` -TOPIC - about_Windows_PowerShell_5.0 - -SHORT DESCRIPTION - Describes new features that are included in - Windows PowerShell 5.0. - -LONG DESCRIPTION - - Windows PowerShell 5.0 includes significant new features that extend its - use, improve its usability, and allow you to control and manage Windows-based - environments more easily and comprehensively. - - Windows PowerShell 5.0 is backward-compatible. Cmdlets, providers, modules, - snap-ins, scripts, functions, and profiles that were designed for Windows - PowerShell 4.0, Windows PowerShell 3.0, and Windows PowerShell 2.0 generally - work in Windows PowerShell 5.0 without changes. - - Windows PowerShell 5.0 is installed by default on Windows Server Technical - Preview and Windows Technical Preview. To install Windows PowerShell 5.0 on - Windows Server 2012 R2, Windows 8.1 Enterprise, or Windows 8.1 Pro, download - and install Windows Management Framework 5.0 Preview. - (http://www.microsoft.com/download/details.aspx?id=44070) - Be sure to read the download details, and meet all system requirements, - before you install Windows Management Framework 5.0 Preview. - - You can also read about changes to Windows PowerShell 5.0 in the Microsoft - TechNet topic, "What's New in Windows PowerShell." - (http://go.microsoft.com/fwlink/?LinkID=512808) - -NEW FEATURES - - New features in Windows PowerShell - - -- Starting in Windows PowerShell 5.0, you can develop by using classes, - by using formal syntax and semantics that are similar to other object-oriented - programming languages. Class, Enum, and other keywords have been added to the - Windows PowerShell language to support the new feature. For more information - about working with classes, see about_Classes. - -- In collaboration with Microsoft Research, a new cmdlet, ConvertFrom-String, - has been added. ConvertFrom-String lets you extract and parse structured - objects from the content of text strings. For more information, see - ConvertFrom-String. - -- A new module, Microsoft.PowerShell.Archive, includes cmdlets that let you - compress files and folders into archive (also known as ZIP) files, extract - files from existing ZIP files, and update ZIP files with newer versions - of files compressed within them. - -- A new module, OneGet, lets you discover and install software packages on - the Internet. The OneGet module is a manager or multiplexer of existing - package managers (also called package providers) to unify Windows package - management with a single Windows PowerShell interface. - -- A new module, PowerShellGet, lets you find, install, publish, and update - modules and DSC resources on the PowerShell Resource Gallery, or on an internal - module repository that you can set up by running the Register-PSRepository cmdlet. - -- New-Item, Remove-Item, and Get-ChildItem have been enhanced to support - creating and managing symbolic links. The ItemType parameter for New-Item - accepts a new value, SymbolicLink. Now you can create symbolic links in a - single line by running the New-Item cmdlet. - -- Windows PowerShell transcription has been improved to apply to all hosting - applications (such as Windows PowerShell ISE) in addition to the console host - (powershell.exe). Transcription options (including enabling a system-wide - transcript) can be configured by enabling the Turn on PowerShell Transcription - Group Policy setting, found in - Administrative Templates/Windows Components/Windows PowerShell. - -- A new detailed script tracing feature lets you enable detailed tracking and - analysis of Windows PowerShell scripting use on a system. After you enable - detailed script tracing, Windows PowerShell logs all script blocks to the - Event Tracing for Windows (ETW) event log, Microsoft-Windows-PowerShell/Operational. - -- Starting in Windows PowerShell 5.0, new Cryptographic Message Syntax cmdlets - support encryption and decryption of content by using the IETF standard format - for cryptographically protecting messages as documented by [RFC5652](https://tools.ietf.org/html/rfc5652). The Get-CmsMessage, Protect-CmsMessage, - and Unprotect-CmsMessage cmdlets have been added to the - Microsoft.PowerShell.Security module. - -- New cmdlets in the Microsoft.PowerShell.Utility module, Get-Runspace, - Debug-Runspace, Get-RunspaceDebug, Enable-RunspaceDebug, and - Disable-RunspaceDebug, let you set debug options on a runspace, and start - and stop debugging on a runspace. For debugging arbitrary runspaces—that is, - runspaces that are not the default runspace for a Windows PowerShell console - or Windows PowerShell ISE session—Windows PowerShell lets you set breakpoints - in a script, and have added breakpoints stop the script from running until - you can attach a debugger to debug the runspace script. Nested debugging - support for arbitrary runspaces has been added to the Windows PowerShell - script debugger for runspaces. - -- New cmdlets Enter-PSHostProcess and Exit-PSHostProcess let you debug - Windows PowerShell scripts in processes separate from the current process - that is running in the Windows PowerShell console. Run Enter-PSHostProcess - to enter, or attach to, a specific process ID, and then run Get-Runspace to - return the active runspaces within the process. Run Exit-PSHostProcess to - detach from the process when you are finished debugging the script within - the process. - -- A new Wait-Debugger cmdlet has been added to the Microsoft.PowerShell.Utility - module. You can run Wait-Debugger to stop a script in the debugger before - running the next statement in the script. - -- The Windows PowerShell Workflow debugger now supports command or tab completion, - and you can debug nested workflow functions. You can now press Ctrl+Break to - enter the debugger in a running script, in both local and remote sessions, and - in a workflow script. - -- A Debug-Job cmdlet has been added to the Microsoft.PowerShell.Core module to - debug running job scripts for Windows PowerShell Workflow, background, and - jobs running in remote sessions. - -- A new state, AtBreakpoint, has been added for Windows PowerShell jobs. The - AtBreakpoint state applies when a job is running a script that includes set - breakpoints, and the script has hit a breakpoint. When a job is stopped at a - debug breakpoint, you must debug the job by running the Debug-Job cmdlet. - -- Windows PowerShell 5.0 implements support for multiple versions of a single - Windows PowerShell module in the same folder in $PSModulePath. A - RequiredVersion property has been added to the ModuleSpecification class to - help you get the desired version of a module; this property is - mutually-exclusive with the ModuleVersion property. RequiredVersion is now - supported as part of the value of the FullyQualifiedName parameter of the - Get-Module, Import-Module, and Remove-Module cmdlets. - -- You can now perform module version validation by running the - Test-ModuleManifest cmdlet. - -- Results of the Get-Command cmdlet now display a Version column; a new Version - property has been added to the CommandInfo class. Get-Command shows commands - from multiple versions of the same module. The Version property is also part - of derived classes of CmdletInfo: CmdletInfo and ApplicationInfo. - -- A new Get-ItemPropertyValue cmdlet lets you get the value of a property without - using dot notation. For example, in older releases of Windows PowerShell, you - can run the following command to get the value of the Application Base property - of the PowerShellEngine registry key: (Get-ItemProperty -Path HKLM:\SOFTWARE\ - Microsoft\PowerShell\3\PowerShellEngine -Name ApplicationBase).ApplicationBase. - Starting in Windows PowerShell 5.0, you can run Get-ItemPropertyValue -Path HKLM: - \SOFTWARE\Microsoft\PowerShell\3\PowerShellEngine -Name ApplicationBase. - -- A new NetworkSwitch module contains cmdlets that enable you to apply switch, - virtual LAN (VLAN), and basic Layer 2 network switch port configuration to - Windows Server 2012 R2 (and later releases) logo-certified network switches. - -- The FullyQualifiedName parameter has been added to Import-Module and - Remove-Module cmdlets, to support storing multiple versions of a single module. - -- Save-Help, Update-Help, Import-PSSession, Export-PSSession, and Get-Command - have a new parameter, FullyQualifiedModule, of type ModuleSpecification. Add - this parameter to specify a module by its fully qualified name. - -- The value of $PSVersionTable.PSVersion has been updated to 5.0. - - New features in Windows PowerShell Desired State Configuration - - -- Windows PowerShell language enhancements let you define Windows PowerShell - Desired State Configuration (DSC) resources by using classes. - Import-DscResource is now a true dynamic keyword; Windows PowerShell parses - the specified module’s root module, searching for classes that contain the - DscResource attribute. You can now use classes to define DSC resources, - in which neither a MOF file nor a DSCResource subfolder in the module - folder is required. A Windows PowerShell module file can contain multiple - DSC resource classes. - -- A new parameter, ThrottleLimit, has been added to the following cmdlets in - the PSDesiredStateConfiguration module. Add the ThrottleLimit parameter - to specify the number of target computers or devices on which you want the - command to work at the same time. - -- Get-DscConfiguration - -- Get-DscConfigurationStatus - -- Get-DscLocalConfigurationManager - -- Restore-DscConfiguration - -- Test-DscConfiguration - -- Compare-DscConfiguration - -- Publish-DscConfiguration - -- Set-DscLocalConfigurationManager - -- Start-DscConfiguration - -- Update-DscConfiguration - -- With centralized DSC error reporting, rich error information is not only - logged in the event log, but it can be sent to a central location for later - analysis. You can use this central location to store DSC configuration errors - that have occurred for any server in their environment. After the report - server is defined in the meta-configuration, all errors are sent to the - report server, and then stored in a database. You can set up this functionality - regardless of whether or not a target node is configured to pull configurations - from a pull server. - -- Improvements to Windows PowerShell ISE ease DSC resource authoring. You can - now do the following. - -- List all DSC resources within a configuration or node block by entering - Ctrl+Space on a blank line within the block. - -- Automatic completion on resource properties of the enumeration type. - -- Automatic completion on the DependsOn property of DSC resources, based - on other resource instances in the configuration. - -- Improved tab completion of resource property values. - -- A new DscLocalConfigurationManager attribute designates a configuration block - as a meta-configuration, which is used to configure the DSC Local Configuration - Manager. This attribute restricts a configuration to containing only items - which configure the DSC Local Configuration Manager. During processing, - this configuration generates a *.meta.mof file that is then sent to the - appropriate target nodes by running the Set-DscLocalConfigurationManager cmdlet. - -- Partial configurations are now allowed in Windows PowerShell 5.0. You can - deliver configuration documents to a node in fragments. For a node to receive - multiple fragments of a configuration document, the node’s Local Configuration - Manager must be first set to specify the expected fragments. - -- Cross-computer synchronization is new in DSC in Windows PowerShell 5.0. By - using the built-in WaitFor* resources (WaitForAll, WaitForAny, and - WaitForSome), you can now specify dependencies across computers during - configuration runs, without external orchestrations. These resources provide - node-to-node synchronization by using CIM connections over the WS-Man protocol. - A configuration can wait for another computer’s specific resource state to change. - -- Just Enough Administration (JEA), a new delegation security feature, leverages - DSC and Windows PowerShell constrained runspaces to help secure enterprises - from data loss or compromise by employees, whether intentional or unintentional. - For more information about JEA, including where you can download the xJEA DSC - resource, see Just Enough Administration, Step by Step. - (http://ppe.blogs.technet.com/b/privatecloud/archive/2014/05/14/just-enough-administration-step-by-step.aspx) - -- The following new cmdlets have been added to the PSDesiredStateConfiguration - module. - -- A new Get-DscConfigurationStatus cmdlet gets high-level information about - configuration status from a target node. You can obtain the status of the - last, or of all configurations. - -- A new Compare-DscConfiguration cmdlet compares a specified configuration - with the actual state of one or more target nodes. - -- A new Publish-DscConfiguration cmdlet copies a configuration MOF file to - a target node, but does not apply the configuration. The configuration is - applied during the next consistency pass, or when you run the - Update-DscConfiguration cmdlet. - -- A new Test-DscConfiguration cmdlet lets you verify that a resulting - configuration matches the desired configuration, returning either True if - the configuration matches the desired configuration, or False if the actual - configuration does not match the desired configuration. - -- A new Update-DscConfiguration cmdlet forces a configuration to be processed. - If the Local Configuration Manager is in pull mode, the cmdlet gets the - configuration from the pull server before applying it. - - New features in Windows PowerShell ISE - -- You can now edit remote Windows PowerShell scripts and files in a local copy of - Windows PowerShell ISE, by running Enter-PSSession to start a remote session on - the computer that’s storing the files you want to edit, and then running PSEdit - . This feature eases editing Windows - PowerShell files that are stored on the Server Core installation option of - Windows Server, where Windows PowerShell ISE cannot run. - -- The Start-Transcript cmdlet is now supported in Windows PowerShell ISE. - -- You can now debug remote scripts in Windows PowerShell ISE. - -- A new menu command, Break All (Ctrl+B), breaks into the debugger for both - local and remotely-running scripts. - - New features in Windows PowerShell Web Services (Management OData IIS Extension) - -- Starting in Windows PowerShell 5.0, you can generate a set of Windows PowerShell - cmdlets based on the functionality exposed by a given OData endpoint, by - running the Export-ODataEndpointProxy cmdlet. - - Notable bug fixes in Windows PowerShell 5.0 - -- Windows PowerShell 5.0 includes a new COM implementation, which offers - significant performance improvements when you are working with COM objects. - For a video demonstration of the effect, see Com_Perf_Improvements. - (http://1drv.ms/1qu3UPZ) - - For more information about Windows PowerShell 5.0, visit the following web - sites: - - -- Windows PowerShell Scripting website - http://go.microsoft.com/fwlink/?LinkID=106031 - - -- Windows PowerShell Team Blog: - http://go.microsoft.com/fwlink/?LinkId=143696 - - -- Windows PowerShell Web Access - http://technet.microsoft.com/library/hh831611.aspx - -SEE ALSO - about_Classes - about_Debuggers - about_Desired_State_Configuration - about_Scheduled_Jobs - about_Updatable_Help - Add-Computer - ConvertFrom-String - Debug-Job - Disable-JobTrigger - Enable-JobTrigger - Get-Module - Get-Process - Invoke-RestMethod - New-JobTrigger - Register-ScheduledJob - Remove-Computer - Save-Help - Set-ExecutionPolicy - Set-JobTrigger - Set-ScheduledJob - Update-Help - -KEYWORDS - What's New in Windows PowerShell 5.0 - -``` +## SHORT DESCRIPTION + +Describes new features that are included in Windows PowerShell 5.0. + +## LONG DESCRIPTION + +Windows PowerShell 5.0 includes significant new features that extend its use, +improve its usability, and allow you to control and manage Windows-based +environments more easily and comprehensively. + +Windows PowerShell 5.0 is backward-compatible. Cmdlets, providers, modules, +snap-ins, scripts, functions, and profiles that were designed for Windows +PowerShell 4.0, Windows PowerShell 3.0, and Windows PowerShell 2.0 generally +work in Windows PowerShell 5.0 without changes. + +Windows PowerShell 5.0 is installed by default on Windows Server Technical +Preview and Windows Technical Preview. To install Windows PowerShell 5.0 on +Windows Server 2012 R2, Windows 8.1 Enterprise, or Windows 8.1 Pro, download +and install +[Windows Management Framework 5.0](/powershell/scripting/whats-new/what-s-new-with-powershell). +Be sure to read the download details, and meet all system requirements, before +you install Windows Management Framework 5.0 Preview. + +You can also read about changes to Windows PowerShell 5.0 in +[What's New in Windows PowerShell](/powershell/scripting/whats-new/what-s-new-with-powershell). + +## NEW FEATURES + +### New features in Windows PowerShell + +- Starting in Windows PowerShell 5.0, you can develop by using classes, by + using formal syntax and semantics that are similar to other object-oriented + programming languages. Class, Enum, and other keywords have been added to the + Windows PowerShell language to support the new feature. For more information + about working with classes, see about_Classes. + +- In collaboration with Microsoft Research, a new cmdlet, ConvertFrom-String, + has been added. ConvertFrom-String lets you extract and parse structured + objects from the content of text strings. For more information, see + ConvertFrom-String. + +- A new module, Microsoft.PowerShell.Archive, includes cmdlets that let you + compress files and folders into archive (also known as ZIP) files, extract + files from existing ZIP files, and update ZIP files with newer versions of + files compressed within them. + +- A new module, OneGet, lets you discover and install software packages on the + Internet. The OneGet module is a manager or multiplexer of existing package + managers (also called package providers) to unify Windows package management + with a single Windows PowerShell interface. + +- A new module, PowerShellGet, lets you find, install, publish, and update + modules and DSC resources on the PowerShell Resource Gallery, or on an + internal module repository that you can set up by running the + Register-PSRepository cmdlet. + +- New-Item, Remove-Item, and Get-ChildItem have been enhanced to support + creating and managing symbolic links. The ItemType parameter for New-Item + accepts a new value, SymbolicLink. Now you can create symbolic links in a + single line by running the New-Item cmdlet. + +- Windows PowerShell transcription has been improved to apply to all hosting + applications (such as Windows PowerShell ISE) in addition to the console + host (powershell.exe). Transcription options (including enabling a + system-wide transcript) can be configured by enabling the Turn on PowerShell + Transcription Group Policy setting, found in Administrative + Templates/Windows Components/Windows PowerShell. + +- A new detailed script tracing feature lets you enable detailed tracking and + analysis of Windows PowerShell scripting use on a system. After you enable + detailed script tracing, Windows PowerShell logs all script blocks to the + Event Tracing for Windows (ETW) event log, + Microsoft-Windows-PowerShell/Operational. + +- Starting in Windows PowerShell 5.0, new Cryptographic Message Syntax cmdlets + support encryption and decryption of content by using the IETF standard + format for cryptographically protecting messages as documented by + [RFC5652](https://tools.ietf.org/html/rfc5652). The Get-CmsMessage, + Protect-CmsMessage, and Unprotect-CmsMessage cmdlets have been added to the + Microsoft.PowerShell.Security module. + +- New cmdlets in the Microsoft.PowerShell.Utility module, Get-Runspace, + Debug-Runspace, Get-RunspaceDebug, Enable-RunspaceDebug, and + Disable-RunspaceDebug, let you set debug options on a runspace, and start + and stop debugging on a runspace. For debugging arbitrary runspaces—that is, + runspaces that are not the default runspace for a Windows PowerShell console + or Windows PowerShell ISE session—Windows PowerShell lets you set + breakpoints in a script, and have added breakpoints stop the script from + running until you can attach a debugger to debug the runspace script. Nested + debugging support for arbitrary runspaces has been added to the Windows + PowerShell script debugger for runspaces. + +- New cmdlets Enter-PSHostProcess and Exit-PSHostProcess let you debug Windows + PowerShell scripts in processes separate from the current process that is + running in the Windows PowerShell console. Run Enter-PSHostProcess to enter, + or attach to, a specific process ID, and then run Get-Runspace to return the + active runspaces within the process. Run Exit-PSHostProcess to detach from + the process when you are finished debugging the script within the process. + +- A new Wait-Debugger cmdlet has been added to the + Microsoft.PowerShell.Utility module. You can run Wait-Debugger to stop a + script in the debugger before running the next statement in the script. + +- The Windows PowerShell Workflow debugger now supports command or tab + completion, and you can debug nested workflow functions. You can now press + Ctrl+Break to enter the debugger in a running script, in both local and + remote sessions, and in a workflow script. + +- A Debug-Job cmdlet has been added to the Microsoft.PowerShell.Core module to + debug running job scripts for Windows PowerShell Workflow, background, and + jobs running in remote sessions. + +- A new state, AtBreakpoint, has been added for Windows PowerShell jobs. The + AtBreakpoint state applies when a job is running a script that includes set + breakpoints, and the script has hit a breakpoint. When a job is stopped at a + debug breakpoint, you must debug the job by running the Debug-Job cmdlet. + +- Windows PowerShell 5.0 implements support for multiple versions of a single + Windows PowerShell module in the same folder in $PSModulePath. A + RequiredVersion property has been added to the ModuleSpecification class to + help you get the desired version of a module; this property is + mutually-exclusive with the ModuleVersion property. RequiredVersion is now + supported as part of the value of the FullyQualifiedName parameter of the + Get-Module, Import-Module, and Remove-Module cmdlets. + +- You can now perform module version validation by running the + Test-ModuleManifest cmdlet. + +- Results of the Get-Command cmdlet now display a Version column; a new + Version property has been added to the CommandInfo class. Get-Command shows + commands from multiple versions of the same module. The Version property is + also part of derived classes of CmdletInfo: CmdletInfo and ApplicationInfo. + +- A new Get-ItemPropertyValue cmdlet lets you get the value of a property + without using dot notation. For example, in older releases of Windows + PowerShell, you can run the following command to get the value of the + Application Base property of the PowerShellEngine registry key: + + ```powershell + $keypath = 'HKLM:\SOFTWARE\Microsoft\PowerShell\3\PowerShellEngine' + (Get-ItemProperty -Path $keypath -Name ApplicationBase).ApplicationBase + ``` + + Starting in Windows PowerShell 5.0, you can run + + ```powershell + $keypath = 'HKLM:\SOFTWARE\Microsoft\PowerShell\3\PowerShellEngine' + Get-ItemPropertyValue -Path $keypath -Name ApplicationBase + ``` + +- A new NetworkSwitch module contains cmdlets that enable you to apply switch, + virtual LAN (VLAN), and basic Layer 2 network switch port configuration to + Windows Server 2012 R2 (and later releases) logo-certified network switches. + +- The FullyQualifiedName parameter has been added to Import-Module and + Remove-Module cmdlets, to support storing multiple versions of a single + module. + +- Save-Help, Update-Help, Import-PSSession, Export-PSSession, and Get-Command + have a new parameter, FullyQualifiedModule, of type ModuleSpecification. Add + this parameter to specify a module by its fully qualified name. + +- The value of $PSVersionTable.PSVersion has been updated to 5.0. + +### New features in Windows PowerShell Desired State Configuration + +- Windows PowerShell language enhancements let you define Windows PowerShell + Desired State Configuration (DSC) resources by using classes. + Import-DscResource is now a true dynamic keyword; Windows PowerShell parses + the specified module’s root module, searching for classes that contain the + DscResource attribute. You can now use classes to define DSC resources, in + which neither a MOF file nor a DSCResource subfolder in the module folder is + required. A Windows PowerShell module file can contain multiple DSC resource + classes. + +- A new parameter, ThrottleLimit, has been added to the following cmdlets in + the PSDesiredStateConfiguration module. Add the ThrottleLimit parameter to + specify the number of target computers or devices on which you want the + command to work at the same time. + + - Get-DscConfiguration + - Get-DscConfigurationStatus + - Get-DscLocalConfigurationManager + - Restore-DscConfiguration + - Test-DscConfiguration + - Compare-DscConfiguration + - Publish-DscConfiguration + - Set-DscLocalConfigurationManager + - Start-DscConfiguration + - Update-DscConfiguration + +- With centralized DSC error reporting, rich error information is not only + logged in the event log, but it can be sent to a central location for later + analysis. You can use this central location to store DSC configuration + errors that have occurred for any server in their environment. After the + report server is defined in the meta-configuration, all errors are sent to + the report server, and then stored in a database. You can set up this + functionality regardless of whether or not a target node is configured to + pull configurations from a pull server. + +- Improvements to Windows PowerShell ISE ease DSC resource authoring. You can + now do the following. + - List all DSC resources within a configuration or node block by entering + Ctrl+Space on a blank line within the block. + - Automatic completion on resource properties of the enumeration type. + - Automatic completion on the DependsOn property of DSC resources, based on + other resource instances in the configuration. + - Improved tab completion of resource property values. + +- A new DscLocalConfigurationManager attribute designates a configuration + block as a meta-configuration, which is used to configure the DSC Local + Configuration Manager. This attribute restricts a configuration to + containing only items which configure the DSC Local Configuration Manager. + During processing, this configuration generates a *.meta.mof file that is + then sent to the appropriate target nodes by running the + Set-DscLocalConfigurationManager cmdlet. + +- Partial configurations are now allowed in Windows PowerShell 5.0. You can + deliver configuration documents to a node in fragments. For a node to + receive multiple fragments of a configuration document, the node’s Local + Configuration Manager must be first set to specify the expected fragments. + +- Cross-computer synchronization is new in DSC in Windows PowerShell 5.0. By + using the built-in WaitFor* resources (WaitForAll, WaitForAny, and + WaitForSome), you can now specify dependencies across computers during + configuration runs, without external orchestrations. These resources provide + node-to-node synchronization by using CIM connections over the WS-Man + protocol. A configuration can wait for another computer’s specific resource + state to change. + +- Just Enough Administration (JEA), a new delegation security feature, + leverages DSC and Windows PowerShell constrained runspaces to help secure + enterprises from data loss or compromise by employees, whether intentional + or unintentional. For more information about JEA, including where you can + download the xJEA DSC resource, see [Just Enough Administration](/powershell/jea/overview). + +- The following new cmdlets have been added to the PSDesiredStateConfiguration + module. + - A new Get-DscConfigurationStatus cmdlet gets high-level information about + configuration status from a target node. You can obtain the status of the + last, or of all configurations. + - A new Compare-DscConfiguration cmdlet compares a specified configuration + with the actual state of one or more target nodes. + - A new Publish-DscConfiguration cmdlet copies a configuration MOF file to a + target node, but does not apply the configuration. The configuration is + applied during the next consistency pass, or when you run the + Update-DscConfiguration cmdlet. + - A new Test-DscConfiguration cmdlet lets you verify that a resulting + configuration matches the desired configuration, returning either True if + the configuration matches the desired configuration, or False if the actual + configuration does not match the desired configuration. + - A new Update-DscConfiguration cmdlet forces a configuration to be + processed. If the Local Configuration Manager is in pull mode, the cmdlet + gets the configuration from the pull server before applying it. + +### New features in Windows PowerShell ISE + +- You can now edit remote Windows PowerShell scripts and files in a local copy + of Windows PowerShell ISE, by running Enter-PSSession to start a remote + session on the computer that’s storing the files you want to edit, and then + running PSEdit . This feature eases + editing Windows PowerShell files that are stored on the Server Core + installation option of Windows Server, where Windows PowerShell ISE cannot + run. +- The Start-Transcript cmdlet is now supported in Windows PowerShell ISE. +- You can now debug remote scripts in Windows PowerShell ISE. +- A new menu command, Break All (Ctrl+B), breaks into the debugger for both + local and remotely-running scripts. + +### New features in Windows PowerShell Web Services (Management OData IIS Extension) + +- Starting in Windows PowerShell 5.0, you can generate a set of Windows + PowerShell cmdlets based on the functionality exposed by a given OData + endpoint, by running the Export-ODataEndpointProxy cmdlet. + +### Notable bug fixes in Windows PowerShell 5.0 + +- Windows PowerShell 5.0 includes a new COM implementation, which offers + significant performance improvements when you are working with COM objects. + For a video demonstration of the effect, see + [Com_Perf_Improvements](http://1drv.ms/1qu3UPZ). + +For more information about Windows PowerShell 5.0, visit the following web +sites: + +- [Windows PowerShell Scripting website](/powershell/scripting/powershell-scripting) +- [Windows PowerShell Team Blog](http://go.microsoft.com/fwlink/?LinkId=143696) +- [Windows PowerShell Web Access](/powershell/scripting/core-powershell/web-access) + +## SEE ALSO + +[about_Classes](about_Classes.md) + +[about_Debuggers](about_Debuggers.md) + +[about_Desired_State_Configuration](about_desiredstateconfiguration.md) + +[about_Updatable_Help](about_Updatable_Help.md) + +[Save-Help](../Save-Help.md) + +[Get-Module](../Get-Module.md) + +[Debug-Job](../Debug-Job.md) + +[Update-Help](../Update-Help.md) + +[Get-Process](../../Microsoft.PowerShell.Management/Get-Process.md) + +[Remove-Computer](../../Microsoft.PowerShell.Management/Remove-Computer.md) + +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) + +[Add-Computer](../../Microsoft.PowerShell.Management/Add-Computer.md) + +[ConvertFrom-String](../../Microsoft.PowerShell.Utility/ConvertFrom-String.md) + +[Invoke-RestMethod](../../Microsoft.PowerShell.Utility/Invoke-RestMethod.md) + +[Set-JobTrigger](../../PSScheduledJob/Set-JobTrigger.md) + +[Set-ScheduledJob](../../PSScheduledJob/Set-ScheduledJob.md) + +[New-JobTrigger](../../PSScheduledJob/New-JobTrigger.md) + +[Register-ScheduledJob](../../PSScheduledJob/Register-ScheduledJob.md) + +[Enable-JobTrigger](../../PSScheduledJob/Enable-JobTrigger.md) + +[Disable-JobTrigger](../../PSScheduledJob/Disable-JobTrigger.md) + +## KEYWORDS + +What's New in Windows PowerShell 5.0 \ No newline at end of file From c4bc8611f8ae8b84c76309bb10f023e73c61dff0 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 4 Jan 2018 15:17:35 -0800 Subject: [PATCH 155/188] Reformatting v6 About_ topics missed in first pass (#2010) * v6 about scrub missed files * fixing broken links and removing non-v6 content --- .../About/about_Environment_Variables.md | 2 +- .../About/about_For.md | 2 +- .../About/about_Functions_Advanced_Methods.md | 269 +++--- .../about_Functions_OutputTypeAttribute.md | 54 +- .../About/about_Language_Keywords.md | 2 +- .../About/about_Modules.md | 12 +- .../About/about_PSSessions.md | 189 +++-- .../About/about_PSSnapins.md | 181 ---- .../About/about_PackageManagement.md | 22 +- .../About/about_Parameters.md | 237 +++--- .../About/about_PowerShell_Ise_exe.md | 109 --- .../About/about_Providers.md | 301 +++---- .../About/about_Quoting_Rules.md | 257 +++--- .../About/about_Remote.md | 238 +++--- .../About/about_Remote_Requirements.md | 244 +++--- .../About/about_Remote_Variables.md | 148 ++-- .../About/about_Requires.md | 7 +- .../About/about_Reserved_Words.md | 2 +- .../About/about_Return.md | 107 ++- .../About/about_Run_With_PowerShell.md | 68 +- .../About/about_Scopes.md | 600 +++++++------- .../about_Script_Internationalization.md | 298 ++++--- .../about_Session_Configuration_Files.md | 506 ++++++------ .../About/about_Signing.md | 326 ++++---- .../About/about_Splatting.md | 137 ++- .../About/about_Switch.md | 14 +- .../About/about_Transactions.md | 780 ------------------ .../About/about_Updatable_Help.md | 668 +++++++-------- .../About/about_WMI.md | 89 -- .../About/about_WMI_Cmdlets.md | 223 ----- .../About/about_WQL.md | 739 ----------------- .../About/about_WS-Management_Cmdlets.md | 195 ----- .../About/about_hidden.md | 37 +- .../About/about_logical_operators.md | 63 +- .../About/about_psconsolehostreadline.md | 55 ++ .../About/about_psreadline.md | 674 +++++++++++++++ .../About/about_pwsh.md | 184 +++-- 37 files changed, 3302 insertions(+), 4737 deletions(-) delete mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_PSSnapins.md delete mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Ise_exe.md delete mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_Transactions.md delete mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_WMI.md delete mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md delete mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_WQL.md delete mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md create mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md create mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_psreadline.md diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index 900e10daf0c5..700cb3bc71ca 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -305,5 +305,5 @@ For more information, see [about_Modules](about_Modules.md). ## SEE ALSO -- [Environment (provider)](../../Microsoft.PowerShell.Core/Providers/Environment-Provider.md) +- [Environment (provider)](../Providers/Environment-Provider.md) - [about_Modules](about_Modules.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_For.md b/reference/6/Microsoft.PowerShell.Core/About/about_For.md index c8343e7483e3..5c8f723bb156 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_For.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_For.md @@ -25,7 +25,7 @@ all the values in an array, consider using a Foreach statement. The following shows the For statement syntax. ```powershell -for (>init>; ; ) +for (; ; ) {} ``` diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md b/reference/6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md index 3e4a5424b207..9dd552a11e64 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,77 +7,71 @@ title: about_Functions_Advanced_Methods --- # About Functions Advanced Methods -## about_Functions_Advanced_Methods +## SHORT DESCRIPTION -# SHORT DESCRIPTION - -Describes how functions that specify the `CmdletBinding` attribute can use -the methods and properties that are available to compiled cmdlets. +Describes how functions that specify the `CmdletBinding` attribute can use the +methods and properties that are available to compiled cmdlets. # LONG DESCRIPTION Functions that specify the `CmdletBinding` attribute can access a number of -methods and properties through the `$pscmdlet` variable. These methods -include the following methods: +methods and properties through the `$pscmdlet` variable. These methods include +the following methods: - Input-processing methods that compiled cmdlets use to do their work. - - The `ShouldProcess` and `ShouldContinue` methods that are used to get -user feedback before an action is performed. - + user feedback before an action is performed. - The `ThrowTerminatingError` method for generating error records. - - Several Write methods that return different types of output. All the methods and properties of the `PSCmdlet` class are available to -advanced functions. For more information about these methods and -properties, see `System.Management.Automation.PSCmdlet` in the MSDN -(Microsoft Developer Network) library at -http://go.microsoft.com/fwlink/?LinkId=142139. - -# Input Processing Methods - -The methods described in this section are referred to as the input -processing methods. For functions, these three methods are represented -by the `Begin`, `Process`, and `End` blocks of the function. Each function -must include one or more of these blocks. The Windows PowerShell runtime -uses the code within these blocks when it is running a function. (These -blocks are also available to functions that do not use the `CmdletBinding` -attribute.) - -## Begin +advanced functions. For more information about these methods and properties, +see [`System.Management.Automation.PSCmdlet`](http://go.microsoft.com/fwlink/?LinkId=142139) in the MSDN library. + +### Input Processing Methods + +The methods described in this section are referred to as the input processing +methods. For functions, these three methods are represented by the `Begin`, +`Process`, and `End` blocks of the function. Each function must include one or +more of these blocks. The Windows PowerShell runtime uses the code within +these blocks when it is running a function. (These blocks are also available +to functions that do not use the `CmdletBinding` attribute.) + +#### Begin + This block is used to provide optional one-time preprocessing for the -function. The Windows PowerShell runtime uses the code in this block one -time for each instance of the function in the pipeline. - -## Process -This block is used to provide record-by-record processing for the -function. This block might be used any number of times, or not at all, -depending on the input to the function. For example, if the function is -the first command in the pipeline, the `Process` block will be used one -time. If the function is not the first command in the pipeline, the -`Process` block is used one time for every input that the function -receives from the pipeline. If there is no pipeline input, the `Process` -block is not used. - -This block must be defined if a function parameter is set to accept -pipeline input. If this block is not defined and the parameter accepts -input from the pipeline, the function will miss the values that are -passed to the function through the pipeline. +function. The Windows PowerShell runtime uses the code in this block one time +for each instance of the function in the pipeline. + +#### Process + +This block is used to provide record-by-record processing for the function. +This block might be used any number of times, or not at all, depending on the +input to the function. For example, if the function is the first command in +the pipeline, the `Process` block will be used one time. If the function is +not the first command in the pipeline, the `Process` block is used one time +for every input that the function receives from the pipeline. If there is no +pipeline input, the `Process` block is not used. + +This block must be defined if a function parameter is set to accept pipeline +input. If this block is not defined and the parameter accepts input from the +pipeline, the function will miss the values that are passed to the function +through the pipeline. Also, when the function supports confirmation requests (when the `SupportsShouldProcess` parameter of the Parameter attribute is set to -`$True`), the call to the `ShouldProcess` method must be made from within -the Process block. +`$True`), the call to the `ShouldProcess` method must be made from within the +Process block. + +#### End -## End -This block is used to provide optional one-time post-processing for -the function. +This block is used to provide optional one-time post-processing for the +function. -The following example shows the outline of a function that contains a -`Begin` block for one-time preprocessing, a `Process` block for multiple -record processing, and an `End` block for one-time post-processing. +The following example shows the outline of a function that contains a `Begin` +block for one-time preprocessing, a `Process` block for multiple record +processing, and an `End` block for one-time post-processing. ```powershell Function Test-ScriptCmdlet @@ -90,119 +84,125 @@ Function Test-ScriptCmdlet } ``` -# Confirmation Methods +### Confirmation Methods + +#### ShouldProcess -## ShouldProcess This method is called to request confirmation from the user before the -function performs an action that would change the system. The function -can continue based on the Boolean value returned by the method. This -method can be called only from within the `Process{}` block of the -function. And, the `CmdletBinding` attribute must declare that the -function supports `ShouldProcess` (as shown in the previous example). +function performs an action that would change the system. The function can +continue based on the Boolean value returned by the method. This method can be +called only from within the `Process{}` block of the function. And, the +`CmdletBinding` attribute must declare that the function supports +`ShouldProcess` (as shown in the previous example). For more information about this method, see -`System.Management.Automation.Cmdlet.ShouldProcess` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142142. +[`System.Management.Automation.Cmdlet.ShouldProcess`](http://go.microsoft.com/fwlink/?LinkId=142142) +in the MSDN library. For more information about how to request confirmation, see -"Requesting Confirmation" in the MSDN library at -http://go.microsoft.com/fwlink/?LinkID=136658. +[Requesting Confirmation](http://go.microsoft.com/fwlink/?LinkID=136658) +in the MSDN library. + +#### ShouldContinue -## ShouldContinue -This method is called to request a second confirmation message. It -should be called when the `ShouldProcess` method returns `$true`. For more -information about this method, see -`System.Management.Automation.Cmdlet.ShouldContinue` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142143. +This method is called to request a second confirmation message. It should be +called when the `ShouldProcess` method returns `$true`. For more information +about this method, see `System.Management.Automation.Cmdlet.ShouldContinue` in +the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142143. -# Error Methods +### Error Methods Functions can call two different methods when errors occur. When a -nonterminating error occurs, the function should call the `WriteError` -method, which is described in the "Write Methods" section. When a -terminating error occurs and the function cannot continue, it should call -the `ThrowTerminatingError` method. You can also use the `Throw` statement for +nonterminating error occurs, the function should call the `WriteError` method, +which is described in the "Write Methods" section. When a terminating error +occurs and the function cannot continue, it should call the +`ThrowTerminatingError` method. You can also use the `Throw` statement for terminating errors and the `Write-Error` cmdlet for nonterminating errors. -For more information, see `System.Management.Automation.Cmdlet.ThrowTerminatingError` -in the MSDN libray at -http://go.microsoft.com/fwlink/?LinkId=142144. +For more information, see +[`System.Management.Automation.Cmdlet.ThrowTerminatingError`](http://go.microsoft.com/fwlink/?LinkId=142144) +in the MSDN libray. -# Write Methods +### Write Methods -A function can call the following methods to return different types of -output. Notice that not all the output goes to the next command in the -pipeline. You can also use the various Write cmdlets, such as -Write-Error. +A function can call the following methods to return different types of output. +Notice that not all the output goes to the next command in the pipeline. You +can also use the various Write cmdlets, such as Write-Error. + +#### WriteCommandDetail -## WriteCommandDetail For information about the `WriteCommandDetails` method, see -`System.Management.Automation.Cmdlet.WriteCommandDetail` in the MSDN -library at http://go.microsoft.com/fwlink/?LinkId=142155. - -## WriteDebug -To provide information that can be used to troubleshoot a function, -make the function call the `WriteDebug` method. This displays debug -messages to the user. For more information, see -`System.Management.Automation.Cmdlet.WriteDebug` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142156. - -## WriteError -Functions should call this method when nonterminating errors occur and -the function is designed to continue processing records. For more -information, see `System.Management.Automation.Cmdlet.WriteError` in the -MSDN library at http://go.microsoft.com/fwlink/?LinkId=142157. +[`System.Management.Automation.Cmdlet.WriteCommandDetail`](http://go.microsoft.com/fwlink/?LinkId=142155) +in the MSDN library. + +#### WriteDebug + +To provide information that can be used to troubleshoot a function, make the +function call the `WriteDebug` method. This displays debug messages to the +user. For more information, see +[`System.Management.Automation.Cmdlet.WriteDebug`](http://go.microsoft.com/fwlink/?LinkId=142156) +in the MSDN library. + +#### WriteError + +Functions should call this method when nonterminating errors occur and the +function is designed to continue processing records. For more information, see +[`System.Management.Automation.Cmdlet.WriteError`](http://go.microsoft.com/fwlink/?LinkId=142157) +in the MSDN library. Note: If a terminating error occurs, the function should call the `ThrowTerminatingError` method. -## WriteObject -This method allows the function to send an object to the next command in -the pipeline. In most cases, this is the method to use when the function -returns data. For more information, see -`System.Management.Automation.PSCmdlet.WriteObject` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142158. - -## WriteProgress -For functions whose actions take a long time to complete, this method -allows the function to call the `WriteProgress` method so that progress -information is displayed. For example, you can display the percent -completed. For more information, see -`System.Management.Automation.PSCmdlet.WriteProgress` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142160. - -## WriteVerbose -To provide detailed information about what the function is doing, make -the function call the `WriteVerbose` method to display verbose messages to -the user. By default, verbose messages are not displayed. For more -information, see `System.Management.Automation.PSCmdlet.WriteVerbose` -in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142162. - -## WriteWarning -To provide information about conditions that may cause unexpected -results, make the function call the WriteWarning method to display -warning messages to the user. By default, warning messages are displayed. -For more information, see -`System.Management.Automation.PSCmdlet.WriteWarning` in the MSDN library -at http://go.microsoft.com/fwlink/?LinkId=142164. +#### WriteObject + +This method allows the function to send an object to the next command in the +pipeline. In most cases, this is the method to use when the function returns +data. For more information, see +[`System.Management.Automation.PSCmdlet.WriteObject`](http://go.microsoft.com/fwlink/?LinkId=142158) +in the MSDN library. + +#### WriteProgress + +For functions whose actions take a long time to complete, this method allows +the function to call the `WriteProgress` method so that progress information +is displayed. For example, you can display the percent completed. For more +information, see [`System.Management.Automation.PSCmdlet.WriteProgress`](http://go.microsoft.com/fwlink/?LinkId=142160) +in the MSDN library. + +#### WriteVerbose + +To provide detailed information about what the function is doing, make the +function call the `WriteVerbose` method to display verbose messages to the +user. By default, verbose messages are not displayed. For more information, +see +[`System.Management.Automation.PSCmdlet.WriteVerbose`](http://go.microsoft.com/fwlink/?LinkId=142162) +in the MSDN library. + +#### WriteWarning + +To provide information about conditions that may cause unexpected results, +make the function call the WriteWarning method to display warning messages to +the user. By default, warning messages are displayed. For more information, +see [`System.Management.Automation.PSCmdlet.WriteWarning`](http://go.microsoft.com/fwlink/?LinkId=142164) +in the MSDN library. Note: You can also display warning messages by configuring the `WarningPreference` variable or by using the `Verbose` and `Debug` command-line options. -# Other Methods and Properties +### Other Methods and Properties For information about the other methods and properties that can be accessed through the `$PSCmdlet` variable, see -`System.Management.Automation.PSCmdlet` in the MSDN library at -http://go.microsoft.com/fwlink/?LinkId=142139. +[`System.Management.Automation.PSCmdlet`](http://go.microsoft.com/fwlink/?LinkId=142139) +in the MSDN library. For example, the `ParameterSetName` property allows you to see the parameter set that is being used. Parameter sets allow you to create a function that -performs different tasks based on the parameters that are specified when -the function is run. +performs different tasks based on the parameters that are specified when the +function is run. -# SEE ALSO +## SEE ALSO [about_Functions](about_Functions.md) @@ -213,4 +213,3 @@ the function is run. [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) [about_Functions_OutputTypeAttribute](about_Functions_OutputTypeAttribute.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md b/reference/6/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md index 546fe9f1e0aa..f5f40dd0d876 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Functions_OutputTypeAttribute.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,15 +7,13 @@ title: about_Functions_OutputTypeAttribute --- # About Functions OutputTypeAttribute -## about_Functions_OutputTypeAttribute - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes an attribute that reports the type of object that the function returns. -# LONG DESCRIPTION +## LONG DESCRIPTION The OutputType attribute lists the .NET types of objects that the functions returns. You can use its optional ParameterSetName parameter to list different @@ -32,25 +30,27 @@ The OutputType attribute value is only a documentation note. It is not derived from the function code or compared to the actual function output. As such, the value might be inaccurate. -# SYNTAX +## SYNTAX The OutputType attribute of functions has the following syntax: -```powershell +``` [OutputType([], ParameterSetName="")] [OutputType("", ParameterSetName="")] ``` + The ParameterSetName parameter is optional. You can list multiple types in the OutputType attribute. -```powershell +``` [OutputType([],[],[])] ``` + You can use the ParameterSetName parameter to indicate that different parameter sets return different types. -```powershell +``` [OutputType([], ParameterSetName="","")] [OutputType([], ParameterSetName="")] ``` @@ -80,9 +80,11 @@ function AdvancedFunction1 [OutputType([])] Param ( [parameter(Mandatory=$true)] - [String[]] $Parameter1 + [String[]] + $Parameter1 ) - + + } @@ -92,16 +94,17 @@ function AdvancedFunction2 [OutputType([])] Param ( [parameter(Mandatory=$true)] - [String[]] $Parameter1 + [String[]] + $Parameter1 ) + } ``` # EXAMPLES - The following function uses the OutputType attribute to indicate that it returns a string value. @@ -111,13 +114,13 @@ function Send-Greeting [OutputType([String])] Param ($Name) - Hello, $Name + "Hello, $Name" } ``` To see the resulting output type property, use the Get-Command cmdlet. -```bash +``` PS C:> (Get-Command Send-Greeting).OutputType Name Type @@ -139,12 +142,15 @@ function Get-User Param ( [parameter(Mandatory=$true, ParameterSetName="ID")] - [Int[]] $UserID, + [Int[]] + $UserID, [parameter(Mandatory=$true, ParameterSetName="Name")] - [String[]] $UserName + [String[]] + $UserName ) + } ``` @@ -160,19 +166,18 @@ that it returns a System.DateTime object. function Get-Time { [OutputType([DateTime])] - Param - ( + Param ( [parameter(Mandatory=$true)] - [Datetime] $DateTime + [Datetime]$DateTime ) - + $DateTime.ToShortTimeString() } ``` The Get-Type method confirms that the function returns a string. -```bash +``` PS C:> (Get-Time -DateTime (Get-Date)).Gettype().FullName System.String ``` @@ -180,7 +185,7 @@ System.String However, the OutputType property, which gets its value from the OutputType attribute, reports that the function returns a DateTime object. -```bash +``` PS C:> (Get-Command Get-Time).OutputType Name Type @@ -188,7 +193,7 @@ Name Type System.DateTime System.DateTime ``` -# NOTES +## NOTES The value of the OutputType property of a FunctionInfo object is an array of System.Management.Automation.PSTypeName objects, each of which have Name and @@ -216,4 +221,3 @@ of an object. [about_Functions_Advanced_Parameters](about_Functions_Advanced_Parameters.md) [about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Language_Keywords.md b/reference/6/Microsoft.PowerShell.Core/About/about_Language_Keywords.md index b1dd44a10b43..5c8fc2278634 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Language_Keywords.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Language_Keywords.md @@ -583,7 +583,7 @@ Syntax: do {} while () ``` -# SEE ALSO +## SEE ALSO - [about_Special_Characters](about_Special_Characters.md) - [about_Wildcards](about_Wildcards.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md b/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md index 6fa833802f55..e5fe0b0de061 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-11-29 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -486,22 +486,20 @@ NOTE: Remote sessions, including sessions that are started by using the commands are packaged in snap-ins. The following modules (or snap-ins) are installed with PowerShell. +* CimCmdlets * Microsoft.PowerShell.Archive * Microsoft.PowerShell.Core * Microsoft.PowerShell.Diagnostics * Microsoft.PowerShell.Host * Microsoft.PowerShell.Management -* Microsoft.PowerShell.ODataUtils * Microsoft.PowerShell.Security * Microsoft.PowerShell.Utility * Microsoft.WSMan.Management -* OneGet +* PackageManagement * PowerShellGet * PSDesiredStateConfiguration -* PSScheduledJob -* PSWorkflow -* PSWorkflowUtility -* ISE +* PSDiagnostics +* PSReadline ## See Also diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PSSessions.md b/reference/6/Microsoft.PowerShell.Core/About/about_PSSessions.md index 196d7fddf1b9..a96bb8e474f6 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_PSSessions.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_PSSessions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -10,63 +10,120 @@ title: about_PSSessions ## Short Description -Describes Windows PowerShell sessions (PSSessions) and explains how to establish a persistent connection to a remote computer. +Describes Windows PowerShell sessions (PSSessions) and explains how to +establish a persistent connection to a remote computer. ## Long Description -To run Windows PowerShell commands on a remote computer, you can use the **ComputerName** parameter of a cmdlet, or you can create a Windows PowerShell session (PSSession) and run commands in the PSSession. +To run Windows PowerShell commands on a remote computer, you can use the +**ComputerName** parameter of a cmdlet, or you can create a Windows PowerShell +session (PSSession) and run commands in the PSSession. -When you create a PSSession, Windows PowerShell establishes a persistent connection to the remote computer. Use a PSSession to run a series of related commands on a remote computer. Commands that run in the same PSSession can share data, such as the values of variables, aliases, and functions. +When you create a PSSession, Windows PowerShell establishes a persistent +connection to the remote computer. Use a PSSession to run a series of related +commands on a remote computer. Commands that run in the same PSSession can +share data, such as the values of variables, aliases, and functions. -You can also create a PSSession on the local computer and run commands in it. A local PSSession uses the Windows PowerShell remoting infrastructure to create and maintain the PSSession. +You can also create a PSSession on the local computer and run commands in it. +A local PSSession uses the Windows PowerShell remoting infrastructure to +create and maintain the PSSession. -Beginning in Windows PowerShell 3.0, PSSessions are independent of the sessions in which they are created. Active PSSessions are maintained on the remote computer (or the computer at the remote end or "server-side" of the connection). As a result, you can disconnect from the PSSession and reconnect to it at a later time from the same computer or from a different computer. +Beginning in Windows PowerShell 3.0, PSSessions are independent of the +sessions in which they are created. Active PSSessions are maintained on the +remote computer (or the computer at the remote end or "server-side" of the +connection). As a result, you can disconnect from the PSSession and reconnect +to it at a later time from the same computer or from a different computer. -This topic explains how to create, use, get, and delete PSSessions. For more advanced information, see [about_PSSession_Details](about_PSSession_Details.md). +This topic explains how to create, use, get, and delete PSSessions. For more +advanced information, see +[about_PSSession_Details](about_PSSession_Details.md). -Note: PSSessions use the Windows PowerShell remoting infrastructure. To use PSSessions, the local and remote computers must be configured for remoting. For more information, see [about_Remote_Requirements](about_Remote_Requirements.md). +Note: PSSessions use the Windows PowerShell remoting infrastructure. To use +PSSessions, the local and remote computers must be configured for remoting. +For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). -In Windows Vista and later versions of Windows, to create a PSSession on a local computer, you must start Windows PowerShell with the "Run as administrator" option. +In Windows Vista and later versions of Windows, to create a PSSession on a +local computer, you must start Windows PowerShell with the "Run as +administrator" option. ## What Is a Session? A session is an environment in which Windows PowerShell runs. -Each time you start Windows PowerShell, a session is created for you, and you can run commands in the session. You can also add items to your session, such as modules and snap-ins, and you can create items, such as variables, functions, and aliases. These items exist only in the session and are deleted when the session ends. - -You can also create user-managed sessions, known as " Windows PowerShell sessions" or "PSSessions," on the local computer or on a remote computer. Like the default session, you can run commands in a PSSession and add and create items. - -However, unlike the session that starts automatically, you can control the PSSessions that you create. You can get, create, configure, and remove them, disconnect and reconnect to them, and run multiple commands in the same PSSession. The PSSession remains available until you delete it or it times out. - -Typically, you create a PSSession to run a series of related commands on a remote computer. When you create a PSSession on a remote computer, Windows PowerShell establishes a persistent connection to the remote computer to support the session. - -If you use the **ComputerName** parameter of the `Invoke-Command` or `Enter-PSSession` cmdlet to run a remote command or to start an interactive session, Windows PowerShell creates a temporary session on the remote computer and closes the session as soon as the command is complete or as soon as the interactive session ends. You cannot control these temporary sessions, and you cannot use them for more than a single command or a single interactive session. - -In Windows PowerShell, the "current session" is the session that you are working in. The "current session" can refer to any session, including a temporary session or a PSSession. +Each time you start Windows PowerShell, a session is created for you, and you +can run commands in the session. You can also add items to your session, such +as modules and snap-ins, and you can create items, such as variables, +functions, and aliases. These items exist only in the session and are deleted +when the session ends. + +You can also create user-managed sessions, known as " Windows PowerShell +sessions" or "PSSessions," on the local computer or on a remote computer. Like +the default session, you can run commands in a PSSession and add and create +items. However, unlike the session that starts automatically, you can control +the PSSessions that you create. You can get, create, configure, and remove +them, disconnect and reconnect to them, and run multiple commands in the same +PSSession. The PSSession remains available until you delete it or it times +out. + +Typically, you create a PSSession to run a series of related commands on a +remote computer. When you create a PSSession on a remote computer, Windows +PowerShell establishes a persistent connection to the remote computer to +support the session. + +If you use the **ComputerName** parameter of the `Invoke-Command` or +`Enter-PSSession` cmdlet to run a remote command or to start an interactive +session, Windows PowerShell creates a temporary session on the remote computer +and closes the session as soon as the command is complete or as soon as the +interactive session ends. You cannot control these temporary sessions, and you +cannot use them for more than a single command or a single interactive +session. + +In Windows PowerShell, the "current session" is the session that you are +working in. The "current session" can refer to any session, including a +temporary session or a PSSession. ## Why Use a PSSession? -Use a PSSession when you need a persistent connection to a remote computer. With a PSSession, you can run a series of commands that share data, such as the value of variables, the contents of a function, or the definition of an alias. +Use a PSSession when you need a persistent connection to a remote computer. +With a PSSession, you can run a series of commands that share data, such as +the value of variables, the contents of a function, or the definition of an +alias. -You can run remote commands without creating a PSSession. Use the **ComputerName** parameter of remote-enabled cmdlets to run a single command or a series of unrelated commands on one or many computers. +You can run remote commands without creating a PSSession. Use the +**ComputerName** parameter of remote-enabled cmdlets to run a single command +or a series of unrelated commands on one or many computers. -When you use the **ComputerName** parameter of `Invoke-Command` or `Enter-PSSession`, Windows PowerShell establishes a temporary connection to the remote computer and then closes the connection as soon as the command is complete. Any data elements that you create are lost when the connection is closed. +When you use the **ComputerName** parameter of `Invoke-Command` or +`Enter-PSSession`, Windows PowerShell establishes a temporary connection to +the remote computer and then closes the connection as soon as the command is +complete. Any data elements that you create are lost when the connection is +closed. -Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` and `Get-WmiObject`, use different remoting technologies to gather data. None create a persistent connection like a PSSession. +Other cmdlets that have a **ComputerName** parameter, such as `Get-Eventlog` +and `Get-WmiObject`, use different remoting technologies to gather data. None +create a persistent connection like a PSSession. ## How to Create a PSSession -To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession on a remote computer, use the **ComputerName** parameter of the `New-PSSession` cmdlet. +To create a PSSession, use the `New-PSSession` cmdlet. To create the PSSession +on a remote computer, use the **ComputerName** parameter of the +`New-PSSession` cmdlet. -For example, the following command creates a new PSSession on the Server01 computer. +For example, the following command creates a new PSSession on the Server01 +computer. ```powershell New-PSSession -ComputerName Server01 ``` -When you submit the command, `New-PSSession` creates the PSSession and returns an object that represents the PSSession. You can save the object in a variable when you create the PSSession, or you can use a `Get-PSSession` command to get the PSSession at a later time. +When you submit the command, `New-PSSession` creates the PSSession and returns +an object that represents the PSSession. You can save the object in a variable +when you create the PSSession, or you can use a `Get-PSSession` command to get +the PSSession at a later time. -For example, the following command creates a new PSSession on the Server01 computer and saves the resulting object in the $ps variable. +For example, the following command creates a new PSSession on the Server01 +computer and saves the resulting object in the $ps variable. ```powershell $ps = New-PSSession -ComputerName Server01 @@ -74,9 +131,12 @@ $ps = New-PSSession -ComputerName Server01 ## How to Create PSSessions on Multiple Computers -To create PSSessions on multiple computers, use the **ComputerName** parameter of the `New-PSSession` cmdlet. Type the names of the remote computers in a comma-separated list. +To create PSSessions on multiple computers, use the **ComputerName** parameter +of the `New-PSSession` cmdlet. Type the names of the remote computers in a +comma-separated list. -For example, to create PSSessions on the Server01, Server02, and Server03 computers, type: +For example, to create PSSessions on the Server01, Server02, and Server03 +computers, type: ```powershell New-PSSession -ComputerName Server01, Server02, Server03 @@ -86,7 +146,9 @@ New-PSSession -ComputerName Server01, Server02, Server03 ## How to Get PSSessions -To get the PSSessions that were created in your current session, use the `Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` returns the same type of object that `New-PSSession` returns. +To get the PSSessions that were created in your current session, use the +`Get-PSSession` cmdlet without the **ComputerName** parameter. `Get-PSSession` +returns the same type of object that `New-PSSession` returns. The following command gets all the PSSessions that were created in the current session. @@ -94,9 +156,10 @@ The following command gets all the PSSessions that were created in the current s Get-PSSession ``` -The default display of the PSSessions shows their ID and a default display name. You can assign an alternate display name when you create the session. +The default display of the PSSessions shows their ID and a default display +name. You can assign an alternate display name when you create the session. -``` +```output Id Name ComputerName State ConfigurationName --- ---- ------------ ----- --------------------- 1 Session1 Server01 Opened Microsoft.PowerShell @@ -104,31 +167,45 @@ Id Name ComputerName State ConfigurationName 3 Session3 Server03 Opened Microsoft.PowerShell ``` -You can also save the PSSessions in a variable. The following command gets the PSSessions and saves them in the $ps123 variable. +You can also save the PSSessions in a variable. The following command gets the +PSSessions and saves them in the \$ps123 variable. ```powershell $ps123 = Get-PSSession ``` -When using the PSSession cmdlets, you can refer to a PSSession by its ID, by its name, or by its instance ID (a GUID). The following command gets a PSSession by its ID and saves it in the $ps01 variable. +When using the PSSession cmdlets, you can refer to a PSSession by its ID, by +its name, or by its instance ID (a GUID). The following command gets a +PSSession by its ID and saves it in the \$ps01 variable. ```powershell $ps01 = Get-PSSession -Id 1 ``` -Beginning in Windows PowerShell 3.0, PSSessions are maintained on the remote computer. To get PSSessions that you created on particular remote computers, use the **ComputerName** parameter of the `Get-PSSession` cmdlet. The following command gets the PSSessions that you created on the Server01 remote computer. This includes PSSessions created in the current session and in other sessions on the local computer or other computers. +Beginning in Windows PowerShell 3.0, PSSessions are maintained on the remote +computer. To get PSSessions that you created on particular remote computers, +use the **ComputerName** parameter of the `Get-PSSession` cmdlet. The +following command gets the PSSessions that you created on the Server01 remote +computer. This includes PSSessions created in the current session and in other +sessions on the local computer or other computers. ```powershell Get-PSSession -ComputerName Server01 ``` -In Windows PowerShell 2.0, `Get-PSSession` gets only the PSSessions that were created in the current session. It does not get PSSessions that were created in other sessions or on other computers, even if the sessions are connected to and are running commands on the local computer. +In Windows PowerShell 2.0, `Get-PSSession` gets only the PSSessions that were +created in the current session. It does not get PSSessions that were created +in other sessions or on other computers, even if the sessions are connected to +and are running commands on the local computer. ## How to Run Commands in a PSSession -To run a command in one or more PSSessions, use the `Invoke-Command` cmdlet. Use the Session parameter to specify the PSSessions and the **ScriptBlock** parameter to specify the command. +To run a command in one or more PSSessions, use the `Invoke-Command` cmdlet. +Use the Session parameter to specify the PSSessions and the **ScriptBlock** +parameter to specify the command. -For example, to run a `Get-ChildItem` ("dir") command in each of the three PSSessions saved in the $ps123 variable, type: +For example, to run a `Get-ChildItem` ("dir") command in each of the three +PSSessions saved in the $ps123 variable, type: ```powershell Invoke-Command -Session $ps123 -ScriptBlock { Get-ChildItem } @@ -136,7 +213,8 @@ Invoke-Command -Session $ps123 -ScriptBlock { Get-ChildItem } ## How to Delete PSSessions -When you are finished with the PSSession, use the `Remove-PSSession` cmdlet to delete the PSSession and to release the resources that it was using. +When you are finished with the PSSession, use the `Remove-PSSession` cmdlet to +delete the PSSession and to release the resources that it was using. ```powershell Remove-PSSession -Session $ps @@ -148,35 +226,38 @@ or Remove-PSSession -Id 1 ``` -To remove a PSSession from a remote computer, use the **ComputerName** parameter of the `Remove-PSSession` cmdlet. +To remove a PSSession from a remote computer, use the **ComputerName** +parameter of the `Remove-PSSession` cmdlet. ```powershell Remove-PSSession -ComputerName Server01 -Id 1 ``` -If you do not delete the PSSession, the PSSession remains available for use until it times out. +If you do not delete the PSSession, the PSSession remains available for use +until it times out. -You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` cmdlet to set an expiration time for an idle PSSession. For more information, see [New-PSSessionOption](../New-PSSessionOption.md). +You can also use the **IdleTimeout** parameter of the `New-PSSessionOption` +cmdlet to set an expiration time for an idle PSSession. For more information, +see [New-PSSessionOption](../New-PSSessionOption.md). ## The PSSession Cmdlets -| Cmdlet | Description | -| -------------------- | --------------------------------------------------------------- | -| Connect-PSSession | Connects a PSSession to the current session | -| Disconnect-PSSession | Disconnects a PSSession from the current session | -| Enter-PSSession | Starts an interactive session | -| Exit-PSSession | Ends an interactive session | -| Get-PSSession | Gets the PSSessions in the current session | -| New-PSSession | Creates a new PSSession on a local or remote computer | -| Receive-PSSession | Gets the results of commands that ran in a disconnected session | -| Remove-PSSession | Deletes the PSSessions in the current session | - For a list of PSSession cmdlets, type: ```powershell Get-Help *-PSSession ``` +- Connect-PSSession: Connects a PSSession to the current session +- Disconnect-PSSession: Disconnects a PSSession from the current session +- Enter-PSSession: Starts an interactive session +- Exit-PSSession: Ends an interactive session +- Get-PSSession: Gets the PSSessions in the current session +- New-PSSession: Creates a new PSSession on a local or remote computer +- Receive-PSSession: Gets the results of commands that ran in a disconnected + session +- Remove-PSSession: Deletes the PSSessions in the current session + ## For More Information For more information about PSSessions, see [about_PSSession_Details](about_PSSession_Details.md). diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PSSnapins.md b/reference/6/Microsoft.PowerShell.Core/About/about_PSSnapins.md deleted file mode 100644 index bab6da6892d1..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/About/about_PSSnapins.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_PSSnapins ---- - -# About PSSnapins -## about_PSSnapins - - -## SHORT DESCRIPTION -Describes Windows PowerShell snap-ins and shows how to use and manage them. - - -## LONG DESCRIPTION -A Windows PowerShell snap-in is a Microsoft .NET Framework assembly that contains Windows PowerShell providers and\/or cmdlets. Windows PowerShell includes a set of basic snap-ins, but you can extend the power and value of Windows PowerShell by adding snap-ins that contain providers and cmdlets that you create or get from others. - -When you add a snap-in, the cmdlets and providers that it contains are immediately available for use in the current session, but the change affects only the current session. - -To add the snap-in to all future sessions, save it in your Windows PowerShell profile. You can also use the Export-Console cmdlet to save the snap-in names to a console file and then use it in future sessions. You can even save multiple console files, each with a different set of snap-ins. - -NOTE: Windows PowerShell snap-ins (PSSnapins) are available for use in Windows PowerShell 3.0 and Windows PowerShell 2.0. They might be altered or unavailable in subsequent versions. To package Windows PowerShell cmdlets and providers, use modules. For information about creating modules and converting snap-ins to modules, see "Writing a Windows PowerShell Module" in MSDN at http:\/\/go.microsoft.com\/fwlink\/?LinkID\=141556. - - -### FINDING SNAP-INS -To get a list of the Windows PowerShell snap-ins on your computer, type: - - -``` -get-pssnapin -``` - - -To get the snap-in for each Windows PowerShell provider, type: - - -``` -get-psprovider | format-list name, pssnapin -``` - - -To get a list of the cmdlets in a Windows PowerShell snap-in, type: - - -``` -get-command -module -``` - - - -### INSTALLING A SNAP-IN -The built-in snap-ins are registered in the system and added to the default session when you start Windows PowerShell. However, you have to register snap-ins that you create or obtain from others and then add the snap-ins to your session. - - -### REGISTERING A SNAP-IN -A Windows PowerShell snap-in is a program written in a .NET Framework language that is compiled into a .dll file. To use the providers and cmdlets in a snap-in, you must first register the snap-in (add it to the registry). - -Most snap-ins include an installation program (an .exe or .msi file) that registers the .dll file for you. However, if you receive a snap-in as a .dll file, you can register it on your system. For more information, see [How to Register Cmdlets, Providers, and Host Applications](https://go.microsoft.com/fwlink/?LinkID=143619) in the MSDN library. - -To get all the registered snap-ins on your system or to verify that a snap-in is registered, type: - - -``` -get-pssnapin -registered -``` - - - -### ADDING THE SNAP-IN TO THE CURRENT SESSION -To add a registered snap-in to the current session, use the Add-PsSnapin cmdlet. For example, to add the Microsoft SQL Server snap-in to the session, type: - - -``` -add-pssnapin sql -``` - - -After the command is completed, the providers and cmdlets in the snap-in are available in the session. However, they are available only in the current session unless you save them. - - -### SAVING THE SNAP-INS -To use a snap-in in future Windows PowerShell sessions, add the Add-PsSnapin command to your Windows PowerShell profile. Or, export the snap-in names to a console file. - -If you add the Add-PSSnapin command to your profile, it is available in all future Windows PowerShell sessions. If you export the names of the snap-ins in your session, you can use the export file only when you need the snap-ins. - -To add the Add-PsSnapin command to your Windows PowerShell profile, open your profile, paste or type the command, and then save the profile. For more information, see about_Profiles. - -To save the snap-ins from a session in console file (.psc1), use the Export-Console cmdlet. For example, to save the snap-ins in the current session configuration to the NewConsole.psc1 file in the current directory, type: - - -``` -export-console NewConsole -``` - - -For more information, see Export-Console. - - -### OPENING WINDOWS POWERSHELL WITH A CONSOLE FILE -To use a console file that includes the snap-in, start Windows PowerShell (PowerShell.exe) from the command prompt in Cmd.exe or in another Windows PowerShell session. Use the PsConsoleFile parameter to specify the console file that includes the snap-in. For example, the following command starts Windows PowerShell with the NewConsole.psc1 console file: - - -``` -PowerShell.exe -psconsolefile NewConsole.psc1 -``` - - -The providers and cmdlets in the snapin are now available for use in the session. - - -### REMOVING A SNAP-IN -To remove a Windows PowerShell snap-in from the current session, use the Remove-PsSnapin cmdlet. For example, to remove the SQL Server snap-in from the current session, type: - - -``` -remove-pssnapin sql -``` - - -This cmdlet removes the snap-in from the session. The snap-in is still loaded, but the providers and cmdlets that it supports are no longer available. - - -### BUILT-IN COMMANDS -In Windows PowerShell 2.0 and in older-style host programs in Windows PowerShell 3.0 and later, the built-in commands that are installed with Windows PowerShell are packaged in snap-ins that are added automatically to every Windows PowerShell session. - -Beginning in Windows PowerShell 3.0, in newer-style host programs -- those that start sessions by using the InitialSessionState.CreateDefault2 method -- the built-in commands are packaged in modules. The exception is Microsoft.PowerShell.Core, which always appears as a snap-in. The Core snap-in is included in every session by default. The built-in modules are loaded automatically on first-use. - -NOTE: Remote sessions, including sessions that are started by using the New-PSSession cmdlet, are older-style sessions in which the built-in commands are packaged in snap-ins. - -The following snap-ins (or modules) are installed with Windows PowerShell. - -Microsoft.PowerShell.Core - -Contains providers and cmdlets used to manage the basic features of Windows PowerShell. It includes the FileSystem, Registry, Alias, Environment, Function, and Variable providers and basic cmdlets like Get-Help, Get-Command, and Get-History. - -Microsoft.PowerShell.Host - -Contains cmdlets used by the Windows PowerShell host, such as Start-Transcript and Stop-Transcript. - -Microsoft.PowerShell.Management - -Contains cmdlets such as Get-Service and Get-ChildItem that are used to manage Windows-based features. - -Microsoft.PowerShell.Security - -Contains the Certificate provider and cmdlets used to manage Windows PowerShell security, such as Get-Acl, Get-AuthenticodeSignature, and ConvertTo-SecureString. - -Microsoft.PowerShell.Utility - -Contains cmdlets used to manipulate objects and data, such as Get-Member, Write-Host, and Format-List. - -Microsoft.WSMan.Management - -Contains the WSMan provider and cmdlets that manage the Windows Remote Management service, such as Connect-WSMan and Enable-WSManCredSSP. - - -## LOGGING SNAP-IN EVENTS -Beginning in Windows PowerShell 3.0, you can record execution events for the cmdlets in Windows PowerShell modules and snap-ins by setting the LogPipelineExecutionDetails property of modules and snap-ins to TRUE. For more information, see about_EventLogs (http:\/\/go.microsoft.com\/fwlink\/?LinkID\=113224). - - -## SEE ALSO - -Add-PsSnapin - -Get-PsSnapin - -Remove-PsSnapin - -Export-Console - -Get-Command - -[about_Profiles](about_Profiles.md) - -[about_Modules](about_Modules.md) - -## KEYWORDS: -about_Snapins, about_Snap_ins, about_Snap-ins - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PackageManagement.md b/reference/6/Microsoft.PowerShell.Core/About/about_PackageManagement.md index 7933f7f0a80e..32789dca75ab 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_PackageManagement.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_PackageManagement.md @@ -104,24 +104,24 @@ For more information about the PackageManagement open development project, including how to create a PackageManagement package provider, see the PackageManagement project on GitHub at https://oneget.org. -# SEE ALSO +## SEE ALSO -Get-PackageProvider +[Get-PackageProvider](../../PackageManagement/Get-PackageProvider.md) -Get-PackageSource +[Get-PackageSource](../../PackageManagement/Get-PackageSource.md) -Register-PackageSource +[Register-PackageSource](../../PackageManagement/Register-PackageSource.md) -Set-PackageSource +[Set-PackageSource](../../PackageManagement/Set-PackageSource.md) -Unregister-PackageSource +[Unregister-PackageSource](../../PackageManagement/Unregister-PackageSource.md) -Get-Package +[Get-Package](../../PackageManagement/Get-Package.md) -Find-Package +[Find-Package](../../PackageManagement/Find-Package.md) -Install-Package +[Install-Package](../../PackageManagement/Install-Package.md) -Save-Package +[Save-Package](../../PackageManagement/Save-Package.md) -Uninstall-Package +[Uninstall-Package](../../PackageManagement/Uninstall-Package.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/6/Microsoft.PowerShell.Core/About/about_Parameters.md index 37c6f1b3c26e..b74b7e5b0cb0 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,197 +7,227 @@ title: about_Parameters --- # About Parameters -## about_Parameters - ## SHORT DESCRIPTION -Describes how to work with command parameters in Windows PowerShell. +Describes how to work with command parameters in PowerShell. ## LONG DESCRIPTION -Most Windows PowerShell commands, such as cmdlets, functions, and scripts, rely on parameters to allow users to select options or provide input. The parameters follow the command name and have the following form: +Most PowerShell commands, such as cmdlets, functions, and scripts, +rely on parameters to allow users to select options or provide input. The +parameters follow the command name and have the following form: ``` - ``` +The name of the parameter is preceded by a hyphen (-), which signals to +Windows PowerShell that the word following the hyphen is a parameter name. +Some parameters do not require or accept a parameter value. Other parameters +require a value, but do not require the parameter name in the command. -The name of the parameter is preceded by a hyphen (-), which signals to Windows PowerShell that the word following the hyphen is a parameter name. Some parameters do not require or accept a parameter value. Other parameters require a value, but do not require the parameter name in the command. - -The type of parameters and the requirements for those parameters vary. To find information about the parameters of a command, use the Get-Help cmdlet. For example, to find information about the parameters of the Get-ChildItem cmdlet, type: +The type of parameters and the requirements for those parameters vary. To find +information about the parameters of a command, use the Get-Help cmdlet. For +example, to find information about the parameters of the Get-ChildItem cmdlet, +type: -``` +```powershell Get-Help Get-ChildItem ``` +To find information about the parameters of a script, use the full path to the +script file. For example: -To find information about the parameters of a script, use the full path to the script file. For example: - - -``` +```powershell Get-Help $home\Documents\Scripts\Get-Function.ps1 ``` +The Get-Help cmdlet returns various details about the command, including a +description, the command syntax, information about the parameters, and +examples showing how to use the parameters in a command. -The Get-Help cmdlet returns various details about the command, including a description, the command syntax, information about the parameters, and examples showing how to use the parameters in a command. - -You can also use the Parameter parameter of the Get-Help cmdlet to find information about a particular parameter. Or, you can use the Parameter parameter with the wildcard character (\*) value to find information about all parameters of the command. For example, the following command gets information about all parameters of the Get-Member cmdlet: +You can also use the Parameter parameter of the Get-Help cmdlet to find +information about a particular parameter. Or, you can use the Parameter +parameter with the wildcard character (\*) value to find information about all +parameters of the command. For example, the following command gets information +about all parameters of the Get-Member cmdlet: -``` +```powershell Get-Help Get-Member -Parameter * ``` ### DEFAULT PARAMETER VALUES -Optional parameters have a default value, which is the value that is used or assumed when the parameter is not specified in the command. -For example, the default value of the ComputerName parameter of many cmdlets is the name of the local computer. As a result, the local computer name is used in the command unless the ComputerName parameter is specified. +Optional parameters have a default value, which is the value that is used or +assumed when the parameter is not specified in the command. -To find the default parameter value, see help topic for the cmdlet. The parameter description should include the default value. +For example, the default value of the ComputerName parameter of many cmdlets +is the name of the local computer. As a result, the local computer name is +used in the command unless the ComputerName parameter is specified. -You can also set a custom default value for any parameter of a cmdlet or advanced function. For information about setting custom default values, see about_Parameters_Default_Values. +To find the default parameter value, see help topic for the cmdlet. The +parameter description should include the default value. +You can also set a custom default value for any parameter of a cmdlet or +advanced function. For information about setting custom default values, see +[about_Parameters_Default_Values](about_Parameters_Default_Values.md). ### PARAMETER ATTRIBUTE TABLE -When you use the Full, Parameter, or Online parameters of the Get-Help cmdlet, Get-Help displays a parameter attribute table with detailed information about the parameter. -This information includes the details you need to know to use the parameter. For example, the help topic for the Get-ChildItem cmdlet includes the following details about its Path parameter: +When you use the Full, Parameter, or Online parameters of the Get-Help cmdlet, +Get-Help displays a parameter attribute table with detailed information about +the parameter. + +This information includes the details you need to know to use the parameter. +For example, the help topic for the Get-ChildItem cmdlet includes the +following details about its Path parameter: ``` --path - Specifies a path of one or more locations. Wildcard characters are +-path + Specifies a path of one or more locations. Wildcard characters are permitted. The default location is the current directory (.). -``` - - -``` -Required? false -Position? 1 -Default value Current directory -Accept pipeline input? true (ByValue, ByPropertyName) +Required? false +Position? 1 +Default value Current directory +Accept pipeline input? true (ByValue, ByPropertyName) Accept wildcard characters? true ``` +The parameter information includes the parameter syntax, a description of the +parameter, and the parameter attributes. The following sections describe the +parameter attributes. -The parameter information includes the parameter syntax, a description of the parameter, and the parameter attributes. The following sections describe the parameter attributes. +#### Parameter Required? -Parameter Required? +This setting indicates whether the parameter is mandatory, that is, whether +all commands that use this cmdlet must include this parameter. When the value +is "True" and the parameter is missing from the command, Windows PowerShell +prompts you for a value for the parameter. -This setting indicates whether the parameter is mandatory, that is, whether all commands that use this cmdlet must include this parameter. When the value is "True" and the parameter is missing from the command, Windows PowerShell prompts you for a value for the parameter. +#### Parameter Position? -Parameter Position? +This setting indicates whether you can supply a parameter's value without +preceding it with the parameter name. If set to "0" or "named," a parameter +name is required. This type of parameter is referred to as a named parameter. +A named parameter can be listed in any position after the cmdlet name. -This setting indicates whether you can supply a parameter's value without preceding it with the parameter name. If set to "0" or "named," a parameter name is required. This type of parameter is referred to as a named parameter. A named parameter can be listed in any position after the cmdlet name. +If the "Parameter position?" setting is set to an integer other than 0, the +parameter name is not required. This type of parameter is referred to as a +positional parameter, and the number indicates the position in which the +parameter must appear in relation to other positional parameters. If you +include the parameter name for a positional parameter, the parameter can be +listed in any position after the cmdlet name. -If the "Parameter position?" setting is set to an integer other than 0, the parameter name is not required. This type of parameter is referred to as a positional parameter, and the number indicates the position in which the parameter must appear in relation to other positional parameters. If you include the parameter name for a positional parameter, the parameter can be listed in any position after the cmdlet name. +For example, the Get-ChildItem cmdlet has Path and Exclude parameters. The +"Parameter position?" setting for Path is 1, which means that it is a +positional parameter. The "Parameter position?" setting for Exclude is 0, +which means that it is a named parameter. -For example, the Get-ChildItem cmdlet has Path and Exclude parameters. The "Parameter position?" setting for Path is 1, which means that it is a positional parameter. The "Parameter position?" setting for Exclude is 0, which means that it is a named parameter. +This means that Path does not require the parameter name, but its parameter +value must be the first or only unnamed parameter value in the command. +However, because the Exclude parameter is a named parameter, you can place it +in any position in the command. -This means that Path does not require the parameter name, but its parameter value must be the first or only unnamed parameter value in the command. However, because the Exclude parameter is a named parameter, you can place it in any position in the command. +As a result of the "Parameter position?" settings for these two parameters, +you can use any of the following commands: -As a result of the "Parameter position?" settings for these two parameters, you can use any of the following commands: - -``` -Get-ChildItem -path c:\techdocs -exclude *.ppt -Get-ChildItem c:\techdocs -exclude *.ppt -Get-ChildItem -exclude *.ppt -path c:\techdocs +```powershell +Get-ChildItem -path c:\techdocs -exclude *.ppt +Get-ChildItem c:\techdocs -exclude *.ppt +Get-ChildItem -exclude *.ppt -path c:\techdocs Get-ChildItem -exclude *.ppt c:\techdocs ``` +If you were to include another positional parameter without including the +parameter name, that parameter would have to be placed in the order specified +by the "Parameter position?" setting. -If you were to include another positional parameter without including the parameter name, that parameter would have to be placed in the order specified by the "Parameter position?" setting. +#### Parameter Type -Parameter Type +This setting specifies the Microsoft .NET Framework type of the parameter +value. For example, if the type is Int32, the parameter value must be an +integer. If the type is string, the parameter value must be a character +string. If the string contains spaces, the value must be enclosed in quotation +marks, or the spaces must be preceded by the escape character (`). -This setting specifies the Microsoft .NET Framework type of the parameter value. For example, if the type is Int32, the parameter value must be an integer. If the type is string, the parameter value must be a character string. If the string contains spaces, the value must be enclosed in quotation marks, or the spaces must be preceded by the escape character (`). +#### Default Value -Default Value +This setting specifies the value that the parameter will assume if no other +value is provided. For example, the default value of the Path parameter is +often the current directory. Required parameters never have a default value. +For many optional parameters, there is no default because the parameter has no +effect if it is not used. -This setting specifies the value that the parameter will assume if no other value is provided. For example, the default value of the Path parameter is often the current directory. Required parameters never have a default value. For many optional parameters, there is no default because the parameter has no effect if it is not used. +#### Accepts Multiple Values? -Accepts Multiple Values? +This setting indicates whether a parameter accepts multiple parameter values. +When a parameter accepts multiple values, you can type a comma-separated list +as the value of the parameter in the command, or save a comma-separated list +(an array) in a variable, and then specify the variable as the parameter +value. -This setting indicates whether a parameter accepts multiple parameter values. When a parameter accepts multiple values, you can type a comma-separated list as the value of the parameter in the command, or save a comma-separated list (an array) in a variable, and then specify the variable as the parameter value. +For example, the ServiceName parameter of the Get-Service cmdlet accepts +multiple values. The following commands are both valid: -For example, the ServiceName parameter of the Get-Service cmdlet accepts multiple values. The following commands are both valid: - - -``` +```powershell get-service -servicename winrm, netlogon ``` - - -``` -$s = "winrm", "netlogon" +```powershell +$s = "winrm", "netlogon" get-service -servicename $s ``` +#### Accepts Pipeline Input? -Accepts Pipeline Input? - -This setting indicates whether you can use the pipeline operator (|) to send a value to the parameter. - +This setting indicates whether you can use the pipeline operator (|) to +send a value to the parameter. ``` -Value Description ------ ----------- -False Indicates that you cannot pipe a value to the +Value Description +----- ----------- +False Indicates that you cannot pipe a value to the parameter. -``` - - -``` -True (by Value) Indicates that you can pipe any value to the - parameter, just so the value has the .NET - Framework type specified for the parameter or the - value can be converted to the specified .NET +True (by Value) Indicates that you can pipe any value to the + parameter, just so the value has the .NET + Framework type specified for the parameter or the + value can be converted to the specified .NET Framework type. ``` - - -``` -When a parameter is "True (by Value)", Windows -PowerShell tries to associate any piped values -with that parameter before it tries other methods -to interpret the command. -``` - - +When a parameter is "True (by Value)", Windows PowerShell tries to associate +any piped values with that parameter before it tries other methods to +interpret the command. ``` -True (by Property Name) Indicates that you can pipe a value to the - parameter, but the .NET Framework type of the - parameter must include a property with the same +True (by Property Name) Indicates that you can pipe a value to the + parameter, but the .NET Framework type of the + parameter must include a property with the same name as the parameter. ``` +For example, you can pipe a value to a Name parameter only when the value has +a property called "Name". +#### Accepts Wildcard Characters? -``` -For example, you can pipe a value to a Name -parameter only when the value has a property -called "Name". -``` - - -Accepts Wildcard Characters? - -This setting indicates whether the parameter's value can contain wildcard characters so that the parameter value can be matched to more than one existing item in the target container. +This setting indicates whether the parameter's value can contain wildcard +characters so that the parameter value can be matched to more than one +existing item in the target container. -Common Parameters - -Common parameters are parameters that you can use with any cmdlet. For more information about common parameters, see about_CommonParameters +#### Common Parameters +Common parameters are parameters that you can use with any cmdlet. For more +information about common parameters, see [about_CommonParameters](about_CommonParameters.md). ## SEE ALSO @@ -212,4 +242,3 @@ Common parameters are parameters that you can use with any cmdlet. For more info [about_Pipelines](about_Pipelines.md) [about_Wildcards](about_Wildcards.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Ise_exe.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Ise_exe.md deleted file mode 100644 index a14a0cea93c2..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Ise_exe.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_PowerShell_Ise_exe ---- - -# About PowerShell Ise.exe -## about_PowerShell_Ise.exe - - -# SHORT DESCRIPTION - -Explains how to use the PowerShell_Ise.exe command-line tool. - -# LONG DESCRIPTION - -PowerShell_Ise.exe starts a Windows PowerShell Integrated -Scripting Environment (ISE) session. You can run it in Cmd.exe -and in Windows PowerShell. - -To run PowerShell_ISE.exe, type PowerShell_ISE.exe, PowerShell_ISE, -or ISE. - -# SYNTAX - -PowerShell_Ise[.exe] -PowerShell_ISE[.exe] -ISE[.exe] -[-File] [-NoProfile] [-MTA] --Help | ? | -? | /? -Displays the syntax and describes the command-line switches. - -# PARAMETERS - --File -Opens the specified files in Windows PowerShell ISE. The -parameter name ("-File") is optional. To list more than one -file, enter one text string enclosed in quotation marks. Use -commas to separate the file names within the string. - -For example: -PowerShell_ISE -File "File1.ps1,File2.ps1,File3.xml". - -Spaces between the file names are permitted in Windows PowerShell, -but might not be interpreted correctly by other programs, such as -Cmd.exe. - -You can use this parameter to open any text file, including Windows -PowerShell script files and XML files. - --Mta -Starts Windows PowerShell ISE using a multi-threaded apartment. This -parameter is introduced in Windows PowerShell 3.0. Single-threaded -apartment (STA) is the default. - --NoProfile -Does not run Windows PowerShell profiles. By default, Windows PowerShell -profiles are run in every session. - -This parameter is recommended when you are writing shared content, such as -functions and scripts that will be run on systems with different profiles. -For more information, see about_Profiles -(http://go.microsoft.com/fwlink/?LinkID=113729). - --Help, -?, /? -Displays help for PowerShell_ISE.exe. - -# EXAMPLES - -These commands start Windows PowerShell ISE. The commands are equivalent -and can be used interchangeably. - -PS C:> PowerShell_ISE.exe -PS C:> PowerShell_ISE -# PS C:>ISE - - -These commands open the Get-Profile.ps1 script in Windows PowerShell ISE. -The commands are equivalent and can be used interchangeably. - -PS C:> PowerShell_ISE.exe -File .\Get-Profile.ps1 -PS C:> ISE -File .\Get-Profile.ps1 -PS C:> ISE .\Get-Profile.ps1 - -This command opens the Get-Backups.ps1 and Get-BackupInstance.ps1 scripts -in Windows PowerShell ISE. To open more than one file, use a comma to -separate the file names and enclose the entire file name value in quotation -marks. - -PS C:> ISE -File ".\Get-Backups.ps1,Get-BackupInstance.ps1" - -This command starts Windows PowerShell ISE with no profiles. - -PS C:> ISE -NoProfile - -This command gets help for PowerShell_ISE.exe. - -PS C:> ISE -help - -# SEE ALSO - -[about_pwsh](about_pwsh.md) - -[about_Windows_PowerShell_ISE](about_Windows_PowerShell_ISE.md) - -Windows PowerShell 3.0 Integrated Scripting Environment (ISE) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Providers.md b/reference/6/Microsoft.PowerShell.Core/About/about_Providers.md index 2a2e72a3ad3a..8080f77944b9 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Providers.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Providers.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,61 +7,58 @@ title: about_Providers --- # About Providers -## about_Providers - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes how Windows PowerShell providers provide access to data and -components that would not otherwise be easily accessible at the command -line. The data is presented in a consistent format that resembles a file -system drive. - -# LONG DESCRIPTION - -Windows PowerShell providers are Microsoft .NET Framework-based programs -that make the data in a specialized data store available in Windows -PowerShell so that you can view and manage it. - -The data that a provider exposes appears in a drive, and you access the -data in a path like you would on a hard disk drive. You can use any of the -built-in cmdlets that the provider supports to manage the data in the -provider drive. And, you can use custom cmdlets that are designed -especially for the data. - -The providers can also add dynamic parameters to the built-in cmdlets. -These are parameters that are available only when you use the cmdlet with -the provider data. - -# BUILT-IN PROVIDERS - -Windows PowerShell includes a set of built-in providers that you can use -to access the different types of data stores. - -| Provider | Drive | Data store | -| ----------- | ------------ | ------------------------------------------ | -| Alias | Alias: | Windows PowerShell aliases | -| Certificate | Cert: | x509 certificates for digital signatures | -| Environment | Env: | Windows environment variables | -| FileSystem | (*) | File system drives, directories, and files | -| Function | Function: | Windows PowerShell functions | -| Registry | HKLM:, HKCU: | Windows registry | -| Variable | Variable: | Windows PowerShell variables | -| WSMan | WSMan: | WS-Management configuration information | +components that would not otherwise be easily accessible at the command line. +The data is presented in a consistent format that resembles a file system +drive. + +## LONG DESCRIPTION + +Windows PowerShell providers are Microsoft .NET Framework-based programs that +make the data in a specialized data store available in Windows PowerShell so +that you can view and manage it. + +The data that a provider exposes appears in a drive, and you access the data +in a path like you would on a hard disk drive. You can use any of the built-in +cmdlets that the provider supports to manage the data in the provider drive. +And, you can use custom cmdlets that are designed especially for the data. + +The providers can also add dynamic parameters to the built-in cmdlets. These +are parameters that are available only when you use the cmdlet with the +provider data. + +## BUILT-IN PROVIDERS + +Windows PowerShell includes a set of built-in providers that you can use to +access the different types of data stores. + +|Provider |Drive |Data store | +|------------|-------------|-------------------------------------------| +|Alias |Alias: |Windows PowerShell aliases | +|Certificate |Cert: |x509 certificates for digital signatures | +|Environment |Env: |Windows environment variables | +|FileSystem |(*) |File system drives, directories, and files | +|Function |Function: |Windows PowerShell functions | +|Registry |HKLM:, HKCU: |Windows registry | +|Variable |Variable: |Windows PowerShell variables | +|WSMan |WSMan: |WS-Management configuration information | (*) The FileSystem drives vary on each system. -You can also create your own Windows PowerShell providers, and you can -install providers that others develop. To list the providers that are -available in your session, type: +You can also create your own Windows PowerShell providers, and you can install +providers that others develop. To list the providers that are available in +your session, type: -Get-PSProvider +get-psprovider -# INSTALLING AND REMOVING PROVIDERS +## INSTALLING AND REMOVING PROVIDERS Windows PowerShell providers are delivered to you in Windows PowerShell -snap-ins, which are .NET Framework-based programs that are compiled -into .dll files. The snap-ins can include providers and cmdlets. +snap-ins, which are .NET Framework-based programs that are compiled into .dll +files. The snap-ins can include providers and cmdlets. Before you use the provider features, you have to install the snap-in and then add it to your Windows PowerShell session. For more information, see @@ -69,103 +66,106 @@ about_PSSnapins. You cannot uninstall a provider, although you can remove the Windows PowerShell snap-in for the provider from the current session. If you do, -you remove all the contents of the snap-in, including its cmdlets. +you will remove all the contents of the snap-in, including its cmdlets. To remove a provider from the current session, use the Remove-PSSnapin cmdlet. This cmdlet does not uninstall the provider, but it makes the provider unavailable in the session. You can also use the Remove-PSDrive cmdlet to remove any drive from the -current session. This data on the drive is not affected, but the drive is -no longer available in that session. +current session. This data on the drive is not affected, but the drive is no +longer available in that session. -# VIEWING PROVIDERS +## VIEWING PROVIDERS To view the Windows PowerShell providers on your computer, type: -Get-PSProvider +```powershell +get-psprovider +``` -The output lists the built-in providers and the providers that you added -to the session. +The output lists the built-in providers and the providers that you added to +the session. -# THE PROVIDER CMDLETS +## THE PROVIDER CMDLETS -The following cmdlets are designed to work with the data exposed by -any provider. You can use the same cmdlets in the same way to manage -the different types of data that providers expose. After you -learn to manage the data of one provider, you can use the same -procedures with the data from any provider. +The following cmdlets are designed to work with the data exposed by any +provider. You can use the same cmdlets in the same way to manage the different +types of data that providers expose. After you learn to manage the data of one +provider, you can use the same procedures with the data from any provider. -For example, the New-Item cmdlet creates a new item. In the C: drive that -is supported by the FileSystem provider, you can use New-Item to create a -new file or folder. In the drives that are supported by the Registry -provider, you can use New-Item to create a new registry key. In the Alias: -drive, you can use New-Item to create a new alias. +For example, the New-Item cmdlet creates a new item. In the C: drive that is +supported by the FileSystem provider, you can use New-Item to create a new +file or folder. In the drives that are supported by the Registry provider, you +can use New-Item to create a new registry key. In the Alias: drive, you can +use New-Item to create a new alias. For detailed information about any of the following cmdlets, type: -Get-Help -Detailed +``` +get-help -detailed +``` -# CHILDITEM CMDLETS +### CHILDITEM CMDLETS -Get-ChildItem +- Get-ChildItem -# CONTENT CMDLETS +### CONTENT CMDLETS -Add-Content -Clear-Content -Get-Content -Set-Content +- Add-Content +- Clear-Content +- Get-Content +- Set-Content -# ITEM CMDLETS +### ITEM CMDLETS -Clear-Item -Copy-Item -Get-Item -Invoke-Item -Move-Item -New-Item -Remove-Item -Rename-Item -Set-Item +- Clear-Item +- Copy-Item +- Get-Item +- Invoke-Item +- Move-Item +- New-Item +- Remove-Item +- Rename-Item +- Set-Item -# ITEMPROPERTY CMDLETS +### ITEMPROPERTY CMDLETS -Clear-ItemProperty -Copy-ItemProperty -Get-ItemProperty -Move-ItemProperty -New-ItemProperty -Remove-ItemProperty -Rename-ItemProperty -Set-ItemProperty +- Clear-ItemProperty +- Copy-ItemProperty +- Get-ItemProperty +- Move-ItemProperty +- New-ItemProperty +- Remove-ItemProperty +- Rename-ItemProperty +- Set-ItemProperty -# LOCATION CMDLETS +### LOCATION CMDLETS -Get-Location -Pop-Location -Push-Location -Set-Location +- Get-Location +- Pop-Location +- Push-Location +- Set-Location -# PATH CMDLETS +### PATH CMDLETS -Join-Path -Convert-Path -Split-Path -Resolve-Path -Test-Path +- Join-Path +- Convert-Path +- Split-Path +- Resolve-Path +- Test-Path -# PSDRIVE CMDLETS +### PSDRIVE CMDLETS -Get-PSDrive -New-PSDrive -Remove-PSDrive +- Get-PSDrive +- New-PSDrive +- Remove-PSDrive -# PSPROVIDER CMDLETS +### PSPROVIDER CMDLETS -Get-PSProvider +- Get-PSProvider -# VIEWING PROVIDER DATA +## VIEWING PROVIDER DATA The primary benefit of a provider is that it exposes its data in a familiar and consistent way. The model for data presentation is a file system @@ -181,7 +181,7 @@ but you can get information about the provider drive by using the Get-PSDrive cmdlet. For example, to get all the properties of the Function: drive, type: -Get-PSDrive Function | Format-List * +get-psdrive Function | format-list * You can view and move through the data in a provider drive just as you would on a file system drive. @@ -190,85 +190,108 @@ To view the contents of a provider drive, use the Get-Item or Get-ChildItem cmdlets. Type the drive name followed by a colon (:). For example, to view the contents of the Alias: drive, type: -Get-Item Alias: +```powershell +get-item alias: +``` You can view and manage the data in any drive from another drive by including the drive name in the path. For example, to view the HKLM\Software registry key in the HKLM: drive from another drive, type: -Get-ChildItem HKLM:\SOFTWARE +```powershell +get-childitem hklm:\software +``` To open the drive, use the Set-Location cmdlet. Remember the colon when you specify the drive path. For example, to change your location to the root directory of the Cert: drive, type: -Set-Location Cert: +```powershell +set-location cert: +``` Then, to view the contents of the Cert: drive, type: -Get-ChildItem +```powershell +get-childitem +``` -# MOVING THROUGH HIERARCHICAL DATA +## MOVING THROUGH HIERARCHICAL DATA You can move through a provider drive just as you would a hard disk drive. If the data is arranged in a hierarchy of items within items, use a backslash () to indicate a child item. Use the following format: +``` drive:\location\child-location\... +``` For example, to change your location to the HKLM\Software registry key, type a Set-Location command, such as: -Set-Location HKLM:\SOFTWARE +```powershell +set-location hklm:\software +``` You can also use relative references to locations. A dot (.) represents the current location. For example, if you are in the HKLM:\Software\Microsoft registry key, and you want to list the registry subkeys in the HKLM:\Software\Microsoft\PowerShell key, type the following command: -Get-ChildItem .\PowerShell +```powershell +get-childitem .\PowerShell +``` -# FINDING DYNAMIC PARAMETERS +## FINDING DYNAMIC PARAMETERS -Dynamic parameters are cmdlet parameters that are added to a cmdlet -by a provider. These parameters are available only when the cmdlet is -used with the provider that added them. +Dynamic parameters are cmdlet parameters that are added to a cmdlet by a +provider. These parameters are available only when the cmdlet is used with the +provider that added them. -For example, the Cert: drive adds the CodeSigningCert parameter -to the Get-Item and Get-ChildItem cmdlets. You can use this parameter -only when you use Get-Item or Get-ChildItem in the Cert: drive. +For example, the Cert: drive adds the CodeSigningCert parameter to the +Get-Item and Get-ChildItem cmdlets. You can use this parameter only when you +use Get-Item or Get-ChildItem in the Cert: drive. -For a list of the dynamic parameters that a provider supports, see the -Help file for the provider. Type: +For a list of the dynamic parameters that a provider supports, see the Help +file for the provider. Type: -Get-Help +``` +get-help +``` For example: -Get-Help Certificate +```powershell +get-help certificate +``` -# LEARNING ABOUT PROVIDERS +## LEARNING ABOUT PROVIDERS -Although all provider data appears in drives, and you use the same methods -to move through them, the similarity stops there. The data stores that -the provider exposes can be as varied as Active Directory locations and -Microsoft Exchange Server mailboxes. +Although all provider data appears in drives, and you use the same methods to +move through them, the similarity stops there. The data stores that the +provider exposes can be as varied as Active Directory locations and Microsoft +Exchange Server mailboxes. For information about individual Windows PowerShell providers, type: -Get-Help +``` +get-help +``` For example: -Get-Help Registry +```powershell +get-help registry +``` For a list of Help topics about the providers, type: -Get-Help * -Category provider +```powershell +get-help * -category provider +``` -# SEE ALSO +## SEE ALSO -about_Locations +[about_Locations](about_Locations.md) [about_Path_Syntax](about_Path_Syntax.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/6/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 8e8248c24f78..8df82dca043b 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,290 +7,272 @@ title: about_Quoting_Rules --- # About Quoting Rules -## about_Quoting_Rules - ## SHORT DESCRIPTION -Describes rules for using single and double quotation marks in Windows PowerShell. +Describes rules for using single and double quotation marks in PowerShell. ## LONG DESCRIPTION -Quotation marks are used to specify a literal string. You can enclose a string in single quotation marks (') or double quotation marks ("). -Quotation marks are also used to create a here-string. A here-string is a single-quoted or double-quoted string in which quotation marks are interpreted literally. A here-string can span multiple lines. All the lines in a here-string are interpreted as strings, even though they are not enclosed in quotation marks. +Quotation marks are used to specify a literal string. You can enclose a string +in single quotation marks (') or double quotation marks ("). -In commands to remote computers, quotation marks define the parts of the command that are run on the remote computer. In a remote session, quotation marks also determine whether the variables in a command are interpreted first on the local computer or on the remote computer. +Quotation marks are also used to create a here-string. A here-string is a +single-quoted or double-quoted string in which quotation marks are interpreted +literally. A here-string can span multiple lines. All the lines in a +here-string are interpreted as strings, even though they are not enclosed in +quotation marks. +In commands to remote computers, quotation marks define the parts of the +command that are run on the remote computer. In a remote session, quotation +marks also determine whether the variables in a command are interpreted first +on the local computer or on the remote computer. ### SINGLE AND DOUBLE-QUOTED STRINGS -When you enclose a string in double quotation marks (a double-quoted string), variable names that are preceded by a dollar sign ($) are replaced with the variable's value before the string is passed to the command for processing. -For example: +When you enclose a string in double quotation marks (a double-quoted string), +variable names that are preceded by a dollar sign ($) are replaced with the +variable's value before the string is passed to the command for processing. +For example: -``` +```powershell $i = 5 "The value of $i is $i." ``` - The output of this command is: - -``` +```output The value of 5 is 5. ``` +Also, in a double-quoted string, expressions are evaluated, and the result is +inserted in the string. For example: -Also, in a double-quoted string, expressions are evaluated, and the result is inserted in the string. For example: - - -``` +```powershell "The value of $(2+3) is 5." ``` - The output of this command is: - -``` +```output The value of 5 is 5. ``` +When you enclose a string in single-quotation marks (a single-quoted string), +the string is passed to the command exactly as you type it. No substitution is +performed. For example: -When you enclose a string in single-quotation marks (a single-quoted string), the string is passed to the command exactly as you type it. No substitution is performed. For example: - - -``` +```powershell $i = 5 'The value of $i is $i.' ``` - The output of this command is: - -``` +```output The value $i is $i. ``` +Similarly, expressions in single-quoted strings are not evaluated. They are +interpreted as literals. For example: -Similarly, expressions in single-quoted strings are not evaluated. They are interpreted as literals. For example: - - -``` +```powershell 'The value of $(2+3) is 5.' ``` - The output of this command is: - -``` +```output The value of $(2+3) is 5. ``` +To prevent the substitution of a variable value in a double-quoted string, use +the backtick character (`)(ASCII 96), which is the Windows PowerShell escape +character. -To prevent the substitution of a variable value in a double-quoted string, use the backtick character (`)(ASCII 96), which is the Windows PowerShell escape character. - -In the following example, the backtick character that precedes the first $i variable prevents Windows PowerShell from replacing the variable name with its value. For example: - +In the following example, the backtick character that precedes the first $i +variable prevents Windows PowerShell from replacing the variable name with its +value. For example: -``` +```powershell $i = 5 "The value of `$i is $i." ``` - The output of this command is: - -``` +```output The value $i is 5. ``` +To make double-quotation marks appear in a string, enclose the entire string +in single quotation marks. For example: -To make double-quotation marks appear in a string, enclose the entire string in single quotation marks. For example: - - -``` +```powershell 'As they say, "live and learn."' ``` - The output of this command is: - -``` +```output As they say, "live and learn." ``` +You can also enclose a single-quoted string in a double-quoted string. For +example: -You can also enclose a single-quoted string in a double-quoted string. For example: - - -``` +```powershell "As they say, 'live and learn.'" ``` - The output of this command is: - -``` +```output As they say, 'live and learn.' ``` - Or, double the quotation marks around a double-quoted phrase. For example: - -``` +```powershell "As they say, ""live and learn.""" ``` - The output of this command is: - -``` +```output As they say, "live and learn." ``` +To include a single quotation mark in a single-quoted string, use a second +consecutive single quote. For example: -To include a single quotation mark in a single-quoted string, use a second consecutive single quote. For example: - - -``` +```powershell 'don''t' ``` - The output of this command is: - -``` +```output don't ``` +To force Windows PowerShell to interpret a double quotation mark literally, +use a backtick character. This prevents Windows PowerShell from interpreting +the quotation mark as a string delimiter. For example: -To force Windows PowerShell to interpret a double quotation mark literally, use a backtick character. This prevents Windows PowerShell from interpreting the quotation mark as a string delimiter. For example: - - -``` +```powershell "Use a quotation mark (`") to begin a string." ``` +Because the contents of single-quoted strings are interpreted literally, you +cannot use the backtick character to force a literal character interpretation +in a single-quoted string. -Because the contents of single-quoted strings are interpreted literally, you cannot use the backtick character to force a literal character interpretation in a single-quoted string. - -For example, the following command generates an error because Windows PowerShell does not recognize the escape character. Instead, it interprets the second quotation mark as the end of the string. - +For example, the following command generates an error because Windows +PowerShell does not recognize the escape character. Instead, it interprets the +second quotation mark as the end of the string. -``` +```output PS C:\> 'Use a quotation mark (`') to begin a string.' Unexpected token ')' in expression or statement. At line:1 char:27 + 'Use a quotation mark (`') <<<< to begin a string.' ``` - - ### HERE-STRINGS + The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation marks are interpreted literally. A here-string can span multiple lines. All the lines in a here-string are interpreted as strings even though they are not enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string in which quotation +marks are interpreted literally. A here-string can span multiple lines. All +the lines in a here-string are interpreted as strings even though they are not +enclosed in quotation marks. -Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by their values. +Like regular strings, variables are replaced by their values in double-quoted +here-strings. In single-quoted here-strings, variables are not replaced by +their values. -You can use here-strings for any text, but they are particularly useful for the following kinds of text: +You can use here-strings for any text, but they are particularly useful for +the following kinds of text: --- Text that contains literal quotation marks --- Multiple lines of text, such as the text in an HTML or XML --- The Help text for a script or function document +- Text that contains literal quotation marks +- Multiple lines of text, such as the text in an HTML or XML +- The Help text for a script or function document -A here-string can have either of the following formats, where represents the linefeed or newline hidden character that is added when you press the ENTER key. +A here-string can have either of the following formats, where \ +represents the linefeed or newline hidden character that is added when you +press the ENTER key. +Double-quotes: ``` -Double-quotes: - @" - [string] ... - "@ +@" + [string] ... +"@ ``` - - -``` Single-quotes: - @' - [string] ... - '@ +``` +@' + [string] ... +'@ ``` +In either format, the closing quotation mark must be the first character in +the line. -In either format, the closing quotation mark must be the first character in the line. - -A here-string contains all the text between the two hidden characters. In the here-string, all quotation marks are interpreted literally. For example: - +A here-string contains all the text between the two hidden characters. In the +here-string, all quotation marks are interpreted literally. For example: -``` +```powershell @" For help, type "get-help" "@ ``` - The output of this command is: - -``` +```output For help, type "get-help" ``` - Using a here-string can simplify using a string in a command. For example: - -``` +```powershell @" Use a quotation mark (') to begin a string. "@ ``` - The output of this command is: - -``` +```output Use a quotation mark (') to begin a string. ``` +In single-quoted here-strings, variables are interpreted literally and +reproduced exactly. For example: -In single-quoted here-strings, variables are interpreted literally and reproduced exactly. For example: - - -``` +```powershell @' The $profile variable contains the path of your Windows PowerShell profile. '@ ``` - The output of this command is: - -``` +```output The $profile variable contains the path of your Windows PowerShell profile. ``` +In double-quoted here-strings, variables are replaced by their values. For +example: -In double-quoted here-strings, variables are replaced by their values. For example: - - -``` +```powershell @" Even if you have not created a profile, the path of the profile file is: @@ -298,21 +280,19 @@ $profile. "@ ``` - The output of this command is: - -``` +```output Even if you have not created a profile, the path of the profile file is: -C:\Users\User01\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1. +C:\Users\User1\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1. ``` +Here-strings are typically used to assign multiple lines to a variable. For +example, the following here-string assigns a page of XML to the $page +variable. -Here-strings are typically used to assign multiple lines to a variable. For example, the following here-string assigns a page of XML to the $page variable. - - -``` +```powershell $page = [XML] @" "@ ``` - -Here-strings are also a convenient format for input to the ConvertFrom-StringData cmdlet, which converts here-strings to hash tables. For more information, see ConvertFrom-StringData. - - -## KEYWORDS -about_Here-Strings - -about_Quotes - -about_Quotation_Marks - +Here-strings are also a convenient format for input to the +ConvertFrom-StringData cmdlet, which converts here-strings to hash tables. For +more information, see ConvertFrom-StringData. ## SEE ALSO [about_Special_Characters](about_Special_Characters.md) -ConvertFrom-StringData - +[ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Remote.md b/reference/6/Microsoft.PowerShell.Core/About/about_Remote.md index ac5e0c6fa90a..36455b275f7e 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Remote.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Remote.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,73 +7,74 @@ title: about_Remote --- # About Remote -## about_Remote - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes how to run remote commands in Windows PowerShell. -# LONG DESCRIPTION - -You can run remote commands on a single computer or on multiple -computers by using a temporary or persistent connection. You can also -start an interactive session with a single remote computer. +## LONG DESCRIPTION -This topic provides a series of examples to show you how to -run different types of remote command. After you try these basic -commands, read the Help topics that describe each cmdlet that is -used in these commands. The topics provide the details and explain -how you can modify the commands to meet your needs. +You can run remote commands on a single computer or on multiple computers by +using a temporary or persistent connection. You can also start an interactive +session with a single remote computer. -Note: To use Windows PowerShell remoting, the local and remote computers -must be configured for remoting. For more information, see -about_Remote_Requirements. +This topic provides a series of examples to show you how to run different +types of remote command. After you try these basic commands, read the Help +topics that describe each cmdlet that is used in these commands. The topics +provide the details and explain how you can modify the commands to meet your +needs. -# HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION) +Note: To use Windows PowerShell remoting, the local and remote computers must +be configured for remoting. For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). +## HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION) -The easiest way to run remote commands is to start an -interactive session with a remote computer. +The easiest way to run remote commands is to start an interactive session with +a remote computer. -When the session starts, the commands that you type run on the -remote computer, just as though you typed them directly -on the remote computer. You can connect to only one -computer in each interactive session. +When the session starts, the commands that you type run on the remote +computer, just as though you typed them directly on the remote computer. You +can connect to only one computer in each interactive session. -To start an interactive session, use the Enter-PSSession -cmdlet. The following command starts an interactive session -with the Server01 computer: +To start an interactive session, use the Enter-PSSession cmdlet. The following +command starts an interactive session with the Server01 computer: +```powershell Enter-PSSession Server01 +``` -The command prompt changes to indicate that you are connected -to the Server01 computer. +The command prompt changes to indicate that you are connected to the Server01 +computer. +``` Server01\PS> +``` Now, you can type commands on the Server01 computer. To end the interactive session, type: +```powershell Exit-PSSession +``` For more information, see Enter-PSSession. -# HOW TO USE CMDLETS THAT HAVE A COMPUTERNAME PARAMETER TO GET REMOTE DATA +## HOW TO USE CMDLETS THAT HAVE A COMPUTERNAME PARAMETER TO GET REMOTE DATA - -Several cmdlets have a ComputerName parameter that lets you -get objects from remote computers. +Several cmdlets have a ComputerName parameter that lets you get objects from +remote computers. Because these cmdlets do not use WS-Management-based Windows PowerShell remoting, you can use the ComputerName parameter of these cmdlets on any -computer that is running Windows PowerShell. The computers do not have to -be configured for Windows PowerShell remoting, and the computers do not -have to meet the system requirements for remoting. +computer that is running Windows PowerShell. The computers do not have to be +configured for Windows PowerShell remoting, and the computers do not have to +meet the system requirements for remoting. The following cmdlets have a ComputerName parameter: +``` Clear-EventLog Limit-EventLog Get-Counter New-EventLog Get-EventLog Remove-EventLog @@ -82,15 +83,18 @@ Get-Process Show-EventLog Get-Service Stop-Computer Get-WinEvent Test-Connection Get-WmiObject Write-EventLog +``` For example, the following command gets the services on the Server01 remote computer: +```powershell Get-Service -ComputerName Server01 +``` -Typically, cmdlets that support remoting without special configuration -have a **ComputerName** parameter and do not have a **Session** parameter. -To find these cmdlets in your session, type: +Typically, cmdlets that support remoting without special configuration have a +**ComputerName** parameter and do not have a **Session** parameter. To find +these cmdlets in your session, type: ```powershell Get-Command | Where-Object { @@ -99,131 +103,134 @@ Get-Command | Where-Object { } ``` -# HOW TO RUN A REMOTE COMMAND +## HOW TO RUN A REMOTE COMMAND +To run other commands on remote computers, use the Invoke-Command cmdlet. -To run other commands on remote computers, use the -Invoke-Command cmdlet. +To run a single command or a few unrelated commands, use the ComputerName +parameter of Invoke-Command to specify the remote computers. Use the +ScriptBlock parameter to specify the command. -To run a single command or a few unrelated commands, use the -ComputerName parameter of Invoke-Command to specify the remote -computers. Use the ScriptBlock parameter to specify the command. - -For example, the following command runs a Get-Culture command -on the Server01 computer. +For example, the following command runs a Get-Culture command on the Server01 +computer. +```powershell Invoke-Command -ComputerName Server01 -ScriptBlock {Get-Culture} +``` -The ComputerName parameter is designed for situation in which you run -a single command or several unrelated commands on one or many computers. -To establish a persistent connection to a remote computer, use -the Session parameter. - -# HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION) +The ComputerName parameter is designed for situation in which you run a single +command or several unrelated commands on one or many computers. To establish a +persistent connection to a remote computer, use the Session parameter. +## HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION) -When you use the ComputerName parameter of the Invoke-Command -cmdlet, Windows PowerShell establishes a connection just for the -command. Then, it closes the connection when the command is complete. Any -variables or functions that are defined in the command are lost. +When you use the ComputerName parameter of the Invoke-Command cmdlet, Windows +PowerShell establishes a connection just for the command. Then, it closes the +connection when the command is complete. Any variables or functions that are +defined in the command are lost. -To create a persistent connection to a remote computer, use the -New-PSSession cmdlet. For example, the following command creates -PSSessions on the Server01 and Server02 computers and then saves the -PSSessions in the $s variable. +To create a persistent connection to a remote computer, use the New-PSSession +cmdlet. For example, the following command creates PSSessions on the Server01 +and Server02 computers and then saves the PSSessions in the $s variable. +```powershell $s = New-PSSession -ComputerName Server01, Server02 +``` -# HOW TO RUN COMMANDS IN A PSSESSION - +## HOW TO RUN COMMANDS IN A PSSESSION -With a PSSession, you can run a series of remote commands that -share data, like functions, aliases, and the values of variables. -To run commands in a PSSession, use the Session parameter of the -Invoke-Command cmdlet. +With a PSSession, you can run a series of remote commands that share data, +like functions, aliases, and the values of variables. To run commands in a +PSSession, use the Session parameter of the Invoke-Command cmdlet. -For example, the following command uses the Invoke-Command cmdlet -to run a Get-Process command in the PSSessions on the Server01 -and Server02 computers. The command saves the processes in a $p -variable in each PSSession. +For example, the following command uses the Invoke-Command cmdlet to run a +Get-Process command in the PSSessions on the Server01 and Server02 computers. +The command saves the processes in a $p variable in each PSSession. +```powershell Invoke-Command -Session $s -ScriptBlock {$p = Get-Process} +``` -Because the PSSession uses a persistent connection, you can run -another command in the same PSSession that uses the $p variable. -The following command counts the number of processes saved in $p. +Because the PSSession uses a persistent connection, you can run another +command in the same PSSession that uses the $p variable. The following command +counts the number of processes saved in $p. +```powershell Invoke-Command -Session $s -ScriptBlock {$p.count} +``` -# HOW TO RUN A REMOTE COMMAND ON MULTIPLE COMPUTERS - +## HOW TO RUN A REMOTE COMMAND ON MULTIPLE COMPUTERS -To run a remote command on multiple computers, type all of -the computer names in the value of the ComputerName parameter of -Invoke-Command. Separate the names with commas. +To run a remote command on multiple computers, type all of the computer names +in the value of the ComputerName parameter of Invoke-Command. Separate the +names with commas. -For example, the following command runs a Get-Culture command -on three computers: +For example, the following command runs a Get-Culture command on three +computers: +```powershell Invoke-Command -ComputerName S1, S2, S3 -ScriptBlock {Get-Culture} +``` -You can also run a command in multiple PSSessions. The following -commands create PSSessions on the Server01, Server02, and Server03 -computers and then run a Get-Culture command in each of the PSSessions. +You can also run a command in multiple PSSessions. The following commands +create PSSessions on the Server01, Server02, and Server03 computers and then +run a Get-Culture command in each of the PSSessions. +```powershell $s = New-PSSession -ComputerName S1, S2, S3 Invoke-Command -Session $s -ScriptBlock {Get-Culture} +``` To include the local computer list of computers, type the name of the local computer, type a dot (.), or type "localhost". +```powershell Invoke-Command -ComputerName S1, S2, S3, localhost -ScriptBlock {Get-Culture} +``` -# HOW TO RUN A SCRIPT ON REMOTE COMPUTERS - +## HOW TO RUN A SCRIPT ON REMOTE COMPUTERS -To run a local script on remote computers, use the -FilePath parameter of Invoke-Command. +To run a local script on remote computers, use the FilePath parameter of +Invoke-Command. -For example, the following command runs the Sample.ps1 script -on the S1 and S2 computers: +For example, the following command runs the Sample.ps1 script on the S1 and S2 +computers: +```powershell Invoke-Command -ComputerName S1, S2 -FilePath C:\Test\Sample.ps1 +``` -The results of the script are returned to the local computer. You -do not need to copy any files. - -# HOW TO STOP A REMOTE COMMAND - +The results of the script are returned to the local computer. You do not need +to copy any files. -To interrupt a command, press CTRL+C. The interrupt request is -passed to the remote computer where it terminates the remote command. +## HOW TO STOP A REMOTE COMMAND -# FOR MORE INFORMATION +To interrupt a command, press CTRL+C. The interrupt request is passed to the +remote computer where it terminates the remote command. +## FOR MORE INFORMATION --- For information about the system requirements for remoting, -see about_Remote_Requirements. +- For information about the system requirements for remoting, see + [about_Remote_Requirements](about_Remote_Requirements.md). --- For help in formatting remote output, see about_Remote_Output. +- For help in formatting remote output, see [about_Remote_Output](about_Remote_Output.md). --- For information about how remoting works, how to manage remote -data, special configurations, security issues, and other frequently -asked questions, see about_Remote_FAQ. +- For information about how remoting works, how to manage remote data, special + configurations, security issues, and other frequently asked questions, see + [about_Remote_FAQ](about_Remote_FAQ.md). --- For help in resolving remoting errors, see about_Remote_Troubleshooting. +- For help in resolving remoting errors, see about_Remote_Troubleshooting. --- For information about PSSessions and persistent connections, see -about_PSSessions. +- For information about PSSessions and persistent connections, see + [about_PSSessions](about_PSSessions.md). --- For information about Windows PowerShell background jobs, see -about_Jobs. +- For information about Windows PowerShell background jobs, see [about_Jobs](about_Jobs.md). -# KEYWORDS +## KEYWORDS about_Remoting -# SEE ALSO +## SEE ALSO [about_PSSessions](about_PSSessions.md) @@ -237,9 +244,8 @@ about_Remoting [about_Remote_Variables](about_Remote_Variables.md) -Enter-PSSession - -Invoke-Command +[Enter-PSSession](../Enter-PSSession.md) -New-PSSession +[Invoke-Command](../Invoke-Command.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md index eda447268fcd..445c1fa6f6b9 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Requirements.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,77 +7,71 @@ title: about_Remote_Requirements --- # About Remote Requirements -## about_Remote_Requirements +## SHORT DESCRIPTION +Describes the system requirements and configuration requirements for running +remote commands in Windows PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes the system requirements and configuration requirements for -running remote commands in Windows PowerShell. - -# LONG DESCRIPTION - -This topic describes the system requirements, user requirements, and -resource requirements for establishing remote connections and running -remote commands in Windows PowerShell. It also provides instructions for -configuring remote operations. +This topic describes the system requirements, user requirements, and resource +requirements for establishing remote connections and running remote commands +in Windows PowerShell. It also provides instructions for configuring remote +operations. Note: Many cmdlets (including the Get-Service, Get-Process, Get-WMIObject, -Get-EventLog, and Get-WinEvent cmdlets) get objects from remote -computers by using Microsoft .NET Framework methods to retrieve the -objects. They do not use the Windows PowerShell remoting -infrastructure. The requirements in this document do not apply to -these cmdlets. +Get-EventLog, and Get-WinEvent cmdlets) get objects from remote computers by +using Microsoft .NET Framework methods to retrieve the objects. They do not +use the Windows PowerShell remoting infrastructure. The requirements in this +document do not apply to these cmdlets. -To find the cmdlets that have a ComputerName parameter but do not use -Windows PowerShell remoting, read the description of the ComputerName -parameter of the cmdlets. - -# SYSTEM REQUIREMENTS +To find the cmdlets that have a ComputerName parameter but do not use Windows +PowerShell remoting, read the description of the ComputerName parameter of the +cmdlets. +## SYSTEM REQUIREMENTS To run remote sessions on Windows PowerShell 3.0, the local and remote computers must have the following: --- Windows PowerShell 3.0 or later --- The Microsoft .NET Framework 4 or later --- Windows Remote Management 3.0 +- Windows PowerShell 3.0 or later +- The Microsoft .NET Framework 4 or later +- Windows Remote Management 3.0 -To run remote sessions on Windows PowerShell 2.0, the local and remote computers -must have the following: +To run remote sessions on Windows PowerShell 2.0, the local and remote +computers must have the following: --- Windows PowerShell 2.0 or later --- The Microsoft .NET Framework 2.0 or later --- Windows Remote Management 2.0 +- Windows PowerShell 2.0 or later +- The Microsoft .NET Framework 2.0 or later +- Windows Remote Management 2.0 -You can create remote sessions between computers running Windows PowerShell 2.0 -and Windows PowerShell 3.0. However, features that run only on Windows -PowerShell 3.0, such as the ability to disconnect and reconnect to sessions, are -available only when both computers are running Windows PowerShell 3.0. +You can create remote sessions between computers running Windows PowerShell +2.0 and Windows PowerShell 3.0. However, features that run only on Windows +PowerShell 3.0, such as the ability to disconnect and reconnect to sessions, +are available only when both computers are running Windows PowerShell 3.0. To find the version number of an installed version of Windows PowerShell, use the $PSVersionTable automatic variable. -Windows Remote Management (WinRM) 3.0 and Microsoft .NET Framework 4 are included -in Windows 8, Windows Server 2012, and newer releases of the Windows operating -system. WinRM 3.0 is included in Windows Management Framework 3.0 for older -operating systems. If the computer does not have the required version of -WinRM or the Microsoft .NET Framework, the installation fails. - -# USER PERMISSIONS +Windows Remote Management (WinRM) 3.0 and Microsoft .NET Framework 4 are +included in Windows 8, Windows Server 2012, and newer releases of the Windows +operating system. WinRM 3.0 is included in Windows Management Framework 3.0 +for older operating systems. If the computer does not have the required +version of WinRM or the Microsoft .NET Framework, the installation fails. +## USER PERMISSIONS To create remote sessions and run remote commands, by default, the current user must be a member of the Administrators group on the remote computer or provide the credentials of an administrator. Otherwise, the command fails. The permissions required to create sessions and run commands on a remote -computer (or in a remote session on the local computer) are established by -the session configuration (also known as an "endpoint") on the remote -computer to which the session connects. Specifically, the security -descriptor on the session configuration determines who has access to the -session configuration and who can use it to connect. +computer (or in a remote session on the local computer) are established by the +session configuration (also known as an "endpoint") on the remote computer to +which the session connects. Specifically, the security descriptor on the +session configuration determines who has access to the session configuration +and who can use it to connect. The security descriptors on the default session configurations, Microsoft.PowerShell, Microsoft.PowerShell32, and @@ -85,48 +79,50 @@ Microsoft.PowerShell.Workflow, allow access only to members of the Administrators group. If the current user doesn't have permission to use the session configuration, -the command to run a command (which uses a temporary session) or create -a persistent session on the remote computer fails. The user can use the +the command to run a command (which uses a temporary session) or create a +persistent session on the remote computer fails. The user can use the ConfigurationName parameter of cmdlets that create sessions to select a different session configuration, if one is available. Members of the Administrators group on a computer can determine who has permission to connect to the computer remotely by changing the security -descriptors on the default session configurations and by creating new -session configurations with different security descriptors. +descriptors on the default session configurations and by creating new session +configurations with different security descriptors. For more informations about session configurations, see -about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). +[about_Session_Configurations](about_Session_Configurations.md). -# WINDOWS NETWORK LOCATIONS +## WINDOWS NETWORK LOCATIONS Beginning in Windows PowerShell 3.0, the Enable-PSRemoting cmdlet can enable remoting on client and server versions of Windows on private, domain, and public networks. On server versions of Windows with private and domain networks, the -Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted -remote access. It also creates a firewall rule for public networks that -allows remote access only from computers in the same local subnet. This -local subnet firewall rule is enabled by default on server versions of -Windows on public networks, but Enable-PSRemoting reapplies the rule in -case it was changed or deleted. - -On client versions of Windows with private and domain networks, by -default, the Enable-PSRemoting cmdlet creates firewall rules that -allow unrestricted remote access. - -To enable remoting on client versions of Windows with public networks, -use the SkipNetworkProfileCheck parameter of the Enable-PSRemoting cmdlet. -It creates a firewall rule that that allows remote access only from -computers in the same local subnet. +Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted remote +access. It also creates a firewall rule for public networks that allows remote +access only from computers in the same local subnet. This local subnet +firewall rule is enabled by default on server versions of Windows on public +networks, but Enable-PSRemoting reapplies the rule in case it was changed or +deleted. + +On client versions of Windows with private and domain networks, by default, +the Enable-PSRemoting cmdlet creates firewall rules that allow unrestricted +remote access. + +To enable remoting on client versions of Windows with public networks, use the +SkipNetworkProfileCheck parameter of the Enable-PSRemoting cmdlet. It creates +a firewall rule that that allows remote access only from computers in the same +local subnet. To remove the local subnet restriction on public networks and allow remote -access from all locations on client and server versions of Windows, use -the Set-NetFirewallRule cmdlet in the NetSecurity module. Run the following +access from all locations on client and server versions of Windows, use the +Set-NetFirewallRule cmdlet in the NetSecurity module. Run the following command: +```powershell Set-NetFirewallRule -Name "WINRM-HTTP-In-TCP-PUBLIC" -RemoteAddress Any +``` In Windows PowerShell 2.0, on server versions of Windows, Enable-PSRemoting creates firewall rules that permit remote access on all networks. @@ -134,64 +130,55 @@ creates firewall rules that permit remote access on all networks. In Windows PowerShell 2.0, on client versions of Windows, Enable-PSRemoting creates firewall rules only on private and domain networks. If the network location is public, Enable-PSRemoting fails. -# . - -# RUN AS ADMINISTRATOR +## RUN AS ADMINISTRATOR +Administrator privileges are required for the following remoting operations: -Administrator privileges are required for the following remoting -operations: +- Establishing a remote connection to the local computer. This is commonly + known as a "loopback" scenario. --- Establishing a remote connection to the local computer. This is -commonly known as a "loopback" scenario. +- Managing session configurations on the local computer. --- Managing session configurations on the local computer. +- Viewing and changing WS-Management settings on the local computer. These are + the settings in the LocalHost node of the WSMAN: drive. --- Viewing and changing WS-Management settings on the local computer. -These are the settings in the LocalHost node of the WSMAN: drive. +To perform these tasks, you must start Windows PowerShell with the "Run as +administrator" option even if you are a member of the Administrators group on +the local computer. -To perform these tasks, you must start Windows PowerShell with the "Run -as administrator" option even if you are a member of the Administrators -group on the local computer. - -In Windows 7 and in Windows Server 2008 R2, to start Windows PowerShell -with the "Run as administrator" option: +In Windows 7 and in Windows Server 2008 R2, to start Windows PowerShell with +the "Run as administrator" option: 1. Click Start, click All Programs, click Accessories, and then click -the Windows PowerShell folder. - -2. Right-click Windows PowerShell, and then click -"Run as administrator". + the Windows PowerShell folder. +2. Right-click Windows PowerShell, and then click "Run as administrator". To start Windows PowerShell with the "Run as administrator" option: -1. Click Start, click All Programs, and then click the Windows -PowerShell folder. +1. Click Start, click All Programs, and then click the Windows PowerShell + folder. +2. Right-click Windows PowerShell, and then click "Run as administrator". -2. Right-click Windows PowerShell, and then click -"Run as administrator". - -The "Run as administrator" option is also available in other Windows -Explorer entries for Windows PowerShell, including shortcuts. Just -right-click the item, and then click "Run as administrator". +The "Run as administrator" option is also available in other Windows Explorer +entries for Windows PowerShell, including shortcuts. Just right-click the +item, and then click "Run as administrator". When you start Windows PowerShell from another program such as Cmd.exe, use the "Run as administrator" option to start the program. -# HOW TO CONFIGURE YOUR COMPUTER FOR REMOTING - +## HOW TO CONFIGURE YOUR COMPUTER FOR REMOTING Computers running all supported versions of Windows can establish remote connections to and run remote commands in Windows PowerShell without any configuration. However, to receive connections, and allow users to create -local and remote user-managed Windows PowerShell sessions ("PSSessions") -and run commands on the local computer, you must enable Windows PowerShell +local and remote user-managed Windows PowerShell sessions ("PSSessions") and +run commands on the local computer, you must enable Windows PowerShell remoting on the computer. Windows Server 2012 and newer releases of Windows Server are enabled for -Windows PowerShell remoting by default. If the settings are changed, -you can restore the default settings by running the Enable-PSRemoting cmdlet. +Windows PowerShell remoting by default. If the settings are changed, you can +restore the default settings by running the Enable-PSRemoting cmdlet. On all other supported versions of Windows, you need to run the Enable-PSRemoting cmdlet to enable Windows PowerShell remoting. @@ -199,45 +186,43 @@ Enable-PSRemoting cmdlet to enable Windows PowerShell remoting. The remoting features of Windows PowerShell are supported by the WinRM service, which is the Microsoft implementation of the Web Services for Management (WS-Management) protocol. When you enable Windows PowerShell -remoting, you change the default configuration of WS-Management and add -system configuration that allow users to connect to WS-Management. +remoting, you change the default configuration of WS-Management and add system +configuration that allow users to connect to WS-Management. To configure Windows PowerShell to receive remote commands: -1. Start Windows PowerShell with the "Run as administrator" -option. - -2. At the command prompt, type: -Enable-PSRemoting +1. Start Windows PowerShell with the "Run as administrator" option. +2. At the command prompt, type: `Enable-PSRemoting` To verify that remoting is configured correctly, run a test command such as -the following command, which creates a remote session on the local -computer. +the following command, which creates a remote session on the local computer. +```powershell New-PSSession +``` -If remoting is configured correctly, the command will create a session on -the local computer and return an object that represents the session. The -output should resemble the following sample output: - -C:\PS> new-pssession +If remoting is configured correctly, the command will create a session on the +local computer and return an object that represents the session. The output +should resemble the following sample output: +```output Id Name ComputerName State ConfigurationName -- ---- ------------ ----- ----- 1 Session1 localhost Opened Microsoft.PowerShell +``` -If the command fails, for assistance, see about_Remote_Troubleshooting. +If the command fails, for assistance, see +[about_Remote_Troubleshooting](about_Remote_Troubleshooting.md). -# UNDERSTAND POLICIES +## UNDERSTAND POLICIES +When you work remotely, you use two instances of Windows PowerShell, one on +the local computer and one on the remote computer. As a result, your work is +affected by the Windows policies and the Windows PowerShell policies on the +local and remote computers. -When you work remotely, you use two instances of Windows PowerShell, one -on the local computer and one on the remote computer. As a result, your -work is affected by the Windows policies and the Windows PowerShell -policies on the local and remote computers. - -In general, before you connect and as you are establishing the connection, -the policies on the local computer are in effect. When you are using the +In general, before you connect and as you are establishing the connection, the +policies on the local computer are in effect. When you are using the connection, the policies on the remote computer are in effect. # SEE ALSO @@ -248,9 +233,8 @@ connection, the policies on the remote computer are in effect. [about_PSSessions](about_PSSessions.md) -Invoke-Command - -Enter-PSSession +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md index 33bf188649a7..cdd13115f8e0 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Variables.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,108 +7,109 @@ title: about_Remote_Variables --- # About Remote Variables -## about_Remote_Variables +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use local and remote variables in remote commands. -Explains how to use local and remote variables in remote -commands. +## LONG DESCRIPTION -# LONG DESCRIPTION - -You can use variables in commands that you run on remote -computers. Simply assign a value to the variable and then -use the variable in place of the value. - -By default, the variables in remote commands are assumed -to be defined in the session in which the command runs. You -can also use variables that are defined in the local session, -but you must identify them as local -variables in the command. - -# USING REMOTE VARIABLES - - -Windows PowerShell assumes that the variables used in remote -commands are defined in the session in which the command runs. +You can use variables in commands that you run on remote computers. Simply +assign a value to the variable and then use the variable in place of the +value. -In the following example, the $ps variable is defined in the -temporary session in which the Get-WinEvent command runs. +By default, the variables in remote commands are assumed to be defined in the +session in which the command runs. You can also use variables that are defined +in the local session, but you must identify them as local variables in the +command. -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"; Get-WinEvent -LogName $ps} +## USING REMOTE VARIABLES -Similarly, when the command runs in a persistent session (PSSession), -the remote variable must be defined in the same PSSession. +Windows PowerShell assumes that the variables used in remote commands are +defined in the session in which the command runs. -PS C:> $s = New-PSSession -ComputerName S1 +In the following example, the \$ps variable is defined in the temporary session +in which the Get-WinEvent command runs. -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"} +```powershell +Invoke-Command -ComputerName S1 -ScriptBlock { + $ps = "Windows PowerShell"; Get-WinEvent -LogName $ps +} +``` -PS C:> Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $ps} +Similarly, when the command runs in a persistent session (PSSession), the +remote variable must be defined in the same PSSession. -# USING LOCAL VARIABLES +```powershell +$s = New-PSSession -ComputerName S1 +Invoke-Command -ComputerName S1 -ScriptBlock {$ps = "Windows PowerShell"} +Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $ps} +``` +## USING LOCAL VARIABLES -You can also use local variables in remote commands, but you must -indicate that the variable is defined in the local session. +You can also use local variables in remote commands, but you must indicate +that the variable is defined in the local session. -Beginning in Windows PowerShell 3.0, you can use the Using scope -modifier to identify a local variable in a remote command. +Beginning in Windows PowerShell 3.0, you can use the Using scope modifier to +identify a local variable in a remote command. The syntax of Using is as follows: -The syntax is: +``` $Using: +``` -In the following example, the $ps variable is created in the local -session, but is used in the session in which the command runs. The -Using scope modifier identifies $ps as a local variable. +In the following example, the $ps variable is created in the local session, +but is used in the session in which the command runs. The Using scope modifier +identifies $ps as a local variable. -PS C:> $ps = "Windows PowerShell" -PS C:> Invoke-Command -ComputerName S1 -ScriptBlock {Get-WinEvent -LogName $Using:ps} +```powershell +$ps = "Windows PowerShell" +Invoke-Command -ComputerName S1 -ScriptBlock { + Get-WinEvent -LogName $Using:ps +} +``` You can also use the Using scope modifier in PSSessions. -PS C:> $s = New-PSSession -ComputerName S1 - -PS C:> $ps = "Windows PowerShell" +```powershell +$s = New-PSSession -ComputerName S1 +$ps = "Windows PowerShell" +Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +``` -PS C:> Invoke-Command -Sessions $s -ScriptBlock {Get-WinEvent -LogName $Using:ps} +## USING LOCAL VARIABLES IN WINDOWS POWERSHELL 2.0 -# USING LOCAL VARIABLES IN WINDOWS POWERSHELL 2.0 +You can use local variables in a remote command by defining parameters for the +remote command and using the ArgumentList parameter of the Invoke-Command +cmdlet to specify the local variable as the parameter value. +This command format is valid on Windows PowerShell 2.0 and later versions of +Windows PowerShell. -You can use local variables in a remote command by defining parameters -for the remote command and using the ArgumentList parameter of the -Invoke-Command cmdlet to specify the local variable as the parameter -value. - -This command format is valid on Windows PowerShell 2.0 and later versions -of Windows PowerShell. +- Use the param keyword to define parameters for the remote command. The + parameter names are placeholders that do not need to match the name of the + local variable. --- Use the param keyword to define parameters for the remote command. -The parameter names are placeholders that do not need to match the -name of the local variable. +- Use the parameters defined by the param keyword in the command. --- Use the parameters defined by the param keyword in the command. - --- Use the ArgumentList parameter of the Invoke-Command cmdlet to -specify the local variable as the parameter value. +- Use the ArgumentList parameter of the Invoke-Command cmdlet to specify the + local variable as the parameter value. For example, the following commands define the $ps variable in the local -session and then use it in a remote command. The command uses $log as -the parameter name and the local variable, $ps, as its value. - -C:\PS>$ps = "Windows PowerShell" +session and then use it in a remote command. The command uses $log as the +parameter name and the local variable, $ps, as its value. -C:\PS>Invoke-Command -ComputerName S1 -ScriptBlock {param($log) Get-WinEvent -logname $log} -ArgumentList $ps +```powershell +$ps = "Windows PowerShell" +Invoke-Command -ComputerName S1 -ScriptBlock { + param($log) + Get-WinEvent -logname $log +} -ArgumentList $ps +``` -# KEYWORDS - -about_Using - -# SEE ALSO +## SEE ALSO [about_Remote](about_Remote.md) @@ -116,9 +117,8 @@ about_Using [about_Scopes](about_Scopes.md) -Enter-PSSession - -Invoke-Command +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[New-PSSession](../New-PSSession.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/6/Microsoft.PowerShell.Core/About/about_Requires.md index 4ae85a982fc2..93f468542189 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Requires.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -142,8 +142,3 @@ always a snap-in. [about_Automatic_Variables](about_Automatic_Variables.md) [about_Language_Keywords](about_Language_Keywords.md) - -[about_PSSnapins](about_PSSnapins.md) - -Get-PSSnapin - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Reserved_Words.md b/reference/6/Microsoft.PowerShell.Core/About/about_Reserved_Words.md index 874a7e5fd8a1..4c2f92e8b5fc 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Reserved_Words.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Reserved_Words.md @@ -70,8 +70,8 @@ Get-Help ## SEE ALSO - [about_Command_Syntax](about_Command_Syntax.md) -- [about_Special_Characters](about_Special_Characters.md) - [about_Language_Keywords](about_Language_Keywords.md) - [about_Parsing](about_Parsing.md) - [about_Quoting_Rules](about_Quoting_Rules.md) - [about_Script_Blocks](about_Script_Blocks.md) +- [about_Special_Characters](about_Special_Characters.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Return.md b/reference/6/Microsoft.PowerShell.Core/About/about_Return.md index ff684edeef37..bcb1e40e8d25 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Return.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Return.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,118 +7,115 @@ title: about_Return --- # About Return -## about_Return - ## SHORT DESCRIPTION -Exits the current scope, which can be a function, script, or script block. +Exits the current scope, which can be a function, script, or script block. ## LONG DESCRIPTION -The Return keyword exits a function, script, or script block. It can be used to exit a scope at a specific point, to return a value, or to indicate that the end of the scope has been reached. -Users who are familiar with languages like C or C\# might want to use the Return keyword to make the logic of leaving a scope explicit. + The Return keyword exits a function, script, or script block. It can be used + to exit a scope at a specific point, to return a value, or to indicate that + the end of the scope has been reached. -In Windows PowerShell, the results of each statement are returned as output, even without a statement that contains the Return keyword. Languages like C or C\# return only the value or values that are specified by the Return keyword. +Users who are familiar with languages like C or C\# might want to use the +Return keyword to make the logic of leaving a scope explicit. +In PowerShell, the results of each statement are returned as output, +even without a statement that contains the Return keyword. Languages like C or +C\# return only the value or values that are specified by the Return keyword. ### SYNTAX -The syntax for the Return keyword is as follows: +The syntax for the Return keyword is as follows: ``` return [] ``` - -The Return keyword can appear alone, or it can be followed by a value or expression, as follows: - +The Return keyword can appear alone, or it can be followed by a value or +expression, as follows: ``` -return -return $a +return +return $a return (2 + $a) ``` - ### EXAMPLES -The following example uses the Return keyword to exit a function at a specific point if a conditional is met: +The following example uses the Return keyword to exit a function at a specific +point if a conditional is met: ``` -function ScreenPassword($instance) -{ - if (!($instance.screensaversecure)) {return $instance.name} - -} - +function ScreenPassword($instance) +{ + if (!($instance.screensaversecure)) {return $instance.name} + +} + foreach ($a in @(get-wmiobject win32_desktop)) { ScreenPassword($a) } ``` +This script checks each user account. The ScreenPassword function returns the +name of any user account that does not have a password-protected screen saver. +If the screen saver is password protected, the function completes any other +statements to be run, and PowerShell does not return any value. -This script checks each user account. The ScreenPassword function returns the name of any user account that does not have a password-protected screen saver. If the screen saver is password protected, the function completes any other statements to be run, and Windows PowerShell does not return any value. - -In Windows PowerShell, values can be returned even if the Return keyword is not used. The results of each statement are returned. For example, the following statements return the value of the $a variable: - +In PowerShell, values can be returned even if the Return keyword is not used. +The results of each statement are returned. For example, the following +statements return the value of the \$a variable: ``` -$a +$a return ``` - The following statement also returns the value of $a: - ``` return $a ``` +The following example includes a statement intended to let the user know that +the function is performing a calculation: -The following example includes a statement intended to let the user know that the function is performing a calculation: +```powershell +function calculation { + param ($value) - -``` -function calculation { - param ($value) - - "Please wait. Working on calculation..." - $value += 73 - return $value - } + "Please wait. Working on calculation..." + $value += 73 + return $value +} ``` +Running this function and assigning the result to a variable has the following +effect: -Running this function and assigning the result to a variable has the following effect: - - -``` -C:\PS> $a = calculation 14 -C:\PS> +```powershell +$a = calculation 14 ``` +The "Please wait. Working on calculation..." string is not displayed. Instead, +it is assigned to the $a variable, as in the following example: -The "Please wait. Working on calculation..." string is not displayed. Instead, it is assigned to the $a variable, as in the following example: - - -``` -C:\PS> $a -Please wait. Working on calculation... +```output +C:\PS> $a +Please wait. Working on calculation... 87 ``` - -Both the informational string and the result of the calculation are returned by the function and assigned to the $a variable. - +Both the informational string and the result of the calculation are returned +by the function and assigned to the \$a variable. ## SEE ALSO -Exit keyword in [about_Language_Keywords](about_Language_Keywords.md) +[about_Language_Keywords](about_Language_Keywords.md) [about_Functions](about_Functions.md) [about_Scopes](about_Scopes.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md b/reference/6/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md index 43445a359c43..2e47af3dba57 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Run_With_PowerShell.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,62 +7,56 @@ title: about_Run_With_PowerShell --- # About Run With PowerShell -## about_Run_With_PowerShell +## SHORT DESCRIPTION -# SHORT DESCRIPTION +Explains how to use the "Run with PowerShell" feature to run a script from a +file system drive. -Explains how to use the "Run with PowerShell" feature to run -a script from a file system drive. +## LONG DESCRIPTION -# LONG DESCRIPTION +Beginning in Windows PowerShell 3.0, you can use the "Run with PowerShell" +feature to run scripts from File Explorer in Windows 8 and Windows Server 2012 +and from Windows Explorer in earlier versions of Windows. -Beginning in Windows PowerShell 3.0, you can use the "Run with -PowerShell" feature to run scripts from File Explorer in Windows 8 -and Windows Server 2012 and from Windows Explorer in earlier -versions of Windows. +The "Run with PowerShell" feature is designed to run scripts that do not have +required parameters and do not return output to the command prompt. -The "Run with PowerShell" feature is designed to run scripts -that do not have required parameters and do not return output -to the command prompt. - -When you use the "Run with PowerShell" feature, the Windows -PowerShell console window appears only briefly, if at all. -You cannot interact with it. +When you use the "Run with PowerShell" feature, the Windows PowerShell console +window appears only briefly, if at all. You cannot interact with it. To use the "Run with PowerShell" feature: -In File Explorer (or Windows Explorer), right-click the -script file name and then select "Run with PowerShell". +In File Explorer (or Windows Explorer), right-click the script file name and +then select "Run with PowerShell". -The "Run with PowerShell" feature starts a Windows PowerShell -session that has an execution policy of Bypass, runs the -script, and closes the session. +The "Run with PowerShell" feature starts a Windows PowerShell session that has +an execution policy of Bypass, runs the script, and closes the session. It runs a command that has the following format: + +``` PowerShell.exe -File -ExecutionPolicy Bypass +``` -"Run with PowerShell" sets the Bypass execution policy only -for the session (the current instance of the PowerShell process) -in which the script runs. This feature does not change the execution -policy for the computer or the user. +"Run with PowerShell" sets the Bypass execution policy only for the session +(the current instance of the PowerShell process) in which the script runs. +This feature does not change the execution policy for the computer or the +user. -The "Run with PowerShell" feature is affected only by the AllSigned -execution policy. If the AllSigned execution policy is effective for -the computer or the user, "Run with PowerShell" runs only signed -scripts. "Run with PowerShell" is not affected by any other execution -policy. For more information, see about_Execution_Policies. +The "Run with PowerShell" feature is affected only by the AllSigned execution +policy. If the AllSigned execution policy is effective for the computer or the +user, "Run with PowerShell" runs only signed scripts. "Run with PowerShell" is +not affected by any other execution policy. For more information, see +[about_Execution_Policies](about_Execution_Policies.md). -Troubleshooting Note: Run with PowerShell command might prompt you -to confirm the execution policy change. +Troubleshooting Note: Run with PowerShell command might prompt you to confirm +the execution policy change. -# SEE ALSO +## SEE ALSO [about_Execution_Policies](about_Execution_Policies.md) [about_Group_Policy_Settings](about_Group_Policy_Settings.md) [about_Scripts](about_Scripts.md) - -"Running Scripts" (http://go.microsoft.com/fwlink/?LinkId=257680) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md b/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md index f4cc17c0121f..92f18f04064d 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Scopes.md @@ -1,124 +1,114 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-08 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet -title: about_Scopes +title: about_scopes --- # About Scopes -## about_Scopes - about_Scopes -# SHORT DESCRIPTION +## SHORT DESCRIPTION -Explains the concept of scope in Windows PowerShell and shows how to set -and change the scope of elements. +Explains the concept of scope in PowerShell and shows how to set and change +the scope of elements. -# LONG DESCRIPTION +## LONG DESCRIPTION -Windows PowerShell protects access to variables, aliases, functions, and -Windows PowerShell drives (PSDrives) by limiting where they can be read and -changed. By enforcing a few simple rules for scope, Windows PowerShell -helps to ensure that you do not inadvertently change an item that should -not be changed. +PowerShell protects access to variables, aliases, functions, and PowerShell +drives (PSDrives) by limiting where they can be read and changed. By enforcing +a few simple rules for scope, PowerShell helps to ensure that you do not +inadvertently change an item that should not be changed. The following are the basic rules of scope: -- An item you include in a scope is visible in the scope in which it -was created and in any child scope, unless you explicitly make it -private. You can place variables, aliases, functions, or Windows -PowerShell drives in one or more scopes. - -- An item that you created within a scope can be changed only in the -scope in which it was created, unless you explicitly specify a -different scope. - -If you create an item in a scope, and the item shares its name with an -item in a different scope, the original item might be hidden under the -new item. But, it is not overridden or changed. - -Windows PowerShell Scopes - -Scopes in Windows PowerShell have both names and numbers. The named -scopes specify an absolute scope. The numbers are relative and reflect -the relationship between scopes. - -Global: -The scope that is in effect when Windows PowerShell -starts. Variables and functions that are present when -Windows PowerShell starts have been created in the -global scope. This includes automatic variables and -preference variables. This also includes the variables, aliases, -and functions that are in your Windows PowerShell -profiles. - -Local: -The current scope. The local scope can be the global -scope or any other scope. - -Script: -The scope that is created while a script file runs. Only -the commands in the script run in the script scope. To -the commands in a script, the script scope is the local -scope. +- An item you include in a scope is visible in the scope in which it was +created and in any child scope, unless you explicitly make it private. You can +place variables, aliases, functions, or PowerShell drives in one or +more scopes. + +- An item that you created within a scope can be changed only in the scope in +which it was created, unless you explicitly specify a different scope. -Private: -Items in private scope cannot be seen outside of the current -scope. You can use private scope to create a private version -of an item with the same name in another scope. - -Numbered Scopes: -You can refer to scopes by name or by a number that -describes the relative position of one scope to another. -Scope 0 represents the current, or local, scope. Scope 1 -indicates the immediate parent scope. Scope 2 indicates the -parent of the parent scope, and so on. Numbered scopes -are useful if you have created many recursive +If you create an item in a scope, and the item shares its name with an item in +a different scope, the original item might be hidden under the new item. But, +it is not overridden or changed. + +## PowerShell Scopes + +Scopes in PowerShell have both names and numbers. The named scopes specify an +absolute scope. The numbers are relative and reflect the relationship between scopes. -Parent and Child Scopes +- Global: The scope that is in effect when PowerShell starts. Variables and +functions that are present when PowerShell starts have been created in the +global scope. This includes automatic variables and preference variables. This +also includes the variables, aliases, and functions that are in your +PowerShell profiles. + +- Local: The current scope. The local scope can be the global scope or any +other scope. -You can create a new scope by running a script or function, by creating -a session, or by starting a new instance of Windows PowerShell. When you -create a new scope, the result is a parent scope (the original scope) and -a child scope (the scope that you created). +- Script: The scope that is created while a script file runs. Only the +commands in the script run in the script scope. To the commands in a script, +the script scope is the local scope. -In Windows PowerShell, all scopes are child scopes of the global scope, -but you can create many scopes and many recursive scopes. +- Private: Items in private scope cannot be seen outside of the current scope. +You can use private scope to create a private version of an item with the same +name in another scope. + +- Numbered Scopes: You can refer to scopes by name or by a number that describes +the relative position of one scope to another. Scope 0 represents the current, +or local, scope. Scope 1 indicates the immediate parent scope. Scope 2 +indicates the parent of the parent scope, and so on. Numbered scopes are +useful if you have created many recursive scopes. + +## Parent and Child Scopes + +You can create a new scope by running a script or function, by creating a +session, or by starting a new instance of PowerShell. When you create a new +scope, the result is a parent scope (the original scope) and a child scope +(the scope that you created). + +In PowerShell, all scopes are child scopes of the global scope, but you can +create many scopes and many recursive scopes. Unless you explicitly make the items private, the items in the parent scope -are available to the child scope. However, items that you create and change -in the child scope do not affect the parent scope, unless you explicitly -specify the scope when you create the items. +are available to the child scope. However, items that you create and change in +the child scope do not affect the parent scope, unless you explicitly specify +the scope when you create the items. -Inheritance +## Inheritance -A child scope does not inherit the variables, aliases, and functions from -the parent scope. Unless an item is private, the child scope can view the -items in the parent scope. And, it can change the items by explicitly -specifying the parent scope, but the items are not part of the child scope. +A child scope does not inherit the variables, aliases, and functions from the +parent scope. Unless an item is private, the child scope can view the items in +the parent scope. And, it can change the items by explicitly specifying the +parent scope, but the items are not part of the child scope. -However, a child scope is created with a set of items. Typically, it -includes all the aliases that have the AllScope option. This option is -discussed later in this topic. It includes all the variables that have the -AllScope option, plus some variables that can be used to customize the -scope, such as MaximumFunctionCount. +However, a child scope is created with a set of items. Typically, it includes +all the aliases that have the AllScope option. This option is discussed later +in this topic. It includes all the variables that have the AllScope option, +plus some variables that can be used to customize the scope, such as +MaximumFunctionCount. To find the items in a particular scope, use the Scope parameter of Get-Variable or Get-Alias. For example, to get all the variables in the local scope, type: +```powershell get-variable -scope local +``` To get all the variables in the global scope, type: +```powershell get-variable -scope global +``` -Scope Modifiers +## Scope Modifiers To specify the scope of a new variable, alias, or function, use a scope modifier. The valid values of a modifier are Global, Local, Private, and @@ -126,362 +116,411 @@ Script. The syntax for a scope modifier in a variable is: +``` $[]: = +``` The syntax for a scope modifier in a function is: +``` function []: {} +``` The default scope for scripts is the script scope. The default scope for functions and aliases is the local scope, even if they are defined in a script. -The following command, which does not use a scope modifier, creates a -variable in the current or local scope: +The following command, which does not use a scope modifier, creates a variable +in the current or local scope: +```powershell $a = "one" +``` To create the same variable in the global scope, use the Global scope modifier: +```powershell $global:a = "one" +``` -To create the same variable in the script scope, use the script -scope modifier: +To create the same variable in the script scope, use the script scope +modifier: +```powershell $script:a = "one" +``` You can also use a scope modifier in functions. The following function definition creates a function in the global scope: -function global:Hello -{ -write-host "Hello, World" +```powershell +function global:Hello { + write-host "Hello, World" } +``` -You can also use scope modifiers to refer to a variable in a different -scope. The following command refers to the $test variable, first in the -local scope and then in the global scope: +You can also use scope modifiers to refer to a variable in a different scope. +The following command refers to the $test variable, first in the local scope +and then in the global scope: +```powershell $test - $global:test +``` -The Using scope modifier +### The Using scope modifier -Using is a special scope modifier that identifies a local -variable in a remote command. By default, variables in remote -commands are assumed to be defined in the remote session. +Using is a special scope modifier that identifies a local variable in a remote +command. By default, variables in remote commands are assumed to be defined in +the remote session. -The Using scope modifier is introduced in Windows PowerShell 3.0. +The Using scope modifier is introduced in PowerShell 3.0. -For more information, see about_Remote_Variables. +For more information, see [about_Remote_Variables](about_Remote_Variables.md). -The AllScope Option +### The AllScope Option Variables and aliases have an Option property that can take a value of AllScope. Items that have the AllScope property become part of any child scopes that you create, although they are not retroactively inherited by parent scopes. -An item that has the AllScope property is visible in the child scope, and -it is part of that scope. Changes to the item in any scope affect all the -scopes in which the variable is defined. +An item that has the AllScope property is visible in the child scope, and it +is part of that scope. Changes to the item in any scope affect all the scopes +in which the variable is defined. -Managing Scope +### Managing Scope -Several cmdlets have a Scope parameter that lets you get or set (create -and change) items in a particular scope. Use the following command to find -all the cmdlets in your session that have a Scope parameter: +Several cmdlets have a Scope parameter that lets you get or set (create and +change) items in a particular scope. Use the following command to find all the +cmdlets in your session that have a Scope parameter: +```powershell get-help * -parameter scope +``` -To find the variables that are visible in a particular scope, use the -Scope parameter of Get-Variable. The visible parameters include global -parameters, parameters in the parent scope, and parameters in the current -scope. +To find the variables that are visible in a particular scope, use the Scope +parameter of Get-Variable. The visible parameters include global parameters, +parameters in the parent scope, and parameters in the current scope. -For example, the following command gets the variables that are visible in -the local scope: +For example, the following command gets the variables that are visible in the +local scope: +```powershell get-variable -scope local +``` -To create a variable in a particular scope, use a scope modifier or the -Scope parameter of Set-Variable. The following command creates a variable -in the global scope: +To create a variable in a particular scope, use a scope modifier or the Scope +parameter of Set-Variable. The following command creates a variable in the +global scope: +```powershell new-variable -scope global -name a -value "One" +``` -You can also use the Scope parameter of the New-Alias, Set-Alias, or -Get-Alias cmdlets to specify the scope. The following command creates an -alias in the global scope: +You can also use the Scope parameter of the New-Alias, Set-Alias, or Get-Alias +cmdlets to specify the scope. The following command creates an alias in the +global scope: +```powershell new-alias -scope global -name np -value Notepad.exe +``` -To get the functions in a particular scope, use the Get-Item cmdlet when -you are in the scope. The Get-Item cmdlet does not have a scope parameter. +To get the functions in a particular scope, use the Get-Item cmdlet when you +are in the scope. The Get-Item cmdlet does not have a scope parameter. -Using Dot Source Notation with Scope +### Using Dot Source Notation with Scope Scripts and functions follow all the rules of scope. You create them in a particular scope, and they affect only that scope unless you use a cmdlet parameter or a scope modifier to change that scope. -But, you can add a script or function to the current scope by using dot -source notation. Then, when a script runs in the current scope, any -functions, aliases, and variables that the script creates are available -in the current scope. +But, you can add a script or function to the current scope by using dot source +notation. Then, when a script runs in the current scope, any functions, +aliases, and variables that the script creates are available in the current +scope. -To add a function to the current scope, type a dot (.) and a space before -the path and name of the function in the function call. +To add a function to the current scope, type a dot (.) and a space before the +path and name of the function in the function call. -For example, to run the Sample.ps1 script from the C:\Scripts directory in -the script scope (the default for scripts), use the following command: +For example, to run the Sample.ps1 script from the C:\Scripts directory in the +script scope (the default for scripts), use the following command: +```powershell c:\scripts\sample.ps1 +``` To run the Sample.ps1 script in the local scope, use the following command: +```powershell . c:\scripts.sample.ps1 +``` When you use the call operator (&) to run a function or script, it is not added to the current scope. The following example uses the call operator: +```powershell & c:\scripts.sample.ps1 +``` + +Any aliases, functions, or variables that the Sample.ps1 script creates are +not available in the current scope. + +### Restricting Without Scope + +A few PowerShell concepts are similar to scope or interact with scope. These +concepts may be confused with scope or the behavior of scope. + +Sessions, modules, and nested prompts are self-contained environments, but +they are not child scopes of the global scope in the session. + +- Sessions: A session is an environment in which PowerShell runs. When you + create a session on a remote computer, PowerShell establishes a + persistent connection to the remote computer. The persistent connection lets + you use the session for multiple related commands. + + Because a session is a contained environment, it has its own scope, but a + session is not a child scope of the session in which is was created. The + session starts with its own global scope. This scope is independent of the + global scope of the session. You can create child scopes in the session. For + example, you can run a script to create a child scope in a session. + +- Modules: You can use a PowerShell module to share and deliver PowerShell + tools. A module is a unit that can contain cmdlets, scripts, functions, + variables, aliases, and other useful items. Unless explicitly defined, the + items in a module are not accessible outside the module. Therefore, you can + add the module to your session and use the public items without worrying that + the other items might override the cmdlets, scripts, functions, and other + items in your session. -Any aliases, functions, or variables that the Sample.ps1 script creates -are not available in the current scope. - -Restricting Without Scope - -A few Windows PowerShell concepts are similar to scope or interact with -scope. These concepts may be confused with scope or the behavior of scope. - -Sessions, modules, and nested prompts are self-contained environments, -but they are not child scopes of the global scope in the session. - -Sessions: -A session is an environment in which Windows PowerShell runs. -When you create a session on a remote computer, Windows -PowerShell establishes a persistent connection to the remote -computer. The persistent connection lets you use the session for -multiple related commands. - -Because a session is a contained environment, it has its own -scope, but a session is not a child scope of the session in -which is was created. The session starts with its own global -scope. This scope is independent of the global scope of the session. -You can create child scopes in the session. For example, you can run -a script to create a child scope in a session. - -Modules: -You can use a Windows PowerShell module to share and deliver -Windows PowerShell tools. A module is a unit that can contain -cmdlets, scripts, functions, variables, aliases, and other useful -items. Unless explicitly defined, the items in a module are not -accessible outside the module. Therefore, you can add the module to -your session and use the public items without worrying that the -other items might override the cmdlets, scripts, functions, and other -items in your session. - -The privacy of a module behaves like a scope, but adding a module -to a session does not change the scope. And, the module does not have -its own scope, although the scripts in the module, like all Windows -PowerShell scripts, do have their own scope. - -Nested Prompts: -Similarly, nested prompts do not have their own scope. When you enter -a nested prompt, the nested prompt is a subset of the environment. -But, you remain within the local scope. - -Scripts do have their own scope. If you are debugging a script, and -you reach a breakpoint in the script, you enter the script scope. - -Private Option: -Aliases and variables have an Option property that can take a value -of Private. Items that have the Private option can be viewed and -changed in the scope in which they are created, but they cannot be -viewed or changed outside that scope. - -For example, if you create a variable that has a private option in the -global scope and then run a script, Get-Variable commands in the script -do not display the private variable. This occurs even if you use -the global scope modifier. - -You can use the Option parameter of the New-Variable, Set-Variable, -New-Alias, and Set-Alias cmdlets to set the value of the Option -property to Private. - -Visibility: -The Visibility property of a variable or alias determines whether you -can see the item outside the container, such as a module, in which it -was created. Visibility is designed for containers in the same way that -the Private value of the Option property is designed for scopes. - -The Visibility property takes the Public and Private values. Items -that have private visibility can be viewed and changed only in the -container in which they were created. If the container is added or -imported, the items that have private visibility cannot be viewed or -changed. - -Because Visibility is designed for containers, it works differently -in a scope. If you create an item that has private visibility in the -global scope, you cannot view or change the item in any scope. If you -try to view or change the value of a variable that has private -visibility, Windows PowerShell returns an error message. - -You can use the New-Variable and Set-Variable cmdlets to create a -variable that has private visibility. - -# EXAMPLES - - -Example 1: Change a Variable Value Only in a Script - -The following command changes the value of the $ConfirmPreference -variable in a script. The change does not affect the global scope. - -First, to display the value of the $ConfirmPreference variable in -the local scope, use the following command: + The privacy of a module behaves like a scope, but adding a module to a session + does not change the scope. And, the module does not have its own scope, + although the scripts in the module, like all PowerShell scripts, do + have their own scope. +- Nested Prompts: Similarly, nested prompts do not have their own scope. When + you enter a nested prompt, the nested prompt is a subset of the environment. + But, you remain within the local scope. + + Scripts do have their own scope. If you are debugging a script, and you reach + a breakpoint in the script, you enter the script scope. + +- Private Option: Aliases and variables have an Option property that can take a + value of Private. Items that have the Private option can be viewed and changed + in the scope in which they are created, but they cannot be viewed or changed + outside that scope. + + For example, if you create a variable that has a private option in the global + scope and then run a script, Get-Variable commands in the script do not + display the private variable. This occurs even if you use the global scope + modifier. + + You can use the Option parameter of the New-Variable, Set-Variable, New-Alias, + and Set-Alias cmdlets to set the value of the Option property to Private. + +- Visibility: The Visibility property of a variable or alias determines whether + you can see the item outside the container, such as a module, in which it was + created. Visibility is designed for containers in the same way that the + Private value of the Option property is designed for scopes. + + The Visibility property takes the Public and Private values. Items that have + private visibility can be viewed and changed only in the container in which + they were created. If the container is added or imported, the items that have + private visibility cannot be viewed or changed. + + Because Visibility is designed for containers, it works differently in a + scope. If you create an item that has private visibility in the global scope, + you cannot view or change the item in any scope. If you try to view or change + the value of a variable that has private visibility, PowerShell returns an + error message. + + You can use the New-Variable and Set-Variable cmdlets to create a variable + that has private visibility. + +## EXAMPLES + +### Example 1: Change a Variable Value Only in a Script + +The following command changes the value of the \$ConfirmPreference variable in +a script. The change does not affect the global scope. + +First, to display the value of the \$ConfirmPreference variable in the local +scope, use the following command: + +``` C:\PS> $ConfirmPreference High +``` Create a Scope.ps1 script that contains the following commands: +```powershell $ConfirmPreference = "Low" "The value of `$ConfirmPreference is $ConfirmPreference." +``` -Run the script. The script changes the value of the $ConfirmPreference -variable and then reports its value in the script scope. The output -should resemble the following output: +Run the script. The script changes the value of the \$ConfirmPreference +variable and then reports its value in the script scope. The output should +resemble the following output: +```output The value of $ConfirmPreference is Low. +``` -Next, test the current value of the $ConfirmPreference variable in the -current scope. +Next, test the current value of the \$ConfirmPreference variable in the current +scope. +``` C:\PS> $ConfirmPreference High +``` -This example shows that changes to the value of a variable in the script -scope do not affect the value of that variable in the parent scope. +This example shows that changes to the value of a variable in the script scope +do not affect the value of that variable in the parent scope. -Example 2: View a Variable Value in Different Scopes +### Example 2: View a Variable Value in Different Scopes -You can use scope modifiers to view the value of a variable in the local -scope and in a parent scope. +You can use scope modifiers to view the value of a variable in the local scope +and in a parent scope. First, define a $test variable in the global scope. +```powershell $test = "Global" +``` -Next, create a Sample.ps1 script that defines the $test -variable. In the script, use a scope modifier to refer -to either the global or local versions of the $test variable. +Next, create a Sample.ps1 script that defines the \$test variable. In the +script, use a scope modifier to refer to either the global or local versions +of the \$test variable. -In Sample.ps1 +In Sample.ps1: +```powershell $test = "Local" "The local value of `$test is $test." "The global value of `$test is $global:test." +``` When you run Sample.ps1, the output should resemble the following output: +```output The local value of $test is Local. The global value of $test is Global. +``` -When the script is complete, only the global value of $test is defined -in the session. +When the script is complete, only the global value of \$test is defined in the +session. +``` C:\PS> $test Global +``` -Example 3: Change the Value of a Variable in a Parent Scope +### Example 3: Change the Value of a Variable in a Parent Scope -Unless you protect an item by using the Private option or another -method, you can view and change the value of a variable in a parent -scope. +Unless you protect an item by using the Private option or another method, you +can view and change the value of a variable in a parent scope. -First, define a $test variable in the global scope. +First, define a \$test variable in the global scope. +```powershell $test = "Global" +``` -Next, create a Sample.ps1 script that defines the $test variable. In the -script, use a scope modifier to refer to either the global or local -versions of the $test variable. +Next, create a Sample.ps1 script that defines the \$test variable. In the +script, use a scope modifier to refer to either the global or local versions +of the \$test variable. -In Sample.ps1 +In Sample.ps1: +```powershell $global:test = "Local" "The global value of `$test is $global:test." +``` -When the script is complete, the global value of $test is changed. +When the script is complete, the global value of \$test is changed. +``` C:\PS> $test Local +``` -Example 4: Creating a Private Variable +### Example 4: Creating a Private Variable -A private variable is a variable that has an Option property that has a -value of Private. Private variables are inherited by the child scope, but -they can be viewed or changed only in the scope in which they were -created. +A private variable is a variable that has an Option property that has a value +of Private. Private variables are inherited by the child scope, but they can +be viewed or changed only in the scope in which they were created. -The following command creates a private variable called $ptest in the -local scope. +The following command creates a private variable called \$ptest in the local +scope. +```powershell New-Variable -Name ptest -Value 1 -Option private +``` -You can display and change the value of $ptest in the local scope. +You can display and change the value of \$ptest in the local scope. +``` C:\PS> $ptest -# 1 +1 C:\PS> $ptest = 2 C:\PS> $ptest -# 2 - +2 +``` -Next, create a Sample.ps1 script that contains the following commands. -The command tries to display and change the value of $ptest. +Next, create a Sample.ps1 script that contains the following commands. The +command tries to display and change the value of \$ptest. -In Sample.ps1 +In Sample.ps1: +```powershell "The value of `$Ptest is $Ptest." "The value of `$Ptest is $global:Ptest." +``` -Because the $ptest variable is not visible in the script scope, the -output is empty. +Because the $ptest variable is not visible in the script scope, the output is +empty. +```powershell "The value of $Ptest is ." "The value of $Ptest is ." +``` -Example 5: Using a Local Variable in a Remote Command +### Example 5: Using a Local Variable in a Remote Command -To indicate that a variable in a remote command was created in the -local session, use the Using scope modifier. By default, Windows -PowerShell assumes that the variables in remote commands were created -in the remote session. +To indicate that a variable in a remote command was created in the local +session, use the Using scope modifier. By default, PowerShell assumes +that the variables in remote commands were created in the remote session. The syntax is: + +``` $Using: +``` -For example, the following commands create a $Cred variable in the -local session and then use the $Cred variable in a remote command: +For example, the following commands create a $Cred variable in the local +session and then use the $Cred variable in a remote command: +```powershell $Cred = Get-Credential Invoke-Command $s {Remove-Item .\Test*.ps1 -Credential $Using:Cred} +``` -The Using scope was introduced in Windows PowerShell 3.0. - -In Windows PowerShell 2.0, to indicate that a variable was created in -the local session, use the following command format. +The Using scope was introduced in PowerShell 3.0. In PowerShell 2.0, to +indicate that a variable was created in the local session, use the following +command format. +```powershell $Cred = Get-Credential -Invoke-Command $s {param($c) Remove-Item .\Test*.ps1 -Credential $c} -ArgumentList $Cred +Invoke-Command $s { + param($c) + Remove-Item .\Test*.ps1 -Credential $c +} -ArgumentList $Cred +``` -# SEE ALSO +## SEE ALSO [about_Variables](about_Variables.md) @@ -490,4 +529,3 @@ Invoke-Command $s {param($c) Remove-Item .\Test*.ps1 -Credential $c} -ArgumentLi [about_Functions](about_Functions.md) [about_Script_Blocks](about_Script_Blocks.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md b/reference/6/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md index f56bd3f816ae..06219eb3961e 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Script_Internationalization.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,190 +7,244 @@ title: about_Script_Internationalization --- # About Script Internationalization -## about_Script_Internationalization +## Short Description -# SHORT DESCRIPTION +Describes the script internationalization features that make it easy for +scripts to display messages and instructions to users in their user interface +(UI) language. -Describes the script internationalization features of Windows PowerShell 2.0 -that make it easy for scripts to display messages and instructions to users -in their user interface (UI) language. - -# LONG DESCRIPTION +## Long Description The Windows PowerShell script internationalization features allow you to -better serve users throughout the world by displaying Help and user -messages for scripts and functions in the user's UI language. - -The script internationalization features query the UI culture of the -operating system during execution, import the appropriate -translated text strings, and display them to the user. The Data section -lets you store text strings separate from code so they are easily -identified and extracted. A new cmdlet, ConvertFrom-StringData, -converts text strings into dictionary-like hash tables to facilitate -translation. +better serve users throughout the world by displaying Help and user messages +for scripts and functions in the user's UI language. -The Windows PowerShell 2.0 features used in script internationalization -are not supported by Windows PowerShell 1.0. Scripts that include these -features will not run in Windows PowerShell 1.0 without modification. +The script internationalization features query the UI culture of the operating +system during execution, import the appropriate translated text strings, and +display them to the user. The Data section lets you store text strings +separate from code so they are easily identified and extracted. A new cmdlet, +`ConvertFrom-StringData`, converts text strings into dictionary-like hash +tables to facilitate translation. -To support international Help text, Windows PowerShell 2.0 includes the -following features: +To support international Help text, Windows PowerShell includes the following +features: --- A Data section that separates text strings from code instructions. For -more information about the Data section, see about_Data_Sections. +* A Data section that separates text strings from code instructions. For more + information about the Data section, see + [aout_Data_Sections](about_Data_Sections.md). --- New automatic variables, $PSCulture and $PSUICulture. $PSCulture stores -the name of the UI language used on the system for elements such as -the date, time, and currency. The $PSUICulture variable stores the -name of the UI language used on the system for user interface elements -such as menus and text strings. +* New automatic variables, \$PSCulture and \$PSUICulture. \$PSCulture stores the + name of the UI language used on the system for elements such as the date, + time, and currency. The $PSUICulture variable stores the name of the UI + language used on the system for user interface elements such as menus and text + strings. --- A cmdlet, ConvertFrom-StringData, that converts text strings into -dictionary-like hash tables to facilitate translation. For more -information, see ConvertFrom-StringData. +* A cmdlet, `ConvertFrom-StringData`, that converts text strings into + dictionary-like hash tables to facilitate translation. For more information, + see [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md). --- A new file type, .psd1, that stores translated text strings. The .psd1 -files are stored in language-specific subdirectories of the script -directory. +* A new file type, .psd1, that stores translated text strings. The .psd1 files + are stored in language-specific subdirectories of the script directory. --- A cmdlet, Import-LocalizedData, that imports translated text strings -for a specified language into a script at runtime. This cmdlet recognizes -and imports strings in any Windows-supported language. For more -information see Import-LocalizedData. +* A cmdlet, `Import-LocalizedData`, that imports translated text strings for a + specified language into a script at runtime. This cmdlet recognizes and + imports strings in any Windows-supported language. For more information see + [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md). -THE DATA SECTION: Storing Default Strings +### The Data Section: Storing Default Strings -Use a Data section in the script to store the text strings in the default language. -Arrange the strings in key/value pairs in a here-string. Each key/value pair must -be on a separate line. If you include comments, the comments must be on separate -lines. +Use a Data section in the script to store the text strings in the default +language. Arrange the strings in key/value pairs in a here-string. Each +key/value pair must be on a separate line. If you include comments, the +comments must be on separate lines. -The ConvertFrom-StringData cmdlet converts the key/value pairs in the here-string -into a dictionary-like hash table that is stored in the value of the Data section -variable. +The `ConvertFrom-StringData` cmdlet converts the key/value pairs in the +here-string into a dictionary-like hash table that is stored in the value of +the Data section variable. In the following example, the Data section of the World.ps1 script includes the English-United States (en-US) set of prompt messages for a script. The -ConvertFrom-StringData cmdlet converts the strings into a hash table and stores -them in the $msgtable variable. +`ConvertFrom-StringData` cmdlet converts the strings into a hash table and +stores them in the $msgtable variable. +```powershell $msgTable = Data { -culture="en-US" -ConvertFrom-StringData @' -helloWorld = Hello, World. -errorMsg1 = You cannot leave the user name field blank. -promptMsg = Please enter your user name. -# '@ - + #culture="en-US" + ConvertFrom-StringData @' + helloWorld = Hello, World. + errorMsg1 = You cannot leave the user name field blank. + promptMsg = Please enter your user name. +'@ } +``` -For more information about here-strings, see about_Quoting_Rules. +For more information about here-strings, see +[about_Quoting_Rules](about_Quoting_Rules.md). -PSD1 FILES: Storing Translated Strings +### PSD1 Files: Storing Translated Strings -Save the script messages for each UI language in separate text files with -the same name as the script and the .psd1 file name extension. Store the files -in subdirectories of the script directory with names of cultures in the following +Save the script messages for each UI language in separate text files with the +same name as the script and the .psd1 file name extension. Store the files in +subdirectories of the script directory with names of cultures in the following format: -- +\-\ Examples: de-DE, ar-SA, and zh-Hans -For example, if the World.ps1 script is stored in the C:\Scripts directory, you -would create a file directory structure that resembles the following: +For example, if the World.ps1 script is stored in the C:\Scripts directory, +you would create a file directory structure that resembles the following: +``` C:\Scripts C:\Scripts\World.ps1 C:\Scripts\de-DE\World.psd1 C:\Scripts\ar-SA\World.psd1 C:\Scripts\zh-CN\World.psd1 -# ... +... +``` +The World.psd1 file in the de-DE subdirectory of the script directory might +include the following statement: -The World.psd1 file in the de-DE subdirectory of the script directory -might include the following statement: - -ConvertFrom-StringData @' +```powershell +ConvertFrom-StringData -StringData @' helloWorld = Hello, World (in German). errorMsg1 = You cannot leave the user name field blank (in German). promptMsg = Please enter your user name (in German). -# '@ +'@ +``` +Similarly, the World.psd1 file in the ar-SA subdirectory of the script +directory might includes the following statement: -Similarly, the World.psd1 file in the ar-SA subdirectory of the script directory -might includes the following statement: - -ConvertFrom-StringData @' +```powershell +ConvertFrom-StringData -StringData @' helloWorld = Hello, World (in Arabic). errorMsg1 = You cannot leave the user name field blank (in Arabic). promptMsg = Please enter your user name (in Arabic). -# '@ +'@ +``` +### Import-LocalizedData: Dynamic Retrieval of Translated Strings -IMPORT-LOCALIZEDDATA: Dynamic Retrieval of Translated Strings +To retrieve the strings in the UI language of the current user, use the +`Import-LocalizedData` cmdlet. -To retrieve the strings in the UI language of the current user, use -the Import-LocalizedData cmdlet. +`Import-LocalizedData` finds the value of the \$PSUICulture automatic variable +and imports the content of the \.psd1 files in the subdirectory +that matches the \$PSUICulture value. Then, it saves the imported content in +the variable specified by the value of the **BindingVariable** parameter. -Import-LocalizedData finds the value of the $PSUICulture automatic -variable and imports the content of the .psd1 files in -the subdirectory that matches the $PSUICulture value. Then, it saves -the imported content in the variable specified by the value of the -BindingVariable parameter. +```powershell +Import-LocalizedData -BindingVariable msgTable +``` -import-localizeddata -bindingVariable msgTable +For example, if the `Import-LocalizedData` command appears in the +C:\\Scripts\\World.ps1 script and the value of $PSUICulture is "ar-SA", +`Import-LocalizedData` finds the following file: -For example, if the Import-LocalizedData command appears in the -C:\Scripts\World.ps1 script and the value of $PSUICulture is -"ar-SA", Import-LocalizedData finds the following file: +C:\\Scripts\\ar-SA\\World.psd1 -C:\Scripts\ar-SA\World.psd1 - -Then, it imports the Arabic text strings from the file into -the $msgTable variable, replacing any default strings that might -be defined in the Data section of the World.ps1 script. +Then, it imports the Arabic text strings from the file into the $msgTable +variable, replacing any default strings that might be defined in the Data +section of the World.ps1 script. -As a result, when the script uses the $msgTable variable -to display user messages, the messages are displayed in -Arabic. +As a result, when the script uses the $msgTable variable to display user +messages, the messages are displayed in Arabic. -For example, the following script displays the "Please enter your user -name" message in Arabic: +For example, the following script displays the "Please enter your user name" +message in Arabic: +```powershell if (!($username)) { $msgTable.promptMsg } +``` -If Import-LocalizedData cannot find a .psd1 file that matches the -value of $PSUIculture, the value of $msgTable is not replaced, -and the call to $msgTable.promptMsg displays the fallback en-US -strings. +If `Import-LocalizedData` cannot find a .psd1 file that matches the value of +\$PSUIculture, the value of \$msgTable is not replaced, and the call to +\$msgTable.promptMsg displays the fallback en-US strings. -ExAMPLE +## Examples -This example shows how the script internationalization features -are used in a script to display a day of the week to users -in the language that is set on the computer. +This example shows how the script internationalization features are used in a +script to display a day of the week to users in the language that is set on +the computer. -The following is a complete listing of the Sample1.ps1 script -file. +The following is a complete listing of the Sample1.ps1 script file. -The script begins with a Data section named Day ($Day) that -contains a ConvertFrom-StringData command. The expression -submitted to ConvertFrom-StringData is a here-string that -contains the day names in the default UI culture, en-US, in -key/value pairs. The ConvertFrom-StringData cmdlet converts -the key/value pairs in the here-string into a hash table and +The script begins with a Data section named Day ($Day) that contains a +`ConvertFrom-StringData` command. The expression submitted to +`ConvertFrom-StringData` is a here-string that contains the day names in the +default UI culture, en-US, in key/value pairs. The `ConvertFrom-StringData` +cmdlet converts the key/value pairs in the here-string into a hash table and then saves it in the value of the $Day variable. -The Import-LocalizedData command imports the contents of the -.psd1 file in the directory that matches the value of the -$PSUICulture automatic variable and then saves it in the $Day -variable, replacing the values of $Day that are defined in the -Data section. +The `Import-LocalizedData` command imports the contents of the .psd1 file in +the directory that matches the value of the $PSUICulture automatic variable +and then saves it in the $Day variable, replacing the values of $Day that are +defined in the Data section. + +The remaining commands load the strings into an array and display them. + +```powershell +$Day = Data { +#culture="en-US" +ConvertFrom-StringData -StringData @' + messageDate = Today is + d0 = Sunday + d1 = Monday + d2 = Tuesday + d3 = Wednesday + d4 = Thursday + d5 = Friday + d6 = Saturday +'@ +} + +Import-LocalizedData -BindingVariable Day -The remaining commands load the strings into an array and display -them. +#Build an array of weekdays. +$a = $Day.d0, $Day.d1, $Day.d2, $Day.d3, $Day.d4, $Day.d5, $Day.d6 -$Day = DATA { +# Get the day of the week as a number (Monday = 1). +# Index into $a to get the name of the day. +# Use string formatting to build a sentence. +"{0} {1}" -f $Day.messageDate, $a[(Get-Date -uformat %u)] | Out-Host +``` + +The .psd1 files that support the script are saved in subdirectories of +the script directory with names that match the $PSUICulture values. + +The following is a complete listing of .\de-DE\sample1.psd1: + +```powershell +# culture="de-DE" +ConvertFrom-StringData @' + messageDate = Today is + d0 = Sunday (in German) + d1 = Monday (in German) + d2 = Tuesday (in German) + d3 = Wednesday (in German) + d4 = Thursday (in German) + d5 = Friday (in German) + d6 = Saturday (in German) +'@ +``` + +As a result, when you run Sample.ps1 on a system on which the value of +\$PSUICulture is de-DE, the output of the script is: + +```output +Today is Friday (in German) +``` + +## See also + +* [about_Data_Sections](about_Data_Sections.md) +* [about_Automatic_Variables](about_Automatic_Variables.md) +* [about_Hash_Tables](about_Hash_Tables.md) +* [about_Quoting_Rules](about_Quoting_Rules.md) +* [ConvertFrom-StringData](../../Microsoft.PowerShell.Utility/ConvertFrom-StringData.md) +* [Import-LocalizedData](../../Microsoft.PowerShell.Utility/Import-LocalizedData.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md b/reference/6/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md index fe470e6bc5b4..b3d7fc0d56e2 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Session_Configuration_Files.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,284 +7,296 @@ title: about_Session_Configuration_Files --- # About Session Configuration Files -## about_Session_Configuration_Files +## SHORT DESCRIPTION +Describes session configuration files, which are used in a session +configuration (also known as an "endpoint") to define the environment of +sessions that use the session configuration. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes session configuration files, which are used in a -session configuration (also known as an "endpoint") to define the -environment of sessions that use the session configuration. - -# LONG DESCRIPTION - -A "session configuration file" is a text file with a .pssc file -name extension that contains a hash table of session configuration -properties and values. You can use a session configuration file to -set the properties of a session configuration. Doing so defines -the environment of any Windows PowerShell sessions that use that -session configuration. +A "session configuration file" is a text file with a .pssc file name extension +that contains a hash table of session configuration properties and values. You +can use a session configuration file to set the properties of a session +configuration. Doing so defines the environment of any Windows PowerShell +sessions that use that session configuration. Session configuration files make it easy to create custom session configurations without using complex C# assemblies or scripts. -A "session configuration" or "endpoint" is a collection of local -computer settings that determine such things as which users can -create sessions on the computer; which commands users can run in -those sessions; and whether the session should run as a privileged -virtual account. For more information about session configurations, -see about_Session_Configurations -(http://go.microsoft.com/fwlink/?LinkID=145152). - -Session configurations were introduced in Windows PowerShell 2.0, -and session configuration files were introduced in Windows -PowerShell 3.0. You must use Windows PowerShell 3.0 to include a -session configuration file in a session configuration. However, -users of Windows PowerShell 2.0 (and later) are affected by the -settings in the session configuration. - -Creating Custom Sessions -You can customize many features of a Windows PowerShell session -by specifying session properties in a session configuration. You -can customize a session by writing a C# program that defines a -custom runspace, or you can use a session configuration file to -define the properties of sessions created by using the session -configuration. As a general rule, it is easier to use the session +A "session configuration" or "endpoint" is a collection of local computer +settings that determine such things as which users can create sessions on the +computer; which commands users can run in those sessions; and whether the +session should run as a privileged virtual account. For more information about +session configurations, see [about_Session_Configurations](about_Session_Configurations.md). + +Session configurations were introduced in Windows PowerShell 2.0, and session +configuration files were introduced in Windows PowerShell 3.0. You must use +Windows PowerShell 3.0 to include a session configuration file in a session +configuration. However, users of Windows PowerShell 2.0 (and later) are +affected by the settings in the session configuration. + +## Creating Custom Sessions + +You can customize many features of a Windows PowerShell session by specifying +session properties in a session configuration. You can customize a session by +writing a C# program that defines a custom runspace, or you can use a session +configuration file to define the properties of sessions created by using the +session configuration. As a general rule, it is easier to use the session configuration file than to write a C# program. You can use a session configuration file to create items such as -fully-functioning sessions for highly trusted users; locked-down -sessions that allow minimal access; sessions designed for -particular and that contain only the modules required for those -tasks; and sessions where unprivileged users can only run -specific commands as a privileged account. - -In addition to that, you can manage whether users of the -session can use Windows PowerShell language elements such as -script blocks, or whether they can only run commands. You can -manage the version of Windows PowerShell users can run in the -session; manage which modules are imported into the session; and -manage which cmdlets, functions, and aliases session users can -run. When using the RoleDefinitions field, you can give users -different capabilities in the session based on group membership. - -For more information about RoleDefinitions and how to define this -Value, see the help topic for the New-PSRoleCapabilityFile -Cmdlet. - -Creating a Session Configuration File -The easiest way to create a session configuration file is by -using the New-PSSessionConfigurationFile cmdlet. This cmdlet -generates a file that uses the correct syntax and format, and -that automatically verifies many of the configuration file -property values. - -For detailed descriptions of the properties that you can set in -a session configuration file, see the help topic for the -New-PSSessionConfigurationFile cmdlet. - -The following command creates a session configuration file that -uses the default values. The resulting configuration file uses only -the default values because no parameters other than the Path -parameter (which specifies the file path) are included: - -PS C:> New-PSSessionConfigurationFile -Path .\Defaults.pssc - -To view the new configuration file in your default text editor, -use the following command: - -PS C:> Invoke-Item -Path .\Defaults.pssc - -To create a session configuration for sessions in which -user can run commands, but not use other elements of the Windows -PowerShell language, type: - -PS C:> New-PSSessionConfigurationFile -LanguageMode NoLanguage +fully-functioning sessions for highly trusted users; locked-down sessions that +allow minimal access; sessions designed for particular and that contain only +the modules required for those tasks; and sessions where unprivileged users +can only run specific commands as a privileged account. + +In addition to that, you can manage whether users of the session can use +Windows PowerShell language elements such as script blocks, or whether they +can only run commands. You can manage the version of Windows PowerShell users +can run in the session; manage which modules are imported into the session; +and manage which cmdlets, functions, and aliases session users can run. When +using the RoleDefinitions field, you can give users different capabilities in +the session based on group membership. + +For more information about RoleDefinitions and how to define this Value, see +the help topic for the New-PSRoleCapabilityFile Cmdlet. + +## Creating a Session Configuration File + +The easiest way to create a session configuration file is by using the +New-PSSessionConfigurationFile cmdlet. This cmdlet generates a file that uses +the correct syntax and format, and that automatically verifies many of the +configuration file property values. + +For detailed descriptions of the properties that you can set in a session +configuration file, see the help topic for the New-PSSessionConfigurationFile +cmdlet. + +The following command creates a session configuration file that uses the +default values. The resulting configuration file uses only the default values +because no parameters other than the Path parameter (which specifies the file +path) are included: + +```powershell +New-PSSessionConfigurationFile -Path .\Defaults.pssc +``` + +To view the new configuration file in your default text editor, use the +following command: + +```powershell +Invoke-Item -Path .\Defaults.pssc +``` + +To create a session configuration for sessions in which user can run commands, +but not use other elements of the Windows PowerShell language, type: + +```powershell +New-PSSessionConfigurationFile -LanguageMode NoLanguage -Path .\NoLanguage.pssc +``` -In the preceding command, setting the LanguageMode parameter to -NoLanguage prevents users from doing such things as writing or -running scripts, or using variables. +In the preceding command, setting the LanguageMode parameter to NoLanguage +prevents users from doing such things as writing or running scripts, or using +variables. -To create a session configuration for sessions in which users can -use only Get cmdlets, type: +To create a session configuration for sessions in which users can use only Get +cmdlets, type: -PS C:> New-PSSessionConfigurationFile -VisibleCmdlets Get-* +```powershell +New-PSSessionConfigurationFile -VisibleCmdlets Get-* -Path .\GetSessions.pssc +``` -In the preceding example, setting the VisibleCmdlets parameter to -Get-* limits users to cmdlets that have names that start with the -string value "Get-". +In the preceding example, setting the VisibleCmdlets parameter to Get-* limits +users to cmdlets that have names that start with the string value "Get-". -To create a session configuration for sessions that run under a -privileged virtual account instead of the user's credentials, type: +To create a session configuration for sessions that run under a privileged +virtual account instead of the user's credentials, type: -PS C:> New-PSSessionConfigurationFile -RunAsVirtualAccount +```powershell +New-PSSessionConfigurationFile -RunAsVirtualAccount -Path .\VirtualAccount.pssc +``` -To create a session configuration for sessions in which the -commands visible to the user are specified in a role capabilities -file, type: +To create a session configuration for sessions in which the commands visible +to the user are specified in a role capabilities file, type: -PS C:> New-PSSessionConfigurationFile -RoleDefinitions +```powershell +New-PSSessionConfigurationFile -RoleDefinitions @{ 'CONTOSO\User' = @{ RoleCapabilities = 'Maintenance' }} -Path .\Maintenance.pssc +``` -Using a Session Configuration File -You can include a session configuration file when you create a -session configuration or add you can add a file to the session -configuration at a later time. +### Using a Session Configuration File -To include a session configuration file when creating a session -configuration, use the Path parameter of the -Register-PSSessionConfiguration cmdlet. +You can include a session configuration file when you create a session +configuration or add you can add a file to the session configuration at a +later time. -For example, the following command uses the NoLanguage.pssc file -when it creates a NoLanguage session configuration. +To include a session configuration file when creating a session configuration, +use the Path parameter of the Register-PSSessionConfiguration cmdlet. -PS C:> Register-PSSessionConfiguration -Name NoLanguage +For example, the following command uses the NoLanguage.pssc file when it +creates a NoLanguage session configuration. + +```powershell +Register-PSSessionConfiguration -Name NoLanguage -Path .\NoLanguage.pssc +``` -When a new NoLanguage session starts, users will only have access -to Windows PowerShell commands. +When a new NoLanguage session starts, users will only have access to Windows +PowerShell commands. -To add a session configuration file to an existing session -configuration, use the Set-PSSessionConfiguration cmdlet and the -Path parameter. This affects any new sessions created with the -specified session configuration. Note that the -Set-PSSessionConfiguration cmdlet changes the session itself and -does not modify the session configuration file. +To add a session configuration file to an existing session configuration, use +the Set-PSSessionConfiguration cmdlet and the Path parameter. This affects any +new sessions created with the specified session configuration. Note that the +Set-PSSessionConfiguration cmdlet changes the session itself and does not +modify the session configuration file. -For example, the following command adds the NoLanguage.pssc file -to the LockedDown session configuration. +For example, the following command adds the NoLanguage.pssc file to the +LockedDown session configuration. -PS C:> Set-PSSessionConfiguration -Name LockedDown +```powershell +Set-PSSessionConfiguration -Name LockedDown -Path .\NoLanguage.pssc +``` -When users use the LockedDown session configuration to create a -session, they will be able to run cmdlets but they will not be -able to create or use variables, assign values, or use other -Windows PowerShell language elements. +When users use the LockedDown session configuration to create a session, they +will be able to run cmdlets but they will not be able to create or use +variables, assign values, or use other Windows PowerShell language elements. -The following command uses the New-PSSession cmdlet to create a -session on the computer Srv01 that uses the LockedDown session -configuration, saving an object reference to the session in the $s -variable. The ACL (access control list) of the session -configuration determines who can use it to create a session. +The following command uses the New-PSSession cmdlet to create a session on the +computer Srv01 that uses the LockedDown session configuration, saving an +object reference to the session in the $s variable. The ACL (access control +list) of the session configuration determines who can use it to create a +session. -PS C:> $s = New-PSSession -ComputerName Srv01 +```powershell +$s = New-PSSession -ComputerName Srv01 -ConfigurationName LockedDown - -Because the NoLanguage constraints were added to the LockedDown -session configuration, users in LockedDown sessions will only be -able to run Windows PowerShell commands and cmdlets. For example, -the following two commands use the Invoke-Command cmdlet to run -commands in the session referenced in the $s variable. The first -command, which runs the Get-UICulture cmdlet and does not use any -variables, succeeds. The second command, which gets the value of -the $PSUICulture variable, fails. - -PS C:> Invoke-Command -Session $s {Get-UICulture} +``` + +Because the NoLanguage constraints were added to the LockedDown session +configuration, users in LockedDown sessions will only be able to run Windows +PowerShell commands and cmdlets. For example, the following two commands use +the Invoke-Command cmdlet to run commands in the session referenced in the $s +variable. The first command, which runs the Get-UICulture cmdlet and does not +use any variables, succeeds. The second command, which gets the value of the +$PSUICulture variable, fails. + +``` +Invoke-Command -Session $s {Get-UICulture} en-US -PS C:> Invoke-Command -Session $s {$PSUICulture} +Invoke-Command -Session $s {$PSUICulture} The syntax is not supported by this runspace. This might be because it is in no-language mode. + CategoryInfo : ParserError: ($PSUICulture:String) [], ParseException + FullyQualifiedErrorId : ScriptsNotAllowed +``` + +## Editing a Session Configuration File -Editing a Session Configuration File -All settings in a session configuration except for -RunAsVirtualAccount and RunAsVirtualAccountGroups can be modified -by editing the session configuration file used by the session -configuration. To do this, begin by locating the active copy of the -session configuration file. +All settings in a session configuration except for RunAsVirtualAccount and +RunAsVirtualAccountGroups can be modified by editing the session configuration +file used by the session configuration. To do this, begin by locating the +active copy of the session configuration file. -When you use a session configuration file in a session -configuration, Windows PowerShell creates an active copy of the -session configuration file and stores it in the -$pshome\SessionConfig directory on the local computer. +When you use a session configuration file in a session configuration, Windows +PowerShell creates an active copy of the session configuration file and stores +it in the \$pshome\\SessionConfig directory on the local computer. -The location of the active copy of a session configuration file is -stored in the ConfigFilePath property of the session configuration -object. +The location of the active copy of a session configuration file is stored in +the ConfigFilePath property of the session configuration object. -The following command gets the location of the session -configuration file for the NoLanguage session configuration. +The following command gets the location of the session configuration file for +the NoLanguage session configuration. -PS C:> (Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath +```powershell +(Get-PSSessionConfiguration -Name NoLanguage).ConfigFilePath +``` That command returns a file path similar to the following: +``` C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc +``` -You can edit the .pssc file in any text editor. After the file is -saved it will be employed by any new sessions that use the session -configuration. +You can edit the .pssc file in any text editor. After the file is saved it +will be employed by any new sessions that use the session configuration. -If you need to modify the RunAsVirtualAccount or the -RunAsVirtualAccountGroups settings, you must un-register the -session configuration and re-register a session configuration file -that includes the edited values. +If you need to modify the RunAsVirtualAccount or the RunAsVirtualAccountGroups +settings, you must un-register the session configuration and re-register a +session configuration file that includes the edited values. -Testing a Session Configuration File -Use the Test-PSSessionConfigurationFile cmdlet to test manually -edited session configuration files. That's important: if the file -syntax and values are not valid users will not be able to use the -session configuration to create a session. +## Testing a Session Configuration File -For example, the following command tests the active session -configuration file of the NoLanguage session configuration. +Use the Test-PSSessionConfigurationFile cmdlet to test manually edited session +configuration files. That's important: if the file syntax and values are not +valid users will not be able to use the session configuration to create a +session. -PS C:> Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\ +For example, the following command tests the active session configuration file +of the NoLanguage session configuration. + +```powershell +Test-PSSessionConfigurationFile -Path C:\WINDOWS\System32\ WindowsPowerShell\v1.0\SessionConfig\ NoLanguage_0c115179-ff2a-4f66-a5eb-e56e5692ba22.pssc +``` If the syntax and values in the configuration file are valid -Test-PSSessionConfigurationFile returns True. If the syntax and -values are not valid then the cmdlet returns False. - -You can use Test-PSSessionConfigurationFile to test any session -configuration file, including files that the -New-PSSessionConfiguration cmdlet creates. For more information, -see the help topic for the Test-PSSessionConfigurationFile cmdlet. - -Removing a Session Configuration File -You cannot remove a session configuration file from a session -configuration. However, you can replace the file with a new file -that uses the default settings. This effectively cancels the -settings used by the original configuration file. - -To replace a session configuration file, create a new session -configuration file that uses the default settings, then use the -Set-PSSessionConfiguration cmdlet to replace the custom session -configuration file with the new file. - -For example, the following commands create a Default session -configuration file and then replace the active session -configuration file in the NoLanguage session configuration. - -PS C:> New-PSSessionConfigurationFile -Path .\Default.pssc -PS C:> Set-PSSessionConfiguration -Name NoLanguage +Test-PSSessionConfigurationFile returns True. If the syntax and values are not +valid then the cmdlet returns False. + +You can use Test-PSSessionConfigurationFile to test any session configuration +file, including files that the New-PSSessionConfiguration cmdlet creates. For +more information, see the help topic for the Test-PSSessionConfigurationFile +cmdlet. + +## Removing a Session Configuration File + +You cannot remove a session configuration file from a session configuration. +However, you can replace the file with a new file that uses the default +settings. This effectively cancels the settings used by the original +configuration file. + +To replace a session configuration file, create a new session configuration +file that uses the default settings, then use the Set-PSSessionConfiguration +cmdlet to replace the custom session configuration file with the new file. + +For example, the following commands create a Default session configuration +file and then replace the active session configuration file in the NoLanguage +session configuration. + +```powershell +New-PSSessionConfigurationFile -Path .\Default.pssc +Set-PSSessionConfiguration -Name NoLanguage -Path .\Default.pssc +``` -When these commands finish, the NoLanguage session configuration -will actually provide full language support (the default setting) -for all sessions created with that session configuration. +When these commands finish, the NoLanguage session configuration will actually +provide full language support (the default setting) for all sessions created +with that session configuration. -Viewing the Properties of a Session Configuration -The session configuration objects that represent session -configurations using session configuration files have additional -properties that make it easy to discover and analyze the session -configuration. (Note that the type name shown below includes a -formatted view definition.) You can view the properties by running -the Get-PSSessionConfiguration cmdlet and piping the returned data -to the Get-Member cmdlet: +Viewing the Properties of a Session Configuration The session configuration +objects that represent session configurations using session configuration +files have additional properties that make it easy to discover and analyze the +session configuration. (Note that the type name shown below includes a +formatted view definition.) You can view the properties by running the +Get-PSSessionConfiguration cmdlet and piping the returned data to the +Get-Member cmdlet: -PS C:> Get-PSSessionConfiguration NoLanguage | Get-Member +```powershell +Get-PSSessionConfiguration NoLanguage | Get-Member +``` + +```output TypeName: Microsoft.PowerShell.Commands.PSSessionConfigurationCommands #PSSessionConfiguration @@ -331,62 +343,64 @@ SupportsOptions NoteProperty System.String Suppor... xmlns NoteProperty System.String xmlns=... XmlRenderingType NoteProperty System.String XmlRen... Permission ScriptProperty System.Object Permis... +``` -These properties make it easy to search for specific session -configurations. For example, you can use the ExecutionPolicy -property to find a session configuration that supports sessions -with the RemoteSigned execution policy. Note that, because the -ExecutionPolicy property exists only on sessions that use session -configuration files, the command might not return all qualifying +These properties make it easy to search for specific session configurations. +For example, you can use the ExecutionPolicy property to find a session +configuration that supports sessions with the RemoteSigned execution policy. +Note that, because the ExecutionPolicy property exists only on sessions that +use session configuration files, the command might not return all qualifying session configurations. -PS C:> Get-PSSessionConfiguration | +```powershell +Get-PSSessionConfiguration | where {$_.ExecutionPolicy -eq "RemoteSigned"} +``` -The following command gets session configurations in which the -RunAsUser is the Exchange administrator. +The following command gets session configurations in which the RunAsUser is +the Exchange administrator. -PS C:> Get-PSSessionConfiguration | +```powershell + Get-PSSessionConfiguration | where {$_.RunAsUser -eq "Exchange01\Admin01"} +``` -To view information about the role definitions associated with -a configuration use the Get-PSSessionCapability cmdlet. This -cmdlet enables you to determine the commands and environment -available to specific users in specific endpoints. +To view information about the role definitions associated with a configuration +use the Get-PSSessionCapability cmdlet. This cmdlet enables you to determine +the commands and environment available to specific users in specific +endpoints. -# NOTES +## NOTES -Session configurations also support a type of session known as an -"empty" session. An Empty session type enables you to create -custom sessions with selected commands. If you do not add modules, -functions, or scripts to an empty session, the session is limited -to expressions and might not be of any practical use. The -SessionType property tells you whether or not you are working with -an empty session. +Session configurations also support a type of session known as an "empty" +session. An Empty session type enables you to create custom sessions with +selected commands. If you do not add modules, functions, or scripts to an +empty session, the session is limited to expressions and might not be of any +practical use. The SessionType property tells you whether or not you are +working with an empty session. -# SEE ALSO +## SEE ALSO [about_Session_Configurations](about_Session_Configurations.md) -New-PSSession - -Disable-PSSessionConfiguration +[New-PSSession](../New-PSSession.md) -Enable-PSSessionConfiguration +[Disable-PSSessionConfiguration](../Disable-PSSessionConfiguration.md) -Get-PSSessionConfiguration +[Enable-PSSessionConfiguration](../Enable-PSSessionConfiguration.md) -New-PSSessionConfigurationFile +[Get-PSSessionConfiguration](../Get-PSSessionConfiguration.md) -Register-PSSessionConfiguration +[New-PSSessionConfigurationFile](../New-PSSessionConfigurationFile.md) -Set-PSSessionConfiguration +[Register-PSSessionConfiguration](../Register-PSSessionConfiguration.md) -Test-PSSessionConfigurationFile +[Set-PSSessionConfiguration](../Set-PSSessionConfiguration.md) -Unregister-PSSessionConfiguration +[Test-PSSessionConfigurationFile](../Test-PSSessionConfigurationFile.md) -Get-PSSessionCapability +[Unregister-PSSessionConfiguration](../Unregister-PSSessionConfiguration.md) -New-PSRoleCapabilityFile +[Get-PSSessionCapability](../Get-PSSessionCapability.md) +[New-PSRoleCapabilityFile](../New-PSRoleCapabilityFile.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/6/Microsoft.PowerShell.Core/About/about_Signing.md index e5836ac5ec8e..f8c13a29566e 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Signing.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,81 +7,81 @@ title: about_Signing --- # About Signing -## about_Signing +## SHORT DESCRIPTION +Explains how to sign scripts so that they comply with the PowerShell execution +policies. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Explains how to sign scripts so that they comply with the Windows -PowerShell execution policies. +The Restricted execution policy does not permit any scripts to run. The +AllSigned and RemoteSigned execution policies prevent PowerShell from running +scripts that do not have a digital signature. -# LONG DESCRIPTION +This topic explains how to run selected scripts that are not signed, even +while the execution policy is RemoteSigned, and how to sign scripts for your +own use. -The Restricted execution policy does not permit any scripts to run. -The AllSigned and RemoteSigned execution policies prevent Windows -PowerShell from running scripts that do not have a digital signature. +For more information about PowerShell execution policies, see +[about_Execution_Policies](about_Execution_Policies.md). -This topic explains how to run selected scripts that are not signed, -even while the execution policy is RemoteSigned, and how to sign -scripts for your own use. +## TO PERMIT SIGNED SCRIPTS TO RUN -For more information about Windows PowerShell execution policies, -see about_Execution_Policy. - -# TO PERMIT SIGNED SCRIPTS TO RUN - -------------------------------- -When you start Windows PowerShell on a computer for the first time, the -Restricted execution policy (the default) is likely to be in effect. +When you start PowerShell on a computer for the first time, the Restricted +execution policy (the default) is likely to be in effect. The Restricted policy does not permit any scripts to run. To find the effective execution policy on your computer, type: +```powershell Get-ExecutionPolicy +``` -To run unsigned scripts that you write on your local computer and -signed scripts from other users, start Windows PowerShell with the -Run as Administrator option and then use the following command to -change the execution policy on the computer to RemoteSigned: +To run unsigned scripts that you write on your local computer and signed +scripts from other users, start PowerShell with the Run as Administrator +option and then use the following command to change the execution policy on +the computer to RemoteSigned: +```powershell Set-ExecutionPolicy RemoteSigned +``` -For more information, see the help topic for the -Set-ExecutionPolicy cmdlet. +For more information, see the help topic for the Set-ExecutionPolicy cmdlet. -# RUNNING UNSIGNED SCRIPTS (REMOTESIGNED EXECUTION POLICY) +## RUNNING UNSIGNED SCRIPTS (REMOTESIGNED EXECUTION POLICY) --------------------------------------------------------- -If your Windows PowerShell execution policy is RemoteSigned, Windows +If your PowerShell execution policy is RemoteSigned, Windows PowerShell will not run unsigned scripts that are downloaded from the Internet, including unsigned scripts you receive through e-mail and instant messaging programs. -If you try to run a downloaded script, Windows PowerShell displays the +If you try to run a downloaded script, PowerShell displays the following error message: -The file cannot be loaded. The file - is not digitally signed. The script -will not execute on the system. Please see "Get-Help +```output +The file cannot be loaded. The file is not digitally +signed. The script will not execute on the system. Please see "Get-Help about_Signing" for more details. +``` Before you run the script, review the code to be sure that you trust it. Scripts have the same effect as any executable program. -To run an unsigned script, use the Unblock-File cmdlet or use the -Following procedure. +To run an unsigned script, use the Unblock-File cmdlet or use the following +procedure. 1. Save the script file on your computer. 2. Click Start, click My Computer, and locate the saved script file. 3. Right-click the script file, and then click Properties. 4. Click Unblock. -If a script that was downloaded from the Internet is digitally signed, but -you have not yet chosen to trust its publisher, Windows PowerShell displays -the following message: +If a script that was downloaded from the Internet is digitally signed, but you +have not yet chosen to trust its publisher, PowerShell displays the following +message: +```output Do you want to run software from this untrusted publisher? The file is published by CN=. This publisher is not trusted on your system. Only run scripts @@ -89,231 +89,206 @@ from trusted publishers. [V] Never run [D] Do not run [R] Run once [A] Always run [?] Help (default is "D"): +``` -If you trust the publisher, select "Run once" or "Always run." -If you do not trust the publisher, select either "Never run" or -"Do not run." If you select "Never run" or "Always run," Windows -PowerShell will not prompt you again for this publisher. +If you trust the publisher, select "Run once" or "Always run." If you do not +trust the publisher, select either "Never run" or "Do not run." If you select +"Never run" or "Always run," PowerShell will not prompt you again for +this publisher. -# METHODS OF SIGNING SCRIPTS +## METHODS OF SIGNING SCRIPTS --------------------------- -You can sign the scripts that you write and the scripts that you obtain -from other sources. Before you sign any script, examine each command -to verify that it is safe to run. +You can sign the scripts that you write and the +scripts that you obtain from other sources. Before you sign any script, +examine each command to verify that it is safe to run. -For best practices about code signing, see "Code-Signing -Best Practices" at http://go.microsoft.com/fwlink/?LinkId=119096. +For best practices about code signing, see +[Code-Signing Best Practices](http://go.microsoft.com/fwlink/?LinkId=119096). For more information about how to sign a script file, see Set-AuthenticodeSignature. -The New-SelfSignedCertificate cmdlet, introduced in the PKI module -in Windows PowerShell 3.0, creates a self-signed certificate that is -Appropriate for testing. For more information, see the help -topic for the New-SelfSignedCertificate cmdlet. - -To add a digital signature to a script, you must sign it with a code -signing certificate. Two types of certificates are suitable for signing -a script file: +The New-SelfSignedCertificate cmdlet, introduced in the PKI module in +PowerShell 3.0, creates a self-signed certificate that is Appropriate for +testing. For more information, see the help topic for the +New-SelfSignedCertificate cmdlet. --- Certificates that are created by a certification authority: +To add a digital signature to a script, you must sign it with a code signing +certificate. Two types of certificates are suitable for signing a script file: -For a fee, a public certification authority verifies your -identity and gives you a code signing certificate. When -you purchase your certificate from a reputable certification -authority, you are able to share your script with users -on other computers that are running Windows because those other -computers trust the certification authority. +- Certificates that are created by a certification authority: For a fee, a + public certification authority verifies your identity and gives you a code + signing certificate. When you purchase your certificate from a reputable + certification authority, you are able to share your script with users on + other computers that are running Windows because those other computers trust + the certification authority. --- Certificates that you create: +- Certificates that you create: You can create a self-signed certificate for + which your computer is the authority that creates the certificate. This + certificate is free of charge and enables you to write, sign, and run scripts + on your computer. However, a script signed by a self-signed certificate will + not run on other computers. -You can create a self-signed certificate for which -your computer is the authority that creates the certificate. -This certificate is free of charge and enables you to write, -sign, and run scripts on your computer. However, a script -signed by a self-signed certificate will not run on other -computers. +Typically, you would use a self-signed certificate only to sign scripts that +you write for your own use and to sign scripts that you get from other sources +that you have verified to be safe. It is not appropriate for scripts that will +be shared, even within an enterprise. -Typically, you would use a self-signed certificate only to sign -scripts that you write for your own use and to sign scripts that you get -from other sources that you have verified to be safe. It is not -appropriate for scripts that will be shared, even within an enterprise. +If you create a self-signed certificate, be sure to enable strong private key +protection on your certificate. This prevents malicious programs from signing +scripts on your behalf. The instructions are included at the end of this +topic. -If you create a self-signed certificate, be sure to enable strong -private key protection on your certificate. This prevents malicious -programs from signing scripts on your behalf. The instructions are -included at the end of this topic. +## CREATE A SELF-SIGNED CERTIFICATE -# CREATE A SELF-SIGNED CERTIFICATE - --------------------------------- To create a self-signed certificate in use the New-SelfSignedCertificate -cmdlet in the PKI module. This module is introduced in Windows PowerShell -3.0 and is included in Windows 8 and Windows Server 2012. For more -information, see the help topic for the New-SelfSignedCertificate cmdlet. +cmdlet in the PKI module. This module is introduced in PowerShell 3.0 and is +included in Windows 8 and Windows Server 2012. For more information, see the +help topic for the New-SelfSignedCertificate cmdlet. -To create a self-signed certificate in earlier versions of Windows, use -the Certificate Creation tool (MakeCert.exe). This tool is included in -the Microsoft .NET Framework SDK (versions 1.1 and later) and in the -Microsoft Windows SDK. +To create a self-signed certificate in earlier versions of Windows, use the +Certificate Creation tool (MakeCert.exe). This tool is included in the +Microsoft .NET Framework SDK (versions 1.1 and later) and in the Microsoft +Windows SDK. For more information about the syntax and the parameter descriptions of the -MakeCert.exe tool, see "Certificate Creation Tool (MakeCert.exe)" in the -MSDN (Microsoft Developer Network) library at -http://go.microsoft.com/fwlink/?LinkId=119097. +MakeCert.exe tool, see [Certificate Creation Tool (MakeCert.exe)](http://go.microsoft.com/fwlink/?LinkId=119097) +in the MSDN library. To use the MakeCert.exe tool to create a certificate, run the following commands in an SDK Command Prompt window. -Note: The first command creates a local certification authority for -your computer. The second command generates a personal -certificate from the certification authority. +Note: The first command creates a local certification authority for your +computer. The second command generates a personal certificate from the +certification authority. -Note: You can copy or type the commands exactly as they appear. -No substitutions are necessary, although you can change the -certificate name. +Note: You can copy or type the commands exactly as they appear. No +substitutions are necessary, although you can change the certificate name. +```powershell makecert -n "CN=PowerShell Local Certificate Root" -a sha1 ` -eku 1.3.6.1.5.5.7.3.3 -r -sv root.pvk root.cer ` -ss Root -sr localMachine makecert -pe -n "CN=PowerShell User" -ss MY -a sha1 ` -eku 1.3.6.1.5.5.7.3.3 -iv root.pvk -ic root.cer +``` -The MakeCert.exe tool will prompt you for a private key password. The -password ensures that no one can use or access the certificate without -your consent. Create and enter a password that you can remember. You will -use this password later to retrieve the certificate. +The MakeCert.exe tool will prompt you for a private key password. The password +ensures that no one can use or access the certificate without your consent. +Create and enter a password that you can remember. You will use this password +later to retrieve the certificate. -To verify that the certificate was generated correctly, use the -following command to get the certificate in the certificate -store on the computer. (You will not find a certificate file in the -file system directory.) +To verify that the certificate was generated correctly, use the following +command to get the certificate in the certificate store on the computer. (You +will not find a certificate file in the file system directory.) -At the Windows PowerShell prompt, type: +At the PowerShell prompt, type: +```powershell get-childitem cert:\CurrentUser\my -codesigning +``` -This command uses the Windows PowerShell Certificate provider to view -information about the certificate. +This command uses the PowerShell Certificate provider to view information +about the certificate. -If the certificate was created, the output shows the thumbprint -that identifies the certificate in a display that resembles the following: +If the certificate was created, the output shows the thumbprint that +identifies the certificate in a display that resembles the following: +```output Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\My Thumbprint Subject ---------- ------- 4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ] +``` -# SIGN A SCRIPT - -------------- +## SIGN A SCRIPT -After you create a self-signed certificate, you can sign scripts. If you -use the AllSigned execution policy, signing a script permits you to run -the script on your computer. +After you create a self-signed certificate, you can sign scripts. If you use +the AllSigned execution policy, signing a script permits you to run the script +on your computer. -The following sample script, Add-Signature.ps1, signs a script. However, -if you are using the AllSigned execution policy, you must sign the +The following sample script, Add-Signature.ps1, signs a script. However, if +you are using the AllSigned execution policy, you must sign the Add-Signature.ps1 script before you run it. -To use this script, copy the following text into a text file, and -name it Add-Signature.ps1. - -Note: Be sure that the script file does not have a .txt file name -extension. If your text editor appends ".txt", enclose the file name -in quotation marks: "add-signature.ps1". +To use this script, copy the following text into a text file, and name it +Add-Signature.ps1. -## add-signature.ps1 +```powershell ## Signs a file param([string] $file=$(throw "Please specify a filename.")) $cert = @(Get-ChildItem cert:\CurrentUser\My -codesigning)[0] Set-AuthenticodeSignature $file $cert +``` -To sign the Add-Signature.ps1 script file, type the following commands at -the Windows PowerShell command prompt: +To sign the Add-Signature.ps1 script file, type the following commands at the +PowerShell command prompt: +```powershell $cert = @(Get-ChildItem cert:\CurrentUser\My -codesigning)[0] - Set-AuthenticodeSignature add-signature.ps1 $cert +``` -After the script is signed, you can run it on the local computer. -However, the script will not run on computers on which the Windows -PowerShell execution policy requires a digital signature from a -trusted authority. If you try, Windows PowerShell displays the following -error message: +After the script is signed, you can run it on the local computer. However, the +script will not run on computers on which the PowerShell execution +policy requires a digital signature from a trusted authority. If you try, +PowerShell displays the following error message: +```output The file C:\remote_file.ps1 cannot be loaded. The signature of the certificate cannot be verified. At line:1 char:15 + .\ remote_file.ps1 <<<< +``` -If Windows PowerShell displays this message when you run a -script that you did not write, treat the file as you would treat any -unsigned script. Review the code to determine whether you can trust the -script. - -# ENABLE STRONG PRIVATE KEY PROTECTION FOR YOUR CERTIFICATE +If PowerShell displays this message when you run a script that you did not +write, treat the file as you would treat any unsigned script. Review the code +to determine whether you can trust the script. ---------------------------------------------------------- +## ENABLE STRONG PRIVATE KEY PROTECTION FOR YOUR CERTIFICATE -If you have a private certificate on your computer, malicious -programs might be able to sign scripts on your behalf, which -authorizes Windows PowerShell to run them. +If you have a private certificate on your computer, malicious programs might +be able to sign scripts on your behalf, which authorizes PowerShell to run +them. -To prevent automated signing on your behalf, use Certificate -Manager (Certmgr.exe) to export your signing certificate to -a .pfx file. Certificate Manager is included in the Microsoft -.NET Framework SDK, the Microsoft Windows SDK, and in Internet -Explorer 5.0 and later versions. +To prevent automated signing on your behalf, use Certificate Manager +(Certmgr.exe) to export your signing certificate to a .pfx file. Certificate +Manager is included in the Microsoft .NET Framework SDK, the Microsoft Windows +SDK, and in Internet Explorer 5.0 and later versions. To export the certificate: 1. Start Certificate Manager. - 2. Select the certificate issued by PowerShell Local Certificate Root. - 3. Click Export to start the Certificate Export Wizard. - 4. Select "Yes, export the private key", and then click Next. - 5. Select "Enable strong protection." - 6. Type a password, and then type it again to confirm. - 7. Type a file name that has the .pfx file name extension. - 8. Click Finish. To re-import the certificate: 1. Start Certificate Manager. - 2. Click Import to start the Certificate Import Wizard. - -3. Open to the location of the .pfx file that you created during the -export process. - +3. Open to the location of the .pfx file that you created during the export + process. 4. On the Password page, select "Enable strong private key protection", -and then enter the password that you assigned during the export -process. - + and then enter the password that you assigned during the export + process. 5. Select the Personal certificate store. - 6. Click Finish. -# PREVENT THE SIGNATURE FROM EXPIRING +## PREVENT THE SIGNATURE FROM EXPIRING ------------------------------------ The digital signature in a script is valid until the signing certificate expires or as long as a time stamp server can verify that the script was signed while the signing certificate was valid. -Because most signing certificates are valid for one year only, using a -time stamp server ensures that users can use your script for many years -to come. +Because most signing certificates are valid for one year only, using a time +stamp server ensures that users can use your script for many years to come. # SEE ALSO @@ -321,13 +296,10 @@ to come. [about_Profiles](about_Profiles.md) -Get-ExecutionPolicy - -New-SelfSignedCertificate - -Set-ExecutionPolicy +[Get-ExecutionPolicy](../../Microsoft.PowerShell.Security/Get-ExecutionPolicy.md) -Set-AuthenticodeSignature +[Set-ExecutionPolicy](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md) -"Introduction to Code Signing" (http://go.microsoft.com/fwlink/?LinkId=106296) +[Set-AuthenticodeSignature](../../Microsoft.PowerShell.Security/Set-AuthenticodeSignature.md) +[Introduction to Code Signing](http://go.microsoft.com/fwlink/?LinkId=106296) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md b/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md index 10b1d7bc00db..02d2b8d169e7 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Splatting.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,68 +7,61 @@ title: about_Splatting --- # About Splatting -## about_Splatting +## SHORT DESCRIPTION +Describes how to use splatting to pass parameters to commands in Windows +PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes how to use splatting to pass parameters to commands -in Windows PowerShell. +[This topic was contributed by Rohn Edwards of Gulfport, Mississippi, a system +administrator and the winner of the Advanced Division of the 2012 Scripting +Games. Revised for Windows PowerShell 3.0.] -# LONG DESCRIPTION +Splatting is a method of passing a collection of parameter values to a command +as unit. Windows PowerShell associates each value in the collection with a +command parameter. Splatted parameter values are stored in named splatting +variables, which look like standard variables, but begin with an At symbol (@) +instead of a dollar sign ($). The At symbol tells Windows PowerShell that you +are passing a collection of values, instead of a single value. -[This topic was contributed by Rohn Edwards of Gulfport, -Mississippi, a system administrator and the winner -of the Advanced Division of the 2012 Scripting Games. -Revised for Windows PowerShell 3.0.] +Splatting makes your commands shorter and easier to read. You can re-use the +splatting values in different command calls and use splatting to pass +parameter values from the `$PSBoundParameters` automatic variable to other +scripts and functions. -Splatting is a method of passing a collection of parameter -values to a command as unit. Windows PowerShell associates -each value in the collection with a command parameter. -Splatted parameter values are stored in named splatting -variables, which look like standard variables, but begin with -an At symbol (@) instead of a dollar sign ($). The At symbol -tells Windows PowerShell that you are passing a collection of -values, instead of a single value. +Beginning in Windows PowerShell 3.0, you can also use splatting to represent +all parameters of a command. -Splatting makes your commands shorter and easier to read. You -can re-use the splatting values in different command calls and -use splatting to pass parameter values from the `$PSBoundParameters` -automatic variable to other scripts and functions. +## SYNTAX -Beginning in Windows PowerShell 3.0, you can also use splatting -to represent all parameters of a command. - -# SYNTAX - -```powershell +``` @ @ ``` -To provide parameter values for positional parameters, in which -parameter names are not required, use the array syntax. To provide -parameter name and value pairs, use the hash table syntax. The -splatted value can appear anywhere in the parameter list. +To provide parameter values for positional parameters, in which parameter +names are not required, use the array syntax. To provide parameter name and +value pairs, use the hash table syntax. The splatted value can appear anywhere +in the parameter list. -When splatting, you do not need to use a hash table or an array to -pass all parameters. You may pass some parameters by using splatting -and pass others by position or by parameter name. Also, you can splat -multiple objects in a single command just so you pass no more than one -value for each parameter. +When splatting, you do not need to use a hash table or an array to pass all +parameters. You may pass some parameters by using splatting and pass others by +position or by parameter name. Also, you can splat multiple objects in a +single command just so you pass no more than one value for each parameter. -# SPLATTING WITH HASH TABLES +## SPLATTING WITH HASH TABLES -Use a hash table to splat parameter name and value pairs. You can use -this format for all parameter types, including positional and named -parameters and switch parameters. +Use a hash table to splat parameter name and value pairs. You can use this +format for all parameter types, including positional and named parameters and +switch parameters. -The following examples compare two `Copy-Item` commands that copy the -Test.txt file to the Test2.txt file in the same directory. +The following examples compare two `Copy-Item` commands that copy the Test.txt +file to the Test2.txt file in the same directory. -The first example uses the traditional format in which parameter names -are included. +The first example uses the traditional format in which parameter names are +included. ```powershell Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf @@ -76,9 +69,9 @@ Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf The second example uses hash table splatting. The first command creates a hash table of parameter-name and parameter-value pairs and stores it in the -\$HashArguments variable. The second command uses the `$HashArguments` variable -in a command with splatting. The At symbol (`@HashArguments`) replaces the -dollar sign (`$HashArguments`) in the command. +\$HashArguments variable. The second command uses the `$HashArguments` +variable in a command with splatting. The At symbol (`@HashArguments`) +replaces the dollar sign (`$HashArguments`) in the command. To provide a value for the WhatIf switch parameter, use $True or $False. @@ -91,11 +84,11 @@ $HashArguments = @{ Copy-Item @HashArguments ``` -Note: In the first command, the At symbol (@) indicates a hash table, not -a splatted value. The syntax for hash tables in Windows PowerShell is: +Note: In the first command, the At symbol (@) indicates a hash table, not a +splatted value. The syntax for hash tables in Windows PowerShell is: @{\=\; \=\; …}* -# SPLATTING WITH ARRAYS +## SPLATTING WITH ARRAYS Use an array to splat values for positional parameters, which do not require parameter names. The values must be in position-number order in the array. @@ -122,8 +115,7 @@ $ArrayArguments = "test.txt", "test2.txt" Copy-Item @ArrayArguments -WhatIf ``` -# EXAMPLES - +## EXAMPLES This example shows how to re-use splatted values in different commands. The commands in this example use the Write-Host cmdlet to write messages to the @@ -153,18 +145,16 @@ Write-Host "This is a test." @Colors Write-Host @Colors "This is another test." ``` -This example shows how to forward their parameters to other commands by -using splatting and the `$PSBoundParameters` automatic variable. +This example shows how to forward their parameters to other commands by using +splatting and the `$PSBoundParameters` automatic variable. -The $PSBoundParameters automatic variable is a dictionary -(System.Collections.Generic.Dictionary) that contains all of the -parameter names and values that are used when a script or function -is run. +The \$PSBoundParameters automatic variable is a dictionary +(System.Collections.Generic.Dictionary) that contains all of the parameter +names and values that are used when a script or function is run. -In the following example, we use the `$PSBoundParameters` variable to -forward the parameters values passed to a script or function from Test2 -function to the Test1 function. Both calls to the Test1 function from -Test2 use splatting. +In the following example, we use the `$PSBoundParameters` variable to forward +the parameters values passed to a script or function from Test2 function to +the Test1 function. Both calls to the Test1 function from Test2 use splatting. ```powershell function Test1 @@ -188,7 +178,9 @@ function Test2 $LimitedParameters.Remove("a") | Out-Null Test1 @LimitedParameters } +``` +```output Test2 -a 1 -b 2 -c 3 1 2 @@ -197,7 +189,7 @@ Test2 -a 1 -b 2 -c 3 3 ``` -# SPLATTING COMMAND PARAMETERS +## SPLATTING COMMAND PARAMETERS You can use splatting to represent the parameters of a command. This technique is useful when you are creating a proxy function, that is, a function that @@ -207,8 +199,8 @@ To splat the parameters of a command, use `@Args` to represent the command parameters. This technique is easier than enumerating command parameters and it works without revision even if the parameters of the called command change. -The feature uses the `$Args` automatic variable, which contains -all unassigned parameter values. +The feature uses the `$Args` automatic variable, which contains all unassigned +parameter values. For example, the following function calls the Get-Process cmdlet. In this function, `@Args` represents all of the parameters of the Get-Process cmdlet. @@ -217,19 +209,24 @@ function, `@Args` represents all of the parameters of the Get-Process cmdlet. function Get-MyProcess { Get-Process @Args } ``` -When you use the Get-MyProcess function, all unassigned -parameters and parameter values are passed to `@Args`, as -shown in the following commands. +When you use the Get-MyProcess function, all unassigned parameters and +parameter values are passed to `@Args`, as shown in the following commands. ```powershell Get-MyProcess -Name PowerShell +``` +```output Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 463 46 225484 237196 719 15.86 3228 powershell +``` +```powershell Get-MyProcess -Name PowerShell_Ise -FileVersionInfo +``` +```output ProductVersion FileVersion FileName -------------- ----------- -------- 6.2.9200.16384 6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\... @@ -248,7 +245,9 @@ function Get-MyCommand } Get-MyCommand -P -C -Name PowerShell +``` +```output Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 408 28 75568 83176 620 1.33 1692 powershell diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md index 1bfafbe78470..cf7500531b40 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2017-12-06 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -167,9 +167,9 @@ Switch has the following parameters: | |condition. Wildcard and Exact are ignored. Also, if the | | |match clause is not a string, this parameter is ignored. | +In this example, there is no matching case so there is no output. ```powershell -Example: PS> switch ("fourteen") { 1 {"It is one."; Break} @@ -179,7 +179,12 @@ Example: 3 {"Three again."; Break} "fo*" {"That's too many."} } +``` + +For the word "fourteen" to match a case you must use the **-Wildcard** or +**-Regex** parameter. +```powershell PS> switch -Regex ("fourteen") { 1 {"It is one."; Break} @@ -189,6 +194,11 @@ Example: 3 {"Three again."; Break} "fo*" {"That's too many."} } + ``` + + Result: + + ```Output That's too many. ``` diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Transactions.md b/reference/6/Microsoft.PowerShell.Core/About/about_Transactions.md deleted file mode 100644 index e93860f24d7f..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Transactions.md +++ /dev/null @@ -1,780 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_Transactions ---- - -# About Transactions -## about_Transactions - - - -# SHORT DESCRIPTION - -Describes how to manage transacted operations in Windows PowerShell. - -# LONG DESCRIPTION - -Transactions are supported in Windows PowerShell beginning -in Windows PowerShell 2.0. This feature enables you to start -a transaction, to indicate which commands are part of the -transaction, and to commit or roll back a transaction. - -# ABOUT TRANSACTIONS - - -In Windows PowerShell, a transaction is a set of one or more -commands that are managed as a logical unit. A transaction can -be completed ("committed"), which changes data affected by the -transaction. Or, a transaction can be completely undone ("rolled back") -so that the affected data is not changed by the transaction. - -Because the commands in a transaction are managed as a unit, -either all commands are committed, or all commands are rolled -back. - -Transactions are widely used in data processing, most notably -in database operations and for financial transactions. Transactions -are most often used when the worst-case scenario for a set of -commands is not that they all fail, but that some commands succeed -while others fail, leaving the system in a damaged, false, or -uninterpretable state that is difficult to repair. - -# TRANSACTION CMDLETS - - -Windows PowerShell includes several cmdlets designed for managing -transactions. - -Cmdlet Description --------------- --------------------------------- -Start-Transaction Starts a new transaction. - -Use-Transaction Adds a command or expression to the -transaction. The command must use -transaction-enabled objects. - -Undo-Transaction Rolls back the transaction so that -no data is changed by the transaction. - -Complete-Transaction Commits the transaction. The data -affected by the transaction is changed. - -Get-Transaction Gets information about the active -transaction. - -For a list of transaction cmdlets, type: - -get-command *transaction - -For detailed information about the cmdlets, type: - -get-help -detailed - -For example: - -get-help use-transaction -detailed - -# TRANSACTION-ENABLED ELEMENTS - - -To participate in a transaction, both the cmdlet and the provider -must support transactions. This feature is built in to the objects -that are affected by the transaction. - -The Windows PowerShell Registry provider supports transactions -in Windows Vista. The TransactedString object -(Microsoft.PowerShell.Commands.Management.TransactedString) works -with any operating system that runs Windows PowerShell. - -Other Windows PowerShell providers can support transactions. To -find the Windows PowerShell providers in your session that support -transactions, use the following command to find the "Transactions" -value in the Capabilities property of providers: - -get-psprovider | where {$_.Capabilities -like "transactions"} - -For more information about a provider, see the Help for the provider. -To get provider Help, type: - -get-help - -For example, to get Help for the Registry provider, type: - -get-help registry - -# THE USETRANSACTION PARAMETER - - -Cmdlets that can support transactions have a UseTransaction -parameter. This parameter includes the command in the active -transaction. You can use the full parameter name or its alias, -"usetx". - -The parameter can be used only when the session contains an -active transaction. If you enter a command with the UseTransaction -parameter when there is no active transaction, the command fails. - -To find cmdlets with the UseTransaction parameter, type: - -get-help * -parameter UseTransaction - -In Windows PowerShell core, all of the cmdlets designed to work -with Windows PowerShell providers support transactions. As a -result, you can use the provider cmdlets to manage transactions. - -For more information about Windows PowerShell providers, -see about_Providers. - -# THE TRANSACTION OBJECT - - -Transactions are represented in Windows PowerShell by a -transaction object, System.Management.Automation.Transaction. - -The object has the following properties: - -RollbackPreference: -Contains the rollback preference set for the current -transaction. You can set the rollback preference when you -use Start-Transaction to start the transaction. - -The rollback preference determines the conditions under -which the transaction is rolled back automatically. Valid -values are Error, TerminatingError, and Never. The default -value is Error. - -Status: -Contains the current status of the transaction. Valid -values are Active, Committed, and RolledBack. - -SubscriberCount: -Contains the number of subscribers to the transaction. A -subscriber is added to a transaction when you start a -transaction while another transaction is in progress. The -subscriber count is decremented when a subscriber commits -the transaction. - -# ACTIVE TRANSACTIONS - - -In Windows PowerShell, only one transaction is active at a -time, and you can manage only the active transaction. Multiple -transactions can be in progress in the same session at the same -time, but only the most-recently started transaction is active. - -As a result, you cannot specify a particular transaction when -using the transaction cmdlets. Commands always apply to the -active transaction. - -This is most evident in the behavior of the Get-Transaction cmdlet. -When you enter a Get-Transaction command, Get-Transaction always -gets only one transaction object. This object is the object that -represents the active transaction. - -To manage a different transaction, you must first finish the active -transaction, either by committing it or rolling it back. When you -do this, the previous transaction becomes active automatically. -Transactions become active in the reverse of order of which they are -started, so that the most recently started transaction is always -active. - -# SUBSCRIBERS AND INDEPENDENT TRANSACTIONS - - -If you start a transaction while another transaction is in progress, -by default, Windows PowerShell does not start a new transaction. -Instead, it adds a "subscriber" to the current transaction. - -When a transaction has multiple subscribers, a single -Undo-Transaction command at any point rolls back the entire -transaction for all subscribers. However, to commit the transaction, -you must enter a Complete-Transaction command for every subscriber. - -To find the number of subscribers to a transaction, check the -SubscriberCount property of the transaction object. For example, -the following command uses the Get-Transaction cmdlet to get -the value of the SubscriberCount property of the active transaction: - -(Get-Transaction).SubscriberCount - -Adding a subscriber is the default behavior because most transactions -that are started while another transaction is in progress are related -to the original transaction. In the typical model, a script that -contains a transaction calls a helper script that contains its own -transaction. Because the transactions are related, they should be -rolled back or committed as a unit. - -However, you can start a transaction that is independent of the -current transaction by using the Independent parameter of the -Start-Transaction cmdlet. - -When you start an independent transaction, Start-Transaction -creates a new transaction object, and the new transaction becomes -the active transaction. The independent transaction can be -committed or rolled back without affecting the original transaction. - -When the independent transaction is finished (committed or rolled -back), the original transaction becomes the active transaction -again. - -# CHANGING DATA - - -When you use transactions to change data, the data that is affected -by the transaction is not changed until you commit the transaction. -However, the same data can be changed by commands that are not -part of the transaction. - -Keep this in mind when you are using transactions to manage shared -data. Typically, databases have mechanisms that lock the data while -you are working on it, preventing other users, and other commands, -scripts, and functions, from changing it. - -However, the lock is a feature of the database. It is not related -to transactions. If you are working in a transaction-enabled -file system or other data store, the data can be changed while -the transaction is in progress. - -# EXAMPLES - -The examples in this section use the Windows PowerShell Registry -provider and assume that you are familiar with it. For information -about the Registry provider, type "get-help registry". - -# EXAMPLE 1: COMMITTING A TRANSACTION - - -To create a transaction, use the Start-Transaction cmdlet. The -following command starts a transaction with the default settings. - -start-transaction - -To include commands in the transaction, use the UseTransaction -parameter of the cmdlet. By default, commands are not included -in the transaction, - -For example, the following command, which sets the current -location in the Software key of the HKCU: drive, is not included -in the transaction. - -cd hkcu:\Software - -The following command, which creates the MyCompany key, uses the -UseTransaction parameter of the New-Item cmdlet to include the -command in the active transaction. - -new-item MyCompany -UseTransaction - -The command returns an object that represents the new key, but -because the command is part of the transaction, the registry -is not yet changed. - -Hive: HKEY_CURRENT_USER\Software - -SKC VC Name Property ---- -- ---- -------- -0 0 MyCompany {} - -To commit the transaction, use the Complete-Transaction cmdlet. -Because it always affects the active transaction, you cannot specify -the transaction. - -complete-transaction - -As a result, the MyCompany key is added to the registry. - -dir m* - -Hive: HKEY_CURRENT_USER\software - -SKC VC Name Property ---- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} - -# EXAMPLE 2: ROLLING BACK A TRANSACTION - - -To create a transaction, use the Start-Transaction cmdlet. The -following command starts a transaction with the default settings. - -start-transaction - -The following command, which creates the MyOtherCompany key, uses the -UseTransaction parameter of the New-Item cmdlet to include the -command in the active transaction. - -new-item MyOtherCompany -UseTransaction - -The command returns an object that represents the new key, but -because the command is part of the transaction, the registry -is not yet changed. - -Hive: HKEY_CURRENT_USER\Software - -SKC VC Name Property ---- -- ---- -------- -0 0 MyOtherCompany {} - -To roll back the transaction, use the Undo-Transaction cmdlet. -Because it always affects the active transaction, you do not specify -the transaction. - -Undo-transaction - -The result is that the MyOtherCompany key is not added to the registry. - -dir m* - -Hive: HKEY_CURRENT_USER\software - -SKC VC Name Property ---- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} - -# EXAMPLE 3: PREVIEWING A TRANSACTION - - -Typically, the commands used in a transaction change data. However, -the commands that get data are useful in a transaction, too, because -they get data inside of the transaction. This provides a preview of the -changes that committing the transaction would cause. - -The following example shows how to use the Get-ChildItem command -(the alias is "dir") to preview the changes in a transaction. - -The following command starts a transaction. - -start-transaction - -The following command uses the New-ItemProperty cmdlet to add the -MyKey registry entry to the MyCompany key. The command uses the -UseTransaction parameter to include the command in the transaction. - -new-itemproperty -path MyCompany -Name MyKey -value 123 -UseTransaction - -The command returns an object representing the new registry entry, -but the registry entry is not changed. - -MyKey ------ -# 123 - - -To get the items that are currently in the registry, use a Get-ChildItem -command ("dir") without the UseTransaction parameter. The following -command gets items that begin with "M." - -dir m* - -The result shows that no entries have yet been added to the MyCompany key. - -Hive: HKEY_CURRENT_USER\Software - -SKC VC Name Property ---- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} - -To preview the effect of committing the transaction, enter a Get-ChildItem -("dir") command with the UseTransaction parameter. This command has a view -of the data from within the transaction. - -dir m* -useTransaction - -The result shows that, if the transaction is committed, the MyKey entry -will be added to the MyCompany key. - -Hive: HKEY_CURRENT_USER\Software - -SKC VC Name Property ---- -- ---- -------- -83 1 Microsoft {(default)} -0 1 MyCompany {MyKey} - -# EXAMPLE 4: COMBINING TRANSACTED AND NON-TRANSACTED COMMANDS - - -You can enter non-transacted commands during a transaction. The -non-transacted commands affect the data immediately, but they do -not affect the transaction. - -The following command starts a transaction in the HKCU:\Software -registry key. - -start-transaction - -The next three commands use the New-Item cmdlet to add keys to -the registry. The first and third commands use the UseTransaction -parameter to include the commands in the transaction. The second -command omits the parameter. Because the second command is not -included in the transaction, it is effective immediately. - -new-item MyCompany1 -UseTransaction - -new-item MyCompany2 - -new-item MyCompany3 -UseTransaction - -To view the current state of the registry, use a Get-ChildItem ("dir") -command without the UseTransaction parameter. This command gets items -that begin with "M." - -dir m* - -The result shows that the MyCompany2 key is added to the registry, but -the MyCompany1 and MyCompany3 keys, which are part of the transaction, -are not added. - -Hive: HKEY_CURRENT_USER\Software - -SKC VC Name Property ---- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany2 {} - -The following command commits the transaction. - -complete-transaction - -Now, the keys that were added as part of the transaction appear in the -registry. - -dir m* - -Hive: HKEY_CURRENT_USER\Software - -SKC VC Name Property ---- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany1 {} -0 0 MyCompany2 {} -0 0 MyCompany3 {} - -# EXAMPLE 5: USING AUTOMATIC ROLLBACK - - -When a command in a transaction generates an error -of any kind, the transaction is automatically rolled -back. - -This default behavior is designed for scripts that -run transactions. Scripts are typically well tested -and include error-handling logic, so errors are not -expected and should terminate the transaction. - -The first command starts a transaction in the HKCU:\Software -registry key. - -start-transaction - -The following command uses the New-Item cmdlet to -add the MyCompany key to the registry. The command uses -the UseTransaction parameter (the alias is "usetx") to include -the command in the transaction. - -New-Item MyCompany -UseTX - -Because the MyCompany key already exists in the registry, -the command fails, and the transaction is rolled back. - -New-Item : A key at this path already exists -At line:1 char:9 -+ new-item <<<< MyCompany -usetx - -A Get-Transaction command confirms that the transaction -has been rolled back and that the SubscriberCount is 0. - -RollbackPreference SubscriberCount Status ------------------- --------------- ------ -Error 0 RolledBack - -# EXAMPLE 6: CHANGING THE ROLLBACK PREFERENCE - - -If you want the transaction to be more error tolerant, -you can use the RollbackPreference parameter of -Start-Transaction to change the preference. - -The following command starts a transaction with a -rollback preference of "Never". - -start-transaction -rollbackpreference Never - -In this case, when the command fails, the transaction -is not automatically rolled back. - -New-Item MyCompany -UseTX - -New-Item : A key at this path already exists -At line:1 char:9 -+ new-item <<<< MyCompany -usetx - -Because the transaction is still active, you can -resubmit the command as part of the transaction. - -New-Item MyOtherCompany -UseTX - -# EXAMPLE 7: USING THE USE-TRANSACTION CMDLET - - -The Use-Transaction cmdlet enables you to do direct scripting -against transaction-enabled Microsoft .NET Framework objects. -Use-Transaction takes a script block that can only contain commands -and expressions that use transaction-enabled .NET Framework objects, -such as instances of the -Microsoft.PowerShell.Commands.Management.TransactedString class. - -The following command starts a transaction. - -start-transaction - -The following New-Object command creates an instance of the -TransactedString class and saves it in the $t variable. - -$t = New-Object Microsoft.PowerShell.Commands.Management.TransactedString - -The following command uses the Append method of the TransactedString -object to add text to the string. Because the command is not part -of the transaction, the change is effective immediately. - -$t.append("Windows") - -The following command uses the same Append method to add text, but -it adds the text as part of the transaction. The command is enclosed -in braces, and it is set as the value of the ScriptBlock parameter of -Use-Transaction. The UseTransaction parameter (UseTx) is required. - -use-transaction {$t.append(" PowerShell")} -usetx - -To see the current content of the transacted string in $t, use the -ToString method of the TransactedString object. - -$t.tostring() - -The output shows that only the non-transacted changes are effective. - -Windows - -To see the current content of the transacted string in $t from within -the transaction, embed the expression in a Use-Transaction command. - -use-transaction {$s.tostring()} -usetx - -The output shows the transaction view. - -Windows PowerShell - -The following command commits the transaction. - -complete-transaction - -To see the final string: - -$t.tostring() - -Windows PowerShell - -# EXAMPLE 8: MANAGING MULTI-SUBSCRIBER TRANSACTIONS - - -When you start a transaction while another transaction is in -progress, Windows PowerShell does not create a second transaction -by default. Instead, it adds a subscriber to the current -transaction. - -This example shows how to view and manage a multi-subscriber -transaction. - -Begin by starting a transaction in the HKCU:\Software key. - -start-transaction - -The following command uses the Get-Transaction command to -get the active transaction. - -get-transaction - -The result shows the object that represents the active transaction. - -RollbackPreference SubscriberCount Status ------------------- --------------- ------ -Error 1 Active - -The following command adds the MyCompany key to the registry. -The command uses the UseTransaction parameter to include the -command in the transaction. - -new-item MyCompany -UseTransaction - -The following command uses the Start-Transaction command to -start a transaction. Although this command is typed at the command -prompt, this scenario is more likely to happen when you run a -script that contains a transaction. - -start-transaction - -A Get-Transaction command shows that the subscriber count on the -transaction object is incremented. The value is now 2. - -RollbackPreference SubscriberCount Status ------------------- --------------- ------ -Error 2 Active - -The next command uses the New-ItemProperty cmdlet to add the -MyKey registry entry to the MyCompany key. It uses the UseTransaction -parameter to include the command in the transaction. - -new-itemproperty -path MyCompany -name MyKey -UseTransaction - -The MyCompany key does not exist in the registry, but this -command succeeds because the two commands are part of the -same transaction. - -The following command commits the transaction. If it rolled back -the transaction, the transaction would be rolled back for all the -subscribers. - -complete-transaction - -A Get-Transaction command shows that the subscriber count on the -transaction object is 1, but the value of Status is still Active -(not Committed). - -RollbackPreference SubscriberCount Status ------------------- --------------- ------ -Error 1 Active - -To finish committing the transaction, enter a second Complete- -Transaction command. To commit a multi-subscriber transaction, -you must enter one Complete-Transaction command for each -Start-Transaction command. - -complete-transaction - -Another Get-Transaction command shows that the transaction -has been committed. - -RollbackPreference SubscriberCount Status ------------------- --------------- ------ -Error 0 Committed - -# EXAMPLE 9: MANAGING INDEPENDENT TRANSACTIONS - - -When you start a transaction while another transaction is in -progress, you can use the Independent parameter of Start-Transaction -to make the new transaction independent of the original transaction. - -When you do, Start-Transaction creates a new transaction object -and makes the new transaction the active transaction. - -Begin by starting a transaction in the HKCU:\Software key. - -start-transaction - -The following command uses the Get-Transaction command to -get the active transaction. - -get-transaction - -The result shows the object that represents the active transaction. - -RollbackPreference SubscriberCount Status ------------------- --------------- ------ -Error 1 Active - -The following command adds the MyCompany registry key as part of -the transaction. It uses the UseTransaction parameter (UseTx) -to include the command in the active transaction. - -new-item MyCompany -use - -The following command starts a new transaction. The command uses -the Independent parameter to indicate that this transaction -is not a subscriber to the active transaction. - -start-transaction -independent - -When you create an independent transaction, the new (most-recently -created) transaction becomes the active transaction. You can use -a Get-Transaction command to get the active transaction. - -get-transaction - -Note that the SubscriberCount of the transaction is 1, indicating -that there are no other subscribers and that the transaction is -new. - -RollbackPreference SubscriberCount Status ------------------- --------------- ------ -Error 1 Active - -The new transaction must be finished (either committed or rolled -back) before you can manage the original transaction. - -The following command adds the MyOtherCompany key to the registry. -It uses the UseTransaction parameter (UseTx) to include the command -in the active transaction. - -new-item MyOtherCompany -usetx - -Now, roll back the transaction. If there were a single -transaction with two subscribers, rolling back the transaction -would roll back the entire transaction for all the subscribers. - -However, because these transactions are independent, rolling -back the newest transaction cancels the registry changes and -makes the original transaction the active transaction. - -undo-transaction - -A Get-Transaction command confirms that the original -transaction is still active in the session. - -get-transaction - -RollbackPreference SubscriberCount Status ------------------- --------------- ------ -Error 1 Active - -The following command commits the active transaction. - -complete-transaction - -A Get-ChildItem command shows that the registry has been -changed. - -dir m* - -Hive: HKEY_CURRENT_USER\Software - -SKC VC Name Property ---- -- ---- -------- -83 1 Microsoft {(default)} -0 0 MyCompany {} - -# SEE ALSO - -Start-Transaction - -Get-Transaction - -Complete-Transaction - -Undo-Transaction - -Use-Transaction - -Registry (provider) - -[about_Providers](about_Providers.md) - -Get-PSProvider - -Get-ChildItem - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Updatable_Help.md b/reference/6/Microsoft.PowerShell.Core/About/about_Updatable_Help.md index 77f69a3b6008..7d45f6555135 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Updatable_Help.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Updatable_Help.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,487 +7,455 @@ title: about_Updatable_Help --- # About Updatable Help -## about_Updatable_Help +## SHORT DESCRIPTION +Describes the updatable help system in PowerShell. -# SHORT DESCRIPTION +## LONG DESCRIPTION -Describes the updatable help system in Windows PowerShell. +PowerShell provides several different ways to access the most up-to-date help +topics for PowerShell cmdlets and concepts. -# LONG DESCRIPTION +The Updatable Help system, introduced in PowerShell 3.0, is designed to assure +that you always have the newest help topics on your local computer so that you +can read them at the command line. It makes it easy to download and install +help files and to update them whenever newer help files become available. -Windows PowerShell provides several different ways to access -the most up-to-date help topics for Windows PowerShell cmdlets -and concepts. +To provide updated help for multiple computers in an enterprise and for +computers that do not have access to the Internet, Updatable Help lets you +download help files to a file system directory or file share, and then install +the help files from the file share. -The Updatable Help system, introduced in Windows PowerShell 3.0, -is designed to assure that you always have the newest help topics -on your local computer so that you can read them at the command -line. It makes it easy to download and install help files and -to update them whenever newer help files become available. +In PowerShell 4.0, the HelpInfoUri property is preserved over Windows +PowerShell remoting, which allows Save-Help to work for modules that are +installed on a remote computer, but are not necessarily installed on the local +computer. You can save a PSModuleInfo object to disk or removable media (such +as a USB drive) by running Export-Clixml on a computer that does not have +Internet access, importing the PSModuleInfo object on a computer that does +have Internet access, and then running Save-Help on the PSModuleInfo object. +The saved help can be copied to the remote, disconnected computer by using +removable media, and then installed by running Update-Help. These improvements +in Save-Help functionality let you install help on computers that are without +any kind of network access. For an example of how to use the new Save-Help +functionality, see "HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP" in this +topic. -To provide updated help for multiple computers in an enterprise -and for computers that do not have access to the Internet, Updatable -Help lets you download help files to a file system directory or file -share, and then install the help files from the file share. +Updatable Help also supports online access to the newest help topics and basic +help for cmdlets, even when there are no help files on the computer. -In Windows PowerShell 4.0, the HelpInfoUri property is preserved over -Windows PowerShell remoting, which allows Save-Help to work for -modules that are installed on a remote computer, but are not -necessarily installed on the local computer. You can save a PSModuleInfo -object to disk or removable media (such as a USB drive) by running -Export-CliXml on a computer that does not have Internet access, -importing the PSModuleInfo object on a computer that does have Internet -access, and then running Save-Help on the PSModuleInfo object. The -saved help can be copied to the remote, disconnected computer by using -removable media, and then installed by running Update-Help. These -improvements in Save-Help functionality let you install help on -computers that are without any kind of network access. For an example -of how to use the new Save-Help functionality, see "HOW TO UPDATE HELP -FROM A FILE SHARE: SAVE-HELP" in this topic. +PowerShell 3.0 does not come with Help files. You can use the Updatable Help +feature to install the help files for all of the commands that are included by +default in PowerShell and for all Windows modules. -Updatable Help also supports online access to the newest help topics -and basic help for cmdlets, even when there are no help files on the -computer. - -Windows PowerShell 3.0 does not come with Help files. You can use -the Updatable Help feature to install the help files for all of the -commands that are included by default in Windows PowerShell and for -all Windows modules. - -# UPDATABLE HELP CMDLETS - - -Update-Help: Downloads the newest help files from the Internet or -a file share, and installs them on the local computer. - -Save-Help: Downloads the newest help files from the Internet and -saves them in a file system directory or file share. To -install the help files on computers, use Update-Help. +## UPDATABLE HELP CMDLETS -Get-Help: -- Displays help topics at the command line. --- Gets help from the help files on the computer. --- Displays auto-generated help for cmdlets and functions -that do not have help files. --- Opens online help topics for cmdlets, functions, -scripts, and workflows in your default Internet -browser. +- Update-Help: Downloads the newest help files from the Internet or a file + share, and installs them on the local computer. -# UPDATE HELP IN WINDOWS POWERSHELL ISE +- Save-Help: Downloads the newest help files from the Internet and saves them in + a file system directory or file share. To install the help files on computers, + use Update-Help. -You can also update help by using the "Update Windows PowerShell -Help" item in the Help menu in Windows PowerShell Integrated -Scripting Environment (ISE). +- Get-Help: Displays help topics at the command line. Gets help from the + help files on the computer. Displays auto-generated help for cmdlets and + functions that do not have help files. Opens online help topics for + cmdlets, functions, scripts, and workflows in your default Internet browser. -The "Update Windows PowerShell Help" item runs an Update-Help -command without parameters. +## UPDATE HELP IN PowerShell ISE -# AUTO-GENERATED HELP: HELP WITHOUT HELP FILES +You can also update help by using the "Update PowerShell Help" item in the +Help menu in PowerShell Integrated Scripting Environment (ISE). +The "Update PowerShell Help" item runs an Update-Help command without +parameters. -If you do not have the help file for a cmdlet, function, -or workflow on the computer, the Get-Help cmdlet displays -auto-generated help and prompts you to download the help -files or read them online. +## AUTO-GENERATED HELP: HELP WITHOUT HELP FILES -Auto-generated help includes syntax and aliases, and remarks -that explain how to use the Updatable Help cmdlets and to -access the online help topics. +If you do not have the help file for a cmdlet, function, or workflow on the +computer, the Get-Help cmdlet displays auto-generated help and prompts you to +download the help files or read them online. -For example, the following command gets basic help for the -Get-Culture cmdlet. The output shows the Get-Help display -when there are no help files on the computer. +Auto-generated help includes syntax and aliases, and remarks that explain how +to use the Updatable Help cmdlets and to access the online help topics. -PS C:> Get-Help Get-Culture - -# NAME - -Get-Culture - -# SYNTAX +For example, the following command gets basic help for the Get-Culture cmdlet. +The output shows the Get-Help display when there are no help files on the +computer. -Get-Culture [] +```powershell +Get-Help Get-Culture +``` -# ALIASES +```output +NAME + Get-Culture -None +SYNTAX + Get-Culture [] -# REMARKS +ALIASES + None -To get the latest Help content including descriptions -and examples type: Update-Help. +REMARKS + To get the latest Help content including descriptions and examples + type: Update-Help. +``` -# HELP FILES FOR MODULES +## HELP FILES FOR MODULES +The smallest unit of Updatable Help is help for a module. Module help includes +help for all of the cmdlets, functions, workflows, providers, scripts, and +concepts in a module. You can update help for all modules that are installed +on the computer, even if they are not imported into the current session. -The smallest unit of Updatable Help is help for a module. Module -help includes help for all of the cmdlets, functions, workflows, -providers, scripts, and concepts in a module. You can update help -for all modules that are installed on the computer, even if they -are not imported into the current session. +You can update help for the entire module, but you cannot update help for +individual cmdlets. -You can update help for the entire module, but you cannot update -help for individual cmdlets. - -To find the module that contains a particular cmdlet, use the -following command format: +To find the module that contains a particular cmdlet, use the following +command format: +```powershell (Get-Command ).ModuleName +``` For example, to find the module that contains the Set-ExecutionPolicy cmdlet, type: +```powershell (Get-Command Set-ExecutionPolicy).ModuleName +``` To update help for a particular module, type: +```powershell Update-Help -Module +``` For example, to update help for the module that contains the Set-ExecutionPolicy cmdlet, type: +```powershell Update-Help -Module Microsoft.PowerShell.Security +``` -# PERMISSIONS FOR UPDATABLE HELP - - -To update help for the modules in the $pshome\Modules directory, -you must be member of the Administrators group on the computer. +## PERMISSIONS FOR UPDATABLE HELP -If you are not a member of the Administrators group, you cannot -update help for these modules; but if you have Internet access, -you can view help online in the TechNet Library. +To update help for the modules in the \$pshome\\Modules directory, you must be +member of the Administrators group on the computer. -Updating help for modules in the -$home\Documents\WindowsPowerShell\Modules -directory or modules in other subdirectories of the $home -directory do not require special permissions. +If you are not a member of the Administrators group, you cannot update help +for these modules; but if you have Internet access, you can view help online +in the TechNet Library. -The Update-Help and Save-Help cmdlets have a UseDefaultCredentials -parameter that provides the explicit credentials of the current -user. This parameter is designed for accessing secure Internet -locations. +Updating help for modules in the \$home\\Documents\\WindowsPowerShell\\Modules +directory or modules in other subdirectories of the \$home directory do not +require special permissions. -The Update-Help and Save-Help cmdlets also have a Credential -parameter that allows you to run the command on a remote -computer and access a file share on a third computer. The -Credential parameter is valid only when you use the SourcePath -or LiteralPath parameters of Update-Help and the DestinationPath -or LiteralPath parameters of Save-Help. +The Update-Help and Save-Help cmdlets have a UseDefaultCredentials parameter +that provides the explicit credentials of the current user. This parameter is +designed for accessing secure Internet locations. -# HOW TO INSTALL AND UPDATE HELP FILES +The Update-Help and Save-Help cmdlets also have a Credential parameter that +allows you to run the command on a remote computer and access a file share on +a third computer. The Credential parameter is valid only when you use the +SourcePath or LiteralPath parameters of Update-Help and the DestinationPath or +LiteralPath parameters of Save-Help. +## HOW TO INSTALL AND UPDATE HELP FILES -To download and install help files for the first time, or to update -the help files on your computer, use the Update-Help cmdlet. +To download and install help files for the first time, or to update the help +files on your computer, use the Update-Help cmdlet. -The Update-Help cmdlet does all of the hard work for you, including -the following tasks. +The Update-Help cmdlet does all of the hard work for you, including the +following tasks. --- Determines which modules support Updatable Help. --- Finds the Internet location where each module stores its -Updatable Help files. --- Compares the help files for each module on your computer to -the newest help files that are available for each module. --- Downloads the new files from the Internet. --- Unwraps the help file package. --- Verifies that the files are valid help files. --- Installs the help files in the language-specific subdirectory -of the module directory. +- Determines which modules support Updatable Help. +- Finds the Internet location where each module stores its Updatable Help files. +- Compares the help files for each module on your computer to the newest help + files that are available for each module. +- Downloads the new files from the Internet. +- Unwraps the help file package. +- Verifies that the files are valid help files. +- Installs the help files in the language-specific subdirectory of the module + directory. -To access the new help topics, use the Get-Help cmdlet. You do not -need to restart Windows PowerShell. +To access the new help topics, use the Get-Help cmdlet. You do not need to +restart PowerShell. -To install or update help for all modules on the computer that -supports Updatable Help, type: +To install or update help for all modules on the computer that supports +Updatable Help, type: +```powershell Update-Help +``` -To update help for particular modules, add the Module parameter -of Update-Help. Wildcard characters are permitted in the module name. +To update help for particular modules, add the Module parameter of +Update-Help. Wildcard characters are permitted in the module name. For example, to update help for the ServerManager module, type: +```powershell Update-Help -Module ServerManager - -# NOTES - -Without parameters, Update-Help updates help for all modules -in the session and for all installed modules that support -Updatable Help. To be included, modules must be installed in -directories that are listed in the value of the PSModulePath -environment variable. These are also modules that -are returned by a "Get-Help -ListAvailable" command. - -If the value of the Module parameter is * (all), Update-Help -attempts to update help for all installed modules, including -modules that do not support Updatable Help. This command -typically generates many errors as the cmdlet encounters modules -that do not support Updatable Help. - -# HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP - - -To support computers that are not connected to the Internet, -or to control or streamline help updating in an enterprise, -use the Save-Help cmdlet. The Save-Help cmdlet downloads help -files from the Internet and saves them in a file system directory -that you specify. - -Save-Help compares the help files in the specified directory to -the newest help files that are available for each module. If the -directory has no help files or newer help files are available for -the module, the Save-Help cmdlet downloads the new files from the -Internet. However, it does not unwrap or install the help files. - -To install or update the help files on a computer from help -files that were saved to a file system directory, use the -SourcePath parameter of the Update-Help cmdlet. The Update-Help -cmdlet identifies the newest help files, unwraps and validates them, -and installs them in the language-specific subdirectories of the -module directories. - -For example, to save help for all installed modules to the -\Server\Share directory, type: - -Save-Help -DestinationPath \Server\Share - -Then, to update help from the \Server\Share directory, type: - -Update-Help -SourcePath \Server\Share - -The following examples show the use of Save-Help to save help -for modules that are not installed on the local computer. In -this example, the administrator runs Save-Help to save the help -for the DhcpServer module from an Internet-connected client computer, -without installing the DhcpServer module or DHCP Server role on the -local computer. - -Option 1: Run Invoke-Command to get the PSModuleInfo object for -the remote module, save it in a variable, $m, and then run Save-Help -on the PSModuleInfo object by specifying the variable $m as the -module name. - +``` + +Without parameters, Update-Help updates help for all modules in the session +and for all installed modules that support Updatable Help. To be included, +modules must be installed in directories that are listed in the value of the +PSModulePath environment variable. These are also modules that are returned by +a "Get-Help -ListAvailable" command. + +If the value of the Module parameter is * (all), Update-Help attempts to +update help for all installed modules, including modules that do not support +Updatable Help. This command typically generates many errors as the cmdlet +encounters modules that do not support Updatable Help. + +## HOW TO UPDATE HELP FROM A FILE SHARE: SAVE-HELP + +To support computers that are not connected to the Internet, or to control or +streamline help updating in an enterprise, use the Save-Help cmdlet. The +Save-Help cmdlet downloads help files from the Internet and saves them in a +file system directory that you specify. + +Save-Help compares the help files in the specified directory to the newest +help files that are available for each module. If the directory has no help +files or newer help files are available for the module, the Save-Help cmdlet +downloads the new files from the Internet. However, it does not unwrap or +install the help files. + +To install or update the help files on a computer from help files that were +saved to a file system directory, use the SourcePath parameter of the +Update-Help cmdlet. The Update-Help cmdlet identifies the newest help files, +unwraps and validates them, and installs them in the language-specific +subdirectories of the module directories. + +For example, to save help for all installed modules to the \\\\Server\\Share +directory, type: + +```powershell +Save-Help -DestinationPath \\Server\Share +``` + +Then, to update help from the \\\\Server\\Share directory, type: + +```powershell +Update-Help -SourcePath \\Server\Share +``` + +The following examples show the use of Save-Help to save help for modules that +are not installed on the local computer. In this example, the administrator +runs Save-Help to save the help for the DhcpServer module from an +Internet-connected client computer, without installing the DhcpServer module +or DHCP Server role on the local computer. + +Option 1: Run Invoke-Command to get the PSModuleInfo object for the remote +module, save it in a variable, $m, and then run Save-Help on the PSModuleInfo +object by specifying the variable $m as the module name. + +```powershell $m = Invoke-Command -ComputerName RemoteServer -ScriptBlock { Get-Module -Name DhcpServer -ListAvailable } Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -Option 2: Open a PSSession, targeted at the computer that is -running the DHCP Server module, to get the PSModuleInfo object for -the module, save it in a variable $m, and then run Save-Help on the -object that is saved in the $m variable. +Option 2: Open a PSSession, targeted at the computer that is running the DHCP +Server module, to get the PSModuleInfo object for the module, save it in a +variable $m, and then run Save-Help on the object that is saved in the $m +variable. +```powershell $s = New-PSSession -ComputerName RemoteServer $m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -Option 3: Open a CIM session, targeted at the computer that is -running the DHCP Server module, to get the PSModuleInfo object for -the module, save it in a variable $m, and then run Save-Help on the -object that is saved in the $m variable. +Option 3: Open a CIM session, targeted at the computer that is running the +DHCP Server module, to get the PSModuleInfo object for the module, save it in +a variable $m, and then run Save-Help on the object that is saved in the $m +variable. +```powershell $c = New-CimSession -ComputerName RemoteServer $m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable Save-Help -Module $m -DestinationPath C:\SavedHelp +``` -In the following example, the administrator installs help for the -DHCP Server module on a computer that does not have network access. +In the following example, the administrator installs help for the DHCP Server +module on a computer that does not have network access. -First, run Export-CliXml to export the PSModuleInfo object to -a shared folder or to removable media. +First, run Export-Clixml to export the PSModuleInfo object to a shared folder +or to removable media. +```powershell $m = Get-Module -Name DhcpServer -ListAvailable -Export-CliXml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m - -Next, transport the removable media to a computer that has -Internet access, and then import the PSModuleInfo object with -Import-CliXml. Run Save-Help to save the Help for the imported -DhcpServer module PSModuleInfo object. - -$deserialized_m = Import-CliXml E:\UsbFlashDrive\DhcpModule.xml -Save-Help -Module $deserialized_m -DestinationPath -E:\UsbFlashDrive\SavedHelp +Export-Clixml -Path E:\UsbFlashDrive\DhcpModule.xml -InputObject $m +``` -Finally, transport the removable media back to the computer that -does not have network access, and then install the help by running -Update-Help. +Next, transport the removable media to a computer that has Internet access, +and then import the PSModuleInfo object with Import-Clixml. Run Save-Help to +save the Help for the imported DhcpServer module PSModuleInfo object. -Update-Help -Module DhcpServer -SourcePath +```powershell +$deserialized_m = Import-Clixml E:\UsbFlashDrive\DhcpModule.xml +Save-Help -Module $deserialized_m -DestinationPath ` E:\UsbFlashDrive\SavedHelp +``` -# NOTES: +Finally, transport the removable media back to the computer that does not have +network access, and then install the help by running Update-Help. -Without parameters, Save-Help downloads help for all modules -in the session and for all installed modules that support -Updatable Help. To be included, modules must be installed in -directories that are listed in the value of the PSModulePath -environment variable, on either the local computer or on a remote -computer for which you want to save help. These are also modules -that are returned by running a "Get-Help -ListAvailable" command. +```powershell +Update-Help -Module DhcpServer -SourcePath E:\UsbFlashDrive\SavedHelp +``` -# HOW TO UPDATE HELP FILES IN DIFFERENT LANGUAGES +Without parameters, Save-Help downloads help for all modules in the session +and for all installed modules that support Updatable Help. To be included, +modules must be installed in directories that are listed in the value of the +PSModulePath environment variable, on either the local computer or on a remote +computer for which you want to save help. These are also modules that are +returned by running a "Get-Help -ListAvailable" command. +## HOW TO UPDATE HELP FILES IN DIFFERENT LANGUAGES -By default, the Update-Help and Save-Help cmdlets download -help in the UI culture and language that is set for Windows -on the local computer. If help files for the specified modules -are not available in the local UI culture, Update-Help and -Save-Help use the Windows language fallback rules to find the +By default, the Update-Help and Save-Help cmdlets download help in the UI +culture and language that is set for Windows on the local computer. If help +files for the specified modules are not available in the local UI culture, +Update-Help and Save-Help use the Windows language fallback rules to find the best supported language. -However, you can use the UICulture parameters of the Update-Help -and Save-Help cmdlets to download and install help files in any -UI cultures in which they are available. +However, you can use the UICulture parameters of the Update-Help and Save-Help +cmdlets to download and install help files in any UI cultures in which they +are available. -For example, to save the newest help files for all modules on -the session in Japanese (Ja-jp) and French (fr-FR), type: +For example, to save the newest help files for all modules on the session in +Japanese (Ja-jp) and French (fr-FR), type: +```powershell Save-Help -Path \Server\Share -UICulture ja-jp, fr-fr +``` -If help files for the modules are not available in the languages -that you specified, the Update-Help and Save-Help cmdlets return -an error message that lists the languages in which help for each -module is available so you can choose the alternative that best -meets your needs. +If help files for the modules are not available in the languages that you +specified, the Update-Help and Save-Help cmdlets return an error message that +lists the languages in which help for each module is available so you can +choose the alternative that best meets your needs. -# HOW TO UPDATE HELP AUTOMATICALLY +## HOW TO UPDATE HELP AUTOMATICALLY +To assure that you always have the newest help files, you can add an +Update-Help command to your PowerShell profile. -To assure that you always have the newest help files, you can -add an Update-Help command to your Windows PowerShell profile. +An internal quota prevents the Update-Help command from running more than once +each day. To override the once-per-day maximum, use the Force parameter. -An internal quota prevents the Update-Help command from running -more than once each day. To override the once-per-day maximum, -use the Force parameter. - -Use a command like the following one in your profile. This command -updates help for all installed modules in a background job so it -doesn't disturb your work. It uses an Out-Null command to suppress -the job that is returned and any error messages that would otherwise -appear when you use the command more than once per day. +Use a command like the following one in your profile. This command updates +help for all installed modules in a background job so it doesn't disturb your +work. It uses an Out-Null command to suppress the job that is returned and any +error messages that would otherwise appear when you use the command more than +once per day. +```powershell Start-Job {Update-Help} | Out-Null +``` -You can also create a scheduled job that runs the Update-Help or -Save-Help cmdlet at any interval. +You can also create a scheduled job that runs the Update-Help or Save-Help +cmdlet at any interval. For example, the following command creates a scheduled job that runs an -Update-Help help command every Friday at 5:00 AM. To run this command, -start Windows PowerShell with the "Run as administrator" option. +Update-Help help command every Friday at 5:00 AM. To run this command, start +PowerShell with the "Run as administrator" option. +```powershell Register-ScheduledJob -Name UpdateHelpJob -ScriptBlock {Update-Help} ` -Trigger (New-JobTrigger -Weekly -DaysOfWeek Friday -At "5:00 AM") +``` -For more information about scheduled jobs, see about_Scheduled_Jobs. - -# HOW TO USE ONLINE HELP - +## HOW TO USE ONLINE HELP -If you cannot or choose not to update the help files on your -local computer, you can still get the newest help files online. +If you cannot or choose not to update the help files on your local computer, +you can still get the newest help files online. -To open the online help topic for any cmdlet or function, use -the Online parameter of the Get-Help cmdlet. +To open the online help topic for any cmdlet or function, use the Online +parameter of the Get-Help cmdlet. -For example, the following command opens the online help topic -for the Get-Job cmdlet in your default Internet browser: +For example, the following command opens the online help topic for the Get-Job +cmdlet in your default Internet browser: +```powershell Get-Help Get-Job -Online --or- -Get-Help -on Get-Job - -To get online help for a script, use the Online parameter and -the full path to the script. - -The Online parameter does not work with About topics. To see -the about topics for Windows PowerShell Core, including help -topics about the Windows PowerShell language, see "Windows -PowerShell Core Module About Topics" at -http://go.microsoft.com/fwlink/?LinkID=113206. - -# HOW TO MINIMIZE OR PREVENT INTERNET DOWNLOADS - -To minimize Internet downloads and provide Updatable Help to -users who are not connected to the Internet, use the Save-Help -cmdlet. Download help from the Internet and save it to a network -share. Then, create a Group Policy setting or scheduled job that -runs an Update-Help command on all computers. Set the value of -the SourcePath parameter of the Update-Help cmdlet to the network -share. - -To prevent users who have Internet access from downloading Updatable -Help from the Internet, use the "Set the default source path for -Update-Help" Group Policy setting. +``` -This Group Policy setting implicitly adds the SourcePath parameter, -with the file system location that you specify, to every Update-Help -command on every affected computer. Users can use the SourcePath -parameter explicitly to specify a different file system location, but -they cannot exclude the SourcePath parameter and download help from -the Internet. +To get online help for a script, use the Online parameter and the full path to +the script. -NOTE: The "Set the default source path for Update-Help" group -policy setting appears under Computer Configuration and -User Configuration. However, only the policy setting -under Computer Configuration is effective. The policy -setting under User Configuration is ignored. +The Online parameter does not work with About topics. To see the about topics +for PowerShell Core, including help topics about the PowerShell language, see +[Windows PowerShell Core Module About Topics](http://go.microsoft.com/fwlink/?LinkID=113206). -For more information, see about_Group_Policy_Settings. +## HOW TO MINIMIZE OR PREVENT INTERNET DOWNLOADS -# HOW TO UPDATE HELP FOR NON-STANDARD MODULES +To minimize Internet downloads and provide Updatable Help to users who are not +connected to the Internet, use the Save-Help cmdlet. Download help from the +Internet and save it to a network share. Then, create a Group Policy setting +or scheduled job that runs an Update-Help command on all computers. Set the +value of the SourcePath parameter of the Update-Help cmdlet to the network +share. -To update or save help for a module that is not returned -by the ListAvailable parameter of the Get-Module cmdlet, -import the module into the current session before running -an Update-Help or Save-Help command. On a remote computer, -before running the Save-Help command, import the module into -the current CIM or PSSession--or Invoke-Command script block-- -that is connected to the remote computer. +To prevent users who have Internet access from downloading Updatable Help from +the Internet, use the "Set the default source path for Update-Help" Group +Policy setting. -When the module is in the current session, run the Update-Help -or Save-Help cmdlets without parameters, or use the Module -parameter to specify the module name. +This Group Policy setting implicitly adds the SourcePath parameter, with the +file system location that you specify, to every Update-Help command on every +affected computer. Users can use the SourcePath parameter explicitly to +specify a different file system location, but they cannot exclude the +SourcePath parameter and download help from the Internet. -The Module parameters of the Update-Help and Save-Help -cmdlets accept only a module name. They do not accept the -path to a module file. +NOTE: The "Set the default source path for Update-Help" group policy setting +appears under Computer Configuration and User Configuration. However, only the +policy setting under Computer Configuration is effective. The policy setting +under User Configuration is ignored. -Use this technique to update or save help for any module -that is not returned by the ListAvailable parameter of the -Get-Module cmdlet, such as a module that is installed in a -location that is not listed in the PSModulePath environment -variable, or a module that is not well-formed (the module -directory does not contain at least one file whose base name -is the same as the directory name). +For more information, see [about_Group_Policy_Settings](about_Group_Policy_Settings.md). -# HOW TO SUPPORT UPDATABLE HELP +## HOW TO UPDATE HELP FOR NON-STANDARD MODULES +To update or save help for a module that is not returned by the ListAvailable +parameter of the Get-Module cmdlet, import the module into the current session +before running an Update-Help or Save-Help command. On a remote computer, +before running the Save-Help command, import the module into the current CIM +or PSSession--or Invoke-Command script block-- that is connected to the remote +computer. -If you author a module, you can support online help and -Updatable Help for your modules. For more information, see -"Supporting Updatable Help" and "Supporting Online Help" -in the MSDN Library. +When the module is in the current session, run the Update-Help or Save-Help +cmdlets without parameters, or use the Module parameter to specify the module +name. -Updatable help not available for Windows PowerShell snap-ins -or comment-based help. +The Module parameters of the Update-Help and Save-Help cmdlets accept only a +module name. They do not accept the path to a module file. -# KEYWORDS +Use this technique to update or save help for any module that is not returned +by the ListAvailable parameter of the Get-Module cmdlet, such as a module that +is installed in a location that is not listed in the PSModulePath environment +variable, or a module that is not well-formed (the module directory does not +contain at least one file whose base name is the same as the directory name). -About_Updateable_Help +## HOW TO SUPPORT UPDATABLE HELP -# REMARKS +If you author a module, you can support online help and Updatable Help for +your modules. For more information, see "Supporting Updatable Help" and +"Supporting Online Help" in the MSDN Library. -The Update-Help and Save-Help cmdlets are not supported on -Windows Preinstallation Environment (Windows PE). +Updatable help not available for PowerShell snap-ins or comment-based help. -# SEE ALSO +# REMARKS -Get-Help +The Update-Help and Save-Help cmdlets are not supported on Windows +Preinstallation Environment (Windows PE). -Save-Help +## SEE ALSO -Update-Help +[Get-Help](../Get-Help.md) -Updatable Help Status Table (http://go.microsoft.com/fwlink/?LinkID=270007) +[Save-Help](../Save-Help.md) +[Update-Help](../Update-Help.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_WMI.md b/reference/6/Microsoft.PowerShell.Core/About/about_WMI.md deleted file mode 100644 index 816338a248a5..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/About/about_WMI.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_WMI ---- - -# About WMI -## about_WMI - - -## SHORT DESCRIPTION -Windows Management Instrumentation (WMI) uses the Common Information Model (CIM) to represent systems, applications, networks, devices, and other manageable components of the modern enterprise. - - -## LONG DESCRIPTION -Windows Management Instrumentation (WMI) is Microsoft’s implementation of Web-Based Enterprise Management (WBEM), the industry standard. - -Classic WMI uses DCOM to communicate with networked devices to manage remote systems. Windows PowerShell 3.0 introduces a CIM provider model that uses WinRM to remove the dependency on DCOM. This CIM provider model also uses new WMI provider APIs that enable developers to write Windows PowerShell cmdlets in native code (C\+\+). - -Do not confuse WMI providers with Windows PowerShell providers. Many Windows features have an associated WMI provider that exposes their management capabilities. To get WMI providers, run a WMI query that gets instances of the __Provider WMI class, such as the following query. - - -``` -Get-WmiObject -Class __Provider -``` - - - -## THREE COMPONENTS OF WMI -The following three components of WMI interact with Windows PowerShell: Namespaces, Providers, and Classes. - -WMI Namespaces organize WMI providers and WMI classes into groups of related components. In this way, they are similar to .NET Framework namespaces. Namespaces are not physical locations, but are more like logical databases. All WMI namespaces are instances of the __Namespace system class. The default WMI namespace is Root\/CIMV2 (since Microsoft Windows 2000). To use Windows PowerShell to get WMI namespaces in the current session, use a command with the following format. - - -``` -Get-WmiObject -Class __Namespace -``` - - -To get WMI namespaces in other namespaces, use the Namespace parameter to change the location of the search. The following command finds WMI namespaces that reside in the Root\/Cimv2\/Applications namespace. - - -``` -Get-WmiObject -Class __Namespace -Namespace -root/CIMv2/applications -``` - - -WMI namespaces are hierarchical. Therefore, obtaining a list of all namespaces on a particular system requires performing a recursive query starting at the root namespace. - -WMI Providers expose information about Windows manageable objects. A provider retrieves data from a component, and passes that data through WMI to a management application, such as Windows PowerShell. Most WMI providers are dynamic providers, which means that they obtain the data dynamically when it is requested through the management application. - - -## FINDING WMI CLASSES -In a default installation of Windows 8, there are more than 1,100 WMI classes in Root\/Cimv2. With this many WMI classes, the challenge becomes identifying the appropriate WMI class to use to perform a specific task. Windows PowerShell 3.0 provides two ways to find WMI classes that are related to a specific topic. - -For example,to find WMI classes in the root\CIMV2 WMI namespace that are related to disks, you can use a query such as the one shown here. - - -``` -Get-WmiObject -List *disk* -``` - - -To find WMI classes that are related to memory, you might use a query such as the one shown here. - - -``` -Get-WmiObject -List *memory* -``` - - -The CIM cmdlets also provide the ability to discover WMI classes. To do this, use the Get-CIMClass cmdlet. The command shown here lists WMI classes related to video. - - -``` -Get-CimClass *video* -``` - - -Tab expansion works when changing WMI namespaces, and therefore use of tab expansion makes sub-WMI namespaces easily discoverable. In the following example, the Get-CimClass cmdlet lists WMI classes related to power settings. To find it, type the root\/CIMV2\/ WMI namespace, and then press type the root\/CIMV2\/ WMI namespace, and then press the Tab key several times until the power namespace appears. Here is the command: - - -``` -Get-CimClass *power* -Namespace root/cimv2/power -``` - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md b/reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md deleted file mode 100644 index 08ee68185fcb..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/About/about_WMI_Cmdlets.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -ms.date: 2017-12-01 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_WMI_Cmdlets ---- - -# About WMI Cmdlets - -## SHORT DESCRIPTION - -Provides background information about Windows Management Instrumentation (WMI) -and Windows PowerShell. - -## LONG DESCRIPTION - -This topic provides information about WMI technology, the WMI cmdlets for -Windows PowerShell, WMI-based remoting, WMI accelerators, and WMI -troubleshooting. This topic also provides links to more information about WMI. - -### ABOUT WMI - -Windows Management Instrumentation (WMI) is the Microsoft implementation of -Web-Based Enterprise Management (WBEM), which is an industry initiative to -develop a standard technology for accessing management information in an -enterprise environment. WMI uses the Common Information Model (CIM) industry -standard to represent systems, applications, networks, devices, and other -managed components. CIM is developed and maintained by the Distributed -Management Task Force (DMTF). You can use WMI to manage both local and remote -computers. For example, you can use WMI to do the following: - -- Start a process on a remote computer. -- Restart a computer remotely. -- Get a list of the applications that are installed on a local or remote - computer. -- Query the Windows event logs on a local or remote computer. - -### THE WMI CMDLETS FOR WINDOWS POWERSHELL - -Windows PowerShell implements WMI functionality through a set of cmdlets that -are available in Windows PowerShell by default. You can use these cmdlets to -complete the end-to-end tasks necessary to manage local and remote computers. - -The following WMI cmdlets are included. - -|Cmdlet |Description | -|-----------------|----------------------------------------------| -|Get-WmiObject |Gets instances of WMI classes or information | -| |about the available classes. | -|Invoke-WmiMethod |Calls WMI methods. | -|Register-WmiEvent|Subscribes to a WMI event. | -|Remove-WmiObject |Deletes WMI classes and instances. | -|Set-WmiInstance |Creates or modifies instances of WMI classes. | - -### SAMPLE COMMANDS -The following command displays the BIOS information for the local computer. - -```powershell -C:\PS> get-wmiobject win32_bios | format-list * -``` - -The following command displays information about the WinRM service for three -remote computers. - -```powershell -$wql = "select * from win32_service where name='WinRM'" -get-wmiobject -query $wql -computername server01, server01, server03 -``` - -The following more complex command exits all instances of a program. - -```powershell -C:\PS> notepad.exe -C:\PS> $wql = "select * from win32_process where name='notepad.exe'" -C:\PS> $np = get-wmiobject -query $wql -C:\PS> $np | remove-wmiobject -``` - -### WMI-BASED REMOTING - -While the ability to manage a local system through WMI is useful, it is the -remoting capabilities that make WMI a powerful administrative tool. WMI uses -Microsoft's Distributed Component Object Model (DCOM) to connect to and manage -systems. You might have to configure some systems to allow DCOM connections. -Firewall settings and locked-down DCOM permissions can block WMI's ability to -remotely manage systems. - -### WMI TYPE ACCELERATORS - -Windows PowerShell includes WMI type accelerators. These WMI type accelerators -(shortcuts) allow more direct access to a WMI objects than a non-type -accelerator approach would allow. - -The following type accelerators are supported with WMI: - -[WMISEARCHER] - A shortcut for searching for WMI objects. - -[WMICLASS] - A shortcut for accessing the static properties and methods of a class. - -[WMI] - A shortcut for getting a single instance of a class. - -[WMISEARCHER] is a type accelerator for a ManagementObjectSearcher. It can -take a string constructor to create a searcher that you can then do a GET() -on. - -For example: - -```powershell -PS> $s = [WmiSearcher]'Select * from Win32_Process where Handlecount > 1000' -PS> $s.Get() |sort handlecount |ft handlecount,__path,name -auto - -count __PATH name ------ ------ ---- -1105 \\SERVER01\root\cimv2:Win32_Process.Handle="3724" PowerShell... -1132 \\SERVER01\root\cimv2:Win32_Process.Handle="1388" winlogon.exe -1495 \\SERVER01\root\cimv2:Win32_Process.Handle="2852" iexplore.exe -1699 \\SERVER01\root\cimv2:Win32_Process.Handle="1204" OUTLOOK.EXE -1719 \\SERVER01\root\cimv2:Win32_Process.Handle="1912" iexplore.exe -2579 \\SERVER01\root\cimv2:Win32_Process.Handle="1768" svchost.exe -``` - -[WMICLASS] is a type accelerator for ManagementClass. This has a string -constructor that takes a local or absolute WMI path to a WMI class and returns -an object that is bound to that class. - -For example: - -```powershell -PS> $c = [WMICLASS]"root\cimv2:WIn32_Process" -PS> $c |fl * -Name : Win32_Process -__GENUS : 1 -__CLASS : Win32_Process -__SUPERCLASS : CIM_Process -__DYNASTY : CIM_ManagedSystemElement -__RELPATH : Win32_Process -__PROPERTY_COUNT : 45 -__DERIVATION : {CIM_Process, CIM_LogicalElement, - CIM_ManagedSystemElement} -__SERVER : SERVER01 -__NAMESPACE : ROOT\cimv2 -__PATH : \\SERVER01\ROOT\cimv2:Win32_Process -``` - -[WMI] is a type accelerator for ManagementObject. This has a string -constructor that takes a local or absolute WMI path to a WMI instance and -returns an object that is bound to that instance. - -For example: - -```powershell -PS> $p = [WMI]'\\SERVER01\root\cimv2:Win32_Process.Handle="1204"' -PS> $p.Name -OUTLOOK.EXE -``` - -### WMI TROUBLESHOOTING - -The following problems are the most common problems that might occur when you -try to connect to a remote computer. - -Problem 1: The remote computer is not online. - -If a computer is offline, you will not be able to connect to it by using WMI. -You may receive the following error message: - - Remote server machine does not exist or is unavailable - -If you receive this error message, verify that the computer is online. Try to -ping the remote computer. - -Problem 2: You do not have local administrator rights on the remote computer. - -To use WMI remotely, you must have local administrator rights on the remote -computer. If you do not, access to that computer will be denied. - -To verify namespace security: - -1. Click Start, right-click My Computer, and then click Manage. -2. In Computer Management, expand Services and Applications, right-click WMI - Control, and then click Properties. -3. In the WMI Control Properties dialog box, click the Security tab. - -Problem 3: A firewall is blocking access to the remote computer. - -WMI uses the DCOM (Distributed COM) and RPC (Remote Procedure Call) protocols -to traverse the network. By default, many firewalls block DCOM and RPC -traffic. If your firewall is blocking these protocols, your connection will -fail. For example, Windows Firewall in Microsoft Windows XP Service Pack 2 is -configured to automatically block all unsolicited network traffic, including -DCOM and WMI. In its default configuration, Windows Firewall rejects an -incoming WMI request, and you receive the following error message: - - Remote server machine does not exist or is unavailable - -### MORE INFORMATION ABOUT WMI - -For more information about WMI, see the following topics in the MSDN -(Microsoft Developer Network) library: - -About WMI: http://go.microsoft.com/fwlink/?LinkId=142212 - -WMI Troubleshooting: http://go.microsoft.com/fwlink/?LinkId=142213 - -And, see "Secrets of Windows Management Instrumentation - Troubleshooting and -Tips" in the Microsoft TechNet Script Center: - -http://go.microsoft.com/fwlink/?LinkId=142214 - - -## SEE ALSO - -Get-WmiObject - -Invoke-WmiMethod - -Register-WmiEvent - -Remove-WmiObject - -Set-WmiInstance - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_WQL.md b/reference/6/Microsoft.PowerShell.Core/About/about_WQL.md deleted file mode 100644 index 4413e4b4bf38..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/About/about_WQL.md +++ /dev/null @@ -1,739 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_WQL ---- - -# About WQL -## about_WQL - - - -# SHORT DESCRIPTION - -Describes WMI Query Language (WQL), which can be -used to get WMI objects in Windows PowerShell. - -# LONG DESCRIPTION - -WQL is the Windows Management Instrumentation (WMI) -query language, which is the language used to get -information from WMI. - -You are not required to use WQL to perform a WMI -query in Windows PowerShell. Instead, you can -use the parameters of the Get-WmiObject or -Get-CimInstance cmdlets. WQL queries are somewhat -faster than standard Get-WmiObject commands and -the improved performance is evident when the commands -run on hundreds of systems. However, be sure that -the time you spend to write a successful WQL query -doesn't outweigh the performance improvement. - -The basic WQL statements you need to use WQL are -Select, Where, and From. - -# WHEN TO USE WQL - - -When working with WMI, and especially with WQL, -do not forget that you are also using Windows -PowerShell. Often, if a WQL query does not work as -expected, it's easier to use a standard Windows -PowerShell command than to debug the WQL query. - -Unless you are returning massive amounts of data -from across bandwidth-constrained remote systems, -it is rarely productive to spend hours trying to -perfect a complicated and convoluted WQL query -when there is a perfectly acceptable Windows -cmdlet that does the same thing, if a bit more -slowly. - -# USING THE SELECT STATEMENT - - -A typical WMI query begins with a Select statement -that gets all properties or particular properties -of a WMI class. To select all properties of a WMI -class, use an asterisk (*). The From keyword -specifies the WMI class. - -A Select statement has the following format: - -Select from - -For example, the following Select statement selects -all properties (*) from the instances of the Win32_Bios -WMI class. - -Select * from Win32_Bios - -To select a particular property of a WMI class, -place the property name between the Select and -From keywords. - -The following query selects only the name of -the BIOS from the Win32_Bios WMI class. The -command saves the query in the $queryName -variable. - -Select Name from Win32_Bios - -To select more than one property, use commas to -separate the property names. The following WMI -query selects the name and the version of the -Win32_Bios WMI class. The command saves the -query in the $queryNameVersion variable. - -Select name, version from Win32_Bios - -# USING THE WQL QUERY - - -There are three ways to use WQL query in Windows -PowerShell command. - --- Use the Get-WmiObject cmdlet --- Use the Get-CimInstance cmdlet --- Use the [wmisearcher] type accelerator. - -# USING THE GET-WMIOBJECT CMDLET - -The most basic way to use the WQL query is to enclose -it in quotation marks (as a string) and then use the -query string as the value of the Query parameter of -the Get-WmiObject cmdlet, as shown in the following -example. - -PS C:> Get-WmiObject -Query "Select * from Win32_Bios" - -SMBIOSBIOSVersion : 8BET56WW (1.36 ) -Manufacturer : LENOVO -Name : Default System BIOS -SerialNumber : R9FPY3P -Version : LENOVO - 1360 - -You can also save the WQL statement in a variable -and then use the variable as the value of the Query -parameter, as shown in the following command. - -PS C:> $query = "Select * from Win32_Bios" -PS C:> Get-WmiObject -Query $query - -You can use either format with any WQL statement. -The following command uses the query in the -$queryName variable to get only the name and -version properties of the system BIOS. - -PS C:> $queryNameVersion = "Select Name, Version from Win32_Bios" -PS C:> Get-WmiObject -Query $queryNameVersion - -# __GENUS : 2 - -__CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - -__DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - -Name : Default System BIOS -Version : LENOVO - 1360 - -Remember that you can use the parameters of the -Get-WmiObject cmdlet to get the same result. For -example, the following command also gets the values -of the Name and Version properties of instances of -the Win32_Bios WMI class. - -PS C:> Get-WmiObject -Class Win32_Bios -Property Name, Version - -# __GENUS : 2 - -__CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - -__DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - -Name : Default System BIOS -Version : LENOVO - 1360 - -# USING THE GET-CIMINSTANCE CMDLET - - -Beginning in Windows PowerShell 3.0, you can use -the Get-CimInstance cmdlet to run WQL queries. - -Get-CimInstance gets instances of CIM-compliant -classes, including WMI classes. The CIM cmdlets, -introduced Windows PowerShell 3.0, perform the same -tasks as the WMI cmdlets. The CIM cmdlets comply -with WS-Management (WSMan) standards and with the -Common Information Model (CIM) standard, which enables -the cmdlets to use the same techniques to manage -Windows computers and computers that are running -other operating systems. - -The following command uses the Get-CimInstance -cmdlet to run a WQL query. - -Any WQL query that can be used with Get-WmiObject -can also be used with Get-CimInstance. - -PS C:> Get-CimInstance -Query "Select * from Win32_Bios" - -SMBIOSBIOSVersion : 8BET56WW (1.36 ) -Manufacturer : LENOVO -Name : Default System BIOS -SerialNumber : R9FPY3P -Version : LENOVO - 1360 - -Get-CimInstance returns a CimInstance object, instead of -the ManagementObject that Get-WmiObject returns, but -the objects are quite similar. - -PS C:> (Get-CimInstance -Query "Select * from Win32_Bios").GetType().FullName -Microsoft.Management.Infrastructure.CimInstance -PS C:> (Get-WmiObject -Query "Select * from Win32_Bios").GetType().FullName -System.Management.ManagementObject - -USING THE [wmisearcher] TYPE ACCELERATOR - -The [wmisearcher] type accelerator creates a -ManagementObjectSearcher object from a WQL -statement string. The ManagementObjectSearcher -object has many properties and methods, but the -most basic method is the Get method, which -invokes the specified WMI query and returns -the resulting objects. - -By using the [wmisearcher], you gain easy access -to the ManagementObjectSearcher .NET Framework class. -This lets you query WMI and to configure the way -the query is conducted. - -To use the [wmisearcher] type accelerator: - -1. Cast the WQL string into a ManagementObjectSearcher -object. -2. Call the Get method of the ManagementObjectSearcher -object. - -For example, the following command casts the "select -all" query, saves the result in the $bios variable, -and then calls the Get method of the ManagementObjectSearcher -object in the $bios variable. - -PS C:> $bios = [wmisearcher]"Select * from Win32_Bios" -PS C:> $bios.Get() - -SMBIOSBIOSVersion : 8BET56WW (1.36 ) -Manufacturer : LENOVO -Name : Default System BIOS -SerialNumber : R9FPY3P -Version : LENOVO - 1360 - -NOTE: Only selected object properties are displayed -by default. These properties are defined in the -Types.ps1xml file. - -You can use the [wmisearcher] type accelerator to -cast the query or the variable. In the following -example, the [wmisearcher] type accelerator is -used to cast the variable. The result is the same. - -PS C:> [wmisearcher]$bios = "Select * from Win32_Bios" -PS C:> $bios.Get() - -SMBIOSBIOSVersion : 8BET56WW (1.36 ) -Manufacturer : LENOVO -Name : Default System BIOS -SerialNumber : R9FPY3P -Version : LENOVO - 1360 - -When you use the [wmisearcher] type accelerator, it -changes the query string into a ManagementObjectSearcher -object, as shown in the following commands. - -PS C:> $a = "Select * from Win32_Bios" -PS C:> $a.GetType().FullName -System.String - -PS C:> $a = [wmisearcher]"Select * from Win32_Bios" -PS C:> $a.GetType().FullName -System.Management.ManagementObjectSearcher - -This command format works on any query. The following -command gets the value of the Name property of the -Win32_Bios WMI class. - -PS C:> $biosname = [wmisearcher]"Select Name from Win32_Bios" -PS C:> $biosname.Get() - -# __GENUS : 2 - -__CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - -__DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - -Name : Default System BIOS - -You can perform this operation in a single command, -although the command is a bit more difficult to -interpret. - -In this format, you use the [wmisearcher] type -accelerator to cast the WQL query string to a -ManagementObjectSearcher, and then call the Get -method on the object -- all in a single command. -The parentheses () that enclose the casted string -direct Windows PowerShell to cast the string before -calling the method. - -PS C:> ([wmisearcher]"Select name from Win32_Bios").Get() - -# __GENUS : 2 - -__CLASS : Win32_BIOS -# __SUPERCLASS : - -# __DYNASTY : - -# __RELPATH : - -# __PROPERTY_COUNT : 1 - -__DERIVATION : {} -# __SERVER : - -# __NAMESPACE : - -# __PATH : - -Name : Default System BIOS - -# USING THE BASIC WQL WHERE STATEMENT - - -A Where statement establishes conditions -for the data that a Select statement returns. - -The Where statement has the following format: - -where - -For example: - -where Name = 'Notepad.exe' - -The Where statement is used with the Select -statement, as shown in the following example. - -Select * from Win32_Process where Name = 'Notepad.exe' - -When using the Where statement, the property name -and value must be accurate. - -For example, the following command gets the Notepad -processes on the local computer. - -PS C:> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad.exe'" - -However, the following command fails, because the -process name includes the ".exe" file name -extension. - -PS C:> Get-WmiObject -Query "Select * from Win32_Process where name = 'Notepad'" - -# WHERE STATEMENT COMPARISON OPERATORS - -The following operators are valid in a -WQL Where statement. - -Operator Description ------------------------ -= Equal -!= Not equal -<> Not equal -< Less than -> Greater than -<= Less than or equal ->= Greater than or equal -LIKE Wildcard match -IS Evaluates null -ISNOT Evaluates not null -ISA Evaluates a member of a WMI class - -There are other operators, but these are the ones -used for making comparisons. - -For example, the following query selects the Name -and Priority properties from processes in the -Win32_Process class where the process priority -is greater than or equal to 11. The Get-WmiObject -cmdlet runs the query. - -$highPriority = "Select Name, Priority from Win32_Process where Priority >= 11" -Get-WmiObject -Query $highPriority - -# USING THE WQL OPERATORS IN THE FILTER PARAMETER - - -The WQL operators can also be used in the value -of the Filter parameter of the Get-WmiObject or -Get-CimInstance cmdlets, as well as in the value -of the Query parameters of these cmdlets. - -For example, the following command gets the Name -and ProcessID properties of the last five processes -that have ProcessID values greater than 1004. The -command uses the Filter parameter to specify the -ProcessID condition. - -PS C:> Get-WmiObject -Class Win32_Process ` --Property Name, ProcessID -Filter "ProcessID >= 1004" | -Sort ProcessID | Select Name, ProcessID -Last 5 - -Name ProcessID ----- --------- -SROSVC.exe 4220 -# WINWORD.EXE 4664 - -TscHelp.exe 4744 -SnagIt32.exe 4748 -WmiPrvSE.exe 5056 - -# USING THE LIKE OPERATOR - -The Like operator lets you use wildcard characters -to filter the results of a WQL query. - -Like Operator Description --------------------------------------------------- -[] Character in a range [a-f] or a set -of characters [abcdef]. The items in -a set do not need to be consecutive or -listed in alphabetical order. - -^ Character not in a range [^a-f] or -not in a set [^abcdef]. The items in -a set do not need to be consecutive or -listed in alphabetical order. - -% A string of zero or more characters - -_ One character. -(underscore) NOTE: To use a literal underscore -in a query string, enclose it in -square brackets [_]. - -When the Like operator is used without any wildcard -characters or range operators, it behaves like the -equality operator (=) and returns objects only -when they are an exact match for the pattern. - -You can combine the range operation with the percent -wildcard character to create simple, yet powerful -filters. - -# LIKE OPERATOR EXAMPLES - - -EXAMPLE 1: [] -The following commands start Notepad and then -search for an instance of the Win32_Process -class that has a name that starts with a letter -between "H" and "N" (case-insensitive). - -The query should return any process from Hotpad.exe -through Notepad.exe. - -PS C:> Notepad # Starts Notepad -PS C:> $query = "Select * from win32_Process where Name LIKE '[H-N]otepad.exe'" -PS C:> Get-WmiObject -Query $query | Select Name, ProcessID - -Name ProcessID ----- --------- -notepad.exe 1740 - -EXAMPLE 2: [] and % -The following commands select all process -that have a name that begins with a letter between -A and P (case-insensitive) followed by zero or more -letters in any combination. - -The Get-WmiObject cmdlet runs the query, the -Select-Object cmdlet gets the Name and ProcessID -properties, and the Sort-Object cmdlet sorts the -results in alphabetical order by name. - -PS C:> $query = "Select * from win32_Process where name LIKE '[A-P]%'" -PS C:> Get-WmiObject -Query $query | -Select-Object -Property Name, ProcessID | -Sort-Object -Property Name - -EXAMPLE 3: Not in Range (^) -The following command gets processes whose names -do not begin with any of the following letters: -# A, S, W, P, R, C, U, N - -and followed zero or more letters. - -PS C:> $query = "Select * from win32_Process where name LIKE '[^ASWPRCUN]%'" -PS C:> Get-WmiObject -Query $query | -Select-Object -Property Name, ProcessID | -Sort-Object -Property Name - -EXAMPLE 4: Any characters -- or none (%) -The following commands get processes that have -names that begin with "calc". The % symbol in -WQL is equivalent to the asterisk (*) symbol in -regular expressions. - -PS C:> $query = "Select * from win32_Process where Name LIKE 'calc%'" -PS C:> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID - -Name ProcessID ----- --------- -calc.exe 4424 - -EXAMPLE 5: One character (_) -The following commands get processes that -have names that have the following pattern, -"c_lc.exe" where the underscore character -represents any one character. This pattern -matches any name from calc.exe through -czlc.exe, or c9lc.exe, but does not match -names in which the "c" and "l" are separated -by more than one character. - -PS C:> $query = "Select * from Win32_Process where Name LIKE 'c_lc.exe'" -PS C:> Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID - -Name ProcessID ----- --------- -calc.exe 4424 - -EXAMPLE 6: Exact match -The following commands get processes named -WLIDSVC.exe. Even though the query uses the -Like keyword, it requires an exact match, -because the value does not include any -wildcard characters. - -$query = "Select * from win32_Process where name LIKE 'WLIDSVC.exe'" -Get-WmiObject -Query $query | Select-Object -Property Name, ProcessID - -Name ProcessID ----- --------- -WLIDSVC.exe 84 - -# USING THE OR OPERATOR - -To specify multiple independent conditions, use the Or -keyword. The Or keyword appears in the Where clause. It -performs an inclusive OR operation on two (or more) -conditions and returns items that meet any of the -conditions. - -The Or operator has the following format: - -Where or ... - -For example, the following commands get all instances -of the Win32_Process WMI class but returns them -only if the process name is winword.exe or excel.exe. - -PS C:> $q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe'" -PS C:> Get-WmiObject -Query $q - -The Or statement can be used with more than two -conditions. In the following query, the Or statement -gets Winword.exe, Excel.exe, or Powershell.exe. - -$q = "Select * from Win32_Process where Name = 'winword.exe' or Name = 'excel.exe' or Name = 'powershell.exe'" - -# USING THE AND OPERATOR - -To specify multiple related conditions, use the And -keyword. The And keyword appears in the Where clause. It -returns items that meet all of the conditions. - -The And operator has the following format: - -Where and ... - -For example, the following commands get processes -that have a name of "Winword.exe" and the process -ID of 6512. - -Note that the commands use the Get-CimInstance cmdlet. - -PS C:> $q = "Select * from Win32_Process where Name = 'winword.exe' and ProcessID =6512" -PS C:> Get-CimInstance -Query $q - -ProcessId Name HandleCount WorkingSetSize VirtualSize ---------- ---- ----------- -------------- ----------- -# 6512 WINWORD.EXE 768 117170176 633028608 - - -All operators, including the Like operators are -valid with the Or and And operators. And, you can -combine the Or and And operators in a single query -with parentheses that tell Windows PowerShell which -clauses to process first. - -This command uses the Windows PowerShell continuation -character (`) divide the command into two lines. - -PS C:> $q = "Select * from Win32_Process ` -where (Name = 'winword.exe' or Name = 'excel.exe') and HandleCount > 700" - -PS C:> Get-CimInstance -Query $q -ProcessId Name HandleCount WorkingSetSize VirtualSize ---------- ---- ----------- -------------- ----------- -# 6512 WINWORD.EXE 797 117268480 634425344 - -# 9610 EXCEL.EXE 727 38858752 323227648 - - -# SEARCHING FOR NULL VALUES - -Searching for null values in WMI is challenging, -because it can lead to unpredictable results. Null -is not zero and it is not equivalent or to an empty -string. Some WMI class properties are initialized and -others are not, so a search for null might not work -for all properties. - -To search for null values, use the Is operator with -a value of "null". - -For example, the following commands get processes -that have a null value for the IntallDate property. -The commands return many processes. - -PS C:> $q = "Select * from Win32_Process where InstallDate is null" -PS C:> Get-WmiObject -Query $q - -In contrast, the following command, gets user -accounts that have a null value for the Description -property. This command does not return any user -accounts, even though most user accounts do not have -any value for the Description property. - -PS C:> $q = "Select * from Win32_UserAccount where Description is null" -PS C:> Get-WmiObject -Query $q - -To find the user accounts that have no value for -the Description property, use the equality operator -to get an empty string. To represent the empty string, -use two consecutive single quotation marks. - -$q = "Select * from Win32_UserAccount where Description = '' " - -# USING TRUE OR FALSE - -To get Boolean values in the properties of WMI -objects, use True and False. They are not case -sensitive. - -The following WQL query returns only local user -accounts from a domain joined computer. - -PS C:> $q = "Select * from Win32_UserAccount where LocalAccount = True" -PS C:> Get-CimInstance -Query $q - -To find domain accounts, use a value of False, -as shown in the following example. - -PS C:> $q = "Select * from Win32_UserAccount where LocalAccount = False" -PS C:> Get-CimInstance -Query $q - -# USING THE ESCAPE CHARACTER - -WQL uses the backslash () as its escape -character. This is different from Windows -PowerShell, which uses the backtick -character (`). - -Quotation marks, and the characters used for -quotation marks, often need to be escaped so -that they are not misinterpreted. - -To find a user whose name includes a single quotation -mark, use a backslash to escape the single quotation -mark, as shown in the following command. - -PS C:> $q = "Select * from Win32_UserAccount where Name = 'Tim O\'Brian'" -PS C:> Get-CimInstance -Query $q -Name Caption AccountType SID Domain ----- ------- ----------- --- ------ -Tim O'Brian FABRIKAM\TimO 512 S-1-5-21-1457... FABRIKAM - -In some case, the backslash also needs to be -escaped. For example, the following commands -generate an Invalid Query error due to the -backslash in the Caption value. - -PS C:> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" -PS C:> Get-CimInstance -Query $q -Get-CimInstance : Invalid query -At line:1 char:1 -+ Get-CimInstance -Query $q -# +!INCLUDE[]~~~~~~~~~~~ - -+ CategoryInfo : InvalidArgument: (:) [Get-CimInstance], CimException -+ FullyQualifiedErrorId : HRESULT 0x80041017,Microsoft.Management.Infrastructure.CimCmdlets - -To escape the backslash, use a second backslash -character, as shown in the following command. - -PS C:> $q = "Select * from Win32_UserAccount where Caption = 'Fabrikam\TimO'" -PS C:> Get-CimInstance -Query $q - -# SEE ALSO - -[about_Special_Characters](about_Special_Characters.md) - -[about_Quoting_Rules](about_Quoting_Rules.md) - -[about_WMI](about_WMI.md) - -[about_WMI_Cmdlets](about_WMI_Cmdlets.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md b/reference/6/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md deleted file mode 100644 index c33d88dcf883..000000000000 --- a/reference/6/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -ms.date: 2017-06-09 -schema: 2.0.0 -locale: en-us -keywords: powershell,cmdlet -title: about_WS Management_Cmdlets ---- - -# About WS-Management Cmdlets -## about_WS-Management_Cmdlets - - -# SHORT DESCRIPTION - -Provides an overview of Web Services for Management (WS-Management) as -background for using the WS-Management cmdlets in Windows PowerShell. - -# LONG DESCRIPTION - -This topic provides an overview of Web Services for Management -(WS-Management) as background for using the WS-Management cmdlets in -Windows PowerShell. This topic also provides links to more information -about WS-Management. The Microsoft implementation of WS-Management is also -known as Windows Remote Management (WinRM). - -About WS-Management - -Windows Remote Management is the Microsoft implementation -of the WS-Management protocol, a standard SOAP-based, firewall-friendly -protocol that allows hardware and operating systems from different -vendors to interoperate. The WS-Management protocol specification -provides a common way for systems to access and exchange management -information across an information technology (IT) infrastructure. -WS-Management and Intelligent Platform Management Interface (IPMI), -along with the Event Collector, are components of the Windows Hardware -Management features. - -The WS-Management protocol is based on the following standard Web service -specifications: HTTPS, SOAP over HTTP (WS-I profile), SOAP 1.2, -WS-Addressing, WS-Transfer, WS-Enumeration, and WS-Eventing. - -WS-Management and WMI - -WS-Management can be used to retrieve data exposed by Windows Management -Instrumentation (WMI). You can obtain WMI data with scripts or -applications that use the WS-Management Scripting API or through the -WinRM command-line tool. WS-Management supports most of the familiar WMI -classes and operations, including embedded objects. WS-Management can -leverage WMI to collect data about resources or to manage resources on a -Windows-based computers. That means that you can obtain data -about objects such as disks, network adapters, services, or processes -in your enterprise through the existing set of WMI classes. You can also -access the hardware data that is available from the standard WMI IPMI -provider. - -WS-Management Windows PowerShell Provider (WSMan) - -The WSMan provider provides a hierarchical view into the -available WS-Management configuration settings. The provider allows you -to explore and set the various WS-Management configuration options. - -WS-Management Configuration - -If WS-Management is not installed and configured, Windows PowerShell -remoting is not available, the WS-Management cmdlets do not run, -WS-Management scripts do not run, and the WSMan provider cannot -perform data operations. The WS-Management command-line tool, WinRM, -and event forwarding also depend on the WS-Management configuration. - -WS-Management Cmdlets - -WS-Management functionality is implemented in Windows PowerShell through -a module that contains a set of cmdlets and the WSMan provider. -You can use these cmdlets to complete the end-to-end tasks necessary -to manage WS-Management settings on local and remote computers. - -The following WS-Management cmdlets are available. - -Connection Cmdlets - --- Connect-WSMan: Connects the local computer to the WS-Management -(WinRM) service on a remote computer. - --- Disconnect-WSMan: Disconnects the local computer from the WS-Management -(WinRM) service on a remote computer. - -Management-Data Cmdlets - --- Get-WSManInstance: Displays management information for a resource -instance that is specified by a resource URI. - --- Invoke-WSManAction: Invokes an action on the target object that -is specified by the resource URI and by the selectors. - --- New-WSManInstance: Creates a new management resource instance. - --- Remove-WSManInstance: Deletes a management resource instance. - --- Set-WSManInstance: Modifies the management information that is -related to a resource. - -Setup and Configuration Cmdlets - --- Set-WSManQuickConfig: Configures the local computer for remote -management. You can use the Set-WSManQuickConfig cmdlet to configure -WS-Management to allow remote connections to the WS-Management (WinRM) -service. The Set-WSManQuickConfig cmdlet performs the following -operations: - -- It determines whether the WS-Management (WinRM) service is running. -If the WinRM service is not running, the Set-WSManQuickConfig cmdlet -starts the service. - -- It sets the WS-Management (WinRM) service startup type to automatic. - -- It creates a listener that accepts requests from any IP address. -The default transport protocol is HTTP. - -- It enables a firewall exception for WS-Management traffic. - -Note: To run this cmdlet in Windows Vista, Windows Server 2008, and -later versions of Windows, you must start Windows PowerShell -with the "Run as administrator" option. - --- Test-WSMan: Verifies that WS-Management is installed and configured. -The Test-WSMan cmdlet tests whether the WS-Management (WinRM) -service is running and configured on a local or remote computer. - --- Disable-WSManCredSSP: Disables CredSSP authentication on a client -computer. - --- Enable-WSManCredSSP: Enables CredSSP authentication on a client -computer. - --- Get-WSManCredSSP: Gets the CredSSP-related configuration for a -client computer. - -WS-Management-Specific Cmdlets - --- New-WSManSessionOption: Creates a WSManSessionOption object to use as -input to one or more parameters of a WS-Management cmdlet. - -Additional WS-Management Information - -For more information about WS-Management, see the following topics in the -MSDN (Microsoft Developer Network) library. - -"Windows Remote Management" -http://go.microsoft.com/fwlink/?LinkId=142321 - -"About Windows Remote Management" -http://go.microsoft.com/fwlink/?LinkId=142322 - -"Installation and Configuration for Windows Remote Management" -http://go.microsoft.com/fwlink/?LinkId=142323 - -"Windows Remote Management Architecture" -http://go.microsoft.com/fwlink/?LinkId=142324 - -"WS-Management Protocol" -http://go.microsoft.com/fwlink/?LinkId=142325 - -"Windows Remote Management and WMI" -http://go.microsoft.com/fwlink/?LinkId=142326 - -"Resource URIs" -http://go.microsoft.com/fwlink/?LinkId=142327 - -"Remote Hardware Management" -http://go.microsoft.com/fwlink/?LinkId=142328 - -"Events" -http://go.microsoft.com/fwlink/?LinkId=142329 - -# SEE ALSO - -Online version: http://go.microsoft.com/fwlink/?LinkId=142331 -Connect-WSMan -Disable-WSManCredSSP -Disconnect-WSMan -Enable-WSManCredSSP -Get-WSManCredSSP -Get-WSManInstance -Invoke-WSManAction -New-WSManInstance -Remove-WSManInstance -Set-WSManInstance -Set-WSManQuickConfig -Set-WSManSessionOption -Test-WSMan - -# KEYWORDS - -about_WSMAN about_WinRM - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_hidden.md b/reference/6/Microsoft.PowerShell.Core/About/about_hidden.md index e64ac4f500a6..50b1758d40d5 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_hidden.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_hidden.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -27,17 +27,17 @@ Hidden members are not displayed by using tab completion or IntelliSense, unless the completion occurs in the class that defines the hidden member. A new attribute, System.Management.Automation.HiddenAttribute, has been added, -so that C# code can have the same semantics within Windows PowerShell. +so that C\# code can have the same semantics within PowerShell. The Hidden keyword is useful for creating properties and methods within a class that you do not necessarily want other users of the class to see, or readily be able to edit. The Hidden keyword has no effect on how you can view or make changes to -members of a class. Like all language keywords in Windows PowerShell, Hidden -is not case-sensitive, and hidden members are still public. +members of a class. Like all language keywords in PowerShell, Hidden is not +case-sensitive, and hidden members are still public. -Hidden, along with custom classes, was introduced in Windows PowerShell 5.0. +Hidden, along with custom classes, was introduced in PowerShell 5.0. ## EXAMPLE @@ -46,7 +46,7 @@ definition. The Car class method, Drive, has a property, rides, that does not need to be viewed or changed (it merely tallies the number of times that Drive is called on the Car class, a metric that is not important to users of the class; consider, for example, that when you are buying a car, you do not ask -the seller on how many drives the car has been taken). +the seller on how many drives the car has been taken. Because there is little need for users of the class to change this property, we can hide the property from Get-Member and automatic completion results by @@ -79,17 +79,17 @@ class Car ``` Now, create a new instance of the Car class, and save it in a variable, -$TestCar. +\$TestCar. ```powershell $TestCar = [Car]::new() ``` After you create the new instance, pipe the contents of the $TestCar variable -to Get\-Member. Observe that the rides property is not among the members -listed in the Get\-Member command results. +to Get-Member. Observe that the rides property is not among the members listed +in the Get-Member command results. -```powershell +```output PS C:\Windows\system32> $TestCar | Get-Member TypeName: Car @@ -104,13 +104,14 @@ ToString Method string ToString() Color Property string Color {get;set;} Distance Property int Distance {get;set;} ModelYear Property string ModelYear {get;set;} + ``` -Now, try running Get\-Member again, but this time, add the –Force parameter. +Now, try running Get-Member again, but this time, add the –Force parameter. Note that the results contain the hidden rides property, among other members that are hidden by default. -```powershell +```output PS C:\Windows\system32> $TestCar | Get-Member -Force TypeName: Car @@ -139,11 +140,15 @@ Color Property string Color {get;set;} Distance Property int Distance {get;set;} ModelYear Property string ModelYear {get;set;} rides Property int rides {get;set;} + ``` ## SEE ALSO -- [about_Classes](about_Classes.md) -- [about_Language_Keywords](about_Language_Keywords.md) -- [about_Wildcards](about_Wildcards.md) -- [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) +[about_Classes](about_Classes.md) + +[about_Language_Keywords](about_Language_Keywords.md) + +[about_Wildcards](about_Wildcards.md) + +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_logical_operators.md b/reference/6/Microsoft.PowerShell.Core/About/about_logical_operators.md index cafeedc3d3f5..7d9280a26f85 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_logical_operators.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_logical_operators.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,13 +14,13 @@ Describes the operators that connect statements in PowerShell. ## LONG DESCRIPTION -The PowerShell logical operators connect expressions and statements, -allowing you to use a single expression to test for multiple conditions. +The PowerShell logical operators connect expressions and statements, allowing +you to use a single expression to test for multiple conditions. -For example, the following statement uses the and operator and the or -operator to connect three conditional statements. The statement is true -only when the value of $a is greater than the value of $b, and either $a or -$b is less than 20. +For example, the following statement uses the and operator and the or operator +to connect three conditional statements. The statement is true only when the +value of $a is greater than the value of $b, and either $a or $b is less than +20. ```powershell ($a -gt $b) -and (($a -lt 20) -or ($b -lt 20)) @@ -28,38 +28,43 @@ $b is less than 20. PowerShell supports the following logical operators. -|Operator|Description|Example| -|---|---|---| -|`-and`|Logical and. TRUE only when both statements are TRUE.|`(1 -eq 1) -and (1 -eq 2)`
`False`| -|`-or`|Logical or. TRUE when either or both statements are TRUE.|`(1 -eq 1) -or (1 -eq 2)`
`True`| -|`-xor`|Logical exclusive or. TRUE only when one of the statements is TRUE and the other is FALSE.|`(1 -eq 1) -xor (2 -eq 2)`
`False`| -|`-not`|Logical not. Negates the statement that follows it.|`-not (1 -eq 1)`
`False`| -|`!`|Logical not. Negates the statement that follows it. (Same as -not)|`!(1 -eq 1)`
`False`| +|Operator|Description |Example | +|--------|-----------------------------------|--------------------------| +|`-and` |Logical AND. TRUE when both |`(1 -eq 1) -and (1 -eq 2)`| +| |statements are TRUE. |`False` | +|`-or` |Logical OR. TRUE when either |`(1 -eq 1) -or (1 -eq 2)` | +| |statement is TRUE. |`True` | +|`-xor` |Logical EXCLUSIVE OR. TRUE when |`(1 -eq 1) -xor (2 -eq 2) | +| |only one statement is TRUE |`False` | +|`-not` |Logical not. Negates the statement |`-not (1 -eq 1)` | +| |that follows. |`False` | +|`!` |Same as `-not` |`!(1 -eq 1)` | +| | |`False` | Note: - The previous examples also use the equal to comparison operator `-eq`. For - more information, see about_Comparison_Operators. The examples also use - the Boolean values of integers. The integer 0 has a value of FALSE. All - other integers have a value of TRUE. +The previous examples also use the equal to comparison operator `-eq`. For +more information, see +[about_Comparison_Operators](about_Comparison_Operators.md). The examples also +use the Boolean values of integers. The integer 0 has a value of FALSE. All +other integers have a value of TRUE. - The syntax of the logical operators is as follows: +The syntax of the logical operators is as follows: -```powershell +``` {-AND | -OR | -XOR} {! | -NOT} ``` - Statements that use the logical operators return Boolean (TRUE or FALSE) - values. +Statements that use the logical operators return Boolean (TRUE or FALSE) +values. - The PowerShell logical operators evaluate only the statements required to - determine the truth value of the statement. If the left operand in a - statement that contains the and operator is FALSE, the right operand is - not evaluated. If the left operand in a statement that contains the or - statement is TRUE, the right operand is not evaluated. As a result, you - can use these statements in the same way that you would use the If - statement. +The PowerShell logical operators evaluate only the statements required to +determine the truth value of the statement. If the left operand in a statement +that contains the and operator is FALSE, the right operand is not evaluated. +If the left operand in a statement that contains the or statement is TRUE, the +right operand is not evaluated. As a result, you can use these statements in +the same way that you would use the If statement. ## SEE ALSO diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md b/reference/6/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md new file mode 100644 index 000000000000..ea1e83939845 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Core/About/about_psconsolehostreadline.md @@ -0,0 +1,55 @@ +--- +ms.date: 2018-01-04 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: about_PSConsoleHostReadLine +--- + +# about_PSConsoleHostReadLine + +## SHORT DESCRIPTION + +Explains how to create a customize how PowerShell reads input at the console +prompt. + +## LONG DESCRIPTION + +Starting in Windows PowerShell V3, you can write a function named +PSConsoleHostReadLine that overrides the default way that console input is +processed. + +### EXAMPLES + +The following example launches Notepad and gets input from a text File that +the user creates: + +```powershell +function PSConsoleHostReadLine +{ + $inputFile = Join-Path $env:TEMP PSConsoleHostReadLine + Set-Content $inputFile "PS > " + + # Notepad opens. Enter your command in it, save the file, and then exit. + notepad $inputFile | Out-Null + $userInput = Get-Content $inputFile + $resultingCommand = $userInput.Replace("PS >", "") + $resultingCommand +} +``` + +### REMARKS + +By default, PowerShell reads input from the console in what is known as +"Cooked Mode" -- in which the Windows console subsystem handles all the +keypresses, F7 menus, and other input. When you press Enter or Tab, Windows +PowerShell gets the text that you have typed up to that point. There is no way +for it to know that you pressed Ctrl-R, Ctrl-A, Ctrl-E, or any other keys +before pressing Enter or Tab. In Windows PowerShell version 3, the +PSConsoleHostReadLine function solves this issue. When you define a function +named PSConsoleHostReadline in the Windows PowerShell console host, Windows +PowerShell calls that function instead of the "Cooked Mode" input mechanism. + +### SEE ALSO + +[about_Prompts](about_Prompts.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_psreadline.md b/reference/6/Microsoft.PowerShell.Core/About/about_psreadline.md new file mode 100644 index 000000000000..c21c0d7a2995 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Core/About/about_psreadline.md @@ -0,0 +1,674 @@ +--- +ms.date: 2018-01-04 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: about_PSReadline +--- + +# about_PSReadline + +## SHORT DESCRIPTION + +PSReadline provides an improved command line editing experience in the +PowerShell console. + +## LONG DESCRIPTION + +PSReadline, introduced in PowerShell 5.0, provides a powerful command line +editing experience for the PowerShell console. It provides: + +- Syntax coloring of the command line +- A visual indication of syntax errors +- A better multi-line experience (both editing and history) +- Customizable key bindings +- Cmd and Emacs modes +- Many configuration options +- Bash style completion (optional in Cmd mode, default in Emacs mode) +- Emacs yank/kill ring +- PowerShell token based "word" movement and kill + +The following functions are available in the class +[PSConsoleUtilities.PSConsoleReadLine]: + +## Cursor movement + +- EndOfLine (Cmd: Emacs: or ) + + If the input has multiple lines, move to the end of the current line, or if + already at the end of the line, move to the end of the input. If the input + has a single line, move to the end of the input. + +- BeginningOfLine (Cmd: Emacs: or ) + + If the input has multiple lines, move to the start of the current line, or + if already at the start of the line, move to the start of the input. If the + input has a single line, move to the start of the input. + +- NextLine (Cmd: unbound Emacs: unbound) + + Move the cursor to the next line if the input has multiple lines. + +- PreviousLine (Cmd: unbound Emacs: unbound) + + Move the cursor to the previous line if the input has multiple lines. + +- ForwardChar (Cmd: Emacs: or ) + + Move the cursor one character to the right. This might move the cursor to + the next line of multi-line input. + +- BackwardChar (Cmd: Emacs: or ) + + Move the cursor one character to the left. This might move the cursor to the + previous line of multi-line input. + +- ForwardWord (Cmd: unbound Emacs: ) + + Move the cursor forward to the end of the current word, or if between words, + to the end of the next word. You can set word delimiter characters with: + + ```powershell + Set-PSReadlineOption -WordDelimiters + ``` + +- NextWord (Cmd: Emacs: unbound) + + Move the cursor forward to the start of the next word. You can set word + delimiter characters with: + + ```powershell + Set-PSReadlineOption -WordDelimiters + ``` + +- BackwardWord (Cmd: Emacs: ) + + Move the cursor back to the start of the current word, or if between words, + the start of the previous word. You can set word delimiter characters with: + + ```powershell + Set-PSReadlineOption -WordDelimiters + ``` + +- ShellForwardWord (Cmd: unbound Emacs: unbound) + + Like ForwardWord except word boundaries are defined by PowerShell token + boundaries. + +- ShellNextWord (Cmd: unbound Emacs: unbound) + + Like NextWord except word boundaries are defined by PowerShell token + boundaries. + +- ShellBackwardWord (Cmd: unbound Emacs: unbound) + + Like BackwardWord except word boundaries are defined by PowerShell token + boundaries. + +- GotoBrace (Cmd: Emacs: unbound) + + Go to the matching parenthesis, curly brace, or square bracket. + +- AddLine (Cmd: Emacs: ) + + The continuation prompt is displayed on the next line and PSReadline waits + for keys to edit the current input. This is useful to enter multi-line input + as a single command even when a single line is complete input by itself. + +## Basic editing + +- CancelLine (Cmd: unbound Emacs: unbound) + + Cancel all editing to the line, leave the line of input on the screen but + return from PSReadline without executing the input. + +- RevertLine (Cmd: Emacs: ) + + Reverts all of the input since the last input was accepted and run. This is + equivalent to using the Undo command until there is nothing left to undo. + +- BackwardDeleteChar (Cmd: Emacs: or ) + + Delete the character before the cursor. + +- DeleteChar (Cmd: Emacs: ) + + Delete the character under the cursor. + +- DeleteCharOrExit (Cmd: unbound Emacs: ) + + Like DeleteChar, unless the line is empty, in which case exit the process. + +- AcceptLine (Cmd: Emacs: or ) + + Attempt to execute the current input. If the current input is incomplete + (for example, there is a missing closing parenthesis, bracket, or quote), + then the continuation prompt is displayed on the next line, and PSReadline + waits for keys to edit the current input. + +- AcceptAndGetNext (Cmd: unbound Emacs: ) + + Like AcceptLine, but after the line completes, start editing the next line + from history. + +- ValidateAndAcceptLine (Cmd: unbound Emacs: unbound) + + Like AcceptLine but performs additional validation including: + + * Checks for additional parse errors + * Validates that command names are all found + * If you are running PowerShell 4.0 or newer, validates the parameters and + arguments + + If there are any errors, the error message is displayed and not accepted nor + added to the history unless you either correct the command line or execute + AcceptLine or ValidateAndAcceptLine again while the error message is + displayed. + +- BackwardDeleteLine (Cmd: Emacs: unbound) + + Delete the text from the start of the input to the cursor. + +- ForwardDeleteLine (Cmd: Emacs: unbound) + + Delete the text from the cursor to the end of the input. + +- SelectBackwardChar (Cmd: Emacs: ) + + Adjust the current selection to include the previous character. + +- SelectForwardChar (Cmd: Emacs: ) + + Adjust the current selection to include the next character. + +- SelectBackwardWord (Cmd: Emacs: ) + + Adjust the current selection to include the previous word. + +- SelectForwardWord (Cmd: unbound Emacs: ) + + Adjust the current selection to include the next word using ForwardWord. + +- SelectNextWord (Cmd: Emacs: unbound) + + Adjust the current selection to include the next word using NextWord. + +- SelectShellForwardWord (Cmd: unbound Emacs: unbound) + + Adjust the current selection to include the next word using + ShellForwardWord. + +- SelectShellNextWord (Cmd: unbound Emacs: unbound) + + Adjust the current selection to include the next word using ShellNextWord. + +- SelectShellBackwardWord (Cmd: unbound Emacs: unbound) + + Adjust the current selection to include the previous word using + ShellBackwardWord. + +- SelectBackwardsLine (Cmd: Emacs: ) + + Adjust the current selection to include from the cursor to the start of the + line. + +- SelectLine (Cmd: Emacs: ) + + Adjust the current selection to include from the cursor to the end of the + line. + +- SelectAll (Cmd: Emacs: unbound) + + Select the entire line. Moves the cursor to the end of the line. + +- SelfInsert (Cmd: , , ... Emacs: , , ...) + + Insert the key entered. + +- Redo (Cmd: Emacs: unbound) + + Redo an insertion or deletion that was undone by Undo. + +- Undo (Cmd: Emacs: ) + + Undo a previous insertion or deletion. + +## History + +- ClearHistory (Cmd: Alt+F7 Emacs: unbound) + + Clears history in PSReadline. This does not affect PowerShell + history. + +- PreviousHistory (Cmd: Emacs: or ) + + Replace the current input with the previous item from PSReadline history. + +- NextHistory (Cmd: Emacs: or ) + + Replace the current input with the next item from PSReadline history. + +- ForwardSearchHistory (Cmd: Emacs: ) + + Search forward from the current history line interactively. + +- ReverseSearchHistory (Cmd: Emacs: ) + + Search backward from the current history line interactively. + +- HistorySearchBackward (Cmd: Emacs: unbound) + + Replace the current input with the previous item from PSReadline history + that matches the characters between the start and the input and the cursor. + +- HistorySearchForward (Cmd: Emacs: unbound) + + Replace the current input with the next item from PSReadline history that + matches the characters between the start and the input and the cursor. + +- BeginningOfHistory (Cmd: unbound Emacs: ) + + Replace the current input with the last item from PSReadline history. + +- EndOfHistory (Cmd: unbound Emacs: >) + + Replace the current input with the last item in PSReadline history, which is + the possibly empty input that was entered before any history commands. + +## Tab Completion + +- TabCompleteNext (Cmd: Emacs: unbound) + + Attempt to complete the text surrounding the cursor with the next + available completion. + +- TabCompletePrevious (Cmd: Emacs: unbound) + + Attempt to complete the text surrounding the cursor with the next + previous completion. + +- Complete (Cmd: unbound Emacs: ) + + Attempt to perform completion on the text surrounding the cursor. If there + are multiple possible completions, the longest unambiguous prefix is used + for completion. If you are trying to complete the longest unambiguous + completion, a list of possible completions is displayed. + +- MenuComplete (Cmd: Emacs: ) + + Attempt to perform completion on the text surrounding the cursor. If there + are multiple possible completions, a list of possible completions is + displayed, and you can select the correct completion by using the arrow + keys, or Tab/Shift+Tab. Escape and Ctrl+G cancel the menu selection, and + revert the line to the state before invoking MenuComplete. + +- PossibleCompletions (Cmd: unbound Emacs: ) + + Display the list of possible completions. + +- SetMark (Cmd: unbound Emacs: ) + + Mark the current location of the cursor for use in a subsequent editing + command. + +- ExchangePointAndMark (Cmd: unbound Emacs: ) + + The cursor is placed at the location of the mark and the mark is moved + to the location of the cursor. + +## Kill/Yank + +Kill and Yank operate on a clipboard in the PSReadline module. There is a ring +buffer called the kill ring - killed text is added to the kill ring up and +yank will copy text from the most recent kill. YankPop cycles through items in +the kill ring. When the kill ring is full, new items replace the oldest items. +A kill operation that is immediately preceded by another kill operation +appends the previous kill, instead of adding a new item or replacing an item +in the kill ring. This is how you can cut a part of a line, for example, with +multiple KillWord operations, then yank them back elsewhere as a single yank. + +- KillLine (Cmd: unbound Emacs: ) + + Clear the input from the cursor to the end of the line. The cleared text is + placed in the kill ring. + +- BackwardKillLine (Cmd: unbound Emacs: or ) + + Clear the input from the start of the input to the cursor. The cleared text + is placed in the kill ring. + +- KillWord (Cmd: unbound Emacs: ) + + Clear the input from the cursor to the end of the current word. If the + cursor is between words, the input is cleared from the cursor to the end of + the next word. The cleared text is placed in the kill ring. + +- BackwardKillWord (Cmd: unbound Emacs: ) + + Clear the input from the start of the current word to the cursor. If the + cursor is between words, the input is cleared from the start of the previous + word to the cursor. The cleared text is placed in the kill ring. + +- ShellKillWord (Cmd: unbound Emacs: unbound) + + Like KillWord, except word boundaries are defined by PowerShell + token boundaries. + +- ShellBackwardKillWord (Cmd: unbound Emacs: unbound) + + Like BackwardKillWord, except word boundaries are defined by PowerShell + token boundaries. + +- UnixWordRubout (Cmd: unbound Emacs: ) + + Like BackwardKillWord, except word boundaries are defined by white space. + +- KillRegion (Cmd: unbound Emacs: unbound) + + Kill the text between the cursor and the mark. + +- Copy (Cmd: Emacs: unbound) + + Copy selected region to the system clipboard. If no region is selected, copy + the whole line. + +- CopyOrCancelLine (Cmd: Emacs: ) + + Either copy selected text to the clipboard, or if no text is selected, + cancel editing the line with CancelLine. + +- Cut (Cmd: Emacs: unbound) + + Delete selected region placing deleted text in the system clipboard. + +- Yank (Cmd: unbound Emacs: ) + + Add the most-recently killed text to the input. + +- YankPop (Cmd: unbound Emacs: ) + + If the previous operation was Yank or YankPop, replace the previously-yanked + text with the next killed text from the kill ring. + +- ClearKillRing (Cmd: unbound Emacs: unbound) + + The contents of the kill ring are cleared. + +- Paste (Cmd: Emacs: unbound) + + This is similar to Yank, but uses the system clipboard instead of the kill + ring. + +- YankLastArg (Cmd: Emacs: , ) + + Insert the last argument from the previous command in history. Repeated + operations replace the last inserted argument with the last argument from + the previous command (so Alt+. Alt+. will insert the last argument of the + second to last history line). + + With an argument, the first time YankLastArg behaves like YankNthArg. A + negative argument on subsequent YankLastArg calls changes the direction + while going through history. For example, if you press Alt+. one too many + times, you can type Alt+- Alt+. to reverse the direction. + + Arguments are based on PowerShell tokens. + +- YankNthArg (Cmd: unbound Emacs: ) + + Insert the first argument (not the command name) of the previous command in + history. + + With an argument, insert the nth argument where 0 is typically the command. + Negative arguments start from the end. + + Arguments are based on PowerShell tokens. + +## Miscellaneous + +- Abort (Cmd: unbound Emacs: ) + + Abort the current action; for example, stop interactive history search. Does + not cancel input like CancelLine. + +- CharacterSearch (Cmd: Emacs: ) + + Read a key and search forwards for that character. With an argument, search + forwards for the nth occurrence of that argument. With a negative argument, + searches backwards. + +- CharacterSearchBackward (Cmd: Emacs: ) + + Like CharacterSearch, but searches backwards. With a negative argument, + searches forwards. + +- ClearScreen (Cmd: Emacs: ) + + Clears the screen and displays the current prompt and input at the top of + the screen. + +- DigitArgument (Cmd: unbound Emacs: ,,) + + Used to pass numeric arguments to functions like CharacterSearch or + YankNthArg. Alt+- toggles the argument to be negative/non-negative. To enter + 80 '*' characters, you could type Alt+8 Alt+0 *. + +- CaptureScreen (Cmd: unbound Emacs: unbound) + + Copies selected lines to the clipboard in both text and RTF formats. Use + up/down arrow keys to the first line to select, then + Shift+UpArrow/Shift+DownArrow to select multiple lines. After selecting, + press Enter to copy the text. Escape/Ctrl+C/Ctrl+G cancel the operation, so + nothing is copied to the clipboard. + +- InvokePrompt (Cmd: unbound Emacs: unbound) + + Erases the current prompt and calls the prompt function to redisplay the + prompt. Useful for custom key handlers that change state, such as changing + the current directory. + +- WhatIsKey (Cmd: Emacs: ) + + Read a key or chord and display the key binding. + +- ShowKeyBindings (Cmd: Emacs: ) + + Show all of the currently-bound keys. + +- ScrollDisplayUp (Cmd: Emacs: ) + + Scroll the display up one screen. + +- ScrollDisplayUpLine (Cmd: Emacs: ) + + Scroll the display up one line. + +- ScrollDisplayDown (Cmd: Emacs: ) + + Scroll the display down one screen. + +- ScrollDisplayDownLine (Cmd: Emacs: ) + + Scroll the display down one line. + +- ScrollDisplayTop (Cmd: unbound Emacs: ) + + Scroll the display to the top. + +- ScrollDisplayToCursor (Cmd: unbound Emacs: ) + + Scroll the display to the cursor. + +## Custom Key Bindings + +PSReadline supports custom key bindings using the cmdlet +Set-PSReadlineKeyHandler. Most custom key bindings call one of the above +functions, for example: + +```powershell +Set-PSReadlineKeyHandler -Key UpArrow -Function HistorySearchBackward +``` + +You can bind a ScriptBlock to a key. The ScriptBlock can do virtually anything +you want. Some useful examples include: + +* edit the command line +* opening a new window (e.g. help) +* change directories without changing the command line + +The ScriptBlock is passed two arguments: + +* $key - A [ConsoleKeyInfo] that is the key that triggered the custom binding. + If you bind the same ScriptBlock to multiple keys and need to perform + different actions depending on the key, you can check $key. Many custom + bindings ignore this argument. +* $arg - An arbitrary argument. Most often, this would be an integer argument + that the user passes from the key bindings DigitArgument. If your binding + doesn't accept arguments, it's reasonable to ignore this argument. + +Let's take a look at an example that adds a command line to history without +executing it. This is useful when you realize you forgot to do something, but +don't want to re-enter the command line you've already entered. + +```powershell +Set-PSReadlineKeyHandler -Key Alt+w ` + -BriefDescription SaveInHistory ` + -LongDescription "Save current line in history but do not execute" ` + -ScriptBlock { + param($key, $arg) # The arguments are ignored in this example + + # GetBufferState gives us the command line (with the cursor position) + $line = $null + $cursor = $null + [PSConsoleUtilities.PSConsoleReadLine]::GetBufferState([ref]$line, + [ref]$cursor) + + # AddToHistory saves the line in history, but does not execute the line. + [PSConsoleUtilities.PSConsoleReadLine]::AddToHistory($line) + + # RevertLine is like pressing Escape. + [PSConsoleUtilities.PSConsoleReadLine]::RevertLine() +} +``` + +You can see many more examples in the file SamplePSReadlineProfile.ps1 which +is installed in the PSReadline module folder. + +Most key bindings will want to take advantage of some helper functions for +editing the command line those APIs are documented in the next section. + +## Custom Key Binding Support APIs + +The following functions are public in PSConsoleUtilities.PSConsoleReadline, +but cannot be directly bound to a key. Most are useful in custom key bindings. + +- void AddToHistory(string command) + + Add a command line to history without executing it. + +- void ClearKillRing() + + Clear the kill ring. This is mostly used for testing. + +- void Delete(int start, int length) + + Delete length characters from start. This operation supports undo and redo. + +void Ding() + + Perform the Ding action based on the user’s preference. + +- void GetBufferState([ref] string input, [ref] int cursor) +- void GetBufferState([ref] Ast ast, [ref] Token[] tokens, [ref] ParseError[] + parseErrors, [ref] int cursor) + + These two functions retrieve useful information about the current state of + the input buffer. The first is more commonly used for simple cases. The + second is used if your binding is doing something more advanced with the + Ast. + +- IEnumerable[PSConsoleUtilities.KeyHandler] GetKeyHandlers(bool includeBound, + bool includeUnbound) + + This function is used by Get-PSReadlineKeyHandler and probably isn't useful + in a custom key binding. + +- PSConsoleUtilities.PSConsoleReadlineOptions GetOptions() + + This function is used by Get-PSReadlineOption and probably isn't too useful + in a custom key binding. + +- void GetSelectionState([ref] int start, [ref] int length) + + If there is no selection on the command line, -1 is returned in both start + and length. If there is a selection on the command line, the start and + length of the selection are returned. + +- void Insert(char c) +- void Insert(string s) + + Insert a character or string at the cursor. This operation supports undo and + redo. + +- string ReadLine(runspace remoteRunspace, + System.Management.Automation.EngineIntrinsics engineIntrinsics) + + This is the main entry point to PSReadline. It does not support recursion, + so is not useful in a custom key binding. + +- void RemoveKeyHandler(string[] key) + + This function is used by Remove-PSReadlineKeyHandler and probably isn't too + useful in a custom key binding. + +- void Replace(int start, int length, string replacement) + + Replace some of the input. This operation supports undo and redo. This is + preferred over Delete followed by Insert because it is treated as a single + action for undo. + +- void SetCursorPosition(int cursor) + + Move the cursor to the given offset. Cursor movement is not tracked for + undo. + +- void SetOptions(PSConsoleUtilities.SetPSReadlineOption options) + + This function is a helper method used by the cmdlet Set-PSReadlineOption, + but might be useful to a custom key binding that wants to temporarily change + a setting. + +- bool TryGetArgAsInt(System.Object arg, [ref] int numericArg, + int defaultNumericArg) + + This helper method is used for custom bindings that honor DigitArgument. A + typical call looks like: + + ```powershell + [int]$numericArg = 0 + [PSConsoleUtilities.PSConsoleReadLine]::TryGetArgAsInt($arg, + [ref]$numericArg, 1) + ``` +## POWERSHELL COMPATIBILITY + +PSReadline requires PowerShell 3.0 or newer, and the console host. It +does not work in PowerShell ISE. + +## FEEDBACK AND CONTRIBUTING TO PSREADLINE + +Feel free to submit a pull request or submit feedback on the PSReadline +GitHub page (https://github.com/lzybkr/PSReadLine). + +## SEE ALSO + +PSReadline is heavily influenced by the GNU Readline library: +http://tiswww.case.edu/php/chet/readline/rltop.html + +[Get-PSReadlineKeyHandler](../../PSReadline/Get-PSReadlineKeyHandler.md) + +[Get-PSReadlineOption](../../PSReadline/Get-PSReadlineOption.md) + +[Remove-PSReadlineKeyHandler](../../PSReadline/Remove-PSReadlineKeyHandler.md) + +[Set-PSReadlineKeyHandler](../../PSReadline/Set-PSReadlineKeyHandler.md) + +[Set-PSReadlineOption](../../PSReadline/Set-PSReadlineOption.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_pwsh.md b/reference/6/Microsoft.PowerShell.Core/About/about_pwsh.md index 593cc726bc25..1e766879d561 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_pwsh.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_pwsh.md @@ -7,20 +7,19 @@ title: about_PowerShell_exe --- # About pwsh -## about_pwsh +## SHORT DESCRIPTION -# SHORT DESCRIPTION - -Explains how to use the pwsh command-line tool. Displays -the syntax and describes the command-line switches. +Explains how to use the pwsh command-line tool. Displays the syntax and +describes the command-line switches. pwsh starts a PowerShell session. -# LONG DESCRIPTION +## LONG DESCRIPTION -# SYNTAX +## SYNTAX +``` pwsh[.exe] [-Version] [-EncodedCommand ] @@ -36,109 +35,116 @@ pwsh[.exe] [-Command { - | [-args ] | [] } ] pwsh[.exe] -Help | -? | /? +``` + +### PARAMETERS + +#### -Version + +Displays the version of PowerShell. Additional parameters are ignored. + +#### -EncodedCommand + +Accepts a base-64-encoded string version of a command. Use this parameter to +submit commands to PowerShell that require complex quotation marks or curly +braces. + +#### -ExecutionPolicy + +Sets the default execution policy for the current session and saves it in the +$env:PSExecutionPolicyPreference environment variable. This parameter does not +change the PowerShell execution policy that is set in the registry. + +#### -File [] + +Runs the specified script in the local scope ("dot-sourced"), so that the +functions and variables that the script creates are available in the current +session. Enter the script file path and any parameters. File must be the last +parameter in the command, because all characters typed after the File +parameter name are interpreted as the script file path followed by the script +parameters. + +You can include the parameters of a script, and parameter values, in the value +of the File parameter. For example: -File .\\Get-Script.ps1 -Domain Central + +Typically, the switch parameters of a script are either included or omitted. +For example, the following command uses the All parameter of the +Get-Script.ps1 script file: -File .\\Get-Script.ps1 -All + +In rare cases, you might need to provide a Boolean value for a switch +parameter. To provide a Boolean value for a switch parameter in the value of +the File parameter, enclose the parameter name and value in curly braces, such +as the following: -File .\\Get-Script.ps1 {-All:$False}. + +#### -InputFormat {Text | XML} + +Describes the format of data sent to PowerShell. Valid values are "Text" (text +strings) or "XML" (serialized CLIXML format). + +#### -NoExit -# PARAMETERS - --Version -Displays the version of PowerShell. Additional parameters -are ignored. - --EncodedCommand -Accepts a base-64-encoded string version of a command. -Use this parameter to submit commands to PowerShell -that require complex quotation marks or curly braces. - --ExecutionPolicy -Sets the default execution policy for the current session -and saves it in the $env:PSExecutionPolicyPreference environment -variable. This parameter does not change the PowerShell -execution policy that is set in the registry. - --File [] -Runs the specified script in the local scope ("dot-sourced"), -so that the functions and variables that the script creates -are available in the current session. Enter the script file -path and any parameters. File must be the last parameter in -the command, because all characters typed after the File -parameter name are interpreted as the script file path followed -by the script parameters. - -You can include the parameters of a script, and parameter -values, in the value of the File parameter. For example: --File .\Get-Script.ps1 -Domain Central - -Typically, the switch parameters of a script are either -included or omitted. For example, the following command -uses the All parameter of the Get-Script.ps1 script file: --File .\Get-Script.ps1 -All - -In rare cases, you might need to provide a Boolean value -for a switch parameter. To provide a Boolean value for a -switch parameter in the value of the File parameter, -enclose the parameter name and value in curly braces, -such as the following: --File .\Get-Script.ps1 {-All:$False}. - --InputFormat {Text | XML} -Describes the format of data sent to PowerShell. Valid -values are "Text" (text strings) or "XML" (serialized CLIXML format). - --NoExit Does not exit after running startup commands. --NoLogo +#### -NoLogo + Hides the copyright banner at startup. --NonInteractive +#### -NonInteractive + Does not present an interactive prompt to the user. --NoProfile +#### -NoProfile + Does not load the PowerShell profile. --OutputFormat {Text | XML} -Determines how output from PowerShell is formatted. -Valid values are "Text" (text strings) or "XML" (serialized -CLIXML format). +#### -OutputFormat {Text | XML} + +Determines how output from PowerShell is formatted. Valid values are "Text" +(text strings) or "XML" (serialized CLIXML format). --WindowStyle -Sets the window style for the session. Valid values are Normal, -Minimized, Maximized and Hidden. +#### -WindowStyle --Command -Executes the specified commands (and any parameters) as though -they were typed at the PowerShell command prompt, and -then exits, unless the NoExit parameter is specified. +Sets the window style for the session. Valid values are Normal, Minimized, +Maximized and Hidden. -The value of Command can be "-", a string. or a script block. If -the value of Command is "-", the command text is read from standard -input. +#### -Command -Script blocks must be enclosed in braces ({}). You can specify a -script block only when running pwsh in PowerShell. -The results of the script are returned to the parent shell as -deserialized XML objects, not live objects. +Executes the specified commands (and any parameters) as though they were typed +at the PowerShell command prompt, and then exits, unless the NoExit parameter +is specified. -If the value of Command is a string, Command must be the last -parameter in the command , because any characters typed after -the command are interpreted as the command arguments. +The value of Command can be "-", a string. or a script block. If the value of +Command is "-", the command text is read from standard input. -To write a string that runs a PowerShell command, use the -format: +Script blocks must be enclosed in braces ({}). You can specify a script block +only when running pwsh in PowerShell. The results of the script are returned +to the parent shell as deserialized XML objects, not live objects. + +If the value of Command is a string, Command must be the last parameter in the +command , because any characters typed after the command are interpreted as +the command arguments. + +To write a string that runs a PowerShell command, use the format: + +``` "& {}" -where the quotation marks indicate a string and the invoke operator -(&) causes the command to be executed. +``` --Help, -?, /? -Displays help for pwsh. If you are typing a pwsh -command in PowerShell, prepend the command parameters with a -hyphen (-), not a forward slash (/). You can use either a hyphen or -forward slash in Cmd.exe. +where the quotation marks indicate a string and the invoke operator (&) causes +the command to be executed. -# EXAMPLES +#### -Help, -?, /? +Displays help for pwsh. If you are typing a pwsh command in PowerShell, +prepend the command parameters with a hyphen (-), not a forward slash (/). You +can use either a hyphen or forward slash in Cmd.exe. + +## EXAMPLES + +```powershell pwsh -Version pwsh -Command {Get-Command -Name Get-Command} pwsh -Command "& {Get-Command -Name Get-Command}" - +``` From 6c3422014641bd472c18e9102fac2a7b2d39468c Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 4 Jan 2018 16:22:40 -0800 Subject: [PATCH 156/188] final pass on About_ topic reformat (#2011) --- .../About/about_Environment_Variables.md | 8 +- .../About/about_For.md | 2 +- .../About/about_Functions_Advanced_Methods.md | 3 +- .../About/about_Language_Keywords.md | 2 +- .../About/about_Modules.md | 5 - .../About/about_Parameters.md | 4 +- .../About/about_Switch.md | 14 +- .../About/about_WS-Management_Cmdlets.md | 196 +++++++++++++ .../About/about_Wildcards.md | 4 +- .../About/about_Environment_Variables.md | 8 +- .../About/about_For.md | 2 +- .../About/about_Functions_Advanced_Methods.md | 3 +- .../About/about_Modules.md | 1 - .../About/about_Parameters.md | 2 +- .../About/about_Switch.md | 14 +- .../About/about_WS-Management_Cmdlets.md | 196 +++++++++++++ .../About/about_Wildcards.md | 4 +- .../About/about_Windows_RT.md | 1 - .../About/about_desiredstateconfiguration.md | 172 +++++++++++ .../About/about_dsclogresource.md | 18 ++ .../About/about_Environment_Variables.md | 8 +- .../About/about_Functions_Advanced_Methods.md | 3 +- .../About/about_Modules.md | 3 +- .../About/about_Providers.md | 269 ++++++++++-------- .../About/about_Switch.md | 14 +- .../About/about_WS-Management_Cmdlets.md | 196 +++++++++++++ .../About/about_Wildcards.md | 4 +- .../About/about_packagemanagement.md | 2 +- .../About/about_Environment_Variables.md | 8 +- .../About/about_Functions_Advanced_Methods.md | 3 +- .../About/about_Modules.md | 6 +- .../About/about_WS-Management_Cmdlets.md | 196 +++++++++++++ .../About/about_Wildcards.md | 4 +- .../About/about_Modules.md | 7 +- 34 files changed, 1198 insertions(+), 184 deletions(-) create mode 100644 reference/3.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md create mode 100644 reference/4.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md create mode 100644 reference/4.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md create mode 100644 reference/4.0/Microsoft.PowerShell.Core/About/about_dsclogresource.md create mode 100644 reference/5.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md create mode 100644 reference/5.1/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index b79253e0522b..700cb3bc71ca 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -244,11 +244,11 @@ The environment variables that store preferences include: The default value of $Env:PSModulePath is: ``` - $home\Documents\WindowsPowerShell\Modules; $pshome\Modules + $HOME\Documents\WindowsPowerShell\Modules; $PSHOME\Modules ``` -Windows PowerShell sets the value of "\$pshome\\Modules" in the registry. It -sets the value of "\$home\\Documents\\WindowsPowerShell\\Modules" each time you +Windows PowerShell sets the value of "\$PSHOME\\Modules" in the registry. It +sets the value of "\$HOME\\Documents\\WindowsPowerShell\\Modules" each time you start Windows PowerShell. In addition, setup programs that install modules in other directories, such as @@ -294,7 +294,7 @@ $path = [System.Environment]::GetEnvironmentVariable("PSModulePath", ``` For more information about the methods of the System.Environment class, see -[Environment Methods](http://go.microsoft.com/fwlink/?LinkId=242783) in +[Environment Methods](https://go.microsoft.com/fwlink/?LinkId=242783) in MSDN. You can add also add a command that changes the value to your profile or use diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_For.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_For.md index c8343e7483e3..5c8f723bb156 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_For.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_For.md @@ -25,7 +25,7 @@ all the values in an array, consider using a Foreach statement. The following shows the For statement syntax. ```powershell -for (>init>; ; ) +for (; ; ) {} ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md index fbcfc30ca802..9dd552a11e64 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md @@ -27,8 +27,7 @@ the following methods: All the methods and properties of the `PSCmdlet` class are available to advanced functions. For more information about these methods and properties, -see `System.Management.Automation.PSCmdlet` in the MSDN (Microsoft Developer -Network) library at http://go.microsoft.com/fwlink/?LinkId=142139. +see [`System.Management.Automation.PSCmdlet`](http://go.microsoft.com/fwlink/?LinkId=142139) in the MSDN library. ### Input Processing Methods diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Language_Keywords.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Language_Keywords.md index fe74da621193..accfd3af1967 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Language_Keywords.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Language_Keywords.md @@ -516,7 +516,7 @@ Syntax: do {} while () ``` -# SEE ALSO +## SEE ALSO - [about_Special_Characters](about_Special_Characters.md) - [about_Wildcards](about_Wildcards.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Modules.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Modules.md index 931280614067..95de124ea62f 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Modules.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Modules.md @@ -486,18 +486,13 @@ NOTE: Remote sessions, including sessions that are started by using the commands are packaged in snap-ins. The following modules (or snap-ins) are installed with PowerShell. -* Microsoft.PowerShell.Archive * Microsoft.PowerShell.Core * Microsoft.PowerShell.Diagnostics * Microsoft.PowerShell.Host * Microsoft.PowerShell.Management -* Microsoft.PowerShell.ODataUtils * Microsoft.PowerShell.Security * Microsoft.PowerShell.Utility * Microsoft.WSMan.Management -* OneGet -* PowerShellGet -* PSDesiredStateConfiguration * PSScheduledJob * PSWorkflow * PSWorkflowUtility diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md index 63ac66fd659e..b74b7e5b0cb0 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -10,11 +10,11 @@ title: about_Parameters ## SHORT DESCRIPTION -Describes how to work with command parameters in Windows PowerShell®. +Describes how to work with command parameters in PowerShell. ## LONG DESCRIPTION -Most Windows PowerShell commands, such as cmdlets, functions, and scripts, +Most PowerShell commands, such as cmdlets, functions, and scripts, rely on parameters to allow users to select options or provide input. The parameters follow the command name and have the following form: diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Switch.md index 1bfafbe78470..cf7500531b40 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2017-12-06 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -167,9 +167,9 @@ Switch has the following parameters: | |condition. Wildcard and Exact are ignored. Also, if the | | |match clause is not a string, this parameter is ignored. | +In this example, there is no matching case so there is no output. ```powershell -Example: PS> switch ("fourteen") { 1 {"It is one."; Break} @@ -179,7 +179,12 @@ Example: 3 {"Three again."; Break} "fo*" {"That's too many."} } +``` + +For the word "fourteen" to match a case you must use the **-Wildcard** or +**-Regex** parameter. +```powershell PS> switch -Regex ("fourteen") { 1 {"It is one."; Break} @@ -189,6 +194,11 @@ Example: 3 {"Three again."; Break} "fo*" {"That's too many."} } + ``` + + Result: + + ```Output That's too many. ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md new file mode 100644 index 000000000000..1b6877370de4 --- /dev/null +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md @@ -0,0 +1,196 @@ +--- +ms.date: 2018-01-04 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: about_WS Management_Cmdlets +--- + +# About WS-Management Cmdlets + +## SHORT DESCRIPTION + +Provides an overview of Web Services for Management (WS-Management) as +background for using the WS-Management cmdlets in Windows PowerShell. + +## LONG DESCRIPTION + +This topic provides an overview of Web Services for Management (WS-Management) +as background for using the WS-Management cmdlets in Windows PowerShell. This +topic also provides links to more information about WS-Management. The +Microsoft implementation of WS-Management is also known as Windows Remote +Management (WinRM). + +### About WS-Management + +Windows Remote Management is the Microsoft implementation of the WS-Management +protocol, a standard SOAP-based, firewall-friendly protocol that allows +hardware and operating systems from different vendors to interoperate. The +WS-Management protocol specification provides a common way for systems to +access and exchange management information across an information technology +(IT) infrastructure. WS-Management and Intelligent Platform Management +Interface (IPMI), along with the Event Collector, are components of the +Windows Hardware Management features. + +The WS-Management protocol is based on the following standard Web service +specifications: HTTPS, SOAP over HTTP (WS-I profile), SOAP 1.2, WS-Addressing, +WS-Transfer, WS-Enumeration, and WS-Eventing. + +### WS-Management and WMI + +WS-Management can be used to retrieve data exposed by Windows Management +Instrumentation (WMI). You can obtain WMI data with scripts or applications +that use the WS-Management Scripting API or through the WinRM command-line +tool. WS-Management supports most of the familiar WMI classes and operations, +including embedded objects. WS-Management can leverage WMI to collect data +about resources or to manage resources on a Windows-based computers. That +means that you can obtain data about objects such as disks, network adapters, +services, or processes in your enterprise through the existing set of WMI +classes. You can also access the hardware data that is available from the +standard WMI IPMI provider. + +### WS-Management Windows PowerShell Provider (WSMan) + +The WSMan provider provides a hierarchical view into the available +WS-Management configuration settings. The provider allows you to explore and +set the various WS-Management configuration options. + +### WS-Management Configuration + +If WS-Management is not installed and configured, Windows PowerShell remoting +is not available, the WS-Management cmdlets do not run, WS-Management scripts +do not run, and the WSMan provider cannot perform data operations. The +WS-Management command-line tool, WinRM, and event forwarding also depend on +the WS-Management configuration. + +### WS-Management Cmdlets + +WS-Management functionality is implemented in Windows PowerShell through a +module that contains a set of cmdlets and the WSMan provider. You can use +these cmdlets to complete the end-to-end tasks necessary to manage +WS-Management settings on local and remote computers. + +The following WS-Management cmdlets are available. + +### Connection Cmdlets + +- Connect-WSMan: Connects the local computer to the WS-Management (WinRM) + service on a remote computer. + +- Disconnect-WSMan: Disconnects the local computer from the WS-Management + (WinRM) service on a remote computer. + +### Management-Data Cmdlets + +- Get-WSManInstance: Displays management information for a resource instance + that is specified by a resource URI. + +- Invoke-WSManAction: Invokes an action on the target object that is specified + by the resource URI and by the selectors. + +- New-WSManInstance: Creates a new management resource instance. + +- Remove-WSManInstance: Deletes a management resource instance. + +- Set-WSManInstance: Modifies the management information that is related to a + resource. + +### Setup and Configuration Cmdlets + +- Set-WSManQuickConfig: Configures the local computer for remote management. + You can use the Set-WSManQuickConfig cmdlet to configure WS-Management to + allow remote connections to the WS-Management (WinRM) service. The + Set-WSManQuickConfig cmdlet performs the following operations: + - It determines whether the WS-Management (WinRM) service is running. If the + WinRM service is not running, the Set-WSManQuickConfig cmdlet starts the + service. + - It sets the WS-Management (WinRM) service startup type to automatic. + - It creates a listener that accepts requests from any IP address. The + default transport protocol is HTTP. + - It enables a firewall exception for WS-Management traffic. + + Note: To run this cmdlet in Windows Vista, Windows Server 2008, and later + versions of Windows, you must start Windows PowerShell with the "Run as + administrator" option. + +- Test-WSMan: Verifies that WS-Management is installed and configured. The + Test-WSMan cmdlet tests whether the WS-Management (WinRM) service is running + and configured on a local or remote computer. + +- Disable-WSManCredSSP: Disables CredSSP authentication on a client computer. + +- Enable-WSManCredSSP: Enables CredSSP authentication on a client computer. + +- Get-WSManCredSSP: Gets the CredSSP-related configuration for a client + computer. + +### WS-Management-Specific Cmdlets + +- New-WSManSessionOption: Creates a WSManSessionOption object to use as input + to one or more parameters of a WS-Management cmdlet. + +### Additional WS-Management Information + +For more information about WS-Management, see the following topics in the +MSDN (Microsoft Developer Network) library. + +"Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142321 + +"About Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142322 + +"Installation and Configuration for Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142323 + +"Windows Remote Management Architecture" +http://go.microsoft.com/fwlink/?LinkId=142324 + +"WS-Management Protocol" +http://go.microsoft.com/fwlink/?LinkId=142325 + +"Windows Remote Management and WMI" +http://go.microsoft.com/fwlink/?LinkId=142326 + +"Resource URIs" +http://go.microsoft.com/fwlink/?LinkId=142327 + +"Remote Hardware Management" +http://go.microsoft.com/fwlink/?LinkId=142328 + +"Events" +http://go.microsoft.com/fwlink/?LinkId=142329 + +## SEE ALSO + +[Connect-WSMan](../../Microsoft.WSMan.Management/Connect-WSMan.md) + +[Disable-WSManCredSSP](../../Microsoft.WSMan.Management/Disable-WSManCredSSP.md) + +[Disconnect-WSMan](../../Microsoft.WSMan.Management/Disconnect-WSMan.md) + +[Enable-WSManCredSSP](../../Microsoft.WSMan.Management/Enable-WSManCredSSP.md) + +[Get-WSManCredSSP](../../Microsoft.WSMan.Management/Get-WSManCredSSP.md) + +[Get-WSManInstance](../../Microsoft.WSMan.Management/Get-WSManInstance.md) + +[Invoke-WSManAction](../../Microsoft.WSMan.Management/Invoke-WSManAction.md) + +[New-WSManInstance](../../Microsoft.WSMan.Management/New-WSManInstance.md) + +[Remove-WSManInstance](../../Microsoft.WSMan.Management/Remove-WSManInstance.md) + +[Set-WSManInstance](../../Microsoft.WSMan.Management/Set-WSManInstance.md) + +[Set-WSManQuickConfig](../../Microsoft.WSMan.Management/Set-WSManQuickConfig.md) + +[Set-WSManSessionOption](../../Microsoft.WSMan.Management/Set-WSManSessionOption.md) + +[Test-WSMan](../../Microsoft.WSMan.Management/Test-WSMan.md) + +# KEYWORDS + +about_WSMAN + +about_WinRM diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Wildcards.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Wildcards.md index 3acd265596c5..ff5ff8afcfd2 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Wildcards.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Wildcards.md @@ -60,7 +60,7 @@ following command gets services in which the ServiceType property value includes "Interactive". ```powershell -Get-Service | Where-Object {$_.ServiceType -like "Interactive"} +Get-Service | Where-Object {$_.ServiceType -like "*Interactive*"} ``` In the following example, wildcard characters are used to find property @@ -71,7 +71,7 @@ value of the CreationTime property of the restore point to a log file. ```powershell $p = Get-ComputerRestorePoint foreach ($point in $p) { - if ($point.description -like "PowerShell") { + if ($point.description -like "*PowerShell*") { add-content -path C:\TechDocs\RestoreLog.txt "$($point.CreationTime)" } } diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index b79253e0522b..700cb3bc71ca 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -244,11 +244,11 @@ The environment variables that store preferences include: The default value of $Env:PSModulePath is: ``` - $home\Documents\WindowsPowerShell\Modules; $pshome\Modules + $HOME\Documents\WindowsPowerShell\Modules; $PSHOME\Modules ``` -Windows PowerShell sets the value of "\$pshome\\Modules" in the registry. It -sets the value of "\$home\\Documents\\WindowsPowerShell\\Modules" each time you +Windows PowerShell sets the value of "\$PSHOME\\Modules" in the registry. It +sets the value of "\$HOME\\Documents\\WindowsPowerShell\\Modules" each time you start Windows PowerShell. In addition, setup programs that install modules in other directories, such as @@ -294,7 +294,7 @@ $path = [System.Environment]::GetEnvironmentVariable("PSModulePath", ``` For more information about the methods of the System.Environment class, see -[Environment Methods](http://go.microsoft.com/fwlink/?LinkId=242783) in +[Environment Methods](https://go.microsoft.com/fwlink/?LinkId=242783) in MSDN. You can add also add a command that changes the value to your profile or use diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_For.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_For.md index c8343e7483e3..5c8f723bb156 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_For.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_For.md @@ -25,7 +25,7 @@ all the values in an array, consider using a Foreach statement. The following shows the For statement syntax. ```powershell -for (>init>; ; ) +for (; ; ) {} ``` diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md index fbcfc30ca802..9dd552a11e64 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md @@ -27,8 +27,7 @@ the following methods: All the methods and properties of the `PSCmdlet` class are available to advanced functions. For more information about these methods and properties, -see `System.Management.Automation.PSCmdlet` in the MSDN (Microsoft Developer -Network) library at http://go.microsoft.com/fwlink/?LinkId=142139. +see [`System.Management.Automation.PSCmdlet`](http://go.microsoft.com/fwlink/?LinkId=142139) in the MSDN library. ### Input Processing Methods diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Modules.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Modules.md index 931280614067..c7751b1d0213 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Modules.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Modules.md @@ -495,7 +495,6 @@ The following modules (or snap-ins) are installed with PowerShell. * Microsoft.PowerShell.Security * Microsoft.PowerShell.Utility * Microsoft.WSMan.Management -* OneGet * PowerShellGet * PSDesiredStateConfiguration * PSScheduledJob diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md index 276ed1c7ded8..b74b7e5b0cb0 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -14,7 +14,7 @@ Describes how to work with command parameters in PowerShell. ## LONG DESCRIPTION -Most Windows PowerShell commands, such as cmdlets, functions, and scripts, +Most PowerShell commands, such as cmdlets, functions, and scripts, rely on parameters to allow users to select options or provide input. The parameters follow the command name and have the following form: diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md index 1bfafbe78470..cf7500531b40 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2017-12-06 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -167,9 +167,9 @@ Switch has the following parameters: | |condition. Wildcard and Exact are ignored. Also, if the | | |match clause is not a string, this parameter is ignored. | +In this example, there is no matching case so there is no output. ```powershell -Example: PS> switch ("fourteen") { 1 {"It is one."; Break} @@ -179,7 +179,12 @@ Example: 3 {"Three again."; Break} "fo*" {"That's too many."} } +``` + +For the word "fourteen" to match a case you must use the **-Wildcard** or +**-Regex** parameter. +```powershell PS> switch -Regex ("fourteen") { 1 {"It is one."; Break} @@ -189,6 +194,11 @@ Example: 3 {"Three again."; Break} "fo*" {"That's too many."} } + ``` + + Result: + + ```Output That's too many. ``` diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md new file mode 100644 index 000000000000..1b6877370de4 --- /dev/null +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md @@ -0,0 +1,196 @@ +--- +ms.date: 2018-01-04 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: about_WS Management_Cmdlets +--- + +# About WS-Management Cmdlets + +## SHORT DESCRIPTION + +Provides an overview of Web Services for Management (WS-Management) as +background for using the WS-Management cmdlets in Windows PowerShell. + +## LONG DESCRIPTION + +This topic provides an overview of Web Services for Management (WS-Management) +as background for using the WS-Management cmdlets in Windows PowerShell. This +topic also provides links to more information about WS-Management. The +Microsoft implementation of WS-Management is also known as Windows Remote +Management (WinRM). + +### About WS-Management + +Windows Remote Management is the Microsoft implementation of the WS-Management +protocol, a standard SOAP-based, firewall-friendly protocol that allows +hardware and operating systems from different vendors to interoperate. The +WS-Management protocol specification provides a common way for systems to +access and exchange management information across an information technology +(IT) infrastructure. WS-Management and Intelligent Platform Management +Interface (IPMI), along with the Event Collector, are components of the +Windows Hardware Management features. + +The WS-Management protocol is based on the following standard Web service +specifications: HTTPS, SOAP over HTTP (WS-I profile), SOAP 1.2, WS-Addressing, +WS-Transfer, WS-Enumeration, and WS-Eventing. + +### WS-Management and WMI + +WS-Management can be used to retrieve data exposed by Windows Management +Instrumentation (WMI). You can obtain WMI data with scripts or applications +that use the WS-Management Scripting API or through the WinRM command-line +tool. WS-Management supports most of the familiar WMI classes and operations, +including embedded objects. WS-Management can leverage WMI to collect data +about resources or to manage resources on a Windows-based computers. That +means that you can obtain data about objects such as disks, network adapters, +services, or processes in your enterprise through the existing set of WMI +classes. You can also access the hardware data that is available from the +standard WMI IPMI provider. + +### WS-Management Windows PowerShell Provider (WSMan) + +The WSMan provider provides a hierarchical view into the available +WS-Management configuration settings. The provider allows you to explore and +set the various WS-Management configuration options. + +### WS-Management Configuration + +If WS-Management is not installed and configured, Windows PowerShell remoting +is not available, the WS-Management cmdlets do not run, WS-Management scripts +do not run, and the WSMan provider cannot perform data operations. The +WS-Management command-line tool, WinRM, and event forwarding also depend on +the WS-Management configuration. + +### WS-Management Cmdlets + +WS-Management functionality is implemented in Windows PowerShell through a +module that contains a set of cmdlets and the WSMan provider. You can use +these cmdlets to complete the end-to-end tasks necessary to manage +WS-Management settings on local and remote computers. + +The following WS-Management cmdlets are available. + +### Connection Cmdlets + +- Connect-WSMan: Connects the local computer to the WS-Management (WinRM) + service on a remote computer. + +- Disconnect-WSMan: Disconnects the local computer from the WS-Management + (WinRM) service on a remote computer. + +### Management-Data Cmdlets + +- Get-WSManInstance: Displays management information for a resource instance + that is specified by a resource URI. + +- Invoke-WSManAction: Invokes an action on the target object that is specified + by the resource URI and by the selectors. + +- New-WSManInstance: Creates a new management resource instance. + +- Remove-WSManInstance: Deletes a management resource instance. + +- Set-WSManInstance: Modifies the management information that is related to a + resource. + +### Setup and Configuration Cmdlets + +- Set-WSManQuickConfig: Configures the local computer for remote management. + You can use the Set-WSManQuickConfig cmdlet to configure WS-Management to + allow remote connections to the WS-Management (WinRM) service. The + Set-WSManQuickConfig cmdlet performs the following operations: + - It determines whether the WS-Management (WinRM) service is running. If the + WinRM service is not running, the Set-WSManQuickConfig cmdlet starts the + service. + - It sets the WS-Management (WinRM) service startup type to automatic. + - It creates a listener that accepts requests from any IP address. The + default transport protocol is HTTP. + - It enables a firewall exception for WS-Management traffic. + + Note: To run this cmdlet in Windows Vista, Windows Server 2008, and later + versions of Windows, you must start Windows PowerShell with the "Run as + administrator" option. + +- Test-WSMan: Verifies that WS-Management is installed and configured. The + Test-WSMan cmdlet tests whether the WS-Management (WinRM) service is running + and configured on a local or remote computer. + +- Disable-WSManCredSSP: Disables CredSSP authentication on a client computer. + +- Enable-WSManCredSSP: Enables CredSSP authentication on a client computer. + +- Get-WSManCredSSP: Gets the CredSSP-related configuration for a client + computer. + +### WS-Management-Specific Cmdlets + +- New-WSManSessionOption: Creates a WSManSessionOption object to use as input + to one or more parameters of a WS-Management cmdlet. + +### Additional WS-Management Information + +For more information about WS-Management, see the following topics in the +MSDN (Microsoft Developer Network) library. + +"Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142321 + +"About Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142322 + +"Installation and Configuration for Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142323 + +"Windows Remote Management Architecture" +http://go.microsoft.com/fwlink/?LinkId=142324 + +"WS-Management Protocol" +http://go.microsoft.com/fwlink/?LinkId=142325 + +"Windows Remote Management and WMI" +http://go.microsoft.com/fwlink/?LinkId=142326 + +"Resource URIs" +http://go.microsoft.com/fwlink/?LinkId=142327 + +"Remote Hardware Management" +http://go.microsoft.com/fwlink/?LinkId=142328 + +"Events" +http://go.microsoft.com/fwlink/?LinkId=142329 + +## SEE ALSO + +[Connect-WSMan](../../Microsoft.WSMan.Management/Connect-WSMan.md) + +[Disable-WSManCredSSP](../../Microsoft.WSMan.Management/Disable-WSManCredSSP.md) + +[Disconnect-WSMan](../../Microsoft.WSMan.Management/Disconnect-WSMan.md) + +[Enable-WSManCredSSP](../../Microsoft.WSMan.Management/Enable-WSManCredSSP.md) + +[Get-WSManCredSSP](../../Microsoft.WSMan.Management/Get-WSManCredSSP.md) + +[Get-WSManInstance](../../Microsoft.WSMan.Management/Get-WSManInstance.md) + +[Invoke-WSManAction](../../Microsoft.WSMan.Management/Invoke-WSManAction.md) + +[New-WSManInstance](../../Microsoft.WSMan.Management/New-WSManInstance.md) + +[Remove-WSManInstance](../../Microsoft.WSMan.Management/Remove-WSManInstance.md) + +[Set-WSManInstance](../../Microsoft.WSMan.Management/Set-WSManInstance.md) + +[Set-WSManQuickConfig](../../Microsoft.WSMan.Management/Set-WSManQuickConfig.md) + +[Set-WSManSessionOption](../../Microsoft.WSMan.Management/Set-WSManSessionOption.md) + +[Test-WSMan](../../Microsoft.WSMan.Management/Test-WSMan.md) + +# KEYWORDS + +about_WSMAN + +about_WinRM diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Wildcards.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Wildcards.md index 3acd265596c5..ff5ff8afcfd2 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Wildcards.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Wildcards.md @@ -60,7 +60,7 @@ following command gets services in which the ServiceType property value includes "Interactive". ```powershell -Get-Service | Where-Object {$_.ServiceType -like "Interactive"} +Get-Service | Where-Object {$_.ServiceType -like "*Interactive*"} ``` In the following example, wildcard characters are used to find property @@ -71,7 +71,7 @@ value of the CreationTime property of the restore point to a log file. ```powershell $p = Get-ComputerRestorePoint foreach ($point in $p) { - if ($point.description -like "PowerShell") { + if ($point.description -like "*PowerShell*") { add-content -path C:\TechDocs\RestoreLog.txt "$($point.CreationTime)" } } diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md index 720271edd23d..26c1585936bf 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Windows_RT.md @@ -69,4 +69,3 @@ For more information about ConstrainedLanguage language mode, see [about_Remote](about_Remote.md) [about_Windows_PowerShell_ISE](about_Windows_PowerShell_ISE.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md new file mode 100644 index 000000000000..986f4d855fbc --- /dev/null +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md @@ -0,0 +1,172 @@ +--- +ms.date: 2018-01-04 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: about_DesiredStateConfiguration +--- + +# about_DesiredStateConfiguration + +## SHORT DESCRIPTION + +Provides a brief introduction to the PowerShell Desired State +Configuration (DSC) feature. + +## LONG DESCRIPTION + +DSC is a management platform in PowerShell that enables deploying and managing +configuration data for software services, and managing the environment in +which these services run. + +DSC provides a set of PowerShell language extensions, new cmdlets, and +resources that you can use to declaratively specify how you want the state of +your software environment to be configured. It also provides a means to +maintain and manage existing configurations. + +DSC is introduced in PowerShell 4.0. + +For detailed information about DSC, see +[PowerShell Desired State Configuration Overview](http://go.microsoft.com/fwlink/?LinkId=311940) +in the TechNet Library. + +## DEVELOPING DSC RESOURCES WITH CLASSES + +Starting in PowerShell 5.0, you can develop DSC resources by using classes. +For more information, see [about_Classes](about_Classes.md), and +[Writing a custom DSC resource with PowerShell classes](http://technet.microsoft.com/library/dn948461.aspx) +on Microsoft TechNet. + +## USING DSC + +To use DSC to configure your environment, first define a PowerShell +script block using the Configuration keyword, followed by an identifier, which +is in turn followed by the pair of curly braces delimiting the block. Inside +the configuration block you can define node blocks that specify the desired +configuration state for each node (computer) in the environment. A node block +starts with the Node keyword, followed by the name of the target computer, +which can be a variable. After the computer name, come the curly braces that +delimit the node block. Inside the node block, you can define resource blocks +to configure specific resources. A resource block starts with the type name of +the resource, followed by the identifier you want to specify for that block, +followed by the curly braces that delimit the block, as shown in the following +example. Configuration MyWebConfig { # Parameters are optional param +($MachineName, $WebsiteFilePath) + +```powershell +# A Configuration block can have one or more Node blocks +Node $MachineName +{ + # Next, specify one or more resource blocks + # WindowsFeature is one of the resources you can use in a Node block + # This example ensures the Web Server (IIS) role is installed + WindowsFeature IIS + { + # To ensure that the role is not installed, set Ensure to "Absent" + Ensure = "Present" + Name = "Web-Server" # Use the Name property from Get-WindowsFeature + } + + # You can use the File resource to create files and folders + # "WebDirectory" is the name you want to use to refer to this instance + File WebDirectory + { + Ensure = "Present" # You can also set Ensure to "Absent“ + Type = "Directory“ # Default is “File” + Recurse = $true + SourcePath = $WebsiteFilePath + DestinationPath = "C:\inetpub\wwwroot" + + # Ensure that the IIS block is successfully run first before + # configuring this resource + Requires = "[WindowsFeature]IIS" # Use Requires for dependencies + } +} +} +``` + +To create a configuration, invoke the Configuration block the same way you +would invoke a PowerShell function, passing in any expected parameters you may +have defined (two in the example above). For example, in this case: + +```powershell +MyWebConfig -MachineName "TestMachine" –WebsiteFilePath ` + "\\filesrv\WebFiles" -OutputPath "C:\Windows\system32\temp" +# OutputPath is optional +``` + +This generates a MOF file per node at the path you specify. These MOF files +specify the desired configuration for each node. Next, use the following +cmdlet to parse the configuration MOF files, send each node its corresponding +configuration, and enact those configurations. Note that you do not need to +create a separate MOF file for class-based DSC resources. + +```powershell +Start-DscConfiguration –Verbose -Wait -Path "C:\Windows\system32\temp" +``` + +## USING DSC TO MAINTAIN CONFIGURATION STATE + +With DSC, configuration is idempotent. This means that if you use DSC to enact +the same configuration more than once, the resulting configuration state will +always be the same. Because of this, if you suspect that any nodes in your +environment may have drifted from the desired state of configuration, you can +enact the same DSC configuration again to bring them back to the desired +state. You do not need to modify the configuration script to address only +those resources whose state has drifted from the desired state. + +The following example shows how you can verify whether the actual state of +configuration on a given node has drifted from the last DSC configuration +enacted on the node. In this example we are checking the configuration of the +local computer. + +```powershell +$session = New-CimSession -ComputerName "localhost" +Test-DscConfiguration -CimSession $session +``` + +## BUILT-IN DSC RESOURCES + +You can use the following built-in resources in your configuration scripts: + +|Name |Properties | +|----------------------|---------------------------------------------------| +|File |{DestinationPath, Attributes, Checksum, Content...}| +|Archive |{Destination, Path, Checksum, Credential...} | +|Environment |{Name, DependsOn, Ensure, Path...} | +|Group |{GroupName, Credential, DependsOn, Description...} | +|Log |{Message, DependsOn, PsDscRunAsCredential} | +|Package |{Name, Path, ProductId, Arguments...} | +|Registry |{Key, ValueName, DependsOn, Ensure...} | +|Script |{GetScript, SetScript, TestScript, Credential...} | +|Service |{Name, BuiltInAccount, Credential, Dependencies...}| +|User |{UserName, DependsOn, Description, Disabled...} | +|WaitForAll |{NodeName, ResourceName, DependsOn, PsDscRunAsC...}| +|WaitForAny |{NodeName, ResourceName, DependsOn, PsDscRunAsC...}| +|WaitForSome |{NodeCount, NodeName, ResourceName, DependsOn...} | +|WindowsFeature |{Name, Credential, DependsOn, Ensure...} | +|WindowsOptionalFeature|{Name, DependsOn, Ensure, LogLevel...} | +|WindowsProcess |{Arguments, Path, Credential, DependsOn...} | + +To get a list of available DSC resources on your system, run the +Get-DscResource cmdlet. + +The example in this topic demonstrates how to use the File and WindowsFeature +resources. To see all properties that you can use with a resource, insert the +cursor in the resource keyword (for example, File) within your configuration +script in PowerShell ISE, hold down CTRL, and then press SPACEBAR. + +## FIND MORE RESOURCES + +You can download, install, and learn about many other available DSC resources +that have been created by the PowerShell and DSC user community, and by +Microsoft. Visit the [PowerShell Gallery](https://www.powershellgallery.com/) +to browse and learn about available DSC resources. + +## SEE ALSO + +[PowerShell Desired State Configuration Overview](/powershell/dsc/overview) + +[Built-In PowerShell Desired State Configuration Resources](/powershell/dsc/builtinresource) + +[Build Custom PowerShell Desired State Configuration Resources](/powershell/dsc/authoringResource) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_dsclogresource.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_dsclogresource.md new file mode 100644 index 000000000000..2c3c38df824b --- /dev/null +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_dsclogresource.md @@ -0,0 +1,18 @@ +--- +ms.date: 2017-06-09 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: about_DSCLogResource +--- + +# about_DSCLogResource + +## SHORT DESCRIPTION + +Provides a brief introduction to the PowerShell Desired State Configuration +(DSC) Log Resource. LONG DESCRIPTION + +## LONG DESCRIPTION + +## HOW TO USE THE DSC LOG RESOURCE diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index b79253e0522b..700cb3bc71ca 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -244,11 +244,11 @@ The environment variables that store preferences include: The default value of $Env:PSModulePath is: ``` - $home\Documents\WindowsPowerShell\Modules; $pshome\Modules + $HOME\Documents\WindowsPowerShell\Modules; $PSHOME\Modules ``` -Windows PowerShell sets the value of "\$pshome\\Modules" in the registry. It -sets the value of "\$home\\Documents\\WindowsPowerShell\\Modules" each time you +Windows PowerShell sets the value of "\$PSHOME\\Modules" in the registry. It +sets the value of "\$HOME\\Documents\\WindowsPowerShell\\Modules" each time you start Windows PowerShell. In addition, setup programs that install modules in other directories, such as @@ -294,7 +294,7 @@ $path = [System.Environment]::GetEnvironmentVariable("PSModulePath", ``` For more information about the methods of the System.Environment class, see -[Environment Methods](http://go.microsoft.com/fwlink/?LinkId=242783) in +[Environment Methods](https://go.microsoft.com/fwlink/?LinkId=242783) in MSDN. You can add also add a command that changes the value to your profile or use diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md index fbcfc30ca802..9dd552a11e64 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md @@ -27,8 +27,7 @@ the following methods: All the methods and properties of the `PSCmdlet` class are available to advanced functions. For more information about these methods and properties, -see `System.Management.Automation.PSCmdlet` in the MSDN (Microsoft Developer -Network) library at http://go.microsoft.com/fwlink/?LinkId=142139. +see [`System.Management.Automation.PSCmdlet`](http://go.microsoft.com/fwlink/?LinkId=142139) in the MSDN library. ### Input Processing Methods diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Modules.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Modules.md index 931280614067..9f7c094784be 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Modules.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Modules.md @@ -495,9 +495,10 @@ The following modules (or snap-ins) are installed with PowerShell. * Microsoft.PowerShell.Security * Microsoft.PowerShell.Utility * Microsoft.WSMan.Management -* OneGet +* PackageManagement * PowerShellGet * PSDesiredStateConfiguration +* PSReadline * PSScheduledJob * PSWorkflow * PSWorkflowUtility diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Providers.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Providers.md index dfed0885c30d..8080f77944b9 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Providers.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Providers.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2018-01-03 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,61 +7,58 @@ title: about_Providers --- # About Providers -## about_Providers - -# SHORT DESCRIPTION +## SHORT DESCRIPTION Describes how Windows PowerShell providers provide access to data and -components that would not otherwise be easily accessible at the command -line. The data is presented in a consistent format that resembles a file -system drive. - -# LONG DESCRIPTION - -Windows PowerShell providers are Microsoft .NET Framework-based programs -that make the data in a specialized data store available in Windows -PowerShell so that you can view and manage it. - -The data that a provider exposes appears in a drive, and you access the -data in a path like you would on a hard disk drive. You can use any of the -built-in cmdlets that the provider supports to manage the data in the -provider drive. And, you can use custom cmdlets that are designed -especially for the data. - -The providers can also add dynamic parameters to the built-in cmdlets. -These are parameters that are available only when you use the cmdlet with -the provider data. - -# BUILT-IN PROVIDERS - -Windows PowerShell includes a set of built-in providers that you can use -to access the different types of data stores. - -| Provider | Drive | Data store | -| ----------- | ------------ | ------------------------------------------ | -| Alias | Alias: | Windows PowerShell aliases | -| Certificate | Cert: | x509 certificates for digital signatures | -| Environment | Env: | Windows environment variables | -| FileSystem | (*) | File system drives, directories, and files | -| Function | Function: | Windows PowerShell functions | -| Registry | HKLM:, HKCU: | Windows registry | -| Variable | Variable: | Windows PowerShell variables | -| WSMan | WSMan: | WS-Management configuration information | +components that would not otherwise be easily accessible at the command line. +The data is presented in a consistent format that resembles a file system +drive. + +## LONG DESCRIPTION + +Windows PowerShell providers are Microsoft .NET Framework-based programs that +make the data in a specialized data store available in Windows PowerShell so +that you can view and manage it. + +The data that a provider exposes appears in a drive, and you access the data +in a path like you would on a hard disk drive. You can use any of the built-in +cmdlets that the provider supports to manage the data in the provider drive. +And, you can use custom cmdlets that are designed especially for the data. + +The providers can also add dynamic parameters to the built-in cmdlets. These +are parameters that are available only when you use the cmdlet with the +provider data. + +## BUILT-IN PROVIDERS + +Windows PowerShell includes a set of built-in providers that you can use to +access the different types of data stores. + +|Provider |Drive |Data store | +|------------|-------------|-------------------------------------------| +|Alias |Alias: |Windows PowerShell aliases | +|Certificate |Cert: |x509 certificates for digital signatures | +|Environment |Env: |Windows environment variables | +|FileSystem |(*) |File system drives, directories, and files | +|Function |Function: |Windows PowerShell functions | +|Registry |HKLM:, HKCU: |Windows registry | +|Variable |Variable: |Windows PowerShell variables | +|WSMan |WSMan: |WS-Management configuration information | (*) The FileSystem drives vary on each system. -You can also create your own Windows PowerShell providers, and you can -install providers that others develop. To list the providers that are -available in your session, type: +You can also create your own Windows PowerShell providers, and you can install +providers that others develop. To list the providers that are available in +your session, type: get-psprovider -# INSTALLING AND REMOVING PROVIDERS +## INSTALLING AND REMOVING PROVIDERS Windows PowerShell providers are delivered to you in Windows PowerShell -snap-ins, which are .NET Framework-based programs that are compiled -into .dll files. The snap-ins can include providers and cmdlets. +snap-ins, which are .NET Framework-based programs that are compiled into .dll +files. The snap-ins can include providers and cmdlets. Before you use the provider features, you have to install the snap-in and then add it to your Windows PowerShell session. For more information, see @@ -76,96 +73,99 @@ cmdlet. This cmdlet does not uninstall the provider, but it makes the provider unavailable in the session. You can also use the Remove-PSDrive cmdlet to remove any drive from the -current session. This data on the drive is not affected, but the drive is -no longer available in that session. +current session. This data on the drive is not affected, but the drive is no +longer available in that session. -# VIEWING PROVIDERS +## VIEWING PROVIDERS To view the Windows PowerShell providers on your computer, type: +```powershell get-psprovider +``` -The output lists the built-in providers and the providers that you added -to the session. +The output lists the built-in providers and the providers that you added to +the session. -# THE PROVIDER CMDLETS +## THE PROVIDER CMDLETS -The following cmdlets are designed to work with the data exposed by -any provider. You can use the same cmdlets in the same way to manage -the different types of data that providers expose. After you -learn to manage the data of one provider, you can use the same -procedures with the data from any provider. +The following cmdlets are designed to work with the data exposed by any +provider. You can use the same cmdlets in the same way to manage the different +types of data that providers expose. After you learn to manage the data of one +provider, you can use the same procedures with the data from any provider. -For example, the New-Item cmdlet creates a new item. In the C: drive that -is supported by the FileSystem provider, you can use New-Item to create a -new file or folder. In the drives that are supported by the Registry -provider, you can use New-Item to create a new registry key. In the Alias: -drive, you can use New-Item to create a new alias. +For example, the New-Item cmdlet creates a new item. In the C: drive that is +supported by the FileSystem provider, you can use New-Item to create a new +file or folder. In the drives that are supported by the Registry provider, you +can use New-Item to create a new registry key. In the Alias: drive, you can +use New-Item to create a new alias. For detailed information about any of the following cmdlets, type: +``` get-help -detailed +``` -# CHILDITEM CMDLETS +### CHILDITEM CMDLETS -Get-ChildItem +- Get-ChildItem -# CONTENT CMDLETS +### CONTENT CMDLETS -Add-Content -Clear-Content -Get-Content -Set-Content +- Add-Content +- Clear-Content +- Get-Content +- Set-Content -# ITEM CMDLETS +### ITEM CMDLETS -Clear-Item -Copy-Item -Get-Item -Invoke-Item -Move-Item -New-Item -Remove-Item -Rename-Item -Set-Item +- Clear-Item +- Copy-Item +- Get-Item +- Invoke-Item +- Move-Item +- New-Item +- Remove-Item +- Rename-Item +- Set-Item -# ITEMPROPERTY CMDLETS +### ITEMPROPERTY CMDLETS -Clear-ItemProperty -Copy-ItemProperty -Get-ItemProperty -Move-ItemProperty -New-ItemProperty -Remove-ItemProperty -Rename-ItemProperty -Set-ItemProperty +- Clear-ItemProperty +- Copy-ItemProperty +- Get-ItemProperty +- Move-ItemProperty +- New-ItemProperty +- Remove-ItemProperty +- Rename-ItemProperty +- Set-ItemProperty -# LOCATION CMDLETS +### LOCATION CMDLETS -Get-Location -Pop-Location -Push-Location -Set-Location +- Get-Location +- Pop-Location +- Push-Location +- Set-Location -# PATH CMDLETS +### PATH CMDLETS -Join-Path -Convert-Path -Split-Path -Resolve-Path -Test-Path +- Join-Path +- Convert-Path +- Split-Path +- Resolve-Path +- Test-Path -# PSDRIVE CMDLETS +### PSDRIVE CMDLETS -Get-PSDrive -New-PSDrive -Remove-PSDrive +- Get-PSDrive +- New-PSDrive +- Remove-PSDrive -# PSPROVIDER CMDLETS +### PSPROVIDER CMDLETS -Get-PSProvider +- Get-PSProvider -# VIEWING PROVIDER DATA +## VIEWING PROVIDER DATA The primary benefit of a provider is that it exposes its data in a familiar and consistent way. The model for data presentation is a file system @@ -190,85 +190,108 @@ To view the contents of a provider drive, use the Get-Item or Get-ChildItem cmdlets. Type the drive name followed by a colon (:). For example, to view the contents of the Alias: drive, type: +```powershell get-item alias: +``` You can view and manage the data in any drive from another drive by including the drive name in the path. For example, to view the HKLM\Software registry key in the HKLM: drive from another drive, type: +```powershell get-childitem hklm:\software +``` To open the drive, use the Set-Location cmdlet. Remember the colon when you specify the drive path. For example, to change your location to the root directory of the Cert: drive, type: +```powershell set-location cert: +``` Then, to view the contents of the Cert: drive, type: +```powershell get-childitem +``` -# MOVING THROUGH HIERARCHICAL DATA +## MOVING THROUGH HIERARCHICAL DATA You can move through a provider drive just as you would a hard disk drive. If the data is arranged in a hierarchy of items within items, use a backslash () to indicate a child item. Use the following format: +``` drive:\location\child-location\... +``` For example, to change your location to the HKLM\Software registry key, type a Set-Location command, such as: +```powershell set-location hklm:\software +``` You can also use relative references to locations. A dot (.) represents the current location. For example, if you are in the HKLM:\Software\Microsoft registry key, and you want to list the registry subkeys in the HKLM:\Software\Microsoft\PowerShell key, type the following command: +```powershell get-childitem .\PowerShell +``` -# FINDING DYNAMIC PARAMETERS +## FINDING DYNAMIC PARAMETERS -Dynamic parameters are cmdlet parameters that are added to a cmdlet -by a provider. These parameters are available only when the cmdlet is -used with the provider that added them. +Dynamic parameters are cmdlet parameters that are added to a cmdlet by a +provider. These parameters are available only when the cmdlet is used with the +provider that added them. -For example, the Cert: drive adds the CodeSigningCert parameter -to the Get-Item and Get-ChildItem cmdlets. You can use this parameter -only when you use Get-Item or Get-ChildItem in the Cert: drive. +For example, the Cert: drive adds the CodeSigningCert parameter to the +Get-Item and Get-ChildItem cmdlets. You can use this parameter only when you +use Get-Item or Get-ChildItem in the Cert: drive. -For a list of the dynamic parameters that a provider supports, see the -Help file for the provider. Type: +For a list of the dynamic parameters that a provider supports, see the Help +file for the provider. Type: +``` get-help +``` For example: +```powershell get-help certificate +``` -# LEARNING ABOUT PROVIDERS +## LEARNING ABOUT PROVIDERS -Although all provider data appears in drives, and you use the same methods -to move through them, the similarity stops there. The data stores that -the provider exposes can be as varied as Active Directory locations and -Microsoft Exchange Server mailboxes. +Although all provider data appears in drives, and you use the same methods to +move through them, the similarity stops there. The data stores that the +provider exposes can be as varied as Active Directory locations and Microsoft +Exchange Server mailboxes. For information about individual Windows PowerShell providers, type: +``` get-help +``` For example: +```powershell get-help registry +``` For a list of Help topics about the providers, type: +```powershell get-help * -category provider +``` -# SEE ALSO +## SEE ALSO -about_Locations +[about_Locations](about_Locations.md) [about_Path_Syntax](about_Path_Syntax.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md index 1bfafbe78470..cf7500531b40 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-12-01 +ms.date: 2017-12-06 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -167,9 +167,9 @@ Switch has the following parameters: | |condition. Wildcard and Exact are ignored. Also, if the | | |match clause is not a string, this parameter is ignored. | +In this example, there is no matching case so there is no output. ```powershell -Example: PS> switch ("fourteen") { 1 {"It is one."; Break} @@ -179,7 +179,12 @@ Example: 3 {"Three again."; Break} "fo*" {"That's too many."} } +``` + +For the word "fourteen" to match a case you must use the **-Wildcard** or +**-Regex** parameter. +```powershell PS> switch -Regex ("fourteen") { 1 {"It is one."; Break} @@ -189,6 +194,11 @@ Example: 3 {"Three again."; Break} "fo*" {"That's too many."} } + ``` + + Result: + + ```Output That's too many. ``` diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md new file mode 100644 index 000000000000..1b6877370de4 --- /dev/null +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md @@ -0,0 +1,196 @@ +--- +ms.date: 2018-01-04 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: about_WS Management_Cmdlets +--- + +# About WS-Management Cmdlets + +## SHORT DESCRIPTION + +Provides an overview of Web Services for Management (WS-Management) as +background for using the WS-Management cmdlets in Windows PowerShell. + +## LONG DESCRIPTION + +This topic provides an overview of Web Services for Management (WS-Management) +as background for using the WS-Management cmdlets in Windows PowerShell. This +topic also provides links to more information about WS-Management. The +Microsoft implementation of WS-Management is also known as Windows Remote +Management (WinRM). + +### About WS-Management + +Windows Remote Management is the Microsoft implementation of the WS-Management +protocol, a standard SOAP-based, firewall-friendly protocol that allows +hardware and operating systems from different vendors to interoperate. The +WS-Management protocol specification provides a common way for systems to +access and exchange management information across an information technology +(IT) infrastructure. WS-Management and Intelligent Platform Management +Interface (IPMI), along with the Event Collector, are components of the +Windows Hardware Management features. + +The WS-Management protocol is based on the following standard Web service +specifications: HTTPS, SOAP over HTTP (WS-I profile), SOAP 1.2, WS-Addressing, +WS-Transfer, WS-Enumeration, and WS-Eventing. + +### WS-Management and WMI + +WS-Management can be used to retrieve data exposed by Windows Management +Instrumentation (WMI). You can obtain WMI data with scripts or applications +that use the WS-Management Scripting API or through the WinRM command-line +tool. WS-Management supports most of the familiar WMI classes and operations, +including embedded objects. WS-Management can leverage WMI to collect data +about resources or to manage resources on a Windows-based computers. That +means that you can obtain data about objects such as disks, network adapters, +services, or processes in your enterprise through the existing set of WMI +classes. You can also access the hardware data that is available from the +standard WMI IPMI provider. + +### WS-Management Windows PowerShell Provider (WSMan) + +The WSMan provider provides a hierarchical view into the available +WS-Management configuration settings. The provider allows you to explore and +set the various WS-Management configuration options. + +### WS-Management Configuration + +If WS-Management is not installed and configured, Windows PowerShell remoting +is not available, the WS-Management cmdlets do not run, WS-Management scripts +do not run, and the WSMan provider cannot perform data operations. The +WS-Management command-line tool, WinRM, and event forwarding also depend on +the WS-Management configuration. + +### WS-Management Cmdlets + +WS-Management functionality is implemented in Windows PowerShell through a +module that contains a set of cmdlets and the WSMan provider. You can use +these cmdlets to complete the end-to-end tasks necessary to manage +WS-Management settings on local and remote computers. + +The following WS-Management cmdlets are available. + +### Connection Cmdlets + +- Connect-WSMan: Connects the local computer to the WS-Management (WinRM) + service on a remote computer. + +- Disconnect-WSMan: Disconnects the local computer from the WS-Management + (WinRM) service on a remote computer. + +### Management-Data Cmdlets + +- Get-WSManInstance: Displays management information for a resource instance + that is specified by a resource URI. + +- Invoke-WSManAction: Invokes an action on the target object that is specified + by the resource URI and by the selectors. + +- New-WSManInstance: Creates a new management resource instance. + +- Remove-WSManInstance: Deletes a management resource instance. + +- Set-WSManInstance: Modifies the management information that is related to a + resource. + +### Setup and Configuration Cmdlets + +- Set-WSManQuickConfig: Configures the local computer for remote management. + You can use the Set-WSManQuickConfig cmdlet to configure WS-Management to + allow remote connections to the WS-Management (WinRM) service. The + Set-WSManQuickConfig cmdlet performs the following operations: + - It determines whether the WS-Management (WinRM) service is running. If the + WinRM service is not running, the Set-WSManQuickConfig cmdlet starts the + service. + - It sets the WS-Management (WinRM) service startup type to automatic. + - It creates a listener that accepts requests from any IP address. The + default transport protocol is HTTP. + - It enables a firewall exception for WS-Management traffic. + + Note: To run this cmdlet in Windows Vista, Windows Server 2008, and later + versions of Windows, you must start Windows PowerShell with the "Run as + administrator" option. + +- Test-WSMan: Verifies that WS-Management is installed and configured. The + Test-WSMan cmdlet tests whether the WS-Management (WinRM) service is running + and configured on a local or remote computer. + +- Disable-WSManCredSSP: Disables CredSSP authentication on a client computer. + +- Enable-WSManCredSSP: Enables CredSSP authentication on a client computer. + +- Get-WSManCredSSP: Gets the CredSSP-related configuration for a client + computer. + +### WS-Management-Specific Cmdlets + +- New-WSManSessionOption: Creates a WSManSessionOption object to use as input + to one or more parameters of a WS-Management cmdlet. + +### Additional WS-Management Information + +For more information about WS-Management, see the following topics in the +MSDN (Microsoft Developer Network) library. + +"Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142321 + +"About Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142322 + +"Installation and Configuration for Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142323 + +"Windows Remote Management Architecture" +http://go.microsoft.com/fwlink/?LinkId=142324 + +"WS-Management Protocol" +http://go.microsoft.com/fwlink/?LinkId=142325 + +"Windows Remote Management and WMI" +http://go.microsoft.com/fwlink/?LinkId=142326 + +"Resource URIs" +http://go.microsoft.com/fwlink/?LinkId=142327 + +"Remote Hardware Management" +http://go.microsoft.com/fwlink/?LinkId=142328 + +"Events" +http://go.microsoft.com/fwlink/?LinkId=142329 + +## SEE ALSO + +[Connect-WSMan](../../Microsoft.WSMan.Management/Connect-WSMan.md) + +[Disable-WSManCredSSP](../../Microsoft.WSMan.Management/Disable-WSManCredSSP.md) + +[Disconnect-WSMan](../../Microsoft.WSMan.Management/Disconnect-WSMan.md) + +[Enable-WSManCredSSP](../../Microsoft.WSMan.Management/Enable-WSManCredSSP.md) + +[Get-WSManCredSSP](../../Microsoft.WSMan.Management/Get-WSManCredSSP.md) + +[Get-WSManInstance](../../Microsoft.WSMan.Management/Get-WSManInstance.md) + +[Invoke-WSManAction](../../Microsoft.WSMan.Management/Invoke-WSManAction.md) + +[New-WSManInstance](../../Microsoft.WSMan.Management/New-WSManInstance.md) + +[Remove-WSManInstance](../../Microsoft.WSMan.Management/Remove-WSManInstance.md) + +[Set-WSManInstance](../../Microsoft.WSMan.Management/Set-WSManInstance.md) + +[Set-WSManQuickConfig](../../Microsoft.WSMan.Management/Set-WSManQuickConfig.md) + +[Set-WSManSessionOption](../../Microsoft.WSMan.Management/Set-WSManSessionOption.md) + +[Test-WSMan](../../Microsoft.WSMan.Management/Test-WSMan.md) + +# KEYWORDS + +about_WSMAN + +about_WinRM diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Wildcards.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Wildcards.md index 3acd265596c5..ff5ff8afcfd2 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Wildcards.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Wildcards.md @@ -60,7 +60,7 @@ following command gets services in which the ServiceType property value includes "Interactive". ```powershell -Get-Service | Where-Object {$_.ServiceType -like "Interactive"} +Get-Service | Where-Object {$_.ServiceType -like "*Interactive*"} ``` In the following example, wildcard characters are used to find property @@ -71,7 +71,7 @@ value of the CreationTime property of the restore point to a log file. ```powershell $p = Get-ComputerRestorePoint foreach ($point in $p) { - if ($point.description -like "PowerShell") { + if ($point.description -like "*PowerShell*") { add-content -path C:\TechDocs\RestoreLog.txt "$($point.CreationTime)" } } diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md index 8b66745260b0..32789dca75ab 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_packagemanagement.md @@ -104,7 +104,7 @@ For more information about the PackageManagement open development project, including how to create a PackageManagement package provider, see the PackageManagement project on GitHub at https://oneget.org. -# SEE ALSO +## SEE ALSO [Get-PackageProvider](../../PackageManagement/Get-PackageProvider.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index b79253e0522b..700cb3bc71ca 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -244,11 +244,11 @@ The environment variables that store preferences include: The default value of $Env:PSModulePath is: ``` - $home\Documents\WindowsPowerShell\Modules; $pshome\Modules + $HOME\Documents\WindowsPowerShell\Modules; $PSHOME\Modules ``` -Windows PowerShell sets the value of "\$pshome\\Modules" in the registry. It -sets the value of "\$home\\Documents\\WindowsPowerShell\\Modules" each time you +Windows PowerShell sets the value of "\$PSHOME\\Modules" in the registry. It +sets the value of "\$HOME\\Documents\\WindowsPowerShell\\Modules" each time you start Windows PowerShell. In addition, setup programs that install modules in other directories, such as @@ -294,7 +294,7 @@ $path = [System.Environment]::GetEnvironmentVariable("PSModulePath", ``` For more information about the methods of the System.Environment class, see -[Environment Methods](http://go.microsoft.com/fwlink/?LinkId=242783) in +[Environment Methods](https://go.microsoft.com/fwlink/?LinkId=242783) in MSDN. You can add also add a command that changes the value to your profile or use diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md index fbcfc30ca802..9dd552a11e64 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md @@ -27,8 +27,7 @@ the following methods: All the methods and properties of the `PSCmdlet` class are available to advanced functions. For more information about these methods and properties, -see `System.Management.Automation.PSCmdlet` in the MSDN (Microsoft Developer -Network) library at http://go.microsoft.com/fwlink/?LinkId=142139. +see [`System.Management.Automation.PSCmdlet`](http://go.microsoft.com/fwlink/?LinkId=142139) in the MSDN library. ### Input Processing Methods diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Modules.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Modules.md index 931280614067..ba9346319905 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Modules.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Modules.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-11-29 +ms.date: 2018-01-04 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -486,6 +486,7 @@ NOTE: Remote sessions, including sessions that are started by using the commands are packaged in snap-ins. The following modules (or snap-ins) are installed with PowerShell. +* CimCmdlets * Microsoft.PowerShell.Archive * Microsoft.PowerShell.Core * Microsoft.PowerShell.Diagnostics @@ -495,9 +496,10 @@ The following modules (or snap-ins) are installed with PowerShell. * Microsoft.PowerShell.Security * Microsoft.PowerShell.Utility * Microsoft.WSMan.Management -* OneGet +* PackageManagement * PowerShellGet * PSDesiredStateConfiguration +* PSDiagnostics * PSScheduledJob * PSWorkflow * PSWorkflowUtility diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md new file mode 100644 index 000000000000..1b6877370de4 --- /dev/null +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md @@ -0,0 +1,196 @@ +--- +ms.date: 2018-01-04 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +title: about_WS Management_Cmdlets +--- + +# About WS-Management Cmdlets + +## SHORT DESCRIPTION + +Provides an overview of Web Services for Management (WS-Management) as +background for using the WS-Management cmdlets in Windows PowerShell. + +## LONG DESCRIPTION + +This topic provides an overview of Web Services for Management (WS-Management) +as background for using the WS-Management cmdlets in Windows PowerShell. This +topic also provides links to more information about WS-Management. The +Microsoft implementation of WS-Management is also known as Windows Remote +Management (WinRM). + +### About WS-Management + +Windows Remote Management is the Microsoft implementation of the WS-Management +protocol, a standard SOAP-based, firewall-friendly protocol that allows +hardware and operating systems from different vendors to interoperate. The +WS-Management protocol specification provides a common way for systems to +access and exchange management information across an information technology +(IT) infrastructure. WS-Management and Intelligent Platform Management +Interface (IPMI), along with the Event Collector, are components of the +Windows Hardware Management features. + +The WS-Management protocol is based on the following standard Web service +specifications: HTTPS, SOAP over HTTP (WS-I profile), SOAP 1.2, WS-Addressing, +WS-Transfer, WS-Enumeration, and WS-Eventing. + +### WS-Management and WMI + +WS-Management can be used to retrieve data exposed by Windows Management +Instrumentation (WMI). You can obtain WMI data with scripts or applications +that use the WS-Management Scripting API or through the WinRM command-line +tool. WS-Management supports most of the familiar WMI classes and operations, +including embedded objects. WS-Management can leverage WMI to collect data +about resources or to manage resources on a Windows-based computers. That +means that you can obtain data about objects such as disks, network adapters, +services, or processes in your enterprise through the existing set of WMI +classes. You can also access the hardware data that is available from the +standard WMI IPMI provider. + +### WS-Management Windows PowerShell Provider (WSMan) + +The WSMan provider provides a hierarchical view into the available +WS-Management configuration settings. The provider allows you to explore and +set the various WS-Management configuration options. + +### WS-Management Configuration + +If WS-Management is not installed and configured, Windows PowerShell remoting +is not available, the WS-Management cmdlets do not run, WS-Management scripts +do not run, and the WSMan provider cannot perform data operations. The +WS-Management command-line tool, WinRM, and event forwarding also depend on +the WS-Management configuration. + +### WS-Management Cmdlets + +WS-Management functionality is implemented in Windows PowerShell through a +module that contains a set of cmdlets and the WSMan provider. You can use +these cmdlets to complete the end-to-end tasks necessary to manage +WS-Management settings on local and remote computers. + +The following WS-Management cmdlets are available. + +### Connection Cmdlets + +- Connect-WSMan: Connects the local computer to the WS-Management (WinRM) + service on a remote computer. + +- Disconnect-WSMan: Disconnects the local computer from the WS-Management + (WinRM) service on a remote computer. + +### Management-Data Cmdlets + +- Get-WSManInstance: Displays management information for a resource instance + that is specified by a resource URI. + +- Invoke-WSManAction: Invokes an action on the target object that is specified + by the resource URI and by the selectors. + +- New-WSManInstance: Creates a new management resource instance. + +- Remove-WSManInstance: Deletes a management resource instance. + +- Set-WSManInstance: Modifies the management information that is related to a + resource. + +### Setup and Configuration Cmdlets + +- Set-WSManQuickConfig: Configures the local computer for remote management. + You can use the Set-WSManQuickConfig cmdlet to configure WS-Management to + allow remote connections to the WS-Management (WinRM) service. The + Set-WSManQuickConfig cmdlet performs the following operations: + - It determines whether the WS-Management (WinRM) service is running. If the + WinRM service is not running, the Set-WSManQuickConfig cmdlet starts the + service. + - It sets the WS-Management (WinRM) service startup type to automatic. + - It creates a listener that accepts requests from any IP address. The + default transport protocol is HTTP. + - It enables a firewall exception for WS-Management traffic. + + Note: To run this cmdlet in Windows Vista, Windows Server 2008, and later + versions of Windows, you must start Windows PowerShell with the "Run as + administrator" option. + +- Test-WSMan: Verifies that WS-Management is installed and configured. The + Test-WSMan cmdlet tests whether the WS-Management (WinRM) service is running + and configured on a local or remote computer. + +- Disable-WSManCredSSP: Disables CredSSP authentication on a client computer. + +- Enable-WSManCredSSP: Enables CredSSP authentication on a client computer. + +- Get-WSManCredSSP: Gets the CredSSP-related configuration for a client + computer. + +### WS-Management-Specific Cmdlets + +- New-WSManSessionOption: Creates a WSManSessionOption object to use as input + to one or more parameters of a WS-Management cmdlet. + +### Additional WS-Management Information + +For more information about WS-Management, see the following topics in the +MSDN (Microsoft Developer Network) library. + +"Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142321 + +"About Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142322 + +"Installation and Configuration for Windows Remote Management" +http://go.microsoft.com/fwlink/?LinkId=142323 + +"Windows Remote Management Architecture" +http://go.microsoft.com/fwlink/?LinkId=142324 + +"WS-Management Protocol" +http://go.microsoft.com/fwlink/?LinkId=142325 + +"Windows Remote Management and WMI" +http://go.microsoft.com/fwlink/?LinkId=142326 + +"Resource URIs" +http://go.microsoft.com/fwlink/?LinkId=142327 + +"Remote Hardware Management" +http://go.microsoft.com/fwlink/?LinkId=142328 + +"Events" +http://go.microsoft.com/fwlink/?LinkId=142329 + +## SEE ALSO + +[Connect-WSMan](../../Microsoft.WSMan.Management/Connect-WSMan.md) + +[Disable-WSManCredSSP](../../Microsoft.WSMan.Management/Disable-WSManCredSSP.md) + +[Disconnect-WSMan](../../Microsoft.WSMan.Management/Disconnect-WSMan.md) + +[Enable-WSManCredSSP](../../Microsoft.WSMan.Management/Enable-WSManCredSSP.md) + +[Get-WSManCredSSP](../../Microsoft.WSMan.Management/Get-WSManCredSSP.md) + +[Get-WSManInstance](../../Microsoft.WSMan.Management/Get-WSManInstance.md) + +[Invoke-WSManAction](../../Microsoft.WSMan.Management/Invoke-WSManAction.md) + +[New-WSManInstance](../../Microsoft.WSMan.Management/New-WSManInstance.md) + +[Remove-WSManInstance](../../Microsoft.WSMan.Management/Remove-WSManInstance.md) + +[Set-WSManInstance](../../Microsoft.WSMan.Management/Set-WSManInstance.md) + +[Set-WSManQuickConfig](../../Microsoft.WSMan.Management/Set-WSManQuickConfig.md) + +[Set-WSManSessionOption](../../Microsoft.WSMan.Management/Set-WSManSessionOption.md) + +[Test-WSMan](../../Microsoft.WSMan.Management/Test-WSMan.md) + +# KEYWORDS + +about_WSMAN + +about_WinRM diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Wildcards.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Wildcards.md index 3acd265596c5..ff5ff8afcfd2 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Wildcards.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Wildcards.md @@ -60,7 +60,7 @@ following command gets services in which the ServiceType property value includes "Interactive". ```powershell -Get-Service | Where-Object {$_.ServiceType -like "Interactive"} +Get-Service | Where-Object {$_.ServiceType -like "*Interactive*"} ``` In the following example, wildcard characters are used to find property @@ -71,7 +71,7 @@ value of the CreationTime property of the restore point to a log file. ```powershell $p = Get-ComputerRestorePoint foreach ($point in $p) { - if ($point.description -like "PowerShell") { + if ($point.description -like "*PowerShell*") { add-content -path C:\TechDocs\RestoreLog.txt "$($point.CreationTime)" } } diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md b/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md index e5fe0b0de061..8a47288dd78e 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Modules.md @@ -446,12 +446,9 @@ Get-Command | Format-List -Property verb,noun,pssnapin,module For example, to find the source of the `Get-Date` cmdlet, type: ```powershell -Get-Command Get-Date | Format-List -Property verb,noun,pssnapin,module +Get-Command Get-Date | Format-List -Property verb,noun,module ``` -For more information about PowerShell snap-ins, see -[about_PSSnapins](about_PSSnapins.md). - ## Module-related Warnings and Errors The commands that a module exports should follow the PowerShell command naming @@ -509,8 +506,6 @@ about_DesiredStateConfiguration [about_Group_Policy_Settings](about_Group_Policy_Settings.md) -[about_PSSnapins](about_PSSnapins.md) - [Get-Command](../Get-Command.md) [Get-Help](../Get-Help.md) From 11244d29bd38d50b1ca14c4e5b0bb865890635e9 Mon Sep 17 00:00:00 2001 From: Andrew Palmer Date: Fri, 5 Jan 2018 18:00:46 +0000 Subject: [PATCH 157/188] Corrected Example 3 (#2014) * Corrected Example 3 Example 3 is an example to remove the user from the group but instead it was removing the group completely. This change adds the correct syntax to perform what was intended. See https://github.com/PowerShell/PowerShell-Docs/issues/2001 * minor edits for spacing and metadata --- dsc/groupResource.md | 72 ++++++++++++++++++++++---------------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/dsc/groupResource.md b/dsc/groupResource.md index 34a51ebc6cd2..554dcb0bf446 100644 --- a/dsc/groupResource.md +++ b/dsc/groupResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC Group Resource @@ -13,6 +12,7 @@ title: DSC Group Resource The Group resource in Windows PowerShell Desired State Configuration (DSC) provides a mechanism to manage local groups on the target node. ## Syntax + ``` Group [string] #ResourceName { @@ -29,20 +29,20 @@ Group [string] #ResourceName ## Properties -| Property | Description | -|---|---| -| GroupName| The name of the group for which you want to ensure a specific state.| -| Credential| The credentials required to access remote resources. **Note**: This account must have the appropriate Active Directory permissions to add all non-local accounts to the group; otherwise, an error occurs when the configuration is executed on the target node. -| Description| The description of the group.| -| Ensure| Indicates if the group exists. Set this property to "Absent" to ensure that the group does not exist. Setting it to "Present" (the default value) ensures that the group exists.| -| Members| Use this property to replace the current group membership with the specified members. The value of this property is an array of strings of the form *Domain*\\*UserName*. If you set this property in a configuration, do not use either the **MembersToExclude** or **MembersToInclude** property. Doing so generates an error.| -| MembersToExclude| Use this property to remove members from the existing membership of the group. The value of this property is an array of strings of the form *Domain*\\*UserName*. If you set this property in a configuration, do not use the **Members** property. Doing so generates an error.| -| MembersToInclude| Use this property to add members to the existing membership of the group. The value of this property is an array of strings of the form *Domain*\\*UserName*. If you set this property in a configuration, do not use the **Members** property. Doing so will generate an error.| -| DependsOn | Indicates that the configuration of another resource must run before this resource is configured. For example, if the ID of the resource configuration script block that you want to run first is __ResourceName__ and its type is __ResourceType__, the syntax for using this property is `DependsOn = "[ResourceType]ResourceName"``.| +| Property | Description | +|---|---| +| GroupName| The name of the group for which you want to ensure a specific state.| +| Credential| The credentials required to access remote resources. **Note**: This account must have the appropriate Active Directory permissions to add all non-local accounts to the group; otherwise, an error occurs when the configuration is executed on the target node. +| Description| The description of the group.| +| Ensure| Indicates if the group exists. Set this property to "Absent" to ensure that the group does not exist. Setting it to "Present" (the default value) ensures that the group exists.| +| Members| Use this property to replace the current group membership with the specified members. The value of this property is an array of strings of the form *Domain*\\*UserName*. If you set this property in a configuration, do not use either the **MembersToExclude** or **MembersToInclude** property. Doing so generates an error.| +| MembersToExclude| Use this property to remove members from the existing membership of the group. The value of this property is an array of strings of the form *Domain*\\*UserName*. If you set this property in a configuration, do not use the **Members** property. Doing so generates an error.| +| MembersToInclude| Use this property to add members to the existing membership of the group. The value of this property is an array of strings of the form *Domain*\\*UserName*. If you set this property in a configuration, do not use the **Members** property. Doing so will generate an error.| +| DependsOn | Indicates that the configuration of another resource must run before this resource is configured. For example, if the ID of the resource configuration script block that you want to run first is __ResourceName__ and its type is __ResourceType__, the syntax for using this property is `DependsOn = "[ResourceType]ResourceName"``.| ## Example 1 -The following example shows how to ensure that a group called "TestGroup" is absent. +The following example shows how to ensure that a group called "TestGroup" is absent. ```powershell Group GroupExample @@ -53,8 +53,12 @@ Group GroupExample GroupName = "TestGroup" } ``` + ## Example 2 -The following example shows how to add an Active Directory User to the local administrators group as part of a Multi-Machine Lab build where you are already using a PSCredential for the Local Adminstrator account. As this is also used for the Domain Admin Account (after Domain promotion) we then need to convert this existing PSCredential to a Domain Friendly credential to enable us to add a Domain User to the Local Administrators Group on the Member server. + +The following example shows how to add an Active Directory User to the local administrators group as part of a Multi-Machine Lab build where you are already using a PSCredential for the Local Adminstrator account. +As this is also used for the Domain Admin Account (after Domain promotion), we then need to convert this existing PSCredential to a Domain Friendly credential. +Then we can add a Domain User to the Local Administrators Group on the Member server. ```powershell @{ @@ -63,43 +67,39 @@ The following example shows how to add an Active Directory User to the local adm NodeName = '*'; DomainName = 'SubTest.contoso.com'; } - @{ + @{ NodeName = 'Box2'; - AdminAccount = 'Admin-Dave_Alexanderson' - } + AdminAccount = 'Admin-Dave_Alexanderson' + } ) } - + $domain = $node.DomainName.split('.')[0] $DCredential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList ("$domain\$($credential.Username)", $Credential.Password) -Group AddADUserToLocalAdminGroup - { - GroupName='Administrators' - Ensure= 'Present' - MembersToInclude= "$domain\$($Node.AdminAccount)" - Credential = $dCredential - PsDscRunAsCredential = $DCredential - } +Group AddADUserToLocalAdminGroup { + GroupName='Administrators' + Ensure= 'Present' + MembersToInclude= "$domain\$($Node.AdminAccount)" + Credential = $dCredential + PsDscRunAsCredential = $DCredential +} ``` ## Example 3 -The following example shows how to ensure a local group, TigerTeamAdmins, on the server TigerTeamSource.Contoso.Com does not contain a particular domain account, Contoso\JerryG. -```powershell +The following example shows how to ensure a local group, TigerTeamAdmins, on the server TigerTeamSource.Contoso.Com does not contain a particular domain account, Contoso\JerryG. -Configuration SecureTigerTeamSrouce -{ +```powershell +Configuration SecureTigerTeamSrouce { Import-DscResource -ModuleName 'PSDesiredStateConfiguration' - + Node TigerTeamSource.Contoso.Com { - Group TigerTeamAdmins - { - GroupName = 'TigerTeamAdmins' - Ensure = 'Absent' - MembersToInclude = "Contoso\JerryG" + Group TigerTeamAdmins { + GroupName = 'TigerTeamAdmins' + Ensure = 'Present' + MembersToExclude = "Contoso\JerryG" } } } ``` - From f2f819fec3b1a3415b381c0bfe075fb6b67f131f Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Fri, 5 Jan 2018 13:09:59 -0800 Subject: [PATCH 158/188] Enable running pandoc on about topic files (#2012) * Enable running pandoc on about topic files * Remove extra line * Removed --ascii parameter from pandoc as it is not required --- appveyor.ps1 | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/appveyor.ps1 b/appveyor.ps1 index f75c0bb75ece..e7caa448943a 100644 --- a/appveyor.ps1 +++ b/appveyor.ps1 @@ -7,6 +7,17 @@ param( $global:ProgressPreference = 'SilentlyContinue' if($ShowProgress){$ProgressPreference = 'Continue'} +# Pandoc source URL +$panDocVersion = "2.0.6" +$pandocSourceURL = "https://github.com/jgm/pandoc/releases/download/$panDocVersion/pandoc-$panDocVersion-windows.zip" + +$pandocDestinationPath = New-Item (Join-Path ([System.IO.Path]::GetTempPath()) "PanDoc") -ItemType Directory -Force +$pandocZipPath = Join-Path $pandocDestinationPath "pandoc-$panDocVersion-windows.zip" +Invoke-WebRequest -Uri $pandocSourceURL -OutFile $pandocZipPath + +Expand-Archive -Path (Join-Path $pandocDestinationPath "pandoc-$panDocVersion-windows.zip") -DestinationPath $pandocDestinationPath -Force +$pandocExePath = Join-Path (Join-Path $pandocDestinationPath "pandoc-$panDocVersion") "pandoc.exe" + # Find the reference folder path w.r.t the script $ReferenceDocset = Join-Path $PSScriptRoot 'reference' @@ -14,7 +25,7 @@ $ReferenceDocset = Join-Path $PSScriptRoot 'reference' $allErrors = @() # Go through all the directories in the reference folder -Get-ChildItem $ReferenceDocset -Directory -Exclude 'docs-conceptual','mapping' | ForEach-Object -Process { +Get-ChildItem $ReferenceDocset -Directory -Exclude 'docs-conceptual','mapping', 'bread-pscore' | ForEach-Object -Process { $Version = $_.Name $VersionFolder = $_.FullName # For each of the directories, go through each module folder @@ -26,6 +37,29 @@ Get-ChildItem $ReferenceDocset -Directory -Exclude 'docs-conceptual','mapping' | $MamlOutputFolder = Join-Path "$PSScriptRoot\maml" "$Version\$ModuleName" $CabOutputFolder = Join-Path "$PSScriptRoot\updatablehelp" "$Version\$ModuleName" + # Process the about topics if any + $AboutFolder = Join-Path $ModulePath "About" + + if(Test-Path $AboutFolder) + { + Get-ChildItem "$aboutfolder/about_*.md" | ForEach-Object { + $aboutFileFullName = $_.FullName + $aboutFileOutputName = "$($_.BaseName).help.txt" + $aboutFileOutputFullName = Join-Path $MamlOutputFolder $aboutFileOutputName + + $pandocArgs = @( + "--from=markdown", + "--to=plain+multiline_tables+inline_code_attributes", + "--columns=75", + "--output=$aboutFileOutputFullName", + $aboutFileFullName, + "--quiet" + ) + + & $pandocExePath $pandocArgs + } + } + try { # For each module, create a single maml help file # Adding warningaction=stop to throw errors for all warnings, erroraction=stop to make them terminating errors From e7835e3e86186f52223951c69f607207ddf1b13d Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Fri, 5 Jan 2018 19:01:02 -0800 Subject: [PATCH 159/188] Creates output directory as pandoc needs it (#2018) --- appveyor.ps1 | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/appveyor.ps1 b/appveyor.ps1 index e7caa448943a..79fee67954e3 100644 --- a/appveyor.ps1 +++ b/appveyor.ps1 @@ -37,6 +37,11 @@ Get-ChildItem $ReferenceDocset -Directory -Exclude 'docs-conceptual','mapping', $MamlOutputFolder = Join-Path "$PSScriptRoot\maml" "$Version\$ModuleName" $CabOutputFolder = Join-Path "$PSScriptRoot\updatablehelp" "$Version\$ModuleName" + if(-not (Test-Path $MamlOutputFolder)) + { + New-Item $MamlOutputFolder -ItemType Directory -Force > $null + } + # Process the about topics if any $AboutFolder = Join-Path $ModulePath "About" From 607b9f4564daf4b611c9014573e82ac9734a7478 Mon Sep 17 00:00:00 2001 From: Steve Lee Date: Tue, 9 Jan 2018 07:21:34 -0800 Subject: [PATCH 160/188] remove alias `sc` to match PSCore6 (#2021) --- reference/6/Microsoft.PowerShell.Management/Set-Content.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Management/Set-Content.md b/reference/6/Microsoft.PowerShell.Management/Set-Content.md index b23a4fd8a3d3..0ce956f144ac 100644 --- a/reference/6/Microsoft.PowerShell.Management/Set-Content.md +++ b/reference/6/Microsoft.PowerShell.Management/Set-Content.md @@ -402,8 +402,6 @@ Otherwise, this cmdlet does not generate any output. ## NOTES -You can also refer to Set-Content by its built-in alias, "sc". For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md). - Set-Content is designed for string processing. If you pipe non-string objects to Set-Content, it converts the object to a string before writing it. To write objects to files, use Out-File. From 3fceb89aba5ecdf677b98d1c071f814f5f7b0290 Mon Sep 17 00:00:00 2001 From: Charlie Schmidt Date: Tue, 9 Jan 2018 11:22:37 -0500 Subject: [PATCH 161/188] Cmdlet help for ConvertFrom-Clixml and ConvertTo-Clixml (#2022) * Cmdlet help for ConvertFrom-Clixml and ConvertTo-Clixml for Powershell#3898 * minor edits - Removed -information* common parameters - reformat code blocks - renumbered example * minor updates - reformatted examples - removed common paramters * update link to about topic * minor edits - removed common parameters - formatted code blocks * minor edits - reformatted code blocks - removed common parameters --- .../ConvertFrom-Clixml.md | 154 ++++++++++++++++ .../ConvertTo-Clixml.md | 169 ++++++++++++++++++ .../Export-Clixml.md | 62 +++---- .../Import-Clixml.md | 57 ++---- 4 files changed, 360 insertions(+), 82 deletions(-) create mode 100644 reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Clixml.md create mode 100644 reference/6/Microsoft.PowerShell.Utility/ConvertTo-Clixml.md diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Clixml.md b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Clixml.md new file mode 100644 index 000000000000..32bcb7b11aff --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Clixml.md @@ -0,0 +1,154 @@ +--- +ms.date: 2017-06-09 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +online version: +external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml +title: ConvertFrom-Clixml +--- + +# ConvertFrom-Clixml + +## SYNOPSIS +Converts an CLIXML string into new corresponding object in Windows PowerShell. + +## SYNTAX + +``` +ConvertFrom-Clixml -InputObject [-IncludeTotalCount] [-Skip ] [-First ] [] +``` + +## DESCRIPTION +The **ConvertFrom-CliXml** cmdlet converts a CLIXML string with data that represents Microsoft .NET Framework objects and creates the objects in Windows PowerShell. + +A valuable use of **ConvertFrom-CliXml** is to deserialize credentials and secure strings that have been serialized as secure XML by running the ConvertTo-Clixml cmdlet. +For an example of how to do this, see Example 2. + +## EXAMPLES + +### Example 1: Import a serialized file and recreate an object + +```powershell +$clixml = Get-Process | ConvertTo-Clixml +$Processes = ConvertFrom-Clixml $clixml +``` + +This command uses the ConvertTo-Clixml cmdlet to create a serialized copy of the process information returned by Get-Process. +It then uses **ConvertFrom-Clixml** to retrieve the contents of the serialized string and re-create an object that is stored in the $Processes variable. + +### Example 2: Convert an encrypted credential object + +```powershell +$CredXml = $Credential | ConvertTo-Clixml +$Credential = ConvertFrom-CliXml $CredXml +``` + +The **ConvertTo-CliXml** cmdlet encrypts credential objects by using the +[Windows Data Protection API](http://msdn.microsoft.com/library/windows/apps/xaml/hh464970.aspx). +This ensures that only your user account can decrypt the contents of the credential object. + +In this example, given a credential that you've stored in the $Credential variable by running the Get-Credential cmdlet, you can run the **ConvertTo-CliXml** cmdlet to serialize the credential to a string. + +To deserialize the credential later, run the second command. +This time, you are running ConvertFrom-Clixml to import the secured credential object into your script. +This eliminates the risk of exposing plain-text passwords in your script. + +## PARAMETERS + +### -InputObject +Specifies the CLIXML string to be converted to objects. +You can also pipe the CLIXML string to **ConvertFrom-Clixml**. + +```yaml +Type: string +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -First +Gets only the specified number of objects. +Enter the number of objects to get. + +```yaml +Type: UInt64 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Skip +Ignores the specified number of objects and then gets the remaining objects. +Enter the number of objects to skip. + +```yaml +Type: UInt64 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IncludeTotalCount +Reports the total number of objects in the data set (an integer) followed by the selected objects. +If the cmdlet cannot determine the total count, it displays "Unknown total count." The integer has an Accuracy property that indicates the reliability of the total count value. +The value of Accuracy ranges from 0.0 to 1.0 where 0.0 means that the cmdlet could not count the objects, 1.0 means that the count is exact, and a value between 0.0 and 1.0 indicates an increasingly reliable estimate. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). + +## INPUTS + +### System.String +You can pipe a string that contains a path to **ConvertFrom-Clixml**. + +## OUTPUTS + +### PSObject +**ConvertFrom-Clixml** returns objects that have been deserialized from the stored XML files. + +## NOTES +* When specifying multiple values for a parameter, use commas to separate the values. For example, "\ \, \". + +* + +## RELATED LINKS + +[Use PowerShell to Pass Credentials to Legacy Systems](http://blogs.technet.com/b/heyscriptingguy/archive/2011/06/05/use-powershell-to-pass-credentials-to-legacy-systems.aspx) + +[Securely Store Credentials on Disk](http://powershellcookbook.com/recipe/PukO/securely-store-credentials-on-disk) + +[Export-Clixml](Export-Clixml.md) + +[Import-Clixml](Import-Clixml.md) + +[ConvertTo-Clixml](ConvertTo-Clixml.md) + + diff --git a/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Clixml.md b/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Clixml.md new file mode 100644 index 000000000000..dfca81a1ca09 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Utility/ConvertTo-Clixml.md @@ -0,0 +1,169 @@ +--- +ms.date: 2017-06-09 +schema: 2.0.0 +locale: en-us +keywords: powershell,cmdlet +online version: +external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml +title: ConvertTo-Clixml +--- + +# ConvertTo-Clixml + +## SYNOPSIS +Converts objects to an XML-based representation and returns that as a string. + +## SYNTAX + +``` +ConvertTo-Clixml [-Depth ] -InputObject [-Encoding ] [] +``` + +## DESCRIPTION +The **ConvertTo-CliXml** cmdlet creates XML-based representations of objects and returns them as strings. +You can then use the **ConvertFrom-Clixml** cmdlet to re-create the saved objects based on the contents of the strings. + +A valuable use of **ConvertTo-CliXml** is to serialize credentials and secure strings securely as XML. +For an example of how to do this, see Example 3. + +## EXAMPLES + +### Example 1: Convert a string to an XML representation + +```powershell +"This is a test" | ConvertTo-Clixml +``` + +This command returns a string with am XML-based representation of the string object with a value of "This is a test". + +### Example 2: Convert an object to an XML-based representation + +```powershell +$FileaclString = Get-Acl C:\test.txt | ConvertTo-Clixml +Fileacl = ConvertFrom-Clixml $FileaclString +``` + +This example shows how to convert an object to an XML string and then create an object by converting the XML from the string. + +The first command uses the Get-Acl cmdlet to get the security descriptor of the Test.txt file. +It uses a pipeline operator to pass the security descriptor to **ConvertTo-Clixml**, which converts the object to an XML-based representation and returns that as a string. +Then, it saves the string in the $FileAclString variable. + +The second command uses the ConvertFrom-Clixml cmdlet to create an object from the XML in the $FileAclString variable. +Then, it saves the object in the $FileAcl variable. + +### Example 3: Convert an encrypted credential object + +```powershell +$CredXml = $Credential | ConvertTo-Clixml +$Credential = ConvertFrom-CliXml $CredXml +``` + +The **ConvertTo-CliXml** cmdlet encrypts credential objects by using the +[Windows Data Protection API](http://msdn.microsoft.com/library/windows/apps/xaml/hh464970.aspx). +This ensures that only your user account can decrypt the contents of the credential object. + +In this example, given a credential that you've stored in the $Credential variable by running the Get-Credential cmdlet, you can run the **ConvertTo-CliXml** cmdlet to serialize the credential to a string. + +To deserialize the credential later, run the second command. +This time, you are running ConvertFrom-Clixml to import the secured credential object into your script. +This eliminates the risk of exposing plain-text passwords in your script. + +## PARAMETERS + +### -Depth +Specifies how many levels of contained objects are included in the XML representation. +The default value is 2. + +The default value can be overridden for the object type in the Types.ps1xml files. +For more information, see about_Types.ps1xml. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Encoding +Specifies the type of encoding for the target file. +The acceptable values for this parameter are: + +- ASCII +- UTF8 +- UTF7 +- UTF32 +- Unicode +- BigEndianUnicode +- Default +- OEM + +The default value is Unicode. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: +Accepted values: Unicode, UTF7, UTF8, ASCII, UTF32, BigEndianUnicode, Default, OEM + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +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-Clixml**. + +```yaml +Type: PSObject +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). + +## INPUTS + +### System.Management.Automation.PSObject +You can pipe any object to **ConvertTo-Clixml**. + +## OUTPUTS + +### System.String +The XML-based representation is returned as a collection of strings. + +## NOTES + +## RELATED LINKS + +[Use PowerShell to Pass Credentials to Legacy Systems](http://blogs.technet.com/b/heyscriptingguy/archive/2011/06/05/use-powershell-to-pass-credentials-to-legacy-systems.aspx) + +[Securely Store Credentials on Disk](http://powershellcookbook.com/recipe/PukO/securely-store-credentials-on-disk) + +[ConvertTo-Json](ConvertTo-Json.md) + +[ConvertTo-Xml](ConvertTo-Xml.md) + +[ConvertTo-Csv](ConvertTo-Csv.md) + +[Export-Clixml](Export-Clixml.md) + +[Import-Clixml](Import-Clixml.md) + +[ConvertFrom-Clixml](ConvertFrom-Clixml.md) diff --git a/reference/6/Microsoft.PowerShell.Utility/Export-Clixml.md b/reference/6/Microsoft.PowerShell.Utility/Export-Clixml.md index 8ae22d949270..8507862cf847 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Export-Clixml.md +++ b/reference/6/Microsoft.PowerShell.Utility/Export-Clixml.md @@ -18,15 +18,13 @@ Creates an XML-based representation of an object or objects and stores it in a f ### ByPath (Default) ``` Export-Clixml [-Depth ] [-Path] -InputObject [-Force] [-NoClobber] - [-Encoding ] [-InformationAction ] [-InformationVariable ] [-WhatIf] - [-Confirm] [] + [-Encoding ] [-WhatIf] [-Confirm] [] ``` ### ByLiteralPath ``` Export-Clixml [-Depth ] -LiteralPath -InputObject [-Force] [-NoClobber] - [-Encoding ] [-InformationAction ] [-InformationVariable ] [-WhatIf] - [-Confirm] [] + [-Encoding ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -42,16 +40,18 @@ For an example of how to do this, see Example 3. ## EXAMPLES ### Example 1: Export a string to an XML file -``` -PS C:\> "This is a test" | Export-Clixml sample.xml + +```powershell +"This is a test" | Export-Clixml sample.xml ``` This command creates an XML file that stores a representation of the string, "This is a test". ### Example 2: Export an object to an XML file -``` -PS C:\> Get-Acl C:\test.txt | Export-Clixml -Path "fileacl.xml" -PS C:\> $Fileacl = Import-Clixml "fileacl.xml" + +```powershell +Get-Acl C:\test.txt | Export-Clixml -Path "fileacl.xml" +$Fileacl = Import-Clixml "fileacl.xml" ``` This example shows how to export an object to an XML file and then create an object by importing the XML from the file. @@ -63,11 +63,12 @@ The second command uses the Import-Clixml cmdlet to create an object from the XM Then, it saves the object in the $FileAcl variable. ### Example 3: Encrypt an exported credential object -``` -PS C:\> $CredXmlPath = Join-Path (Split-Path $Profile) TestScript.ps1.credential -PS C:\> $credential | Export-CliXml $CredPath -PS C:\> $CredXmlPath = Join-Path (Split-Path $Profile) TestScript.ps1.credential -PS C:\> $Credential = Import-CliXml $CredXmlPath + +```powershell +$CredXmlPath = Join-Path (Split-Path $Profile) TestScript.ps1.credential +$credential | Export-CliXml $CredPath +$CredXmlPath = Join-Path (Split-Path $Profile) TestScript.ps1.credential +$Credential = Import-CliXml $CredXmlPath ``` The **Export-CliXml** cmdlet encrypts credential objects by using the Windows Data Protection APIhttp://msdn.microsoft.com/library/windows/apps/xaml/hh464970.aspx. @@ -149,33 +150,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -InformationAction -The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -The default value can be overridden for the object type in the Types.ps1xml files. For more information, see about_Types.ps1xml.```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -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. @@ -275,7 +249,7 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -301,5 +275,9 @@ You can pipe any object to **Export-Clixml**. [Export-Csv](Export-Csv.md) +[ConvertTo-Clixml](ConvertTo-Clixml.md) + +[ConvertFrom-Clixml](ConvertFrom-Clixml.md) + [Import-Clixml](Import-Clixml.md) diff --git a/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md b/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md index 9b10800a07a1..84bf429635d1 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md +++ b/reference/6/Microsoft.PowerShell.Utility/Import-Clixml.md @@ -17,14 +17,12 @@ Imports a CLIXML file and creates corresponding objects in Windows PowerShell. ### ByPath (Default) ``` -Import-Clixml [-Path] [-InformationAction ] [-InformationVariable ] - [-IncludeTotalCount] [-Skip ] [-First ] [] +Import-Clixml [-Path] [-IncludeTotalCount] [-Skip ] [-First ] [] ``` ### ByLiteralPath ``` -Import-Clixml -LiteralPath [-InformationAction ] [-InformationVariable ] - [-IncludeTotalCount] [-Skip ] [-First ] [] +Import-Clixml -LiteralPath [-IncludeTotalCount] [-Skip ] [-First ] [] ``` ## DESCRIPTION @@ -36,20 +34,22 @@ For an example of how to do this, see Example 2. ## EXAMPLES ### Example 1: Import a serialized file and recreate an object -``` -PS C:\> Get-Process | Export-Clixml pi.xml -PS C:\> $Processes = Import-Clixml pi.xml + +```powershell +Get-Process | Export-Clixml pi.xml +$Processes = Import-Clixml pi.xml ``` This command uses the Export-Clixml cmdlet to save a serialized copy of the process information returned by Get-Process. It then uses **Import-Clixml** to retrieve the contents of the serialized file and re-create an object that is stored in the $Processes variable. ### Example 2: Import a secure credential object -``` -PS C:\> $Credxmlpath = Join-Path (Split-Path $Profile) TestScript.ps1.credential -PS C:\> $Credential | Export-CliXml $Credxmlpath -PS C:\> $Credxmlpath = Join-Path (Split-Path $Profile) TestScript.ps1.credential -PS C:\> $Credential = Import-CliXml $Credxmlpath + +```powershell +$Credxmlpath = Join-Path (Split-Path $Profile) TestScript.ps1.credential +$Credential | Export-CliXml $Credxmlpath +$Credxmlpath = Join-Path (Split-Path $Profile) TestScript.ps1.credential +$Credential = Import-CliXml $Credxmlpath ``` The **Export-CliXml** cmdlet encrypts credential objects by using the Windows Data Protection APIhttp://msdn.microsoft.com/library/windows/apps/xaml/hh464970.aspx. @@ -68,33 +68,6 @@ This eliminates the risk of exposing plain-text passwords in your script. ## PARAMETERS -### -InformationAction -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: infa -Accepted values: SilentlyContinue, Stop, Continue, Inquire, Ignore, Suspend - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -InformationVariable -```yaml -Type: String -Parameter Sets: (All) -Aliases: iv - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Path Specifies the XML files. @@ -179,7 +152,7 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS @@ -202,5 +175,9 @@ You can pipe a string that contains a path to **Import-Clixml**. [Securely Store Credentials on Disk](http://powershellcookbook.com/recipe/PukO/securely-store-credentials-on-disk) +[ConvertTo-Clixml](ConvertTo-Clixml.md) + +[ConvertFrom-Clixml](ConvertFrom-Clixml.md) + [Export-Clixml](Export-Clixml.md) From d9aa756da6f656fc4c0f63f0016d9a0b2cc98556 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 9 Jan 2018 13:33:41 -0800 Subject: [PATCH 162/188] fix broken link (#2024) --- .../3.0/Microsoft.PowerShell.Core/About/about_Functions.md | 2 +- .../4.0/Microsoft.PowerShell.Core/About/about_Functions.md | 2 +- .../5.0/Microsoft.PowerShell.Core/About/about_Functions.md | 2 +- .../5.1/Microsoft.PowerShell.Core/About/about_Functions.md | 2 +- reference/6/Microsoft.PowerShell.Core/About/about_Functions.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md index 676287f49608..0b80ce4a75bd 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md @@ -223,7 +223,7 @@ function Get-SmallFiles { ``` For more information about the PSDefaultValue attribute class, see -[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN. +[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN. ### Positional Parameters diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions.md index 676287f49608..0b80ce4a75bd 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions.md @@ -223,7 +223,7 @@ function Get-SmallFiles { ``` For more information about the PSDefaultValue attribute class, see -[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN. +[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN. ### Positional Parameters diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions.md index 676287f49608..0b80ce4a75bd 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions.md @@ -223,7 +223,7 @@ function Get-SmallFiles { ``` For more information about the PSDefaultValue attribute class, see -[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN. +[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN. ### Positional Parameters diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md index 676287f49608..0b80ce4a75bd 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md @@ -223,7 +223,7 @@ function Get-SmallFiles { ``` For more information about the PSDefaultValue attribute class, see -[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN. +[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN. ### Positional Parameters diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/6/Microsoft.PowerShell.Core/About/about_Functions.md index 676287f49608..0b80ce4a75bd 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Functions.md @@ -223,7 +223,7 @@ function Get-SmallFiles { ``` For more information about the PSDefaultValue attribute class, see -[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN. +[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN. ### Positional Parameters From 38d2060b7d2d7dca78eeeb028a353ace278fd55a Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 10 Jan 2018 07:58:30 -0800 Subject: [PATCH 163/188] Adding more info to Contributor Guide (#2023) * adding notes about OPS extensions * added notes about OPS extensions and linking * fix typo * fix typo --- contributing/STYLE.md | 93 +++++++++++++++++++++++++--- contributing/WRITING.md | 16 +++-- contributing/images/alert-boxes.png | Bin 0 -> 10272 bytes 3 files changed, 96 insertions(+), 13 deletions(-) create mode 100644 contributing/images/alert-boxes.png diff --git a/contributing/STYLE.md b/contributing/STYLE.md index c17e3e0562a8..1d321f9db02a 100644 --- a/contributing/STYLE.md +++ b/contributing/STYLE.md @@ -111,19 +111,94 @@ to get this output: ## Links -* Avoid using bare URLs. Links should use MarkDown syntax `[friendlyname](url)` -* Links should have a a friendly name when applicable, most likely the title of the linked page - * **Exception**: Links to non-Microsoft sites can be bare URLs +* Avoid using bare URLs. Links should use MarkDown syntax `[friendlyname](url-or-path)` + * **Exception**: Links to non-Microsoft sites can be bare URLs for transparency +* Links must have a friendly name, usually the title of the linked topic * All items in the "related links" section at the bottom should be hyperlinked. +* Use relative links when linking to other content that is hosted on **docs.microsoft.com**. -## Using relative links +### Structure of links on docs.microsoft.com + +Content presented on docs.microsoft.com has the following URL structure: + +``` +https://docs.microsoft.com///[]/[]/[?view=] +``` + +Examples: + +``` +https://docs.microsoft.com/en-us/azure/load-balancer/load-balancer-overview +https://docs.microsoft.com/en-us/powershell/azure/overview?view=azurermps-5.1.1 +``` + +- **\** - identifies the language of the article (example: en-us or de-de) +- **\** - the name of the product or service being documented (example: powerShell, dotnet, or azure) +- **[\]** - (optional) the name of the product's feature or subservice (for example, csharp or load-balancer) +- **[\]** - (optional) the name of a subfolder within a feature +- \ - the name of the article file for the topic (example: load-balancer-overview or overview) +- **[?view=\]** - (optional) the view name used by the version selector for content that has multiple versions available (example: azurermps-5.1.1) + +### Linking to content in the same repo -You should use relative links when linking to other content that is hosted on **docs.microsoft.com**. When the content is in the same repo, the relative links are simple to calculate. -Note that the path to cmdlet reference is created by our publishing system. -There are special rules for linking to reference topics from conceptual topics. +The link target must be the path to the _Markdown file_ in the repo. +For example, the following markdown links to the about_Arrays topic in this repo. + +```Markdown +[about_Arrays](../reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md) +``` + +Here is the live link: + +[about_Arrays](../reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md) + +Note that the live link works within the GitHub view of this content. + +### Linking to content in a different repo + +When the content is in a different repo, the relative links are more complicated. +The link target must be the URL path to the _published article_ on **docs.microsoft.com**. +The relative link starts with the **\** portion of the URL as described above. +You should omit the **[?view=\]** portion unless you need to link to a specific version of the content. + +For example, the following markdown links to the Overview topic for Azure PowerShell. + +```Markdown +[Overview of Azure PowerShell](/powershell/azure/overview) +``` + +Here is the live link: + +[Overview of Azure PowerShell](/powershell/azure/overview) + +Note that the live link does not resolve within the GitHub view of this content. +This link only works on the webpage published to **docs.microsoft.com**. + +## Markdown extensions supported by Open Publishing +The following sections describe supported extensions in Open Publishing. + +### Note, warning, tip, important +Use specific syntax inside a block quote to indicate that the content is a type of note. + +```Markdown +> [!NOTE] +> This is a note. + +> [!WARNING] +> This is a warning. + +> [!TIP] +> This is a tip. + +> [!IMPORTANT] +> This is important. + +``` + +And it will be rendered like this: -\[TO DO\] - document special rules +![alert boxes](./images/alert-boxes.png) ## Next steps @@ -137,4 +212,4 @@ See [Formatting code blocks](FORMATTING-CODE.md). [links]: https://help.github.com/articles/relative-links-in-readmes/ [gfm-spec]: https://github.github.com/gfm/ [semantics]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/ -[platyPS]: https://github.com/PowerShell/platyPS \ No newline at end of file +[platyPS]: https://github.com/PowerShell/platyPS diff --git a/contributing/WRITING.md b/contributing/WRITING.md index 4cab02420487..3b877c853697 100644 --- a/contributing/WRITING.md +++ b/contributing/WRITING.md @@ -1,7 +1,10 @@ # Writing PowerShell documentation One of the easiest ways to contribute to PowerShell is by helping to write and edit documentation. -All of our documentation hosted on GitHub is written using GitHub Flavored Markdown (GFM). +All of our documentation hosted on GitHub is written using *Markdown*. +Markdown is a lightweight markup language with plain text formatting syntax. +Markdown forms the basis of our documentation's conceptual authoring language. +Creating new articles is as easy as writing a simple text file by using your favorite text editor. ## Markdown editors @@ -12,9 +15,9 @@ Here are some Markdown editors you can try out: * [Atom](https://atom.io/) * [Sublime Text](http://www.sublimetext.com/) -## Using GitHub Flavored Markdown +## Get started using Markdown -To get started using GFM, see GitHub's Help topics for [Writing on GitHub][gfm-help]. +To get started using Markdown, see GitHub's Help topics for [Writing on GitHub][gfm-help]. **NOTE:** GitHub recently adopted the CommonMark specification (with GFM extensions) for its Markdown syntax. In the new specification, many spacing rules have changed. @@ -22,6 +25,10 @@ Spaces are significant in GFM. Do not use hard tabs in Markdown. For more detailed information about the Markdown specification, see the [GitHub Flavored Markdown Spec][gfm-spec]. +DocFX, used by OPS, supports DocFX Flavored Markdown (DFM). +DFM is highly compatible with GitHub Flavored Markdown (GFM) and adds some functionality, including cross-reference and file inclusion. +There are [differences between DFM and GFM][dfm-diffs] that can affect content preview in GitHub or your editor. + ## Creating new topics If you want to contribute new documentation, first check for [issues tagged as "in progress"][labels] @@ -53,4 +60,5 @@ Read the [Style Guide](STYLE.md). [gfm-help]: https://help.github.com/categories/writing-on-github/ [gfm-spec]: https://github.github.com/gfm/ [labels]: https://github.com/PowerShell/PowerShell-Docs/labels/in%20progress -[gfm-task]: https://github.github.com/gfm/#task-list-items-extension- \ No newline at end of file +[gfm-task]: https://github.github.com/gfm/#task-list-items-extension- +[dfm-diffs]: http://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#differences-between-dfm-and-gfm \ No newline at end of file diff --git a/contributing/images/alert-boxes.png b/contributing/images/alert-boxes.png new file mode 100644 index 0000000000000000000000000000000000000000..f033cd52ed60ed4942e2443f5fbba690ce507cca GIT binary patch literal 10272 zcmchd2~<-_x9^YIw(UrFJK%(E_(O`==fX- z*nLFjpw1y!J0~9$QhRE7>ICYh%V?L^Q}n={@r!WbmC4!!O)51lCtAnrEN$>N|E5FF zEyMM0M7%osFws&q`tsqet1Ta{`-Oh=#lzEfd-v|$`tv*W-+#UCy*WMn@#CzAaX;vq z9gX@yZ|Lks^M~o3Kd>BwtL7zRY^I;sCuxj_wapx1a4Q4gQqNp(g;`_{yX52OkQ(qZU0DUQMEZ_gXG-qN(g=*pK^)^)lz z<&s-7oXF4K;TeJHtaRl(eN^yZp`^ecBNFyF&wcBk?JCAZK+rTbhq0G3(^VDF`*B;c z!kD_!7g2XXRcLWY(l{e`m{oCeMi{iHbIehzzx~hib$OrdV=sk0McSHH3i=y)Qdb-4 z4e0jO%egCIqBb)U%!4nYW0Y>;MQ<4Ur#q$;WCI!HTcntQGw1hEh?2NZR}~U&HV*6% z$3`fhM404HKF@gH5`%<}(;FPedF>7R{TBm-y1|mb_B?aL7Pzq6F#TICxon_;5xJOZ z$u3?H;5>WuSUGcX**vKwLCI?-6@exA%)%Xng^w?xm_?!iEnfEmrG71ftT!SEj=Qdd z*$y3dIX^5Sci`p*{MF#j!G52=1wc`G$movD%KikDemw#KM`%Of#+G z1y7u3O=9_CNMBAG(#N>iP1+Z+s`AK{nWvAYTAT`0sD*6Xyv6#3RMkDAAZxC!3$yZ@ zDAK_9tKVR4eSPDrJjbe=Y%>+z6#f3b8RPBFTUS6sr#S=@iUIlj!?eV^t<9C~iREDn zH$^J=RoOVtsa3u%rd~5oEv@s;`p%(w?Ss@$SJx*LhP*3kD{#U3_x*W(0Fzz*Mf}&~ zeKS?rbqD_7wBocOhI~7h73RJ&{flKpzb3)(E0o`sg|Znfva~B@Y z@t^lpm{z^sd3J}I>S9PQD=x-&#{0rNDf(^M)#i@sNW9^^gHD3+<-Sf|lYABOI%wj} zir!l{Ay=LDP}q1d;X}4jt}mi?dL}ilK4e+igXuK(g0J9<-D=y@(<9E3&-&(vX(UE z(-zf;?QjmNaP85HEL6t32-gnc6*9N?qe=!a_0)dzl$-r`qA4uxopRraE#P3-U-PuN zEa#`P_4lW?oV{gWGC67OWlch-O(-)<{oNLPH!X((biK6esYil#N#^XL2Ny)zUgKZw zBWR(z-ZFO1oS}lrxH~d?cop=Q-&4kx0hEBztczHWc{CU*iJIeMTggYnQ^h&X3^w=e zvfDMb9LIR%35oKEmTW#CcJaD0^!B2fS1wBfy1i_V7j6x-J1(alTsY;cQXmLdpGaN~ zec1nZJ>W>llG>P}B8_6M(g7=FNkdb3tMGw=&bBWcgI>i}u<+r}7~S>MuWH5mj(cK3 zlsvfma&8)HD5DE0FX*a>a@0D2Dp5roydb{vT&Wlgc* zadzkHY>nJPJ1eh%RR=@wPYP2II>e~9{5CbF1#GUBrsq|lE4`T+OQO=S`_9kBX8QyU zR)(&Ib~@y93}NW{XD7>JXqlRn$5)UcR=jGBE*^@dMw%G9*S5MVgirf?JaeDsKF5J8 z(X8{U)2kEo2QbOk*r}8WYYk0k>+PjBk`*Hn>UB2zDY#B}c0Vd2+Us&k>eb&wl-!UM zn!+}eGBxzw^xar%Ey5;ftNKzE=N;?)X|pUg=JsARhC+bDVk_-#CBV>?v>0_#isYo# zeziE441@UUFlqvM`RzMuUQ$)cnl;6rqx1zC0wp)584)qAn3@6|}WKA0+CcF)9fT zy>)%wZpYcqYtK^{#x93k4+aO5K4jbs_t#8Vi-I8YsxE2kox5qz`mPM3CU=^H?7XS9 za^$(y^8{q==x1FTbo(7Z1CN#awcDHV)IP!oIZ@~h6aOoK@&Bcd|HebdVi z$Mi02S2iecX;skp>f}w@DwOVE`k0(j7)s+05RZYaHdK@sEOATmM@vv&lK>32ThU14 zdpHQNKeB`^LmAhWA_ge41TbmQFPCD+Nj38&l(~m^yc9*ik1RpWum6Jv0LrjM?-z$F z=6k(#9Emb>EuK#3%p-0$-FO-F*TG+mG#rOXPBK+nJZ1t`g_g=A(Flr zgb==dh*h}WeStKoHhh1T?KZgg>=&!;*Rx%x0RLns`Nh=*TlqFD?#@N;_> zLMF+*HNF)Bp=tY0-45CGpS_cH?}Cj!q|>`m z@U{%aT}Gl$pDfN29RS9C0haJGM|hJi3Lf$)PKzB$_`18yq>eaZ;Oy_UbdHj3MfpOG zhsDlY>~{8m3Y}#FgB>1y=;n~4lUyWfsjYt&?GwTb*Z>_@mUnX{j4{?R{2(+`q-DIJ zBEPSQlow9ZR%&c1xm@#HDL9pUqwDp!={D^8j>5|)Y&19PoKgzzWPsLdIu)y7*}A2I zhbnZYpngIHI-V+TQ0yyx9Ul1;` zEzyRPYZPDl#D{)syJ&%!7ep1W;ayLWW;WE)a(C>i8cDrcyxx}Xx_&WxPO->$z4!;? z=daEO*4D&@S7_cE`!iw%tLLT}?((I1PPrP(hNVnoYs9Ht#E4!+r|4A3K5dL9!Edn> z>oB3bds=OACKv1bcn!q|dayxLQMx^?l%_!!S{&RL!9) zeyzFwx6Jiy?O1}BkV^?Ko$6|fyrPT6JGGrI?n)+xdivI7@GW+7W&NDGx_xXM=Nq4$ zQ!S!RVyG!qH)K8GOz~hjH_xd<*!)ZVMtag*Krem`4FBgdjP3PBR$BttMFjqtQbliC2^PqN&8x4 zWCAC!er@fHrpq&dXO%YfB`yr_O%Gu+XOn4uzhr}myj)9tu$|{#;gpk|7cu=9(_6b^ zpnamYv3OJJxrIs2@3l!$B%O@zL&aT6yNq5BwA6x?`eQg)sg5bg+Taj9i&IzxtAQHi zK)+^;>v+WVCGzTL+#<;{H8V%z*Bpu=Vrf5Ls4cO?dlN-7sRtHYJh;1puM?2Et6xnd z)+U9b>B>Gc_%`Qw_ zz+BHIUOEq&J}@ibW*4Y3g+YJT8}2*dKk`RhO#-7CweHoHLDZY6h|;OFpPvM$mcv7B zZZ1IM}kwp}jsJfm_0`r<9gdRmXJOfo&mjlXo?H11&N=Ls54 zlc;Ut5htj!LYHVC9r^rqu$vjkXFNf`W(1tU_6TOSu4T`q&pn+6L3}rVwHA;0YJ6RT z2DJ5nJTja>FblpZC`IS(G7!k{zHBAk&$84Y>_Pw8EHn!(pUkXYHKf z!xUv9pL`qa7@@rPEn%by!%tzU-EUq^>((iC?>c9YW6%NJzM}=K38=tx{5@K!SNEa} zJ!?4rKuJ$rok{l*43@R`_A4~95{Z94>-BxU99rQF?4;d9eK8!qC=ruLdZHxp@Ghf~ zV^w~=S#LmKb}q-YGJEFc3pa&@6JCd0_!-*zQ9j^M#QJ?nyGp!Jd<7>EDu$~9=c08D z7KmG+gAiEK|FUH9Kh8G)+(03RhpJoY?X7ssKIpZ2=(Xv-^>R>cGEUF+wz3GQSTxSS zZiI&DV35PfWJ3Q!(P^zC_sCIT(eIWo`bG@Jpm|4^0ipYq;BFU4mT!Ai{#_OgjYZzS zfUiaSd}haRrk+@YZQS0o-5Q$~QbCD+lA2MdH)w(tU)#$(af@idud80`Kpcs;Cw%#X zYl%2Rd^Sz;8uOT$_Ij{LYE!9Y6K5NQ6MbO=%{I{17xE4zk*)Ig>^#tJsgXuAN;mQ` zXfA(oVh?%%K&)CR(kDGf*BQ+W7LrdZ9~j0z-h(zWeKyWrcf*0uJgum)*b|%LkeB`O z35Xw(NDx0HsuUXi9m+X?8gSZCVLg2h8imuWtJlwOv4vaCy7KGbi@$d$TW?0&Nsaiv zc2kL^#O97Bs{pYznzcZq@n{W*Ej|6H6TN*l`KOan$;g#m zWT%j<_PysZl!jD;xij|_E#bD4Zj#fz`UO}uPbE2e${qLrWnc|G${PBucPjODKNZhJ zVX|d!lDLn$4SVQcyb)~Thv~G_i>45i`cyu0ON2?)?80QhOM4B_XOf#y%Ei(Wf!-??qd zC~8U%N85TRHWKso$fF!CUrJsR`C$L5VV4t#WpC9E$U|I<2Ei6}9eS$Zgr`vOHAUwc^I=@&<`gt$473@65R?H8(tdws(Oy~2k z-^d+vy(wjJ5Ks+^#v3b+vyW1`yT{9U5Tq}UnPep1_D5*<|He%IGqmS2V4``f>9OE? zTN(ecUS#D&(;{9JsispZ%8MfwXdA7EUM$LUJRX!=Ds&TC z*zTd8okNSlPiQ(58zdJJ!6w4-2~HpuH!Tign<^Mnrhy!j!ckFhmA*$mcA?PUdQ_Mq zP4lnLcxFa9K%|Ww{RgY=hcUdna!iu~q&3^(UKBC&XQ#fklucqpbsNP^%CO5$D^js< z4%JirTa=|#W!+#M!j^wv^JW-hDrGKxQI^u&D$Fl_jy07GeNA~3QB^e~OFirKR1(L> zT5Adlxc8LZj|r2?^p-)AbHGh=KTyL9bd~0$`uJ5|$BO&H%mz(SL9ZPN)g`-Jet=%+ z$|;maHX3e~_}ZX@2V2IK2?&#E=?#@ICxTb+Rjg!-+56_%IZ{pv?hE&UY8?wcyhDrQ zod;B@kB#!VHAgTP+w%(^xR6LQam|KKuv`5fBF4sg1{$daaN{eT30h+=H^#%&QcVdT zN?KKn%Svm0fym)KeG-7cO$XJ!Ko1Q#9EgAmWj3WEVOE+eH#M^{I3q^&KC_zBKEh@$*j`(SVI@xb3yD(l|^A%v7p66ofkyW3EmU)rAX07GE(xa zi+FJ@^g;tfFNOi7P19(8hXpoXW;h>FIq{WbP?`7iFtA9g8OzkYftgJ#>T6&nJ0mfm zUpn$3@lXQ_do$LzXT$Wran=_TzrECp(lf=kW)`H1lrcX-j_RNkF%fC98ip2ifwjny z=MDz&r{+J>^bO~?FH$5Ml7Y}Aag@(`Gc_;N*LOpYneOKqEHl6q0XA}>+HwQ%P)|N+ zKriTE-UH(Yfn<*b&i~J-@V~z`{d?YI&7e=7o>#wh>Q%1}ABSGie}i{_s;{-R@1Q<0;Fu(4 zF;ASI-OBd;1^)Fe@BYT^RX;%oZ+=hwYzO$cEVBJcfFIip6;02DG!#715y0j8R{aa0 zr-iD}Uh(?KRt|*1iM@}(o~7VBb6AB(S<%J!N~rB;2@Go3Icgz7E~2IOm?6-lk<(S% zp@Z@NK#SM|;d0>&jk$ZN%gM+y2bZezrLKY6!HtZBpu3h}j=u|K%cJ#a&jlQfC7~>H zM~L#g05z)B2AXP0XE)BaW&~3-1%)SmxL)K=wit>MN%Ej8HDFSClzySYphIRxA zs&f2p8E*x&4hMPx1f-yu@jQ8kmrH5Dn&JMQ;yY5jJj2IJ#bNW0mrlO+``=juy%-vm zD(_qva($R_EddsL%))LNw9kCH_g&L>MU6>vt;&)cb#xwnMpNA*%_q-#GuLb>iJuq$ zy*d4#P@$}mdUus+NBMlsVmAZic0Vge^?P~&snB}H9!J7f8TxZQE1W7@f4>opATn=U344O{?E(30~6pJ~`AHEA| zz^b(1!w@8&*1vlO|5MS90mM;hZ|N%IxF)ip^yMvXr{Cg=NZDZS_hUlPM}`h1u<|C) zrf0S(eq$u_+CtSUn0{zyX8P$rOfLQz(}=k~Ml;<8y{MAYfIf^d8b0H%M)q6yW2His z-33JL`|ZYqG|>h5Nny}f{I>{6@yg-h$Q4jXzC2HWG$`&z^HTjf^6|bg5!dHy=vZQQ zND_UR-9k;>VLbRAQnq4%ui)`unrq29#aNg!cGv zr*-1MUhSYfg3QAhk~X25^lL|AaEKjZbV%ShCwc-zje8ORhq>7)MjX%+;>C-gg2SgFuScP%jENJ%FK1gfZ7{w7-`;&>&p{} zP@if;*}%+|;x4#w_Kjs?$Z(-GLNaM%?NDfItRWR@>0vdGy?Khn9$VC^!xEaSTdo*3 z&7F2cY`nVg@}o)8u4GB+p*kgL`i)OtzhVlpQzGU4{HXzdW$h4BcKj(ft01-Vl=7;n z=cMGAo!i9UT4pvUM^fUxxHwO+>!Yu#vPPW@rf9lqzSG6U^z36n)p54ukh$uX{hxGg zlr>%O^8=EZ%}?qwl|5#(wT!-wlVCC%a7JYfVhT7swB(#B7Hl6t5u~qL^^<;tiE1x! zHqrN)6!jP4=rPLDL6f95wJkV7R^yg9pTmKB+LwvJb&$G;jG(0q640OYBWFBABXENEO!~{D4Zzl*LN?*L}eMpSFbM@ zL@M&y>8T~YEx}LX_y) z$y;QyG3jvJMU>cZ;q<2o;?LX7u(mdEcKE@O_T7=I{ns(-2Hh1SCt1cM0fK1^k z&lGeXir_waZ`>3$g-+`*jrnb&ja;P^ESt=ushmK<@YDK1-kR`2_eLcy`8UZ`w!peh zIjDWMUaP@yzT3$_^;TS8^1Bp&+Mvq)DR~c#*KlQy(@_CltpC5pE*P7~ay!DZMP2wzI&n*}BH6A*yq4B-ul57B(cB zpLfm)gmf&zD@xO-H)BU!XOUkovv&IqW6$d3QLVAmsbr0Gc$^-^z)4)&-@1C^)$S_S zt6^EoZ`Uj-OdqIuCKoz1##;5nnfAXAwF7 zzJESt7G3Jm9sI49@q|_R*FDzRq=GU*2YTGkeLZw7S0099kkmZIU8x)Mgyhf;MN*8* zHY379v09I~Jv*Fkt#1K{G8d$A$F=^NXR5+vMgMk0)Z!U{{v?d z$N1iq?u8K1J0G0qTf&uYs&_iC@>eC(O&-4t`q)4(L`y`I3&_V6lEXS3NAnZsmNb}@ zB(_;?%qTp)%`RFo42Kgsw=HVtObFXp=S6P9^Sw2O3t3cwVeTz;CihmiS*>wOx^6jb zVfykO8qK9ZqV&WzCnUaYaR=HW>X9Ziq$uY+fM-We?b&3t8obg_`&u17FjuM=ggp}$ zfSZMS7s7PTkh139gly9|b#`t_G38vttLlx`zK%`llN+DxL2o`M!cdG_vUA_J4c}Y7 z)}3<X&4uIW(2RMqU{DG4V&`eOZPZ|*hKi{Mmf+3P4g7wyCTdyZ znb;SWJy}t3{xGK75Ky&>=vmD8RqQC;VfG+<(Gcie^1Tw!yS9<;zIbUw+0ZMmhx8pg zQT8IDv~|*%I-g4l4pp>oI^t@n7#go)H3;ycO|sIdtan(A%&thuAiV z&BZ*a!eWVAPx)6dIFU85{1=`p?^$}uZNzQtk($hO%bOoM&S}tdzzckkr8(kM-bvTr F{|{d48_NIy literal 0 HcmV?d00001 From 7298a9ddba56507695c99a49def6aef0b3b48c8b Mon Sep 17 00:00:00 2001 From: Joey Aiello Date: Wed, 10 Jan 2018 11:30:17 -0800 Subject: [PATCH 164/188] Support lifecycle doc (#1994) * first pass of support lifecycle doc * add notes on MIT license * address slee's comments on support lifecycle * respond to lifecycle feedback from Sean * add lifecycle image * Fixed spelling typo * add lifecycle to TOC * respond to feedback on lifecycle * Removed en-us from URLs You need to remove locale paths from URLs. Including en-us forces the reader to English rather than being redirected to the localized version of the article that matches their locale. * add note on 12 months, fix en-us * Fixed typo --- .../PowerShell-Core-Support.md | 97 ++++++++++++++++++ .../images/modern-lifecycle.png | Bin 0 -> 28050 bytes reference/docs-conceptual/toc.yml | 2 + 3 files changed, 99 insertions(+) create mode 100644 reference/docs-conceptual/PowerShell-Core-Support.md create mode 100644 reference/docs-conceptual/images/modern-lifecycle.png diff --git a/reference/docs-conceptual/PowerShell-Core-Support.md b/reference/docs-conceptual/PowerShell-Core-Support.md new file mode 100644 index 000000000000..74656d24f813 --- /dev/null +++ b/reference/docs-conceptual/PowerShell-Core-Support.md @@ -0,0 +1,97 @@ +# PowerShell Core Support Lifecycle + +PowerShell Core is a distinct set of tools and components that is shipped, installed, and configured separately from Windows PowerShell. +Therefore, PowerShell Core is not included in the Windows 7/8.1/10 or Windows Server licensing agreements. + +However, PowerShell Core is supported under traditional Microsoft support agreements, including [Premier][], [Microsoft Enterprise Agreements][enterprise-agreement], and [Microsoft Software Assurance][assurance]. +You can also pay for [assisted support][] for PowerShell Core by filing a support request for your problem. + +We also offer [community support][] on GitHub where you can file an issue, bug, or feature request. +Alternatively, you may find help from other members of the community on the general [Microsoft Community][] or the Microsoft [PowerShell Tech Community][]. +We offer no guarantee there that your issue will be addressed or resolved in a timely manner. +If you have a problem that requires immediate attention, +you should use the traditional, paid support options. + +## Lifecycle of PowerShell Core + +PowerShell Core is adopting the [Microsoft Modern Lifecycle Policy][modern]. +This support lifecycle is intended to keep customers up-to-date with the latest versions. + +The version 6.x branch of PowerShell Core will be updated approximately once every six months (e.g. 6.0, 6.1, 6.2, etc.) + +> [!IMPORTANT] +> You must update within six months after each new minor version release to continue receiving support. + +For example, if PowerShell Core 6.1 is released on July 1st, 2018, +you would be expected to update to PowerShell Core 6.1 by January 1st, 2019 to maintain support. + +![PowerShell Core branch lifecycle][lifecycle-chart] + +The Modern Lifecycle Policy also requires that Microsoft give customers 12 months notice before discontinuing support for a product (i.e. PowerShell Core). + +Eventually, we expect PowerShell Core will adopt the "long-term servicing" approach where we would require only servicing and security updates to stay in support on a specific branch/version of 6.x. + +## Supported platforms + +PowerShell Core is officially supported on the following platforms: + +* Windows 7, 8.1, and 10 +* Windows Server 2008 R2, 2012 R2, 2016 +* [Windows Server Semi-Annual Channel][semi-annual] +* Ubuntu 14.04, 16.04, and 17.04 +* Debian 8.7+, and 9 +* CentOS 7 +* Red Hat Enterprise Linux 7 +* OpenSUSE 42.2 +* Fedora 25, 26 +* macOS 10.12+ + +Our community has also contributed packages for the following platforms, +but they are not officially suppported: + +* Arch Linux +* Kali Linux +* AppImage (works on multiple Linux platforms) + +## Notes on licensing + +PowerShell Core is released under the [MIT license][]. +Under this license, and in the absence of a paid support agreement, +users are limited to [community support][]. +With community support, Microsoft makes no guarantees of responsiveness or fixes. + +## Windows PowerShell Module + +Support for PowerShell Core does not extend to other product modules unless those modules explicitly support PowerShell Core. +For example, using the `ActiveDirectory` module that ships as part of Windows Server is an unsupported scenario. + +However, modules that do not explicitly support PowerShell Core may be compatible in some cases. +By installing the [`WindowsPSModulePath`][] module, +you can append the Windows PowerShell `PSModulePath` to your PowerShell Core `PSModulePath`. + +First, install the `WindowsPSModulePath` module from the PowerShell Gallery: + +```powershell +# Add `-Scope CurrentUser` if you're installing as non-admin +Install-Module WindowsPSModulePath -Force +``` + +After installing this module, run the `Add-WindowsPSModulePath` cmdlet to add the Windows PowerShell `PSModulePath` to PowerShell Core: + +```powershell +# Add this line to your profile if you always want Windows PowerShell PSModulePath +Add-WindowsPSModulePath +``` + +[Premier]: https://www.microsoft.com/en-us/microsoftservices/support.aspx +[enterprise-agreement]: https://www.microsoft.com/en-us/licensing/licensing-programs/enterprise.aspx +[assurance]: https://www.microsoft.com/en-us/licensing/licensing-programs/software-assurance-default.aspx +[community support]: https://github.com/powershell/powershell/issues +[Microsoft Community]: https://answers.microsoft.com/ +[PowerShell Tech Community]: https://techcommunity.microsoft.com/t5/PowerShell/ct-p/WindowsPowerShell +[assisted support]: https://support.microsoft.com/assistedsupportproducts +[modern]: https://support.microsoft.com/help/30881/modern-lifecycle-policy +[lifecycle-chart]: ./images/modern-lifecycle.png +[semi-annual]: https://docs.microsoft.com/windows-server/get-started/semi-annual-channel-overview +[MIT license]: https://github.com/PowerShell/PowerShell/blob/master/LICENSE.txt +[`WindowsPSModulePath`]: https://www.powershellgallery.com/packages/WindowsPSModulePath/ diff --git a/reference/docs-conceptual/images/modern-lifecycle.png b/reference/docs-conceptual/images/modern-lifecycle.png new file mode 100644 index 0000000000000000000000000000000000000000..b9283dc6a6517dda226d08adb34762fb1855cbd8 GIT binary patch literal 28050 zcmeFZ2UycdyEcxif}+A&0F~xiV5O=ky(p+yXi6_3A_`K2KA=JF{ zqxP*^?FK&Yb-7{c#>OTX!uq!(YHa=?8=I5p&8t@oyeuhr2J$riitq{pC2``kNaGB* zsU&}n(ZOyT*#Zgv#9yT?uU0hL*w!?O>~XYq>2)cTX#Dp5O!rQYqvOt{c@KCG(>d#J z?)QFTw99(dKR3_rX^1kXSB`B-CYfRYP15i3N6#){CKlUiArsv>iqLYOkGA7k`i9Ip zaiC#rY$pv6o9}nT3|Q|^e&rEky3M(1yZr*OIY_~oMJsx<=`64NtIEf*Q3>rw0QdG5}Z7LR6lf4z@CRR zAuUBY|omWFBuNsf61(2oY2=J$5q5yxFc_Qxh$uYF7j?w7t9 zINL(o9YMP1!Ybzpzk+?RqJ@jul(drIfNdOSaevt{tMzc!cWi445u8wa9{Xb4MXkAk zmW-^Jbd2x%W-mIER(MD*Be`-5#s}=?@^CrnNhP!ebeJ&fIr;3)z$9Gv-R{?X*A3VF zdR%l_e|-W|a1J(8Llg~IN}i=iAEBr;yLYBoRzMth?A>k@FXpM|nD^LAZVqM@T%b%{ z(opbGbi3gP?ek_2IwNAUZUwz@FZ@!}>gn&iG7!3`k8CNW-5ESK
  • s^IuI+aE(E@brI=?`(HH#TZU1 zbB&a;z7An5(m7bQKIwE3;~~*0mmhA8iMl_u5K>+6K4kf(8`ibxQ}K&M2obM~5JHeiVAMk~+|)x||=?#SHj~&GnPI z_8s_3p!^r30zeSa(}SlW^sccAbd3ZY;#Y*8z5!zMNd?VdP9^VhGwdSC@HKVp1EC1H zlMAY7*%VS9XMD&xh4a$2V6n}1yBQ$z!WO&IGQ|rNk#ZFB6OE+Eo(1^KSj=xdmxB{N zsPh~IUX2Q32EEm*nVBSlcd?Hdq`zlJh@v2JOatE}z84v^rMOYsd<)|UbLH1v;kw3D zu2i{j=~n5UmOar;zd#gm!+vFEsI`hkdyFMWRb?GC9hM$fXGaOS2X_@if7f6`4x|JA0bGBl()f zA14~7iQ)JU6w8BmkJ-JWv^(Ex?vO0deBFXq}Z2gB#qV$D%uT)lXK!{ zz3-N$7$DAy8L+HeQMsx7+4f9oLOo^`lnhfI@7u2A|M!O|0iFM+A>{3q?_hf704Xf#ob$S>X zk2S|bOIY9JBQugb_AfaNS)+e?0-*;#^!B-RmIV44G*3R?ak4v0yRVxPJ$)W>(ZF-W z8#}bm`3BZI@M1Qhv)uifdc%UdY|w2dh;!PXKn_C9Sbj< zxcOa3e~VLce)lI^laHahrHenyAV|Y#ybEFgp@)VW#nqy^qOi0;LWr0|D|(}7K!FZ_ zNxY~836w6>JzjY)a{!73x-)Hy&o3FBjVyT#N{_XOl}}g4OzBl0YQ6tk+K{=Upn; zUmI2gi917$ay?$bpY4sZS<>INvn13#hw%_b$)fnuhC=qKrK{q4Gsp%qz3DB9&@*9A zVYMi!CYDp{Y;o!fd?k(}4=s!lpCCtdOI%}u4itNtsltm0-;);hewwI@r8l&@aqKLK z&(-75i0}woR5Qr%8NFN_81KsETNE#&W0r{Mv&}XljC^zZ^Ku4vp38;qUm~4|V;aTJ88&${#k5PGyK8ll+{@J@ zr+x00GPh1N>no#AO( zdSM{0x$P3PLr@G?L$S~*J+;+#{VUgwzI~=rCk2JaTD*EUGo7iyEpKqXx3g)%e;vOJ zo!|S+e2n|yeZIVOIzMkg-Q}kCy>U^e_bf{+qq8A-5bb1l6ld|d zk&mzTZix)P+#h~E4-#-ebk3Wp;xH9&T*S6CBKR@>Lf5>UHf889u|FEVrRTy)GaONa z<7&jeg#C1lEiQYslW9M%PW8uNPu&#S52#Z`dsqUaC@B2KYN!KB% zbVGRBM(@XjZ!-x|<5C+|K~J_lc7?Bd**I)5?*!V{VP{J2vqn$D@nJh}Ff%k){lK_I zbNV}vbF&NG8=aYYL4C2FGa+su5lEvna&_E>IrGXg!~PdBPuR9HLDfBmh~W3V$BzUW zrt;w|yMiQO{^dK@xa;<#dSJ5s7jnS|jkx==0}Y$47LRt)J&QfY$DV|ZWgZX2D1#*i zc1C9%N1u(E$mQ%NRrRJSq}z1q*!6H057^qID9uaaKExq5{PQ2v6(O+2P>-Mez+wh7 z@>{&5Y~a~KZjYP?ttRA>>9AE2nLamDmB$s<^#G42SNB=l+UeYxqE|QFo4cPlXOR(! zJo=vC1bW16*P&!;RiAwwU3V+~Lx$L7&m`2Y9?A)E>!4Zk$JqXw znJs=h=1k_SwDj)jdH|Z|Gm1{lC~vWOBTgRZbuqv$BJiT|8gM6$D zRS=bfoL0G4giFF`;UQ8|wR5-5L6O+!oSQQ*I!1z!33c!;|6wO+uSZz5DKH(|+Rz`x za3+^br`;++AD{2U@%swftwpyccTK)cn^3^2+-p*94$XTdFYl9T2L+;-vy4IP7%sJhoTjkKRVR z6$uY^quVf&E9G{y1T-bVbvgTb`bCwtyti7hQE2~tq589~Ng>brxJ24j1nw>H+e!N9 zMjXw0{+;X2U$>t$#pOUY*%7BXUg8bgy7nlDx#>Q+A$_ z%RwXMotM@iy1v$E^(2+7_OmVTY(2|FRGXZM>gzbP#e`&g$lhsvxbrS^PUxmN zw#jZvp9QhOlNp|6t>)$AZm<667grt<7sQvuD;Y0&*mnZoK>}N_9SH)4@BU?+-xr? ze(F{BrN=p7I7P4~iE$GMk;Bao>QO(dQ3rJ|ia9Eid)8@$aiV+am?Rx0N$G2HP+I8P z6?obQynFD{wvmKNnipIWcPjo6v^0Pm8eh6#4ILG!ZFL-$=w#fR3%%YM`K{%nTu3`l z!lKP)#T+%3t{0u86?#=~teD;{#>I2V`fwNR{JDvoQ=e zVT!F-r1Ga`>i#w5%)_v9JJ5Qb@ zuI20QN4>ZqwE9I8%T&Tn2=_q0pH+YxBA6}2)oSosi*zXKytMjRG>`!aSds~fIQd2+ zHU&)&25&$QzSd<9PpB@{rW|uT@>*-5Ex>10l1N38%IDrD>IKt@foqy%VYVk0jAm)Z zjOY3svP+GPZFP0H3Ar92%%spcPRL-FVPN`@CsU2eoqiPn>40sO7~2D#U`_>nxQ-qG z3GM!$&;PCd2ySCEP}O`F%&FXLmjehJ(a4RFKz~Cf+k@-Dioe64fAlSY)V3NR4kxd} zh%0GEq{dN9v%qQKEFR!J0%$7r$(z z=QOn|HG~QYQ}!zL^8hi~+2mujo8m2hrFYvJ&nlSvlekI34rt-h)qMGnt)czwsG*D zCIEmB*`(Qjv$ch>FMfwflMXx$5*|>Nr&dSDQDZ$`Ri^@QXYH^2%`G`gharCb_Odip zmwPT=kVbp!;UjEzo6n2bfAcYY)NAL#6)@e4PESbBD323nixdOtbM?GrUslcQApTM? z^i_90C4AEkI%aNLPJ0@hV||KS#}NLL z92~%6oki{hMXJOXP5jzW>F42b2YF4BE3nkh09#Eg)Y~zHIHWx}Zn-u&kO;I-?E0F6 zLC&AGRIn!n?3sETDfrH$g_BL-dd1$P(qn;bJLQn^{bnu+nR=S$W>0>YKAd$$SZ&Zf z&eoXv+(}cx<9&drq5ZFHLu~i8AKia#_b_E=)`q*|Q_>_kT~^~0;pXmFA2!=&^e_@5 z5IDJ~p%U;j5B%U-pg$Fnd0%A@&;wE(Ue|?mj`uRET1YsPGm5Tl8%qLgcUk>r+3!i@ z?iiFN4u+~N@9MA?QlcwnOzt$?@g(RNL|v}wS||4}`1vZ55##flj_+KlA*+;+Hvu z%ZS4FI9LO`XIvHG-mD$Dn@#5{!SfrMDkOh~_4m01^i;#l=M>jy>m5&`FN{cSJoXjd zgVk-J^Dw5%G5Cdi`CvM-`V@>#C=WBqF9ynBZt3n;) zV?gPY%#IL38^UK?94V_8)}3G+x<#8*my3+`*nr8REP|R~J{z*v;oJBt%aXM|O3hqX zVd2~>S;~-%W^$fyu$g7{k6CRjX$E(m{aMY!1U}GRGUjSC-lA*r90m$xSX7yv=FflvnE?8FJBK} ztv{u&)70@g*y=ExPc3Khm!LwM6z^*jSFKD)(pMy#`Mo1Y3=q+B?GV8MLj+pb+_y5@ zVLYU%K{tV^6TV48X*r1DWLHe%kV;gA}8G_>^4EqcV+IS?1L12}Skbel00O3ui%dV}!4uIVtzX+BI1|&xX6l zSS9T#zBHCfYSHLn94{I?ltFz-;g)`x+W*zrp>8toGnvp2ro58ap9(;j_M?3sNWFmq z*H>x3IghItjnzjnXfRGF)>>}D3Hjxm<<}oW+v$;JCDm^xV@Zw>GCAE_=wEk7n#z?? zb57B#^O%Tc^6U_gy{i@FYB0TJO>p2yvvi7zsp_7WI1cVO!VmA@aPg;3S{07Ebyi$L z#)^Fuug+?)(Ibw)Q+!HFJCSA z+7mdWk7b51%bfS?Hj|NhM0&>najsey3+#F}S&7wdh}v3jgX*$B+vVKKwNpg374p*; z4`LuIL+Pv^L#@5;Z<1iHhk!Nn@;LDSc+KC>9IsCT(fUgwr{U?vKaR6^S^MdDefY}< zLVut@FA;iHxXvzmk}>jSwlp6#&0o+3p+s6nK5^hu0{FMBzieK$*RSF+P3nOyL#yC3 zhymx>{{cdr{h%Iva3U-7iSI-g$qr)&1`yK7a)$U<%*s=3U5_$6E9h z_b+|@oSx;=);>@LfgA4^;IuSv~g1(vWO5zVe#S#n2WKy498={_3c`U;Cs#X52-6d(&o6?bjvn)sj-M*c|MO`H~PZE<%5L)8tQ0 znC5sb+Lh~vv77_O_tN1rq9%72`okKBQ~A|+$VnM^Z)0^3Uvx=?yxy(Gkb z_BwIes3)qrK2+p!iFXRw&ye5{SouixI;~wcRPw4|*-sDa`uOejGM{U-z|7me9Fwy- z05$Is(23kOhF>v8ytd@7wA=f5kEXrMb4FE144{+^XgaF_JiSi3*^I%unUt(U(*ikq zsmAx-Q{*@_@I4M(qMF;r=?veZV(EQkxda*YNCkD?zLYAEWPt{GL4#0Yp1u(ks9j~xpK31TXWL}OC#XVg5&G%m8MiW=|8A}x@aKx#p^!Q@|+FKw2QbjA;#ldTw5<*H_CGqW|eeIm~;fG zF!*@8hn2mX99@j}Xspa@Ux5{-=%e-ACB1OB4)(%O_RM3Um_#ca!+X zVCSv%RpuSIJh#t9pdE^(WvHio&W{mJl%e*YWR4cLWLJxd$`q>Mr#KBnG*$okF_D*r z%Um;GnqI4;AO;=ugF#)@(56F&FZJbc^AH9IO;+d%)9609dQ$mMjd1pm!GChzv4Gp2 zfn6W!oGDiK502z;8}46TD)5u@L-}JYlQ`t6guf&mE$U5}{y+7j+Oph1#AHfU1 z97n4f&&mQ#09G5IFWFuxu;yl?)z+LR!Ogr0V5ai0T}a;+seWHHL}{EY|VeS^$vU)I7-xRFS|nAKyD%I#fvZDz>)t)PmTZ^ zz9@c6(KA3RPThgmfQsb77$9RLo|Q4;AyfCF>j|>E$>Vc-L=|Q;o&%;JEjM~;OS~VP zJ;<@|V+nM;FcU~w`8@Q7g@HK(aXzkiH~1aZ2V<5@oUegAuC&PM`5s~hQU$pS+dnSL z4TR=#QVSG7Ch$n7aPvekZ{du#?;o}6Qds>4OSt}TzyvXG~?(e!fed0Q^^!O&Spv4n6bY`+% zY&1^g&b{y$oAu~!-1&Vp1DI>NTs)+WubkAN6d{X0x_2h;(ZTKqP|I2GkkdZp?;Di! zIicNr61^cSNoA?i>4bNGw+JV_Sw$0uRN~=3-B$w`|#%cEABj6m01_~beq=b zy6!yo=O$WwnrG@6b>mxjurx@c8aM_;@eGlO#RQ{xKe&dlTDBz$SOJ_oJc}=+4%{`l z+hK1OhiOTSiSIoo{N49upU&&%^;Gd1(&Kn4@}+{KkhK{zx4X4Mz$M?pa0D4QaYa1N zqN`UsL)p_X&xoU5s72vYmd7o$5dyC&vo;tCf%9UnQfI>=I(xha5_K4f=P9kcMaJsX+8jUBJ3v?nNe=lz9*S^%1y=5u$}`= z{z1;Ug6FdvpZPAM54kN#wBVP%7n-7jqZk2s$#?w4*Lvw+2|KUf#`iVh7~{hi5-%4r zn@yqm{Tb>9=wmZ)54vH4?cLT7wP0J#eWIKMZ_cgv*;z&Nqg7qx{uc7B7_m-DPW$?K zY->FvA63g@Ntul{ZO*r2Y`#%A;Oyc8zWWZL8ur_&Cf>>LU$T|{u0pELu35-klUHg3 zsK9(N+$yog#(e1z#U&}ErbFh<#=E`vDGvoso#<_m_NyRok>kK#`=ZzP^LdU~!T77t z=d(KU6g)8Yydg%kP*j)IfF!%EDUh9|Hd_Fq9B8{>^Z38chKWf*Q7Tk{Cr0PKH*#}% zKKWbi0CRMudw{!m+P;!f2V^(k-%n*lNp7G)>n2mvX&n}#g^_Y01R+{6P;%hz! z?VO={4qO_WHjU7+^GUWk8!sj7N#{MZNx|(d6x90QD_=D#x8NT(bn~Zqw`vfOvbJ^S z83L6YxFOCrc?(6U%o3kXAW~-zL%tTcu8(8G1ktJGheICTKTT>!TD zh(Z>5bZl{2s^_z9AI1DdiccK5;tc)V(^a0#jkjwz{^qk}vl92<<8Pg7Tg6ulm9F-@ z&WVK<8%stw-m0RGU9fm{KxzPTb2R01CPkY~&|ECBfuM=lHR#5Yv!dWOpK;wDd!rX&s=o+gavps1=F~_35h2^7k<3O9uQ8#?SR?e2=DaetQ|qa`@Ql;>1876^j*5qG-I z)-0DL(&sqa)_I5H5a&k}8w~i$RPqvQ?y;YeTgcKYYuJ9e`Y)YJ|Md>&FK5l&Pnx%T z&!0PkANivHcHaXWmhW05AemLV+*0wZGk+|Ev0O+e>atyqWi@(&tTxvvhC`608R=?^ zk|{oI#5L?j7B?d$aP_-1>x`bf3L{eM)mFZ6v-Sifs{_or6z&b56DLi_+WeZ*bFoV) zr24tfiJ!%A*cGPEr z??GUexnk$D#wqhq2JD+rI&GmZdMwDE`Y1k(!xo~-FVHKzT3tKl5)#o~GFP`K7o?hZ zbe(jK0gLcH)s_z&Knf(!XMGmOWodS);`{q?`3z1d%KA2o@)}U~`fzR2^Z1WC5bEtw zSJHb1eblr}f@DLM3h-^ts917f`pP0VvJhuwKPh)=Jx#q4{4dJ(b|`X z6xqN|)a*P1mg|}P4#UiBBA@S&WkDODYOz+n9%Jbe^cSngw1xTFdk-h6h69L_7EApg zAc5I4Hy~ZkXs@agnLTj6LLslucIM0C^qK^2UaU~R&DCAUy5TtwDYqfb=h2U;GVQSL z4YL*@m)amo`fg`SQY873?kqvYE#;c5CnA+QUyI> z0OFdBZQ5bOcP=`~5(0nJSs#h{#XieMQY*Zo-4HSM6u{KUK(-ZQ;6^$uSI<+;V}x|a zExup*-G==pl>E*^Vd4UHIIYGjz2_3l&<7cPT#{ZQmo`vy%Qq#UtF2YQyCfALV;vkC zBAvu>Dv>!ckWr$5`NVL(+yV>MuG&c8geo!UQXNwV#BnFNTNC`pd6Eu0S!G~%6`zBQ zu14y?bqH70JRCvr8K~pbYJqctu#~Wx-G`Q$!87#Go;NXmgUWXb&3P63rg)z9 z-0X_l{Z8M#^=O%QjqO~~Q-xEr!*e|LizZK3`up>(vsn0X5KkQ?Y0Zh2XfeEr+Fo_) zaXz&h@1Ab#&{MSRjN&G@SL;QeQd7$EIGSR0e>6#;Lfxsn$)#hbb%V1Q4nmmi6_nj1 zcib+4z+S@sAapTkG+Z^W8^EhM-m!DY-oBM(tfL)1SoC3x3p22uu1RQti{oqpGKO8J zdkfSVjkANZy+a?0h@T99urT^g+N%g3$~P#MT@rPbUUh%1Hf$JCf*deAujn{ej#@TW zIt{CT6lj)k+*=cHIwwRkz$X~r=IQVs>KZ8w%kB2{nxAa!e%VeK;^S^5OcTsw zjw;-Nm#Emek0w!kPcaev$^q^S$Oe`0JFs1SfL^t?f#2IRBwG)%pw*qisAl{i(VU6e z^r|8N^A6c*grJi8ICPi2)+f7&eas)I`7-_^x0Vv&%bNUT#JZeb2GHDQ^Z3$sFvnMkX*jXMJY*0p*AgqgHsGr2_#V?bw%C_9KDEj( z4$!I3xdVJ$8n2#?KEkxmWbWO~_Tc6w)L~fpJt)NpejQl(U0GTX7ODXV8N@abSXM6o z4^-pi$-CD!!ElzKV{^*^)ROrF3}!;XPSBo(B@Fm~ecYWjwt9ZX z3Jf6Ntp-F9tU|jFk6Qc6gqZCB|7gv9s%mcuX64oO~Y&{bT#eG}X~FCqx2I#}|H|7amkjjU6) zB9I{ZR{_bh>jk|zs>&50h8_m&>*@FSL)YpDLHB%l@b#H$VTQ%nZ*sH^&r?gcy3!&J z@Mh)0=4(|>r8q2obi=-#lab|fJLsrvA$$Nx1ZL?+{xVco9?O<|E)X|C&G3S;W=L5I z2&G%#gYMJAE3aW6p@h@aBXlk}hiH@&3Niio36lSldu{F9vH>0O;9Io8CmX%hi@V$r zqgS_ghUb-bUI!9MN3vZnt-rkWKnRIz)(`_Cd%o&`be~@HPz@s8QMO$8XB+?Ilfee$8FD&GR;+Bp12}e|G6jm*jF-li|RPG!_Eo0Dr z9*;B-NvVhXQS+r67M*~joVXvzE>{9@Uwq-^66hOreb@E4+0@-2~WF?P)o37odE7LG#WX2M->d+_pOnz_11Ro|be;8L<^o{Sm%)yCDk za&o*o@JrQ~9WE(Ac)oh|<6pew*GGF#U9;%P7fC3eiCk#MT^fWx=X4<6;L>0Jq>Gbk zOI){zKJ3g%d`}j*30ay7Q<%LyMJ+MU-xV{x-9JV}vzJdkG&Lrj=`YH7nP*Rqynr(~ zw40LqLDbCi3?;lR#!+TXGx#>xcWPGFzr)+O;M`*PD~@gPCT4mUhdG#dN*M-tt?ZJRnzFDWMNbWGxOwuE(c1H8(15oF!rsqARJJ0t4aQ{tj$rN&>rIr_CyTcqM#byvz zC|Uqt`mrLm4GNYPNo3pBULN*xrRr0t)i%#6xXxFHRSO#Re$82cIslHIJe!p6raBIZ zF;`xGk6Zmqee!!Z)qWWtHWP3+6_qSDffdF7iBDin>dkXBD?I-bpYWfoyJxoZ2^T{D zvQGbdK4HsG|2>}&{|BKB*dOzcd_v>tzbyU#%qP6D`-`pr!6$4f`v;$JL-{X-c_kSz zMxOWF486hkBO!IOGZ%97z?k*?*(u4Z_~~xRE0P#0T5SV5%M7hPbNICuK#rpyJ+Abb z=*qf4Zn}n{*t|TLwF8_JM|qLT|I`;?Xjvn2Ay@CVp;P|@ayz2#)9Q1`F@P9h88TB) zGPDn1HjSGWl`K~zTUk!Ju9wx69yX&PDb+(oav8xbWz+YuV425Zi%s{tF?Nv3u;}#* zyt;DHPHE-wwzh&mgn))K;c`Z{rvjumtA|WSUn%K`M&P z0FB=?WrzTTv*rD6r$uRoSDB;k#`4bj7SzfUJYqBe_S~|t0-&p8O~PQEYZgW$@bq?# zjg|od_QA^qz{1xqZ(BLXHtB_W&e^#hrR?%PqKJx6eEvx9cy=f~Qqn)KQ9A(M;8b#`#(b zH7%kfoNWACmxe4E%;VOpTwk;S%1QE8xaVuV;^R$-bw7Oj(Vq&N7ST)^r*=zbQb#V3 z+St~t>N#wVxF&svv37rC2}+QiID9RJsPi~>p>#-J6#Hu_|Mn?9lV=jqh2JOK{U9_1 znoF)l@2nlmx{}j3K)_>!5>-56$B)G13RmoBm#*L27DHNjxr2o79$SMYXe8`6#~dp> zPT|#*TMoXh7m_Y`e#9JcRr(HTNwNy9~E};>CA<@x5QaRy&*Tl4|nDMhi<-PG#ji2&+T}A=Y3z`cy{?& ziUFLR;p+MIMHx}OSRo*E96TY3X()+2?X}@(c24CV-L4zbSJLTW{;zd5w~8s}YvZ|X z4eW&(eYd@$e9mR%4Nj}JwgM)*11V@5sJuRaD^jwUfG;g{Y16H*@9upmAmYgr>zvRy2)y3_ax4*m z+?8>H=3E1nHJPP2{4&msO%cBY5ad9nCP0h+C2|8ql{M59qJ}HTS}hsK{hQ9F82Wde z4XI{}&L%EO>F+w5zR9$7^)c1$%Sl=7c((~?ssx_{9Rn?*3I4;{g+`IYbUCK@aMxu*iG$GmyVo(>r)v9MINK zK%3ec?f;Ut20vIL4SCc6`Nf9>%3X||DW~={*OzEQS-vU!ci${@$bP?FV1w`a4}nb< zjU}+jx}W)XfsI3NQdZBY$p3=CM#Aq;fz3oqD&&-K1AAI0(*QL+i?@UW9B!Ke3qd?`S_p^ zyH*~*4=#6u)Q;Ak*4>{DaEe=wV?Z3`Y?xZev@kka1hVR`^+lndxkfwB1sKaa>g}t3 zTXF%QK?Dg(Ah}w?>63D0ZSk8m4Hn$6Ah=ur#AZtw6Mi4wP3Du^r4>uxOwkR4zX}3u z;+8YEYe=xb4`+Ybd1!IaHDOCbgf@JhGL`thA^JxBt;U-0%sdKQTZ44J;>@|-18GAM2SdT(l`4`I5 zu_Np zib1^P>ygHe`>RnWHb_{Bg$ZVV+lw1Ut7}9CHgMFM$owN0@LU~u=S%GV{VcLTVFJ5> zX3_#zds6nxzPur_nm}XV!pL!~1V0@>q6%L5*0wQ>UCUvPi86aORX9MA&9;FwzJS%9 zYgb>cM{LrYW6YZDRoJw;IEe;?${e7$8_T`2bSo-GI*Gl?-c-xq0`-4mKXKQLP^& z11IncAd4T+kg$jdK=#bTrUzFCbR;aY;{T{e=QJUKV*>$0#sIeVM8bb*LY29k;#a(} z<4gFz;A`FznYGOIxQ&^%A2iDe^T4Uujlo&w_rTmh`SU=6spNY50Qh$TsAOZ3(&-Ny zylH@7si1(D%d;PZ5!?TU3zvp^fjsk-dNg6J9^INtI-peAn9o)2 z1SUdeckbZ24p2`5eN-4X!MyuDD_!5ig{2heoaX?q&-Fq4Rtf_xnDRsd$4>$*e6F{L z%0fI{Lmw3k`^|ssw_VL9w1cAoR9La+#fhF zI-Ji7h%HV{UOfD8Y}{sDH()-8-q0b$5gW2A$iUDp@F^)yt(`y5XHS(8bYI>npd<6p z1sMQ60&o!erq><5Q3NBs9QDg8QI_8HVQ+>2Th!g%Pplu^YL?bj&UGi-tYf&R2acp& z$xt*YFw5jE-&l_$3-4Io6oA~zWcT+du{$SRx%z?dv;0baOOU>>vbQP3j^mgzK-kGY zDX1PCyrni@pPpmmHoKF9J%kpUEi0n4<6H>PRi#fuj~7|;9`{H{3KCXYp2--u%bXeG zcrtRc=WT8Aho>0s>?O|^67u+LFQ~Md%PC-n4Y7AzdIYcx{@!!eFwSE0QXj^`V+^Mu zFh&j0j_QFE`({HcXjAMQ&W;|F&WpzIpEOfhQk4^?L1{Cer3JqCj+ZbfK!*-_-PN8< zs}9eR!LL=-bmzb3NYB)J3S()KFyS=prt16)pJs)^O)GSmpi9@rd2sRhx zP!V@Gr2mqWj<2u@Pb%Y5rqQ3ZSO)2+{kA0Ez@?RKvzv|U1mQQG!Eo%vQ&^9dlcc=1 zAtF^$vdUu9j(?@ON&8otn{(QLk%O1BzY6#&YHpZDI$d5yW70`?4C{P;7Go1I z{x~15oOm&B?J2A)Bmb8BXfk6;flZ5L6xxC4uXe)?>*prA(R=ttl=t)``Qry};A$=| z>x#X22|jJL-`pE^W|>nD-@X;16rOu~cW*q)o$*&=;wug_Uo=$u%=@jrxAZm}-PDt0 zs{wA(cjWCr1|(m1@CsmLm-xq$PVj?%VZYIUz$Zz-9Dkw#TYKMeUXCSE6Z9osneFx+ zT4H(gPKTK^Vf5j^ubXn5hH&&s152|u&-$)56a0)h)F>ofjoqA*y=%XGOt$1qJozIC z{L9_5zuSjf0jh|S|VQb0UJ021+i)E#|{Qrkq{2yxZf2hU( zp%(uir4}(8oK)S)g)S^36zmP8))+G>A!@5}!W%V->rqhw8|}39FTbbOd|`Z9!!jC& z0%^eR97q8++*lS37-KzLeqNciPx2?n>g%v@<8 z($tt={_^;eTp%e&8UvDhE;@c1;G_Xb4M&_rlG<8}+A6R`-=Kp*Y*qM8Mg~YqR%YpP zvh)Bxp6v(Rb@g{y&9;xP=G=<|0Cevp3*DPqv241j+dv6iZD!?M9Sf;5`q|!t>bI5~V6)_!d#AeT}=mH-^M4*o9Lc@tE(DrO;Sat8kxN-+t94p+c=o1EvTJW2-2`zLQs z=v2ykIiSvQOf8LTi5N=ohPGL+jm%!eIR!SMT&ur#Zyv3I8wNL1iEpv@tGi(meZxF^ zo^q8Jn`-QK5bbG^oUr2W6)wEw(@_@9T`#?y&CNZl5tZmJTBx?+gHZ%uoFJ?Ah~x(& zP6=bz^)PUsxO_F-;69$C3M2K|aObgSwUpnlA^g1)_P>qj^(j7E#Jl*l*cp|>PqN+L zrD|D-Ey)+3W_J*B7!gfUTAlgGAbv`rmZjp656<)|n870h*PW^#4rc0s+faU=_i>?q zK)ok_7fvl)Kw5||XD%O`RTOWBm#4qyikx{am~}8+HzCpQ!JPAj&^C0`=!56alB{`1 zOAW}~JS0oL%uD3(d3bp(Wa3%v>rJxd&#thviE#kkjI*!)piy_bh{Xm5$I9p^o?o4* zs9PCpnPu^ZvT3S~mNuZq>nlcxd5o>);$p5Eo~dr=ydufxO#6G0<8K{6M7c`K0$zTx z$1kr2D^7fjj^-AxkfKUXamY>pydpF;AJFXxs{y*5(U1fg6n{Wd%s|DE%Y&_h9(Qca zZ2DN7Mn3#d`U@cWR7WxW*kHx&N}!%4Cr!4!#RN(CkcI6i`f zhP*aPLq5pp%@UN|_|iVwAPgvc7%9O%06}S;vX3kM)|M%?aKSXUr2>oonPsaY%q`6ML{tjn~n%T9n@ft#Xu2dTf+;I}V=owO)pDpNv9<{WE~`OmMJiuH)dn;L zofnakPZZn4A7A_~yJ~E@TGqXM|20Y|_=Co7h%Sl8uX>rVqfj^Do!_wW_xp{F+?T-g zTdgy?p6Kxym=PjmB^JW``+&X~Gn;QJUr%_%kR8^5j=aTYUMJy)1!u6eH}#`ud9U$~ zC_8bO?Hb@l|9atk{E%_9u-NK+Q-?Q3OjU;lyT&}TGE$o^Wk3%%|Db`V?+!V&HChO` z%Q;7-&D570eh77T>ejOgDNQ0wc8cPm3+;}mP&Dj^KuG3h;CdrBkGD|GqY^1xOXZk( z`H+jl)&btB?__KUg<@=nH^|-^JT9WIFk;kLm?!I5W&E zBmOqOTwh61GYcHf&u+{pXmovzYe1r7oq$U@yFIC>@kI9!nb@d(zqTEl)&mGX0$(7T zn@BVv9XKSkuB?RBt&X26Zs4`;^ZP(yfE!SLOF;2}=J789xOb9QNCaJ6>mwi~XSCc3E$6nk3^D}c=NTt<$4OdnZR3mE4Uc(cXEV0F(CkF|HLBfftrV-s^@ ztv;KHox5nBNJzf7iSB zp1R<`QItGZ!Uhjp9!JYJN?Xsn%k*~Wp8usfdep#D1Xnc?n-3j{s7+)}GWi&yRa{0QoX#p>Jt+Z$E=X4R^ zYHxB``kG5-5=II+oR_E#A|SX_?0kY(`NQXj-*52|n*O)o;)hei$`W7FczKeO)3fd^ zfMUwL%m_*WAF}j<6!;d;rU^EqD~g##Vz_%HV@Ye@E#l%Dl~#j1eDTwL{s%=%dwEN? zEQ((l7meV&&x{=O)(s;pd%Q9Fs`rZ=+P7RXM@({35ij%$w_~8qlonm9>Rb&Yu$IXj zWP#}a9{c5vcbK(i2gh^8ME|*O+VotSz8(RP);Jg6Gl@PU)LoX#J;<*93X_|>sdoyqFHH=+rRoH90-`XyU`6{tOfsO^k=H!o=b z+-yguRsb4>QfG8`623=8zKDO3E7wOvZcEs8RfFyZBP;fa<&>=4R;w$xVHj}Dtlb&a z?vpRs+F`qwUVLxd>SZ*0wDe(fQ-xk9ajOv^gCGCa1E6de3y64P&Gq#|+7ZzS*Nspo^qlgOy7>~j zlBULu>s|$^pd}3xt_++X_$7!Z5)E;ZyD zw+w$Hsm_-uI+_;_NdT<$#02Ork9~!^c_M@_<2xI*o}k&k@o`gYGUeTh{J+{e^Qfk- z1P-TKWW<3SDJ~TPwzQ(6f>oB10E!i=$YP5`1PRDkKnS30VFxi%KuLkhmV%vx!jd485D0;}FK9=d<8sPTA-#otRR1uy#JzvYPT%13p@DO8-sfh5VDuOY?N3@z|hQ=*{mg zGc4ZdpSd~3XHC($2RYjAyo;F1Lq6Evb2fLKPH1)g>hd11+<&sKiS};60rw@R#Hb%{ zzty9>LoSypb=KyUT(0Mx>??qguKvSVC2_3%oX^p+0Ku#VBXGm9P~c?kIBvErrS*#E z7op?T*Ilem3cE_?dE~bGyn`J?lR-ac_}HLwuYR~zh&>cUer?1LTIBA&e*{(1W8|Kw ze@P)erCyItd$Y!+tg z#ZS<63+Ce0zkI$z_rL`4TbZMI zADD~&6YoDz>Z7*62XPFLd|~vQcqMj2ge~S-EIkNnubVD-DRygwCdpN6fj%mTx@ETW zMIc4a1CmqeEwN%%3`AGqVFJR0%2=Q1KsW_LX(F&9|DzmmF(2uG)BPJnk)qz`fII(@ z4miIo0B8Kr+Sh={%8u-^ljo*#*Bx#q#V zQa=|FLTuW<{e-lswJF_*aeeuMShc|(Ojb3>9;4srXxEk1ZC0?4lY`%*(x}f%r+E zjxqzXH-LONX&0)j_m|E^Tw9Whm&ze-C;^a@pA@DR>RdcIVN^#rxnXZQqr&79@El=cvYpoeo{RGTu>#8{I$&e zDP_Ld04sItY0t2%Hth5QUIf6rLVB64RS0pZm47C9O(>!_?0tlz3|t=X<`iYC1s=-1N^Yc%_jikbdWAn}IdmzGH99Q>zhdD5=jWKV9hO3*6KUIHQ{-D)->AJ*V_MJJOuauXDsi*xWT2t9Lz z;}zBEn+HQmKo&9gn?(O-D$l#o8W|cYG?GfGS_RcJ{I&2U$TGY{dukf-BlPTo?VYdnF#*dX4MM8|^0+<9o|hoL z47P?T7om*h}=jnAIcomeLoPYOb>^cl8Y#)1dY-5Q%t-dEkXGRIA16I^; zYb5Hoq9Xkjo#S81wrQ~iawaH}*dT4sd`-16d~njYLsI?VHpDDX#`-*D3@l?FmW!48bNy!95# zo-4mJy@|Gj4UDF=>J@*Uj}^$fnFdi0J1c}RV;F5S-PNicK3Tx@HUdm%eh5qm705JjM14%((Qn_jn!=@qYAt!^;B7iGP*jwG0FA*sjoA?NzI-&Qwog3A7L zZ!yzYriNo)(pBs_#q?0=x)qtZ%_P*%dP>uP()An=MnBipj4+3BjFpt*4GIaOvt2Cmo)Y9c)GRW7l9JlWf0Cw=WY9 z9X@Z>$G{eCMrh-hwxR+=0@ks@aJSjjd$$nkG*Y2b7AKRKN2sg@PZ4=L1-AqIfWts< z+n0K|+QqF6m!lKt5bw|-5F3+e$gJKbHp|R0MJWIsRb-jy=0?D|4~>+oQKb*YFR+H5 zD9%H_<*e*tum;0DDcIxO-BJ1vc%K}9zHstp0bki36?mueOofi{eq^~$?VR=3#^zSJ zSc@%)0B6y_L&NcH1QqgY&DZ}ZcIXRr8WEMqhk6pQ-R0rZ2aZ(Yr3)=5=;iQ?$>+jO z$l(gM{<>k`z#RHU<=GX#U%2Q)^2q Date: Wed, 10 Jan 2018 11:46:23 -0800 Subject: [PATCH 165/188] Move setup/install and remoting docs into PowerShell-Docs (#2026) This creates a couple new topics around WSMan remoting, SSH remoting, and installing/configuring PowerShell Core. It also adds a topic on using VS Code with PowerShell. --- .../Running-Remote-Commands.md | 18 +- .../SSH-Remoting-in-PowerShell-Core.md | 221 +++++ .../WSMan-Remoting-in-PowerShell-Core.md | 58 ++ .../core-powershell/vscode/using-vscode.md | 191 +++++ .../core-powershell/vscode/vscode.png | Bin 0 -> 151555 bytes .../Installing-PowerShell-Core-on-Windows.md | 106 +++ ...ling-PowerShell-Core-on-macOS-and-Linux.md | 808 ++++++++++++++++++ .../docs-conceptual/setup/setup-reference.md | 3 +- 8 files changed, 1403 insertions(+), 2 deletions(-) create mode 100644 reference/docs-conceptual/core-powershell/SSH-Remoting-in-PowerShell-Core.md create mode 100644 reference/docs-conceptual/core-powershell/WSMan-Remoting-in-PowerShell-Core.md create mode 100644 reference/docs-conceptual/core-powershell/vscode/using-vscode.md create mode 100644 reference/docs-conceptual/core-powershell/vscode/vscode.png create mode 100644 reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md create mode 100644 reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md diff --git a/reference/docs-conceptual/core-powershell/Running-Remote-Commands.md b/reference/docs-conceptual/core-powershell/Running-Remote-Commands.md index bdd7befe9e78..121d608858a2 100644 --- a/reference/docs-conceptual/core-powershell/Running-Remote-Commands.md +++ b/reference/docs-conceptual/core-powershell/Running-Remote-Commands.md @@ -6,18 +6,31 @@ ms.assetid: d6938b56-7dc8-44ba-b4d4-cd7b169fd74d --- # Running Remote Commands + You can run commands on one or hundreds of computers with a single Windows PowerShell command. Windows PowerShell supports remote computing by using various technologies, including WMI, RPC, and WS-Management. +## Remoting in PowerShell Core + +PowerShell Core, the newer edition of PowerShell on Windows, macOS, and Linux, +supports WMI, WS-Management, and SSH remoting. +(RPC is no longer supported.) + +For more information on setting this up, see: + +* [SSH Remoting in PowerShell Core][ssh-remoting] +* [WinRM Remoting in PowerShell Core][winrm-remoting] + ## Remoting Without Configuration Many Windows PowerShell cmdlets have the ComputerName parameter that enables you to collect data and change settings on one or more remote computers. They use a variety of communication technologies and many work on all Windows operating systems that Windows PowerShell supports without any special configuration. These cmdlets include: + * [Restart-Computer](https://go.microsoft.com/fwlink/?LinkId=821625) * [Test-Connection](https://go.microsoft.com/fwlink/?LinkId=821646) * [Clear-EventLog](https://go.microsoft.com/fwlink/?LinkId=821568) * [Get-EventLog](https://go.microsoft.com/fwlink/?LinkId=821585) * [Get-HotFix](https://go.microsoft.com/fwlink/?LinkId=821586) - - [Get-Process](https://go.microsoft.com/fwlink/?linkid=821590) +* [Get-Process](https://go.microsoft.com/fwlink/?linkid=821590) * [Get-Service](https://go.microsoft.com/fwlink/?LinkId=821593) * [Set-Service](https://go.microsoft.com/fwlink/?LinkId=821633) * [Get-WinEvent](https://go.microsoft.com/fwlink/?linkid=821529) @@ -134,3 +147,6 @@ For help with remoting errors, see [about_Remote_Troubleshooting](https://techne - [New-PSSession](https://go.microsoft.com/fwlink/?LinkId=821498) - [Register-PSSessionConfiguration](https://go.microsoft.com/fwlink/?LinkId=821508) - [WSMan Provider](https://technet.microsoft.com/en-us/library/66fe1241-e08f-49ca-832f-a84c33ca8735) + +[wsman-remoting]: WSMan-Remoting-in-PowerShell-Core.md +[ssh-resmoting]: SSH-Remoting-in-PowerShell-Core.md diff --git a/reference/docs-conceptual/core-powershell/SSH-Remoting-in-PowerShell-Core.md b/reference/docs-conceptual/core-powershell/SSH-Remoting-in-PowerShell-Core.md new file mode 100644 index 000000000000..163e1c9f10b7 --- /dev/null +++ b/reference/docs-conceptual/core-powershell/SSH-Remoting-in-PowerShell-Core.md @@ -0,0 +1,221 @@ +# PowerShell Remoting Over SSH + +## Overview + +PowerShell remoting normally uses WinRM for connection negotiation and data transport. +SSH was chosen for this remoting implementation since it is now available for both Linux and Windows platforms and allows true multiplatform PowerShell remoting. +However, WinRM also provides a robust hosting model for PowerShell remote sessions which this implementation does not yet do. +And this means that PowerShell remote endpoint configuration and JEA (Just Enough Administration) is not yet supported in this implementation. + +PowerShell SSH remoting lets you do basic PowerShell session remoting between Windows and Linux machines. +This is done by creating a PowerShell hosting process on the target machine as an SSH subsystem. +Eventually this will be changed to a more general hosting model similar to how WinRM works in order to support endpoint configuration and JEA. + +The New-PSSession, Enter-PSSession and Invoke-Command cmdlets now have a new parameter set to facilitate this new remoting connection + +```powershell +[-HostName ] [-UserName ] [-KeyFilePath ] +``` + +This new parameter set will likely change but for now allows you to create SSH PSSessions that you can interact with from the command line or invoke commands and scripts on. +You specify the target machine with the HostName parameter and provide the user name with UserName. +When running the cmdlets interactively at the PowerShell command line you will be prompted for a password. +But you also have the option to use SSH key authentication and provide a private key file path with the KeyFilePath parameter. + +## General setup information + +SSH is required to be installed on all machines. +You should install both client (ssh.exe) and server (sshd.exe) so that you can experiment with remoting to and from the machines. +For Windows you will need to install [Win32 OpenSSH from GitHub](https://github.com/PowerShell/Win32-OpenSSH/releases). +For Linux you will need to install SSH (including sshd server) appropriate to your platform. +You will also need a recent PowerShell build or package from GitHub having the SSH remoting feature. +SSH subsystems is used to establish a PowerShell process on the remote machine and the SSH server will need to be configured for that. +In addition you will need to enable password authentication and optionally key based authentication. + +## Setup on Windows Machine + +1. [Install the latest version of PowerShell Core for Windows][] + - You can tell if it has the SSH remoting support by looking at the parameter sets for New-PSSession + ```powershell + PS> Get-Command New-PSSession -syntax + New-PSSession [-HostName] [-Name ] [-UserName ] [-KeyFilePath ] [-SSHTransport] [] + ``` +1. Install the latest [Win32 OpenSSH] build from GitHub using the [installation] instructions +1. Edit the sshd_config file at the location where you installed Win32 OpenSSH + - Make sure password authentication is enabled + ```none + PasswordAuthentication yes + ``` + - Add a PowerShell subsystem entry, replace `c:/program files/powershell/6.0.0/pwsh.exe` with the correct path to the version you want to use + ```none + Subsystem powershell c:/program files/powershell/6.0.0/pwsh.exe -sshs -NoLogo -NoProfile + ``` + - Optionally enable key authentication + ```none + PubkeyAuthentication yes + ``` +1. Restart the sshd service + ```powershell + Restart-Service sshd + ``` +1. Add the path where OpenSSH is installed to your Path Env Variable + - This should be along the lines of `C:\Program Files\OpenSSH\` + - This allows for the ssh.exe to be found + +## Setup on Linux (Ubuntu 14.04) Machine + +1. Install the latest [PowerShell for Linux] build from GitHub +1. Install [Ubuntu SSH] as needed + ```bash + sudo apt install openssh-client + sudo apt install openssh-server + ``` +1. Edit the sshd_config file at location /etc/ssh + - Make sure password authentication is enabled + ```none + PasswordAuthentication yes + ``` + - Add a PowerShell subsystem entry + ```none + Subsystem powershell /usr/bin/pwsh -sshs -NoLogo -NoProfile + ``` + - Optionally enable key authentication + ```none + PubkeyAuthentication yes + ``` +1. Restart the sshd service + ```bash + sudo service sshd restart + ``` + +## Setup on MacOS Machine + +1. Install the latest [PowerShell for MacOS] build + - Make sure SSH Remoting is enabled by following these steps: + - Open `System Preferences` + - Click on `Sharing` + - Check `Remote Login` - Should say `Remote Login: On` + - Allow access to appropriate users +1. Edit the `sshd_config` file at location `/private/etc/ssh/sshd_config` + - Use your favorite editor or + ```bash + sudo nano /private/etc/ssh/sshd_config + ``` + - Make sure password authentication is enabled + ```none + PasswordAuthentication yes + ``` + - Add a PowerShell subsystem entry + ```none + Subsystem powershell /usr/local/bin/powershell -sshs -NoLogo -NoProfile + ``` + - Optionally enable key authentication + ```none + PubkeyAuthentication yes + ``` +1. Restart the sshd service + ```bash + sudo launchctl stop com.openssh.sshd + sudo launchctl start com.openssh.sshd + ``` + +## PowerShell Remoting Example + +The easiest way to test remoting is to just try it on a single machine. +Here I will create a remote session back to the same machine on a Linux box. +Notice that I am using PowerShell cmdlets from a command prompt so we see prompts from SSH asking to verify the host computer as well as password prompts. +You can do the same thing on a Windows machine to ensure remoting is working there and then remote between machines by simply changing the host name. + +```powershell +# +# Linux to Linux +# +PS /home/TestUser> $session = New-PSSession -HostName UbuntuVM1 -UserName TestUser +The authenticity of host 'UbuntuVM1 (9.129.17.107)' cannot be established. +ECDSA key fingerprint is SHA256:2kCbnhT2dUE6WCGgVJ8Hyfu1z2wE4lifaJXLO7QJy0Y. +Are you sure you want to continue connecting (yes/no)? +TestUser@UbuntuVM1s password: + +PS /home/TestUser> $session + + Id Name ComputerName ComputerType State ConfigurationName Availability + -- ---- ------------ ------------ ----- ----------------- ------------ + 1 SSH1 UbuntuVM1 RemoteMachine Opened DefaultShell Available + +PS /home/TestUser> Enter-PSSession $session + +[UbuntuVM1]: PS /home/TestUser> uname -a +Linux TestUser-UbuntuVM1 4.2.0-42-generic 49~14.04.1-Ubuntu SMP Wed Jun 29 20:22:11 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux + +[UbuntuVM1]: PS /home/TestUser> Exit-PSSession + +PS /home/TestUser> Invoke-Command $session -ScriptBlock { Get-Process powershell } + +Handles NPM(K) PM(K) WS(K) CPU(s) Id SI ProcessName PSComputerName +------- ------ ----- ----- ------ -- -- ----------- -------------- + 0 0 0 19 3.23 10635 635 powershell UbuntuVM1 + 0 0 0 21 4.92 11033 017 powershell UbuntuVM1 + 0 0 0 20 3.07 11076 076 powershell UbuntuVM1 + + +# +# Linux to Windows +# +PS /home/TestUser> Enter-PSSession -HostName WinVM1 -UserName PTestName +PTestName@WinVM1s password: + +[WinVM1]: PS C:\Users\PTestName\Documents> cmd /c ver + +Microsoft Windows [Version 10.0.10586] + +[WinVM1]: PS C:\Users\PTestName\Documents> + +# +# Windows to Windows +# +C:\Users\PSUser\Documents>pwsh.exe +PowerShell +Copyright (c) Microsoft Corporation. All rights reserved. + +PS C:\Users\PSUser\Documents> $session = New-PSSession -HostName WinVM2 -UserName PSRemoteUser +The authenticity of host 'WinVM2 (10.13.37.3)' can't be established. +ECDSA key fingerprint is SHA256:kSU6slAROyQVMEynVIXAdxSiZpwDBigpAF/TXjjWjmw. +Are you sure you want to continue connecting (yes/no)? +Warning: Permanently added 'WinVM2,10.13.37.3' (ECDSA) to the list of known hosts. +PSRemoteUser@WinVM2's password: +PS C:\Users\PSUser\Documents> $session + + Id Name ComputerName ComputerType State ConfigurationName Availability + -- ---- ------------ ------------ ----- ----------------- ------------ + 1 SSH1 WinVM2 RemoteMachine Opened DefaultShell Available + + +PS C:\Users\PSUser\Documents> Enter-PSSession -Session $session +[WinVM2]: PS C:\Users\PSRemoteUser\Documents> $PSVersionTable + +Name Value +---- ----- +PSEdition Core +PSCompatibleVersions {1.0, 2.0, 3.0, 4.0...} +SerializationVersion 1.1.0.1 +BuildVersion 3.0.0.0 +CLRVersion +PSVersion 6.0.0-alpha +WSManStackVersion 3.0 +PSRemotingProtocolVersion 2.3 +GitCommitId v6.0.0-alpha.17 + + +[WinVM2]: PS C:\Users\PSRemoteUser\Documents> +``` + +### Known Issues + +1. sudo command does not work in remote session to Linux machine. + +[PowerShell for Windows]: https://github.com/PowerShell/PowerShell/blob/master/docs/installation/windows.md#msi +[Win32 OpenSSH]: https://github.com/PowerShell/Win32-OpenSSH +[installation]: https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH +[PowerShell for Linux]: https://github.com/PowerShell/PowerShell/blob/master/docs/installation/linux.md#ubuntu-1404 +[Ubuntu SSH]: https://help.ubuntu.com/lts/serverguide/openssh-server.html +[PowerShell for MacOS]: https://github.com/PowerShell/PowerShell/blob/master/docs/installation/linux.md#macos-1012 diff --git a/reference/docs-conceptual/core-powershell/WSMan-Remoting-in-PowerShell-Core.md b/reference/docs-conceptual/core-powershell/WSMan-Remoting-in-PowerShell-Core.md new file mode 100644 index 000000000000..41021451931d --- /dev/null +++ b/reference/docs-conceptual/core-powershell/WSMan-Remoting-in-PowerShell-Core.md @@ -0,0 +1,58 @@ +# WS-Management (WSMan) Remoting in PowerShell Core + +## Instructions to Create a Remoting Endpoint + +The PowerShell Core package for Windows includes a WinRM plug-in (`pwrshplugin.dll`) and an installation script (`Install-PowerShellRemoting.ps1`) in `$PSHome`. +These files enable PowerShell to accept incoming PowerShell remote connections when its endpoint is specified. + +### Motivation + +An installation of PowerShell can establish PowerShell sessions to remote computers using `New-PSSession` and `Enter-PSSession`. +To enable it to accept incoming PowerShell remote connections, the user must create a WinRM remoting endpoint. +This is an explicit opt-in scenario where the user runs Install-PowerShellRemoting.ps1 to create the WinRM endpoint. +The installation script is a short-term solution until we add additional functionality to `Enable-PSRemoting` to perform the same action. +For more details, please see issue [#1193](https://github.com/PowerShell/PowerShell/issues/1193). + +### Script Actions + +The script + +1. Creates a directory for the plug-in within %windir%\System32\PowerShell +1. Copies pwrshplugin.dll to that location +1. Generates a configuration file +1. Registers that plug-in with WinRM + +### Registration + +The script must be executed within an Administrator-level PowerShell session and runs in two modes. + +#### Executed by the instance of PowerShell that it will register + +``` powershell +Install-PowerShellRemoting.ps1 +``` + +#### Executed by another instance of PowerShell on behalf of the instance that it will register + +``` powershell +\Install-PowerShellRemoting.ps1 -PowerShellHome "" -PowerShellVersion "" +``` + +For Example: + +``` powershell +C:\Program Files\PowerShell\6.0.0.9\Install-PowerShellRemoting.ps1 -PowerShellHome "C:\Program Files\PowerShell\6.0.0.9\" -PowerShellVersion "6.0.0-alpha.9" +``` + +**NOTE:** The remoting registration script will restart WinRM, so all existing PSRP sessions will terminate immediately after the script is run. If run during a remote session, this will terminate the connection. + +## How to Connect to the New Endpoint + +Create a PowerShell session to the new PowerShell endpoint by specifying `-ConfigurationName "some endpoint name"`. To connect to the PowerShell instance from the example above, use either: + +``` powershell +New-PSSession ... -ConfigurationName "powershell.6.0.0-alpha.9" +Enter-PSSession ... -ConfigurationName "powershell.6.0.0-alpha.9" +``` + +Note that `New-PSSession` and `Enter-PSSession` invocations that do not specify `-ConfigurationName` will target the default PowerShell endpoint, `microsoft.powershell`. diff --git a/reference/docs-conceptual/core-powershell/vscode/using-vscode.md b/reference/docs-conceptual/core-powershell/vscode/using-vscode.md new file mode 100644 index 000000000000..0979a7139701 --- /dev/null +++ b/reference/docs-conceptual/core-powershell/vscode/using-vscode.md @@ -0,0 +1,191 @@ +# Using Visual Studio Code for PowerShell Development + +In addition to the [PowerShell ISE][ise], +PowerShell is also well-supported in Visual Studio Code. +Furthermore, the ISE is not supported with PowerShell Core, +while Visual Studio Code is supported for PowerShell Core on all platforms (Windows, macOS, and Linux) + +You can use Visual Studio Code on Windows with PowerShell version 5 by using Windows 10 or by installing [Windows Management Framework 5.0 RTM](https://www.microsoft.com/en-us/download/details.aspx?id=50395) for down-level Windows OSs (e.g. Windows 8.1, etc.). + +Before starting it, please make sure PowerShell exists on your system. +For modern workloads on Windows, macOS, and Linux, see: + +- [Installing PowerShell Core on macOS and Linux][install-pscore-linux] +- [Installing PowerShell Core on Windows][install-pscore-windows] + +For traditional Windows PowerShell workloads, see [Installing Windows PowerShell][install-winps]. + +## Editing with Visual Studio Code + +### [1. Installing Visual Studio Code](https://code.visualstudio.com/Docs/setup/setup-overview) + +- **Linux**: follow the installation instructions on the [Running VS Code on Linux](https://code.visualstudio.com/docs/setup/linux) page + +- **macOS**: follow the installation instructions on the [Running VS Code on macOS](https://code.visualstudio.com/docs/setup/mac) page + +> [!IMPORTANT] +> On macOS, you must install OpenSSL for the PowerShell extension to work correctly. +> The easiest way to accomplish this is to install [Homebrew](http://brew.sh/) and then run `brew install openssl`. +> The PowerShell extension will now be able to load successfully. + +- **Windows**: follow the installation instructions on the [Running VS Code on Windows](https://code.visualstudio.com/docs/setup/windows) page + +### 2. Installing PowerShell Extension + +- Launch the Visual Studio Code app by: + - **Windows**: typing `code` in your PowerShell session + - **Linux**: typing `code` in your terminal + - **macOS**: typing `code` in your terminal + +- Launch **Quick Open** by pressing **Ctrl+P** (**Cmd+P** on Mac). +- In Quick Open, type `ext install powershell` and hit **Enter**. +- The **Extensions** view will open on the Side Bar. Select the PowerShell extension from Microsoft. + You will see something like below: + + ![VSCode](./vscode.png) + +- Click the **Install** button on the PowerShell extension from Microsoft. +- After the install, you will see the **Install** button turns to **Reload**. + Click on **Reload**. +- After Visual Studio Code has reload, you are ready for editing. + +For example, to create a new file, click **File->New**. +To save it, click **File->Save** and then provide a file name, let's say `HelloWorld.ps1`. +To close the file, click on "x" next to the file name. +To exit Visual Studio Code, **File->Exit**. + +#### Using a specific installed version of PowerShell + +If you wish to use a specific installation of PowerShell with Visual Studio Code, you will need to add a new variable to your user settings file. + +1. Click **File -> Preferences -> Settings** +1. Two editor panes will appear. + In the right-most pane (`settings.json`), insert the setting below appropriate for your OS somewhere between the two curly brackets (`{` and `}`) and replace ** with the installed PowerShell version: + + ```json + // On Windows: + "powershell.powerShellExePath": "c:/Program Files/PowerShell//pwsh.exe" + + // On Linux: + "powershell.powerShellExePath": "/opt/microsoft/powershell//pwsh" + + // On macOS: + "powershell.powerShellExePath": "/usr/local/microsoft/powershell//pwsh" + ``` +1. Replace the setting with the path to the desired PowerShell executable +1. Save the settings file and restart Visual Studio Code + +#### Configuration settings for Visual Studio Code + +By using the steps in the previous paragraph you can add configuration settings in `settings.json`. + +We recommend the following configuration settings for Visual Studio Code: + +```json +{ + "csharp.suppressDotnetRestoreNotification": true, + "editor.renderWhitespace": "all", + "editor.renderControlCharacters": true, + "omnisharp.projectLoadTimeout": 120, + "files.trimTrailingWhitespace": true +} +``` + +## Debugging with Visual Studio Code + +### No-workspace debugging + +As of Visual Studio Code version 1.9 you can debug PowerShell scripts without having to open the folder containing the PowerShell script. +Simply open the PowerShell script file with **File->Open File...**, set a breakpoint on a line (press F9) and then press F5 to start debugging. +You will see the Debug actions pane appear which allows you to break into the debugger, step, resume and stop debugging. + +### Workspace debugging + +Workspace debugging refers to debugging in the context of a folder that you have opened in Visual Studio Code using **Open Folder...** from the **File** menu. +The folder you open is typically your PowerShell project folder and/or the root of your Git repository. + +Even in this mode, you can start debugging the currently selected PowerShell script by simply pressing F5. +However, workspace debugging allows you to define multiple debug configurations other than just debugging the currently open file. +For instance, you can add a configurations to: + +- Launch Pester tests in the debugger +- Launch a specific file with arguments in the debugger +- Launch an interactive session in the debugger +- Attach the debugger to a PowerShell host process + +Follow these steps to create your debug configuration file: + +1. Open the **Debug** view by pressing **Ctrl+Shift+D** (**Cmd+Shift+D** on Mac). +1. Press the **Configure** gear icon in the toolbar. +1. Visual Studio Code will prompt you to **Select Environment**. + Choose **PowerShell**. + + When you do this, Visual Studio Code creates a directory and a file ".vscode\launch.json" in the root of your workspace folder. + This is where your debug configuration is stored. If your files are in a Git repository, you will typically want to commit the launch.json file. + The contents of the launch.json file are: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "PowerShell", + "request": "launch", + "name": "PowerShell Launch (current file)", + "script": "${file}", + "args": [], + "cwd": "${file}" + }, + { + "type": "PowerShell", + "request": "attach", + "name": "PowerShell Attach to Host Process", + "processId": "${command.PickPSHostProcess}", + "runspaceId": 1 + }, + { + "type": "PowerShell", + "request": "launch", + "name": "PowerShell Interactive Session", + "cwd": "${workspaceRoot}" + } + ] +} +``` + +This represents the common debug scenarios. +However, when you open this file in the editor, you will see an **Add Configuration...** button. +You can press this button to add more PowerShell debug configurations. One handy configuration to add is **PowerShell: Launch Script**. +With this configuration, you can specify a specific file with optional arguments that should be launched whenever you press F5 no matter which file is currently active in the editor. + +Once the debug configuration is established, you can select which configuration you want to use during a debug session by selecting one from the debug configuration drop-down in the **Debug** view's toolbar. + +There are a few blogs that may be helpful to get you started using PowerShell extension for Visual Studio Code + +- Visual Studio Code: [PowerShell Extension][ps-extension] +- [Write and debug PowerShell scripts in Visual Studio Code][debug] +- [Debugging Visual Studio Code Guidance][vscode-guide] +- [Debugging PowerShell in Visual Studio Code][ps-vscode] +- [Get started with PowerShell development in Visual Studio Code][getting-started] +- [Visual Studio Code editing features for PowerShell development – Part 1][editing-part1] +- [Visual Studio Code editing features for PowerShell development – Part 2][editing-part2] +- [Debugging PowerShell script in Visual Studio Code – Part 1][debugging-part1] +- [Debugging PowerShell script in Visual Studio Code – Part 2][debugging-part2] + +[ise]: ../ise-guide.md +[install-pscore-linux]: ../../setup/Installing-PowerShell-Core-on-macOS-and-Linux.md +[install-pscore-windows]: ../../setup/Installing-PowerShell-Core-on-Windows.md +[install-winps]: ../../setup/Installing-Windows-PowerShell.md +[ps-extension]:https://blogs.msdn.microsoft.com/cdndevs/2015/12/11/visual-studio-code-powershell-extension/ +[debug]:https://blogs.msdn.microsoft.com/powershell/2015/11/16/announcing-powershell-language-support-for-visual-studio-code-and-more/ +[vscode-guide]:https://johnpapa.net/debugging-with-visual-studio-code/ +[ps-vscode]:https://github.com/PowerShell/vscode-powershell/tree/master/examples +[getting-started]:https://blogs.technet.microsoft.com/heyscriptingguy/2016/12/05/get-started-with-powershell-development-in-visual-studio-code/ +[editing-part1]:https://blogs.technet.microsoft.com/heyscriptingguy/2017/01/11/visual-studio-code-editing-features-for-powershell-development-part-1/ +[editing-part2]:https://blogs.technet.microsoft.com/heyscriptingguy/2017/01/12/visual-studio-code-editing-features-for-powershell-development-part-2/ +[debugging-part1]:https://blogs.technet.microsoft.com/heyscriptingguy/2017/02/06/debugging-powershell-script-in-visual-studio-code-part-1/ +[debugging-part2]:https://blogs.technet.microsoft.com/heyscriptingguy/2017/02/13/debugging-powershell-script-in-visual-studio-code-part-2/ + +## PowerShell Extension for Visual Studio Code + +The PowerShell extension's source code can be found on [GitHub](https://github.com/PowerShell/vscode-powershell). diff --git a/reference/docs-conceptual/core-powershell/vscode/vscode.png b/reference/docs-conceptual/core-powershell/vscode/vscode.png new file mode 100644 index 0000000000000000000000000000000000000000..4c9354bd0c909362a01addc14abd0ed61f91c8a5 GIT binary patch literal 151555 zcmdSBWl&sQ*DZ>>YjA7a8z;Cn&^QDQ65L$_!QC4txI4iT+^x|BOOPZu0fIY0PUo@r zdB1b&)~WmBR^3%aHNE%ly_d{6<{V?L?idXuTF2MqXE&-ou~E*k_;u$@_lM)v>?1KTiH}O&~Zh+VWfP zMB6p+c-`SvhZ%dM?=i}*av^=?%<7*mUbbK2E+{8nD1~plvar}DOvlsT%?Sv$44tKZ z+>FKS1@?OGj4)UMe-oAyr}y~q~pU(vs>&0(6=^Z08R1;J~)P{nke zsj?(GyoskfNy)*A04^mLv#CpXh+Ay?xuojM!{*uf(`$n-??2vOAAe)~!Lt*TmH+F_ zIq}Mv(UXNHOGV61L%fyAyD*2` znyO5T2i#u0y4oyw`x36P@A31jhtbSV&ui`%Y}%>uQ&GPxo7UpTcQ;~FfEplg&0(+0 z_OyTkv2dl#6edV@^cj2XL=88pYFYTa^nz8i1F`#yV$I5)yP51Tp4<(6?b3I^T_olbC&rlfAcn;0 zmUb}LU6jviCyQDW8~kO90(AX*DM@TqIVv=|jRb@9G!}(95U|`dAvQEk34l1Dc?s2# zRF4c$3||YD*wZQKr2s05LLlt;dmtq?6{WHv+Nf4B4Rsvl?56Rs@znh(JoAoKxK~8@ zq+Xx5(l)9oi@B7yiglvu$1^A5X5YpTD5V>;&gv?aY7$pWsFMPe@|?Em(~`$C3&(v* zh1k8A+$~wln0C)1=7b9KmV!KeW ztrV0Q^9>81Wt&cH9Zz%-S&5iEGrF!pj@2;TtA;C8xjkKxtD%CUUF+-#pvxkYp3-Cg zv4{hsN~eRKb&%~C6j)oY=7+SPyO2QJGVoHj%aE(P>VgFDs=Ab$?=R~p2egTuX)@}1 z>}|4M5hii{Dk$H5gmQodHlHGZn@=-uxmS$at0r$G=ivY)r(6qAc1y+$`>x$sD8Au( zHRX$ZS^2%rQc2lxdZq^@no$oKmf-rz4V78bVy@zz4&BU{$JOd&9nS1l5NvtftNWAA z>_NBDH4EwWarNBnmyM8YQH?-duVb{jFL=bzInx`HhSYujB}?$YoHuZ;2@PwPuop<0pGPYrmo#^o&H{H&lsH)YNbg0`C`|U zSHArMNjIfPr{3OpDOY4%m=VAC6<4*R?A2acH*dy~8bKj3+Hoh(%?WngKl$De;W9 zk8yt4M)Uqg8goOMa$qe^Y8f*Kq#jva?T}c6J8#Nd-F8(is-DMYS)6E!Xt!Su7=5yW zUb5iAXF!!a)A2A#baegw6qa*;=%~Nn4x!08ZD3Vl_S$68{Ov;;!&@Dq&42b$Ko{z) zP7GlPBq(ar4;%{Z6aBmu2GB0!=Q+oXlXWUNp7{JX@Ni_98<{|aA?65an5mIza^{)r*> z0k0tD|J*e}9Sr_}?V;lyN$+l)LsdeE^c{%94Z*hORA*2174kn`ifGhye2bnXz^@p7s>I)?$fl+#9Y5i3UmJ8&KNWr{ed*f*X_<;WS5`Nu=#W78tILb(#tW%n zVhQWO?wS3$gLZNYY|4}*2f)pv(;})8o~ICWm|X#*w$|_~C?xX~Dbs)TGRjM6?BcmL z@%R|+xto`eXJAGCK^UY`Un-%>DzHdtrB>MHpJ^4SB}avZ*Eg(sY1h#&J}tMPpxb*f zTy`IjSJICMU?k%+zW9l14`*kDvHQ>L*GB3(ffUd+Ub3PYen0{S!QYN_&CZJDd_X5$f{I!xubzE~k*M9gc z2SXptwp+e}KL4?$s#QeJexgKW^rf<&;a+EJPE}VAAol>H>JA@-T4XYkS6bs9^-p4= z8&SY&*cE|l0R-0g)L;C!<`QUC18f6-nqhbLWK1tZ|hNN z2te`v_4?_AL}UK=zO&p+8Q>t_$%)R zOiSV8U49|Peou0Z5&_vb@h1=T^p9@gYSo4lQN#zFO(_~Ofv=a19tu5KN)X6&-Q1Ct zv_|krfSEV=iBfyszKd7GL~tKXEhs(_DqMW6Mp*+yJv00gu2zFf4ilw z^d%!%U8gC7od?%RPCXOZf!f&u3N0B(t+t`bUH-yY>rQmMthzOz((BslPV;;I)eA|E zLNG;K^s@uC?d?p`&t1S0kT{Rh;+$p*LgwCqY$~O~d~qFyF%y5Llsa=7BSg>5K_K<2 zd|RyMHBye;olE-P$*GnOHw6E&$2sQRa;4UEb&)Y_;{6pfRj;e3%u3K4zSL4WkhO>L$zN0Aoi(Y&yX z-@Bf6#GTewtz-J{JbO>~0aPCFqU}p`I8(>G)PS9?oCu?z((QdmYNK8yq*Dgy!@w~l zcanqasx|Whb10kat=mQ@mt9eBrFxVq0e`3-Ed1F z?s)wCRCt8XHd9JFFJt%&K3$7x_&YZ6p|$=A0PWC@NE4X-8oL5*8)DJW-uq+yHgoeW zypp6S^+olgYrbFddndE^|I<-D0T??7l(9RF`g?k-)xf}7ZrT5M`f{Z*#6Vx^EW%%9 zy1sbJ0UIDP7Yk_!?1!)$DxGa7(YC_{LM-M@-2GuMKZyUq?i#@jiT_I;k_raa^@0MQ z9)g-08wI$2B`%a+MoHdFpARj4`Q0QkVf+SmrWA_9T@#~x-uBnwlK(#+4m7x`kbEF} zd{yvb3hGvClG9=u3Kg&r(6pl#qWIlbZ1|bT1mAN{Jl>2-svgfimJLJXyPsoI2>v|! z+L_7q@^0n(W2Dqg%F)pg8eL$vbJ^BWQ%)^^(%XdJ?U0W=6^mje(<~imaWp(T?twwokNAL!n>GRLHPfN`v?+TnA(pPygQ=e_at$|OE58bb?1)Y`wrna_AD=U(IXGmp*ZLrU-U%^`_DZy;l zKEgISJ}d_yEp1?6(CvR&tZg<~rjm&Vs?b&XkC6$$L3J1f*0XYQ#*120%IjPC2|G39 zy_tf@dRM*&UAOfrXFiI~53EeQ`eBCYaw`g*coodFaQ!3#=Z1I5-QkF;?@OmoNulhT9aF%x4!-t1Ql`TekU z&|~WP{CZy&p|+xBZN9djEtwALhqIZWN9wzor=doT%Zjwp_e|}bG|7#Pyk={CA&6&w z#2xfX61S@e6n)1}6Q++q&mS6a3g+hPh0(cPH>#TeM) zz?R58zFNS2Yb-Pr0gp6MGOIN3*VWR}(hUjzB;LpxQAkcAdBWeuRd>ZCLI$ySHOvc? zgY13p?X9V)i3fiBwmF)V$vv;1)3G=U{)xupd6l{M;?Y^sd(`ck=4+RC(i|c)k5e@~ ziQ4q^HVUwx6e0*WrJ#QZT z{WW!h3{e?^KKLIlHKPI$^HXMee@)NKa0>~2s43mr+Pb;9G5X-FnS?F&D*}_0O`I5) zM#8w;UjX9k?{95wje?Avo|e|-cWwBBd@-QC?axSU4^2NCJod|KEfSfQxW_;4kC@u9rR zq^i3AxY;s!>6K8mq^{Opt0)BPU1^TA6&Dv*-!r+v3d&N9+ID`gx-z@$tzXC3s+13h z;JaGys}DK#1ChAN@gMS_STP}`crPtKYD6z!y^AH#_EG96o_^v^z1DPR4V~29fFxR$ z8%4A^kwg!VFs1YzVl##FZatUj%c5fVwV^HXSt<1@3`J8hs<*dSxavwL^?fAM=UPK} znX|LAF$U)TqF#^P>Gw`6YfTm9ADqad2k{pH~7*1622#EtL+|$ zC|GT89z>^b`G}1<>jTUG+9l|&dw$emck(BJu(`Vxc~g(BFUv< zZaTXjJ-X@(ULm1gzjLOePg7Ia?;6bqQFIV9gT*UHYV;cVM1tv8TVrCNFw=JnLo)o> z;dP*~5+5H=%>F{((6E?FN@H^*LH6wA#1$Z2v_=xn;$e}DBwr#tUPR8ygSdcXK|8f+ zZSlL+)Y;u9?5hjd3A|8*+^(%YvnqaSv72K-lA&d6DEhrPRU4(ObkoP>EcX{y7Ey84%$3J;vg zKrrS>a&|VlVu7dv5gPnSFv

    {aP!`0x9raWYK)fofr-otb z8Yn>Ah?X2d!b-tPcEDzi|a z1zFD7I(otE`{m>^{SjMUO-*fhco-I1J*%bA%usqHvMOq8e?C6^GBGiMBSu273&xIC zddZ%jpD!HQfZH)PJ&hu`rb9>Bb~FCv9XcV?YKPYZ%r-4Uv0xd1a>zpb7y?Dt>uVe@ z-=|0MwgJh?QF$xh42_y)tZ zu@nYSgrRPJj-A})k7AgyYq z@ONaicY%D+RAXHzcws}6Vp-^Sz5^{M-v*OmL29R73>QcU+t0PRTj zy12aBJ+=fIP#FLlGlH+n;guzd(*jd#C|@!mlhbo6ig3T=XANj=9ugx)SbF1*5~L}U zj{9T6lbzA$gD9tQ8y+6Q2NQ|R7XM58Rs7Wp7+`3kU2<&p&Ce5^ey%f8TnAi&-|o#- zz&ze4B)Ld73I^f|ii$PpieJAs1^)6*i?D~w(4fD3NgJerEfu|CizGNUHYOE$)(${U zrQM1YOX0JRlhO28Mf-s^S{MOyZ+e`zn#xL0xANPLNb+^>V9P=dISu>zciP)W3=u=s zP;E|ukzf;AWNY6M$=^wvkws&Y3NRTc6sfk?7CAfLno({Axe7Ha&Ayi77sxwpU?AHv z+t@nZJ~U0Se4Mqb7mHI^*w%6z35pggQFy8Gnou#wg*!#h@5OfttX06ymr9v0Zy-#+ z;suhK)-%oAr>ZmR>JICSKCJmo?0ydvvKlAyU5A;@$)(G;E~T%mu8Uz|VZSc+`1~(y zPe!&UGFOy}!}qfVgXuLAfKr%l8=IT`&-k;$(NK*;=$TY=T3!uf+#JkHB7W1**!uCQ zgk^bh5^E`6)GHQ2i3K^N5bf5O*~Z4EZzM;+A(;~{xI+U@4;Ca#?=+A#a@*TQHs%;< zXlVKrX7a@q6Dh0mF_DUJDw$QYVq#;*XJ)>)*rk%s2J`A*2ha!XOlAu!gso*rYp|dJ z%6ks>tz2BxpUGAr@u8K@RhRm$I{wiLK1ql|+uGVH2mhYHoKpf=hUDDpQF*?9<*8IV z@U!=IS0QFrq~#VM`NME920%8D>DA9HIbru&JeSS|S@zIz)7NkHq3rxoH_r{hN2Rp` z#wN+M?0!?*XTXO%pP5RYvxGxtyQUd^#6PpwTKj&?r%q*ab8|a8J6epJYkpkn@L<~t z^@2CBsO#)}1k0Ul_tEG{NlCR$!{^NzxIfl{F{L3*O+e*V-_uvF^6u_H2wbw1VlcMx z04onlW#L|@R2>8YNmjCg6s0((FTrIGjf@lz!Q#x&kX+6pLUNnOF3u$fKEkIuCDx(j z_RkHbn+mYx!tdt9d}=;mo)EbRg0~E>UmVGghlw3K*y#S8g{m&fTee-Q6^4RF`uZ$B zoZE(Z{9m~ju1Avp&dd(^mKB-FKvZg@0%_&-j*gP}VZCUm*I~cYeCSsz0fYb0iL}c2spb=#ja8CfPC;R`5h6QRt+&n!?H_4T?^_xg{Wws`DSNlb{rtkWfeW zKM&U>0ycmA0HvKtFL*o08|HMtm}%fG)AO!crfSLib=(~0Kg)Ah?X`&jKBwiDoIWts z&PZih6+4W%Wx7oLRjZSTfkmAH1#;XN7$chyx?LFflY3vL4F8T#i^)vAhJWd*5=~i_ zFtSTNyQPQur_i#fNCKm96h^W+_x68@pm$^TT7bEj;a7nKc5nRcQ%yPll7?suepB|E z#o7Cd`TxGBKF5o?vfI5X)ia%M0>V+8ux{e2L#cAAv90k)n!QBL0qOobn3|Qr$MLPY-76-5mg2=`uTU4RSLS$ z=b?Fr(+a~F_gS__wG*=rodFBq{W~-3e_p12$Pa+2*9mI>VN{ zFx|L=xK}$~GiV>X4X>LQEraX&+a}G<&n<2$%u0MR&}RS!0i@Ff$>&Fhn`m~se6R{h zMoD~|GCz`Litg4RV9?(4f0|Q{7*s_UWLTesvPv98Q4XBPd!^ zn*Npi(GRDt?~+)0^ATrDuldtb8aPWrkZd0swA|I^y+y2wcM?7x?1y3w&~QEv+uGNLyNEFBO>zB{mqed!`J1g z#hD-5ih`NpkJ3N=i=Xr1;`+X(TSDsr36rJ5nb{gtM=1fRhwBgaf>fBzmC~KO?7&<^sQzE=J~U z)Bg!{3ks?QmX#DROb{si)AceGY6KNt`X^+I_z&lkb*?7VsdGz^*zKfu2(ny{;`MVn zgt;%G3^aX4v5c7^&!H4Sg{H)$>3*~SeqqI2A8K!Xe46{tKj=I9$f4-v-zc-Ej=S<_}M#c zMR6ti4tX<$}{*6qf zi!bxm5;hdW^-Qas%vOSDB^OYnn051QCN#NG9_&zlEqC4rCVDej+#p zg_C@A)gwQaFoKF_l zHLKd~!f`sSzw@?zmD`~`=nCV>u{rpsZpcy%qQ@fAb{6VxZJpz`&Rk(PzqH7KI&tll z>f7#7j~}ZGdB1QoYaWqR=(2zOuzmi#^Kj+E@%P^EU%$S@h8sl}SmdIX$=Gr=CSs^=^XMlj2`d_^hnjt0F&7ar#;N;}6Q+@Q80q=i<)K zI?J-#D!4Dk^tb#h8ucQp)OWPL*IE%k`z8_GU!YHzP^EP<3BTqvNFJ|NB#!{wyXc2BP-7iBnYe})7aE54l!Cd107s;}W@a{WPZx!|6 z`C9k0Kly@a_?MtC=%X?CGp0^tR%AFW`}`2HKZy;SqkOf~VFjCjndjMpGlwGqA6k$@ zEuA?o#*Me~&>;pJsjc%u+I{h+ix^Ko)8R$f5k0n?v+|8EZ=8I%d0^sgvXwRCRRs;zN34I0Dk{MMpzy%Ui>##&@k@*E;GS-_JB(^m& zkxIx&5{jtmU3|ReF1vBQYxA z#3i9#PEi0ZIL>$8a2p)rvncY}kvXm%hIwEBU*??^=jDtE3g(yrewG7CS~DAqkC*FF zPI9gQ-A&pQB}z5=Gzrt44I4c+S}C2m!k4quMg~%+{f{0}aT$_hKG(yQw_`GuFY_sd`u?u4}O zJf|U^mvOth{2p^iW#L37_a?!3hwo`|YpYihHE~9FdAN?>eP?72t+lHwPk?fSuq6z+LRfD2fj~&u1$2I1=M|ZYMgrvpot+rq4~DR%H$ln} zMziewjK}*Vhe11$QC%`cP&*mC@0dBi#5}i~4=&ivaQ^vb@C%^j zf$95BW}!XEdMuf)sHmu|^a2`;ibExe)Ib%IzP-CEWc!g;8S}URVc~(!p8xFnT8N*& z)U}MZbriQEL+nigp2x;e3=ygp2t@!3Gu4NuJiz;KS-uwei?I7vG)l<47Q<*y;4d^a zB0555W@Z7*bwRi0GpqDuJfZp_M^{M599Aj6kkDwI6HN1fNjfSS982vU%xa%&4ftHw zq=vG2%n@>A;`5eUG4)uBiec#4VA}g;p;~u*FA|$V${7?VW!d`r+F9Q~-iTN?0|X$pcYyPCZ2eKQ+N0wCb#8 zTO~O}dg3atQ_T=KvcFMkp`@Lw9c^jdUOwfi`Zf^g#5E}%m>(qrB*W}(MuOsvAZ_(! zAn$PDjtgK;za)cvU<0^JRf(O?i4HdY$bcF!RHBHL?B^DpS`PrOXtV5u^LcT{jQz#j zzubE{iF!FWpOk?M8zL>&`tV!&s4Dz`C;8Bcq?nlgUQE|xyp8?+>URm9ozG8WHX2Zo zk-ZKURmU6J8yiny$}!6htT+G*5-RJ;mT-s>eST$GH>fL?tj&&@gbFdpOV+~t&NH4jgxzb`Zk(!zsP0mV#Q3q>5 zma%GJ-&&{1NeUwUwnXlpp~rn&S*)0fR+LgbhaY{N zma^N5PN)y1sZ82o49_RZ8}Vn=?iOBspgc)5WDpqpC_#1 zQ!AZvg`X@{7U#3`Se@N%`;G_LOyT{`XAz>eBU4Zt(PI$z&;&+o%0$}f%Rt%Yg5|gP z5F2kcm+h+ig^KgV+!QQS;LO%6^JzSPoWdZVD1x1B7R&~6I-ot;1w|;FMo^yz17zGz zAhge;wW&$#2B~(oSRV5xl-~*ENWxe=R!OT5F>{TGUT)7CzOfI#)Yc3!JUl9@gu@c& zvj$atIBcdFgoU5cjS-4yQ-Y{)u2T?VEa8ZQ+550^RWO+QJ>-!#Xb5JHRz9fDNtV!} zhTn|q1Gh8id`F1Tn6nIF_DStk9?l-NB!L3$a~Kuhcvdf1Eoad<&n581Y%mhrHt{Q2?d8TTE>kd>gotPjUG}2KCvov z6*Ju+k&kBLEy+6Vb^a>aqOV)l_fpy&jjrZJos2}Zp#3}xQ3%)-(|@8k!=TNT4jJ-M zcpg5&UrUkXRWX`nsKpjKy$mwHfMzl}@^3}qQU|uJYb1W1hWWP3aJ_;{GwDOXqDmAeJ?9BvG$~!{H!Uyn82sph51NTPqg?3(B<@knKHc12H z?wd(bx3W-nxX>qGlBa#(7j|i<&Av~skOtm5Orsfb`l6r$XVKz6rNoQPf^#GpQse!z z3{k8hQFX(ww^cJx18SI-e^%o^@U<|0-Ti*lo{Nn^%wQY)A`~x z)WzkrQRKTIPf|SWRP7@fRc!!cDxb}C-{FfWep+ZUZh}SIym0xa7xtOt&Z5|oM!j#u z*@E%f_T(_}hC^s@6=|y0s|nmj5>2ZZ*sM%2 zk2J)!%ZPr07_75jBII$~*r;D?zrX{~mKE-2N93iVqS`*kRobL${6pF5HIyjGA$#^L zAzRXOW{(#KeKUzsT{r`Hs*ho2UENHZZO1%YUI4=X3aqzlUUi;yOTDuk`T^P!m(d4~gMTmXCgB|+{703c|os*AYdd}^AgR#f}l9S1lWOX71hqPQ3XCl+mg zybO>A-r6?Xx^EIqn#oE0NpDnly%{1B~8y>biYgC)c8h z2n$10s|rGdGkf()hDS=BIJ8UcD{!gWN-7?cB2GUl_Pgrb-4Qcgk zV<9<(5=0=aqa5XX+8gOH3^MvN8#*!qnZ;TIMAHK6E?a(^Y09C|Ft}$QdH4u?Q9@3R z`_cOly+~2{VfHUZUY3L)lMCB)L5m}?5D1h)LqLoTc4X~pf|WRQ%V<-1Ek+8JZKX;F zSbZJ0$J5b@Qq24(W-%#Z(`GLrSoWb|;|v#R6@`D#zpg2yeLMmt|yKVUK$&CxKOeH1Z#zCXQ!`4 z&8v6?vat?0`@zjUFPVkQ$L~oX16Z#7+qCIy&wmgyf!lmf>1AxIvBczwq$R{F5!d;3 zQE+T6Edg*A2a9!S8X-~krF3LlU4}w0>c~TEG_XGsS;>^_;MJ3gfM5yes~06RAfRxt zwuIlA>8VQ zv`n|BZOUPDc!>e7V6)(ywPylF(#8NY0wCSJhQ3T)wQ@h}#wJngFzYkK(Kh^Ifo>~S zPT2}jC|a-(qfL%)Nv5SMmj1v8Dv>!x0+gbW(@F>n|WA#G+n6<;>i#IGV2nlnxwf%8? zoP_6l4pRwA*KKZw7>h{{O=Qv*6$GpE#1ebQZCuMi0)W5e>+%<8x30y6)g% z&puaISkf>Rzlw(h>#qqE6P4{E-Agfy+=cpHtkCRl^@6N z>;#y}kY|zyM{o~Gme&A-cLNK}HtK(YIUIm5;Ko&kXxSEwQ^%4+hq%xsi!$pAf)&zW zRgi`Z^%@c81MQO|^qyo-j$c7E4T%=-3 zLm|`8a*{9*NOs=Mmk`*z`)fN3X^RVO+!QbO! zO38X8o@^^qui2YSH7rF|cY+J?jceiLUKE;{#s!QtxE1cu3>7iLYkZu}du|7(uUj2y z2^-Y!$g7kXbZi>}59+VTNyQ4U)&hY*WADrdSu`5R!!0|!57|1QwcIAY`hO{2Jpc072HPn!J5jaC`=}W=ycyr$hExCwUSaW4YsRHH|oOV@dXF=h?3~oNVO& zTPC_&rV7kpUXm1_=^crQAT49#JJ_DRYpdgLnHk-q{Rbbcl&(#TMkV#%tY;Y9)TNUG z^3mCmX2*CKE@#Fj_zyzJ?5456C*Z*W@cV4VjhlsEScZ?ZLLV!%rj$^cT3gG=&i$`b z`^y*<6Dy(8P)dB-o1^iCx>;r0K8kQXF7lQ_E?d~P6PS}5zccHHJ^JDP{^U55vcV8i zqym!)LqbBRA!wC&Xz-~TsIdm@5HfN9mL_Cot@Q#Bj9$RflN=TF_0H;}f_7Yke z4?hV)oE)K1$*0HWc^hDyJjqX*9G}I^H*q-Pm=rH!lI_vmymMH4M=@no_F($v=3;BC_RL9AehFL5Ndd^06mEXL*kXIBlviY!0)~+@Sd%6lh-+X$ z+JN{65kr9cSO`&LMOwJ(a&kx!dM3PBx4FV@p=RYxM3uo3AfP{TfT-t>9CsjuqN*? z8d;U}$Ua|?=F1>&x$%5!y%=i=f^D~mAg%XwUW2PZOXJo{1F|B2N^?3Za{k)EN^vp= zgd>ONgLx?RvuDr9$do?0y23>AhhNvY&v>K~bvU7L07oaM6uGasgd`;17e6$S1wpNh zWN2Q$6K!8#VK*v?lrR{RuGSQ%T?qO8HN~2ksziV`nMK;(BTOcQ`;etP(0{T%$l8VT zFNjNOu%3GR^wGh0X6g+h&M2-Zgnx|7?j)tuT#+E!5*D5lAShW0un--@Z`agP6aR&A zPQ>dBJsC_6vMygq$fhQ1?gsAo+DuB*^2cLAF&yeX((9^k1P*^_aspsA8oc&Xm%2CWKxXQp>eZ}dXQP@ z2|;km^7mI)4lF9U0NU6i{I&elTB(g>&(+0(bnkugOuD$PdLb9PF%uC~m?cI2NQGu?r;DsScSv-ZHhwbxL`TR0vX&h>jA~GhQ@QjRV^P?gGD%Cz zWA|<3+W!`-;=|8V@|KT*6OOij(!MW#UW6fm3(*}kIN3){Q)a{Da3n!f@+~Zf;@KGX z=&#T};{acTpc}5eJdm;MIKPWkJp0u1<-9l_y7dd4a5COWFe={= z-#Dl_34?D3-k>HxD{2zxu+)*a>i)z8jP z4yz#^d_NnW(Ima}1oqE!+7+p+c9rnX9nvcti_Znt9Tb!w-;MUD2-qFC*hBj5^o^NP zz%@%NvKB5~toV7%H$%KKSAH*9IA5bK@3nk%?>sP|9h!rcf}DN6dEV=suFTHgKkp@f zzaOlAQ?lFetv4u1hwf9A8F6Srag;hY^DZq9Yen=~3vQxLWFxEVhWpX-Lj`xTn8X2z z@=%!sJI=5*QL!-+{d6&6z5sJJ{y}1)gkorY)(Yz5=nYN!iRQs!-96V5@=F8j!}B=l ziS(1b=W6=D6u+RD2#Rl&;kZB|N3PrOu5WJH#fE;g1hh0WAuNfG(u&~+h@X7qbN)7{ z?R(nsWni0wYaM=_mktS^g!)7dq@jb6kA|ZbJ~CwWwUoKCacS|*dJ&sagKkG&xWJ^%O=w@C)wQ%ZhuURh%(27UFEd;SR+T+4-lb^QG$Kjd@tANm4@Z0r#-U&X7_dZM@Ya9@hRB}9YZ{VxmvADl3 zhQud46@kbx_3vqUW4`v(UOs+9dBpZvBHT^_41?g?T(WaBJ8U> zFFpOS=z$0eDV7rOBU0qJRgYKAJu1CqJ>?V2sc~Z3dNQkBMfh_fLoTny;n*mCEWI$sua`^#R)yksv#qs6|>%wKmi%2g-4 zPqr;2?;knX_;3?`s{j}{EkkoHktSNB2_;+`uh}5z2yYR5#GkTpR7o3C#4oOExvW8l z1_)VG;W^AMT1ZYVg(xR}{Q+9{6g^Y?<$dnGZWi5MM}UJG_;G)*JA-O<+q?eS{UJXv zl~=4kivsy2=`lkoJXdk6fE!-u$!m2aC`*VhmoJO3D{kkTLj~z;#$T)=`3xzOiK#_O z?eel-*fovB&7A~&I`6~cj95SI9D9vgl!X!v`e2y~dVwxs8*C(U3_X7=yM1~zdGYxd zWd>+Ou(8)kCTK-2+tM~TJ50YnULiBVn*fs+6OtnME3;xe7xb2m(-h_cI~)zQOA<>S z_wKvO0KQ`wJwF$cJui@C=c*Bzq_uY2>wMjy>;$2%i|wkRvS#X^BoED=^K;lTw@x=# z@IMbg%F1s1+HTPx?alzJ6q3X(0Cb*1c!5BKNtl)pfDj)7i!$PedL@fK#+!l*yxt+B z*xJYOR&Na05u1liyv~?#mxFE=1g~v9D|AQS@O}ZO+I)=%DU>5AN#P&IohIe?`WqQ~ z{{-{5x39$-;pT%|U8lMH;oO5q3vz-`L17lcnd|5VL&Rv< z)lEryImO=yb}#|v{63i^>rNPu2uB)qt&U_4bb{7V_#!?#dw)?s{S?*EY;;Tne#u*t zgarP6x-NMuq=o2y|APq2KCg2Z5K-vlBIzILg5cG|$_vlwOK*4UllEfZy8qzS{qPV6 zOeiBWc9$armGSrCg+><9CM8K_gynLn#xG?C(7^q z+T>D zXUnsfUS%yQMv`@HM^3+-JBt!@*Zy;HZ*-qSZiiqA&t+p!LC5P-uX&EoE$z;G=i+=M zcb1%|GbZ?1vIl6NOciR@$Y}sV93;js9^Zsz>aQW~};t{@} zeYZF$GI1e%?qc%N*zxEvN-DHI?%K=HR*5hJPpxG5BNGw!I{MNFspl9_ja`Z!K)BQm zP_AOzhi579EWmNSd(;=nroL>m=G7sMw1|#{1rzp*)Oc%TK0Klt6LAZ(FX}1#r(j=wYPa9HoZL1+MvaG;ayr^*Vt1}%kzgbC; zLVz-Wp~GsnybT0k;2h%Uuqxf2*tyxA#vXr53X#0_EOPt7c|PGoc-;NQKN8@`b6;9S(9n#pryisaG}%02Z~M_CKwt z8!6XeQCE{2jxjllCpRxE@y|@2T zUB^6a`K?QGew8G{?VP%Y!t8BY*9r`&5jQ$=J5j2a0`7^18^&`pW0ZjEKKC>^7fIUN zvjd3v^EF}0_Mk||p9+dRJUtXSC*!}@Eppl0R>(?Kz2*Q2g`uc|=LCQSaWc(0+Z>kX z@a{<>V=Rv2iH(3w#=%`4Tb~neUMq9;$KPKQAzP=-_`hv`mwQ@s z^?uvyk6&h3(3ziCD*p}~qlVn2T|5-p|ZSRBTKK{YAGIQ}R=GZ*_DIrKoEG-}%BHi5!NOy;HcfN=3^P749V3=W;9XR)W&UIa%I!li@IuSgj zCE=!MlTX7`u-Q?2nx#Tn%pUcG5zX8Lm`2kFn64tjcwyD%h?DMQMuk}TZoD8bdwg~; zaT*{Ejt7Z$Ywp<3EoF+N(azR)>n^VCUawHHHqaWu);cm`m#Q>m*vn-7;GFKp*FGHP zbX{*GxI5)9V`Se3M1}oO8i2-ce2$S{MKgPts0yMA7-JCkq`&KTbqw7&jUnTi#?n1p z@#Wfkyz7^y{n*|5Bp#d$+nas3r9rOBXCvH1p^pZWV+G6?m4bJxm}^i3bT>USzvrc7 zS0^Tc2Zl^-k;hRT&1OL4sTZ7yEbW`DX88nCq=u$ROniK#(1XitSNk-A@bCrlk|cJ= zdlQmLUrH}o=z6IYed;|~n-Gc^coF4aNpUD4t2s0F zlvvyQG|US>s?7jDb4{u2wM&C(Zcg8P7YA#+|NQxO^~!dH`_9sC5eoC=X)T+Q;l>M+H( zdwQS>I`LClG5XEiAhtfV?%pHqDXcdLKJ*1ZSz(u!X02gX32533W2J>TbCE@cV|MAizUs{Synb|GOU z$%gF5zxYE52fkE-_?kI4V?tIVsS84GVpwH6&1Dlz$4b`J9GfmnR$)G8FAI&IFpj%6jSl3awHh}@YYV=; zOUcqV%aXZQ)dPH&eA-^NZVN(CcUoPF!ieWw&5y%~?j-K8Cgbr^)vjvVtOs&nAtU1N z*?oy@Z-#Btw7Y&Fr2joEgIOyO;+`;Nb;T*mk65%BNmsoOa74Vp1=XE~m-&D4?(f

    OUe9>b4R3grvow<}L?${Dcw2=_9)tVKq zv}gHPYC_C>wJ(dI#=}0t_UIh7AG5@tD#SwQ;pHO$6>0`!V}>p)ZX*ti*6aBiV1pB< z)$rfXvaI}mIU?t(2Tdhhs!$7Jv$=SmN;Tkr1FUqhBmygSd!{|7H((f`0^F9U^PMo!gi2QO%5yVk57{L{X0t`BrF&0(Lm z@Xg&>*5Sjj`!XR;b5HX==7gbo9}L)f(0rm#v4w%w&~Trt(4W*fWW+|Tp0LFuPPeLL zW_^-gzxr^i0kr#l-r>Wp=Z3Mib!Wat zu;(q9w+?D6Pd7gPQo5p~vv%bHZ#E-P>Ra+b%DJt0J>@3E9rUp}oXb$!+FLC0<=IF@ zp$%*OcamxHK02ZB&IEp1%ujz6Vjbj3n4hzg(xWB#nYPcoB{7N<-p$&GgEQK^=G5Jb z>wz=F`ko|kpdpfL7>(AwhGu_f5NPf_{@394UJp$;j}h^sk z<;tm!r|e}{dM!-u*FM|`wbFB+h7X;3g)bw8oXf;#!s~+}4@*E&l}OcdGm@^p>l%D` z(qQuzih;V@t{f8;-g96?M9{H!z0eGt))*c z-wqely3iYOW24kZDf7U9=dHAgOspI(|^5R zARk*wz%Gu82;2gwpQALzN&-|=r~PAn`I?Ax-;WX_I<~H4{w_i5V!N|9_sQ;lHJzgF zox|S{#~t4gRqH_n{TOw(CMUOllh`Pm81HGi(Z3t5-xa*y-^sClxzF0<lhV z!D`rAI5IDGDEQ19I5RZAzklfY;srQI)|$WHS>KB_$Dqybx0 zY3Nqw*F3ukMM6U-o5_*K3}MmdNYccPt1pS1=HXsyn%}ps%oDuclX4e-2|#-utppH3 z0xL(_5j*(O9<%;06$YWAm1{D^4Lkbh>@nlUsrG7!la#GQo<1RyVx{q$X1%5KFLT0C zhdX96k8^1MS@v`moNMHN$lgkYe-I3~voqX_`(T3iaMDYorFgh%!4}5oYPMUp^$VBl z$intr7*f}7SI}9rdnaj61YSEgZ)NwMRLPOp(^^J0Soy-eml?WNhr(sb{ih^COz9{T z;PPc=idhQIGD&-hJU~mT)&8+^a$m$VmDnWC1Tz6+Ajv2HZ6N%(YTb|liq+J>e5Z1Q zT56Jg)o}QM+1uybEKjaewXDxoLt++rP@1Oy5u#A-9AUAJcw`=Wu7uhu|8`tp5w30z zEDCFZFz(!~{XAZqu_kZZg!`TG&ihwsqf*})J|t`o&dtrO#ngUl`c_C+k}U;oBC$gb zdqMk2`nCNdwwyGr0S1R$?_uentWw3EnDAfn{80icrdMQx@+J#Am!j@;=1=1d>hYq_ z#a2Giin!4jt^1>Js@p<2XAZa6f=Y%)zkJ`#u{O|&ulOqmVB~4>x=hv-XoK=YV{W9iR)xV&HsTb!AmrF@i zW)*>OLAC{*S3)}OYsFYFr#3`ZDg*-tScvv;xV1lR0&*tNU%fgRe$xN%&q+52oVB{-{1l;ute|AL6QsQrBF-=u7!eLYqW zbv>OH#*oHikFhmD6j*yCwobhEYwgNT5$g({ai#>raoHw>q;1bVk3&H=9XO>F9=2#k zoJe_E(>qKiLAQouKP|6sCd?eog`}X{co87&sna!tRCd&Vhs^1cj|{`AMTQNJ`jF`G z9Oe$Q(A?E>D1>pyB`wi8_ql=dG5SO2q=@-vUt$v;5!!`SrxyRRug0y2%Zy80#Ey)c z+Qp5H%%)(%)tE{{gZnk>xn+-^1ObBK6AT}uif!<~f2P8@MH3Y`%eKobvnOA1vYVgT zp2ro<^cLyc*-ZU;#lr(Qnlkn0Ar6j?Vvhs`1qHY{IqQHcAe>xqxmVQE%f7O*u~}qF0_fHBWBs8o6D_Rm=5*`$mMGR{1Lh`2`@&m|rcHG9 z>t|CCWifo^I=gMUk_*VKH71^n*78+UQ1zF-14XZxs6+UucD&k`^Y+%EuP zpfG?0TgBj{TXL1B+0&sHX*^xFIh^^U(}pOE_QrrB67*{u#I*Yhy<*@;yZ4&t{}R#7 zQDLjU;CVjPpXZ?4{*J)4;!G(ZYP;w0jP}#+bj8NT#&=TQUQwp+eF&Z(n|q3!i|`)-8DdI$AKq(IU<>}Kq@I=z?) zg^15rG&Xl#LL7Kl^Q{5VpHPb2f+4DhG9gyEwovl8gNPQ4Ufl& zlf3e&Ch&vlm#QCMiyz;0@x6+0jXvvoL&t+4IKE3!&Hknj9We()Hmt@RaoC-_9m_u` zXiZ@xMPdTOP2d&bTUb@Q^XL5P3xE924z5?-Ky@=P99##A{C*=CkNiy!0^M)V^gCCU zcPA(l0Hm}$oN@#@ifupm5eDZd3r(aHO0-9d{Jy>Pl(Cw>{F?lA(mwi6PY9q(7b->6`q@Xhqj{UD!`Cy0r5WK6cuXuJ>YP66c&sXIs%A_iMQU`1l< zb)GIP{9UJf3BppCKj!wB9&G^>$h4#17YZ_vD9jx*hp7Q(*E+r|XFlSE&*v2`GpCUV zSGs}3UNw^g@=tamw1#*{sA&|%=I?D)gg#`8N=xMtdu;>0Cm`ef=nIlwjp@sP1;85l z1_`-j(!4GH_b0&cbq~%We@bmWMoC%!{BC}Y>fk|jSkk%gCt2wf1v^fPlZK0fDLF2| z@IzA-GA#RdB%d1@$Zb0vRd!*rY$^*0R0vI`fQeUK`@RK(jqH!dtN&C%UR>*Jr%nFi&`GB>Ckjtkt$?xK)0h1Ot{e zbkU-Cg>1YzyNsgdXB_i+eW$t|sJZg7YLXBmhJBGQ@!7V)t5359LbPu@9A z;xg|8jH`uU4}fV-I-jTNTwmGsiJ92>`j4`{hWf?G3Q?3ozItnriBYjq``^cA0obPc zN3v&9E5V2w;_@RVA2Rxk{vgVmjloN`@u3mTGTS-&K~m?wrt91hu~K|zH7g2r0-0R& z#evL!u*%O*knL9I+`o9bpKU2L$I_Bv>zM`EcjVq7NA)NfHj1`_Q)<;z(BX2^WKr zCI3s1ziu1jwCPdhifqk~WTpTm)9^wD%4hLqTNb(4OfLNVL5f38xtNLgUDDDv;Zm8x z%x?-QQ~Xt){|Hx-_2-k&xDdvl^$xSBHZ-Dl)Zh&_4h~CdRe$y9@sNV(^Cy--$N1i- z!q%?3wY0!FI)Q@bHn}gS_lIj=@Mle(c6m&8Jo4Xbw5r1D>%j?3nNEGark%m(Z+qKK zWQn#G&ORq6J_OBEHs)aKi|;G?nyhU`~hF#q+~ON=N)& zad_>&*wY3BCSO+S3-1c4;I^^_CrJ>@-=Bu*Pa zr>L3w&o85=$}RD3O!^~aY^McL2LE7IqU*D*1;4( zqN3H!P3;MNpyF}a3M)!*@Sbws$*wGKbN}}9F!rXAeWI;&S3!p* z4~FTM4; z*5|MhLFs8;O!7w#Oq^-`a9Wpq5}%i}^Z`|8k-08NKPX2ocM(E?PEX9rcw=;t9WX(b zYQ7mr3z*t(&ji77jGJ1=n*5mzmA~7v^Vf3KFF>Ut5u18$x5PwlsQp4=SLjeCw5mW% zqlaII{7n#1n*Du|PBd#h`VN_?88dPP)bLN|$!gIwBv!_xZV*>wXb<2WN&L2NvR8L0 zB96NuRqn@kF<*9cb17mUi{G{oAR*1-6UYvDbGv>kc>0DR@JV&W5GmOYoYjC?9DsjBSWv;psmt)4Lzmd&(^5@_ zB#|v!ty|a0@LYxF{?`SM%la%A_G66`M17s(^;qR3dY@C-{TLn$a1%*D2DkbcDeKp} zEhT8HzhgXE-LUzMUd_-p{Y!}3jeUAsTicSjDj%6~bq9`EKKR)Zh;c!NH}ePXKd!oK z55Ws1V(Waxj`qH$x|%_e^YR>c+(0Z&Dxbs4dY|Oh((G6?926z;AO5S|5BX#EU+wiI z$=W5n+C_C%eN|Tj3j)xw19c;=kl;vi!Eao4CV`I$R4^ByzUM1;?|Pz!9?kD|K()nb z+KqFmhwC2ai)RJlE>b6)#)}fAi4{_reF3HaDCl+ZJ0b%65Lb9^c2=27h=xph=&=Se zV~9OIFq>UmUyuByOMjtLJwUUt^;b9)&Ffr`#9lpCo%>hgi&x3>*CJdPX8uvDdwT{! zXdw6&41$Nk5Unb4hm^Apmr1-4TXQGt&|Jz&Nk8#Nojbv{O@ib0K6>x0{W!e!{&Zas zrOJC=U8v{zbNt@O(0n#HyXCMW)z#J$cwJnz0GX3ocmuzRk#`d#tk>eJ_9aYA@wYhe zT~bFSUKB#5$n`;USX62||B5be8O6@Tt>p0G1#)t_TP`R!t!0##nL?~BKi>)CW8E7d z(?Wk4+o$*MqAp#(#JXVOz7Jo1FPQcn86GyX`bd-X@lV_8r^C%0j#7^JUueJR21n>1 zf40Ynl@K#SBGB6c8kISKQryUX@xh#@z`J&Z)a-QVLLqXjX^0>1aIaGD}hTGzp z&h`pLULT@h+nu(Y&iyy6nvIMB#CE;)_BHo?`7N7=yNAJ>Dm~Ow$sis76$xh17q0_* z2h7y={`Y*iFY!G7=7vC(FnUg-!;E{&R2Rahv-kP@=)a8S@{ItoJO)VFVknn-AQ%vxw4Z(qGXYZM)dwju8PPTb z1(wa1qv-0VQYBwY1&JX2Bm|U6Ft7HET|mOo`PDoFlMvcJmPjL*%0`jozfeNM>V}Ku zlvgiYdD~|rYLB-hW#ELG!lrC;z5d6kcEOEJWVAF7dQgoNHa%xWOm@P%AApYbAgACZgp-q#Y=5dO zh&4}=Hq&iv^%F44N;Qa){C?Dvw~sO$@?MFsN)+`OwzK_aYjEaK(N3+&YIyV8=zub+X&UHUq&RLmU8Vzc7 zJ7EpGSK8f(QQuqmn|nz214k-%;F-y2nyG!h7pEoMF|q5bom!Rc+`%uPBJRLOr}ot) z`4LQe@pU;V&|X6L^9`T(Ih|rMkZ=YkJZaY?p}t_0<6JL{~Re^JzoHi`NO1`S&^NU8U>4i41pA_BKT+Zk7^*G z@Y3E;hGs13#<(g5$}79KXW8>z#m9V7=B=JKD@|IFOgU=(4PdUMXsuG#Brn#I}clp&{&??n!Z4zps>T6QikH5?G`=dV1aWL#o zn+`(h`LUXKGlr8vJpCL=d`^|?H%>O~BR8aGB#K^N0cW~k@l#PQFW%HfFI62nsf8uh z(JIxcb?w@p+!pT%9p9#IvAqpQxUtHsn(m(&bGOTyoHjH&LMjX3s+Hf1-28x=DuctE zAfswFYR!QiP1n5%XIf#XHR}wqg=alMPUXf599u-gS4_ z!1+M(ehl{l+l)jQM~o4OVp!Vrmo$Gyl)|h-reR9**|X;r$F+~#PQavR$y+)SjmvZ) zcm1acQ^ej%{*co1d!{+!GWGXW2rE&jF+i`bMI^T3kiT^&>8WqTY12bcG%w9qkE%=m z(s-v@Z*gHvb_&vc|1C#sjK_Oo@8wglt!hxgXTtaIxAKeKDoFre??y z!Iz!-oJ><38iY+5n1tn%$eQ;!2SS0{-|xGKNsagG-1pHSX=)7c;DzTYp&1MT7f#3r zDmB!-Isr=Dn+s5nqOVW2r90c(AK8-ay}(Dd5EWW`7Rv>43T7{WcX{pjn?G*|4<*zz zcpC4QAPNmgI?dE(zzGZTvT%auZ$}% zppw}ih3D$L(S9e(q5y$i>r*d?qWi(09rwv()aq?C^5u$VU>fJ7TeB~6E-uQUT>BWv z@LZ|$lRI%mrVRm!xm9+QjV2cma2)*Qebl7)gPbP^M(m>GY%L9

    yI<|W)`r|HJd`UaE5WO^se)=VWFVnn?44fzX_~;KZxgO;UJa~9q4=#xSC%V=V;B)0PVsTVV;n+ zq+4cd4pdlpH&70%L4vYWj1MESN*$}@dskQTR8u-O{xA+$jwodf0H&tK4B+@=!+xE`v@$9xS5c$+jKzA%oFgI`JQ!gb8;HWt$q0Z89byktj@e${15?5;vwgrD zJ@58zyvz56#{x7bf@8$yhKE8SJGsWiN8dD&|um(?=P5U`f& zV?Cu~d+G6H?^zUP_!8?oDXG@mUw4qLk9okaE+11R5kK1cN?LfRixkJ*NS5nD{UF!a z*cb@|phx~OSt039Vnt(>Imk2zF7YBUaf*-9p+BC9DU*DYs7lA6_48juQB30bzHC8) zet_nRclYwtI`95zxEhF?E-o$}i@`h%P>Cn{QjkOYGi9jq`g|W78(UML-zuXvDlE!2 zzNa@(&XLyJsvg5ETt>FFL?&ECj+?5-H{^;fJDKD6KG0*m?icV9)~ab2VxkX8mcUY2Nmireh)qmWEUMXx=ZdZUO|yQQ zkwkM$daZ2_RZK!upJUofwV){()C<2L2^aw)7*xwQtnHR)Y%M>7nx1tfzV~A`=6tGp z#3VnZsi)Pux>MnlNDu0r4iyS3K@&?ubTVr9&#^Y;@@TT`c++STLFc))A@Ff+AmH(B+|KBk`|LmS(qB5m>h^jDJ zL=x~cZn;CPhL!)FovbB2e<%Le=`D%l$zd3Pua82cvo1_CdHEI{7Nti0{%`ZVd0b9G zA}gdTlY$e-$M*|E?QNp!kfjg2b_!_lET;tRpV&S>|0=N9*xa1Uzb7^lX4)8!7xk3a zKjFe<&ijV!yYCl1;-((UC1ij#yz^Z?AbWu))BNj8e+9Qk*{CWSd9AD7zbOT7nLv4n z(fFECvX$@DX{s;8+I_g`t|H+VfX126dcyuQTL3d;NY{IMN~Khnm(J6N>w#n6#X-?Hx9XIsk5Jz@X!Ccs4BO8fVz($-b#F zow>|g@df_p&$+8%qw}Cwt-yQ49Xg`$X;X#3&idA;$8t(*aJ037!=A*ISpGwa>5G-T zwjDh5fbqiRE3*1|Yr~HdLLB;M?M{=BxzC>X@>Ji_e>htI9Bd~=Ea$gu`L3s2jW_9{ z?S+a#0Z94;3oG#2+QbBvGEqP%pBfIP7Il{m8GjSCM<{lTFJFprmWN!KE=KkJiw?x5 z+*@76CntZ-_HC9i7%iI7(cWJ9%D>S*Ixk-d4GHy$3f;2inFRG#w3zl$jjRP%IX1=L znos}m>7%9MiwqhP6???hwZ6)#@XY`0EYY*z&L{0*sFQCkhTn>uihZc2eK(vVm57sf z@HkF|ju8V}CtQsbY^23!d3UeGPC`3f)rUaXMA-N5v9$Ql^EUeAx967VLwHde9o3SP z-{Z38b#eUxg+`SIZm2X>0>dOxp<{<#kGTk%Oz*#-=@p<*+}rvwKf&!epQrop*q~m6 z12IQrr<5&1O6m3~@|{5%p0+;uh~P9GDY-2BtZT!ZttfPO1B%SKg$(n#J-itVDjFHh zA_@3}IT6<>8{6QC&NekGtXxxjdBNyb<%D5S2#t8fx(#cY>ylM^rZ+=6jH`AZ8P;z1#4R)X;Vd5El zl>lD>ku-R591FVskfxolcl@C!$eiw>Vn;+kcj&dAy;-9x*ZM6E>OteZ{jv z$wz$qmNJ&Fj4vY_n7s^^lkeJ3T6g(#>=dz?5?12{$2mO{tUDK1HoeK-d(OOa=Eq-f z_aU2?E^-aF^t55gqAt;;@tI^2*0re_M*H!yA#vk40QQ?F>(V!`KasS%$WXJzTSXep zKj&E$T6p-MaBXhdGKUo@J`O?Gy(~E^87kF1kry;A&f|!fpR815RhA=Ckj$}Cldk6G zx3acoW?z??fMoI0r_2iv8L7(=$0D^)=PE+An7gP^eNRfT()gsFI0`y#;3Q%>skrYv zXOcHa*V!Tr2sYi=U$$yVYJbkE^*bF823ypIg!BIW1M5*~I;$V$#T8cZ3kL=|cS zNm*Qhjw;E^F>&v!6MiuFd`>_j_3`oPH+-d4IGvyOFy$Cz-VxQJbZQyw+cW%((U*-d zfuPQQs(d%k=Jq~go|o?0;jp$Fod(7B`6(;$V%$g{KOXJKrnJ?&q%16SWKM_Ob3Hsk z6BJn1$5@&Bg_48&t~+Kf?n{*C^DJI^4XoUxaQ~Mdok7;-dyxtX;hd3iReb=#2vp)8 z-_?Z(!})+hs<7iV&{`tYh>fKBIOKq?1$;^I)3tQ+z54Df3)%m{b*ObD0jyn?1B{$+ zq4e*w>#`n#aMluqud@=aL?KrWaeGG{1?BO&@4E7kxffeGTN!r;7~?}sjYTT1{Qt^JIuU;B<}_>{GG z_T`2xMiH~ZtlD!CW=<~B+ZIW~Edo6_`x&=~fu1E*3wSdwn)06Yvk&@MgDH~7fyh1O zV-1OzPUvG(;{`0A-;8**x5D}hl7Fg*gBL6Y)63Sa%@@Mgi;t31&lHX9=;r2z1OrJ= zISNUEv|AN@RE%F=^WAn6;-C;&W!UaQ%@zn$RaHeqL~2bfEkop1TQY_1s~z$U>UIDV z+M8C(9D|8#(BMIk21t)`TBqmg%;yduY;9?23FG*7L6u zPs(RN(h`X5S;AB0!hMV7wz9XU82m?0C(j+ARrcyaLPGlb`WOenx?K2=Y=6E=vUGyz z{K^0ILph5akD1TXP^Ij4>f@U zG8<06vby?+csz_nE&4BGqsRr_3VvE}h#h_-=LN^v-W=(IfY;?=(l0jBP<3=5T=2WK z3?aIGrr#((HDFs7<%MeJk`w9m37 zN?q+1;$AIyHtY@0A@9|A>z5slM=yv4#e6Ts6(p11_|2w>n4R%1YT$BLn$RShk~)yj zT7+zlsf`H3Pyaoqv$F!JS%5Yh_2~n#PE>q<$H&Kmk-Abk)51u&pDy8ct5HF^Cnx!& zD@-tPnS7Yg;LV}mLPCDZ<)Xg8dUPIInUwVsNhHQuPEs6@I~25D-lku@tkzzP_p543 zAZ2oadnC^!hNkTaRotIQW0*%RBk?ary!4rUJ*)g{?yqe569OFqVpO}>*3-K=^3U`N zm7?q5f`k0s=A7D!2U$hFYcvLmYuIgySBBDe=AT|_Dj;*PWR_eL54d6v=9Ite<7OFQ zIHFc9{#@}~-q;9E<7uP^*En2oQ$w}3L85zbwj#=l9x5oqlLc1VcXVnTSL2K#GQ7OJ z{fT6+$I-_g$*dPdC1LUyc8UyAJ-?}A)zF>)RMgh;W#HX=4~oHL*Dcs+fBaT)0y>)< zHr*Sz+tons;tZbRT&l;_*^kH!#+E9&$Mea=%6#)pMukfA(h+J^o%Y5-SO?H?fihEC#$PaZU-^6Mt41(t9d7q*l2uCXNQG` z=ejC$0{G21)&Xsak z$v{j3!e~Az@t$>q+^3X^zx29c9M5n}5b{8+AGG=`8l$1+WVXocL)BX-Gi#_V{8juu z>-TzB==M}Y{4X;zXl-t=BoBtk>O_<=TWFv0H-p5lb9?{j?y`n&H@>r;M46Q5~Ex zi4@wS3c4(TD(r&FC+F!xZ>~SPg?&?ZJ4vZd_t+LG7m7W!fs=M>PQXJ z!fEWQJuK~B8TO|6dKnp*72KE1-n1!%^!3+&Wh82TUt&x8o!L|^*K}@{;!pER% z_b#*Wg-Cavs5Ry#u&7oaAo?GhKl_)~z|D3tzVkN&{!>y_Y(GJ-)(3ig30g_HEZ6Y$ zj*N+U=`>%swIo~om-($%&RF2XUGk)OWXQ2zIZaY7eAqv&^enEJgV5Y*0V459;1r#= zEkO!r`VW$`p7Ker9wWcGg#=R)#Zw1LP!y!tGbt{|+uQd}>G62E3wjD#qyyPIb#bvs z9>IVCu75YFl#qp2^5(a~P0F9SJ>oXhL;W39Y=ee#HSUa^p@QL%?6M9;Y&%J z9lWmfN_)g=Xg*;!lEL)rvkXTr%ErlKm zy9-5_ySx}Vd;iej+cT85`SGUilRkB#L}mxtF9iYJ#dtYJ@YWq%2s5%?qo1j zaoNx*QhsJ`LI9{Oml6o0&h-wlDeArIsF(L}lsF*S5po)a6FaKfgFgz?r}mg#1*Ylb zXz_qRXbW4n_@>XPAnkN0ZlLo_^?$t(WK-8)o5L(Wj2&3%c;ag2#SzyNK%SR0sR@dZ zRQ%MpJm^s;lnUZ$_L$S%cS>sxsVt;Rl}<1xSO#=JIW-K&cV^M>f2qO~w`k$!z&x-Q z$I)}zY4NXIR54FzN41trW^*}m9BlA;dgyf;f?@|QGMZ!mWuZt#RMJFof!z6O?^}1* z60f0%r)s7!q+-t7z?kS7Y070xA$HR!*23*=>Iqv6rb28~;ApFk&39lI;HHJg%@kL% zW7`hUj@TQYmwGr{dqEvk%M$BBWF?4wJ*WXU5*ZUqo(4g_2dOb%`=Dyvm^uI6h?yc7 z`QYP4REIx9JVbwdp}raGPgEB0Oq5M1+|0>YKIk5q=mW6zUd)ud-)~Z^yQjNF*5)9m zqCK6r9{kbe9kGCu*?0DB$js(-Mx){KVZ?2mWv`iu^{C6b*Tv>1A}+rQ=tGC8t^{Q_ z0|#qZIoa{)-mnhh=qao=4~pufYW4&cI2mAyD+(1zh(b#skL8KuPkgiKwuS%C6l8S# z8?_wH@&Q3a(;?+~^utK}ndC9(lXNG1_zRXk$xDsfC4dl zOzWS$yI3G0@FJzv5ko|alSFpZ944U?GhLs9(U9MQkwP_f} z%Df*FMSuIQVxCEQ9i0v`9?#-ZqWxM!Jg<>fJfIgu{0FX}{crJfuVE)~aip!&yExC{ zoqx-2to-2NrLt3edq<_|e)X}dP38c@Xfa0d-Fx&p)9^C{`F;%VP>Iodq(YoDyxV7; zm#g28x;LFq0xzsL{M^6>KHIq0S-Mt2)qL=fSci>U4;71qapwduM?VBE42u@Yf36r+ z;s$eR?Bu>7CVSa8kdXtrSZrx9l1J_qQ37#zGkw!=b}=^NORD4{7uwnf{sbpD6=W~w;ckF&B|UHl zWGk^hp+B5L$b;%{XJ;VFPhdyu6wj|X)x9df5CkJ0?KsmMJx>hBADKNjzK#w1KT*yv z^>8e2)3mgLybq*t!>|I(-`5IcxqgyG--=wS4i(oiufwO=rUl1mt22O3KKADsVqUB0 zl9B4taD6rST<*xfPA=cY*UU&hK?nn7UTCzi23b10pdz*36u*GIIqb^Rsjm0Le-kYs z*6z%XJ_?h?cs(*5lYPYIEbVnRxN%qMO(Jy3;^;|TJMv;igYkD09RI~f8DGhVY+O5n z&wEm}z_E2GhGR#tofTfmn6j%{$3M5>{w5PBhmg)^sSVuQygJ^%RYa@arQv!*@diY+ za4-3&_G3LN=Yxu}cE(4Rg`&JO#UdY;*_E;tv>g%{j6wEiP%^W%`KFdLh!eLd~jeZCx(&a7G` z$n2-Da87>G5Nxl<4V@|jf(Z29vA_yLOdVT~?rr<#H6emyVA_UCH&C*>?N1<7kiC6_(m$mv;5$Tt;RW)-6pO<8*$S_WUdwVpHaFk|}RR!59ENl%^qI&w@MVg6~TVhZT4m2GQ9NB*tL}EJdu%Qc(VR0xT zcQ%zaeWxET&cQWl1F9SI)15)){5$m77yKJTGDD+}5GOjWs(noud&j(=In z-gA17ob5>p$&U>T2~FOh9KN=-^-Az6*1**~;PW6Hh`jVc|c zxc4j$C5n%rW4a5H41q%&Pn1sHcp#6_rLibE*%U~2fqh6Hhf(#-pKKO!Q`l# z+jsr|ufUE%gr(2}$0nNPjq%^38c#)?OML-cC$sn&ehJjw9f06Jws8=i^XjYwYP?G-5?FZZe?#9SsvO zkmh^k;n&RR3lRvksz?Nxka=lVV$l2{Gd@Dvkribx?1F7zneiAx;?xP9;`te&;1v-t zA*f?u-NanmA6_7$CEavY6qT`WY)y;h%dyLQAd{zChmeB9|GPA1?5A|LSrdfWd(XMdc)O#XMdw8n_Wu5`9Xm|w7| zefn!8BU96I5N=%ibnNLvhb}$^faB}ik9GT+7q`y(7RUWBSSqEM?lV@>d_L%A>U^v{ z;XNMlG1xk-%R?ve`VRd?Y8so;^tEpayuP}|YYnIEaNwWirseEd=EEYSJh2kA`?p1d z?2B{IDY_7PtEodX2CTNtu`SkEqyr1zSE-U6lE@s!P9o!>7B=gOM5{*i6T5aJRjdMw zmMfHg^3_U#-wOk2!97oEW58?oza?Ko%i@>L>{|x%6$LM)q%W!ChjUm4`{n0}OR2NE=}Ce9PlNL*lZ?I@3->kMYRyI#TkRm1UxBPAls zW$1%ErBRq?@fQwbdU#%rZC$od|7X3MjOxNH+=2~m_$S$3W4oqlLU+4lLs7%h8FiPz zl`SktA}viE6LL?wZEnsRnNE~*+*ib~J_4O;Ojx?$MdU;HE^tMwtXO|EHTOcdVu)+uOcF zkhoK`nTA$!*>p>ijVERD^bHb|J<<(Q8WKMeJ4v+mK7ReN>4uNuyhI*a;U6gk%Rr99 zGzji^`;02+DEaqP4|u8JNZ);#nLm2XkcNtiCWWWHcSOS4J+Ae2gqu#{t46S*HZ0=3 z39vVFf{2YCidZ}hti!v9h8Q~eT%}VYMrdjymOdYYggACxB&+6MNY1etV|#XF-Dz=T zmnVNP&1C!}0e!ED2_5R+UvSkwKxGh1Tvj5ciPIPM$eaj~Kalb{pA}67lhSd}1%6?@ z8ynaD+AWct^*liUpWQEVPj6@{3%`$fmYt|i)of$&l(F8_5NQheuz>8R+wVWHAg4|~ zYR-aN5uPvDr6Q#oI4U+{Fu)x%4?$L$BkyP-W&>e?rU0RnTcZ2{B9Wlk&22tPQ<#WJ zk7Z0GRMYox(`M>XOL2^c5+3>B!*;@;HCc1Dyb!3nC%&fv`bI_cBH_XTKWSLacQ8gI zOuz zV$$w%huevHgw%;I|BO)}@#Z1-vZze2O`8MA%~P8g>y!^1ka^KP*07JdclYB) zg0j1$S9%4QR(i48L)RA1eW$Xp;Jd?DeYjymj*q!6(OvT!Z?O|wvP031ZSKZ12)Kp+ zGZ9Nx&_HrM5>#U3&BmUZP<;;?HI-L@0u8&shNnX-jGj!B4)XW0GP-<5>Y)-Xsx_}2 z5mF%RW}go-4UXlm$8qTOZGKYe@!V&~_Z)ZcUZFqANM|JMic(g9HW8P5fp^bwa`!V< zxj28>tyAGdd=)1h7#gz&>R7*Vn0O$=3=4n0`7Dq4tg`W|L!&4{5iKzFQ`}%kp?tYm0Gch~tV@9&q>~tkfP@&F4DI!mIJ#BPmj$+JH z(GFjZQR)$wpp8gN<~cR%Jl*vm7EOCYr#|k=ZbDKvV#MqeBK_6>UokpJE>i+f|CdD3 zo>JU@vkHAkEqln2Cq~ow8BX-oD%b!=OE=69w9;33{a@BnT$5vXzU3jYlfO2Z-X%n$ zxv}$}W3y6q?NAm8V<)qg`Y}Yz;L`vCuOJLmY8 zJmAf7*JFGgiMfc{)1x9PJeC4A8#4eW;_fw8D!9GjzZl0U@uyC`1nki@vWcRpOxcZ{ zQ{{xsSBx-Z<=vRGf3at$6Js@EL1BxKka4RwLxz8fR9ME-tc6?Z`Twt#Ndk>vq(K65 z8-pgJgbF$P|K+?=&I}}DmyF4p#e%rJQ6&*f_>hB~y=K8960vMF;sBPbIzz7P&IBIZ zwneRzHU>Es-C*^mEbiW3`tz!)de#r}UO@pEQft;fdUP+&N1Zz`?fW1Ml})b`-1ED6 zmQ?mumaDk8zYRU-XZAcevT<8tK9)NVyq+TixY;C)50b)RJX-9F&fxikHkm+N@SS+B z`cI``=FEPzPK|hW>?k#Aex6wxVvKNmfQwR~N&A>^^y0sC96}H>mfp)glKKCrddsLR zv@U9tl5SACOS-$e8|jh`N$KwHkW{1vq(MTuQ$RqvySwXd-gCe4-Ft@r4l*3iv-jF- z%{4~1<@Jz*l*H?;|GmGuE=02*zqmWX zC;O{)+W$%XQ&XiEd;3Bxr5YJw2FS*n1pN)%7w4IjT&+{ie0ty?C|0Va~C+29xOOo=NRUQeKPD13&Z?3NHG}3r2pRMW0*UcII(o$E~Eeu2FSf4 ziA)P(nXOB<0*S%6eqJ2D=pyH(f7wz16QQOSNB;q@*V91ldewX{G)POHd68&ak7tVC zKSFESI9|YPLAeXpS|y`SEyExxu^iPD6~c6#FT$6l7t`*@&Cs@i0=8kikGxcnMM0X) zCBDuP&sfSj9BtvBOfX{_io(|>aga(@tsSchT)jbYD53fPeL4QIMz*ILbMF=^Y`&h* z#Vop;o5bL1ghB6NQ#YHWh?<)?w|C%rO5myFcJ<(T{!TxZwvJ`1HjUBFA7S?|Q0`2+ zaPK<**3Q6GSop=(>Tg6%k|_X|ztQ2Z(Xd!lSuTsjFGAY$cHpx9h;fb z@{S||NB)N_|GhlBnOPDB^rj=uy9pDM7!DgHLYe;c1X?=JTf4JndJ4 z{`hxM&aq;zT)T-bE6Y3m;-N9IHWhhVWwW)eP#h-x4w}#z2@nx9S8WQX2L1}lG(0jg zFv`vIITF8L#eu+Z+;DAUepkj?3Mm6yip+l1|7x50f1(EV%PpXb2!38#TVs@;wOr}) z_MvynEDIq25p3~Usz}ocykpA_53ko8xEngec(H&jiDP?Kw+~_%gz4gExNORp!F}58zQtXD_6`cwCzngG z{gcfT-!^W^tqY7>LKwxOvD=t)~ z(=WuR5MN&xQL^b{tJsNKNFSE%&E{E&%PRR?+5s`GHe6>AlbG7#*&f1LVlpFdpcPX$ z<$TO?5)>K8E%-O*oglrZK~@E>wZxoW&d3f@*Kr&oWlSQU*`}yDFOWe1kVuZ;t~i=A zExy2|PVv|(IpiLFa2LRPWnYexxO!k>1}Q1}hU=%7N?Ee*%dHv0}@#yW~0f7s_3rZt18wCzBylmtr^6%{~E-^Esj44A0m zE^L^)f)#UZ9Od&T=wu`#Bl~W3*Yf2x2Z|1?dtk}aK{D(o@In0FbfCgz8;kM0JBH!R zk>o^H*yWZ|ZYhuJ=E5(b{gni&MaD5LrZK6rOj5e}3JNh`BhK{i{pZ1b8tNPQ--h?t z>EC`6xn67~YdIj8+Hi48T`rgj(JkZLcnoDMP(TCjTsyD6LOd<*daCe%V8hE`b{i8w zE#{7XOp$%2tj{;FkzPoNovj5FiY-fuSlVQFDmm%a%sH(h{D2Yzm<{eiMg zHV6^7E$B2UwqV4!pvf2_CeyC~?#dJJ6+o{GK>#Av+_r|^%FD|;#<3Mekb|6cejc7i zAjVHMT`yhdUv~lL3oseLb()x%=#M8UR(k7vjxNl=fSk5UsP(Mg080k=VB+H9iB&+2 z0EbH0=yS)0nWsWePapDWsrhQEM1AuX5NlR}u76W>-AzTXKvL1|crjAr2c10@S)<&v zBk%(d`oWS!x)v||{C;RMveapJJQtJ{QpQpn8ymT_1m0O@YHHX93kQdlYEx+#x*Meo zTS6TT)0H+~4Nr|vx2J3Hhm*ze(a}h3qR)vHW-YW@2-s@8(nZnCa zQ+sznlN&~v0h{)Jed0MHq$*jo-HW!ui-tPXafly(0qu}J#%I$4*;5{>80&WNbo+~E z+d9v7fgcLS3eM8|QBDd6ZVEqD|LHXxP$ig#ICL)CqB#h7T&$zuN_C~njpxn$H$B+c zZFZj(A4iCqci^^*iA<<4vx;G|fOr!} zCd-j@$c7|X>Rg79?lehMnP@_~v3`|@qSISnAD>k(e0+Rj0T1-|Y~I(OHW7Y^h)uy* zzZDXNfq;mO)NS?RB$PG_&Fr8s0%<~l=r&Mv`8MB6jS(cI!m_v>V5e7)fkS^ZdPHg9 zLP!H5+VbRN^8I_q7%On{dpkD=lLM)Kz^>EZRMZux#4^-j)`)Gb&D+n{A>4#Q-?laK z6H?Gmp(w^GsGw*Ne-NXiQm%sy*m=#k=QQqsC{Syjm_ox&b#Za&`I@Kmufjk+Flvgk zU_n~*6kwqc8raepr7$kJeLV&n%c-3fazd%m>P({hI}z7#VY&6H+2`it@@!r?ZwlH* zOXYGc6~((wm!cygzFQ4p;4d)+#A{#7zhUsNtsX9iII@aGN%36? z-&X5Gg92z9Q8e$k4wzr|8lKg>Lnu8o9BUw<0c9_=8!;`qYt2Jd!NX$H3zQoO`}c&$ zr6x(y2$tA6nwpv}Z-b%{avVT%-h26{aL0Or(g>(MhtpH5coJdM6ZAmGMs5(qD4paZ z0f>21kU2o<6c!A>T3ugHWr@KV$iXT4CILZTL6K9&@n9{j8?Ki|9|T2&hQ2X)V?c^< zOf=}keA({`FPZ#X;U*5+tRl^9mBV4SDiHmR7))a?2(S6Bj>!gD_}(c+U_!#`4)D*_ zdH&|XJBMOGPP`|y3fyeO;G32)5WhOwcnAM?R|7*g{r=={Pam3}_ z<)}bLhR*+n*Ol(J|MUPV4Rh>!_9VBMJ>z7V--b}8F19J=*Mb>>BJ)?yjqaUMRs33r zMnWEUUz$y9Y^cmx-3?EgpFR4Te&+|Wib|4ZtUWhJJ{y`~jRYQhLQ^K~eI~DM_-s+R zfwxq6l?KTUwz6w@6sIxuBkbpg{+;Yj0eIrWw#Mv`>>&NPjyn#~q9+7TH&A!}BW!s= zu^y~q^HXLg=8gqQLvqYK1!d>kU~$+6(U95n19|{d|O6nMIh1grIsqq2j>K{zdPHYiG8x&d!6RFH#v9r_ueHlT* z08A*9;)IEpLupNlWuWPm-9DqF0b$AclO~huS4M=D&!@0$lz`H`?@U%Gq4-PAiKo$J z57SpxrqS1!tP6uA2RoqxQ%YWdU;#rRx_Yz3~a!H8ksS7ENR1KVPdAS_SO!!oZ?G(_G4A)st zszluvU4AM1;_SY^@Us+Kz*fL33OcZc=8|kmj>})W&pDoQ!j}jpzyP;v`cDwa7fWD;;wO@MxsH2;QtPIH5Qwk8FgFkl|? z8^PhN;m;JA!=Rv2av|O}%2;}|ijLOr_;P;&=oLB9Gh|>VR4g;GMbl)4T5Z{Aaw7!2 zufI20RlG?+zJqQU$IkR*OF@w3mE^22Y?Z@GrdIy;Q-L#3Ku}OQn^^`oKR-W_x6A3R6FSzJ)6YeX zE$1sCq!9XsNYmCrQbOEd%UB1_zxK0Lko}ntgt1}rXixh29k_W{_|Zs48I;N)`3q_MPX5QAL!62M#am+pI{b6eL|h@5`Nv#nP=3* zamhkJuZrSGv$9IXy#M@`V#qk(2g$$1<;3JU+OksKHiEUP!C|Gqt*a1d#4lp9jznASy9G>U2kmkJFDn_5QDqaBXx7mk_(KroHf1w2DUFyIUO2v z&Cz}M@pqjSb>oM@qUnx+9mX9+CO{q}kvnc%{K=MG1LiZ1f2?fyWgQfHwZdK+KJO^u z>jsAepqmh%)2=Od3jh20TmWB@YnUX8IuIU4LuQGeFPWyo)MB?!lUqvX3%{@7=m}*1 z&8`PUPFsmE$JFJPp^A%CKw|!G&PU9+o8zUKmZm^z-R^l{(x&{CPtifJ<%W^r*Ujz( z7MX_;vu>Tt|6*ap0sRJQ+R5u`KNg4Hu;e{Bt*#DcW(9F7pD!*iC8%#{U_ zBco=D$1+DSoB`(_>-DKl%?f>4`_8rQUq2vFRqzzEn{}Xn#T%CGH~E;nHX+3p!8>&< zXqsp&`NwZOc1-fxdsw=hR`5$k&K;Oz>22E|biIecs-%K|D1w_Wg_Na_tLXxxT0!T= zl-r9J+O!5nrg29Rwb}Fi^~d$487fW!B`E{ej&yJ4<@=o$mfw%Y5-hk<#v|_u13m^t zOTCHeP3w*EuO_otV_E516M7?F`0am>nP4xuMX+EG6og4jhPS={l!Qv`qCE7F7>ak4 z4hP~`fg4|*-r@+|#Hn%6+Vd@{cjX3gi6!i*R0A6D4~*cNNJP$*vF1)sKWM+!xKN${ zU_wxT>2>!LtrUOO7$mze8!52mbaGHacUJZa(_~tqSbg3eDQt(J4a!=sqJ)luhlfx2 zoF;)`G4^d^XJ==7yQt@9q;G;5P|8cRGd@e`TgJ^Bs$w_1MQbD$Hcy= zSI%%T_ucegM;nW&VdLY#FZ?E{_IUWZurAi(-tF zaI#Rp!G)&W_0#CXt@dxXTz+Jiqyb*TKDug}-5BOnCvwYe-m3avuD{RHUhR#1c9(`( zA!fvtnw2q*kzk{Mjt+yvM#-m2e{w+0pJQXmutW@#@g7G0@+l!*I2n#$m5FN<8+y#_ z8%F-0o_`r8zU-`_uni*Ke+IfouKQ(KD6U7beN~_=B>3x=sExyPVNtGvr(B$KkmKC- z*|mM@Jk$8>$8OA{WQ*)yp&0F0-B)WcL-thgUrLIA_ceo{;1e(_i;If`+6&-&lLMqe z;AYO0>q!f?&&|z6sO##2I5d7<^ZLIUMfem+fsW&4S|=SHq__1bSKO^^NE-VUu%p@!bADovaD*je<)8ymz-vJ-h;~=On=q++| z?nzZuvn#BCW&Le11NNJh&2m^z3nzdn6-&>~mrmN38u=!z7u(-BCVl-RY5Kg594l;X@e9InKB7|kaCiP>=i=*u^#=sFD$kad?W8Ni6+mVO5<#YXWX2Y ziDgfUR_AcRq+J@=A}*rq|egd<}7m&GkE zyZQOqS(P0GA*YyxxAY^c&p~d0@(Q8r_@TR-8N?fQ_4H7(v0;|1{;Sk)!h8uaO8(XJ z<)0QSY4N)kAzmIHa`aD9p3k=%Ugo%2P&8I3x5wZC>44s!-2GSn5Q#;j!UP5CAE(ng zB~{HTt}pQgP}Dm~{|HV_#!6BrUBZw2nkp}SWR>X4et~sh5?BR87D3#2E6y8-1-F9uS>jGT92UBiTRk;$ks6^ z9H&dCd89s&k&vu_YD=DAKRz^spY}tJn%V>j6i+iQuJ zEuCnzSy)ikT+HcIr?ZOOIG9%%M4qB4z#G?|b{PyG#1kgv z@D&QUDrg=?`Xm(aD+UR=Dfp}>M2tzttzT4&uTwmPNME1D$Mp!-M0;D|+;nhV2VT`b z{H|Qoac*`j@OI;tww{l%bB4>J>=s8Ly6z`9j<$86<;uX|--#fy=wLT7%^>+T$R07I z#j=1OX~CiGmFHPG;k@u)kcrh57I_9}Q!LEPKFwCGX|>-^&lvfmgjs_ydH`^yG3vS9 zo_^%XH#9VK{80Y$=Q~EjsY)YZXz1XT$8GNKnZhr3V*m;t92^uybvC>&C{f@nYEXuK z8xS82E$OIybF!km@ioG5Ksr1e(LXKwlgD32%ScEW$NDw3Wc6sr!Q9ySUv>oAq2&6F zj*xL|EsjB0J#Yf!RD@YsSq(Nqy8C`WS&6I$V#=83vZgWUL=m7NArT08!1sdE2gGO59QhOIITdu}8YqL` zUC`fzCjTgZ50{4{AR3}xp1?~Ek(08&XGao}uYyP!8Xg``z^$}okN*D6V2R?XVh2qe z=NJ)y5pqRrU+oPc|;FHCY zbnnOvIznW5ZT|@y2v?P?1Q4X;HfPOWe4W9C8bG*HrWVFONL+f$Vwz^+qK$9rM%w8J z7~jjY*XJO6tu&^tTfr7-Ldb;CVo3vU!b`6bS3!4W_L8OJkq{AA zV?fgNix#LyGwrvCZwUDus~Q^{>*_TAG~{ulmh?rK4a`t>J}lN*vp@a;pt1d8qbwd1 zReAU93h>ZrquqV8OebJK2yGlk$QuOBQ@JU!u&~hZY0d_mHy+TXgX+^%Zq!b^#zH!I zw((~G3*)rO^+1yxPi~=H&pjo`^md#B6_NM?OpDm3x*-)v_pT%9nwyU~?;MM3Ow_lKx3NBuW_-%G*kCyj|nlaIJdg}3;olMEAz zGU5rC`J~3-pF$sp&cB-;uS?qgmolVI73f1szDTW$yk=#&e<7-9F_IprA@>sB(7=6* zgAy6UvG|{au{}5rl zGM5ObW6H?6B^1qpY_Ry&`dQ$L)&$C%gO?+vm5G)g)7$?v5_w)k{nJ-Z7DIef>LZq5 zZ{V9{IIk*=+&rn6YE2)Q1H9bPiP%OP|6A57iYaEBEz37MZS?(6&2N9&Kk$EgY9C4G z`no78FF(9luqnTWV>z0A=kRh~Y4mh47D#XO^tkhK_2mED=w_gQc(uB^%Bc6NVYGq`D2hib2t;aRHV%NIX_TN0P?n?LqC_fotV|ui7InJe zg!Ly9dGkW>2%M?&sPTGk&dzeFs3%&mE4aCvY0ZL^jf2H_%sAALw5Icit+tULy|Z7@ z@_th80F)@bW|xwpG-$C%nYg^^@`92WHBUtzHi=(yTF6WwRTOU17_59vQ$ht)UCK0t zRess1H=uc7a*JK5)`5Ih@H&%2wG|o@5UMmyQQs=53Ase!)A5$kBXmP5Vf+B`60cvp zE{J&e;WW&MF-0?JVN02aob3v-kf5OlCFDOpnerdDE73C(5GjRCuJo$L&=agBnqoL{ zKdfbG^%e$Tp-}ENB(Z`0-~vUYa?#f|!I77LEMVR0ixhe{kkjphBz3!#?Fu}V7jcx0 zW_Wh^@YtBWG}*ejXJis$0P+C9Ce+Qa-*m zhpXhoG&S*N8x#Vw4mQR3K+`D7;j~Jy$!>OB69bu~o=0HWdup|ItVQf!=&?+%nGS51 zhk>=1bN&sP(Elf437ymXnvhDo-ty;QHhA4W${-zgRac)qf@xIUEC|wL^9Qjj*hxDo zEa5x$mo(CAReVp%6v8tm=t_()*#iXvnk*m!9g>0DZr-J^30@cdS@0IqFMG3#ZiE|3JVqHWcCbtPqUsWDTR&aO#DR883 zQAb8J!Aj0N&;bq^SLR0YYT`SRpgS6x@>bkbYWNyRa4jgy8F|e&OHgGFp8G5 zZgtLf=yh8^v3gpj2ay@BV{wfX8{3?YDhIH#Y@%i1q+6Qh%ug`Ap`<7pBE-IUelsWo zBuD$$Nr|3PE&~z->9d>%AgL_*m89{ruYy{h?bRLn=GZ_%VdQ4TAMFuW$j3v&Y-;GO zMf=m0gX4k-hKI+B-_s~_`}4L|SKHHcLzmy(QNv1*W!v5ML1o+h{Xu0sv0zj>xE61^ zf3oRiq@{7Y?5c#g@BO7>XUDo54wZc!JSOGY9L?y*k|F(8F-1|uP9rw}VmLkxkgzqn zwZIgyh-@txCmW1#0q1&9u{r-#fH19*$h^c=@iGbkQRQbPVaf1;Jy(v9uk|s%QX&ke zRw<$-QO{J=K4L%8(1nw@q@}S<8$^HNl zKA;vMBO`ZEvs;XGIE{T1Y=1cZty613MM-G}n!lyydcCv?qnGtEBfkrjk1?cpEF&{U zFWcPhf$iyEzdnJ8Uw|a}02lN7hlhB4PC7xsRzPwYxM+WQXm?m{p~az=1>RN)%)qJ? zj$YnlZU6dcAxr)s2GV&Tx|b#{5@q#JDT6JvLRb5fw2wr<3F^yR!?r$(@CL7W z!)eydO?`78WMKO#q+&ugl%@jjwRLn#Ucb|BR*|5j)ye*T%f-esc(}lhCg}+o6N_J% zPL44{gglNAtWMGqlk)RyNq^;#=*Pf!ObOSwI{WXR=3YIi__G|<^r)m1^oYtG@OM#- zsOcgIQM+6QmzE5V5X2xSY#)*Gp67nRLRVr8wwiL8x)X9=2g($_dK+#FdW?@)wp@Yj!`0wwZLdqT1yS>`;^6_uv6v!&n*J|dfkb-r)M)2fn87u7!hG|4!&|JyeC#A^Tf7Csd34~vAxfUX zbZwn4Sd-JnG_4|Pp8p2oTPss6=vD*{|M0wI{e8~{$wK;WzP9FMFk7f%u1jhAGWnB@ zi0I-`TBVR|I5G?MiPIU!iU8||ku+P_+XpkNZ^%cNl?fwg7KWqVarXZf19blj1g8ED ziWOL8toS{EQe)=;s1JANTR6;ypXTfKxZCeWzcA`Cg@pPdq2FC+tvqcv9L?87w!X{C zNpqO}wRGZt!|yNr($dnRM8qGJn%R3>Q~7e2^TNx-gnIXQp4R@jbm9m0%DVdc*;!f9 z$c}F%dMLa5ihxG;d}37a+Ch^Tvli&lcq_#< zNOT0`zp?~dh7?J(o)5>*(G7nFmAA9$@V6O3JlsbJmX6f6^P-20)~~()9$K?&z1Fnn z!~ByRo~N^z4Sh?6GLmJ{!hf5))}_5O`LZ+EgE1(>{%mS>RD;O=+@NpI>f(3trF={3 ze=*nK?pr4*SXgY6yqtzRwB6Hnth|8BMv5mc-tEx-jKA%?-jgI5{rXZH`Cg1NQ$0L6 z_&1nOZl|PRTUzc^RaJd~g{*U@KR4#*uP6GK4)dYfZ7MDC(RS+3k?o0Tih!_X73j#mo`STxIvkf`US{6 z9uL=y$;bo*Kqqw9$YwRs$_OWy{k`W7-fFju-Ex~&#+s{pc3ANp&X?TsMf?BeZ8BgJLrYK3 z?{wh0B;IPCqLI+!v&({&Q7L0~nlr!edce-iJZWtYUqT%F#D$;BY&JrW< z2lVVS%9{xSUCYC@;RacEqlY5lImff>_mwS%G&K+`z7Q;b@JvX7GAHk(7icV?$En`% zP~MB6Mk^7YS<^ru$Us*?jscodK6jtz&QCsf+l}6ZEas&-d?(9=EpOmK@Jo6r{3yV{ zw~9iS?QV7L&n{2{!R^bd`K0%zdJlX&*y0~>T-)n{tk5xtxA;zqjvdvfC`<52gBvu* zP)Tr{J8IU!qP6hXJ%(S!<8e#vXHEnH_Wdw>|aD|l@ zeR}+;&VyT2u3dFt<4p*_poWLcwPo$b+c32T1!;l+=_uSd^Blf8e(%Xpz3|GV&yCN< zFVo&-e{f>Y{v7OOPfy}OT)foYybI7Vn45p$zF9u;ZwFvK_I^}@iku_LF)9MSeiR&y z2s|bDBQs$l2@TVLsUIbu@P%$%%zR$&t2NTJb?(#4vOCdr_BXBbK2pkqjA{349m}KE znJ=|BUd|!z2j$IbGXgT(%?KNQ5lE=ecG|noa923`$lp%x%f&L#3nZDspmP$#M{N>p zd$%$pwQS108jdq>_NkiM9R4{z)k_g9JG86?Qxgb(YDT#0U_8Fuj;Ea1{Dn!tP)(y1 zTtD+Z_fO`{`|@|@%`MIPz8MD_!;Yn;NFykCII$%#u}-bW{zYm~EyoIXx9sLLISdz% zb>HPU^?!~%O>>8e<*K}Q#&yO|zS}RWTqUSN;u!>l$JwUOG#}Z>(S$EmVoRs}?zV7b zlmO*{#QRd!YVgVP92uDe{=)NeLVE10Air6{fzgQ1ek6@vy-h0sf&i1v@A+;Ai$>|E zW;s4AHu)Qn&vGA(CUkpPJNC_UJHs-^_jnUS1O#A4{V~Vo;5WUXyvr z!7y~Ne=E!2{0;le0eOSNu!u#F!C3mB@b$|(j_*(MyD|e^_2zt;F9(W$v_%L5r>@nBcUix~^q0$(b(Ycoz4a%VU3_IYVsu z@tk>sPuV)-cr-0_P{C>FU%nT1lSM`l>qEMJ-yEP93>jpezfifWBDVD5Wc}O0@pz59 z4TEp-zI+8U^KbnwNL^_HOI?S7amSmRGy~>A;8?I~P8EF6)I6}y_TR^f?~I)c@U(y1 zqgfZ5gX-WmxG#I|WI421&sOC|&u%tVs`bhZr!lrW-<=aUw44nyw~JXY={G_w%+-1; z7o!rvU7oa?4Pr8Y6@RsHXHY7=rhb$28+_nD*GJ-a3;Bi3;drsuQf=AmVszJO<9vJY zq2uWWK(gl`9&G2&*Rl__nr$>We4gh8-FRZ$aIX*rfPU7dW+7UQYX%wC@z6!SK&yN>lED5!iW6nIT z`%_~=4~P5HWdI-Z+f0;JQ&R(AsuS1~*O(6rfnQMd6%25#FV7FkI850$l{fW>2%*y* zZisK`rfSUPwXy1o4Gy^C1uh-WhxrNrEHdH=c$@;D2Cx7(#uumrd`RsCT=z9VUeSg| z9~C+r8#!|IWB$XO^r`f7;ET5;E>Yk6=;u5Cn=WUXRm5@mFLbIkDbXWSHik?-i3xZ! ziU^*4hoKktY!{{UyY7h@(G|?TO?NQ|u{fT~hlLGWIq5EfV%uIQQp98rGm7bS_Fb!( zG7}6lS`+$g!>-*lvx=YeLx-O-LLC~Hb94^xaXxK!L!1xjl)p{0t#on1OqcyCfg_pd z!2P?YS6hGOEjpE@LoLqChTVBaApS9dga<*4w?=ixQTjreTLsliTV3RIwYm^5g-<0!Y@9{EuMglz-m5}GGpkC!VSo<58(fBTmS93iZ|FE z3Rs$NN7*&tLT77{!1juv{tf>T=8%&`$c%8APN)$fz3bxPb1yzUm{%OCY!+h&RG36puv1d zBs-gHFIgl4=FeD8`*$FFK=mz>(ak{iX8CLZh*qer%x6PpQgMX!z7N-YuKRqKeg&3e z-^Q0NS((De_KevYn=QwdFYH<1FtM=8G|RWE1{uz>Kk)_+LJTM%q@~cQmb#S8GY+BX zYd8%>MyVTAMh~>#80{IEZGV{gnt@~BQ-tUPE3{g~QQ=Md$mEqj)HQ<==%lku&5~+q z6u{Dm=((m}h_^#qmG{svH1hd_#kWef1E|p7_A`x$;bVv)|v|~DNwefF0Yi9^(Y!|T}XQ?8Lr>k#; zQGF?0Xf~6@iFH~@sJ^Ew%T?Gu7R!hc%N_VSfSw%q1AU}vFk0C-!Cq)1B0=qKx&nA0 za_J?00A7Abi~q~Ritxi>EhzIV?km0({xjg}fbWgR{2Y6xeInD+p!9D9EZ~%E<^)nY^J59`J5yaf~uIr@_7n^~D5V#nstKj!(RT>I% z#qU;c5RZ8Ki}?g~;|c$*-MMfi3vy_b0I60*$~k};uNbb_OodJ^x~aIslafJYZO(={ z33nW?MID?Z_P57O?TVe&y1Y_*W$p8Q`Uv2I6g)B+G^@;K^L{>r&7d-*(febg1Sa_BXXoss?#C-?O=1ONF%t+E_CAhLgW7X03(lir?%$ z3omaM(K|~IT-ml}UnCufa?UJ~;j}wr;mXzWjM!F;;WiTeep10>bbW$mW5UPsFMX`~ zP`F>8_?y-JJPcWd`m=lPe|N1QXV7JLoQ#%sa6HxT={__ptmd0@DR?x%`Z_*7KCL$W zBSX_)nAeN9*y70!R1?(Dyq@66Mta8p&x^-lg`NpVoRIcRqTTjMXLCSxJn6x}jM_m$ z0_GDOB8;C?u-JEQp2Pc~jEAgY3JUV;!)3el5%9h@0@Rs++kWb&PVzX5TUQU<`F3oM zK<`=%30aVWlF~KuZ+_SP7Wb27AoU;;^1*cuEwY)m0a!3lCSK0fTJ8-3l0qJ(y=Z z;nxvh;azLzH2=Wa0PV-+!3;@k@z{F6=D7fUC~i1t-@OiJS$_+2@Ul9+{kHJLdbPeU z&)m9c%;rH)1u^^P?5M@_VnB&(q*b@x2KaLWz{?ou$#8G>Ce!ARbbJ!gjTFL)czybE zdU_<9<#p)(Vg+AgL`^=W%C8XDY&@Y4*uD(MSy2TR%vUJ`hZ5IEHgHIVoHya2t359)!bPQebajt$7aPn&22&Ueid?>a+3MQSiV`*# zG?n_!9G}s;>Sx#Yq>=t$5&cjRtw@&-g4N>_nh;_hf{p)icP_pt$%k53j3H=j&ZLaY z;qBPt_(49Kp5b{$OCA4h6h>ZcE~z6&xfXL^KQf+Lxc}QKh9!ev)--@E<2RBy8)7KAJNZ`y*gSFu zbKnY!jw^o<2r3}1koY@!0v19HwNfa8y{Qtc7IRRcO@X40)ug9k#m^hyLV1$W&A1T{ zB=!0&j;cP3n*zWMc>MF&(Om0J>&>$FSuai&mz|u3*VDZ#)Fq%|fCu;toT_vo*Zs** zq+}`!{mc1+`r{K$;nUM@G_dr$0nrGcTc@--2E3ym5%5Z**=Mh%0E%p`-WKN*47r&W z=DW$9Lix1FNIc~_#YZCi`KS(}T5842yu^XjgtUQr?;GNRg?d~6RS2>@1}HvqU2;>$ z{izZF+lV9V1_C%d({T=-YTzlveyLe~3LM433lU50! zFSIkYa!QoaV`gf5u`Q>!$5s;WZW%_S)!tQjDJg-aG4h>H!`@Q}$o z#1`XVzTx|hcz%obS)8L!nYL5?uZuFQ96B+vQVzQ(PeF7`^T!a(Lj?;UyW2eHBUF%S zuCQBhOTc>%*D6htd6=FH5*Lb+KT_9WkQ{dJxYkVA$ov5r5NC>Xq0AYzc-XeqP00!T z>=LJi!!W6|dd(J-HLXQjG5j{I+)y`;Pu(vAygVZ2p35Uw6~kpRR5z82TaJ-Fe`b5J z{(Q)E`$we~M2389l=hbqw-M1j^~5U)#VPF&b4~K4S#`r}tM7hS$NYViA`f=#!z9$d zR-C(v0AMLUXOFf-@*d0CeA?=wRBW-@8G1Xd6l;Ay@VDsy?-&Ux6oH#9rUdX(Z4pUY zd?+j4x_p3iJ9Cx0Tf816=Zo!8FgA9ZfqLHNakdWl5?_1%Y?_&@Jl-&Nr5_e?dopNHZGBl_&(oX=0d|=2wzRz*B`)! zq4|(HEI&No&ww6bt*o*wsAU?|EfX5W%uAnmVwQ}8=`x}}w`rgd&`?(dIgf`+BwNAH zMJghQ%VHH%)0`0UI;T`i!z*tcLz10Nasx}=a@NuGj=xAdA3$q`yPDB`DH|0X{w;c1Sycq07;twgeVqo_P>xHciX zs@yoUHAUFqxEWn+TpX*Hwanf5+w?#%U2XluHh;vHr`QECmy8YiFlseReaGxU!t!4j z66-t`NgXud|mnN?jR5-??HrG1os6SDPxVHRT|$bxJEU<&n#CpDfE|! zAI}!9(AZ!YRdNUdGwiOpjd|3-kh8Sv-zSG*^fs*i-vbIwYMrjbZbU|%k`|je!!G`# zBUhi&qYFDM>BJB$nhWwCaKcF4we&3wZul0j8$5#!%)Ml1d&{falDDbl-#R2y;pAY* zQE=Pn-`E(I3-mup#XcZGO6lJO#WdO@HoesQ&9tU1Yz{ry9(Q;2>%VRCt!=YQaBLP^ zJgXT~rq`*rSD^(xi2s|w<$-q!Mc_^N`NNqAY%&i4(-~|UoujND*Q1%aKFzA2K79w% z7NB#j{Ibh(^&zkt|NM{d4+PXlHc*Ii86SsoIbyeDPz5__xxRy^N~a$$U=PyB05WCp zb#jR0V9x-R4E+WjTTJ)XpvoB1_DA+Qx(xp8q?pA(deMJJ5^P-CU$q(3lb{X+O)$4V z)_|y4(D#1shMN)(9q@hG8)35s7WmvH9FZ(eegyGI)F5B1UK_`ZV~ZEL7)}sS_F*1JXVFip0AXItUoA3`e$JlrDFaj zer>_r&F|^kjYa?Nu+$uzu1)N7zF+IqaiF6de)Kayf4h@0u+hf7&&evKi@Sh>zLp>? zJcd~Cek6l^o6}cX+Eea+IXO`XyoLG9+!BX=e>ZPEX1+2>@63inlb!4R`oz12p^h`( zJspDLMJv%!M}s3b##E!srK`B0cu?SDnju>K!LmjM&b3ZvVkgSe>0 ziW17jKE?_(*v2=7^6{NWVD_&Hw{5aYb;a7gt~FyqV?h&BKU5WjZ%05m=S@vdhyQv!Rg$cI-`P4~1}4A;-v_sf6~Ir^rEC8_ z3k`=_C8g8vAHs$QhWgV`4t6}xUST1jZ-vQ@U+T!%3j)(2z3~T3EzBC?paUqx=w(VBZQJ!p{v{qX z(QqU_r+dXYU+DFIId%p)5{I)xB0AYPJF}(s^~7*jisNPodZR9o=~;A##VRyf$7k*N zT+n!8L?LDm&c5Wu&z=l=gmp=Eb@2@ZD;xT9p?U}&>{Wez8xrqrXaZXBh z&m<591^MD~lqCb7(*{$J$KI0cv;u{IYn+c%l9z8tovq6ZH2f#iC=@9Hf%!g0-J-lb zOz60nU{jXcJYA+Wd|`Z9+$3t*Gjp0T_~jx!=3v_YMmRP*W(oMT{FUG33p zr%9mzo%^_FZ~r-qvxz72VHonfGr&L6N4Ud|l*`_N>M%5KQAuv_Sa-8wed@D$c*Xna z0(q4txvq~^ZHuu@pGg>MJJFJL+I*S_K`}|NZuh=9hS=~HZO#}$Vs3$Os?mP7tD15@ z_%~Y97^`5(1}c2EkncS9alrq3H0oGi>qq0<(7UGku6=77c9@R^6QJ7#jcZ1MYV$?Y z>Hq=!>$7(L0KWR$jrhBZotFcn7q9gmgb2my)m1o$7w8xCRHd(cYY-!w04Hh!LFA2K zxAKKC3*>l4y`^uv-!D5Q@teyT-yF@lX?r*(0RL1iBj4U_ttw;DyZa1UMo>Qh#L*6F zPClBjT7`m+RXk{k*xU}ayUsv+jaiGCMa<{&!*XnAtK4N5QZ=JmK~4_5a&I%i@PocC z|9U=va385RlY@W{^|OCa0|wDW~tf z3x^6+RO(D@OB4yU=?z{d2|Kx2E+S8`7I%z?Ia^zpIB|3Lw-7T9pLhldixF~u-a53L znZfPUL6`lhxu?;99XzAbbT+DQ>VW!Y`0Gh)3>^bCcTw)0rU zOpak=Ap=?PSU@G_*hN9xTl&on45JCo&d&5t6ohdHz)rmJ|Do=$|Ds;oE?`&z5u`hn z9#UdJx=UiD6@z9dMM?w(q)SR*5Ewy9N(=-H5a}EmL;*n>1f@%mdXCxq+Sk4B`+fg_ z=lN;>vOhTAGmcnm9qSyH6Q0_KJW&~5Cg-oI|KQ`ngjQvGd(e9{gD>`u@@T z!LRNQdTBxrg2q2lDNX)K!5#ptvYTcd$c6f(vU>Qy?|1FpU#W2RxO<&(+FEEA<)3`V zHhdW@MbVn;;oY=^T`+K8<=D+inzrmIsqTYoajy$Jbh$T)B9<7L3fzdJ)AJW_&DV~9 z0!bFxGkGpRqdl^y*XOiiZ=Sbo90FKk!s);g&Uwe=H*==_!lj?oscfiOmzvLbnuPLmsu zN4*&B0Agc#3>Y{AP_SDw!+by8SeKlxQ++qGqPv{|*1VzA|vr;_4)p0Lvxy;gIJ zlSK;R+}tu7@&jF#+36!5sa7qUF;wJ6gvhnKhan1w`b$qnrC;a0H2r{MIG393_rB{* zvkBLs-j(N;joTvFU$;8H-ct8{*hE5rMus0zA}T<(`T7~-`Rmaqx9ppvX&@*EKt_4E z0pn>xQwkVG1fmeSZj^zeJ76vOL_Z^1jYwEdQ?L?UPFM1OPk#!5O81!WVtGv&GU)uY zf@=m9c`7DWSV-uMN_?-n+^*8ypY)>>@M_z&&mPb;tqjBLP5UP;`#S!a7pDcj! zpy|(Ot!RErk29iaGjG4DaTXo<)&|mTY7!e-Qeyo#$sz^8km3-=b1E5Fe>K z*yx0(dlVOrl95}4RZ#CRbf&h&#YT?DF-so+Uf0G#(nV*e*bu2^;lKU!%jt9XPEh=* zd$45;pE!Fx?X8dM@lgs7ySARa@F4_LT(nX(J$c7eT#VidzV*?6)B zmIzn17QM{qARjNx^p23&go{gS_aQaIaO{5HC7qXV^&z7yC*z7s>f!m*Z7kmcj);ptQ+JBKuoVAF~$tH*>CRzFd z`H^a#)9+@Ixwm4HCxT~1m(|h1{7I@F>o;N!eFFo>nXB*w@+U#G6Ee`R{(r5wIAd>H z(^c)7WR|wJ4ptdA5$XR~Z74tv0qE9G5%7f32Gb$PJ=Xa~T=!zdv8Ol2>t^QCM&I6C z_8XczIxTcXfNFVff8zM4M`0DJl+ojZA1V_Met(C`^=O9U*oH~)8h3lQ)wxXRyEoO< z3GPSWa!7BpZ1e^l(Xz1t?K7U3NG)_3@hp$q?)-UQ22p9#m|d$C^GeN?FDWmtzA~E; zE$~OAu+`Na4BnZWu?%R9*0Mxo3*E_hosto7MsSs}l(d-4(SiI+6~NV~RxL-1W^J9M z6sjqj>(hd6qO%5LjK6H9nR^B+=IkD&tVq5LwL+0(t-f$t6YTO?$JCp+?G(ar4_)=U?f~ z7}|C}_)!zI|9<)QjdxWlkM@%!i!Ws4YR7#q_-!R>m2DLd)vgwYdD-!ba~ zgXeu~$U|%Ibu3UR)21TlLhE(I^TrTDjOL!P!|88-5hr8}=!m9`z4v5jEZsML8`RH+ zq0X{TQ~9Qo>P0Hp_o|$ZDvf2=vZ&{DWRSxo~{+yRPE6ApkN*OZu_JZ`+k1 zPM7W{Fch2@f}DopsbG)wZ>MFhS);vD8 zwQ~0h7TNFL87?L=5{SlKKX38D+U-M|9$IqO7P;b7-9z`hLhy}OhalZ&cTii6Ro#J( z;rj=7YtZ&j$u+ODyG_)dEwP!tmrhupY~8iQN4>Q=ToxuGC@7f7F7#N492hXiAi)+o zs91vC=Vyp2C58_hXcel(U8)CmT?PQYlN6&y@bRhD+i3RjO6jMGZhs+6usdsncm|X) z|3E7`yjaR@Y*_yNq5W~a3brA=f>%88)AL3et^%P(bUkEkudRjtHV$ZeE^@SB;J=%If&> zCvfEWV0)vW6GErhPr+Je?aFr zP*$Ea+Od^kUb3B-{DrNmruOut@Si$)tNJS91Y69z1;L?d+4?9$Ge+f3w%YDe!H&k za|C~zeb5&V!s__m6?*#T=G-bG5FxclWTt%98bQS0nkz9_~1@m?E@}>UV6cDQJ3Y%o#tydVHkwT z+MnXeowdn^y-lm7v9iyYM=I;3{M}<-#}DpjiCW}CU9uYlhEDKF7d15}eZ0IjN*+I? zQrVr>odx&F+}Y zP(4mi0TTLvxb-IW>9TctbK@&zf(3|kq73hz4X)+qj8}xJ6Q_{8{^3VAe=huAxHi6s zrXu9kY$6a^#gXuy_dAVU@5&Iu_iWs8>L(g10qWWQHFQJj7O^qTf8qg{Pq9ZvMnVhz z47jbUQ&!p%F+%c}L_Rg8poiesY=Vuy*;-Q6;(ieoz~ z2lMR<5bQ!1+zg-h-_WPDHZA`#m@{7!CNv~E_2=A(68ZnyH1foKp`B6W%UpQ;iwzpT zfIHXo0%z1!V#e6d&BiKdvutC-HDwWS{k)41rn_CiQN?jRlu2_nPgm zAM@Yw=@V7ybS_s*G@>`ge63&oypX`55(qmBAT2*XKgibWV1<5v_np8zQc}LaH8omV zxA*-c-KLmqrm->Zj4_}vMz7S2HkJ7l+ESKe>Sm+23tB%daZC66>$fb4T{yCNKFlK; zIb)ensYB+-jN!X^5f@FtcUnYf#KF#}^Q78^C*z}IbB{QaYm00zG*Rf^Ep6Da!b@1_ z2D;Dy+=DavzMoE)IEzg?%EW}W4o!X#Nsf>HF6ZTxS@b^k{uFSaR8aAiwgt8+5#yT3Q!we;c&L zD6;@)OixxE8Y2$~An+1SS%N>`XsWBL7oi@u)#sYydZuycKd+hB)`zk`d840eWGh$g z%=oUbqR-rMyG2>5g;O~!gJ z_O8)u3uosAKr~whj#?^COyNoESd(31-dWJ^y)v!1a#WP{QN=K8f3vdI)d$Mnx$cY) z9#f4iF%15oS?W93E)AMXtDsU@vk5ua8+~`1Y*fO1XCF^EaibjJIczUxdNbN`8U}{B z$L{&MV<_;?Y|*2vF^5wxrq_y%^I(V?i2e&Jf*tsMW&np)1-*AyH{&k3rq+z$F)2l(jN>$|vI8Jz~C^4#G%?YMW*VjoweF0R0%UC7pTOuz4t%j~F za1Ikx5^;*5?+wDZ+gX?$E7t)MKFr2*_*_+yn++UR&-D4_|fNrJ%UYH&=}2 zSnowoaydiv~7>CZ$=XQ}?dk{6p6CFBa%2CF?8k1uP&mkYFcrwG(Pz*#%m=oCA!0vrGgI>Gcz z>E7DpR8y3gb?w37?};WW*-o+4D_Mj13kDVZ0?`wQX_}gvs$4dLFaXGL;ieh9ZUQKm zACg5^Q(N2aYq!9P4jc8Es6Gw&M>YV_PGFS#P zPeH4LDyZ*_74&BE^?VY|uw70QfzqzGo8!Jq)*T()O6g0cs{Qk(KhCk$sxn4S^9}z{ z3FcPUH9Q7`zgOid$YwMVHJ)^DX>053JPam^68PM0ON4I&$^^7dcpS5QJ5{A`f3}k9 zQe*xr#pew`j<2JU0FXvHzP*vDrDbMWN46;zfJ4i4)-MmS`Dls|qiJy+0 zeaQxC$FpeL6iJ2&x!GvNX`C54epRZSqUsXwBPP z;(juW%jkPcGqaSZ;fayq9%l$sdKFE*2L%)`>wDf(vF*$tk11c32Sxa{ z4L-i5<`m>fwQyWJoke0Is0pr=m|Zit{OUSIAT3AsiPpG>C8kB99rN8c>ZSTLwc;b{ zNw{1ll;hNm>>gRA927prrOO%*>FcFAKE(UIXq}&?~*x9eVx! z{q51zpw-@%_cmMXO`)enE3-9kkiK%_c)lyIT8ue7t5~_KWgM4WJ3debBv?Qn$V?0UWn> zM&Keqe9!@Xtve1Tr9;SeebOsI75c6!d*r92q`*7GUOIaoys+O#bJ_=WhsvABDZ<9h zxrR|!^<)1&FItQ|z7kj{Mf7s&0-IW8Cj9m}tb@)kwWQVG91r~Q^iqZlP^#H+33*6v z5AyU@Fzab-Y-BG2>3bC%!3wv;Nuw>mSCj*G#XGt)WS|V35NEMB40-tQA%GTPxo4qN zfc{kY%FE)*FW#dshT~A#$~|^UEg9;jj1!|%-PNR#&HdlsT6g3alMs6BRV54JNh`Oe3 z`)im&M<0#|AsYF;`ZqHY-F~O{F*Ar4>qElgYRyZ>FWel|giusoA!zN#5GB4~bm`BP z0YDtW-VReFf>*A11Yka*8id&(40c!?a7ZVFK3#(cg-6F>7K;I;&4an2!b{X@dc~*r z)`xH}$gdGAu<~<#Ce}4XU_9pcUs4u(S;O?MYh=)h}$#Sbk$lx!d*fT1AdbB4%yP z!xp)bMP8TRPh#xp^sb(3Oi&de8L+#Sm}o>xG?9n_-VSRzI1cv{PBKe;P)!WU=L>Rj z_rawx5hZ|^D_-iQIxFuA4I0$C7g~J~gxxl8mh|GV_Aq`Ty<=4X0cRQ2x=H3JegnZJ zrTd>iALAO4*@cGc^!<$wE2}|kAz_JVBjtmIXW)cxT>0!{Jv11iUQK9lJ_int$A*H6 zLl(-3sK;25;Z{fg*|1L;BF)u+0`BXUg=3ECpE2KY8Or^6Rt+A&MYzjc{=hX&^BJt zz~aF+eSc%C;o-3c%V1~EzdTlDYL&6hcVqvfRdN;0vHQk=O4LpT1msAXhSH^kJ*Iyp zqggZp!yu(S>&_80_Q5*n;@uFk!H6|8D+dYHnZ2woDAjW0sUyK3GaAuCk;?)q!n*+- zEHUcdx3Yxkmf*<>ok3wt$aPue5s@U%V0=^@2R`5H6TfMmCbjnq$L{N`U3FG1qH%-3 z$T5mqkW>H+DWFv6y*SX`-VTEA+>0(U?Quj_s8fdRyQA$x}a5a0s%hd18F!Dx=e6T-vh+C`N4B%X$0c!rKj@m)FaNMY7tYjviboC zfmeJkkNQF<25_4)5ZL z`gh721{{?zfPcrAQi%p_eW-h|HWihHKM{vBze-h(r^%wmMN>dW-tLqg1cF2JC_*8j zs%tL`_$)odS;8QndUPN+hzUyJcEJ(pk>80FaX`KyBd~s`c8Y~G^qM%AI^eez3CGcK zk}R?s0RaKt-f!8*?;=b=U7xpeij48x=Ef300xgExBEjf}UHaBnSFn!QU>ye0O-rlrtU@4c_1gqfjd>&% z!YhK8mwK-|Qx3$)FLjc*ouP*dKTg$RrMb78rHsH-dERX8uW&MKv>=v1BFpt23!OSc z?>tgopjlHDk896K5irgJ;ox9`BlrsYX4yJ^V8NGHwTWB^jRhMQ!r;gJu~-yHG1yT} zqSqSG)V)DLmRfv6kn;1%C=rB0X2pq_nQ@M=wXim`iHYXQBfj9qL}2a8Db9XolK)K# z)P`Pg@G6Y(unBM&_QWnBAEQH_;s#%s_XhCJfT^pAF=>IHI~B9A?lh3E3tu)P;`c{fK%jkC!S9P@@-KrykhKJ30Nu;H zD}_z&x9J_T30_i)y!8F!U0ZtkXo}RnL4dt-fB1sRF5NT6EuTYtVZ5gLMXgjLM$stN z?4ruPFYPx;`&M!mdKR(zW{hV8r@TCX9x(!hi`igQRKMSLN7>^&01wktHtBk4qUX0e zT+#UpQY;E*76%H*I-tm%$=?z$sw^}T0`|D1od{unaE*VPYDFc{_ImeJt8?gwD|O|v&N4(Nu=T2N0(D-RrBQS$&^Ci z!?IAVuTLhjG%8r5T8#^9ex8s3CyYihZn-Px_3yH!7_PNlBMen(CokfCpP}F@N|9pP z7YxwHz8#Ww@4f?)z?YIKoOam$qQ8ZxUx@RP#1>TD@hSwv=8&!nhzKruYN&pK!MDqe z*1vY&H@!|RI%TFd4yEk%HtBmiv`Qx?Fp;su9*n&;-#)+4#Pyx8{*k=%4IL8^Gwe_9 zrfuQ&)Q8YtK0fhj^w?~{9bW2Q5rjQ)S~v&)*)ZGn^b-ce=gdih7t$&P~-+1i%>&uH(4{a?z-@opK z6}D@-<#o_!M@TW6I(RhZ&OFM(VyvQ9xf(PPTg|9pYL}$NXITLO9lJ^#hCfZfSlzB#7lX)M1(l3i?!op` z3&aveeKt`&S{6v2@xn`N*Ux7*5LH8ndoa&3q;f^yT$Q}I$0}M$^oJ39YrW+`9i?D) zWvY}Veqx9uPIGN5E=6?;fJ&Jj!*uanm<`G+a)HA3F~R3EdO1?14KK_z#U2Y?jwyMr z!`dUL7{1#OBpVwq)du(BF5r_34xG-802iW@GHmGe`TIgp^NU^CNd<+_v>#%!bmL9xL8`BQ?nIF>LxQ)(AX2v!OO zm{+dQ+9t8C5Mex-D`QDX@CcI2&}*geW;MwrJ0~Q^;j()|g%uw)Vsl$&0(iF1|EL~x znG~_)AxL(@ZV)p@1SY-@yLv`4P?rqDrHLtO0kRcvO_`>E14%4Ejpv}s)zjd4lvhAX z^qI(3Gcm>Sxmy#FhnG%VXRgP&eZhU}2|4dsFZP%+qOF~`Gbu`G%})yhQZgIsFJ~_I z*%G6;tn_oZL(kRJdM->Z3UO8&toFEDV+$ZHEmIRyQ%S`(q8HBet70d0p3Cbp?sGYvuO6MG zC(cU?OpF{})}o4&4B2{AR@KL*s6cm&6Wq{4yMG|E6A5{a8-`VfgVb*Qb?!bFj?Y&T zKnTK-dQ?Y|fE=Hge>>OCd=~kf(UTuaEEh@DakBYx-Z|a`t*^6i~)jga(#-@DVivr~L5B%EWU_V?uz_9W5m)Qc1$H8t~DD8O@< zf1}~G>94xJ5=6sy(mfFxK?Ct7tWReqbhR0&JXN)^#yLUxHC=Cke!cqDjc8b9KI<~) zVNO9$AR-r-6V-}W-@eX5Waw-ywTIzYsZTrs(jb>ljI?PFo>eO5-?M(D z10U~ZfbaFjufC$oPn~AY%ut zRQ&)km%GdN`g9RAuQ)Bm)A#q*?e0IYrZlbLpSkxOAt?CpV{>->)IFIKI*C8-9iGTZ z(-|^H;kYyn;z$`uS(Z~unWj#W4MmK6RdnjMRE(xn-At`^s-)iZah*pUr*EeTfmD_~9qAA=HnTC4Z@)G7fZ3(Gz^m!_Wv9+DGn?)E z1VLUsQ?Xj?;`ujh%yDco33dz+-Y<`lA~0@vT41hYnN6^k_Z48oc9e&bSQwz`or(*3 z7|mP-N+WeCb^Mq?il8aJWQOBPuDHNEbg)Op-k~5yO=!OLgHnc67^bn7#M?!lUw+{O zBlvsHkBwp#>d^zd*cP<9#*O8PI+X_#&1`aBgWxapYw)@LA1fzhA~og1K=OAal$2KQ zZa$`F2(&#bLchR84!Z;jboK)@L{f{hvk}FpEX9#GOfWA+AdyM{8RQ0x>^&EL#hK58 zz<4CKCmUrrQ`LOB6cV}S1~oYJe;c1Z+dUGLBPS(I>bsVwU0ooNYMKm*RN6_`s1quu zIrkr$^?(bjY8Y#l?Nnm=*wfZ7O3fAoklvUx-1qX0fY+tUHg;l5+us2R`MK~Crv0%6 z3?n9}ygf}~ca7M<%A`o@=TG=5zh0~4NPVV$c>>?60-mG&pO^mxz+~_ny+v*>Tf~Q> z1<_DNi)7YZ=_n6puyq(8cc>IaAxO+vO#47n%nhq>0* zVP;!|X=UxRR(=6Wv=_|m2w_}{#pbxZTWN7X_0PpjCIj_eaSHSq<8Od-*of`;m4%%2 z(j(_Q&!?B7s^OAn>n&vdI<5fPg!~wV2K3cN#*s-;1m|Cy{mZ@9lbSpVeHN2@6X-J- zHvIvJfoAiyx6TrInTwyD04|e!rRFrL7La;IIhswJqOlDhyIx)Ic1yfgjyJ|;lQGse zGQt5MIAAGoM+k${k%NYbcU1`h=$Mzpp3*3d=?!m1k{@K6Kf;$hBBA9hFS+qeBr?nZ zU`{R3=BGADN;P_cR)2pNN>ACDi_u~j42JJ3J=dT7 zG@|ft0BATUC;~kIe-2)Zg$W6N*FFqhGXt+SMUgyQhu^d0Suzyo!xe3aLgiDFQ?knn zd@!0MUit-HT&jv!6C+rh0M4fEk_peU8F+2oirPv0}AIa+XG}4w%B(URwOa9F}5Z$h=kBrX4S*zqv@nYTyTzICCO(LtGv@VEu}A+gMz3kD7A}C~cf`rp}Y> zB-4mLXIJk0uF|FGuRzyw{rbSEDjBaK+xySj)e>_!cI?Cf!uaWOT;$HauyPb0b`k{x z&k|m}%ap2rV?LPmHgxULdLK6o5ok@n~<@m5Y}%Co@a#SH+ycPb*?zfy(>e8iU8#E_kURsQ!_FmKKKgU z2kAZ}AcKjfyNh9eQMb^dRQN1kr?uibMj}Xs!`N2r2tx5=AIQVSaw_G6weP>j>Gsy1 zJvvadY!!@>Jc=lmfnif)goXOic~&}!(Qax2Q@T*Pl+KAknv_WOdkmOPx?!|>HbtBfNjFN@dg8?Kmae9nS;u#_kD)r2ZZpyK9MOx$ z+S&<8`&?PwT>DESchc|Ksd6O>E6NbH^2SX@X16}^s&X}ZgYOtmU)nen=$m}zR4(dQD`BBwK^Crf=1RUNXa|H|x4Q73j__HAwU~f(sh45f2vY&`>u;JqlJ( zlZ-3-o;BYm;LjiZf_Lfm2eQkUA#oPN?2s=PK7?qKBenj;NhNV1?##4OG&-Dq!=e)S z>Fy-4;}v3={7ltJP$N9{4v5%mdZe5jG&EuQhAI=6zc1Xiq7uVT=lLznK>a6#CcqtJ zZhg%hHn+2DyyEY%bRlv3Nx$fh#h^~g7=+e9rDLH-#81>vh6Lqmt$2x8VN=`yyW8;b z?4$Hicw{w&51lRPWMDFIec;8FSKRTD=b|67xR0AjsG9?yo>W;W>+;0uj==4P&{J75 z!r~Yage{W_TuD0)P9ipv-~jYXaHh}W<&v(I&wa69!>Jf9cENo-^a{qun^T>%5j~p~ zS7kq6$v=aoX%Id}wcc`f%KJCZq=9M`esk^9y|TNL6eb3ocwtUQ9FwCwNu&leEwjyO zHXO1Ttb%VAh$__66~OEeKeCceE6?%w$O>tWZu>1Nn5|Bdt%SYSd`){_L46GzmYbU| zr`SkELmnxMszYo=8B;qcSfz6IAUIotiKKZU_58X=awb>mqT(gFwU2;}b_#Qghewbx zbqJ2}yve$7OWNfgfg>(se|m}F!`P*I)Tf#H+pepIiAfDMOZU5zqL5? zhktbOs{fDlaY@qZU6+?!gjUy12G~3!d;O>c);tK1w~Gnv4Xx(<^(anv`W}y&b74Bz zN+AbU{AI~!IU9pq#nqe5xk&hrE;lZPTBteb`frcia>ox&OI{Y|!fI_br3kJIEZ)99 zB1rvjswTk>x!feb8+5s~2d#6wJo9LIV~@!?@%!uhziWQS)o>s*UjN8modbCUhza~) z5FON>U<4CZ)86)sRWOrb{5vAL8PFF~#R2Acj&W3g(ZCxU%CAj*9h`PYTfTuTx2yQv7CTXp$U zr1_-Pb7uE;RToZEP7*&hp;`Z6i`=E=$PTVyZnt+`DBE(STue`2m(q-j5W$X%;}=k* z<&Q0rml;v5($F9Wr? zY{a_Wgns>L-|g@Z1$$3%@vOoBS>%>jl@BhPj;Fid=rc-SEvtR~9~fQK;$!+ZMF@hk z6<&}Aat_o51^ws$1m(BjEI6m-cPk(sOr4@GFPz-+}`HWSo3p z5+Rn{q{slT@RyIiSl9`4S%#F$&*JM^eEO$Ejin2xztjGsKUm=v>6j*z!{9ifyxN5n z$3DhGHwT}=PD}f<*i4J>#Xk~+m@&fG@?F&g2c!-laS-l_lLa?`TwDd-kNwN@;<1xJ zhyO)?bN{Z-6H!jYU{Pguyc{Kveu71H zbR2M!LL*R4!gepD^_d++^J5mP?dsdCgEj_|3Me1^nf;cw>R!FJQF(r*uJY(qT|&iw zH5R&8Q(8`YAu%*ApeM<2uX!rSaUv&CKTXW(AQ#z${!4`t9UUJJrsyXZVHiNer6Wb~ z*BhpgSMmE;oh$X1xedNN-U-pV7Qp#Kk|iIoU12&p$z7NE zUghHeAl{%v^QOWXbvVM@`tBO$#9X}01Wao=IX>{XmfjUjLqo^k+GsfISq`)syb1S+T~3eI z*x3GJJnQ4c#NbPi8YMFP*q$o*zJ?J};8ppWK5bVGdL;q zTD|M25k10^E6y(M|ES%Y8U;(w<$Ha#IZZIP;zoLC3~6ny>pAAeRI@8JAuRy7irfejX6b0bvDrd;B@2>*T=k`>c*XyT8du z`S(fHY}P3UTmA-t%PV(v!Q-N&<%_)E-tdj=Pv`xjDIW5qB_yxxnDp+QW(xfM+4sM{ zLFRvcL!{Iv2M~Yt(dtA$#ldys1T+~>b9}t|wRFM;oEe?veU>yy;pCE%zLq(fl4Jjd z1s%x)xd^@;=nhi!E_+4hKgPkQdT)O1#-HC#Hfw`nX;P&QYxnPX1)BaNk^P^o=9zyc zUr?#+{Rw*fPp)vo-#Gyc&d1KJM|Mj{2trB~=AXOW@-!SyjVc!Po(@zrftvrY?|;QO za7A(D2kp_pe}$b@rx_jAVJh=~>8qyx(N~G%Z^=JerHG6F(JD3l{qO&+ykb1}ALSK! z6NE;XGSbrGlWe(u@1Lkm4xtr>UH;Z&{eS2WW2+JPa{T@68+v*jP=Og{DY9^6Pl~Sz z0Rj8H!f6$hPk`?&$<7H5+vx6v!X<*}sUT3C--O~b*9AGpPU&%_2KJ%ddBy+aR+h-W zcBbol65NVLE0M^lRxp`4D{aNcgCbVV%zI|f?kH5H_g~qSr18uDyXIA71Ay#zYN4+8KxIyk-g7}x|NqaQ zglX$x5MM!66&?{GXRy6ALRahgm4cQ%CJ>N%03x)j0HOk_f(>E6Bq%N+Q3gIpc47eQ z+uELOzXxNn;o;$5UyZUW_;k^igAk3m2lN^7@W5~*a3{L(63`c`1dT_N!w{$h7!Sd; z2=1c^WdYuV8E7e>Y6?Wlq(ZwP;tSlIZXSlH|IN^o8D^-aj1;PCfi(xX9!w7;7vXZ7 z2ufoREfJCL%QGB;a+kMMH131vQ!Dfb-zdX?;#eL1@aPEao80BRF7j?ToZ>G+oH(GTS51y=KgwFkVpg;qUz zr}d7M(*Ms{##VEJ^AxA(Sh)ikO^M~is~f*(+8*f-3Iy}QIt*_&SFSN~LBH4BoW~@) z@&QbfdaBCc8NF%yW0ZDf%y1o)h)|NO6;M%eM4L#RkY)f_Cu9|#O#+M7nF~8wl3ugL zKr-K5{uZzKkX9|P)cBbrdNv(=fLQgDfbiGS)`nYlcV)>AsSVaK)HF1AV4HIygiaPi0-9U@_r9)#QYX{?@<*~XT5REP3P8Y#QH3?!u(NB8 z4Fs8$0N4?F!ftSJGPsA|hOOp=Vj2(r`!AqYtd0edB6qhYi5Bk)8* zRg}{14`a9aFpuw?-W7b35d5(w_d-IB4o`!w<*_E{tBmNQV-{=?>;^t~opGL&x{J?W zTq{8DfYK-Sqwm!P~?h)qIFOo`cZFEEtSslTI%zgfJ6 z22WYfp0#&(l}-~ho%UTCR{K$p3JnX(m1ta_6o+FCmSmORWszQ8$$a|ZO-0MD;1oAe#tYZrsl~80^bLt-!ra*O6Z2KoFsCQkksLYxhK$zl3>7;P?QAzK z^b!7)-aRr@x@loOR9)itA-J@NB&!GDzShFi)Nakk8K1U#bLCE5NUoO0t6#WLW`(!F zGE-w!@M|OHB=sG-`=g$79SjJDrG%&T$d9M{VZCN&(K{~O;;b#JV3>jX;`DymwH=KX zfdzIrD_l+#Q4!Itm)4|4VO5DA&!O!_=CxQ3! zx5q-`4}M!72arm>Ms&44;;{a7Zyhc)=W9)<>iSyLxm!--hb!rc~O#e0b@ath{>)K@jv{L7W$frcz>5W^Ks5O z9IDZpP`^|OX^L@@}EqFQ_c^LtvWfTn$ zx8ekbtDHj;apwJ3Ajz*VlA{=#8_+$(?+I8!pnd9zE z+V`%LasgaiuSflSV{y#zcG#2^`I26$2rMusP-LB@9SC`nzGu>Up+6<5%q2TC0~K=oxmx9q zJSl1<l#FLX%&9AYzh+h@OgN_` zB&HP}MTNeU=ANV`2Ua%G62d&T!X5Zo`!{+dor0T-;x<+%Wg59s8&zfL3pKe0wX}v! zjqRpOAZgNkDh$I-rW4Jfiv+eb2c9FboI@WvBWXW_xVJX&kQk`6m^k*&fP@Nk2cMjp z&v4Wht0KpQM8YenwlFaR#MAs!%#zsFWq?Ikyia4Mh5|3@yWJsOdZ1IPF5SgtSI5uu z5CUC$aw)irJ{CY$ZEN^+cdXpcmGYrbH}*0_h=_=Qx{$~b(zk3=v?QrZ#P{JBSIG>C zCs~xti;Zl7C0_Daz}CCEe|_jrWbqzYXg)I#V!dmY2Y=GMH|0o+dNoV_ZV5c(n<^Ab!@<$p;t!Mt zNae4WsDyrbcvg|k3K3#G@9P_aBpI7Rom4>Fww){ni#}^9iXQ{FfL*h*n+78XEzGt5 z*^=VoG2;-!My@I1#MF|YgPT4*)VHQ^Cjzv3;qk4dlN%&a1s|CpW)bdHaAXt|Y(SM< zMGfqiETr70c)h(!(01>09brroj=l0h>&XwFJf;Xjj-Wmh`NAP#Q-9*g37xAYOCcx3 zHmhq@S%_*y9oXRolN>JcTV7sX1$vJ~ZZm3NQ6FuM896}CmgiM;3RwZRaqPPG|NM}V z9rx@buF*T3)oDnq1qq9{yquGY);!rrHZB;fOR##NbYIBCsRa*Db(lC%5#7U1 zY@h1jT)Qh6CeHL7qBtCX7nh22*S?3yG5=HT3t|5XQo9eclnh~JNrY$^&QHww4x#^VbLEmx-+& zy1Sagiw7|34`m8HEv?u3w3b1^qG8rs{OX(V#M`yqo~W&HaMFMehn?V`@N7)x3?An! zz56Zxr6Y3w@d)@Xve~aeQ#<`hOlAT905c$`11gpAoA4JlKb;LhaC1+$C-H0$JoHv~ zb}n9Y>Rfq`$wH|l=G&BIU(x&{y9~s!l zDYdXn_){*;x$rHXwb>!lwDEg30|%fd)72)36FXWsa&_mT~>8Lst#jf-;CS3 z{th3X`Ie-X_M-P>=_|VEC`u#bTxZcw3FY?PF685cqtuo{H zoXQMTB_28;Xs%uT`^4g{E;HegCS-c7K*8{-pFv9COCG$-KfF zFFyx1T*W`wL+%XUe*W?a5|2i*r6HQu-G>FAc4pqml@IFR$_K@w#1g_SIE>#yz z`kF)swePDi->lEq9lV_@F`e|LH-@p`}N(N@+J@BGEUwZ-_OL!EX z0EBa`&`s**An0f8GimizLp3tNvFoWr$~H>73Hb1E*hvaPf%U+U^fy^9`< zlUMIWd@2Y&3_V3g5-jrS^nvDGT0N8JP9$KRZ5ANT6iwQ=V6|^1Rgre>wsw?tN^oUI zzg%IBYFxMGTzR>nS=-B0kzs)IM`n>vwXLjso%{8fqxD;}CK-g!g{#~IpSlRItK@3& zGqB&!Y-<7}2b-fdw7|rrhJ}z5;wU<))MQ*F%`ai5@3vQ#WAmk34v~ z4KvYmDTn^f>i%8vPayYI43+=Rkui3JN7f3a$nQQRZqK^Z)z%t0elEGZ3^(z8{UUF>P8Ek+_|8j2cA)8dV9}f>tixPp+H0c(ot>2_kb8r~`Mydj(Eu#cjsuO8& zFzo+;B<laeql($sH z%%4L_Yj#+bKREZRZ@rCR>=(T#hxBJTwFDf9Amy5{IbG4xSpzPVeF`X1-W@Z10vZe1 zyLUnDl_wit75j$^&3DM-YJ%EDyoP6rny0r^p-xy-iVU{3vv5v(YWSzh>_G$CQ&GKD zJtV7rSQ(vVJ_eL%zxbDK3%fpW>qPrC!7)I&`yW%WN=5G=-7gh%p%(8e(om2bAPqkg z%*hcRlILw@)L1%h7(J_c*i5ZDQ#IQ^dUoeJk47ZlRY;+WhI%%yY#N_AZBrMR>tM~A zlii-1XgooD!p3*W`YfFoFf?SDAN+SNI^ z+r-*EyM#iab5C#hUQk!vkEaQ7y}Lv~E6`3RonUy1I<($4pSq&JSfoF)EaiH!H#Der zHsZIwifrxdE0#M|@ZUc)CmH@Bpm(IRBy1smuW$gi9r$w6I3`pmls&ydD%9Q@3= zw<0(7K+Q3!Y5db270~>H$QD5i`>x9R>zB#)nbOkj&Igti7R<7*Wj_;UnGV(`wNPTm zcSu(mHsUY%_YwtS3B68Ls`is6uq-%HpEYMp#A(#A_?)+S--Ht1$!y(W?Vjdj3lX50 z-6`B-e{Zhy!6+$v%7gO~omF9sIV}=2svYaD2}94@<63mvntH1k|4)o=?^!1G8OhJ* zC50zTZtH7yrrJ=6kfV?7eI**oT#FseZL;k@*poqQAdg6IBj=Tp@O95;yyF}-_M>4q z+}9*xXn8CL4)Gx0)c-@;TZdJ>b?yELNQrcpbV+xEAia>5kWd;$q@_bax5%S*GnVeX-}l+?IoB`FpU-o-7c1s>&N0Wh@6V0e2$p3Vw({N)M!G&( zG5`$G$ZEKIs*4NtZx_dARD2dx!I5gi=8M=0*1NlY`3phsvyXe|=-*vlwT=@ZIor2B z3^`&Fg^ZaJu}RMm+2=_+Zd?ql+L{k6j)GZa)9{Y%vyK+oyF*2vlL%xKg0w(tLS?kz z`!OEnviEV|QJOkRzy?l&WrHPZCV_ZmI_^Q;J3=#!x?)rQAAt@0N8JUgI_ymen zs|DJ}z4c+f*|_p8|HeC5Tb-0X2@diWtd5=`euK%UJ!cOc%}YWrIq0$CZjrL1Y_{pK zJ#{4aZCM%2xR$Uo=ds|&(8R8`_PqXJIufo+^j1Q}?86Tin=FM(cPc~FWyeetRx+H! zg$B!Ib$4%ikKNE+brNFMuq4D<@x{2(lNp4TN!LVi>C{Qiv-*dbw>$JIUF<@!r*lbl z1lF8O!-CKTWb*{uC&*tA_eDDwIFazgVNWjKVd(3P@4#?*GkWcCufT|r{X+DqV{8+@ zLZI(9`5fF}(^69xy&iPKmR8X#Gj*Y|%6`xW^l=9p-B*kIYp>G9+H{>%-9x=@OwKO* znB8=>+R#^nPBT>cUQ*1KT20WfWnfzFRv@42xroQXK4qAC-l4zEtK#{CAP$ifdU)@tcbUQIqrqA!(KiaE-np4}I#b~>!rMc<$Ja~cHA%Y9uZP%XzP@$THJY38 z)_8hzI)v`3@#GiIKIw_972^o1+0R#Wr=l-?UZ$+@m3z~yacPKsbMe4K zk$ex2>T8A58^+jc(KNyZuV-D5zhu*L?`mLXy)M1vYmVy_kzOn|5Uyk+$w0#QA!%0N zdE8e<`~t6buv+v862(yIUJRlQ87uc(bH$j(7Vf6weQI#Oc*45{J*LcP^l?s;Lb_as z1xR<{NNYmK+3J+F;p|=5a%*kUj=Z8iIntN#!sO4UcS;#nH89p-lhRr*6s`uvfLeQ)IlQGFC-4M5i)`=l>0?%F# z+2~y~ubUgtlYs|OAXIGK>((&80($>r=n>#ZPo~^aw0xod>DvVgnVWQZG~V==NL(pu z?H=UWwhjh2{quuKsS|igtk|#Tzd|1{ZD2*?>yc{0tU5WyrTM%+6IeXo$vI0p|D3Fb z1~#ssbbrmfCf$3XPY-RpUi|zndLUD}cD!8>Q2%z1S9Q11M90TDljy}=sZtM>H^nL6 z4m}iKTrDr?sN@w8spt>oz1dh=*1MbR?xFOw_+W*Y_AY6SQ2DQQYO1r^_hzNZM;H@W$-WXV;(o;G)IV(t+}hrtgJ-IWw_jC zb)IljWw-BS9cv6*R|Zf_Bhm_N+Xuwihv_<9B)@-c(EJ5E(D|=*5wL4@!l3f)%-H&T zi;fkWpw}EBVF7Xd={t-!?PmlrS2{CRf8NKW*R$fEJ01~eCl(PInTgIFYOI!=tl7t; zo6eCS1DWs^_R8$+EcBmJ$rW>S%0Ey?|G12%%x$5%vvTN(VOVYx-OAE+gJ=0bBqwd} z47dN*`3$ru-J&!U2877$AN3%f(LX4}l#vd+VoAT()-a!!m^pG)G3`00%i@CO*OiNV z`8BAU=x9A$$>yHDSLunHhNLOCOI~`>b!l3j29B^7LcUDA=$s+H)H=;k8d6hfbN;f6 zVlu&tyj_#b{>A3aqr?LID>8^d#Oj~jlN{9~>jd|un|mO6BwO>|TWyJMc+ET-;@DpP zK2o0$&vvp&FV`O8X@yB*vyMo8`QFiMq629epEoPNbKw4-x1VMp&hpI`byiwy^c{=d zoF0!#DEXV}`W%Nr>Wy@%hgNt%Q9;Oj`9*zOH%_9l_Zy<>cbyLU+Khb|KRxB$^W5&f z7#q!dynHt$+SFgY;PfLR#<;}3St`xhqXW}p2V)} zcf_+ahlN+WVJQ$c!#FNDG}LvZ>i*bwe-S6v^4ra*otj!&s-ZFj&7m+T*Ok1E1;M88 zz<}MO@v81PA7Y&m@}h{OwbD6^C%UNqogXHNbEc`eH+4t=Cm?yc3~vYrG(|c zOS5BB?vlMw8{?L^z&571SH-iiU;&mpkI>$P0ZJP)rC_T1Cy%!>qE2hc@TJ)h1$?|6LiPi}H?ji^@*m$4MEJ7C|m_IY9Y#h-Sw)`Fo!~UHu9}+nqVC9{k z-)N$BxG(&z(VWcJ#dnFAKX)%0@0TIdPr<`0t3T<_3ll%N{3<8E+8#>!OJ}Ck@=LD2 zA=ybEss4Txr%}T&vErqzWGC7r{>XN zrjy>Yf+j1NY4Lk*+#Y~~j)@+L+x;=wtMcAjpk;^kM!KDW2e{8cYJ^nY{#=xHSg}R3 z6`-`=1>e89*Ie@A;v(!G^w(u!e2Yg-h=mc%#$kWo&h9FnbB5ZgjH?=JVE%!)b&5%^ z)v)R8&ksA>s{-#aj~ASW4~NgSiVRCzZn#*zvUm*IF@A5KdYhj}Q*i-x#)@r*V{7F~ zCeeF^h8x74=Ec&M7qPpc!SvGBgw!)E@t2`WA?>;WA0y_E^Ylm36I;X+;&~0pDtx`PP-W2jtfcjXIk9+gya^&Qe zK>)EbY7JYHvF(0D1-jK>~>*F^jBKSe6EH_o<(Rr6UM3c!-JkwzI#v^Zw6{@h>==Vi8!>A zaz3nlMjtrrk^5*%l$s0K$#_0D=vUAc*;eco-P!G$Ie*Q!bv|w7?rPGTZVk#2 zGuNqq%o3Ji=XJ==qg)QAaT(+&TgRKV1 z2ZqV4$FHwO0#x?j3WVLl{79IYnX{UoR3fb(b}*I$jz9NPxEIee=F?2e?hp+cyffwo z!R=G%l9*LHG4R(?M8=V;_v%n(OHmb{QSb!yt-JuoxPJ|v8YaX>j6PZCipR(eH%vkBWtrEh} z_MV{2kY(^$Uc3Gc+^X6wlujsp9D}_tSzeYsywm_+HG(z4PtKYr+sdN+=JPlA&XTFA zEEY@!eC9a$2q{8lWM9bbk2VsiPr0aHu=JVL7*l+3e*DPO;>tzI+2XG;Tc=G|6FIbB zUI)Crw|CQtrC8I6kASCj?DO2xJq{AFSyr?{_Qr-aRPj8CSJ-T#ZX|p(0$|rbWtLNJ zU7UQ+K6gbc!Qft0)s}(pQR1qOkN^Ts>ZVUp8yCCBUpSpue>^e8_P3aCJeg7NVc*${ zRCElNG*+wUnsFh8o`Hl{bp<~fh|@&}qi)0nXku7u$}eN9J-u`-PZ_3Q_3U|bFi#eF zFu_F?g_gNtax*o%VjshH^CYy2;5j&4(P`x6ttz>d-F@xw^K))ys;8g!xB6}UZ<(zX*5ul_u^ZMkwZ?OA z1&9>R%9?YQ+j@S%X&*=A>7Ds8Wz^JEtP~Pw7V4aoT4<8n>mHUaUs5}-tytOQSIp!9 zPjsu$4+wZ1BeEB2NbN!5Tv}VRX>!67w5ggC3d16U%Y)}Z!yj&ht&iP1$-L(y16|x8 z&+E#{m=}|oYgt~CQZ*T2DM5FtwMBw}<~f$3)!vG@p4ybs%(p9&iBqUHxsNIOB`lOx z!e(D8{o;ms`Bl~oh!bF(&r^DDo8%cYW|ghTzRHCvC{h4+IMu_v6!yVpD+D!%)AzR{ zTrnPf?K))#zgRXi+uJwMpY15nYlb0p#tGIdzN)MOl(mn@zBnB_^^*x|-YhcdBJdRc zg!B8NxOX5o9R+h15tOKrl@Zzz)Dbo@tHfK=tLDm22_iyh zy_MuExjQ9Fz}lLJ^>8|gjs0mU7V|tY{+m&{BwT6{#Mw7_Dwg8s+gC4FG}0$Iv(Atb zX%Mv$qdD6>2{e1eNnl1z&B5seGx(fYM~XOE|4RXJvdwWN)X(L}_}DF?sL@~Kz=={_ zg^OdYW~-JqP=(F|=1|2YJC#7oDQx5JM~~CkI{hb`F8E+MGIG-Yc=SLhPR1F5FPJi$ zgfM-^C731@8D)rLwO4k#`$}Cdc3TL0*Rq#z<%iS03bf6(ihZEy;br=LzI*%8?ahsr zkV^_ra7%l=9viTtz1DVodx4U7(C{RQJQ_FW_rnn^lK5l$dvK6tfjWLxd<^P9DLXVU zctqq--FEhxUuqZEZQ-cRaC50F2K%Khnss#YVm>71o0JVb z=*{F{zZWfLIS4=O z&tgkqVt-@$K}4Y|L#;HB;u30;nd8}e%(A4e+k+MMx~bX04~62whZ_8R`oaV?5E%XT zfSj@B&2PQnI}<`~mSt*ooMsoOs2a6o#*+(ua~LoVC@BYEEOKY@+?`cRG7NpWfm!S; z%p6y`frHD(Bt=?mhZ@p!r|!)1+|%wZgUCx9*8GK?l0Ft(74=zVrLyOZA=Ig6b4e%e z=?X`o_7BdLKd)w8h4Gj2xk?v>LYLIoz5Oo>hYF!#TUZ54!SVz)A*7fjhv;=O#m!I$E>A`x1e&A_(|@<>0$IRhRA&CpW>U4i8r z+va?99!i%|!kkeZO;CW9u6zoWW5?k;q%=`^Hgo3-3R_(u7)EMhdMFO>;-!c$CsTS$ zHD9SyQ+9RX{C($(?jnIe-5fJbKiT3%-b)dm@qDCS_cML@e8ta4o&hhw{A5MeM#j~_ z>WuE&6|eUy{-wOTJ&C-*(q4Wyw0lSAs@nU`gc^q@7!F4bI=AIND9hepce$rs%4;Jf zExHn~bZ!6s>N)epv-huu^9M8NO!l)Y8g?{2Ik|E{^#!s|<3|5_+bBl|m2$>Zicv?V zY06{?A=X*x!uPEfGlz#&A~b z$5D?OdAS(3PFLiKjb+GoqS~!sw;>=q8Qu(Id(g|eH9{da#ta&> z^|PcenyM4GF5xsv^8YNU-S?wNF&8o{THBLzgVW3qglnpjVyMc zVXLs%-qE&f0ZL~$R1*^)j%H?;{alpm`GH~K?ArLqe1JrKxE|z%eYXhkvMWGqpn_QW zc14JY=9M^5e!MPQLdh3LRxtCnCh@Ugb+Dxv{xu>-+u(r}L|){vX@HkIUFm+{X4}^r z)U^9aG>>wvHovJSttWTkLOZ&?j%3!{4v)4H+|WyRi$T0jOh?z-ggi{2@P&vue1GfZ z;P7?_P2j_F`aTFAESMEx(c?N&OqmA#GbqS&{KN1ZKr_?1N)w@b(NtxR;- z13tOnbFUrrm)?n8xw6x_(|?@*WIVv);1vhc71Qy}=BK%5wk9*jU28m3*-P)}>`unb zZ7RIAgg$+c8ZWk)aQm4U-wG;G;%ZU5{=A9!RlI#8UlK91wM29B{6~GFb#f z2aL9W8v3Y?&2k7(c@EI&zeLWHR0l(;5aEj#lcQo{knxM{ME8kTAZJi@;^96^Dj|Vx zr4-xz5+-TUb426kFaNbesl4E549NHbD)u#8QmFC`S^r#GLpb1$bh5c4tY@*YATvXIwUn z(QOGRZ%QqFeUN&q@Hq`M&%YS|tXU2?PZs=wv_LL^Uc)3__&9I4$?pPt#rQxMm z`S=Sew=eUYZc6H%v^cH6-(u`kADi4-EynKpRK4*U@O!PqTpw0&{_D{My*NuE3tTq8 z$TlozUS<&!^MuQ0+6{~qRNa^AwB3k!C>02*Jts7}v;O=AVEB8^btf-82w+ud(3st| zR5Li-$LvE zlem4(EaAVrNiBa|LGtl;{vNfDtD~l{Q|oRzhW|}Yen|B9KyN?c_gg}4_dd7(*8K4P z^AG=4;y=`Yq-IiDS_pYyfqo?=;1zRJoh$Etd)gWo*AH4y;3GKT>bVqn3Zyk$#qd4Z zW#gqa`qiJWS>$(k_WlxY?3ln=oI&*_nYASR0TNMa~ZfaNS+g4 zCI{$8@ADC}Dqznh?0~gNL!5Iz9o{&udi>6c-*(Zt=jlqNE7SMrie*)~2Og&5r$DMc z+4!16)PJp+M{;b_GsJ){AR^IAP{4XpH*$rVnwnCa zl?jmt!bLvHh?h;UoPNLh|CKjJTe~KuEwO7{^>63i^bO=(7imwKGyBIP==>KX!%R0-V_24UBfb7^I0;B&%3qofBZ);*0GFNOnvdgzX|{T zD6?w+{$ooqS%(>l`*HtziJlivL8-nrQodh@iA--OL1Z$s7J(}sDaWJnK4&z0A>)Sx zCC2D-)?EAVAmfdkOSHPJpzVTHSqe#F%VMT>?|tsv?7T#de|nm~e(1g^$bNI^&*HxN z=j(RO2e+r1NYXpMbMM>z<}^qkGV*nFS^=bZ03oM9m+z9;iw37ps~1FETF{R5yA3^h z8`r_xS11#})hNhAS9jKz`Mu#GUas^DnbO+dTlY`S|4{t~g zED;yp`{M>q{^PK!xd)hY@TwSsj2WCX$T|g>ThPwUV#bpUI6HxscYj<4%&bD8F9O^g zN3be^wi{d+rEW_)15iC;<6p5WyKUd8>adanUA!04K7hKs44C6qW!A zkIDWEWIQpauW1if8;$yCaPCq2BsZ~ey=?_CQ!K6IdzhXA?IH#kW07RHfa*B@InkM% znQa{xKs%)tiZDAXF`C7|_A#?^D_36d@I@IJSSaqN2zJYVrpdrvFe_>!u#D2HmG$MA z=-!kn`KS*t#-e{hf**vZAX7%+W{>F)H=12!Rs&>$)kARw;%LB@iTIx!Xv&`Mh=O6H zx)k#G1S}MIHfCaF8$cPM^DN7GE7D_R@2q{@|M0L1UU4r|mfL56`Pou2T{ZlEGDmC6 z=C5a}e)a|&Y8U>9Ts4aOW}w4N-e`VyU^@He{_N2&SU{&69kMyUuK1tMt;^P=rwHXU zlZT!-)*f-rshF<&AGgas_`xhWH+=8f+oIolD5Jrj-DSQg{Bf6@WfmEc0BWkLpge(k5dC zfO-`&0I=+b5|V!!+~nB}vhC;*Fl?mWnCH`nwxe72k1PBz3qaD|A)$vsgN;Vkp9b$7 zB!B$puypVSA6Eg(G#`ZK(Nw|(Ff9dd71%U(Aj!u9dOAA~8V;Y_cn$GIU{@KRGqS6& z%!m)Zblh-y__034>^{Hb(d=He8NV@*Jcd?i}^WTG;fF z2KcXw%AU&=u?oK0GxuKov|b!5Q5s@m?*H(`Pt{P7fbG_YytETWUL9e>XwMPeTO&V` zGTqMXDpemR_R=1ngf7qYuEf>$`nkM2O*klU{U|gp^U;jZ!ae%;E?e_g(e+RRZk^!z z48BJLm59?SyvOL`o3{PnZM}A#X{-cayLq{gxCV>yO|z%+g-uu zV>RCsJ*c}IEfE+uEItC$5g9iK$iZuhsigoQ%ep!#0?KOzG_-Swyo-5~hOrG0vLk@w z!BevjNmOBV7BzQTF*v$op78bwmmLkH^*!(<-tErA7+XL{$Di!R{^a#q_H3!ChYiPX zdikT)4axH3!u6t8o6jP5iuQTrZ!6LLjJk~N&vIN)rRn@VgLR145&xp>$(Epy5-t&M z?XQFu+W+l03{PcnK^%@G)|HT_ZSC!yVw-m{KXZR z@}J<*zK0JDHo)#F(Ano9(pu!k(s}?21LjHQ=uHUU@Yz+HTWUDly;3De*~gpO)f2=? z9W!eVGknv)%;5|8L0$cbd_>be!g*B1GutW>Oz|PIdm_TR@2`L_WwAI5) z%21nv5z|HN?pM3xW85cCJMZN2rNQ8hC|TYz44|Z@oEIgcXe}tzk=%}`FuvvrUTIWO zYQEcn;(FLxi|62OOn7>Y|9Y`;3zA}0uiDAoD&4Zl$IvKuu@g& zi)ZpXKU3bW@vw7Iucb_d&>$7Sd&B8RL`S#Q?*j!+&ZT$fVGucgLB!?cU=wna6dE|ljLmP#e^;q~kUw*-uU zk=*e`oX4nRQBhIM2<2Fv9;>9w!99Fs6p&lQ9$M$2{s`=H z65--nfkO|TlOtGyCC(|f*%RN5lzus+m+qZ>p*}z9+U+>kl&$mhHTdzF7wdzH?>0Kd zlgwdP;U5CWlgW{d$L9VS9v-o(A76|d4s_KI z1)Rm#b{_o7zv4FbVcaam;6Dl(xn3&)vc695lO@dnm*49VGZb!~W*}8^!u5w)H7yNI zIw>L#xLROvVCe+M$4`(<(L>OYe1lV!q?ZcWXry*Y9`XmQ7~|u2Eot1BI@KcL^-Rp#BCJ*nB$UXQB??;CujG zn(z*Pg}DN37ztIt_kdLTh{4byV@Xnt)yspXOF5pZ z2G7J3%q@9!{Jb1SRHveCV(T|HEAIuI*Dbvl_xN;Ioh>P?zp>?OHqGc@lF^+br(cW@ zzNJ|Fa`3;9`{q;Oe-*iWWai*C(iSVYsoh0_jl+p8C=MxFP{t`oQA~+Fe*wPYfs0~Y zv?wPGGcI$>eF4X(4`&OnIJVJ_uZTSl|Mx~q8S?5bkuX$t^?LY_H;?}`?dLI?aBx>9&%*; zWjs#!byV!sEdEz`;(wGhako-?%+G%vF%CjeWUdb;|L5a~!wQ#3I#=C;%Q67iHJDQ{oC{MYS^-heL+`3WGBH|z&JaaUBmAt~wamg1k<`8Ttm z=1~_)XAfkII#zjYG=~bzp`q*v=(UgxoIml_|iKi?u=+93skE)OM;xF^a`r z=zEP@GYM%{HPd|k!g<)+urFwY#XIm#UIb1oJ`U$n|8WXj{no~+ctu3M7n!_w@Y2yq zFimva{B;)~7n~t(xj8xDLVgKt3h+zA!^+mvc4tW)SU!uo$v|3UV=a;ZkZdcm1A1@} z4Ei~7hq{QryH^n?$m>(5DPmssY({o#f%kS#1c}#Cc%=%_!PiIXnS3DD<@yqd|`a%p_q z*Rrw_V2hOm-6S+Sb#!!KOVB1-FS=C~6PBhWDIxLXwI7^#!@wrsVq~-ck1$0dYtqM5 z7xriY7E5piLZ2GW{fCoH&0tP?1sQ_N@IRp~td0$%Z_O+jF}>-TkhVZKL{7kPBT<^sg4q^oG^VF`-ho+!)=)r% zZIN>uU*{QsD*{Z`YA7ZF0K|kKBOGs{9F>2@ex*o0=f-FSiDNnZXW$lm#+Apz4~iqI z(FmtZs?s*_*uInP)FAg5Sj=Zk5YsmA z0FT+(R!XDcf&i|rgK>M?xI9YFhxzMcaI_)k-J5GbeUIiRbOOn>^dO1+;saFYBrB6L zt8gnJQKeY|1`YR)fou2#tvobdKqo`RM>2qH+ZDcyA*D|)I4M|zA-v&EyU)Jc|!Lqklpa#JeEHVrA|^r#~E)|wSCXIA=~&t@%d5lu`km% za(hIVJt?s(@eC2=EqukAW(GB%6~`#QTte(NZ3zJ!X}fO)yRc3H$i%6s?`2GNjY+NL z9&S_yC-b9)x26xE-mIO(KxbuOxC56DqG!}>kWxW*CDUoT4SRbw`Hgx{+qbQ`t6=?4 z;o6d^r|@*wN5?C7{2?(c56lh?)5Yjk3nlD|&TOI3Ft@DMCM%)PIH42r1RMCBg6coa z_77!Im-`s}dt1g~-OfBe%!H~~$vmfXFyo;m9Rwizn1xCm&L%#6fiJd#Mo#QH^jbR+ zYvRlxfNC+PvITe1ChROh}Z61?cChi4}jk+QXkx{LOj>P&Xm#X&L01vgn%ZvYGU z*g29{4ILrxxXoFm>+WvX3}xK6z>P10s6t-)b{9 z2!P5w-!zYUiDq>AUcYPL|NQANPJW&rpJ$(MXV#D3u31Jr*?~iz9vhZ7;PzJ>MfaYG z1XbHAG0rb!2AsjTkdN39JqW^2m8H3(vj|zv;_dMs1!e8jd=rn%xJsEY(q zsA^8oYRZt#gd+_f+p8u_x0?UKL?i%bKo$r)Ee-;MuIx*Q22_Vd2E}L4e&6^$5tQ@< zt)FhYHge;t&o|KaNc*3NSt;FJhk;?kw|4;N>Hw{u$;;e|*AQsv_GTwz=vv=}e;@Bv ze3To=D&^*{Sh@4_!;XNHj{$}rGLx?*oJv3Lqc?1QF5F%VNWXrjw@%O8F???neL92k zjzHTW0GN{dtlpW_Bw&pV4q#Ee61wt(kyi*qwq4G`xfnG_-1nfw*G8^Q40}IL#DdRz z$L>ZmI$U-jC&Os54X%^z`kX8~`2%no6d9E(rEj`bf<7EJu~%}3tf?enp>X0VBcWl z2k!MhCFK9{kCf^CS1$8^ZZ7})HJu>!r06%ERsT?>B>!rE;!bG>93>(@0~hJvUH?Db zbpY_4K&Z#lQO1 zWDP(WNG=AUfy*LV`~@@{3u!khPz=qG?6=m&8G~n>2q{a6bKesI}x>vw2nb(SX|7jqj|R=TJ2NSPLyZN#NqBD;DYYHzjo6d`f! z-(1{kZt#W)EXxsd?whBOUhdMzx^zh$2HWFhG369otY<^S=NRHX;$^=nVKw(GQlnlx zO%<}WwCISX5|)6i{4d7R_K}4E*yBOt{!iX2c$s+Sbk+5~8n&_j9#kFJ3T(ucuV)_5 zhdu~6UaeBkG;@?LK5hD@Fmb+h`n<}Kky=OO&c+97f@F>^UGWgWpcAc;CB6YrGhB6w zPYJm`!!(eUk(2WmBoc|;rd_bJ!b#kW)!WzW?LI)#WB3@q^DJMtVG!Fyf}8nYgdz z=hRCoA#{;AB;3|7wj&{p(`HL@y^a`&O0*x&gLlBiHk+W&ukQf;zmYQQ@7KNuGHf(v z9Ef&~e2V{TOqvL}tI*Pe8t-e#omb$a2If-5LOZVUG|Cq_Aa_GQi;hIE%wtsoxEsI& zBmiceBsLET)hH(q4_x=2?ag+PL7U?wdK`i4t}*N2|lCrnc|!$ zXwEPxyivq&yS^q(iRoU0hIlfW!Do<$uwnQn{jHwq1McEBvL7kqTdk9;=E6y=oh^T{ zWf4O0lH8b}%Le$3MYNw={D}<$*pjHcY(p(W$;oT%ha*(9u!f#DI`J=8%UzrH>5Otu z<%bwF>roA!AukbMR`WAd#m5Sz*NhsL>xB3dclgtYqFWw^vXU2$N|*=9ce?Io1mwB6 zE~lI4#C9QRE8ynd{Z&JSmDDxt3|*M+ee;lj$LaMnMoGWneZoP7Aoob-(EU!H$lsSi zsh()iWBeYsnP{m$`_*`2P%Fs%$md(nE>txmQgK=0)CZu=B|7(d-1Yx8m$2tO!UmL? z>vh|`02aaWRZn6Mn&29TE!rBt0q$rp;ki{|H`QyE4ImQWfyYNdsb_1j2BiJm%}+)} zBpz!Z`|dow&=fM0c2WHolyQSFR4Ib_Dkvr3l8`-1f{_XUMjtCeLFX1ruATxKE$Oxt^MM#}V`bDWzfC?wxq|7R{AH5g9qT!nYXVJ7gDDa z=_X)g$5aW_@Izpu1T%e6+VSvo?^~{hT%%;w;UFdBFO~NUBxw4&&IZ(ZNx2OBhYX*K zKemR>^*Af)ygy-<;XFflSXfw65(#A_%+ST}T~SlxGxNgB4e|@j`Ds!g@Zo%kAKTEm zX=vwF@$4Nw9Ka*z3Be^HXKv(K(Xy!=b{sm6a)Hvy$6;$NCPZ(-q}ISR#+<=Qd4WUd zn-;4x#h@*6th)lk&<)l=uQ zrXG!!T4HX;sSAjRJbh`XqWa0r?{s&F!`$Yr30{X6TJM0;4eev7>4GVBxQwhm^GjmI zeZIs(eyQl$Jhi9rM!Bjs)9$n_0)eYmw_E!@uHBV^==sXuGfF1lVJa%c5I*_>a~{34 zDAh;`L2)6?6ga|srrQjQlo+^Ey&#LaaQs!mO;&}M`&<5)KV{rz@~J(F0(!8>hfXMj zwG$#0X)gPqSz%m`l(Z?k;`v$LbR`n*2rZZcW%|6v6=6bD1E|j7ZBY0Q7kTe2Ha~4W z>(2OmLp9RL9|%lIJsf*%t;%OOT9B;@)BGon*7A4o+M_juCBVWRVOX)g3u5#_T9G4^hNa zjb_sSb8PxaJ2mvme{S`Z>jj7CfPW2xvR1rnufi3s#W@?Q4x#k5m*>uX6Xzt3jb$r*$w!>Z>CKov3g{(|2Hw47xlB2^ z!6Dj8$f`S;meq|WBBfgzPJv<$(Y-%1U`OAc<29_ivCsLqD)GzJM6dTZ7YbS*e&D`j zSRgx*2>J_H;^6|ORk~Z`o_RXDoe7V-qzu-*aB(m%T57!oWPY|}=QQWEh?)=%?~pZ~ zhAWCA8e8*KfrMO_1Em@k#muDjJ&Pd5K6(3Y_Y5QVHW{jEe?Pk)u9uGndS2>}>Cu(Y z-DR5-qt|`JjyerVb67$)QFTS)XT=&1<9Xs}1=CJ)?hraXhmuGz5{WEfj{lT75)yPU z*}GpnI;S;R^VQRgNx=1ltDGxVClWD_OyupbHNvdU>XcVXI=Jn@=vs>AN;-pm*2!u? z0ND;{ZX^aYryU|e;F6aNt8rMuOb?1m<3w-3^}Vk{aofflP1A`^-Tu*V=jgQie}81? zP5gm70fQPBNQ@B!fd#Qtj(SQFAF)RpQV?TOu?SktP^C0PZ{q)BmUqgFG+aWMmanP+ zA}gp~>$}B>F_!l*ci058OBtHwp8WPriJGttfQ~iOwa#~&q0a8bgje}mXY-6~1h$1x zl)os!EPoM37p6`kZ)Nk|)kAp?_dS{Mb%h>o)VmK?Zc&tkmyvccT+X*&`J5U~&91R( zp{-WkaBKj>ZnMpePD0_7nAcmm~FG;s5-+tIia>Lz?_DlFM zR-H!*4Gud_-0cG_dKfi>4tKRh;pBQOHDT5XDSMuKWsAw_4Vv2(c0?As)TWvtZU ze0x*qSST(n(cNkoa{j1_EO61HD_T%Q*)gxw#Z;C!_D1Mfh;aoC*|j!NpvxrXVWPZx zEO=e}dueQ3eAJs8vIV#4U-y1_ima9ZBU*m`IhiFCBTvVCPAt6?%|h$V`RIva#KKj> z9E;*Po|rqf0*V>$z6O|vE1}_TZnRtBc3$nXfB-xcGxTMrAA_$4bY3eKAUc{A)T+`p zFj;5zPN3GA<+6z*NKK}};SR z1zZqHsR*FLr+y$&41%e4a@VXBh`vVR%9enC4FmqM6w!wClKVv7NsSY=hljhoPw9;I zzC{;{?E-n)e{1*L#+KDmHmTB(sBCTDMfSlq;J2V3ILLJr_$^)0Bm;-QiT&0LQX!%ttTJXp29FD@_1sE`U`Y~~%90D{UJ=;ufR70LS zIKE0}!z)V}C-=W`wqK@vIB4ZFb{Qe=MsGlBvBE$*^ zEb7jVmH{sn|IwJH-U^Rnd~59T<~0Wt@{1`Lt7hood9{9 zVo1U-yk_}}C^cfm`&E*{q_}?If-tHSue9o=QJ}{pX&y8{&DfJ=1|L1A3&b2#T-=q% zw^_@-xT+|APo95L?}|cu0JUHICTODO-_E*_ERUE?ilO60()8|)9MJIesZdP#Z zYdi5vsyJCqRO)&~l~)VJCnI*^ML~}H(B7Ya;E6{tLcFUcj)6SPp>GDUrThWeBnL}8 zL4|Vx4j+m=2%X}Z^d(9_x{OYf!@|2dt+hr9Ud87E}zO?&Ss!YnxuyWbufg6%|2l(R)lpM&BB80OaVa4*yVf|ouUL!(2J zm;*x~38TLTj3zp)+gEIR%){)32OnQ}>1#e1i_K*aQ7sB%ijU@bkZiYd`k;tQTqw>_ zdA*QEt>j@ATJY9ZRGL>$)axI7l+AI=06PV!Dep z5x^EnvLkU+!*J2egX+2vcU&*WO+&j|QbZ`nu<|{rH&?g8qASL7OkIj+qc=6dT- zWCM0NJRhf#>q?hASz=9c(1WaO2qDZ=58y)Vt~iPz^K%te98EuV~Jw6!<}PXl;dWg>y5Np3CBi6 z$gA?~b+T%h^nLfSxnQ=>Af6*9;v&?R(h(&OBcUE20lhXedE%1?r4-2L{dzQ9oH{Oy z6QKEX7&-LoZow`ym$nO!#9NaZog1YLrS^na@9!^r`;F+4laVO}M@ zvn`a^l_U>>%G<3^9cVw?K^~lD5{Z|IK6YA9B=T#xx}^k`cgRf^n(lC3!&tTWnOvXl zZB3rSHNf+bl1J-B8aM7Hlr$0#*APleeNdcc?f=SvBNOq=fyhHeJQ(_{fVHJuj$GTX zu8R?lZ*vrV9m6mI?-;nSPgn@?1+8Gyg(5Z+?v0SrnKo6CqCJy>7Zg+n#i3!ICHpFb zPUNsTr%uKWhh)ST&clVX`ubr*-cRUkF!4@l3FA#Z@f+Wan@Fr4oH%dtw;s7u`@=vy z2G1=}MH=o}P~0I_*1D{4q)tt8{Z*k_yd-VVwQHgJ8Sik5oD2F-yPdC6NqO{NtenhW z)p~us^-Mo>eXrYUi=5|X?XKrgO3F65Q)7U@2gHZ2#VI1|(GHv!fg0GloHTm5-Ep)n zRwjyr=+IE%#2(n4gEV4R2l)(w8MF6 z%Jg_!=lUD!4=?Zx=SOe}_t?T+jo+1Km8hglo6tx_SNI(=qbc2m3(rPiP=buumq2uu zlS~k^B$!rpaFK@Nv-VqrKM@!C4n>EF`A&GNzBxvN2uG9=+2UpPXlMXewhzf$ktT8f zEdzEzS^&P^lT5rLY^zy2@Bgx6JBS@`j!BTB?r{G3##7M#m6Q=jIC~(Os+ezg0}qy9 z;a`85VN|kHi_dLThA!x$oh4Oa*~5-*>(u2h@{Ri@?)RF;q3c~MDP=|$N?jIcFzn2PdIv!! z$Ka4?_CX!*V$sv{($yw|4<$kYLn$iH3{7rarjts=qC0={Ol|2xfna%i)FVr8Pxn~e zjG34;p%La4zPZU{+!43{Q=)e72!98I<3MXL-fTi62vX60d6`|*TBq!E zMjpB|EW9jQF`3yUxhN7r3A#JUzEjcI_?Foc5sVp$bOf38H)IcOXp^52q1alFb1Y1* zVsfpX;;$GywL{MvQ}yBg_$BBD371Z(CgaJq2^41zM?p%9hcC~eaqw*2yIC~rG7X%( z7_7RbLoVb~9FrEpTe-yv+)78aYzh<8?zQ^VUSX(RW_hP1Lkp><*K_?VzbH>~^1R=0 z5I+>7aLBnnbFIay^T4FujKoZE9+l>m+cE`aVl)4^D`mAH8IRGoTsM^G0N=kSdd0R- zf0+b`9Tsk0R4EdHO>G|xQ7r9-ke|>6NwooM9`X*c; z@*Ho&hx_^tcCVqWu_Q*|%9^xLe%F{vc=*Bq^!tFXu;vwmI}`m~^3qy13M z9sA#PmjCDrMwElB?Ruc3cWLh#=9>GP_a`cqz~P*3urCJzp`#-%V_)Y%RFh14|2GQyf18tD2<`soQ~p0E-v7V#!cRPNfNu?y z-Fqr3VnF)_>IiI6&|!@lz*+c;V%~Q#gJ2tshAyiVNBxyxhj_0~fl0l%nAoUzJ0D`|Dm8|D>oi=#O#Q_Kctuz^tWwGsm#V+igViVC(fwSD?NJF{v zq%~l@fWPQVnaH}U_V>aX@ZqWLvZ?RT^d=@YC@kr`c%A)%pQm>FpZ;H+xyUE!HR zzO*~V5bt64#{hfuk_T%2DeHWN%bNKdc*`O+uE?R`=z6Y=J?MV_ckh>JRj=_E)~J@t z;%(WQSy|`t!_;z|#k~5(Z=R;}-v$mq zHeQvQS<=Igv1TfEK1BXp%uuibZfIZI~yw<8tK~QRp)bGaJ9YXy}qk1r3%? zo1_)Wt`7e4d(K4ipF=u<3C0aXtG~f62+CGjS(Y|Hjh)5>cMEcsVU%Pmvd`=JoEF?( zyxne{PX}Zjp+Jy(u0LP?g3(&M(bLRB5(U*j*N1M*!0TH>@XM;!#>1l6r-!^juN}LP z>+0Nr-`D$$4|C7RUM2ky$O>SlnnUYIEQf;xZ6bSG$p$S(>}Lx&Ol#v|CGuvis;WFqZLqrZ&JH|5*uf*? zpP?>YH+Z-9gIy>4h2iHWe`n(blfg`d`)-*2TO{rBj}K2~E?A8-zLpc6aEZf}z3P5k6CMDGd_VO2L8)bccY~f#!$@nKoNpIb-AzhUBI{dcx_m`R} zRBxI5R?h%Uv0BwD&>yIMO506YBipoaje2r*pymd{oyy%KPC+cj$q$RV%Ajccg#j2iJlf(=DP_G9TkL{*X#&!e$1CZPLOO>!~Xmk7xV2-SlDJ#;WM&Cuyhp za&);GZ?jRFBvmD_o0=vPobrzHCJ?2XWLH-WoC>bGB&Mt8n%u$dCS1AvB)3>{u54se zEs$9~Uppo(%%hm3#N+A4)TDT2jXGnWw_EX)IlwCOE}u_& z5n%gWs+X_BDA@_?5$^^m_1UX6bmA@-4C&T%R4`m;X48p1D zG5*FWxn-yUd=cCNg)ueng` zGTl4C{S1N8Or%19+7{P{b^H{Hg$UY54jA(4jQbBo2^in#BV=Z;I(~QT102b^DA`8) z<`M)@wnYgD@UJl?!t=e{)qXNb?HkvP!P{kk zoCJu0bcs&m%mik7hp?Y>3#?M4JF^Aa0ZBUZ2u8Wd-{b(C6Uigm4tQvuj*_{9kVSj)~*=V_I35r>aOBDE^15qZB?^R2jpE8 z1D!)OE+9?O`KOg?VpmS#x+A=S8>vd^9G+;c>h)Qh=JqXxS60#5e4i7`GJ6ivJ2KVY z%Ehx@Bw9C`#K4S#M_)Hb;?LM(=p~kTcLXUlySA7QNe+Br>1uqz!FL9d>nC~d78mf8VU1yc|f!-Y`Q&TYHTY=R%&y~UF zmx6NBzNNIM=3*CG@T$^{gEzIlK2=zZTRYS5U2p)t5P@iM`WX7TB&W&s3K9W%jhN6$ z;Vr~ZEehYwGe|=KkzR*1^!9EXcouqpdEPpPG&zWX8Gfj1i^rgxYE<+rc(aUAB^!WLIzltwNC5Pc-Ul>GR+I(VP5gd}H$I zr{jDnR)LgXQ$}^eidbkAzeU@lCp}_|sZY3jq|OWKMQ&3&(=Ry7QCkWx9GRMApc}A+ zx*JSRQPexz(^%uKRvTXvWJDw3n}1wUior1i0~ zyDA4}r`p3w%g~EJ^ZhYB#OOmFhya<6VV^lAmnT(A!uRp{eV71ay&0g z7)N{;{VH*_sN*}yxz8+l-(kLb-1$po(K&KWN!i?%?oY;;bp!EoO)G45iSkBoNva|e zxm2pBle*_u>SO3Q)(>ahlukTHWF9%3pX@K9R;#yp&(HtJocnh*d^^v+c9Meb-{-a1 z=S6RYX}sGc&UlWpvcf|LT`?{k{LN74KRqxtvGv{a*BDP#gR<@-0|r0!XSwAJJti_6yO<9xLQ%GQkG2KBW9meTIa{rJ3fRJ+0e-Ttxb zroBX@EscAo&zB@c$MdLqnKhY!8fh}6g~#YG_j@q6>m}FGVO2v<8I8+9Rsyx)vWS(H zRh|4T{2HF3ug9-UKY>m=?AD)r$j{u5o=@(csM+!QC9)!CIW@JtGrey^K9fn4@UM}Ax@h?M?d?V3%<-Tq^C?Vjd}i54HEt{}iFMb597vUKc_}Rs+YIKY6pSb_ z_%~0tU^DpLnNzzW>-)r_yu7?WQq}h=ksNEYgrLtNP*!f$Y(-qL_#SYBpkpRZHS70b zP*`esT}@5e7bzK;tX654o&FYVaypS^LYW-tmvNYXx58~s$B*@MWd*XnX%{oDzPkan z=bkC+{*;`#{zs+U3?aENMZQe4QPUgt6Fx1)YGzK)Mkd1l>W_q|dTtAxSmpEvq9onr zs?2IW@G|di^u6M2s+0}h@(p?zZ5@zIAk10$8-9Tkg(qxeflvOf<5&N7yCh~?pt3ZF zeT_6kkzjw#hf<`@l5jd+2)Hcd(ja3ZXF1k9UDDxKJM@b-RURkiIl~v0>I3EHM@9}# zPJ0JejpYg@p>udE_4fHm;QbMf`lWtT*=4!I(Sd@}(u4{p2Zyr0@aL3#I013|`?f*f zXSi-3mS$-elbtda?dHnbQu|-+gMFepWqdMwyIUY6iCFGGvB_Ki_^8bk=jy}ec_N?P zJIGf%NOBArr3KE{9GD)&x8llD zuxqMT>zR$bz0(@C`k}DUI?{&xAfRp*sxL7%4flYpyyDG1+%wPw{SBR8IV1kTjo@Ip z+vjh*S$1AepI)3T;=I)n@M;4m+AfFU?Q>lO*FbN^wEpPJULF!*i)LjWrifoeC2taD zO$@(yaJ!f-Ge~s#GH(+bt15j`u|1huIZfzB8SgiYq@0Tp2=V#u{d}lB`Djkdzpf^F zsqzJCBaAQ*6^e~kw{~0|B2p)3Pk8;hii zq8XV#v_M>y<}bcJYV(PU47I|TZG=@Z@#8w#@qx`+Tru}7e(MJARD|HpCyZuYLqq%N zxy?xHe6qRgqu03-V1ak%qTsaO-rlZ$5ET1aF67vQKazH;By^*F`Z`LBoK^jfK>wvp zl3IxMyTy+Rg2h5+^f9_s5wa#}+pt-2=s;M=ePhKrI=KItkil0!F%;(h0-jviCJK`a zCwfi$+OG`i*|fm-k1Fi1y=#De-y>HJpNbeI8zsjmN{NXM>ku!N_DDQA5jad~;`Em% zF100r8owPEw4(Ue55;jsq=Z9eo|@~_Wg#+jI%+H?E;1zrEupVz%|8_WDNH+CNBWi71=brG%Yb>wH-iF%$+qx|n>?L-5vZ zGO_c9v1w)!_?OTNgj>ZSxeQ8~vl-Gy*oGyuWf>_@{Zp_g={cS8YSkBk+*JN>V$wlC zv-=wOcV&~P?GCn~{64eKByW{Pr=mVoX)^lYb5Lve?+z$6meuw2KRYfhm2aGO!J)pg z_~#V;w0)<+?`S1+Zv$~b{x|jNVVfd>R`PJbj+g=zfR%&$mHPZI z4z!%>EKaOD9`UKvSle$EQuyrBsWa90O={i4pZ2!5-+UtOe^zCicH=U3z5pm;zuiW^ zcPVy>`%Cb`zb{PYjtoYB3RlE$t4Y7^Y(Bq_N(2S;1KVxAb8VV@RIvwGyH+?B8gRzB zSn=f~31&Z9Fr-^5+ESTK>gUenDhOJ z)OS;+$A-d-*FTqOlASW01Sue3{RNi4`EN86WFDPx#Gd)-73ijFO&8h>?A>s{kbr4p z%JaF{NUJL0El)?eEP7`S=Q>~=G!X?`lJaqe>ohSwqzpq&O_)_yPJFA&uLBR&VNsm1 z*Q;rJ>=9?`&q-fBM{~}&Z7w!Bk3wH3gFfo}{P}ZtOh#bC6_XE=*Oan;r;ce4%3O=Cu`x?O0tM7<;~?MVD{wy%AqsKbClQOs7-rc=)|Dd zY5eO{14__m>um&|zm*9PV#8p`XU#$=PLlN(~vt-c858ak}UZYp?v$lo# zoF@*I81DJ*^pwC9C-Z3yI*Fh)$BPZ0otmf6Km4|>EX%wVpO#8Ads=yUn-~6cy{~5z zai~<{`6gS#NdvY+Wz0zfqg{~DZVTJ>7}^e*&6TE!)+a`ri`R>gW{rE(?0Eh;5h5DS z0=`}4p0-oB)+j^>qF3ZJfW=C0e@e?2cW1<9rT^K(lfWAZv^sP$;%kjGWjRhxPL!9b zSdyi2ajdUmd0z`2Oic|>r;&MdvX^!DT_iE9C{OafgWRux(?nCy$~XlF^A6hTqoXfG zp-zMZC+DGizj?<(-`v@h4U=AkXrEM8$5pDJhG_fqoE1l!UNHLrtGg+Q;P;^#Nyy~4 zLiUo`K)RTfxSzRgH_6B7Pu38q74Hh->9#LcT3z@28MDzd25$y+j%FUMQee0!yqayh z>A9de_%-p87k3i)#@Z(zW!IwAi?8@e%v_LVuX++=-!olYzT`8_m~SG{Lh} z6zomD(G}qhmgL6-K{K-vd?}FNA^1C1VW6@_o3FmUW;r^BaOjNcwW`>ct$qsCk;SyA zNVh6ntJ)N2$rn~pM^=G~F87*2y=w!`hXJk?9CWC)D zpS$WX_x|BLH7I>9+(_{>Et*)zeL@>s%`I1>P$kc!Z)|*z=ugaZk^>qOU!2FWbN_kc zox}P17OJ#Xp`HMdHl~i2k5A>-r7$~&&$gT$?~}_ zH$kr4@xu28n?Zu>v{d5JgQDJz4veJkPep_$)n=pF^1pA~K%w>>CqMqoTKY{$%>FX& z`CT=+uGN#Kqq3hin)GK~uYSi$Z)@F-^6k<>fJ2NZlmx#_2~#?pTPIp?IY(v%C3N)l zH2{RGq@?8Q>uYR034rh_QY?RCA?n|WwpIKz_?7ZCRj3cCt zJfBCM#ySiKkS6fR;f(E# z+0)vH7)BcWqu`+WEdy*PdU!22Z>TR|_HWjQUR_sD4~D7(>tD>|iHp__Z&ygUj%AOXh3{by|hq zpI#q-`0B*oM7cgSP1O4Xs?wk#B_O(f#AODbm&j|jC8f;d+c6Am_Pr3|a^DD(kHF{rR(VWzO$Tu5{|Mb^a5Ww=lx3egL_J@mSqY-k1AdNQKHL6RCK&U#!j8q z{rbN>P&gPXXQ@(&TUk61EPbye?lpDw+3anc%(wAQ$-QNP50Dv{AZGBy>vLvDJMuCd zw2NP(`NsUkftFzz`r98k`S~Fa9ryIO%)WXnKGhH(4wcEL*k7lgL>IdaToVykzNcGk zz3GyMM#lR`A2kQ*>(R;TDk|Y;yyqf9A7}E0p!&UtZs#`0ou;V>n_8)n^|KqnTGO@$nU#mVoJ9-y(0DH)n z68TFs;|X1f%`Jo%sv3OH_OuykMK?tlYsku%5T-a|MFD$$iw%da^9%xibV~lR>toUPbrfV07S+kXOQ;uDn^hQ z!S({IJ_e!7F8XwpOD+vkTfbAVrjhMO7IIfvj{U1DN;i3W7PhKcwS&S5`t z_}8x?%&;FfHQ@Y&GDu=GILt)Lb8vEST$qU3*J>de?R549K7Rh3JGwkz2`zNfi>R*U zX0s{VGEffYU|(2j@ITx%AESezDxf7hnf%CEk!im&@12JpsmaL-tqm}V>TK54(lXoI z5`H`<(R>sp6NUfN5?5aCPl0K}*TTY>&Z34X4dy(giPx+GWtytSz%%P9&HjRuGyxm^ zasWI@Yzi!wuv>$=+Ji_y`r{K++On6_qhq%4ZPjiN*ugrpl@$+j?_hUpu32<&S1-oA zOR9w6e~Tp2eyqBcC?&Ng{@w;E*4BFZ-%}?;qHtGU{&OD2{veXNw_~qQ{6TNY*!H_9 zx4~q2@6V^A<4&`w*mlOri>;lG#~sog*&lL3cMqUPF5Ca1YiZ?T?0&lZE;iF|`vbUK zCkUpjrcq?w&ALK(d%O&P13O;cGyRZ;Nae$Yqr27P$NXWpv9UfD6d?K*CUSFg)2&2% z2U$!y^m9=;BEe( z2|H0ro$_Hs?@l||vijr8Vr4RCX?@E&5E)wjrEwMvmJ;IjKWKlrOpH)xc3}0stu8G? z$LI>0iEeP%Dii(fHN5afcna1_l*7!tyu@LkuUW!g?0lQB5TB?mn$~4&NUHo<<&O@z zIY&8``4p*H!Y5(>BZfXKDnDZx|Jv}#bJ^@MN0NHhQfW86Z-EG6(aUOOkY$I#XSp$q zA%K}e<(J}lt<(4~AYHO}GC#;=HJ^&bB-hFb`bB$R$MSaw<*IV1Q`+&kizXCBND3Xl zA3uOH`avmmqzvB$*$Sc{$kwk|4;2&?^jLHAcvbjlW*}bh_Z{Zo6H)iJ-V=SN#k6j- z;BQz4H12l~u!wtcu^2eo(AJmMRF-89&4hnLdXP*_0evX!7d*S)0ITZ`7I|b2p1JWeIi>z^C?YhsT}b>n?+S-XkLZ=c3%(s8_q(;Jo8PF2!qfwwegZ&6>yr%+ zCDQh?!JnBSw(hXIX=S*{>YIw&i?kEjHPK2J`D-rbf6LqgbqifbIr1_^90p6C!^QL4W4Pj3|N=#(9=JK{_T@cna*f`Cd_vGu04H0oz*`5 zOC}wuOhsn+{4nkL0|cqW!YXWkPRcbaQ)Om7ye{O9w6)ilk|Eh?x!uhBCbrQKi?}EG z=gA623eW#MBVnqG<5EUELYdOl=+{e`zS3Nl#XMF7l!JWw%HLC^_VtTibzaRw(g!RH zCle@68R+RLPT@*#m=>GKDk!u7(Zj@luL2ygo7vt_S*bY%dwh>+tUC%Ow!YY3&Dq1< z@mdA3|A|toNdHYPQMznHL^Re5)b>mmesBBh4K*<;s(9VL7aml8tn=f{oY;hD7=WD( zWxY(5Cdg>P!^4xiK`PlS=Chk>#`2Ochu?Ba5-?&V2JUiIiktYoZz!ll4vpW1C<-8h zQSQOd=@*L;=V{&dIMPx~{%9)Sb>Q|_P7?dua5KcdA{_hw{`==44;J(AD{_53r@95w z3a!+Y>%Dv{`*vcbUwPD7pnk^JtI1@dH@O39qjtA|Rm;|=q2?QvUQt_n{2A)nv;Dhx zFptXzf~*5qSO5TNU=l=|^~|C@7COb&;G#z75&ri`oHym=g6E^pMbcsCmM+Y|z`(0m zoo1(Fw>f;{$B!R;&&{X;L|;wTC3JLkeJUt8?J_;LFjXCGK%qh4OWr9VIk0ys+mHNHapHXh>}ZEBJM1OKD=b81fK znc}jV!gC%fJCN;E&FI7u9%o&U>aVnH{eLD&^`bWV$$CrO?=|x$5mkFNdo~D>cgQ&Y zKFRTe>@a%84mt@C@)$@DqxYM6nbciu-f+P_I@7y$^cy&$@0lYf>wQIp;7(sOBOu|8 zvS8iM>m7o&H;vQhc$F%8MAS5)$+FaAjC1C&DZD?x8w6U$N_8VPo?guBOzQ!}4F5UQadE zR>}U1aOeU%!vvw;1*564r_A>q=pNM`(k}LhOfS5QOSq_enl&$9l=uwNiARfn377uH zY;d28HwvUNbWyD?S`l1nrBz*Q#Af&?URv~aBC})SJin`UKzXYp=d29hV4>2Y1uv1o zbEq}uhLM4RH<;Gu_Ck|#(K|eD6YWR{InnA^ov1vYScyoOG$QxYWUYy+dBC#M|2_7m zCA4Jh`Uue3qp!W5tR8Sa4tyuIL-hN0CjOAOsP}H3-O|jI$M@F0IR1|kO=^F+vd2L) z>-O|nPl|u$-`At;53jsDvgmi#sm18B&get>NV^xDjz`G1Fz{yX^h+J8=jG%qz%UjV zYj{7q))hFpPM`Su*ZT`P!;L7aOQ5xP75N{P?S@HgK#lp&j#u&$4O6=yLvX&vOMf`t zaQ1up^j@s#?sCW9>2s(2vmMkqz6pBKB|x@k+VxPR;c(paG$BahbP3hPZh|%_xYKi$ zSaP=un;zN(Y=-3{lA?^?^ipUB^lH|Fmm5-UwtZQY0h|57Ri|hu_YXe(&n!^X_Laj> z*SD@<|1dkTjX3M0m|tn$&ffidM=N970u@RZmA>aOl^!bZ4gJl1arInJzn*LE$8xhL4pl)F~TMA#sZ^Oio z^;TkT`+xr-H9B?!9EWQAKE|wnme%t*)wg@v5?~^sfK&7UyPr8DwD*Hph-h~I2mLq^ zehJ@?LEndLGheywYUV%tAg(NM>`@DOYGgK{^VSJxJpb?Mx8@u~8|=K}6=uD=*e(aC z)}#*SpP|k)Q}vV)Y*YXJt?zY69&djCjym|0By(=w`U7_;ziw|mM@Id%r1PH~8MC4M zs4QXc({lECo4OOA$t?cB6@0z59&(V^Ahi+9j=!jWW;^9>vec8gJzHnDW22ddZcJ)n z=zUae)~d9V&uhpR+)2Eou_h_BG>KW3-%QhRGX4;~o+5Rwr>f}TNx;3e+q6{Mm4p1} zT#NiyYW7~v4nu84nx6Jd!++;%)2G};dc~#J0+2JE4TlO#mw8d#k7Q0iVG?Dx@dgAw z{sFL+78SxELS5AwX8+vW+@Le++E%3y5D)-8JkJO(j`o}L~MYyj@T z>+m!q9Rx6XflBfNnu*EB1n#6)>_9MKU4H`4Q4g{JWQ_(1N{Bo<7h{3AgcU3S7Wo(j z^WA0sEWd3P2m{%|ANZ08t}Kc)P^Z6st!6$|cQkp3X6tnBTYuE?=r|?iKzNn-fzL_! z?X;qX^RXKT%kdc*(KHvFFDP`x>R4D3i?=|A#(63jXQ0Tm0YE-FF}LO$_)u7VXojb% z+~FRamXIdtjrhHk*>zEX7o^)qvZuvT#UpMVm#)&6N<2j5J&;SD3J6lg!o$Z$9nOXU zM??GT6PDm7>}lhQs)`UfC;xpd%&d;OyNVo0)m;1yZBdz3CO8JmUyBZZJKVXb9U4F2LY!GuQ%Z1sBw7 zC4nnmy90t2sjxjS9e5?|{@0yeiM!9Upj(tYS)Dvwc)iN{*?}dPNDO^&{d@<#)o>OI zT}a`%j1lVKsNJ(l6ZC{OK}HUJx-pV@Oh$9sM}?D|Yn9~|@$zel_aQC^HO7T}0F*NY zbUzsF?Ci4q_YLIb<$Zl6oNl`g>Bu;a6oYTv7nkwoo9M;L{33}M^Q(Ixv{nA z_1!kmU;rYc7k9UH4AHO+6~X%a@uS7fZLh5UrKP2zcvZ>k*RGMq7Bw2#*|BqHq=?#j zgT~zOupUk)%&jzNMbFe3_PRG`m>hEj+eu>M;R>c<`eT$0E z?2d|x%9AGomr3|OU3WBdsD>sQq#XuBNjW(=B_48Lir2Sq< z3I#XAJI?ohdq00Emzki>_NMAld+T3xAt?iQ*+mO+e{pd!hE{~WrisyCEV8@3$Nw6& zyr*CvXnw$*T&rq0dqHr@iJ68o!oiy_nSMI2}i?P4}KIp2?&Xoob?s(05r%7Z}c07_iYt52mNeBV?Lw zHH(V+RyS=>I;x?~$Dry2dx&WlV&04_-x=8tVVw^IH!A|pd=M_ZOnU+X0yWVpLn?Dy zdiwh9{^wt&&xl$~w6$kBx5Ck&ayhqfdb9(z%DaSF+dES-03XsmZ>^RBISEwk%jMVi zMPVHP0uEsQU>0g@YKjKfZ{`o^>qbRpZEw5nUbSGoO)m)}s$+o0R}@Txl%C!cTm1ob zE0jbpZ;H4~b?Zk3xq@W-eGiXHmsoXB4b0&t(v^STkM-F?BlU(*chb>ZAXdSp%fK&8 zOE3>o$LNtK?5Y5XZY+h51DL>ErGLT-!88X0YLA;NLxk3<)=&aA9QBx?9g%}M9jpQb zG;f^Zc-o1lF^^=$cwKJ)7MZ3y$(K3nurE$ef4F()UPA!y1VcS2 z;KB5@5p)Yp{Yn^^@EUhoXV;<4PbmUd7uP~nTR%~778M?z zHk>w~yN+V;H`b1C>T6#1esZXDggTcw-$9+A&r#<~=+i8{BVApDx3~BEE6C7aR~cCZ zz;x*3M_S_z4g0T_ZA20TLc;1V4^?SNuYrP&xzOg6?}oNYgiG*X?z?yI-oJ0}4N`dy z*hw!K#oNPV=;x0g6!)*Z|1dUY_(RUwxv&B^=-m7T0LwM=BPlDNT?JG_z2eC8j0gm= z-nonv2bNYS8GxA8V6U8p22oSToQkHVQWnW2fv5StyJndB*c_u7qJk_#BO~n(im^x{ z?m`Et%ntactZE)@Hz#!`4p}+I9P@km?$seHSr*7TRGq*F*bIBD_R=qEe{*f?ne@e| z2mVrv>zvD46|1V@{ONwyd3nesEd*eH`=i1HE{ChrXe-1=@bbh@R)~Sc(6f4MgQ{`p zIq_Ujdu<;%f1>vq&VIeo%P!9UdN_TSf{Ojo7+iD;QF;VBg|0mn4iDu6GeWWm@>rJX zY@6%GoN04&7Fl0>d8!uUK^V)fZ8-2ij0nfxKoj$2<7=5ID_{Tpb32_E zpiahL0hI3i+}xUveb6UafrffP1Z8zyQ3P4csDfT+2EV;Y9_yH3WfH+A6Jnt!OE&O9_A?S8j|#^09R^wh&8EWCRoL!A96AVdEYJ}!n=dmC1x6udim#72N^RpB-Ve}B{j7{V0yUf{q!?`AUku4Xg{Cn~- zo$TX;_;_tSz2T{;fUUU}z^fpldvLZNJTeQmv9-`3Ozrd z+GAs5{bsjCJ~hm`;x1V^**iF#?5-rLyYvqPV8(p)s-|X<=kw_Nr%ZbMPdNvpgVB2A zmg=JOnC86>{dqWKCv3!!$8R33i_a5(h~$wrUTm0ileaT>rLw1_;iLv-Zb=aF1r@wi z{N3Gcrp`B+WsTlIzvbS|@;xSw(yrWm7L*~BTHrtS`LAZmXo}N6<)gdAKlf6R^-GGn zD(h_x$hykQXYUA#UFyRS0k1~0Np-G6omiP=9D{CcK&M@-|hfq}6IXD=B!E_iU{f=R^Yqroc*nG)00gAzLa%N@#_+MK@ zqFd1i(6K-UpG_FUYXt#m%5N_0 zXz*LWbFo8#9^7Ptt_LP28fAbnQ(n6U+?c+Miy4T{vwy0__>OfJc{TT<=X2pARa+B0 zRXH#*4#GqpF>fslgXzvIK|8XJs=h;&FCtE3cYSF<^tC%+QPjk^zu?WAXOds*>+9dW zyGq@}=R99drIy>_q7NPp_D#n5`(|sx7HuW7_Qd(*1F*HsEeBO9Gm?{J%MX9q! z4nk9-qoUl~lBi{i3zzVK?!S&gqJkYXxF2B71Vv@ve^TPD#E!RsK)<-p^iR~X3Hq;Z zjnszG++B|Ni{5=ppz)t;+>R{04XrCvvT_GR{=>AHe4Etda$;EIcvmdl}nk(WAUZp~+fi$629{QK72|G#NA zO-gVc%=cCz1Ba=`{Pp|gUq#apF%1n3flW30k*skJz&0>$*=c-v5!gO{w0CjIcY}LG zO--$b5`gZ?O$flVzcH4@dQhn@izhfQylk3hazkO^PhJ5HWliD8kcZ652O4*A9vA(u zUtmHPq-laF8tUrO-F$p}o<0={gA4-7H5@`vf-Dw;T7rxWI==vk;|0ywx_cDt5F%1a zOA!*MAK0lKEE`W=rlq9`2?^=pLQiK@VV_*lz|yY_7&=q}NiMgq1;xKHR8v*O`JNF; z<30vH3)Ig)@ZT<(IFOecD0u*Pu|;o!HEbH4*44HQZtaG@ZGAyYp^km5bN z5+=jW0>4e>shela!Q{33r~nyh$FQ(Oo6j z2Qj_zs+v-okj?M2wo?LTmhWkmqrfftOm9`|s(c#dJTQmt8Z&sS!=xd=Ussnr-t{My z;9_@U_Cv&-ZjYbUw>>&=`lOc>Y1hMGL*+5$<<*MIZ&Pp$Q(9XUYl~^#Q`qB#=N1+e zEZ~u;08QWN{Xr_$3u0bw?&!#-{t3Q``+6#7FAq+F8iQ_H8C;fFc&V6nt80yf>Ur+W z&l_#+-QCDZs-VX(QLJWo-^@MmGAT)`1972DL-XY7_z#Ut$qr=jJNZ(B{%*>|pO%D9 z;sl+~cMixb`I$1eTtvJ}Yn}v`6stGeLty&%1g_|{cW^~wA~+ttrc2~pSOyI!YeUq;G%lAVJ7z@cS%Z)mCrbJ1t2t7yX2BDsbJpc_Iy82r`Kr+lWE% zeK#m)@(BG179&JeH09R<%NVP^*~c9lIm#B~9yppCy>twg<3sO@iPuP6zs?r&S3?T8n)hBa|-JirS@1XfhIujqzV1fWC*#7 zyy_8e5`8Iomf)>Sn1sL@$?Np5wY9GzEj)ifg}W@*1!TN|*386aMKv1w@BGhUp01<$ z)+II^r<=0vx@7rM9>UnBvy-^d>aB!OcD~Vs7wB8IcXUuodhva-mutULX~3s66cJ!w zfQ4dxG~B=3VJ$20g(*NB<3cc5@MA*?iOhS?;Rq{?CJkZFi5Lc%%u*6Ls(;gsT9w6z zvbLWd;Zic}92`t15MysXX9_%7|FUtRY^Z00p3s<6NW+M1{?&~2f!6z4xHP*2?!m>P zqNxtb$AD6qR&9RsPEC1vl6y3d``r=0%|>j3us(>i3E$%Tv{|uPYI4lH#p;za1|+39 z2?O`5UoLbpQ|4e^qF9YPgh1w(My-9pnft=yEym93&G9a=Y>eVX&)w$=zl~?7>0fJU z=Joyvl20{~)Utk+Bwtfx&RuWwy0oHPHc+m>i4FPlJ<(lKi_mY%8SIHRiOshJ{H7e8 z>l0>c57`*E`p9h^RYMi5Kkz=PzC)>D=weV&!Oq2nq`ZB(_VtwouIovNd4xE>)?&d^ zbFF6LA)xtU)VS4<};sze0cMf4nky``>hYO_#oP31t|`Lomt*IxF-FXfRz9iv2* zN{W(7qOnT`yc{uV-)kQq>5E8M?Fdx~8}KM?a?%Y?c7_UBKQeo@A6Tm;P@8Bnlu**X z!glY~eLcPX0VReTQa%(45pFjP^6SO;9d+&-D$7=5zevXqJHAI{!p9se&+)j$;MEaq zJ`507TTS-QHY!+(I#)v6YVvr%k3b+Uc3PJU1msiYP5i$#w^rBb*x5w)GhRH|Eyabr zYio|1e4?cG?-|70kiVW>m&1wuw@e!ROhAojmNrwo;w~_q7+6wL)EVbfSy?&O$Deq_ zDBM2Z7|s`)@Y`j9yc`vk{RN$28|y#BdZ>9W%cZO%kM%oFS+sm%s;%!4)ufyApL>$U6a+MW ztV1xOgLZ;x4W_f?C(H>or9$T7>Kx~3QJ!j7RQ;O-1%HtFH{ITkMnlIlzI?9ztg+zJ z$B!g@6ga6^P<)i3Hmd56<6mC`omk+69SIegP(mWs92)=WH5`L+?y-+5wOTsb`d zjpxO=;77OVBo0%4M~B2nxk0Dp}rLd1GT^ZS8m$ zd5-YHYM@T%$6W^Q31pyRpVRT%!=YGE4Q2fPz3?QDno8sx{UXO7z?ij_-yZ`A5W!e$ zC1{I;nQ)AU#+=ktl3uO`2GsL&)Y>JkvvOE(13+mjr^&0#^woBu^0J+xC5KAn2ewIq zn%veu64;0QTbCD>mdboYp)so@_A#h$qwLX(`aU;8Y|hAcTOfp66pCa7KAFYIpU4Bv z*ILZYBt^(?0iPq=<>UJ&ov(I6!7F^tKEIlB{}whu{RL~-c2#~3Z*0SJ;Mv13c^!h6 z^7ZY@(=p9tV!|$-FJpDI0pX7;R=aHcGmShfLnXqQpyE7I@vaMMupY)DX)_DUygI}I zz~y8DB9}O0$1l=d<0o&+nioCmt+3#K>+U~?H8o-7zdz#UJ_3Ys4v~0Vx#(;kG0v>) z`(M9)y?%84f3J&4WoToX>G!~DsLhhZ^+_=fn83=*bq;N7tHE}`yaaxy6Lj6k#eLgLQ91<(I?db}>F7I41h zX?rvC(Pvj5h#C$K4i6qYfa?0uPh)ckIj|+SJ|hkwWi=cTzPc<55r#|`TnbTlHXV7_ zB!FG~Km}J1tvj>$a3)_e(g>JBx$2EKn1ebp!42sb{7~>($B;BV*qmcv4+^j#5Xn83 z=*duSey{xwIF1lPS1&liH~+0cx}-2ydNq|gycYYiOaU1$GL`8RQSWlZyTK3LT0}&| z;Najyjq=K9*;2$cP9BpwaHbZ*GHeKtN)|~JqWQ{lxLW5x^%%UUVGySNIXm0DJ&tj` z`DvbJRsgg(0EJY~Uux8z6T0M}Hs~1HTEWB4-qGFdzVy}_Dzv9hpRTQ~IXO82jswVU z!_l>6AIeFM$B(zblwz_my4ss%K88F#D=YTVN^Nw*(8Si$Ae3JGx9G4rKsgd%mNsGh zZ#(|d7jH1bi)CmnZYO>a_!=drv2`f8WYN*lpvdO2#Pl1mer7Tql};cj7=whubK20Q zE$+Y|t0m*$3q+s7vSywknE9pv4;Pnvn+&U{svOIc)5FISktj-6V3K%n80zx~j=;iy zHAuyX!6Jk=z;iuCcYc*EdpNV_C?^r9nR~`dXxuFoZj|}-ULX3I63e#gYm+4;b36cM z{O1U}bAl%X5NB+al-htp0opIi_KEVf6VZtL1zbq`p8oLHn8o(NTn!C4mO-C%89Fh(g9o{CU5qz-? za%uk871_DDD~fSfW*URLGZ-(dMI$2cPTh%~WFTjwsRb5c2@d+?vH^d!ISjl?cSR2m z;bfUQ%Qlu+|(TF}9cG-?9R<(Y4 zHXn$|goH`CkJUbPP*lW9srdM@leHy+KSJsQCl600W)A+79Q;p6L~Myhx~MjgE#Tb4 z=u789t$dF@GFrjG-k!;NUEj#b`E^19*~@|0sXZKr zNAy8GKW0UzqZ~>m?DR{I<(i!8+q3*4I@o=(-?fh@ySGQJCFm^UskxUC5Xh4qFEaP|R+Dza{@ktyo|LKgf zAF!qtl9nL;@ZrNUq9}!L1z4E|cu0;>l!iu3G-h+F+zknjs9b9;y;R?4K9qs9sj7un z@F7>v71~^G=U`$CXb^SBog&_y^LTs5bRB7Z_r1qS+A1R%)4~;g_Tj`&&pw5~nEmw3 zEKEA*aOTYE8M&{pg0I8sRy|b)ZGssNuH*3OXVP)F0>=Lrdv6&~<+`N_V$3 zC>%j?pOOdjjV%8Om+W{(z{-|o?8DgwEP0wbJ6L&Mip3>9pwA?La{o=T! ztX4GPfML)?oPTqh(VdeCsHxv|7iK@Vrg?brSsbP4r4k+nH~>Ci@_=mhW}z|D_*)`8 zW?k5!hA&^+-q|K37u=RCsDLG%&^$>IGt>I3QMKdlHFLeI8C=9Mm#5Rg~^QOqWv^lBF_zo1vVwAxFf6InvyVDZ60q6|LR|_X>#oeQ9B{Q>C3Resd ze98O2*~IHVMDBcymTJm`@2-r7A+4=KhaN|B?zKftk1^#GG})r>(AR-dL)2}G%8-Eg z#U9%egnY2Ye1XtIa~C$u5D%UX1h`deiD<-ze(h?%gOl}j{>;y3A@jRukihvSNs|!OoeM-)=n){nGv-e;_u<_ru$Jtl0G^m zMX8`^7RnLAKB??{xh4%Hv2@K-v{zK%@IMwpe*>p0T-?rZt|@Uh%Lwt>SM@B zeQ`fBvxo4%gFsgCFyTfP=H6m+QN}xCX~#K@76Gw`X2ZhZUs68W2f5t(gt8r-*_*E z92yd8D0Wmo{l?QF0v>+-SYT}5DeCy8Ilu9k8T9&%pZZCvuvP_QN~fq_biL(4$;`Qt zODQtzb?Oa*jNlsy_xz@#KUoDMp0!+|+@Tl94OB#rjA0%6n|HZ{*0R;$ z$l-&o>6~&A6H9IYmSM|MD7r%M!JBuV)E+`cp6z4P`7PP)v@qD)lbT0{x1p z!ac&%?`qsWX4jrK^^S-c7r8OW&d&@`Gq}Lo);Yz`H!_G$4H{=EF@f7VYoaNzHP>2x zwlQ)0f-bNT)_S0$`>aOC#=?eRw^Q0H?-p)g=3(>E;_awlMi<|_wBeED(kRA?%;H>& z&3&lYa!;XTCXMJ-<#JB>?JWB5%pmPSn123ZM=EovgwW4)xaH7^v9JD$H3 zw(W+S=|MVSyBb(^*V|7M6BB!Rp!X<$DZCJrWoc~srab`OCMaJ(bDMn`O;^VlCX zYeVsfBF8gOR#tA@vTIx}&Bz||wMB109+aX{0BGn{@m!?G>l=>H7YPFFg=G-vwGkU5 z{ZLiBhI0ahG}gs&hSNjn;dsgZuT|S;(mpKKku|T=2Rs_&@D9{t#1 zUxU<58`@{&8Z5+lxDkwW@3meE^A{mTGO*z-u%$=}c_oB1Q z0v54W@~nqaJ|>|d=6ibMyz)YB7Zrm@Uyu0{brkzuCX_*CIXU##j2ILbVTR=mK+#sn zcxhqS2v=#|x-z3~tSWh}dki6Ovg|&7OSf&IH;B$h%L%`gx7+?C`-vA8C`V`TC zb6fe8(ecu2@l0E-6_6IR&9-^2-*^(Qprb>o25l8T=AzV<P2rrXH+}4I>>~2 z)`L&nhu&+uVL%@eUnXV;sZ=WmPK#YMDG{a_&=QmhjrJspVV;;>q2zS7fMIBRcG z6o%r=Xb4a3IpMHf9Bb$c_Ojxi~HxXjY6>54o#@?|}}QxcvK! zDU|ytgU^5z@K&6~1GEg$*SMxr95R7=EpfWV#+IcoioaN#)weLbFIUvk(gKoA)!<7rk;DMj z+lOoc+MptmitejVDLcakn5X#ydw)R*VEuKJ)xxofwuhCq}l zASKzkxoR@GL&L*kO9LUHp||NO8NV{pp%|*xk7vn6Zy~Ncr~9DY+`0CO;vsi^=B(cp z!t9KUmz8< z=7Nuc4Czmi9OJpBdACpJ7+p`}Vq>*UxapgGKu-~Nvq)-}=!)s#)-2FkhN>TKfarhe z&jFkSO_u+UE^&sRPos_G7h!j5wRRzZ5Xao@0v48>+d=hhsXRf_BWRGLhYGl@S z=y2Wa^CgQbF+TD>Y@%%Y{E>?sm~V53Hlx>?Na>hQo8MrBe091JuP@$nNaA4gYcDd2 z%eLKTWxRY7FrMYF)LlN)Y3M$Y;_baTwY8#*jIBeutxL-b8*F?fMr^n4Dz^8Akr1?s zMN8m0>|xm(i3TSVc^pzw`4?&y%mf7bp6 zqn9GVxT^cj5G(`htj6KV=N}3E!V6q23FxpYME=}XHrYI7*fa2?h{dWe&QG8fzHe#y zA?Bq|94g2GAhDD&0hE@JapSpPWq-)o`4-@XpmJOEd;XdMS>14IRcTq-Y!_b@R^=^{ zm0R9N*N=D$?9Al@q-6A}T|SA#Qqx5l{cInT>s{(jA;lP~FyJ)a0huo`X5QtK^Ds+i z@Fa8u*wBKHtOk zyY@O#j;8~_0?LQn4Cp@8_l*qvej26TschHp<$-c7r4CRS2-e>f@T2tm>w_9V@_}-p zYO#$fy7AA2AAllraB#@DP_e8%l%&T$r3rafUTpA+7%OO6w2knojC0micH+=70OKCO zg~_tJ-1nB!W9xFq<#j~%)_21zZ&5YSH80aF6(g1$qBmU+F#bN-?;rIkyJa0}8~~tw z8ZKB*>D0qMMBob{-XhY!-=b?rE(vT}BRYPfaoMSF;$%UhAvN90 zlVB`w3daHZI9;fYQkpfcz6HM2rcs;FizBi+vnwk{14?R9Fqgye7cQIC0VNBnvP#F1 z1OZ#!M~`k^3AmyqRAmUs$os);Rnw_aAi~`c{5L-Y@S@3CC5|HdZ-PkLWL>1rXw%YpglT6)w7Cpk$w9g)%VL%+UaPafr_#)AjkpsFQFUsaWc z^Q1s91#$PjQA5kx&~9_g)Fj|HbE?Yr*%m`cLl5e2!0ShfhZ$kvP2v0jP(9}r}0NW#hJ>zlS9Qr+gnz!|e!OX$1{+b@# zYK%gg+U>^1#yDZjAK=$MadZ43M}QGczgcd(wiQCLHNAg1OTl$bqkGv>FIA$)#oojk z!}t<=12R%nk5}Xi?)DmgOn-m>Fv(*ZJ%Bw^Ea{Q*IX}!6I&4La z+Ns|H>Fxd>Q4QR^{~y$p{qOnKzwl>Pi8iQklSL3(wF-;W!}Vk{8Sh1`%$dx@Y&ylqZhCux8&{uDnoEK~LdQp)oBtomI0X0pk=+O{hNo#}F_2W9HLXWqsBO2jTuJ85d)kZ&`tc)w~L?cj+ zUf2e^r9l4IKQO?IaC%(t%T=N5knX0wTJb8BR8iBljNN}G;Yv+Vh{?i3LRLyK^F}#| z5%;h0Tt?lgB9>2rK-`gvfqbJvd}wG0L2K1vHV1`~dZUhEmUx{VLzh&*&@k>_MCu#< z_${a;HF?H`i4S1d=EYKerMB3bb2_A6D(UZs9hyHWJRqaYKwaqegrN)n+ z&Mi@_{@hCac-h;AKx}sO3Ax)nw6855A2Ci}(k17A%(xi$!)H|9TG|03PSpiW^+%+1 z+BSnDy6&&`x7Bbae=DDd9dx!@pmp5rsy2vRRYeHYHsyfJCF9h;WNQk_p{yv6*X8X~ zHSTINXW(aW1`X>C*ss_4We})F7qJrO3aWE!Y^JU7yY9(W)3qrFURSo1A?G*E%J)FS z(iWMo{`w}l=fcWM5jWA(weMxII<&$}YWSApa$6QHZ$0%+9_=G@|GJmv{=;AE9)(*b zPZQdmQpu4n5R=}Za63K9PY86c5zcA7Md`Aok>Hto6u9%H5*{V0hiHP>j} z($&Il=Bn9fMouRJ#uye>*46RyTh3Ghc(*ajJAi^-v!Ux6D=|}n7Rs6XHn9M3pCOHR zV&me*J!7_}_US@-3<~v=0q8Mq2a*_Ers9~r}^?y8mz zuR~f7fUN*TF`bE}NtJfKvt~en4_{}yZkF@dNjU)zO>}f|aOi^uaBE%ZPR4iOc$L=5 z6#HX#r#LjSZV-kvD%rfBh<3s#&}^&|#ZHBqSNT+M*7jx6z-|_$$T>N+3xSV-Ok;b% zIseKbASW{YC|J85hrvh58-P+O7sQCnek?$qs%R}By zY32NTF6m~C-`9E%`_jt=uiqJCdVUStfPP0@g*VuOMFj?qkoDJQs2PvEj_fwOTX?Yc z*Y*_6ta}2X&|XiaT;UP4l+nsvmiMbGp5R}43X=hQQ@RJF%eUUHka@UHcRHBoUph0!9=T!?V`73T|VSh5A z-`K%w^0e(4gib%}|w z8p+q0kdtO_VPN7(-W5Fi54j1Zd*tVOEtivcRUaa=}bdt9BCA=PIOkYf4i1CIPf90!um-tlbKG9eX_r-|{ z-%E;=-u5p@x(rwO3~NK+Yr)T#wtX9wx_$Qft0Zn`8JjO&jSp;cp*LFpcv-cFsTzgU z7jsth6aR@I%W6g#;o6&4JuPoSEfH1QT;U87p@p9(5ywQ&-RT~p@$OSD%4z1z3@{_v zR$Sv(er~JdUQ|EPu-9Z<<701XY-}}F8vGJ5$|5<=!Ec!~20m?&_5mNBxYZ;){GCew z+m)JV{cLiQZA{s{s3*9rk(8UTLFZxALdCl7G zAAOGtG$?%VbTn4v!uL`kli2jE0zFFgX z_<|E2ZF2xRzn+ec_wU|qUnrY?7jr4pE(1~h<|~1zqJwXcFm~vD1h@5e|CqavtyO~n zW0gB&hWB+03H8Ys6i&E97B&e)glwKfpt_wuLfZAH=<&-8(=dZ~uM;Ukbi?tisEL#h z=^EJsSxVs_D*~cQr-}?(R$Ps~Efw#y=pJ&PP2O8_zc^;c@;;h*+f!4+w@dp?P~}i@ zvGTN#sI3fLG&)#~TYUrKAo@{Nx|2&+Uk18YCK8=@1e{l<2sK=+7Ps2mWIfUGcMnct z*+s*WJ**I@xIJkfrr#f3M0PB&IKx9cEjU|4PB+V*lCQzpjY-P?P(wo{o|9TgD2YQn zTaQNfECrhh^L+Tw(xH{h=OP@d!HjzmIsWd5>qkC)gXkx?rV<2gdSw3KUx1rqbG*Fg z!l-g7mV?7L6*AJV<_eqlro)vm`V^!xV*nsjcGO**ZGO>pMN_7m&HpmR3f{GN?d99p zRKjR0pd5iwc@9VHF(3X-^v(JiOeDWq+Lyo;^7Ha`LJ1bQE_&SuJ~T;h=g)-us_jmn ziqMyA0%eL2??$Jlz{JDgXf?oU=R@dDS9fMc#cmorswAysWFB8epT<2M?LL1w6Rk8{ zm@$O96qS$Rb!~e@dxHEw-sma)Q_^<0R$ZiMZo=*aTH6+L(hsOn6jODs(A!b*Rf2fY zR??~3X$5Z-{iq{~UI9?{Q}_75h5W3n<|!;+TiJ7^xZOrkeSPb>?RRyz#AT71Qz^ov zA|u~M=Zjs~v?E32&?+3)p0Ecl%th1)3R@1}ck2^e;MC%|@lCBMF5Y}wdv2ETq>gh{ zw(z{pc{)0w^uvgPt?Kk$D;aau57h};s+;!&QpxuF9BpkSG=z5#cY0LB%yT0(JLfW5 zOHL1rp*7JP4)aan%fcFoQS2#YJg)t6usx9gIgVznA2(0?d?>$B)Gz79C`M33h#tsK zx4UaHIg`=4m{b~owCyZ#Ms8qTiZ9i#{F*0B1adi2!6fgfU6)u3tLMUvkfT%mOm<{y zf7CG|{4-1XMnQGZ$%aKA`$5qtCUHO5$R>P8O`N*-OY6y2H|hf}to4#R6z4cZ-9S~= zVc`=^q2uVn0kVx;3yGhi-O17SK1UxI)v2m*T2gU=!nyzG6{|+U;ZOjeEZoRV&uV_* zknzrDRZX#ODJCzpHm|%dxIno?PE4NC^h!d#>(%yGLh!cEk`q-Kpf%mQf@oC;9=lC< zwwytFnq6viG=O-O&sNp79YRoeOTs&u@{FlQ8>hBHrrUGmF%|rJ0QY71>%e#;1#+xi zyp?&jfli>?=#1QrVssrP&92xB)8bM?B^|48+LaGo)9%Z9$jwjw=prlGT_R@B>g!(H zA$a8}2N%b=$vp6O0h3c%=?dNY%F4^UfWLuORC`{d7J9s-bKJI#NqQnf__V!{2 zkK}9GgxQkuCGfVdXmVm&gmM#CFI6{Q_(#7{$s56MAyR~U*mL> zpA5LqP%8eU3+uvqbto~*V1`RZ?zZp7;MmV$nViZql=7>N=X25asF+9J?PDZt(X$h= zfiO4NWDw+i=KL}9pHlEzPCUDlI^Oe%g_W4$L+taAs^ zX+khLl~>2$p`K|;a)i(15dg1rx}^=+_AO?S=Odp^@5SfsD! z4M~&e@e5PkZZ>;!HgH#=oSqdcP(`EpK2DQbYz$iqd|w5n1}o8O_{ru?NE9i#YJ5W& zgG{g}Kfm*|m;7qu`v;&=%n}NG{Q6Lc)2XSKJdzcpBdt6G#(eP#MZ`6l#KMOq4-w}k zv~s0dk(xf*%D~p;tF5gXI}3}UmX8rV;@lho0*l7eeH@DRAE%~)4;lx&SShuc+L)*n zg5Pz9fO-RWEt=(n_bEC(L??x$$KudH=;~kY&S9G78gZGm5++zi^29@253O$7a+4jKOX3w`iuJv&JUSv>! z$lsxs#`uHNKIfuWyMO;aQF?kh6(~{5DxMUVlz^fIu`0ot4Zcc{JJ~<~=N(um_+@^X zh~MfvxCGT^wGb}Yf6T&P{xa&~%rX37!ENG5SrVXR4i62LwWil+2*Jn&w=M*;4)^xf zzXOc>K4_(1rrZI%?xb4@BS4>u)Dj_dYSA~pC?mrc0{~bLtcQ+{C3~5*dUaj^w2>vU zb__PVIZMg{MgS=-^K6r1XS-_7e|d0U|B>QOaO7}AF(-ieEgc62y0SYm;2{cx+3<6T zIUX-!_WO7C$V21;5Hxqc10E%f1Z$mC5JF)ng$SD`qhMe1O?na z##E$9KzNy(o2!GFu2a1P9)IBaGps!b;cG}{q5a2SI!H>vGRc!j zDdq0gcWFB^Ev*jjRG9K<*&{`gYaHq4(|*1f`d&e8MfFhW$rJKGs1enn zu4uR0Jq2m#hFsUPHHBLMo&rt>LUHiXBT@z-Xi@aybO(ZKAgic>LtX9BqaQ6;Gh()} zAbWy!e$ct$cEV331`>o1;7p>HF8x!9$`uIZ5gRrket1W-6_Iri@oY4()+Wyw)LGCb zs61N>INo%ENa6O)(-!YYA0Hn$ zsy7J;s^%#~hV!+glw{j`C$S6w%>k3h69@)y7POfVM8v|%rohTK9GNZB3yHOIR16Z0 zhY!;|dc_Ll|2iChgaZ>Cz!ds5K)5UpBUE?2avSnY{}DhZArQckK+ET+c%WU|J8(e^ zU})&J@2-w)g2;IA#?70aAW>S*+}+&;bee1|f?)s*m!V+U{wdjB4+NdXFkH}CE2j^& z)&k>KOrEI9!*2>i-)FbP_0bX#zT+XjC&*F$<(X$kJTjEEi&|+}DzQ6v?!YwU;~?Jj zeH18tUhoq^zU?~9SI`1W2D;EA!F6S6WtBA#NH3tM?#MTku1{g?ScW|(7^_&^JU+{W$ba(TY^%Jw6FDo<4m_%Pz4oShLDyV#gsu#irv&F*Ad}3TgKwL)hA3gMhfa-30*baQJ_LdP1uncqd?KOeR&cwRz0^gh%iSgtU!XG+lMN3J#<#tM3k^5G zb$$(a_fjjHqDB57+<4r|P|_-0b88Ie!&nNtZAkAv_@J7dSTIF}-DN>yw+f z&zFqJaQuQONP`kQ)xx%OW{z(562fg*@|NL!%tN4!E*>+;P=*}&1e6Z;~*Nh(Z3(7gLCj>Wc zz{-Kqz~;Q&V9{pQ1b8Nqz0e`JHV5HWR#u8u-XnyBEjvwUpx|j}+TN2)(-mI$@dGH5 z(d8Evcf8Mq%{-Al2t1RZ&N2qCDvr^<0Vk*J@G4e}B4H{te?edVwBrsc5;D3EANoy+ zn|3A%6lP>l!*;Y|2%>^O4G7}y6vZP@+-+bbt^!}^MvR88M9tvH2slv$+1WACjrH6b zmf%qIamH@IVwveGQglzZ?fQy+dIIAXXqP}AKQTDitTkQlmQYo+p*|B+d^7$^KL-zw zBM39%Zs~mn12;xga3v&Jq{@p)7k_e5T1GUJ6_$T4rh^;*4iB-k1Qiy^yHg1G&WFUG zPjt)6#6omx5gOz-BE{iy+r3+Z*zdjTs0+;Oz4|ant&Ro0f4{FR-d7p#7$XGL5W=Zj zZj+!amG7=_Ut5lb3;Mh5yN^%(ldfh}%%F+R;{5=ZC#V&U4{%DQ57Y|Iv9vY5iX!Mfl}72c-N= zIK%_wL&Y60FZ?SeQyS9B{*|>8>mKPm<%){lH#`hq3?iPZ;C^tPlac;lOp^sP_P-)p zHZ&0jr0!3h+~5Nq%>iZwKFi_AGl))O2md1Uyc-j*4%=B0;L=IC?T84j`R_ki6$39J znTT8I+qd(8)x&9UDr?X11b-xun3MJ|;9i```s*h9SXz3+T7U040h_s%RW*Dzs1Xq3 zqA$8K7V1bXbsWZi24S$cBuR-%8vs{rQBwVl*!wpAzJ>%6Bl)u=vU&vY+5` zVBqva#dSMt3JM#C%LeExd^ufRT^NRF3v|lEJ3v0$m~)-{j3)u)mMrjYEBy5qi~aeL zs%|nG79gBZ1-5h4(z3IiiF~0=P^mNII=+2_m&0NY?&CJ>tSiL^;3QO+!`xHnSO2K} zNJAsA&AydOsTfiSSx-Ls$me|egga!6iO6l^lPgH!S8a&N|9Z~cixITVPuTIVTc=Na;$jr{7$$Y5ku1JMZM{Zf{ z$;h@7!QK3I9hx1mq$0lkpW`y2MuiQ7#&dWVz&>x>oc_W=92bT^Z-`AF1jqfqd;$Lt4hSuM2JSK9>AIotWf|a_= zc_K{^(~w5{b{h=e?>?p77%wr4K#zi(Ipn)aNFT*4?lGkWh-f4)w7TG7Ahf&);lf+T zeX#El#5i9?U}OJ(9?D*w;Ns-ioU@0W>?{+fV}RqhP8BKj%ZU@5n|DjpWmJ zPkVdIqJs6Z(f;c%Q78xFSR`~w&z+o-MSn+DH8jWVRza(il?4_141_-rR!7I2`$B+9 zDc2riM=-%94;SZWo5{r2ui+o|45wfNanS=byiGrO?FVv~pi&CKlme6UyUw1T!Ve$b z=72mjbt&v$4(LJ1`s08+tAWX9K@Ak=m)^cjfg^Z2Pi1MLdXH-WMRt_Hd^Y53vY16z)ZOnN7oOX!`zP9kR*J%xuIn5$~@UTkv~> zp|u87k=wzBQjUV8BEO0+uvom8q~LNviNODTE z3foH}s%wyd(aT3d^mI!q=S3#MQ^m?-KPP?t9ELW*(nz*2=v=iHcx6-}rwkUy*qM}D zkINtxtih*CV6&7(tkE_AIVV10XqjOQj>ciu+etho$_|0Y9*E?e75T!5j&JjXEX|G-^zu1S%3f_mM<=RVhb4=IzH{jx)6VAZD<}~`rDDY8K zdK$nIy05ihfp8mMHj_4pDU?IZU61MyIAyBq+lig}Kr zU-r&@VzPdFm<_f~IF#UR1be@#v#u(jRFH{=PjUWH{0AnX9@M?RO@Axu`x}$1(u(&` zO*E2{BcrI>Kf6VlMk7nmH)UKDB}llZRSeX_*VB)rp*335JHx+|p;UBzDkvlaq9?T< zJu>OR;pXN>Yuc++UcN5eP;^#}ku1eIMpgS(C>$4qxt8qb9CkxMx?NL30E2l9N^UO; z$b6oHGSb3=E3je4{z^tdiwc=w7VTtoOxGg_nHn5FR_j>Mt->}j`($eKEy;Ymm*+WH=m>RZ+WH6Q{ewp<#Kf3rLVhd+Vz58v}XTy)lGBt$Bz|5(qbVCE*$U_g=J))BatZ| zXejr)h>O>uF@-UUR@P^_3Vp6Ar`mpAh6J`aMoz!I=F^ArDNlBq*k=~lR1ev069+d_ z1AN4M4@rediHTdAfwKH+yiy1Y6Xp!#a<~!Y0)f3?Kg07eW)Jf43eCO|-jiGZ{k#zRcU@GE`|{8mX2{75h*>9HQFi9H5&uKkkDfEWzoOE6e!~Q zi|#yO9@+xyGd_Ga#7Ae!HpKgxT=CdfI{AM>>}`tNV}|JeM`13r)&B4Rudkt*3O<=0Z*J`?>1 zwC5~mU|;~RAov+3?SF!i^&xmE0NI}0eg>)h9e2L?a{Rj)NXQWiw^t}R58hh)-oq2n z`5g7hoX#)#QI<`=e`=!@dRV-+B;7WW^KiilG5Y;`z197~rO5IMi%@y13;h0u2ysU>fGt*Zqg@rI3= z84k9kg@r+WSQrM2RBt>#OoBja0M?;fVMiSUcxV#8^-~+0T9_gsYXK5AB~1R>k3r5i zIF6bJhPx)MrzE7Lglw9@f7n zcY#*XkVA-7CFRcD%pS6Barc(&)C}tk&17&a3G=jOW@c(K22v)z6x7kxwON&$2GJoj z`>;M4y{B^*p_Z*jFEHnUISgUOa!sewo9dh(!^c?Uu zm7AWDV$?K`GnHGOE(Iem#DwE6hG=`RGDXo67v9Y(q>`6U-4Q(<{FYKy=W!{e7gPsg zRb`4f#$HFgM(8PGk^9nV+oX1qmugVMjdYg-83R2BZKs%%%8t06yaqvat>BjcW-%Vq zo3#6G7H>q}H=Z85fDvE>g!b7YX|0LE{bogv+{6yedO>x4o>^kiv)iC{M+A;(<>#8z zZFcv4ufi3|kVXT(7Ll_o~{vBatV*=R)`}eu1 z9G{i7qrZOx#XfR{L+5iCHy=dC1N%mOAJQ*jI&Xs}mQA-hz5|DsK`a$aN$}_7`~hf7 zi;D{s5QbKffL$8N?=msZxrKPY6?sWX$#x~I(7pozA{BekD-IXUVq-aNZ4%LKtJf}b zB5HEq|2?>>UMrK-z8rkM=I zDfk8TTBq1XX;0Ygn%B$i=s&-vw)EmroB389wa9qvR%+IPJjO*qf>Nc(l1Bbz z_+i>XXMaWm8%0OY`RpyGwD=O`N5SzPhnZ&F9G5PsEXherJZwJ~c&uZ2%daB$4_p2R zEjgD@efp~Xmt3Kea^%eO3}XjJ$CV#-p2`rg%O$rD+xUF8KBi2t9`R{w>O;-j6c-7sjSM5@xg4?#kF~5)^%bJ8 zb%vVCqKR!oMVU7SpWyJ->L>{ou**{4%ojx?CnY7VK@q1J^Tj%*;fd#q$$4#+VgNlT z8Fwi=GoK=vtJEz@-Ms79dT9(iar8fn^3t+gF_n(ad7*P>t`+N*p9EmUgc|!~0f{rk zqzj`tIBoImztYan(gt)7pDfMC1yYotFcCz#!zdz{>EpKBGVnI`SuEwo+2eE5T@~$N z)wI_GRE~4Q_jnwIpcn)ST6)PIfSetLy^lFI)uo+9Xs_LNNt>84WnMI~&rA}ROVgw< zPUhLu08}@4YE)CVFXQk>7o+qZDVnxW|6K1qLI1ik2Km6#n zxyqB}^NDdCNfiab)72oZ9wIeUbB{!Z(pd90@DG{dZI}+L|1*r*iB&gN9DKlF-&7f9 zjx2(3I;{XDB|?b4*TzuDkMZv&(U{w4Yk5#|Y-grp z*s5QEOg0ssrs6bVbvUqK^giYK z6*WpO>JeX@vKQGqj+y}OmI*c5xG~fZJ`Y}6jn_)4q$+(@+6W(WE!~VXyV&|l+jE|? z!zI}hxH2b(V9@7}%5X*hRiG`;5y=9<9Npp_m}w|(NejDvdn8&d1`${4b5T6Nv# zkDL|OkW4dhm2T{v@9BuRi@f@^?RnpX&30+T%kY@7f<&{w?55;I$sd4bvLljO3I~I( zn6A0}ScLdE>K&pma`Qpp3UHWWKW6HFMDs>-E&ceBBI3@!8~oPAycz)_CgJ1#Ku9g- zeKd4kO<)Xb$nt&4*B1kwu+>aK2*oMpU_R{*6`UsrN|;(k`V1PK68l3?AO(Bav&C{sLp?n&rBPM%jhQ$%|Om=7<6kwaTV*9Dz|MFfA* zgb2*YS+}!L1+y+EzOSuK%_rHO>Hg|qQw{J@LIe_TBq8bnm)A zKyPRibqO{zIIPXJ0iT87^O3ZOfl6g2z(4=s>cj) z@Z8kUQsH9R^>p5xhZGoh?w)X+2*cnMm%~x9(`>NBV2kt>?ie)Y{m>e~PFyJBNQq#$ zqBo9aI$kZx=Yf9v4!P0v-O;|IuMyJni*eW@v7#>5FwIT(0szJdV$9f?VS_miex&@k z1F2URUf-mMZwZT?=@*{AeP@=)1PdE`Lip;GdjfG~z0Zg=*Kjer?C_Fr&5+SIJziUy zxufw5TkjCp6ISnS3@v?BN|}}@*28j{X)tTaKYz6E*XwQChB<8r-g3r*(bfxxuLP@{V_`> zo^*@dM-M26tV~|?Cl#7`+?yXkrUpuVLE_hY83A97KWcI%ocyLrTXhpg5~xI)DPB#nZ7y*f}$si(=X(eCn{2 zJJ{{KxSC;h16w#K&C5}x{{<|;j)gZXDQfoNnnq>!z~R@?R?039zVA^Q14!QV!H!~~ zgk~e)dRmukKb*dN(&qurs+H-BgpCxw5eeI7iW%Yc@Ir6vMKDVF4_@uQ&n+^*oeJJT z<>eTz1>d@GB6GRvrD^t0g}YRly2r~`@VQEcY8%F`QEzzuhQ|r)H>LO^ltVAP+SqXi zDGq250Zf$Qj;%D}2k)==^+wm}nAcHK`5lh_c_o9~(*TT0{R@9;C7&iZD2(YA;Pzd1_78wL-~`$Hd(f>E z{0!U3)zufV3V5Cl<`uY4@d+ySuxD#LEvMK7~e_vu&?w)m;y?s+=t7-VzcJ zKnN|gFC*j^L;*$ZD8!(7ga?e+Z~+mklCXm6ca9b+h+i4!tt>59mzTwFuT50)h=@$4 ztVaDt!$~Eg+>U;k1YBy7M5jWEWZiHg0}u3mY3)1NwmhiV9B9KS>H?OV)j-&Yj{jpTp?2<5FJzJcC|#SMI>}nTZXI z@~~-TN;KpFstYNu3)U#JLcrOpBZ0zhr@AeGOOpazV_GQvkkM+?P^*V>#tH*EX?_;!rV zt3Ce7iZ2;U;QQ=y|F(Whgm+7$7Qw%uz&uAF%-C=v95`8Y3uT-cpgi=i*t;!^fM-**uYSf0dL-29W zAB6!Vgx+$Jv$==*o6$ASqf6Wn6o-M!HH-f2jht?~>SX0=WLVTkZ3LnYf6u=_ZY=Z8S5e*vZ+L+`;ls z=W@eJ_50Wy=r9LL`$Px=*!fHfv;ngQmKk)PVU*XBfeoS0Qi$V-iHp+__9EbwA-5-l zyyy6&ka&o>+c6oQLh9Pmmv0Gd)>2Q^&D-E$VD-Zh6Zl;+V{N_$$FBmffh=}U8qf9i zz6gOXGcBjArV`$zceeu(Ha;oe+E~|U%;-eO+U@)aphs{HjYydkQW`bAQCHAQj2PkZ z)Pmki*%DP`R-2B_*A_Pwj-!BjR8!+J_SnGM~GR)HR^i zIy6S|=`m&-3Yf8zA&ky^i%ICGg?#U&ekuC529D|n{N>f!`sf-ArD*jgnOe)iI2uK; zD-4F@!s=fg;BN2CIKXfzVx~2J{pMVo@aD}U{!~y1*<6Z^`{JVzo0J3xY!q0j`xmgR zF`kl&v$2H3i)}dVY8t1(74mn;EVs*`R%K(}6{v_=I;_A`^ zJ!a~_&ngdGw^p*R5U+#HjrgGEU~1m3KTB@^T~;~<8sdpC1v8RjF%$P6z>oL(i`xFH z?die6g*rxGos&+YCmtOXWZltL4?bB5=l`GT-a8!Y{{I_SWOd3a5wcgACn2);7A3Ox z%nsQr5!suF5EshIOtx%7_9jtgSvig0^St`hb$!0a@1OgR`?&AB<2tJ2Fs{7cukn07 zAImK8<-um>ffZ>YTM4dmI;Y;*+B97Qj*{TNakw3p+ck^H_>v}Bb%9Z%1B7`pHQrX- zE-NBIncu;i+%XiVIT>k=uetZ&7UDKIk4uFQn9L1xuYi0v2c+jF2!n| z>=)fX+pvEL9oRJMcPjGJ%D~{NrL~mO#8CMA*B>9sYpi<-4opmVg1y(=<*NgDaPYX< zK+!rpaKaytxKaQpEV(1Oot+qQh@Y%ZjdLzuP_T79^_5O$897SMV4BCHzyiX-l-FiP zXi=WRj2B!#l&7Y?f5i+pq{s%^7DEomFoEU>hbWWY53mgAO$-dLgX-CZe1|F>xsP%0 zNjq4zOP~G8FQFbLZE`wf1^f=EH7HW&oa}x5AMps=ZhlDRHV&LNYAyFW^-W`V1&xfA zKr*4|iZPg;S0+bDnz|}oj=KaXJLPYb{r@6X!v7lgYzhU&2lc=?q@D_WV_F@g%fi6$ z5&(UWtG#-0vXfYu)2Ob-}@m1dVsDvC4q5m zbIE`No(jb0 z3(Kot1T42}S5rS8Xnocch|TtQ(CAE7)T?zZ5RSZpF0rcb{d0={|IyJD^3A*@J8geE zn4qA)w(Lu{CII82fw3{L>3{pHl6i5S2@}YUiIsV|x$vW)Te`n1vB8LlsjJf%pL=?g zQFCMue(@h9xDK!0@_MZu?;+eB0- z1@fqXR{|5yb%=CJKKDiO_6w2jZ<#gc-V6g>!H(=#jYf}6-}EDtn89k5D}|t|OPlee zJ-mSwTrUph6JI`qYqIBGQ`JGmZr3vkXc`*XV!ppm&)EHOY;Ixx?22Rb{T1_uHJ z{7}VQH3>Fp?SVLl4g)(`_ z%`?qL@i6?leHF5tyTg}2;x$=nDyOR22h^#Xb>LOmhy5l#^PFgnI6H07V52ndjl6x_ zDBaM9{1mGW?+%0mFwmA5j_H>qasOp4xgg#1Q15{=JFi=@u#h}c!44kN8^-v=mAKuJ z(b2fH*h-LJqt<3mVrIHz2Uu3W1A*TvqE;Nk8|;%tLiDIOVlpx|9-k@TuRjVR_FhOi z+oXMlJoV042s6p>IX35JT7_94F@~IKH>fV4PPU``atQhq%8FH@2l&pPKQDDgw_ZX> zHG}#{h)4=(828;yjnyehc6;du) zJg+BPxYI0b4A(kVf2~d~P{RJ9jck*g?bt-?4kEy2m);gDAtE@nKwp!uX`c zE+ZO;<`q{pDUWyL1|7D>qbn@eQR=3>r&n&iQpTJcYV)MFv7=zq=0dsZxw!lQtfhVh zDR@^$r!%(l?c41uJ9Y%Plq&wCSQ!8S)2H!@k;8)^y0-Do;le z_^aK~+A1Xpj*s90dqZd^(f0L=-)L@`%0_&LdTT7zqkkksrbVrc8{VNo&+|)0k!}In zR5lQP8vXov@8RS*d;>PI5x`Hib?Lo7C)|T}&f?xvixZwJqR&puP3D9p@+t_^nSxEf726DiKVm+a&+J*r{7FXU-Pw<&X zz&GI*BmwOK>8hU1h=@(ZvY2%)-RxvsvmLu9xQ3~k@dBsJW@@6!$GdT) z$4CR5t_*#4@5;)CoMtG$^TbQ+oJ%R{b#L@P17tG`!9M3MKL4M3VDPxrV!BsQ0=A~j z)E^*L1Cwv5-TBXfBU|`^qXkkG9!cE@I$qRyJ z%5+ggx4FfzrO*0oLqXOxFbof+>{Or2U_C`D-$6@D3o<@UiAf4vyl2)#2D<&cuai4Q z&-K3mqIWX+!Y8GC&VAMZlS>8too>)=fMQud4JrLmp&4?B_+`ZA1{G|TM(^_ zs3FTz`;esugCP5cV;E&tdi48Cc~!=7BWxEXE<)_3`-!b8qW4_(`7#?Yt#u0syw?@A zJ7N3gV@P5J3rU>@pD^&v%*~m0m7^b48q7!?J@;2N9dWzi;{}W3=AVHHaMb_b%!xhd z90H2LFB7;HYPnXZq~4z#+PXVBG^grSI~s$2c%xd$N_O#eQp~y18$e|A($Pt|i#D|U z=Tz{*cRobN1-Du`I5=2YY1g?ufaNQE90%%>hRVu4X5KYQdZxIDVRQ}jZ>g*%mWwA= z4@@Wk%<+TDJTo=9CKrJUk?&-LMi5~1OaFcH{7=2tg3BQg?4vWlJZ!S-z#9JVwzk(f zIC4whLWLs+*2ud+)dxQV(P<|W%X%p#7x(pvPe8;k2jgiVFlqP$Dwmeo)6)Y9GwGUW zV}_-;T?j%#=YpO9ctDQ{s-S^z zO?IV6k8Zk@`co`Cq49mO1>7i7%ype-XwS05q97Uh#^IrEi`2x#5ViKtBt&REO@75H zR?^40qD0}|y@;I%0dJoFQ8fj=aJC%9AA$62*M5lqm&;%Ub(FT6? zpzM=oEM@*>HY>1?nj1af9J_lBuP=8vBS=#sU{RdmE}ykgNr&xtz5k zkB|5SV_8x{CT)%)pPK546QdIIFAamGQJ1txoH-GF!v zkkkk0;ay8PxM56-)xR-a7e;j^=!aQhZ()I=_yKV;O(7VE<-hs*)h2!HVs$H4v?Fm( z5RiMn{R50XCFL1~43q8V7U~bQh0Lqc7||Vrjn_KYZZa;i5Xi9PfY4iHKqM=cZZ`LF zLKbrT3*1t~yk?1eZ@xE%=Dcc3oI91Fd4iV^!7^WMbXEQZ1TPIRYEcYxT)iLLyNDAI zu#&CJ>luS$*2TXSCxXhQ)se#_VzGH9^;L(J`SYi9rF2(2HrJyu!0vRaLO}EfHMzVXjfnmICHY<}!t5N_n8;*uletus;)bk}K61oQe`*-4 z`U)+O`Ev?`y>cB|?-6ZZJF(<(W-jv0mjY;$V2;9sa(!E>Oble)sQdO`v%Dmk7Kf&S z&GF$5aVu>%sy0&EGQBM&Vp%-H3zv(=C-@SOCsbBcBu{z}W?8rQUtu45{dxlxKsO|I&4S)a2-2G|9u zTU2X;8tG1oiSEY@Oh}e}l0AAsd0SMTdT3D4)t0!$9s^gE&X*W8U?+btzf~<5odsT? zD`fatR}VDOF39Ga48kqbK6UtVlG%<${_jB^zmYY`YR4*lkpFB z%#@nOjrvs3S)ZCkWD=ffW*Y8HTm@&Bm7VnkHS{2K-e!dfA-7%MG4>} zvI02bv7PNBh<`gc=O=WcNE5?*`9(!jwGXfF%0JJ8bW)gmMH>i!4#4pJJJ^IL*IAqR z1dLPolHx0l4&A$+sXHrg*sgBEN#0rVA&SOf7dwoN7+S-z_wSsbog1j06WLOf?8%Xj zao?B%xtIBDyU`&o#_(BF9sEcd6r*-oZsV)Vm`0t4phD1j_9EF>T9xiz=rgC7Gw3i% zhb(Qoh_^5qvuIKz!APhS?4Ue`{i;wlPj#O1lNN{fKSPjj-1yN;$JTlG z>s{1{qOY&0Z6AlkF|?gJXHG>Zq;YLnDu%J2=;4k$ON6?0UaR!x#DX^EmMw{%E-FL0 z>=Skl^|zoSO5kcenR>csEz&S7jv*~$w;^c%-wO-EV>m=zjxnu)R|;b;NQ{mYzI>2U zkVtc?op>yGN#BF1hB0ai7W@Oy=-fsE5!WmZo|?{0xW_8q*VjL%lTW4KjHil2-9PLe zfH4Q(B&aW+BReK2k~+{1I--1>9)vv?DH^paxPVAXTm0-vVo`{~xm%>Mr}vJ6l_b2l zup3#v0RlFIj$wk!BnMajh|p2T4%DJ$$;GjIQ280L-$y<^M(v~gA@^krd?g__{>b@Z zq$f4AjFKwxE3q3e_kbYmQ=c@WM!fDKyo~iH4S~F$6OcC~PP20Pt0~sxzOKFM51q<0 z4UbDmxOAUX_2*lrJ1B~v;6j29-bB^|d7{r!T=p_&E!b^BpX7)3UJk{Yd{@;ZX8d5p8%YjJ@b?g}tNJbz@86ySHj)oN=sOD}DE}vI zQlblZaF+3a5JSKS`wRWI(5#SbL&;c8db`CFqSv7V=OzoZ0m|*288yY_K8me{xLuTJ zwdWcGZ`ZK;>C&S0{C!GXqP- z>DsrsxsS^suJT35P8A%Usc`23hsR~*$6T;wkSYkel~b>J?G1!6?ZDvB#?EdDbolx} zU@kfD`~DXtSd0O)|KJNi>cR{fQZxP1`B|5Jwu$Z_w=E0M#5cvLE|4szA6V+ZRh#!l zZTvV#P$nH<;TI&e214Y#7KnS#a4DL#FppU2I6gR5hM?& zfDS&Q&gvsQI_DD&dEV$8IU}L;Oyy}EJ%67eUSFG7e!zi}=~dQ}l5NF2kcyyvbIzpD zx&UWOwbIk0g(ZXXZ)UTxD4nk~p=qg=uXOF$@uEJM^ODx|CT$g!z^a8~|Mgjc68-(T z>AQM*RDSMEnn*8EKUDW;)8bq99;cdK7UShtz&A;^|`f2Gvs)3vfr=(H}7bNjct18#F?@MGCl zux00!;#fLSs5C)+0;((x$H8r=5z!gOS|iST zl7w0^_ouR8_9N`}>?E3xiKQ@SpXz}sc`tM1$LKUOsQh`ff-rDh!GF|Sj4Ni=Bgs>)0F@=q#}vZLOT-Ua zC9^dJ!^SlBAwQn!GTBpooA2_@y*oRu>Ctn{w}heETWE^9dj*ODW(iDfU{9EBA>H=Ue>El)c>Lx+d94L?W3D2uDWGK^WL`)2zyjd00HhL!<-`(_QWA3C)i!##DGG z($0hCxEZ~022iW=JKh%(KWp_X2RS@9u*fu!Q+T-ioX>FEE^SXQ;3CMbMf^mfxUaX>2zC>N5BcL2a5w@&j3|TB zoquHkFU9{Xjp9GIc;-R@9}8Z;Dp;l5%k+U~CnYzE2A8{GQt#~{UOty)OhW{9@U;S7 z6TH*CFlIu!bG#D=<*ki{F7D6gY`_`F*Y#_$N{Q3a;Nv6GAVZw5q}M3Ii{HL|2t$}^ zd^et=Md+>+-YaaQ>FCuJdU|p;VbXvbu@!jgODG!CCUrCpk~Ud9Uk|*%LWzJD zQ8C|vrOa#U8=k9V9QRvoJWd5pmD@=@8y7M=$23C$ssQD$#!Q_%m$?nO$h@)?o)6LK zjlY6j!W#I*dA~`PN5|sn3(8k|X0<_qh0Mg0+u+JqV6o0nF0*7 z5IaGr`_?K;OP#>&0D@UA_zKV(P>&#-}!Ln_sV4zT~AXLEU za(r6lzSnS9&+_W2+91k73?E+#Tb@L?y6*r`< z_g}tw-IxBT&t<0lZr zo=kba!S($qxY-;Y9zrWGEYlKThCCUZ4>l$W)CCT~B^XN3)#tneUw)y9I`=oWvG&xg znreTEyS3`En*N0N6m^=LNv^u4-GMr+acBIB*F;h}KBa+C4D?T9!q>j^racMx8L{@U z$z1sdTt1Ejkchkovgi|}bHQA2!m3zYspRRsduGhM3tqE6Z=5#*dR0-o>Su<8c1Iws zgJ|SJKs+YOVDsK9+=BI2rTL)QufP%QQ&`fWA~Dd!!#!s2kar zJtbRqhA^JatG?PyBTuh7q;(oebv-4OmElkJe3*-J8_)T0^=7sCOfEyi*S}DAH5V?s zWb_}L4l@QH6iTKjTozOhfw|c~!)w;VG2w zLE%UWh1i8Vj<&>-x5VQU62{$`e}c2c?r9x(r;$s?cgn|Jd=;qs3+E5H&CH;nk&bWA z@ptV{A^XpFh5@u0xj8bHv8`Zk|`_CKrC;V$89q>6Q!rkD4Yuc{DeLi>t6E_mYG~)!by}ckp z(P}w|Z3DZYJ_rj0W}|`6?x#7At+A@@+>MtFvZuRgmVwvkT3=)<%f{viUYfcea&KN3(W6Ig^qRVqK2%UwfV$@Q78k1c;0BMuTJ|?sU-CF~wXo-xn1~bJF4{ zd}Fm#jy%YaA-G!j_Y>`omP}E09N=>2^JND^$xBpIcx!F&Qx+8?Q-qsmyF9omar_%l zlTY^JFH!l~&XYz(9rd|iO+9HPFS{Zv^WMq1e*s~REXaT$ZHJQ|NvEf=Y_mSkWdH9@MD4=@@nJPg2M(@^ay_`NNy0o7o& z0?OXw?EyCGVUtBGxa4FlM> zhi&1PT~?wP-!fPH<=w9JBZ6X!s>Q)an0}R- z5PTtH9lOy!MouS6aceZ^M%9h&H)8;F+=3GQ&f)oFdB&-;LKZ4Ce#_I68sT$-csFIg z2{*X*E32cL%q_~z_812vn7CAIW~y?29ADBkM7cZD*`9-csmj*!7mk<|SXn%Jop=M_{PA#&)2n4Y!3j!sEF1ih)|LJgQ=01M^h@nr*A z*X!4=H5-8oQaoG*az<4ay{X{LLq%c@o@-I$JSH&B#@b)*qU}Hz20Q}R31}@UYxrYR0BdBY-~*|C#b`^a}P=ZiWMym z9Sw-#b~2Hsyk_h!C534zMNKW_8oIr>4zVeW&Nmz`uyfopUvO27@62H(WhL#?a46jV z-p$3*dwN!sqQr}Naaj~>JeT|a(ol~mcl+TiFUL31}3F6_E=VvD8)%*^JAPzIJ zxr@)tZO0c{WB_a+Uo(AvJ|(6^tLO2uc3#>dtZQuw{=f(3A~1)4A|Tf1<|w#T*w!0* zcVVI$T+!QOyezMdF$+lGlvgU9wR`zs2&;@pyL<#F zC&sh=Mv3VJZ*+6XsL6133QYVM7e>;>p)$4?cm&%$f;brvZ`lum+hqdOye}& z7maio3VS4B!Af4}=bUvNfEO<3GwTB@EDz+9I@90iA2w^ADyC@p^jlh}m1%NsDYt`f zyH-;eW0zTQ=(*pQ9WtND_nd;V16RNu^|Y&(t*}3I;;y|NH2`7us=`0z#!PO{r2PL{%@^5r{81TSlZg%q6OWpFXt} zxKa}*k;+Y!2^P8Id*8p_qB8X8d;kri2p(21Ex8WKh2xp^a9OzM7~_D=J{-MAM4{=o zGC-#ka5Tfv4UbD0|AFnSf29NAv!S`Ijn`!EWI4I0X-z&>m=9#H+K3E`d3JDEIEiCoMnE+$yrr3)p6seN`ITUt z@KXFB3!Krxu}!mo;6(oO4N7#UluQsWv$C4@ z+T86CaG3yoFaqbjH1=!g#7)iFefo1)+1qNDD1~3wh^g4DY;>|@nl0&BYps$ETzGbl z>*!$Zq}f{2_ac?olqvIKs5kRVW!X?=`0aPKQIMhxqR+NjxE_N|$n@bLehH3tRSn0* z^4vG2*=bDfykm)n#9&mKjy4g`54cu<=)=m1`=x2zne)n!$ zj&|^`{^9HMDx$smYJnM#AZIaKB@=(k!l>XFUfVoVLocsy#Z|07tSygW^{p{s1pMlhN+LozcR?BTIX zlr{bqrqSF~1t(Fa!oH$VH%T_=?~RSoWc>A0=3_HUzB_9iu}S`mf1d3gRpWbS%wP!s zCg>pEc=uY?Cs5;Af4sCk3pGw%Z7uFY*!Me}@T#6^I=+zLu=Xxjvd`c0>`;<{C)@PIpzx5f2f`T^sD%;u zCpbUdSc!jK3==LQCDHYPO_8#6`$&6TpVKT6l(awdhKbU&7EP7r*jWGb6cNnw%=1dU=uPSPSgPGxOp||$3EANyAJCIr zv-k)$V$RMmw=L>{P{U2^N-Oba`laIZmglt%3^vFHEQc9p{cKx`BBi>ePBRgBJq~1_ zpTE(cc>aCTJc}C^HxEMw@)pJ#3+jEi;^4iuh+v)*! zPv$&w_CK+0zd(X@2n=dZKOlmM2)Tb(pfb0r5jDyoSj!-B0C@*)WLr?U5B2a&6h7ol z6Y~B0(~6ZXKK*rf?=vgPGueZd?fUg{u9|HfUEOb|r~HzkIF!E+>;Ijd$^TMM)NLpL z%#ah9rv?SpnSj+NxJ3cC-p0|piaWwr)_HSL`2%=mKodwAAc$+}w4Jn3>-hRA{NQzTJ8+f=u zUcI<<*r9)_3Jt_ZWeeJRqk*Vr$P@=0PL72G4_*q+`xc6g)Ks&xh%n{$Qx|n+hF0}I z4JhJTl<1+=!-o$6Q_75o;!@fI*)OuM2j+^|)2|kU^ID^GJ>BcM!f z&~be-`Ja-$C}aI%@^wxQ?65PFtroYXbhV;F0JUfreP}di=mG1$BnCt2L&<}5;1mF_ z2-=WJX1$b=Mex*Ik2QL=Wok(cH2~DwrXxG=0h+X-=Q`;qR<19ZPG}#S!a8PJP-|a@ zzL=CcMt6>cKglR(Qd9SIfQg_8<9ZM6v8t1apA#fy6I(tIStooNX(t4DA=U4FgUo*i zfD2iCBanmxCw7Q#Jw~G4H?w8KJy=P!HONiaNz-j zY7x(PEv|Q4XA3|4W%5Y(UXg#>iic?#pjK6vJv8c!P~>7#Z$swDZa!@2!C2{=WnTuC zpLe=?rPWw5wt1Dwj#6Ut4PNuEi@HpM-07xqLM6lJqdFHpJU-x8OHGzVrhls7%Y z`Xqvkgw|G8TP&e8NP|gQ67rDvjfJSGuHo}(?BN?@v>{IgIPtLOxMC)`Ud!e+Di>!F z*Ffi{yp-Y0zZ(k@OJ?jh4JSfUCfqqLi6!%`$89>gleRAy?vY7O_5VI<6D64BP3(z> z^PU)S#&>Fa%hpqq2s_JL$=gXYK2Jz6-=)L#VL#lKqJIgj#ppc zt6G}uX0@2p_-dWao`To5&rIif9iw9#)^Q}aY4iz0-atlec&0?2z4=OWUdDLL?l|4^ z*a~isD(SV$EpB4x=4HQyPMsA{!FLPDoz(2hGZ@Sg!za0I`%U;vRfxFUYxdyk%s+Fk zAp9(i=+>P*68Up)SLqh;%#oZ%NIh`{N7APbU^FG*Fryp~7N<kKeW<)aRgUHQ| zB=^$Ai#dC^d`{16JEF=qdnKjLuW5Llu{lx{uE-xHYn_XR6>DFn6{TX6D~#ZX7dBfW ztE&s7*xBs8K%iCd{{4H%OnUX|!}~2vdzHpK+0PI3jh6{ym4mL}7wDIyf%i7l{7V?H z-^T`s7CVle2e_Tf^Rq5JIF>OwY`QuXcx4tt11Ci7%SeexZZUPOuL4O2kNm9;19`gq zEYTGPzAG6A5$rWSOH{qDbTWt?fYsi|^ zyjF~{5xYSdQ00ke*?X)w8#X&~Uq=VmN$gLZik-lwnMc$_#7G=4J?(`&5lat3S*`-- zwZ?CT9}WN@@4;N)2Hnr>a2YXQ`6XWOgDt48K}0O}qlY&*Eo*i?H!QqRZ%Hmialij4 zA|PhWC9K2X2&MysoU&0@dtK3NY5qu9aJ{(enKMB0PNu%C4?3%?zkGNQxJh8u9|Y06 zco{Cv&PDIhBb~+$j;{~T@y^+a&8!ivDRhIJw8Z;x^%X}fb`^8uJB%P`^7kE%3SMLI zzQ)ldP5TIOXY_Rt^)3=4KgLU>YevTXuz~8N@kk|$`9_>^Tjk_bZB@m+rT1SE}x$nZ3XplGI23F`-yYy;aSP+UTW=acR9bmR5k~@ zJP^y0g9Z+GrI>jcuYqEBv_fVT$fI!H9%wHV#m|B_Lcb;_rBK9VD0Is6f*u_5UP6IV zFd@7W?DHhfh}-w*06g*LQzQW7KL*BZYm(~|8VfT`BXY9c+Q4t6G!7P+j5n)4#|046 z1DQ6Xd~O6Q`SR4rB_jyoG3R>9ediYMS_fxO22)#vQXt~lnW6Nq;bWxf7S8foz?E*Z zBCZJy>!ifuLb`d=?UVLU7w$si*Y&zE9*RXzX0EzE+-VIVumB*)m$ytWn371&P(C8l@ zR+=yrIZ^GzSVuVs@;HQ?;=Dy$Q&1;mpQqc<{b#-!sQqNF{r$JIdp;R~x?-I&jb;vF zX{E_ZQSsVnx?`wrI=JY3hADqUQ`D~o zovlHM$VBwm0chq5;=_f?cT0pAV47nQoe2*0Exw6e$7K}N zH_j}ZYqop>4Bn}&oo7G#dSj1oHa=z5NsN9prg~6{E&;Y(ea^) zXV{B9vJH(7?K2Hg?+zHM$}-PS8p`^G$tQe^ZQuww<0riF7q3Q@zjP>7r_Gd9Lx;$@ zK3Ri7``u(y2-eQM{_FAQLbsdsXI4eLJ&#kcj|ZMO49yUnXyWJ{E*(2()R^;wSz1U^ zA#_pn$dp*p?BegbgnnVs_k7=)m+M~ly9=mmx8>yIz<5yo1~+{@-bXQ*(-4LHE?9}T zoied3!=$rWetxca{hE`6(2L=gz)!y@Jr(DZqern6sF}V8VLQyN7;yRrbN^ln|HqLJ zJY-5Hfi9;)EaTt*@!iRR_Vw4_bFx^_58~H{2t?SR$NKem>lFp`5a!p1C`Pl_7U~;r zjtxzD9fylCfXg2RlCm281OEDyc%1~*H%CKn`yKMcnO;e@W8Se#L97n1rdFzP`gHjp zbn=aSE`rPF5AS2$Es}RP?~_~cn!zrqTkJ^5jtR-b;Nd z{!LpY*);*mzf_&%namLz3vBX;6hwV&h2FPAzT4gdA?M-?vP4akO;bgGewE#{H5a2S zN3Fe0Gt3kt;on*!5nK_wS17vud303h+6Q*7N9%;64!*u_o@3&_ADn{@r(DVK=ea{{ z;haXg1h>!>Tcmhfbf>m~xlcol8I8Fp+vJOz-`Fu99Pcc@Rca{z-Y({SEVIe!eobai zy#0HMFHQH_`-Ab(ddgzGNAnZCVk6a>f8InSd&ZM*hDSAS(>(hsuLtNXvO=ovB2s$Z zzJBj++DMXo$<*M>kj9mRrNLKygB688+jp0B*+!Ei#iozeD%?ksylADy@mFcOD~`99 zzgRl>+~$~fr~A*_9Hd=sPnu6sr>D!syYa5rq{A$*FHZYPi=|_FtAOmRGH-|YpaqgM z;HBN;ohbA7^KyR{!Ze|Cit;HNfu$6ILt%ti+$V|J3uYSMaD^%m%KStvkuq?uYf}~K}++9IG+Qp`4 z56U)ASBv!Bd)l$~4lnH9ZqOh3-g!^JbFHfTwePVXi%m23tT!#DuNG!Zl=-1=-P&Kr zZaSO0Z$w4h>S){(|MTtHhUlqFP6d|ZlrlA#V;%B^9>fIo0s8aMCs$G5ep#&$v(ql39)O^|y|oUH<)=2jb8N z*RO9BlJU=G<=gr9{(nXLXU{8KQS^L^Iz8h(IhFpi_Xhz6{8Ernm3}R06!`xE9~gca literal 0 HcmV?d00001 diff --git a/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md new file mode 100644 index 000000000000..4d7eb338bd86 --- /dev/null +++ b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md @@ -0,0 +1,106 @@ +# Installing PowerShell Core on Windows + +## MSI + +To install PowerShell on a Windows client or Windows Server (works on Windows 7 SP1, Server 2008 R2, and later), download the MSI package from + +our GitHub [releases][] page. +The MSI file looks like this - `PowerShell-6.0.0...msi` + +Once downloaded, double-click the installer and follow the prompts. + +There is a shortcut placed in the Start Menu upon installation. + +* By default the package is installed to `$env:ProgramFiles\PowerShell\` +* You can launch PowerShell via the Start Menu or `$env:ProgramFiles\PowerShell\pwsh.exe` + +### Prerequisites + +To enable PowerShell remoting over WSMan, the following prerequisites need to be met: + +* Install the [Universal C Runtime](https://www.microsoft.com/download/details.aspx?id=50410) on Windows versions prior to Windows 10. + It is available via direct download or Windows Update. + Fully patched (including optional packages), supported systems will already have this installed. +* Install the Windows Management Framework (WMF) [4.0](https://www.microsoft.com/download/details.aspx?id=40855) + or newer ([5.1](https://www.microsoft.com/download/details.aspx?id=54616)) on Windows 7 and Windows Server 2008 R2. + +## ZIP + +PowerShell binary ZIP archives are provided to enable advanced deployment scenarios. +Be noted that when using the ZIP archive, you won't get the prerequisites check as in the MSI package. +So in order for remoting over WSMan to work properly on Windows versions prior to Windows 10, +you need to make sure the [prerequisites](#prerequisites) are met. + +## Deploying on Nano Server + +These instructions assume that a version of PowerShell is already running on the Nano Server image and that it has been generated by the [Nano Server Image Builder](https://technet.microsoft.com/windows-server-docs/get-started/deploy-nano-server). +Nano Server is a "headless" OS and deployment of PowerShell Core binaries can happen in two different ways: + +1. Offline - Mount the Nano Server VHD and unzip the contents of the zip file to your chosen location within the mounted image. +1. Online - Transfer the zip file over a PowerShell Session and unzip it in your chosen location. + +In both cases, you will need the Windows 10 x64 Zip release package and will need to run the commands within an "Administrator" PowerShell instance. + +### Offline Deployment of PowerShell Core + +1. Use your favorite zip utility to unzip the package to a directory within the mounted Nano Server image. +1. Unmount the image and boot it. +1. Connect to the inbox instance of Windows PowerShell. +1. Follow the instructions to create a remoting endpoint using the [another instance technique](#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register). + +### Online Deployment of PowerShell Core + +The following steps will guide you through the deployment of PowerShell Core to a running instance of Nano Server and the configuration of its remote endpoint. + +* Connect to the inbox instance of Windows PowerShell + +```powershell +$session = New-PSSession -ComputerName -Credential +``` + +* Copy the file to the Nano Server instance + +```powershell +Copy-Item \powershell--win-x64.zip c:\ -ToSession $session +``` + +* Enter the session + +```powershell +Enter-PSSession $session +``` + +* Extract the Zip file + +```powershell +# Insert the appropriate version. +Expand-Archive -Path C:\powershell--win-x64.zip -DestinationPath "C:\PowerShellCore_" +``` + +* If you want WSMan-based remoting, follow the instructions to create a remoting endpoint using the [another instance technique](../core-powershell/WSMan-Remoting-in-PowerShell-Core.md#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register). + +## Instructions to Create a Remoting Endpoint + +PowerShell Core supports the PowerShell Remoting Protocol (PSRP) over both WSMan and SSH. For more information, see: + +* [SSH Remoting in PowerShell Core][ssh-remoting] +* [WSMan Remoting in PowerShell Core][wsman-remoting] + +## Artifact Installation Instructions + +We publish an archive with CoreCLR bits on every CI build with [AppVeyor][]. + +## CoreCLR Artifacts + +* Download zip package from **artifacts** tab of the particular build. +* Unblock zip file: right-click in File Explorer -> Properties -> + check 'Unblock' box -> apply +* Extract zip file to `bin` directory +* `./bin/pwsh.exe` + + +[releases]: https://github.com/PowerShell/PowerShell/releases +[signing]: ../../tools/Sign-Package.ps1 +[ssh-remoting]: ../core-powershell/SSH-Remoting-in-PowerShell-Core.md +[wsman-remoting]: ../core-powershell/WSMan-Remoting-in-PowerShell-Core.md +[AppVeyor]: https://ci.appveyor.com/project/PowerShell/powershell diff --git a/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md new file mode 100644 index 000000000000..a3e31810d9ea --- /dev/null +++ b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md @@ -0,0 +1,808 @@ +# Package installation instructions + +Supports [Ubuntu 14.04][u14], [Ubuntu 16.04][u16], [Ubuntu 17.04][u17], [Debian 8][deb8], [Debian 9][deb9], +[CentOS 7][cos], [Red Hat Enterprise Linux (RHEL) 7][rhel7], [OpenSUSE 42.2][opensuse], [Fedora 25][fed25], +[Fedora 26][fed26], [Arch Linux][arch], and [macOS 10.12][mac]. + +For Linux distributions that are not officially supported, +you can try using the [PowerShell AppImage][lai]. +You can also try deploying PowerShell binaries directly using the Linux [`tar.gz` archive][tar], +but you would need to set up the necessary dependencies based on the OS in separate steps. + +All packages are available on our GitHub [releases][] page. +Once the package is installed, run `pwsh` from a terminal. + +[u14]: #ubuntu-1404 +[u16]: #ubuntu-1604 +[u17]: #ubuntu-1704 +[deb8]: #debian-8 +[deb9]: #debian-9 +[cos]: #centos-7 +[rhel7]: #red-hat-enterprise-linux-rhel-7 +[opensuse]: #opensuse-422 +[fed25]: #fedora-25 +[fed26]: #fedora-26 +[arch]: #arch-linux +[lai]: #linux-appimage +[mac]: #macos-1012 +[tar]: #binary-archives + +## Ubuntu 14.04 + +### Installation via Package Repository - Ubuntu 14.04 + +PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). +This is the preferred method. + +```sh +# Import the public repository GPG keys +curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - + +# Register the Microsoft Ubuntu repository +curl https://packages.microsoft.com/config/ubuntu/14.04/prod.list | sudo tee /etc/apt/sources.list.d/microsoft.list + +# Update the list of products +sudo apt-get update + +# Install PowerShell +sudo apt-get install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +from then on, you just need to use `sudo apt-get upgrade powershell` to update it. + +### Installation via Direct Download - Ubuntu 14.04 + +Download the Debian package +`powershell_6.0.0-rc-1.ubuntu.14.04_amd64.deb` +from the [releases][] page onto the Ubuntu machine. + +Then execute the following in the terminal: + +```sh +sudo dpkg -i powershell_6.0.0-rc-1.ubuntu.14.04_amd64.deb +sudo apt-get install -f +``` + +> Please note that `dpkg -i` will fail with unmet dependencies; +> the next command, `apt-get install -f` resolves these +> and then finishes configuring the PowerShell package. + +### Uninstallation - Ubuntu 14.04 + +```sh +sudo apt-get remove powershell +``` + +## Ubuntu 16.04 + +### Installation via Package Repository - Ubuntu 16.04 + +PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). +This is the preferred method. + +```sh +# Import the public repository GPG keys +curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - + +# Register the Microsoft Ubuntu repository +curl https://packages.microsoft.com/config/ubuntu/16.04/prod.list | sudo tee /etc/apt/sources.list.d/microsoft.list + +# Update the list of products +sudo apt-get update + +# Install PowerShell +sudo apt-get install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +from then on, you just need to use `sudo apt-get upgrade powershell` to update it. + +### Installation via Direct Download - Ubuntu 16.04 + +Download the Debian package +`powershell_6.0.0-rc-1.ubuntu.16.04_amd64.deb` +from the [releases][] page onto the Ubuntu machine. + +Then execute the following in the terminal: + +```sh +sudo dpkg -i powershell_6.0.0-rc-1.ubuntu.16.04_amd64.deb +sudo apt-get install -f +``` + +> Please note that `dpkg -i` will fail with unmet dependencies; +> the next command, `apt-get install -f` resolves these +> and then finishes configuring the PowerShell package. + +### Uninstallation - Ubuntu 16.04 + +```sh +sudo apt-get remove powershell +``` + +## Ubuntu 17.04 + +### Installation via Package Repository - Ubuntu 17.04 + +PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). +This is the preferred method. + +```sh +# Import the public repository GPG keys +curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - + +# Register the Microsoft Ubuntu repository +curl https://packages.microsoft.com/config/ubuntu/17.04/prod.list | sudo tee /etc/apt/sources.list.d/microsoft.list + +# Update the list of products +sudo apt-get update + +# Install PowerShell +sudo apt-get install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +from then on, you just need to use `sudo apt-get upgrade powershell` to update it. + +### Installation via Direct Download - Ubuntu 17.04 + +Download the Debian package +`powershell_6.0.0-rc-1.ubuntu.17.04_amd64.deb` +from the [releases][] page onto the Ubuntu machine. + +Then execute the following in the terminal: + +```sh +sudo dpkg -i powershell_6.0.0-rc-1.ubuntu.17.04_amd64.deb +sudo apt-get install -f +``` + +> Please note that `dpkg -i` will fail with unmet dependencies; +> the next command, `apt-get install -f` resolves these +> and then finishes configuring the PowerShell package. + +### Uninstallation - Ubuntu 17.04 + +```sh +sudo apt-get remove powershell +``` + +## Debian 8 + +### Installation via Package Repository - Debian 8 + +PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). +This is the preferred method. + +```sh +# Install system components +sudo apt-get update +sudo apt-get install curl apt-transport-https + +# Import the public repository GPG keys +curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - + +# Register the Microsoft Product feed +sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-debian-jessie-prod jessie main" > /etc/apt/sources.list.d/microsoft.list' + +# Update the list of products +sudo apt-get update + +# Install PowerShell +sudo apt-get install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +from then on, you just need to use `sudo apt-get upgrade powershell` to update it. + +### Installation via Direct Download - Debian 8 + +Download the Debian package +`powershell_6.0.0-rc-1.debian.8_amd64.deb` +from the [releases][] page onto the Debian machine. + +Then execute the following in the terminal: + +```sh +sudo dpkg -i powershell_6.0.0-rc-1.debian.8_amd64.deb +sudo apt-get install -f +``` + +> Please note that `dpkg -i` will fail with unmet dependencies; +> the next command, `apt-get install -f` resolves these +> and then finishes configuring the PowerShell package. + +### Uninstallation - Debian 8 + +```sh +sudo apt-get remove powershell +``` + +## Debian 9 + +### Installation via Package Repository - Debian 9 + +PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). +This is the preferred method. + +```sh +# Install system components +sudo apt-get update +sudo apt-get install curl gnupg apt-transport-https + +# Import the public repository GPG keys +curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - + +# Register the Microsoft Product feed +sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-debian-stretch-prod stretch main" > /etc/apt/sources.list.d/microsoft.list' + +# Update the list of products +sudo apt-get update + +# Install PowerShell +sudo apt-get install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +from then on, you just need to use `sudo apt-get upgrade powershell` to update it. + +### Installation via Direct Download - Debian 9 + +Download the Debian package +`powershell_6.0.0-rc-1.debian.9_amd64.deb` +from the [releases][] page onto the Debian machine. + +Then execute the following in the terminal: + +```sh +sudo dpkg -i powershell_6.0.0-rc-1.debian.9_amd64.deb +sudo apt-get install -f +``` + +> Please note that `dpkg -i` will fail with unmet dependencies; +> the next command, `apt-get install -f` resolves these +> and then finishes configuring the PowerShell package. + +### Uninstallation - Debian 9 + +```sh +sudo apt-get remove powershell +``` + +## CentOS 7 + +> This package also works on Oracle Linux 7. + +### Installation via Package Repository (preferred) - CentOS 7 + +PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). + +```sh +# Register the Microsoft RedHat repository +curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo + +# Install PowerShell +sudo yum install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +you just need to use `sudo yum update powershell` to update PowerShell. + +### Installation via Direct Download - CentOS 7 + +Using [CentOS 7][], download the RPM package +`powershell-6.0.0_rc-1.rhel.7.x86_64.rpm` +from the [releases][] page onto the CentOS machine. + +Then execute the following in the terminal: + +```sh +sudo yum install powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +You can also install the RPM without the intermediate step of downloading it: + +```sh +sudo yum install https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +### Uninstallation - CentOS 7 + +```sh +sudo yum remove powershell +``` + +[CentOS 7]: https://www.centos.org/download/ + +## Red Hat Enterprise Linux (RHEL) 7 + +### Installation via Package Repository (preferred) - Red Hat Enterprise Linux (RHEL) 7 + +PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). + +```sh +# Register the Microsoft RedHat repository +curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo + +# Install PowerShell +sudo yum install -y powershell + +# Start PowerShell +pwsh +``` + +After registering the Microsoft repository once as superuser, +you just need to use `sudo yum update powershell` to update PowerShell. + +### Installation via Direct Download - Red Hat Enterprise Linux (RHEL) 7 + +Download the RPM package +`powershell-6.0.0_rc-1.rhel.7.x86_64.rpm` +from the [releases][] page onto the Red Hat Enterprise Linux machine. + +Then execute the following in the terminal: + +```sh +sudo yum install powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +You can also install the RPM without the intermediate step of downloading it: + +```sh +sudo yum install https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +### Uninstallation - Red Hat Enterprise Linux (RHEL) 7 + +```sh +sudo yum remove powershell +``` + +## OpenSUSE 42.2 + +> **Note:** When installing PowerShell Core, OpenSUSE may report that nothing provides `libcurl`. +`libcurl` should already be installed on supported versions of OpenSUSE. +Run `zypper search libcurl` to confirm. +The error will present 2 'solutions'. Choose 'Solution 2' to continue installing PowerShell Core. + +### Installation via Package Repository (preferred) - OpenSUSE 42.2 + +PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). + +```sh +# Register the Microsoft signature key +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc + +# Add the Microsoft Product feed +curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/zypp/repos.d/microsoft.repo + +# Update the list of products +sudo zypper update + +# Install PowerShell +sudo zypper install powershell + +# Start PowerShell +pwsh +``` + +### Installation via Direct Download - OpenSUSE 42.2 + +Download the RPM package `powershell-6.0.0_rc-1.rhel.7.x86_64.rpm` +from the [releases][] page onto the OpenSUSE machine. + +```sh +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc +sudo zypper install powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +You can also install the RPM without the intermediate step of downloading it: + +```sh +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc +sudo zypper install https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +### Uninstallation - OpenSUSE 42.2 + +```sh +sudo zypper remove powershell +``` + +## Fedora 25 + +### Installation via Package Repository (preferred) - Fedora 25 + +PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). + +```sh +# Register the Microsoft signature key +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc + +# Register the Microsoft RedHat repository +curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo + +# Update the list of products +sudo dnf update + +# Install PowerShell +sudo dnf install -y powershell + +# Start PowerShell +pwsh +``` + +### Installation via Direct Download - Fedora 25 + +Download the RPM package +`powershell-6.0.0_rc-1.rhel.7.x86_64.rpm` +from the [releases][] page onto the Fedora machine. + +Then execute the following in the terminal: + +```sh +sudo dnf install powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +You can also install the RPM without the intermediate step of downloading it: + +```sh +sudo dnf install https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +### Uninstallation - Fedora 25 + +```sh +sudo dnf remove powershell +``` + +## Fedora 26 + +### Installation via Package Repository (preferred) - Fedora 26 + +PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). + +```sh +# Register the Microsoft signature key +sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc + +# Register the Microsoft RedHat repository +curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo + +# Update the list of products +sudo dnf update + +# Install a system component +sudo dnf install compat-openssl10 + +# Install PowerShell +sudo dnf install -y powershell + +# Start PowerShell +pwsh +``` + +### Installation via Direct Download - Fedora 26 + +Download the RPM package +`powershell-6.0.0_rc-1.rhel.7.x86_64.rpm` +from the [releases][] page onto the Fedora machine. + +Then execute the following in the terminal: + +```sh +sudo dnf update +sudo dnf install compat-openssl10 +sudo dnf install powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +You can also install the RPM without the intermediate step of downloading it: + +```sh +sudo dnf update +sudo dnf install compat-openssl10 +sudo dnf install https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0_rc-1.rhel.7.x86_64.rpm +``` + +### Uninstallation - Fedora 26 + +```sh +sudo dnf remove powershell +``` + +## Arch Linux + +PowerShell is available from the [Arch Linux][] User Repository (AUR). + +* It can be compiled with the [latest tagged release][arch-release] +* It can be compiled from the [latest commit to master][arch-git] +* It can be installed using the [latest release binary][arch-bin] + +Packages in the AUR are community maintained - there is no official support. + +For more information on installing packages from the AUR, see the [Arch Linux wiki](https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages) or the community [DockerFile](https://github.com/PowerShell/PowerShell/blob/master/docker/community/archlinux/Dockerfile). + +[Arch Linux]: https://www.archlinux.org/download/ +[arch-release]: https://aur.archlinux.org/packages/powershell/ +[arch-git]: https://aur.archlinux.org/packages/powershell-git/ +[arch-bin]: https://aur.archlinux.org/packages/powershell-bin/ + +## Linux AppImage + +Using a recent Linux distribution, +download the AppImage `powershell-6.0.0-rc-x86_64.AppImage` +from the [releases][] page onto the Linux machine. + +Then execute the following in the terminal: + +```bash +chmod a+x powershell-6.0.0-rc-x86_64.AppImage +./powershell-6.0.0-rc-x86_64.AppImage +``` + +The [AppImage][] lets you run PowerShell without installing it. +It is a portable application that bundles PowerShell and its dependencies +(including .NET Core's system dependencies) into one cohesive package. +This package works independently of the user's Linux distribution, +and is a single binary. + +[appimage]: http://appimage.org/ + +## macOS 10.12 + +### Installation via Homebrew (preferred) - macOS 10.12 + +[Homebrew][brew] is the missing package manager for macOS. +If the `brew` command is not found, +you need to install Homebrew following [their instructions][brew]. + +Once you've installed Homebrew, installing PowerShell is easy. +First, install [Homebrew-Cask][cask], so you can install more packages: + +```sh +brew tap caskroom/cask +``` + +Now, you can install PowerShell: + +```sh +brew cask install powershell +``` + +When new versions of PowerShell are released, +simply update Homebrew's formulae and upgrade PowerShell: + +```sh +brew update +brew cask reinstall powershell +``` + +> Note: because of [this issue in Cask](https://github.com/caskroom/homebrew-cask/issues/29301), you currently have to do a reinstall to upgrade. + +[brew]: http://brew.sh/ +[cask]: https://caskroom.github.io/ + +### Installation via Direct Download - macOS 10.12 + +Using macOS 10.12, download the PKG package +`powershell-6.0.0-rc-osx.10.12-x64.pkg` +from the [releases][] page onto the macOS machine. + +Either double-click the file and follow the prompts, +or install it from the terminal: + +```sh +sudo installer -pkg powershell-6.0.0-rc-osx.10.12-x64.pkg -target / +``` + +### Uninstallation - macOS 10.12 + +If you installed PowerShell with Homebrew, uninstallation is easy: + +```sh +brew cask uninstall powershell +``` + +If you installed PowerShell via direct download, +PowerShell must be removed manually: + +```sh +sudo rm -rf /usr/local/bin/pwsh /usr/local/microsoft/powershell +``` + +To uninstall the additional PowerShell paths (such as the user profile path) +please see the [paths][paths] section below in this document +and remove the desired the paths with `sudo rm`. +(Note: this is not necessary if you installed with Homebrew.) + +[paths]:#paths + +## Kali + +### Installation + +```sh +# Install prerequisites +apt-get install libunwind8 libicu55 +wget http://security.debian.org/debian-security/pool/updates/main/o/openssl/libssl1.0.0_1.0.1t-1+deb8u6_amd64.deb +dpkg -i libssl1.0.0_1.0.1t-1+deb8u6_amd64.deb + +# Install PowerShell +dpkg -i powershell_6.0.0-rc-1.ubuntu.16.04_amd64.deb + +# Start PowerShell +pwsh +``` + +### Run PowerShell in latest Kali (Kali GNU/Linux Rolling) without installing it + +```sh +# Grab the latest App Image +wget https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0-rc-x86_64.AppImage + +# Make executable +chmod a+x powershell-6.0.0-rc-x86_64.AppImage + +# Start PowerShell +./powershell-6.0.0-rc-x86_64.AppImage +``` + +### Uninstallation - Kali + +```sh +dpkg -r powershell_6.0.0-rc-1.ubuntu.16.04_amd64.deb +``` + +## Raspbian + +Currently, PowerShell is only supported on Raspbian Stretch. + +### Installation + +```sh +# Install prerequisites +sudo apt-get install libunwind8 + +# Grab the latest tar.gz +wget https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0-rc-linux-arm32.tar.gz + +# Make folder to put powershell +mkdir ~/powershell + +# Unpack the tar.gz file +tar -xvf ./powershell-6.0.0-rc-linux-arm32.tar.gz -C ~/powershell + +# Start PowerShell +~/powershell/pwsh +``` + +### Uninstallation - Raspbian + +```sh +rm -rf ~/powershell +``` + +## Binary Archives + +PowerShell binary `tar.gz` archives are provided for macOS and Linux platforms to enable advanced deployment scenarios. + +### Dependencies + +For Linux, PowerShell builds portable binaries for all Linux distributions. +But .NET Core runtime requires different dependencies on different distributions, +and hence PowerShell does the same. + +The following chart shows the .NET Core 2.0 dependencies on different Linux distributions that are officially supported. + +| OS | Dependencies | +| ------------------ | ------------ | +| Ubuntu 14.04 | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
    libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu52 | +| Ubuntu 16.04 | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
    libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu55 | +| Ubuntu 17.04 | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
    libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu57 | +| Debian 8 (Jessie) | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
    libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu52 | +| Debian 9 (Stretch) | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
    libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.2, libicu57 | +| CentOS 7
    Oracle Linux 7
    RHEL 7
    OpenSUSE 42.2
    Fedora 25 | libunwind, libcurl, openssl-libs, libicu | +| Fedora 26 | libunwind, libcurl, openssl-libs, libicu, compat-openssl10 | + +In order to deploy PowerShell binaries on Linux distributions that are not officially supported, +you would need to install the necessary dependencies for the target OS in separate steps. +For example, our [Amazon Linux dockerfile][amazon-dockerfile] installs dependencies first, +and then extracts the Linux `tar.gz` archive. + +[amazon-dockerfile]: https://github.com/PowerShell/PowerShell/blob/master/docker/community/amazonlinux/Dockerfile + +### Installation - Binary Archives + +#### Linux + +```sh +# Download the powershell '.tar.gz' archive +curl -L -o /tmp/powershell.tar.gz https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0-rc-linux-x64.tar.gz + +# Create the target folder where powershell will be placed +sudo mkdir -p /opt/microsoft/powershell/6.0.0-rc + +# Expand powershell to the target folder +sudo tar zxf /tmp/powershell.tar.gz -C /opt/microsoft/powershell/6.0.0-rc + +# Set execute permissions +sudo chmod +x /usr/local/microsoft/powershell/6.0.0-rc/pwsh + +# Create the symbolic link that points to pwsh +sudo ln -s /opt/microsoft/powershell/6.0.0-rc/pwsh /usr/bin/pwsh +``` + +#### macOS + +```sh +# Download the powershell '.tar.gz' archive +curl -L -o /tmp/powershell.tar.gz https://github.com/PowerShell/PowerShell/releases/download/v6.0.0-rc/powershell-6.0.0-rc-osx-x64.tar.gz + +# Create the target folder where powershell will be placed +sudo mkdir -p /usr/local/microsoft/powershell/6.0.0-rc + +# Expand powershell to the target folder +sudo tar zxf /tmp/powershell.tar.gz -C /usr/local/microsoft/powershell/6.0.0-rc + +# Set execute permissions +sudo chmod +x /usr/local/microsoft/powershell/6.0.0-rc/pwsh + +# Create the symbolic link that points to pwsh +sudo ln -s /usr/local/microsoft/powershell/6.0.0-rc/pwsh /usr/local/bin/pwsh +``` + +### Uninstallation - Binary Archives + +#### Linux + +```sh +sudo rm -rf /usr/bin/pwsh /opt/microsoft/powershell +``` + +#### macOS + +```sh +sudo rm -rf /usr/local/bin/pwsh /usr/local/microsoft/powershell +``` + +## Paths + +* `$PSHOME` is `/opt/microsoft/powershell/6.0.0-rc/` +* User profiles will be read from `~/.config/powershell/profile.ps1` +* Default profiles will be read from `$PSHOME/profile.ps1` +* User modules will be read from `~/.local/share/powershell/Modules` +* Shared modules will be read from `/usr/local/share/powershell/Modules` +* Default modules will be read from `$PSHOME/Modules` +* PSReadline history will be recorded to `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` + +The profiles respect PowerShell's per-host configuration, +so the default host-specific profiles exists at `Microsoft.PowerShell_profile.ps1` in the same locations. + +On Linux and macOS, the [XDG Base Directory Specification][xdg-bds] is respected. + +Note that because macOS is a derivation of BSD, +instead of `/opt`, the prefix used is `/usr/local`. +Thus, `$PSHOME` is `/usr/local/microsoft/powershell/6.0.0-rc/`, +and the symlink is placed at `/usr/local/bin/pwsh`. + +[releases]: https://github.com/PowerShell/PowerShell/releases/latest +[xdg-bds]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html diff --git a/reference/docs-conceptual/setup/setup-reference.md b/reference/docs-conceptual/setup/setup-reference.md index 959d7ee4842f..aeb967904927 100644 --- a/reference/docs-conceptual/setup/setup-reference.md +++ b/reference/docs-conceptual/setup/setup-reference.md @@ -6,6 +6,8 @@ title: setup reference # Setup Guide +- [Installing PowerShell Core on macOS and Linux](Installing-PowerShell-Core-on-macOS-and-Linux.md) +- [Installing PowerShell Core on Windows](Installing-PowerShell-Core-on-Windows.md) - [Installing Windows PowerShell](Installing-Windows-PowerShell.md) - [Installing the Windows PowerShell 2.0 Engine](Installing-the-Windows-PowerShell-2.0-Engine.md) - [Installing the Windows PowerShell SDK](Installing-the-Windows-PowerShell-SDK.md) @@ -17,4 +19,3 @@ title: setup reference - [Starting Windows PowerShell](Starting-Windows-PowerShell.md) - [Windows PowerShell System Requirements](Windows-PowerShell-System-Requirements.md) - [WinRMSecurity](WinRMSecurity.md) - From 76160fe19ffd8fa7b0251d492fecb0167ceee873 Mon Sep 17 00:00:00 2001 From: Joey Aiello Date: Wed, 10 Jan 2018 11:47:02 -0800 Subject: [PATCH 166/188] PowerShell Core 6.0 release notes (#2020) What's New in PowerShell Core 6.0 --- .../What-s-New-in-PowerShell-Core-60.md | 403 ++++++++++++++++++ 1 file changed, 403 insertions(+) create mode 100644 reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md new file mode 100644 index 000000000000..81b2d64ff4da --- /dev/null +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md @@ -0,0 +1,403 @@ +# What's New in PowerShell Core 6.0 + +[PowerShell Core 6.0][github] is a new edition of PowerShell that is cross-platform (Windows, macOS, and Linux), open-source, and built for heterogeneous environments and the hybrid cloud. + +## Moved from .NET Framework to .NET Core + +PowerShell Core uses [.NET Core 2.0][] as its runtime. +.NET Core 2.0 enables PowerShell Core to work on multiple platforms (Windows, macOS, and Linux). +PowerShell Core also exposes the API set offered by .NET Core 2.0 to be used in PowerShell cmdlets and scripts. + +Windows PowerShell used the .NET Framework runtime to host the PowerShell engine. +This means that Windows PowerShell exposes the API set offered by .NET Framework. + +The APIs shared between .NET Core and .NET Framework are defined as part of [.NET Standard][]. + +For more information on how this affects module/script compatibility between PowerShell Core and Windows PowerShell, +see [Backwards compatibility with Windows PowerShell][#backwards-compatibility-with-windows-powershell] + +## Support for macOS and Linux + +PowerShell now officially supports macOS and Linux, including: + +- Windows 7, 8.1, and 10 +- Windows Server 2008 R2, 2012 R2, 2016 +- [Windows Server Semi-Annual Channel][semi-annual] +- Ubuntu 14.04, 16.04, and 17.04 +- Debian 8.7+, and 9 +- CentOS 7 +- Red Hat Enterprise Linux 7 +- OpenSUSE 42.2 +- Fedora 25, 26 +- macOS 10.12+ + +Our community has also contributed packages for the following platforms, +but they are not officially supported: + +- Arch Linux +- Kali Linux +- AppImage (works on multiple Linux platforms) + +We also have experimental (unsupported) releases for the following platforms: + +- Windows on ARM32/ARM64 +- Raspbian (Stretch) + +A number of changes were made to in PowerShell Core 6.0 to make it work better on non-Windows systems. +Some of these are breaking changes, which also affect Windows. +Others are only present or applicable in non-Windows installations of PowerShell Core. + +- Added support for native command globbing on Unix platforms. +- The `more` functionality respects the Linux `$PAGER` and defaults to `less`. + This means you can now use wildcards with native binaries/commands (for example, `ls *.txt`). (#3463) +- Trailing backslash is automatically escaped when dealing with native command arguments. (#4965) +- Ignore the `-ExecutionPolicy` switch when running PowerShell on non-Windows platforms because script signing is not currently supported. (#3481) +- Fixed ConsoleHost to honor `NoEcho` on Unix platforms. (#3801) +- Fixed `Get-Help` to support case insensitive pattern matching on Unix platforms. (#3852) +- `powershell` man-page added to package + +### Logging + +On macOS, PowerShell uses the native `os_log` APIs to log to Apple's [unified logging system][os_log]. +On Linux, PowerShell uses [Syslog][], a ubiquitous logging solution. + +### Filesystem + +A number of changes have been made on macOS and Linux to support filename characters not traditionally supported on Windows: + +- Paths given to cmdlets are now slash-agnostic (both / and \ work as directory separator) +- XDG Base Directory Specification is now respected and used by default: + - The Linux/macOS profile path is located at `~/.config/powershell/profile.ps1` + - The history save path is located at `~/.local/share/powershell/PSReadline/ConsoleHost_history.txt` + - The user module path is located at `~/.local/share/powershell/Modules` +- Support for file and folder names containing the colon character on Unix. (#4959) +- Support for script names or full paths that have commas. (#4136) (Thanks to @TimCurwick!) +- Detect when `-LiteralPath` is used to suppress wildcard expansion for navigation cmdlets. (#5038) +- Updated `Get-ChildItem` to work more like the *nix `ls -R` and the Windows `DIR /S` native commands. + `Get-ChildItem` now returns the symbolic links encountered during a recursive search and does not search the directories that those links target. (#3780) + +### Case sensitivity + +Linux and macOS tend to be case-sensitive while Windows is case-insensitive while preserving case. +In general, PowerShell is case insensitive. + +For example, environment variables are case-sensitive on macOS and Linux, +so the casing of the `PSModulePath` environment variable has been standardized. (#3255) +`Import-Module` is case insensitive when it's using a file path to determine the module's name. (#5097) + +## Support for side-by-side installations + +PowerShell Core is installed, configured, and executed separately from Windows PowerShell. +PowerShell Core has a "portable" ZIP package. +Using the ZIP package, you can install any number of versions anywhere on disk, including local to an application that takes PowerShell as a dependency. +Side-by-side installation makes it easier to test new versions of PowerShell and migrating existing scripts over time. +Side-by-side also enables backwards compatibility as scripts can be pinned to specific versions that they require. + +> [!NOTE] +> By default, the MSI-based installer on Windows does an in-place update install. +> + +## Renamed `powershell(.exe)` to `pwsh(.exe)` + +The binary name for PowerShell Core has been changed from `powershell(.exe)` to `pwsh(.exe)`. +This change provides a deterministic way for users to run PowerShell Core on machines to support side-by-side Windows PowerShell and PowerShell Core installations. +`pwsh` is also much shorter and easier to type. + +Additional changes to `pwsh(.exe)` from `powershell.exe`: + +- Changed the first positional parameter from `-Command` to `-File`. + This change fixes the usage of `#!` (aka as a shebang) in PowerShell scripts that are being executed from non-PowerShell shells on non-Windows platforms. + It also means that you can run commands like `pwsh foo.ps1` or `pwsh fooScript` without specifying `-File`. + However, this change requires that you explicitly specify `-c` or `-Command` when trying to run commands like `pwsh.exe -Command Get-Command`. (#4019) +- PowerShell Core accepts the `-i` (or `-Interactive`) switch to indicate an interactive shell. (#3558) + This allows PowerShell to be used as a default shell on Unix platforms. +- Removed parameters `-importsystemmodules` and `-psconsoleFile` from `pwsh.exe`. (#4995) +- Changed `pwsh -version` and built-in help for `pwsh.exe` to align with other native tools. (#4958 & #4931) (Thanks @iSazonov) +- Invalid argument error messages for `-File` and `-Command` and exit codes consistent with Unix standards (#4573) +- Added `-WindowStyle` parameter on Windows. (#4573) + Similarly, package-based installations updates on non-Windows platforms are in-place updates. + +## Backwards compatibility with Windows PowerShell + +The goal of PowerShell Core is to remain as compatible as possible with Windows PowerShell. +PowerShell Core uses [.NET Standard][] 2.0 to provide binary compatibility with existing .NET assemblies. +Many PowerShell modules depend on these assemblies (often times DLLs), so .NET Standard allows them to continue working with .NET Core. +PowerShell Core also includes a heuristic to look in well-known folders--like where the Global Assembly Cache typically resides on disk--to find .NET Framework DLL dependencies. + +You can learn more about .NET Standard on the [.NET Blog][], in this [YouTube][] video, and via this [FAQ][] on GitHub. + +Best efforts have been made to ensure that the PowerShell language and "built-in" modules (like `Microsoft.PowerShell.Management`, `Microsoft.PowerShell.Utility`, etc.) work the same as they do in Windows PowerShell. +In many cases, with the help of the community, we've added new capabilities and bug fixes to those cmdlets. +In some cases, due to a missing dependency in underlying .NET layers, functionality was removed or is unavailable. + +Most of the modules that ship as part of Windows (for example, `DnsClient`, `Hyper-V`, `NetTCPIP`, `Storage`, etc.) and other Microsoft products including Azure and Office have not been *explicitly* ported to .NET Core yet. +The PowerShell team is working with these product groups and teams to validate and port their existing modules to PowerShell Core. +With .NET Standard and [CDXML][], many of these traditional Windows PowerShell modules do seem to work in PowerShell Core, +but they have not been formally validated, and they are not formally supported. + +By installing the [`WindowsPSModulePath`][windowspsmodulepath] module, +you can use Windows PowerShell modules by appending the Windows PowerShell `PSModulePath` to your PowerShell Core `PSModulePath`. + +First, install the `WindowsPSModulePath` module from the PowerShell Gallery: + +```powershell +# Add `-Scope CurrentUser` if you're installing as non-admin +Install-Module WindowsPSModulePath -Force +``` + +After installing this module, +run the `Add-WindowsPSModulePath` cmdlet to add the Windows PowerShell `PSModulePath` to PowerShell Core: + +```powershell +# Add this line to your profile if you always want Windows PowerShell PSModulePath +Add-WindowsPSModulePath +``` + +## Docker support + +PowerShell Core adds support for Docker containers for all the major platforms we support +(including multiple Linux distros, Windows Server Core, and Nano Server). + +For a complete list, check out the tags on [`microsoft/powershell` on Docker Hub][docker-hub]. +For more information on Docker and PowerShell Core, see [Docker][] on GitHub. + +## SSH-based PowerShell Remoting + +The PowerShell Remoting Protocol (PSRP) now works with the Secure Shell (SSH) protocol in addition to the traditional WinRM-based PSRP. + +This means that you can use cmdlets like `Enter-PSSession` and `New-PSSession` and authenticate using SSH. +All you have to do is register PowerShell as a subsystem with an OpenSSH-based SSH server, +and you can use your existing SSH-based authenticate mechanisms (like passwords or private keys) with the traditional `PSSession` semantics. + +For more information on configuring and using SSH-based remoting, +see [PowerShell Remoting over SSH][ssh-remoting]. + +## Default encoding is UTF-8 without a BOM + +In the past, Windows PowerShell cmdlets like `Get-Content`, `Set-Content` used different encodings, such as ASCII and UTF-16. +The variance in encoding defaults created problems when mixing cmdlets without specifying an encoding. + +Non-Windows platforms traditionally use UTF-8 without a Byte Order Mark (BOM) as the default encoding for text files. +More Windows applications and tools are moving away from UTF-16 and towards BOM-less UTF-8 encoding. +PowerShell Core changes the default encoding to conform with the broader ecosystems. + +This means that all built-in cmdlets that use the `-Encoding` parameter use the `UTF8NoBOM` value by default. +The following cmdlets are affected by this change: + +- Add-Content +- Export-Clixml +- Export-Csv +- Export-PSSession +- Format-Hex +- Get-Content +- Import-Csv +- New-ModuleManifest +- Out-File +- Select-String +- Send-MailMessage +- Set-Content + +These cmdlets have also been updated so that the `-Encoding` parameter universally accepts `System.Text.Encoding`. + +The default value of `$OutputEncoding` has also been changed to UTF-8. + +As a best practice, you should explicitly set encodings in scripts using the `-Encoding` parameter to produce deterministic behavior across platforms. + +## Support backgrounding of pipelines with ampersand (`&`) (#3360) + +Putting `&` at the end of a pipeline causes the pipeline to be run as a PowerShell job. +When a pipeline is backgrounded, a job object is returned. +Once the pipeline is running as a job, all of the standard `*-Job` cmdlets can be used to manage the job. +Variables (ignoring process-specific variables) used in the pipeline are automatically copied to the job so `Copy-Item $foo $bar &` just works. +The job is also run in the current directory instead of the user's home directory. +For more information about PowerShell jobs, see [about_Jobs](https://msdn.microsoft.com/powershell/reference/6/about/about_jobs). + +## Semantic versioning + +- Made `SemanticVersion` compatible with `SemVer 2.0`. (#5037) (Thanks @iSazonov!) +- Changed default `ModuleVersion` in `New-ModuleManifest` to `0.0.1` to align with SemVer. (#4842) (Thanks @LDSpits) +- Added `semver` as a type accelerator for `System.Management.Automation.SemanticVersion`. (#4142) (Thanks to @oising!) +- Enabled comparison between a `SemanticVersion` instance and a `Version` instance that is constructed only with `Major` and `Minor` version values. + +## Language updates + +- Implement Unicode escape parsing so that users can use Unicode characters as arguments, strings, or variable names. (#3958) (Thanks to @rkeithhill!) +- Added new escape character for ESC: `` `e`` +- Added support for converting enums to string (#4318) (Thanks @KirkMunro) +- Fixed casting single element array to a generic collection. (#3170) +- Added character range overload to the `..` operator, so `'a'..'z'` returns characters from 'a' to 'z'. (#5026) (Thanks @IISResetMe!) +- Fixed variable assignment to not overwrite read-only variables +- Push locals of automatic variables to 'DottedScopes' when dotting script cmdlets (#4709) +- Enable use of 'Singleline, Multiline' option in split operator (#4721) (Thanks @iSazonov) + +## Engine updates + +- `$PSVersionTable` has four new properties: + - `PSEdition`: This is set to `Core` on PowerShell Core and `Desktop` on Windows PowerShell + - `GitCommitId`: This is the Git commit ID of the Git branch or tag where PowerShell was built. + On released builds, it will likely be the same as `PSVersion`. + - `OS`: This is an OS version string returned by `[System.Environment]::OSVersion.VersionString` + - `Platform`: This is returned by `[System.Environment]::OSVersion.Platform` + It is set to `Win32NT` on Windows, `MacOSX` on macOS, and `Unix` on Linux. +- Removed the `BuildVersion` property from `$PSVersionTable`. + This property was strongly tied to the Windows build version. + Instead, we recommend that you use `GitCommitId` to retrieve the exact build version of PowerShell Core. (#3877) (Thanks to @iSazonov!) +- Remove `ClrVersion` property from `$PSVersionTable`. + This property is irrelevant for .NET Core, and was only preserved in .NET Core for specific legacy purposes that are inapplicable to PowerShell. +- Added three new automatic variables to determine whether PowerShell is running in a given OS: + `$IsWindows`, `$IsMacOs`, and `$IsLinux`. +- Add `GitCommitId` to PowerShell Core banner. + Now you don't have to run `$PSVersionTable` as soon as you start PowerShell to get the version! (#3916) (Thanks to @iSazonov!) +- Add a JSON config file called `PowerShellProperties.json` in `$PSHome` to store some settings required before startup time (e.g. `ExecutionPolicy`). +- Don't block pipeline when running Windows EXE's +- Enabled enumeration of COM collections. (#4553) + +## Cmdlet updates + +### New cmdlets + +- Add `Get-Uptime` to `Microsoft.PowerShell.Utility`. +- Add `Remove-Alias` Command. (#5143) (Thanks @PowershellNinja!) +- Add `Remove-Service` to Management module. (#4858) (Thanks @joandrsn!) + +### Web cmdlets + +- Add certificate authentication support for web cmdlets. (#4646) (Thanks @markekraus) +- Add support for content headers to web cmdlets. (#4494 & #4640) (Thanks @markekraus) +- Add multiple link header support to Web Cmdlets. (#5265) (Thanks @markekraus!) +- Support Link header pagination in web cmdlets (#3828) + - For `Invoke-WebRequest`, when the response includes a Link header we create a RelationLink property as a Dictionary representing the URLs and `rel` attributes and ensure the URLs are absolute to make it easier for the developer to use. + - For `Invoke-RestMethod`, when the response includes a Link header we expose a `-FollowRelLink` switch to automatically follow `next` `rel` links until they no longer exist or once we hit the optional `-MaximumFollowRelLink` parameter value. +- Add `-CustomMethod` parameter to web cmdlets to allow for non-standard method verbs. (#3142) (Thanks to @Lee303!) +- Add `SslProtocol` support to Web Cmdlets. (#5329) (Thanks @markekraus!) +- Add Multipart support to web cmdlets. (#4782) (Thanks @markekraus) +- Add `-NoProxy` to web cmdlets so that they ignore the system-wide proxy setting. (#3447) (Thanks to @TheFlyingCorpse!) +- User Agent of Web Cmdlets now reports the OS platform (#4937) (Thanks @LDSpits) +- Add `-SkipHeaderValidation` switch to web cmdlets to support adding headers without validating the header value. (#4085) +- Enable web cmdlets to not validate the HTTPS certificate of the server if required. +- Add authentication parameters to web cmdlets. (#5052) (Thanks @markekraus) + - Add `-Authentication` that provides three options: Basic, OAuth, and Bearer. + - Add `-Token` to get the bearer token for OAuth and Bearer options. + - Add `-AllowUnencryptedAuthentication` to bypass authentication that is provided for any transport scheme other than HTTPS. +- Add `-ResponseHeadersVariable` to `Invoke-RestMethod` to enable the capture of response headers. (#4888) (Thanks @markekraus) +- Fix web cmdlets to include the HTTP response in the exception when the response status code is not success. (#3201) +- Change web cmdlets `UserAgent` from `WindowsPowerShell` to `PowerShell`. (#4914) (Thanks @markekraus) +- Add explicit `ContentType` detection to `Invoke-RestMethod` (#4692) +- Fix web cmdlets `-SkipHeaderValidation` to work with non-standard User-Agent headers. (#4479 & #4512) (Thanks @markekraus) + +### JSON cmdlets + +- Add `-AsHashtable` to `ConvertFrom-Json` to return a `Hashtable` instead. (#5043) (Thanks @bergmeister!) +- Use prettier formatter with `ConvertTo-Json` output. (#2787) (Thanks to @kittholland!) +- Add `Jobject` serialization support to `ConvertTo-Json`. (#5141) +- Fix `ConvertFrom-Json` to deserialize an array of strings from the pipeline that together construct a complete JSON string. + This fixes some cases where newlines would break JSON parsing. (#3823) +- Remove the `AliasProperty "Count"` defined for `System.Array`. + This removes the extraneous `Count` property on some `ConvertFrom-Json` output. (#3231) (Thanks to @PetSerAl!) + +### CSV cmdlets + +- Add `PSTypeName` Support for `Import-Csv` and `ConvertFrom-Csv`. (#5389) (Thanks @markekraus!) +- Make `Import-Csv` support `CR`, `LF`, and `CRLF` as line delimiters. (#5363) (Thanks @iSazonov!) +- Make `-NoTypeInformation` the default on `Export-Csv` and `ConvertTo-Csv`. (#5164) (Thanks @markekraus) + +### Service cmdlets + +- Add properties `UserName`, `Description`, `DelayedAutoStart`, `BinaryPathName`, and `StartupType` to the `ServiceController` objects returned by `Get-Service`. (#4907) (Thanks @joandrsn) +- Add functionality to set credentials on `Set-Service` command. (#4844) (Thanks @joandrsn) + +### Other cmdlets + +- Add a parameter to `Get-ChildItem` called `-FollowSymlink` that traverses symlinks on demand, with checks for link loops. (#4020) +- Update `Add-Type` to support `CSharpVersion7`. (#3933) (Thanks to @iSazonov) +- Remove the `Microsoft.PowerShell.LocalAccounts` module due to the use of unsupported APIs until a better solution is found. (#4302) +- Remove the `*-Counter` cmdlets in `Microsoft.PowerShell.Diagnostics` due to the use of unsupported APIs until a better solution is found. (#4303) +- Add support for `Invoke-Item -Path `. (#4262) +- Add `-Extension` and `-LeafBase` switches to `Split-Path` so that you can split paths between the filename extension and the rest of the filename. (#2721) (Thanks to @powercode!) +- Add parameters `-Top` and `-Bottom` to `Sort-Object` for Top/Bottom N sort +- Expose a process' parent process by adding the `CodeProperty "Parent"` to `System.Diagnostics.Process`. (#2850) (Thanks to @powercode!) +- Use MB instead of KB for memory columns of `Get-Process` +- Add `-NoNewLine` switch for `Out-String`. (#5056) (Thanks @raghav710) +- `Move-Item` cmdlet honors `-Include`, `-Exclude`, and `-Filter` parameters. (#3878) +- Allow `*` to be used in registry path for `Remove-Item`. (#4866) +- Add `-Title` to `Get-Credential` and unify the prompt experience across platforms. +- Add the `-TimeOut` parameter to `Test-Connection`. (#2492) +- `Get-AuthenticodeSignature` cmdlets can now get file signature timestamp. (#4061) +- Remove unsupported `-ShowWindow` switch from `Get-Help`. (#4903) +- Fix `Get-Content -Delimiter` to not include the delimiter in the array elements returned (#3706) (Thanks @mklement0) +- Add `Meta`, `Charset`, and `Transitional` parameters to `ConvertTo-HTML` (#4184) (Thanks @ergo3114) +- Add `WindowsUBR` and `WindowsVersion` properties to `Get-ComputerInfo` result +- Add `-Group` parameter to `Get-Verb` +- Add `ShouldProcess` support to `New-FileCatalog` and `Test-FileCatalog` (fixes `-WhatIf` and `-Confirm`). (#3074) (Thanks to @iSazonov!) +- Add `-WhatIf` switch to `Start-Process` cmdlet (#4735) (Thanks @sarithsutha) +- Add `ValidateNotNullOrEmpty` too many existing parameters. + +## Tab completion + +- Enhanced the type inference in tab completion based on runtime variable values. (#2744) (Thanks to @powercode!) + This enables tab completion in situations like: + + ```powershell + $p = Get-Process + $p | Foreach-Object Prio + ``` + +- Add Hashtable tab completion for `-Property` of `Select-Object`. (#3625) (Thanks to @powercode) +- Enable argument auto-completion for `-ExcludeProperty` and `-ExpandProperty` of `Select-Object`. (#3443) (Thanks to @iSazonov!) +- Fix a bug in tab completion to make `native.exe --` call into native completer. (#3633) (Thanks to @powercode!) + +## Breaking changes + +We've introduced a number of breaking changes in PowerShell Core 6.0. +To read more about them in detail, see [Breaking Changes in PowerShell Core 6.0][breaking-changes]. + +## Debugging + +- Support for remote step-in debugging for `Invoke-Command -ComputerName`. (#3015) +- Enable binder debug logging in PowerShell Core + +## Filesystem updates + +- Enable usage of the Filesystem provider from a UNC path. ($4998) +- `Split-Path` now works with UNC roots +- `cd` with no arguments now behaves as `cd ~` +- Fixed PowerShell Core to allow use of paths that are more than 260 characters long. (#3960) + +## Bug fixes and performance improvements + +We've made *many* improvements to performance across PowerShell, +including in startup time, various built-in cmdlets, and interaction with native binaries. + +We've also fixed a number of bugs within PowerShell Core. +For a complete list of fixes and changes, check out our [changelog][] on GitHub. + +## Telemetry + +- PowerShell Core 6.0 added telemetry to the console host to report two values (#3620): + - the OS platform (`$PSVersionTable.OSDescription`) + - the exact version of PowerShell (`$PSVersionTable.GitCommitId`) + +If you want to opt-out of this telemetry, simply delete `$PSHome\DELETE_ME_TO_DISABLE_CONSOLEHOST_TELEMETRY`. +Deleting this file bypasses all telemetry even before the first run of PowerShell. +We also plan on exposing this telemetry data and the insights we glean from the telemetry in the [community dashboard][community-dashboard]. +You can find out more about how we use this data in this [blog post][telemetry-blog]. + +[github]: https://github.com/PowerShell/PowerShell +[.NET Core 2.0]: https://docs.microsoft.com/en-us/dotnet/core/ +[.NET Standard]: https://docs.microsoft.com/en-us/dotnet/standard/net-standard +[os_log]: https://developer.apple.com/documentation/os/logging +[Syslog]: https://en.wikipedia.org/wiki/Syslog +[ssh-remoting]: ../core-powershell/SSH-Remoting-in-PowerShell-Core.md +[breaking-changes]: https://github.com/PowerShell/PowerShell/tree/master/docs/BREAKINGCHANGES.md +[changelog]: https://github.com/PowerShell/PowerShell/tree/master/CHANGELOG.md +[community-dashboard]: https://aka.ms/PSGitHubBI +[telemetry-blog]: https://blogs.msdn.microsoft.com/powershell/2017/01/31/powershell-open-source-community-dashboard/ +[.NET Standard]: https://docs.microsoft.com/dotnet/standard/net-standard +[.NET Blog]: https://blogs.msdn.microsoft.com/dotnet/2016/09/26/introducing-net-standard +[YouTube]: https://www.youtube.com/watch?v=YI4MurjfMn8&list=PLRAdsfhKI4OWx321A_pr-7HhRNk7wOLLY +[FAQ]: https://github.com/dotnet/standard/blob/master/docs/faq.md +[CDXML]: https://msdn.microsoft.com/en-us/library/jj542525(v=vs.85).aspx +[docker-hub]: https://hub.docker.com/r/microsoft/powershell/ +[docker]: https://github.com/PowerShell/PowerShell/tree/master/docker +[windowspsmodulepath]: https://www.powershellgallery.com/packages/WindowsPSModulePath/ +[semi-annual]: https://docs.microsoft.com/windows-server/get-started/semi-annual-channel-overview \ No newline at end of file From 4e8ebb8fab06abdab6b78c3d60ed5231936df43e Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 10 Jan 2018 14:39:55 -0800 Subject: [PATCH 167/188] update TOC and change title of setup mac/linux article (#2030) * update TOC and change title of setup mac/linux article * fix typos --- ...ling-PowerShell-Core-on-macOS-and-Linux.md | 2 +- reference/docs-conceptual/toc.yml | 41 +++++++++++++------ 2 files changed, 29 insertions(+), 14 deletions(-) diff --git a/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md index a3e31810d9ea..86733b995deb 100644 --- a/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md +++ b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS-and-Linux.md @@ -1,4 +1,4 @@ -# Package installation instructions +# Installing PowerShell Core on macOS and Linux Supports [Ubuntu 14.04][u14], [Ubuntu 16.04][u16], [Ubuntu 17.04][u17], [Debian 8][deb8], [Debian 9][deb9], [CentOS 7][cos], [Red Hat Enterprise Linux (RHEL) 7][rhel7], [OpenSUSE 42.2][opensuse], [Fedora 25][fed25], diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index a221257a4bd2..ef6d0676491c 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -1,4 +1,4 @@ -- name: Conceptual +- name: Conceptual href: PowerShell-Scripting.md items: - name: Core PowerShell @@ -72,8 +72,17 @@ href: core-powershell/ise/windows-powershell-ise-object-model-reference.md - name: ISE Guide href: core-powershell/ise-guide.md + - name: Visual Studio Code + items: + - name: Using Visual Studio Code + href: core-powershell/vscode/using-vscode.md - name: Running Remote Commands href: core-powershell/running-remote-commands.md + items: + - name: PowerShell Remoting Over SSH + href: core-powershell/SSH-Remoting-in-PowerShell-Core.md + - name: WS-Management (WSMan) Remoting in PowerShell Core + href: core-powershell/WSMan-Remoting-in-PowerShell-Core.md - name: Web Access href: core-powershell/web-access.md items: @@ -105,13 +114,13 @@ href: getting-started/cookbooks/changing-computer-state.md - name: Collecting Information About Computers href: getting-started/cookbooks/collecting-information-about-computers.md - - name: Creating .NET and COM Objects New Object + - name: Creating .NET and COM Objects New Object href: getting-started/cookbooks/creating-.net-and-com-objects--new-object-.md - name: Creating a Custom Input Box href: getting-started/cookbooks/creating-a-custom-input-box.md - name: Creating a Graphical Date Picker href: getting-started/cookbooks/creating-a-graphical-date-picker.md - - name: Getting WMI Objects Get WmiObject + - name: Getting WMI Objects Get WmiObject href: getting-started/cookbooks/getting-wmi-objects--get-wmiobject-.md - name: Managing Current Location href: getting-started/cookbooks/managing-current-location.md @@ -131,13 +140,13 @@ href: getting-started/cookbooks/performing-networking-tasks.md - name: Redirecting Data with Out Cmdlets href: getting-started/cookbooks/redirecting-data-with-out---cmdlets.md - - name: Removing Objects from the Pipeline Where Object + - name: Removing Objects from the Pipeline Where Object href: getting-started/cookbooks/removing-objects-from-the-pipeline--where-object-.md - - name: Repeating a Task for Multiple Objects ForEach Object + - name: Repeating a Task for Multiple Objects ForEach Object href: getting-started/cookbooks/repeating-a-task-for-multiple-objects--foreach-object-.md - name: Selecting Items from a List Box href: getting-started/cookbooks/selecting-items-from-a-list-box.md - - name: Selecting Parts of Objects Select Object + - name: Selecting Parts of Objects Select Object href: getting-started/cookbooks/selecting-parts-of-objects--select-object-.md - name: Sorting Objects href: getting-started/cookbooks/sorting-objects.md @@ -145,7 +154,7 @@ href: getting-started/cookbooks/using-format-commands-to-change-output-view.md - name: Using Static Classes and Methods href: getting-started/cookbooks/using-static-classes-and-methods.md - - name: Viewing Object Structure Get Member + - name: Viewing Object Structure Get Member href: getting-started/cookbooks/viewing-object-structure--get-member-.md - name: Working with Files and Folders href: getting-started/cookbooks/working-with-files-and-folders.md @@ -192,7 +201,7 @@ href: getting-started/fundamental/using-windows-powershell-for-administration.md - name: Windows PowerShell Basics href: getting-started/fundamental/windows-powershell-basics.md - - name: Windows PowerShell Integrated Scripting Environment ISE + - name: Windows PowerShell Integrated Scripting Environment ISE href: getting-started/fundamental/windows-powershell-integrated-scripting-environment--ise-.md - name: Fundamental Concepts href: getting-started/fundamental-concepts.md @@ -207,6 +216,10 @@ - name: Setup href: '' items: + - name: Installing PowerShell Core on Windows + href: setup/Installing-PowerShell-Core-on-Windows.md + - name: Installing PowerShell Core on macOS and Linux + href: setup/Installing-PowerShell-Core-on-macOS-and-Linux.md - name: Accessibility in Windows PowerShell ISE href: setup/accessibility-in-windows-powershell-ise.md - name: Installing the Windows PowerShell 2.0 Engine @@ -234,12 +247,14 @@ - name: What's New href: '' items: - - name: What's New in the PowerShell 50 ISE - href: whats-new/what-s-new-in-the-powershell-50-ise.md - - name: What's New in Windows PowerShell 50 - href: whats-new/what-s-new-in-windows-powershell-50.md - - name: What's New With PowerShell + - name: What's new with PowerShell href: whats-new/what-s-new-with-powershell.md + - name: What's new in Windows PowerShell 5.0 + href: whats-new/what-s-new-in-windows-powershell-50.md + - name: What's new in the PowerShell 5.0 ISE + href: whats-new/what-s-new-in-the-powershell-50-ise.md + - name: What's new in PowerShell Core 6.0 + href: whats-new/what-s-new-in-powershell-core-60.md - name: PowerShell Core Support Lifecycle href: PowerShell-Core-Support.md - name: Glossary From 436a35af90c3039d0de2ff41b4602987abc21dda Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 10 Jan 2018 17:25:37 -0800 Subject: [PATCH 168/188] attempt to fix images (#2033) * attempt to fix images * update to docfx to support images --- dsc/docfx.json | 3 ++- .../core-powershell/vscode/using-vscode.md | 2 +- reference/docs-conceptual/docfx.json | 4 +++- .../{core-powershell/vscode => images}/vscode.png | Bin 4 files changed, 6 insertions(+), 3 deletions(-) rename reference/docs-conceptual/{core-powershell/vscode => images}/vscode.png (100%) diff --git a/dsc/docfx.json b/dsc/docfx.json index 723ddcc7b52b..8a0ca570ced8 100644 --- a/dsc/docfx.json +++ b/dsc/docfx.json @@ -20,7 +20,8 @@ "manager": "carmonm", "ms.devlang": "powershell", "ms.tgt_pltfr": "windows", - "ms.author": "sewhee" + "ms.author": "migreene", + "author": "mgreenegit" }, "resource": [ { diff --git a/reference/docs-conceptual/core-powershell/vscode/using-vscode.md b/reference/docs-conceptual/core-powershell/vscode/using-vscode.md index 0979a7139701..3219cdf53920 100644 --- a/reference/docs-conceptual/core-powershell/vscode/using-vscode.md +++ b/reference/docs-conceptual/core-powershell/vscode/using-vscode.md @@ -42,7 +42,7 @@ For traditional Windows PowerShell workloads, see [Installing Windows PowerShell - The **Extensions** view will open on the Side Bar. Select the PowerShell extension from Microsoft. You will see something like below: - ![VSCode](./vscode.png) + ![VSCode](../../images/vscode.png) - Click the **Install** button on the PowerShell extension from Microsoft. - After the install, you will see the **Install** button turns to **Reload**. diff --git a/reference/docs-conceptual/docfx.json b/reference/docs-conceptual/docfx.json index a557e8d563cb..26221736b294 100644 --- a/reference/docs-conceptual/docfx.json +++ b/reference/docs-conceptual/docfx.json @@ -22,7 +22,9 @@ "resource": [ { "files": [ - "**/images/**" + "**/images/**", + "**/*.png", + "**/*.jpg" ], "exclude": ["**/obj/**"] } diff --git a/reference/docs-conceptual/core-powershell/vscode/vscode.png b/reference/docs-conceptual/images/vscode.png similarity index 100% rename from reference/docs-conceptual/core-powershell/vscode/vscode.png rename to reference/docs-conceptual/images/vscode.png From 491970b980ada02c11195153368346f9706a0e11 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 11 Jan 2018 10:41:20 -0800 Subject: [PATCH 169/188] Update docfx to add image support (#2040) * attempt to fix images * update to docfx to support images * update root docfx for images * update docfx for image support --- reference/docfx.json | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/reference/docfx.json b/reference/docfx.json index a8365f764236..26f9531542e7 100644 --- a/reference/docfx.json +++ b/reference/docfx.json @@ -1,7 +1,6 @@ { "build": { - "content": [ - { + "content": [{ "files": [ "bread-pscore/toc.yml" ] @@ -196,18 +195,19 @@ "dest": "module" } ], - "resource": [ - { - "files": [ - "**/*.png", - "**/*.jpg" - ], - "exclude": [ - "**/obj/**", - "**/includes/**" - ] - } - ], + "resource": [{ + "files": [ + "**/images/**/*.png", + "**/images/**/*.jpg", + "**/images/**/*.jpeg", + "**/images/**/*.gif", + "**/images/**/*.svg" + ], + "exclude": [ + "**/obj/**", + "**/includes/**" + ] + }], "versions": { "powershell-3.0": { "dest": "powershell-3.0" @@ -245,4 +245,4 @@ "template": [], "dest": "pscore-reference" } -} +} \ No newline at end of file From 7eb981463a4512c81ae53bca558206d5a7541a29 Mon Sep 17 00:00:00 2001 From: Thomas Lee Date: Thu, 11 Jan 2018 23:01:19 +0000 Subject: [PATCH 170/188] Update Installing-PowerShell-Core-on-Windows.md (#2042) The original paged rendered badly - this edit is a move of a 'to do' comment in the MD so as to not break the sentence. --- .../setup/Installing-PowerShell-Core-on-Windows.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md index 4d7eb338bd86..a88579a5e3e9 100644 --- a/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md +++ b/reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md @@ -3,9 +3,10 @@ ## MSI To install PowerShell on a Windows client or Windows Server (works on Windows 7 SP1, Server 2008 R2, and later), download the MSI package from - our GitHub [releases][] page. + The MSI file looks like this - `PowerShell-6.0.0...msi` + Once downloaded, double-click the installer and follow the prompts. From 18fedf7ea6d54a93a2b161846449550b2f8efda6 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Fri, 12 Jan 2018 08:06:14 +0900 Subject: [PATCH 171/188] Fix $PSVersionTable.OS in What's New 6.0 (#2039) $PSVersionTable.OS is: x [System.Environment]::OSVersion.VersionString o [System.Runtime.InteropServices.RuntimeInformation]::OSDescription --- .../whats-new/What-s-New-in-PowerShell-Core-60.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md index 81b2d64ff4da..8b2a5edecb44 100644 --- a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md @@ -236,7 +236,7 @@ For more information about PowerShell jobs, see [about_Jobs](https://msdn.micros - `PSEdition`: This is set to `Core` on PowerShell Core and `Desktop` on Windows PowerShell - `GitCommitId`: This is the Git commit ID of the Git branch or tag where PowerShell was built. On released builds, it will likely be the same as `PSVersion`. - - `OS`: This is an OS version string returned by `[System.Environment]::OSVersion.VersionString` + - `OS`: This is an OS version string returned by `[System.Runtime.InteropServices.RuntimeInformation]::OSDescription` - `Platform`: This is returned by `[System.Environment]::OSVersion.Platform` It is set to `Win32NT` on Windows, `MacOSX` on macOS, and `Unix` on Linux. - Removed the `BuildVersion` property from `$PSVersionTable`. From 6026e8d12e589cba3bf210df5c970b91d40dd401 Mon Sep 17 00:00:00 2001 From: Andrew Palmer Date: Thu, 11 Jan 2018 23:07:17 +0000 Subject: [PATCH 172/188] Update WSMan-Remoting-in-PowerShell-Core.md (#2038) The current example doesn't work for me when specifying the full file path. It just outputs the file location rather than running the script. I had to move to the location of the file and run it from there. The parameter PowerShellVersion also doesn't appear to exist anymore so I have removed that. I've also changes file paths to match the 6.0.0 GA release rather than the previous alpha 9. --- .../core-powershell/WSMan-Remoting-in-PowerShell-Core.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/reference/docs-conceptual/core-powershell/WSMan-Remoting-in-PowerShell-Core.md b/reference/docs-conceptual/core-powershell/WSMan-Remoting-in-PowerShell-Core.md index 41021451931d..93e0eff36c53 100644 --- a/reference/docs-conceptual/core-powershell/WSMan-Remoting-in-PowerShell-Core.md +++ b/reference/docs-conceptual/core-powershell/WSMan-Remoting-in-PowerShell-Core.md @@ -35,13 +35,14 @@ Install-PowerShellRemoting.ps1 #### Executed by another instance of PowerShell on behalf of the instance that it will register ``` powershell -\Install-PowerShellRemoting.ps1 -PowerShellHome "" -PowerShellVersion "" +\Install-PowerShellRemoting.ps1 -PowerShellHome "" ``` For Example: ``` powershell -C:\Program Files\PowerShell\6.0.0.9\Install-PowerShellRemoting.ps1 -PowerShellHome "C:\Program Files\PowerShell\6.0.0.9\" -PowerShellVersion "6.0.0-alpha.9" +Set-Location -Path 'C:\Program Files\PowerShell\6.0.0\' +.\Install-PowerShellRemoting.ps1 -PowerShellHome "C:\Program Files\PowerShell\6.0.0\" ``` **NOTE:** The remoting registration script will restart WinRM, so all existing PSRP sessions will terminate immediately after the script is run. If run during a remote session, this will terminate the connection. @@ -51,8 +52,8 @@ C:\Program Files\PowerShell\6.0.0.9\Install-PowerShellRemoting.ps1 -PowerShellHo Create a PowerShell session to the new PowerShell endpoint by specifying `-ConfigurationName "some endpoint name"`. To connect to the PowerShell instance from the example above, use either: ``` powershell -New-PSSession ... -ConfigurationName "powershell.6.0.0-alpha.9" -Enter-PSSession ... -ConfigurationName "powershell.6.0.0-alpha.9" +New-PSSession ... -ConfigurationName "powershell.6.0.0" +Enter-PSSession ... -ConfigurationName "powershell.6.0.0" ``` Note that `New-PSSession` and `Enter-PSSession` invocations that do not specify `-ConfigurationName` will target the default PowerShell endpoint, `microsoft.powershell`. From 2947472ab155685cf2648ad7ef7ec843ebe6901c Mon Sep 17 00:00:00 2001 From: Josh Rickard Date: Thu, 11 Jan 2018 18:09:24 -0500 Subject: [PATCH 173/188] Update Get-FormatData.md (#2034) Updated Get-FormatData Markdown. Fixes #1895 --- .../Get-FormatData.md | 104 +++++++++++++++--- 1 file changed, 88 insertions(+), 16 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Get-FormatData.md b/reference/5.1/Microsoft.PowerShell.Utility/Get-FormatData.md index da166c6085be..7a12bf36d3cd 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Get-FormatData.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Get-FormatData.md @@ -39,41 +39,64 @@ PS C:\> Get-FormatData This command gets all the formatting data in the session. ### Example 2: Get formatting data by type name -``` -PS C:\> Get-FormatData -TypeName "Microsoft.Wsman*" +```powershell +PS C:\> Get-FormatData -TypeName 'System.Management.Automation.Cmd*' ``` -This command gets the formatting data items whose names begin with Microsoft.Wsman. +This command gets the formatting data items whose names begin with System.Management.Automation.Cmd*. ### Example 3: Examine a formatting data object -``` -PS C:\> $F = Get-FormatData -TypeName helpinfoshort +```powershell +PS C:\> $F = Get-FormatData -TypeName 'System.Management.Automation.Cmd*' PS C:\> $F +``` +```Output TypeName FormatViewDefinition -------- -------------------- -HelpInfoShort {help , TableControl} PS C:\> $F.FormatViewDefinition[0].control -Headers Rows -------- ---- -{System.Management.Automation.TableControlColumnHeader, System.Manageme... {System.Management.Automation.TableControlRow} PS C:\> $F.FormatViewDefinition[0].control.headers -Label Alignment Width ------ --------- ----- -Name Left 33 -Category Left 9 -Undefined 0 +HelpInfoShort {help , TableControl} +``` +```powershell +PS C:\> $F.FormatViewDefinition[0].control +``` +```Output +Headers : {System.Management.Automation.TableControlColumnHeader, System.Management.Automation.TableControlColumnHeader, System.Management.Automation.TableControlColumnHeader, + System.Management.Automation.TableControlColumnHeader} +Rows : {System.Management.Automation.TableControlRow} +AutoSize : False +HideTableHeaders : False +GroupBy : +OutOfBand : False +``` +```powershell +PS C:\> $F.FormatViewDefinition[0].control.Headers +``` +```Output +Label Alignment Width +----- --------- ----- +CommandType Undefined 15 +Name Undefined 50 +Version Undefined 10 +Source Undefined 0 ``` This example shows how to get a formatting data object and examine its properties. ### Example 4: Get formatting data and export it -``` +```powershell PS C:\> $A = Get-FormatData PS C:\> Import-Module bitstransfer PS C:\> $B = Get-FormatData PS C:\> Compare-Object $A $B +``` +```Output InputObject SideIndicator ----------- ------------- Microsoft.BackgroundIntelligentTransfer.Management.BitsJob => PS C:\> Get-FormatData *bits* | Export-FormatData -FilePath c:\test\bits.format.ps1xml +``` +```powershell PS C:\> Get-Content c:\test\bits.format.ps1xml +``` +```Output Microsoft.BackgroundIntelligentTransfer.Management.BitsJob ... @@ -88,10 +111,59 @@ It uses a pipeline operator (|) to send the format type object to the Export-For The final command shows an excerpt of the format.ps1xml file content. +### Example 5: Get formatting data based on the specified version of PowerShell +```powershell +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 1.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 2.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 3.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 4.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 5.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 5.1 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 6.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} +``` + +This example shows how to use **Get-FormatData** to get format data for a specified TypeName and a +specified PowerShell version. + ## PARAMETERS ### -PowerShellVersion - +Specify the version of PowerShell this cmdlet gets for the formatting data. +Enter a two digit number seperated by a period. ```yaml Type: Version From b50733078f25c6b4f25974af501c92361e9fdcee Mon Sep 17 00:00:00 2001 From: Josh Rickard Date: Thu, 11 Jan 2018 18:09:37 -0500 Subject: [PATCH 174/188] Update Get-FormatData Markdown (#2035) Updated Get-FormatData Markdown. Fixes #1895 --- .../Get-FormatData.md | 104 +++++++++++++++--- 1 file changed, 88 insertions(+), 16 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Utility/Get-FormatData.md b/reference/6/Microsoft.PowerShell.Utility/Get-FormatData.md index 788d1a6b930d..7417a15ef22f 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Get-FormatData.md +++ b/reference/6/Microsoft.PowerShell.Utility/Get-FormatData.md @@ -40,41 +40,64 @@ PS C:\> Get-FormatData This command gets all the formatting data in the session. ### Example 2: Get formatting data by type name -``` -PS C:\> Get-FormatData -TypeName "Microsoft.Wsman*" +```powershell +PS C:\> Get-FormatData -TypeName 'System.Management.Automation.Cmd*' ``` -This command gets the formatting data items whose names begin with Microsoft.Wsman. +This command gets the formatting data items whose names begin with System.Management.Automation.Cmd*. ### Example 3: Examine a formatting data object -``` -PS C:\> $F = Get-FormatData -TypeName helpinfoshort +```powershell +PS C:\> $F = Get-FormatData -TypeName 'System.Management.Automation.Cmd*' PS C:\> $F +``` +```Output TypeName FormatViewDefinition -------- -------------------- -HelpInfoShort {help , TableControl} PS C:\> $F.FormatViewDefinition[0].control -Headers Rows -------- ---- -{System.Management.Automation.TableControlColumnHeader, System.Manageme... {System.Management.Automation.TableControlRow} PS C:\> $F.FormatViewDefinition[0].control.headers -Label Alignment Width ------ --------- ----- -Name Left 33 -Category Left 9 -Undefined 0 +HelpInfoShort {help , TableControl} +``` +```powershell +PS C:\> $F.FormatViewDefinition[0].control +``` +```Output +Headers : {System.Management.Automation.TableControlColumnHeader, System.Management.Automation.TableControlColumnHeader, System.Management.Automation.TableControlColumnHeader, + System.Management.Automation.TableControlColumnHeader} +Rows : {System.Management.Automation.TableControlRow} +AutoSize : False +HideTableHeaders : False +GroupBy : +OutOfBand : False +``` +```powershell +PS C:\> $F.FormatViewDefinition[0].control.Headers +``` +```Output +Label Alignment Width +----- --------- ----- +CommandType Undefined 15 +Name Undefined 50 +Version Undefined 10 +Source Undefined 0 ``` This example shows how to get a formatting data object and examine its properties. ### Example 4: Get formatting data and export it -``` +```powershell PS C:\> $A = Get-FormatData PS C:\> Import-Module bitstransfer PS C:\> $B = Get-FormatData PS C:\> Compare-Object $A $B +``` +```Output InputObject SideIndicator ----------- ------------- Microsoft.BackgroundIntelligentTransfer.Management.BitsJob => PS C:\> Get-FormatData *bits* | Export-FormatData -FilePath c:\test\bits.format.ps1xml +``` +```powershell PS C:\> Get-Content c:\test\bits.format.ps1xml +``` +```Output Microsoft.BackgroundIntelligentTransfer.Management.BitsJob ... @@ -89,6 +112,54 @@ It uses a pipeline operator (|) to send the format type object to the Export-For The final command shows an excerpt of the format.ps1xml file content. +### Example 5: Get formatting data based on the specified version of PowerShell +```powershell +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 1.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 2.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 3.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 4.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 5.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 5.1 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} + +PS C:\> Get-FormatData -TypeName 'Microsoft.Powershell.Utility.FileHash' -PowerShellVersion 6.0 + +TypeNames FormatViewDefinition +--------- -------------------- +{Microsoft.Powershell.Utility.FileHash} {Microsoft.Powershell.Utility.FileHash} +``` + +This example shows how to use **Get-FormatData** to get format data for a specified TypeName and a +specified PowerShell version. + ## PARAMETERS ### -InformationAction @@ -136,7 +207,8 @@ Accept wildcard characters: False ``` ### -PowerShellVersion - +Specify the version of PowerShell this cmdlet gets for the formatting data. +Enter a two digit number seperated by a period. ```yaml Type: Version From c2ffb264a029d8b052f93e62e4cef6d23eedbac2 Mon Sep 17 00:00:00 2001 From: Josh Rickard Date: Thu, 11 Jan 2018 18:11:43 -0500 Subject: [PATCH 175/188] Updated Get-Runspace Help (#2032) Updated Get-Runspace Markdown. Fixes #1883 --- .../Get-Runspace.md | 55 +++++++++++++++++-- 1 file changed, 50 insertions(+), 5 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Get-Runspace.md b/reference/5.1/Microsoft.PowerShell.Utility/Get-Runspace.md index 252801918821..7e0602696d6d 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Get-Runspace.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Get-Runspace.md @@ -11,7 +11,7 @@ title: Get-Runspace # Get-Runspace ## SYNOPSIS -Gets active runspaces within a Windows PowerShellhost process. +Gets active runspaces within a Windows PowerShell host process. ## SYNTAX @@ -35,20 +35,62 @@ The **Get-Runspace** cmdlet gets active runspaces in a Windows PowerShell host p ## EXAMPLES -### 1: +### Example 1: Get runspaces +```powershell +PS C:\> Get-Runspace ``` +```Output + Id Name ComputerName Type State Availability + -- ---- ------------ ---- ----- ------------ + 1 Runspace1 localhost Local Opened Busy + 2 Runspace2 localhost Local Opened Available + 3 Runspace3 localhost Local Opened Available ``` -### 2: +### Example 2: Get runspace by Id +```powershell +PS C:\> Get-Runspace -Id 2 ``` +```Output + Id Name ComputerName Type State Availability + -- ---- ------------ ---- ----- ------------ + 2 Runspace2 localhost Local Opened Available ``` +### Example 3: Get runspace by Name +```powershell +PS C:\> Get-Runspace -Name Runspace1 +``` + +```Output + Id Name ComputerName Type State Availability + -- ---- ------------ ---- ----- ------------ + 1 Runspace1 localhost Local Opened Busy +``` + +### Example 4: Get runspace by InstanceId +```powershell +PS C:\> $activeRunspace = Get-Runspace -Name Runspace1 + +PS C:\> Get-Runspace -InstanceId $activeRunspace.InstanceId +``` + +```Output + Id Name ComputerName Type State Availability + -- ---- ------------ ---- ----- ------------ + 1 Runspace1 localhost Local Opened Busy +``` + +In this example, we identify an available runspace using the `Name` parameter and we store the return object to a new +variable named `$activeRunspace`. The second example, we call `Get-Runspace` with the `InstanceId` parameter and pass +in the `$activeRunspace` variable but we specify the `InstanceId` property on our reuturn object. + ## PARAMETERS ### -Id - +Specifies the Id of a runspace ```yaml Type: Int32[] @@ -78,7 +120,7 @@ Accept wildcard characters: False ``` ### -Name - +Specifies the Name of a runspace ```yaml Type: String[] @@ -99,6 +141,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS +### System.Management.Automation.Runspaces.RunspaceBase +You can pipe the results of a **Get-Runspace** command to **Debug-Runspace**. + ## NOTES ## RELATED LINKS From cebcd52f9f82354e4a7600d21f0e10cb41b1d18b Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 11 Jan 2018 15:20:16 -0800 Subject: [PATCH 176/188] updated docfx to try to fix images (#2043) * attempt to fix images * update to docfx to support images * update root docfx for images * update docfx for image support * update docfx for images --- reference/docfx.json | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/reference/docfx.json b/reference/docfx.json index 26f9531542e7..6379956cb5a9 100644 --- a/reference/docfx.json +++ b/reference/docfx.json @@ -195,19 +195,19 @@ "dest": "module" } ], - "resource": [{ - "files": [ - "**/images/**/*.png", - "**/images/**/*.jpg", - "**/images/**/*.jpeg", - "**/images/**/*.gif", - "**/images/**/*.svg" - ], - "exclude": [ - "**/obj/**", - "**/includes/**" - ] - }], + "resource": [ + { + "files": [ + "**/images/**", + "**/*.png", + "**/*.jpg" + ], + "exclude": [ + "**/obj/**", + "**/includes/**" + ] + } + ], "versions": { "powershell-3.0": { "dest": "powershell-3.0" From 81a2dda5553dc96c69c0c3441ae56e242e675a7b Mon Sep 17 00:00:00 2001 From: Qinen Zhu Date: Fri, 12 Jan 2018 11:58:05 +0800 Subject: [PATCH 177/188] Add resource per version in docfx.json (#2046) --- reference/docfx.json | 62 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/reference/docfx.json b/reference/docfx.json index 6379956cb5a9..04bbc9671568 100644 --- a/reference/docfx.json +++ b/reference/docfx.json @@ -206,6 +206,66 @@ "**/obj/**", "**/includes/**" ] + }, + { + "files": [ + "**/images/**", + "**/*.png", + "**/*.jpg" + ], + "exclude": [ + "**/obj/**", + "**/includes/**" + ], + "version": "powershell-3.0" + }, + { + "files": [ + "**/images/**", + "**/*.png", + "**/*.jpg" + ], + "exclude": [ + "**/obj/**", + "**/includes/**" + ], + "version": "powershell-4.0" + }, + { + "files": [ + "**/images/**", + "**/*.png", + "**/*.jpg" + ], + "exclude": [ + "**/obj/**", + "**/includes/**" + ], + "version": "powershell-5.0" + }, + { + "files": [ + "**/images/**", + "**/*.png", + "**/*.jpg" + ], + "exclude": [ + "**/obj/**", + "**/includes/**" + ], + "version": "powershell-5.1" + }, + { + "files": [ + "**/images/**", + "**/*.png", + "**/*.jpg" + ], + "exclude": [ + "**/obj/**", + "**/includes/**" + ], + "version": "powershell-6" } ], "versions": { @@ -245,4 +305,4 @@ "template": [], "dest": "pscore-reference" } -} \ No newline at end of file +} From a98db07f27f9cda5638d3398c00473fb27cd35d7 Mon Sep 17 00:00:00 2001 From: Dongbo Wang Date: Fri, 12 Jan 2018 12:39:00 -0800 Subject: [PATCH 178/188] Change 'PowerShellProperties.json' to 'powershell.config.json' in about_logging (#2050) --- reference/6/Microsoft.PowerShell.Core/About/about_Logging.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md index f22df57b0193..463b605af0b0 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md @@ -148,7 +148,7 @@ sudo log stream --predicate 'process == "pwsh"' --info On Windows, logging is configured by creating ETW trace listeners or by using the Event Viewer to enable Analytic logging. On Linux and MacOS, logging is -configured using the file `PowerShellProperties.json`. The rest of this section +configured using the file `powershell.config.json`. The rest of this section will discuss configuring PowerShell logging on non-Windows system. By default, PowerShell enables informational logging to the operational @@ -157,7 +157,7 @@ marked as operational and has a log (trace) level greater then informational will be logged. Occasionally, diagnoses may require additional log output, such as verbose log output or enabling analytic log output. -The file `PowerShellProperties.json` is a JSON formatted file residing in the +The file `powershell.config.json` is a JSON formatted file residing in the PowerShell $PSHOME directory. Each installation of PowerShell uses it's own copy of this file. For normal operation, this file is left unchanged but it can be useful for diagnosis or for distinguishing between multiple PowerShell From e0f0486e1968a3045981d23041dd5183ccc5b22a Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 12 Jan 2018 13:26:39 -0800 Subject: [PATCH 179/188] OPS Build config changes and minor article edits (#2051) * clean up warnings from build log * clean up moniker mapping and add image types to config * removing unneeded index pages * fixing typos --- .openpublishing.redirection.json | 15 + dsc/DscForEngineers.md | 7 +- dsc/configDataCredentials.md | 22 +- dsc/docfx.json | 1 - dsc/enactingConfigurations.md | 3 +- dsc/metaConfig.md | 11 +- dsc/metaConfig4.md | 1 - gallery/index.md | 3 - jea/index.md | 3 - .../About/about_WS-Management_Cmdlets.md | 2 - .../About/about_WS-Management_Cmdlets.md | 2 - .../About/about_desiredstateconfiguration.md | 7 - .../About/about_WS-Management_Cmdlets.md | 2 - .../About/about_WS-Management_Cmdlets.md | 2 - .../About/about_Language_Modes.md | 1 - .../Providers/Environment-Provider.md | 75 ++-- .../Add-Content-for-FileSystem.md | 259 ++++++----- .../Get-ChildItem-for-FileSystem.md | 371 ++++++++-------- .../Get-Content-for-FileSystem.md | 401 +++++++++--------- .../Set-Content-for-FileSystem.md | 245 +++++------ .../Providers/Function-Provider.md | 104 +++-- .../Providers/Variable-Provider.md | 102 +++-- reference/docfx.json | 321 ++------------ .../core-powershell/console-guide.md | 12 - .../core-powershell/ise-guide.md | 36 -- ...-Integrated-Scripting-Environment--ISE-.md | 2 +- .../understanding-concepts-reference.md | 25 -- reference/docs-conceptual/toc.yml | 6 - reference/mapping/monikerMapping.json | 21 +- 29 files changed, 841 insertions(+), 1221 deletions(-) delete mode 100644 gallery/index.md delete mode 100644 jea/index.md delete mode 100644 reference/docs-conceptual/core-powershell/console-guide.md delete mode 100644 reference/docs-conceptual/core-powershell/ise-guide.md delete mode 100644 reference/docs-conceptual/getting-started/understanding-concepts-reference.md diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index daed14f40454..dfd5a347b34e 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -15,6 +15,21 @@ "redirect_url": "/powershell/wmf/readme", "redirect_document_id": "False" }, + { + "source_path": "reference/docs-conceptual/core-powershell/console-guide.md", + "redirect_url": "/powershell/scripting/core-powershell/console/powershell.exe-command-line-help", + "redirect_document_id": "False" + }, + { + "source_path": "reference/docs-conceptual/core-powershell/ise-guide.md", + "redirect_url": "/powershell/scripting/core-powershell/ise/introducing-the-windows-powershell-ise", + "redirect_document_id": "False" + }, + { + "source_path": "reference/docs-conceptual/getting-started/understanding-concepts-reference.md", + "redirect_url": "/powershell/scripting/getting-started/fundamental/about-windows-powershell", + "redirect_document_id": "False" + }, { "source_path": "reference/virtual-directory/index.md", "redirect_url": "/powershell/scripting/powershell-scripting", diff --git a/dsc/DscForEngineers.md b/dsc/DscForEngineers.md index 024fd629cbfb..07977850c493 100644 --- a/dsc/DscForEngineers.md +++ b/dsc/DscForEngineers.md @@ -1,6 +1,5 @@ --- ms.date: 2017-10-13 -author: eslesar;mgreenegit ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Desired State Configuration Overview for Decision Makers @@ -112,15 +111,15 @@ Configuration Sample_Share # implement the logic of "how" to execute a task xSmbShare MySMBShare { - Ensure = "Present" + Ensure = "Present" Name = "MyShare" - Path = "C:\Demo\Temp" + Path = "C:\Demo\Temp" ReadAccess = "Alice" FullAccess = "Bob" Description = "This is an updated description for this share" } } -} +} #Run the function to compile the configuration Sample_Share #Pass the configuration to the nodes we defined and configure them diff --git a/dsc/configDataCredentials.md b/dsc/configDataCredentials.md index 9e6efcebcc77..4a998aa4eca8 100644 --- a/dsc/configDataCredentials.md +++ b/dsc/configDataCredentials.md @@ -18,7 +18,10 @@ To suppress these error and warning messages use the DSC configuration data keyw * **PsDscAllowPlainTextPassword** * **PsDscAllowDomainUser** ->**Notes:**

    Storing/transmitting plaintext passwords unencrypted is generally not secure. Securing credentials by using the techniques covered later in this topic is recommended.

    The Azure Automation DSC service allows you to centrally manage credentials to be compiled in configurations and stored securely. For information, see: [Compiling DSC Configurations / Credential Assets](https://docs.microsoft.com/en-in/azure/automation/automation-dsc-compile#credential-assets)

    +> [!NOTE] +> Storing/transmitting plaintext passwords unencrypted is generally not secure. Securing credentials by using the techniques covered later in this topic is recommended. +> The Azure Automation DSC service allows you to centrally manage credentials to be compiled in configurations and stored securely. +> For information, see: [Compiling DSC Configurations / Credential Assets](/azure/automation/automation-dsc-compile#credential-assets) The following is an example of passing plain text credentials: @@ -133,7 +136,8 @@ see [Running DSC with user credentials](runAsUser.md). Newer resources and custom resources can use this automatic property instead of creating their own property for credentials. ->**Note:** the design of some resources are to use multiple credentials for a specific reason, and they will have their own credential properties. +> [!NOTE] +> The design of some resources are to use multiple credentials for a specific reason, and they will have their own credential properties. To find the available credential properties on a resource use either `Get-DscResource -Name ResourceName -Syntax` @@ -228,8 +232,8 @@ for node 'localhost'. ``` This example has two issues: -1. An error explains that plain text passwords are not recommended -2. A warning advises against using a domain credential +1. An error explains that plain text passwords are not recommended +2. A warning advises against using a domain credential ## PsDscAllowPlainTextPassword @@ -276,10 +280,11 @@ $cred = Get-Credential -UserName contoso\genericuser -Message "Password please" DomainCredentialExample -DomainCredential $cred -ConfigurationData $cd ``` ->**Note:** `NodeName` cannot equal asterisk, a specific node name is mandatory. +> [!NOTE] +> `NodeName` cannot equal asterisk, a specific node name is mandatory. + +**Microsoft advises to avoid plain text passwords due to the significant security risk.** -**Microsoft advises to avoid plain text passwords -due to the significant security risk.** An exception would be when using the Azure Automation DSC service, only because the data is always stored encrypted (in transit, at rest in the service, and at rest on the node). @@ -291,8 +296,7 @@ still generates the warning that using a domain account for a credential is not Using a local account eliminates potential exposure of domain credentials that could be used on other servers. -**When using credentials with DSC resources, -prefer a local account over a domain account when possible.** +**When using credentials with DSC resources, prefer a local account over a domain account when possible.** If there is a '\' or '@' in the `Username` property of the credential, then DSC will treat it as a domain account. diff --git a/dsc/docfx.json b/dsc/docfx.json index 8a0ca570ced8..8d4d435b0573 100644 --- a/dsc/docfx.json +++ b/dsc/docfx.json @@ -13,7 +13,6 @@ "breadcrumb_path":"bread/toc.json", "uhfHeaderId": "MSDocsHeader-Powershell", "layout": "conceptual", - "ms.locale": "en-us", "ROBOTS": "INDEX, FOLLOW", "ms.prod": "powershell", "ms.technology": "dsc", diff --git a/dsc/enactingConfigurations.md b/dsc/enactingConfigurations.md index b036558181e0..ad90ea1563b5 100644 --- a/dsc/enactingConfigurations.md +++ b/dsc/enactingConfigurations.md @@ -1,6 +1,5 @@ --- ms.date: 2017-10-16 -author: eslesar;mgreenegit ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Enacting configurations @@ -27,7 +26,7 @@ For example, if the configuration MOF is located at `C:\DSC\Configurations\local you would apply it to the local machine with the following command: `Start-DscConfiguration -Path 'C:\DSC\Configurations'` -> __Note__: By default, DSC runs a configuration as a background job. To run the configuration interactively, call the +> __Note__: By default, DSC runs a configuration as a background job. To run the configuration interactively, call the >[Start-DscConfiguration](https://technet.microsoft.com/library/dn521623.aspx) with the __-Wait__ parameter. ## Pull mode diff --git a/dsc/metaConfig.md b/dsc/metaConfig.md index 6992810d6307..64f864bd5556 100644 --- a/dsc/metaConfig.md +++ b/dsc/metaConfig.md @@ -1,6 +1,5 @@ --- ms.date: 2017-10-11 -author: eslesar;mgreenegit ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Configuring the Local Configuration Manager @@ -46,7 +45,7 @@ configuration LCMConfig RefreshMode = 'Push' } } -} +} ``` The process of applying settings to LCM is similar to applying a DSC configuration. @@ -144,7 +143,7 @@ you create a **ConfigurationRepositoryWeb** block. A **ConfigurationRepositoryWeb** defines the following properties. |Property|Type|Description| -|---|---|---| +|---|---|---| |AllowUnsecureConnection|bool|Set to **$TRUE** to allow connections from the node to the server without authentication. Set to **$FALSE** to require authentication.| |CertificateID|string|The thumbprint of a certificate used to authenticate to the server.| |ConfigurationNames|String[]|An array of names of configurations to be pulled by the target node. These are used only if the node is registered with the pull service by using a **RegistrationKey**. For more information, see [Setting up a pull client with configuration names](pullClientConfigNames.md).| @@ -211,7 +210,7 @@ see [DSC Partial configurations](partialConfigs.md). **PartialConfiguration** defines the following properties. |Property|Type|Description| -|---|---|---| +|---|---|---| |ConfigurationSource|string[]|An array of names of configuration servers, previously defined in **ConfigurationRepositoryWeb** and **ConfigurationRepositoryShare** blocks, where the partial configuration is pulled from.| |DependsOn|string{}|A list of names of other configurations that must be completed before this partial configuration is applied.| |Description|string|Text used to describe the partial configuration.| @@ -221,11 +220,11 @@ see [DSC Partial configurations](partialConfigs.md). __Note:__ partial configurations are supported with Azure Automation DSC, but only one configuration can be pulled from each automation account per node. -## See Also +## See Also ### Concepts [Desired State Configuration Overview](overview.md) - + [Getting started with Azure Automation DSC](https://docs.microsoft.com/en-us/azure/automation/automation-dsc-getting-started) ### Other Resources diff --git a/dsc/metaConfig4.md b/dsc/metaConfig4.md index 32644e5ff88b..467225674575 100644 --- a/dsc/metaConfig4.md +++ b/dsc/metaConfig4.md @@ -1,6 +1,5 @@ --- ms.date: 2017-10-12 -author: eslesar;mgreenegit ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Windows PowerShell 4.0 Desired State Configuration Local Configuration Manager (LCM) diff --git a/gallery/index.md b/gallery/index.md deleted file mode 100644 index d52e9bb0f2ae..000000000000 --- a/gallery/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_url: readme ---- diff --git a/jea/index.md b/jea/index.md deleted file mode 100644 index 5d11197e6073..000000000000 --- a/jea/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -redirect_url: overview ---- diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md index 1b6877370de4..1c2f2843c295 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md @@ -185,8 +185,6 @@ http://go.microsoft.com/fwlink/?LinkId=142329 [Set-WSManQuickConfig](../../Microsoft.WSMan.Management/Set-WSManQuickConfig.md) -[Set-WSManSessionOption](../../Microsoft.WSMan.Management/Set-WSManSessionOption.md) - [Test-WSMan](../../Microsoft.WSMan.Management/Test-WSMan.md) # KEYWORDS diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md index 1b6877370de4..1c2f2843c295 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md @@ -185,8 +185,6 @@ http://go.microsoft.com/fwlink/?LinkId=142329 [Set-WSManQuickConfig](../../Microsoft.WSMan.Management/Set-WSManQuickConfig.md) -[Set-WSManSessionOption](../../Microsoft.WSMan.Management/Set-WSManSessionOption.md) - [Test-WSMan](../../Microsoft.WSMan.Management/Test-WSMan.md) # KEYWORDS diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md index 986f4d855fbc..81758fca1960 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_desiredstateconfiguration.md @@ -30,13 +30,6 @@ For detailed information about DSC, see [PowerShell Desired State Configuration Overview](http://go.microsoft.com/fwlink/?LinkId=311940) in the TechNet Library. -## DEVELOPING DSC RESOURCES WITH CLASSES - -Starting in PowerShell 5.0, you can develop DSC resources by using classes. -For more information, see [about_Classes](about_Classes.md), and -[Writing a custom DSC resource with PowerShell classes](http://technet.microsoft.com/library/dn948461.aspx) -on Microsoft TechNet. - ## USING DSC To use DSC to configure your environment, first define a PowerShell diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md index 1b6877370de4..1c2f2843c295 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md @@ -185,8 +185,6 @@ http://go.microsoft.com/fwlink/?LinkId=142329 [Set-WSManQuickConfig](../../Microsoft.WSMan.Management/Set-WSManQuickConfig.md) -[Set-WSManSessionOption](../../Microsoft.WSMan.Management/Set-WSManSessionOption.md) - [Test-WSMan](../../Microsoft.WSMan.Management/Test-WSMan.md) # KEYWORDS diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md index 1b6877370de4..1c2f2843c295 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_WS-Management_Cmdlets.md @@ -185,8 +185,6 @@ http://go.microsoft.com/fwlink/?LinkId=142329 [Set-WSManQuickConfig](../../Microsoft.WSMan.Management/Set-WSManQuickConfig.md) -[Set-WSManSessionOption](../../Microsoft.WSMan.Management/Set-WSManSessionOption.md) - [Test-WSMan](../../Microsoft.WSMan.Management/Test-WSMan.md) # KEYWORDS diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Language_Modes.md b/reference/6/Microsoft.PowerShell.Core/About/about_Language_Modes.md index c53e1e438e24..c12aefe01cec 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Language_Modes.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Language_Modes.md @@ -251,4 +251,3 @@ NoLanguage session, PowerShell returns the ScriptsNotAllowed error message. - [about_Session_Configuration_Files](about_Session_Configuration_Files.md) - [about_Session_Configurations](about_Session_Configurations.md) -- [about_Windows_RT](about_Windows_RT.md) diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/Environment-Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/Environment-Provider.md index 9081a845cfad..9374699d9809 100644 --- a/reference/6/Microsoft.PowerShell.Core/Providers/Environment-Provider.md +++ b/reference/6/Microsoft.PowerShell.Core/Providers/Environment-Provider.md @@ -13,39 +13,36 @@ online version: https://go.microsoft.com/fwlink/?linkid=834944 ## Provider name - Environment + Environment ## Drives - `Env:` + `Env:` ## Short description - Provides access to the Windows environment variables. + Provides access to the Windows environment variables. ## Detailed description - The Windows PowerShell **Environment** provider lets you get, add, change, clear, and delete Windows environment variables in Windows PowerShell. + The Windows PowerShell **Environment** provider lets you get, add, change, clear, and delete Windows environment variables in Windows PowerShell. - The **Environment** provider is a flat namespace that contains only objects that represent the environment variables. The variables have no child items. + The **Environment** provider is a flat namespace that contains only objects that represent the environment variables. The variables have no child items. - Each environment variable is an instance of the [System.Collections.DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) class. The name of the variable is the dictionary key. The value of the environment variable is the dictionary value. + Each environment variable is an instance of the [System.Collections.DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) class. The name of the variable is the dictionary key. The value of the environment variable is the dictionary value. - The **Environment** provider exposes its data store in the `Env:` drive. To work with environment variables, change your location to the `Env:` drive (`set-location Env:`), or work from another Windows PowerShell drive. To reference an environment variable from another location, use the `Env:` drive name in the path. + The **Environment** provider exposes its data store in the `Env:` drive. To work with environment variables, change your location to the `Env:` drive (`set-location Env:`), or work from another Windows PowerShell drive. To reference an environment variable from another location, use the `Env:` drive name in the path. - The **Environment** provider supports all the cmdlets that contain the *Item* noun except for [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md). And, it supports the [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) and [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) cmdlets. However, it does not support the cmdlets that contain the *ItemProperty* noun, and it does not support the `-Filter` parameter in any cmdlet. - - Environment variables must conform to the usual naming standards. Additionally, the name cannot include the equal sign (`=`). - - Changes to the environment variables affect the current session only. To save the changes, add the changes to the Windows PowerShell profile, or use [Export-Console](there-should-be-an-external-link) to save the current session. + The **Environment** provider supports all the cmdlets that contain the *Item* noun except for [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md). And, it supports the [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) and [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) cmdlets. However, it does not support the cmdlets that contain the *ItemProperty* noun, and it does not support the `-Filter` parameter in any cmdlet. + Environment variables must conform to the usual naming standards. Additionally, the name cannot include the equal sign (`=`). ## Capabilities - ShouldProcess + ShouldProcess ## Examples @@ -56,13 +53,13 @@ online version: https://go.microsoft.com/fwlink/?linkid=834944 #### Example 1 - This command changes the current location to the `Env:` drive: + This command changes the current location to the `Env:` drive: ```powershell Set-Location Env: ``` - You can use this command from any drive in Windows PowerShell. To return to a file system drive, type the drive name. For example, type: + You can use this command from any drive in Windows PowerShell. To return to a file system drive, type the drive name. For example, type: ```powershell Set-Location c: ``` @@ -73,18 +70,18 @@ Set-Location c: #### Example 1 - This command lists all the environment variables in the current session: + This command lists all the environment variables in the current session: ```powershell Get-ChildItem -Path Env: ``` - You can use this command from any Windows PowerShell drive. + You can use this command from any Windows PowerShell drive. #### Example 2 - This command gets the `WINDIR` environment Variable: + This command gets the `WINDIR` environment Variable: ```powershell Get-ChildItem -Path Env:windir @@ -93,14 +90,14 @@ Get-ChildItem -Path Env:windir #### Example 3 - This command gets a list of all the environment variables in the current session and then sorts them by name: + This command gets a list of all the environment variables in the current session and then sorts them by name: ```powershell Get-ChildItem | Sort-Object -Property name ``` - By default, the environment variables appear in the order that Windows PowerShell discovers them. This command is submitted in the `Env:` drive. -When you run this command from another drive, add the `-Path` parameter with a value of `Env:`. + By default, the environment variables appear in the order that Windows PowerShell discovers them. This command is submitted in the `Env:` drive. +When you run this command from another drive, add the `-Path` parameter with a value of `Env:`. ### Creating a new environment variable @@ -108,14 +105,14 @@ When you run this command from another drive, add the `-Path` parameter with a v #### Example 1 - This command creates the `USERMODE` environment variable with a value of "Non-Admin": + This command creates the `USERMODE` environment variable with a value of "Non-Admin": ```powershell New-Item -Path . -Name USERMODE -Value Non-Admin ``` - Because the current location is in the `Env:` drive, the value of the `-Path` parameter is a dot (`.`). The dot represents the current location. -If you are not in the `Env:` drive, the value of the `-Path` parameter would be `Env:`. + Because the current location is in the `Env:` drive, the value of the `-Path` parameter is a dot (`.`). The dot represents the current location. +If you are not in the `Env:` drive, the value of the `-Path` parameter would be `Env:`. ### Displaying the properties and methods of environment variables @@ -123,32 +120,32 @@ If you are not in the `Env:` drive, the value of the `-Path` parameter would be #### Example 1 - This command uses the [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet to get all the environment variables: + This command uses the [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet to get all the environment variables: ```powershell Get-ChildItem -Path Env: | Get-Member ``` - The pipeline operator (`|`) sends the results to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), which displays the methods and properties of the object. -When you pipe a collection of objects to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), such as the collection of environment variables in the `Env:` drive, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates each object in the collection separately. [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) then returns information about each object type that it finds. If all the objects are of the same type, it returns information about the single object type. In this case, all the environment variables are [DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) objects. -To get information about the collection of [DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) objects, use the `-InputObject` parameter of [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md). For example, type: + The pipeline operator (`|`) sends the results to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), which displays the methods and properties of the object. +When you pipe a collection of objects to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), such as the collection of environment variables in the `Env:` drive, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates each object in the collection separately. [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) then returns information about each object type that it finds. If all the objects are of the same type, it returns information about the single object type. In this case, all the environment variables are [DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) objects. +To get information about the collection of [DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) objects, use the `-InputObject` parameter of [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md). For example, type: ```powershell Get-Member -InputObject (Get-ChildItem Env:) ``` -When you use the `-InputObject` parameter, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates the collection, not the objects in the collection. +When you use the `-InputObject` parameter, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates the collection, not the objects in the collection. #### Example 2 - This command lists the values of the properties of the `WINDIR` environment Variable: + This command lists the values of the properties of the `WINDIR` environment Variable: ```powershell Get-Item Env:windir | Format-List -Property * ``` - It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get an object that represents the `WINDIR` environment variable. The pipeline operator (`|`) sends the results to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command. It uses the `-Property` parameter with a wildcard character (`*`) to format and display the values of all the properties of the `WINDIR` environment variable. + It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get an object that represents the `WINDIR` environment variable. The pipeline operator (`|`) sends the results to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command. It uses the `-Property` parameter with a wildcard character (`*`) to format and display the values of all the properties of the `WINDIR` environment variable. ### Changing the properties of an environment variable @@ -156,19 +153,19 @@ Get-Item Env:windir | Format-List -Property * #### Example 1 - This command uses the [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) cmdlet to change the name of the `USERMODE` environment variable that you created to `USERROLE`: + This command uses the [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) cmdlet to change the name of the `USERMODE` environment variable that you created to `USERROLE`: ```powershell Rename-Item -Path Env:USERMODE -NewName USERROLE ``` - This change affects the **Name**, **Key**, and **PSPath** properties of the [DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) object. -Do not change the name of an environment variable that the system uses. Although these changes affect only the current session, they might cause the system or a program to operate incorrectly. + This change affects the **Name**, **Key**, and **PSPath** properties of the [DictionaryEntry](https://msdn.microsoft.com/library/system.collections.dictionaryentry) object. +Do not change the name of an environment variable that the system uses. Although these changes affect only the current session, they might cause the system or a program to operate incorrectly. #### Example 2 - This command uses the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet to change the value of the `USERROLE` environment variable to "Administrator": + This command uses the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet to change the value of the `USERROLE` environment variable to "Administrator": ```powershell Set-Item -Path Env:USERROLE -Value Administrator @@ -180,7 +177,7 @@ Set-Item -Path Env:USERROLE -Value Administrator #### Example 1 - This command copies the value of the `USERROLE` environment variable to the `USERROLE2` environment Variable: + This command copies the value of the `USERROLE` environment variable to the `USERROLE2` environment Variable: ```powershell Copy-Item -Path Env:USERROLE -Destination Env:USERROLE2 @@ -192,18 +189,18 @@ Copy-Item -Path Env:USERROLE -Destination Env:USERROLE2 #### Example 1 - This command deletes the `USERROLE2` environment variable from the current session: + This command deletes the `USERROLE2` environment variable from the current session: ```powershell Remove-Item -Path Env:USERROLE2 ``` - You can use this command in any Windows PowerShell drive. If you are in the `Env:` drive, you can omit the drive name from the path. + You can use this command in any Windows PowerShell drive. If you are in the `Env:` drive, you can omit the drive name from the path. #### Example 2 - This command deletes the `USERROLE` environment variable. + This command deletes the `USERROLE` environment variable. ```powershell Clear-Item -Path Env:USERROLE diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Add-Content-for-FileSystem.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Add-Content-for-FileSystem.md index ece5a6b15211..0866984673d1 100644 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Add-Content-for-FileSystem.md +++ b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Add-Content-for-FileSystem.md @@ -8,198 +8,187 @@ online version: http://go.microsoft.com/fwlink/?LinkId=834948 --- # Add-Content for FileSystem -Appends content, such as words or data, to a file. +Appends content, such as words or data, to a file. -## Syntax +## Syntax -``` -Add-Content [-Encoding { | | | | | | | | | | }] [-Force] [-Stream ] [-Confirm] [-WhatIf] [-UseTransaction] [] +``` +Add-Content [-Encoding { | | | | | | | | | | }] [-Force] [-Stream ] [-Confirm] [-WhatIf] [] -``` +``` -## Description - In file system drives, the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet appends the content you specify to the end of a file. This cmdlet is not valid on folders. +## Description + In file system drives, the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet appends the content you specify to the end of a file. This cmdlet is not valid on folders. - Note: This custom cmdlet help file explains how the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet works in a file system drive. For information about the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) -Path $null" or see [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) at http://go.microsoft.com/fwlink/?LinkID=113278. + Note: This custom cmdlet help file explains how the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet works in a file system drive. For information about the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) -Path $null" or see [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) at http://go.microsoft.com/fwlink/?LinkID=113278. -## Parameters +## Parameters -### -Encoding - Specifies the file encoding. The default is ASCII. +### -Encoding + Specifies the file encoding. The default is ASCII. - Valid values are: + Valid values are: - -- ASCII: Uses the encoding for the ASCII (7-bit) character set. + -- ASCII: Uses the encoding for the ASCII (7-bit) character set. - -- BigEndianUnicode: Encodes in UTF-16 format using the big-endian byte order. + -- BigEndianUnicode: Encodes in UTF-16 format using the big-endian byte order. - -- Byte: Encodes a set of characters into a sequence of bytes. + -- Byte: Encodes a set of characters into a sequence of bytes. - -- String: Uses the encoding type for a string. + -- String: Uses the encoding type for a string. - -- Unicode: Encodes in UTF-16 format using the little-endian byte order. + -- Unicode: Encodes in UTF-16 format using the little-endian byte order. - -- UTF7: Encodes in UTF-7 format. + -- UTF7: Encodes in UTF-7 format. - -- UTF8: Encodes in UTF-8 format. + -- UTF8: Encodes in UTF-8 format. - -- Unknown: The encoding type is unknown or invalid. The data can be treated as binary. + -- Unknown: The encoding type is unknown or invalid. The data can be treated as binary. - Encoding is a dynamic parameter that the FileSystem provider adds to the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet. This parameter works only in file system drives. + Encoding is a dynamic parameter that the FileSystem provider adds to the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet. This parameter works only in file system drives. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|ASCII| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|ASCII| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -Force - Adds contents to files even if they are read-only. Without this parameter, read-only files are not affected. +### -Force + Adds contents to files even if they are read-only. Without this parameter, read-only files are not affected. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|False| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|False| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -Stream - Adds the content to the specified alternate data stream. If the stream does not yet, exist, [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) creates it. Enter the stream name. Wildcards are not supported. +### -Stream + Adds the content to the specified alternate data stream. If the stream does not yet, exist, [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) creates it. Enter the stream name. Wildcards are not supported. - Stream is a dynamic parameter that the FileSystem provider adds to the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet. This parameter works only in file system drives. + Stream is a dynamic parameter that the FileSystem provider adds to the [Add-Content](../../../Microsoft.PowerShell.Management/Add-Content.md) cmdlet. This parameter works only in file system drives. - This parameter is introduced in Windows PowerShell 3.0. + This parameter is introduced in Windows PowerShell 3.0. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -Confirm - Prompts you for confirmation before executing the command. +### -Confirm + Prompts you for confirmation before executing the command. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. +### -WhatIf + Describes what would happen if you executed the command without actually executing the command. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -UseTransaction - Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see [about_Transactions](../../About/about_Transactions.md). +### + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +## 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. -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). +||| +|-|-| +|Inputs|Sytem.Object[], System.String[], System.Management.Automation.PSCredential

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

    When you use the Passthru parameter, Add-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output.| -## 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. +## Example 1 -||| -|-|-| -|Inputs|Sytem.Object[], System.String[], System.Management.Automation.PSCredential

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

    When you use the Passthru parameter, Add-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output.| +``` +C:\PS>Add-Content -Path *.txt -Exclude help* -Value "END" -## Example 1 +Description +----------- +This command adds "END" to all text files in the current directory, except for those with file names that begin with "help." -``` -C:\PS>Add-Content -Path *.txt -Exclude help* -Value "END" +``` -Description ------------ -This command adds "END" to all text files in the current directory, except for those with file names that begin with "help." +## Example 2 -``` +``` +C:\PS>Add-Content -Path file1.log, file2.log -Value (get-date) -PassThru -## Example 2 +Description +----------- +This command adds the date to the end of the File1.log and File2.log files and then displays the date at the command line. -``` -C:\PS>Add-Content -Path file1.log, file2.log -Value (get-date) -PassThru +The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to Add-Content. The PassThru parameter sends the added content through the pipeline. Because there is no other cmdlet to receive the passed content, it is displayed at the command line. -Description ------------ -This command adds the date to the end of the File1.log and File2.log files and then displays the date at the command line. +``` -The command uses the Get-Date cmdlet to get the date, and it uses the Value parameter to pass the date to Add-Content. The PassThru parameter sends the added content through the pipeline. Because there is no other cmdlet to receive the passed content, it is displayed at the command line. +## Example 3 -``` +``` +C:\PS>Add-Content -Path monthly.txt -Value (Get-Content c:\rec1\weekly.txt) -## Example 3 +Description +----------- +This command adds the contents of the Weekly.txt file to the end of the Monthly.txt file. It uses the Get-Content cmdlet to get the contents of the Weekly.txt file, and it uses the Value parameter to pass the content of weekly.txt to Add-Content. The parentheses ensure that the Get-Content command is complete before the Add-Content command begins. -``` -C:\PS>Add-Content -Path monthly.txt -Value (Get-Content c:\rec1\weekly.txt) +You can also copy the content of Weekly.txt to a variable, such as $w, and then use the Value parameter to pass the variable to Add-Content. In that case, the command would be "add-content -path monthly.txt -value $w". -Description ------------ -This command adds the contents of the Weekly.txt file to the end of the Monthly.txt file. It uses the Get-Content cmdlet to get the contents of the Weekly.txt file, and it uses the Value parameter to pass the content of weekly.txt to Add-Content. The parentheses ensure that the Get-Content command is complete before the Add-Content command begins. +``` -You can also copy the content of Weekly.txt to a variable, such as $w, and then use the Value parameter to pass the variable to Add-Content. In that case, the command would be "add-content -path monthly.txt -value $w". +## Example 4 -``` +``` +C:\PS>Add-Content -Value (Get-Content test.log) -Path C:\tests\test134\logs\test134.log -## Example 4 +Description +----------- +This command creates a new directory and file and copies the content of an existing file to the newly created file. -``` -C:\PS>Add-Content -Value (Get-Content test.log) -Path C:\tests\test134\logs\test134.log +This command uses the Add-Content cmdlet to add the content. The value of the Value parameter is a Get-Content command that gets content from an existing file, Test.log. -Description ------------ -This command creates a new directory and file and copies the content of an existing file to the newly created file. +The value of the path parameter is a path that does not exist when the command runs. In this example, only the C:\Tests directories exist. The command creates the remaining directories and the Test134.log file. -This command uses the Add-Content cmdlet to add the content. The value of the Value parameter is a Get-Content command that gets content from an existing file, Test.log. +The Force parameter is not required for this command. Add-Content creates directories to complete a path even without the Force parameter. -The value of the path parameter is a path that does not exist when the command runs. In this example, only the C:\Tests directories exist. The command creates the remaining directories and the Test134.log file. +``` -The Force parameter is not required for this command. Add-Content creates directories to complete a path even without the Force parameter. +## Example 5 -``` +``` +C:\PS>Get-Content test.xml | Add-Content final.xml -Force -Encoding UTF8 -## Example 5 +Description +----------- +This command appends the contents of the final.xml file to the contents of the test.xml file. -``` -C:\PS>Get-Content test.xml | Add-Content final.xml -Force -Encoding UTF8 +The command uses the Force parameter so that the command is successful even if the Final.xml file is read-only. It uses the Encoding parameter to specify an encoding of UTF-8. -Description ------------ -This command appends the contents of the final.xml file to the contents of the test.xml file. +``` -The command uses the Force parameter so that the command is successful even if the Final.xml file is read-only. It uses the Encoding parameter to specify an encoding of UTF-8. - -``` - -## See Also - [FileSystem Provider](../FileSystem-Provider.md) - [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) - [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) - [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) +## See Also + [FileSystem Provider](../FileSystem-Provider.md) + [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) + [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) + [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) + [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) + [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) + [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) + [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-ChildItem-for-FileSystem.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-ChildItem-for-FileSystem.md index 31d62bc5d9ab..6bdb07292604 100644 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-ChildItem-for-FileSystem.md +++ b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Get-ChildItem-for-FileSystem.md @@ -8,286 +8,275 @@ online version: http://go.microsoft.com/fwlink/?LinkId=834950 --- # Get-ChildItem for FileSystem -Gets the files and folders in a file system drive. +Gets the files and folders in a file system drive. -## Syntax +## Syntax -``` -Get-ChildItem [-Attributes ] [-Directory] [-File] [-Force] [-Hidden] [-ReadOnly] [-System] [-UseTransaction] [] +``` +Get-ChildItem [-Attributes ] [-Directory] [-File] [-Force] [-Hidden] [-ReadOnly] [-System] [] -``` +``` -## Description - In a file system drive, the [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet gets the directories, subdirectories, and files. In a file system directory, it gets subdirectories and files. +## Description + In a file system drive, the [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet gets the directories, subdirectories, and files. In a file system directory, it gets subdirectories and files. - By default, [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) gets non-hidden items, but you can use the Directory, File, Hidden, ReadOnly, and System parameters to get only items with these attributes. To create a complex attribute search, use the Attributes parameter. If you use these parameters, [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) gets only the items that meet all search conditions, as though the parameters were connected by an AND operator. + By default, [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) gets non-hidden items, but you can use the Directory, File, Hidden, ReadOnly, and System parameters to get only items with these attributes. To create a complex attribute search, use the Attributes parameter. If you use these parameters, [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) gets only the items that meet all search conditions, as though the parameters were connected by an AND operator. - Note: This custom cmdlet help file explains how the [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet works in a file system drive. For information about the [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) -Path $null" or see [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) at http://go.microsoft.com/fwlink/?LinkID=113308. + Note: This custom cmdlet help file explains how the [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet works in a file system drive. For information about the [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) -Path $null" or see [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) at http://go.microsoft.com/fwlink/?LinkID=113308. -## Parameters +## Parameters -### -Attributes - Gets files and folders with the specified attributes. This parameter supports all attributes and lets you specify complex combinations of attributes. +### -Attributes + Gets files and folders with the specified attributes. This parameter supports all attributes and lets you specify complex combinations of attributes. - For example, to get non-system files (not directories) that are encrypted or compressed, type: + For example, to get non-system files (not directories) that are encrypted or compressed, type: - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) -Attributes !Directory+!System+Encrypted, !Directory+!System+Compressed + [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) -Attributes !Directory+!System+Encrypted, !Directory+!System+Compressed - To find files and folders with commonly used attributes, you can use the Attributes parameter, or the Directory, File, Hidden, ReadOnly, and System switch parameters. + To find files and folders with commonly used attributes, you can use the Attributes parameter, or the Directory, File, Hidden, ReadOnly, and System switch parameters. - The Attributes parameter supports the following attributes: Archive, Compressed, Device, Directory, Encrypted, Hidden, Normal, NotContentIndexed, Offline, ReadOnly, ReparsePoint, SparseFile, System, and Temporary. For a description of these attributes, see the FileAttributes enumeration at http://go.microsoft.com/fwlink/?LinkId=201508. + The Attributes parameter supports the following attributes: Archive, Compressed, Device, Directory, Encrypted, Hidden, Normal, NotContentIndexed, Offline, ReadOnly, ReparsePoint, SparseFile, System, and Temporary. For a description of these attributes, see the FileAttributes enumeration at http://go.microsoft.com/fwlink/?LinkId=201508. - Use the following operators to combine attributes. + Use the following operators to combine attributes. - ! NOT + ! NOT - \+ AND + \+ AND - , OR + , OR - No spaces are permitted between an operator and its attribute. However, spaces are permitted before commas. + No spaces are permitted between an operator and its attribute. However, spaces are permitted before commas. - You can use the following abbreviations for commonly used attributes: + You can use the following abbreviations for commonly used attributes: - D Directory + D Directory - H Hidden + H Hidden - R Read-only + R Read-only - S System + S System -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -Directory - Gets directories (folders). +### -Directory + Gets directories (folders). - To get only directories, use the Directory parameter and omit the File parameter. To exclude directories, use the File parameter and omit the Directory parameter, or use the Attributes parameter. + To get only directories, use the Directory parameter and omit the File parameter. To exclude directories, use the File parameter and omit the Directory parameter, or use the Attributes parameter. - To get directories, use the Directory parameter, its "ad" alias, or the Directory attribute of the Attributes parameter. + To get directories, use the Directory parameter, its "ad" alias, or the Directory attribute of the Attributes parameter. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|None| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|None| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -File - Gets files. +### -File + Gets files. - To get only files, use the File parameter and omit the Directory parameter. To exclude files, use the Directory parameter and omit the File parameter, or use the Attributes parameter. + To get only files, use the File parameter and omit the Directory parameter. To exclude files, use the Directory parameter and omit the File parameter, or use the Attributes parameter. - To get files, use the File parameter, its "af" alias, or the File value of the Attributes parameter. + To get files, use the File parameter, its "af" alias, or the File value of the Attributes parameter. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -Hidden - Gets only hidden files and directories (folders). By default, [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) gets only non-hidden items, but you can use the Force parameter to include hidden items in the results. +### -Hidden + Gets only hidden files and directories (folders). By default, [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) gets only non-hidden items, but you can use the Force parameter to include hidden items in the results. - To get only hidden items, use the Hidden parameter, its "h" or "ah" aliases, or the Hidden value of the Attributes parameter. To exclude hidden items, omit the Hidden parameter or use the Attributes parameter. + To get only hidden items, use the Hidden parameter, its "h" or "ah" aliases, or the Hidden value of the Attributes parameter. To exclude hidden items, omit the Hidden parameter or use the Attributes parameter. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -ReadOnly - Gets only read-only files and directories (folders). +### -ReadOnly + Gets only read-only files and directories (folders). - To get only read-only items, use the ReadOnly parameter, its "ar" alias, or the ReadOnly value of the Attributes parameter. To exclude read-only items, use the Attributes parameter. + To get only read-only items, use the ReadOnly parameter, its "ar" alias, or the ReadOnly value of the Attributes parameter. To exclude read-only items, use the Attributes parameter. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -System - Gets only system files and directories (folders). +### -System + Gets only system files and directories (folders). - To get only system files and folders, use the System parameter, its "as" alias, or the System value of the Attributes parameter. To exclude system files and folders, use the Attributes parameter. + To get only system files and folders, use the System parameter, its "as" alias, or the System value of the Attributes parameter. To exclude system files and folders, use the Attributes parameter. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -Force - Gets hidden files and folders. By default, hidden files and folder are excluded. You can also get hidden files and folders by using the Hidden parameter or the Hidden value of the Attributes parameter. +### -Force + Gets hidden files and folders. By default, hidden files and folder are excluded. You can also get hidden files and folders by using the Hidden parameter or the Hidden value of the Attributes parameter. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -UseTransaction - Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see [about_Transactions](../../About/about_Transactions.md). +### + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +## 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. -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). +||| +|-|-| +|Inputs|System.String[]

    You can pipe a file system path (in quotation marks) to Get-ChildItem.| +|Outputs|System.IO.DirectoryInfo, System.IO.FileInfo, System.String| -## 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. +## Notes + The Attributes, Directory, File, Hidden, ReadOnly, and System parameters were introduced in Windows PowerShell 3.0 and -||| -|-|-| -|Inputs|System.String[]

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

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

    Get-Content returns objects that represent the content that it gets. The object type depends on the content type. If you use the Stream parameter, the cmdlet returns the alternate data stream contents as a string.| -## 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. +## Example 1 -||| -|-|-| -|Inputs|System.Int64, System.String[], System.Management.Automation.PSCredential

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

    Get-Content returns objects that represent the content that it gets. The object type depends on the content type. If you use the Stream parameter, the cmdlet returns the alternate data stream contents as a string.| +``` +C:\PS>Get-Content -Path C:\Chapters\chapter1.txt -## Example 1 +Description +----------- +This command gets the content of the Chapter1.txt file and displays it in the console. It uses the Path parameter to specify the name of the item. -``` -C:\PS>Get-Content -Path C:\Chapters\chapter1.txt +Get-Content actually passes the content down the pipeline, but because there are no other cmdlets in the pipeline, Windows PowerShell formats the contents and displays it in the console. -Description ------------ -This command gets the content of the Chapter1.txt file and displays it in the console. It uses the Path parameter to specify the name of the item. +``` -Get-Content actually passes the content down the pipeline, but because there are no other cmdlets in the pipeline, Windows PowerShell formats the contents and displays it in the console. +## Example 2 -``` +``` +C:\PS>Get-Content C:\Logs\Log060912.txt -TotalCount 50 | Set-Content Sample.txt -## Example 2 +Description +----------- +This command gets the first 50 lines of the Log060912.txt file and stores them in the sample.txt file. -``` -C:\PS>Get-Content C:\Logs\Log060912.txt -TotalCount 50 | Set-Content Sample.txt +The command uses the Get-Content cmdlet to get the text in the file. (The name of Path parameter, which is optional, is omitted.) The TotalCount parameter limits the retrieval to the first 50 lines. The pipeline operator (|) sends the result to Set-Content, which places it in the sample.txt file. -Description ------------ -This command gets the first 50 lines of the Log060912.txt file and stores them in the sample.txt file. +``` -The command uses the Get-Content cmdlet to get the text in the file. (The name of Path parameter, which is optional, is omitted.) The TotalCount parameter limits the retrieval to the first 50 lines. The pipeline operator (|) sends the result to Set-Content, which places it in the sample.txt file. +## Example 3 -``` +``` +C:\PS>(Get-Content Cmdlets.txt -TotalCount 5)[-1] -## Example 3 +Description +----------- +This command gets the fifth line of the Cmdlets.txt text file. It uses the TotalCount parameter to get the first five lines and then uses array notation to get the last line (indicated by "-1") of the resulting set. -``` -C:\PS>(Get-Content Cmdlets.txt -TotalCount 5)[-1] +``` -Description ------------ -This command gets the fifth line of the Cmdlets.txt text file. It uses the TotalCount parameter to get the first five lines and then uses array notation to get the last line (indicated by "-1") of the resulting set. +## Example 4 -``` +``` +C:\PS>Get-Content .\DataSets\*.csv -Delimiter "*---*" -Force -Encoding UTF8 -## Example 4 +Description +----------- +This command gets the contents of all CSV files in the DataSets subdirectory. It uses the Force parameter to get all files, including hidden files, and the Encoding parameter to specify the file encoding. -``` -C:\PS>Get-Content .\DataSets\*.csv -Delimiter "*---*" -Force -Encoding UTF8 +The command also uses the Delimiter parameter to divide the returned content into sets, each of which ends at the CSV file row that contains the "*----*" marker. -Description ------------ -This command gets the contents of all CSV files in the DataSets subdirectory. It uses the Force parameter to get all files, including hidden files, and the Encoding parameter to specify the file encoding. +``` -The command also uses the Delimiter parameter to divide the returned content into sets, each of which ends at the CSV file row that contains the "*----*" marker. +## Example 5 -``` +``` +C:\PS>Get-Content .\Copy-Scripts.ps1 -Stream Zone.Identifier -## Example 5 +[ZoneTransfer] +ZoneId=3 -``` -C:\PS>Get-Content .\Copy-Scripts.ps1 -Stream Zone.Identifier +Description +----------- +This command uses the Stream parameter to get the content of the Zone.Identifier alternate data stream. The output includes Zone ID value of 3, which represents the Internet. -[ZoneTransfer] -ZoneId=3 +The Stream parameter is introduced in Windows PowerShell 3.0. -Description ------------ -This command uses the Stream parameter to get the content of the Zone.Identifier alternate data stream. The output includes Zone ID value of 3, which represents the Internet. +``` -The Stream parameter is introduced in Windows PowerShell 3.0. +## Example 6 -``` +``` +C:\PS>$Manifest = (Get-Module -List PSScheduledJob).Path -## Example 6 +C:\PS>$Hash = Invoke-Expression (Get-Content $Manifest -Raw) -``` -C:\PS>$Manifest = (Get-Module -List PSScheduledJob).Path +C:\PS>$Hash -C:\PS>$Hash = Invoke-Expression (Get-Content $Manifest -Raw) +Name Value +---- ----- +Copyright ? Microsoft Corporation. All rights reserved. +ModuleToProcess Microsoft.PowerShell.ScheduledJob.dll +FormatsToProcess PSScheduledJob.Format.ps1xml +PowerShellVersion 3.0 +CompanyName Microsoft Corporation +GUID 50cdb55f-5ab7-489f-9e94-4ec21ff51e59 +Author Microsoft Corporation +CLRVersion 4.0 +CmdletsToExport {New-JobTrigger, Add-JobTrigger, Remove-JobTrigger, Get-JobTrigger...} +TypesToProcess PSScheduledJob.types.ps1xml +HelpInfoURI http://go.microsoft.com/fwlink/?LinkID=223911 +ModuleVersion 1.0.0.0 -C:\PS>$Hash +C:\PS>$Hash.ModuleToProcess +Microsoft.PowerShell.ScheduledJob.dll -Name Value ----- ----- -Copyright ? Microsoft Corporation. All rights reserved. -ModuleToProcess Microsoft.PowerShell.ScheduledJob.dll -FormatsToProcess PSScheduledJob.Format.ps1xml -PowerShellVersion 3.0 -CompanyName Microsoft Corporation -GUID 50cdb55f-5ab7-489f-9e94-4ec21ff51e59 -Author Microsoft Corporation -CLRVersion 4.0 -CmdletsToExport {New-JobTrigger, Add-JobTrigger, Remove-JobTrigger, Get-JobTrigger...} -TypesToProcess PSScheduledJob.types.ps1xml -HelpInfoURI http://go.microsoft.com/fwlink/?LinkID=223911 -ModuleVersion 1.0.0.0 +Description +----------- +The commands in this example get the contents of a module manifest file (.psd1) as a hash table. The manifest file contains a hash table, but if you get the contents without the Raw dynamic parameter, it is returned as an array of newline-delimited strings. -C:\PS>$Hash.ModuleToProcess -Microsoft.PowerShell.ScheduledJob.dll +The Raw dynamic parameter is introduced in Windows PowerShell 3.0. -Description ------------ -The commands in this example get the contents of a module manifest file (.psd1) as a hash table. The manifest file contains a hash table, but if you get the contents without the Raw dynamic parameter, it is returned as an array of newline-delimited strings. +The first command uses the Path property of modules to get the path to the file that contains the module manifest for the PSScheduledJob module. It saves the path in the $Manifest variable. -The Raw dynamic parameter is introduced in Windows PowerShell 3.0. +The second command uses the Invoke-Expression cmdlet to run a Get-Content command and the Raw dynamic parameter of the Get-Content cmdlet to get the contents of the module manifest file in a single string. The command saves the hash table in the $Hash variable. -The first command uses the Path property of modules to get the path to the file that contains the module manifest for the PSScheduledJob module. It saves the path in the $Manifest variable. +The third command gets the hash table in the Hash variable. The contents is returned as a collection of name-value pairs. -The second command uses the Invoke-Expression cmdlet to run a Get-Content command and the Raw dynamic parameter of the Get-Content cmdlet to get the contents of the module manifest file in a single string. The command saves the hash table in the $Hash variable. +The fourth command uses the ModuleToProcess property of the hash table to get the value of the ModuleToProcess key in the module manifest. -The third command gets the hash table in the Hash variable. The contents is returned as a collection of name-value pairs. +``` -The fourth command uses the ModuleToProcess property of the hash table to get the value of the ModuleToProcess key in the module manifest. +## Example 7 -``` +``` +C:\PS>$a = Get-Content -Path .\Download.zip -Encoding Byte -ReadCount 0 -## Example 7 +Set-Content -Path \\Server\Share\Download.zip -Encoding Byte -Value $a -``` -C:\PS>$a = Get-Content -Path .\Download.zip -Encoding Byte -ReadCount 0 +$b = Get-Content -Path .\Download.zip -Encoding Byte +Set-Content -Path \\Server\Share\Download.zip -Encoding Byte -Value $b -Set-Content -Path \\Server\Share\Download.zip -Encoding Byte -Value $a +Set-Content : Cannot proceed with byte encoding. When using byte encoding the content must be of type byte. +At line:1 char:1 ++ Set-Content \\Server\Share\Download.zip -Encoding Byte -Value $b ++ [!INCLUDE[]()][!INCLUDE[]()][!INCLUDE[]()]~~~~~ + + CategoryInfo : InvalidArgument: (:) [Set-Content], PSArgumentException + + FullyQualifiedErrorId : Argument,Microsoft.PowerShell.Commands.SetContentCommand -$b = Get-Content -Path .\Download.zip -Encoding Byte -Set-Content -Path \\Server\Share\Download.zip -Encoding Byte -Value $b +Description +----------- +This example shows how to use the ReadCount parameter of the Get-Content cmdlet with a value of 0 to avoid byte-related errors when using the Set-Content cmdlet to write the bytes to a file. -Set-Content : Cannot proceed with byte encoding. When using byte encoding the content must be of type byte. -At line:1 char:1 -+ Set-Content \\Server\Share\Download.zip -Encoding Byte -Value $b -+ [!INCLUDE[]()][!INCLUDE[]()][!INCLUDE[]()]~~~~~ - + CategoryInfo : InvalidArgument: (:) [Set-Content], PSArgumentException - + FullyQualifiedErrorId : Argument,Microsoft.PowerShell.Commands.SetContentCommand +When getting the content of a file in bytes, Get-Content creates an object (PSObject) for the bytes in each read operation. If you read the bytes one at a time, which is the default, Get-Content creates an object for each byte. The objects cause errors when you use the Set-Content cmdlet to write the bytes to a file. -Description ------------ -This example shows how to use the ReadCount parameter of the Get-Content cmdlet with a value of 0 to avoid byte-related errors when using the Set-Content cmdlet to write the bytes to a file. +The first command uses the Get-Content cmdlet to get the contents of the Download.zip file and save it in the $a variable. The command uses the Encoding dynamic parameter with a value of Byte. It also uses the ReadCount parameter with a value of 0, which directs Get-Content to get the file contents in a single read operation. The default value of the ReadCount parameter, 1, gets one byte at a time. -When getting the content of a file in bytes, Get-Content creates an object (PSObject) for the bytes in each read operation. If you read the bytes one at a time, which is the default, Get-Content creates an object for each byte. The objects cause errors when you use the Set-Content cmdlet to write the bytes to a file. +The second command uses the Set-Content cmdlet to write the bytes in the $a variable to the Download.zip file on a file share. The command succeeds. -The first command uses the Get-Content cmdlet to get the contents of the Download.zip file and save it in the $a variable. The command uses the Encoding dynamic parameter with a value of Byte. It also uses the ReadCount parameter with a value of 0, which directs Get-Content to get the file contents in a single read operation. The default value of the ReadCount parameter, 1, gets one byte at a time. +The third and fourth commands show the same sequence without the ReadCount parameter. -The second command uses the Set-Content cmdlet to write the bytes in the $a variable to the Download.zip file on a file share. The command succeeds. +The third command uses the Encoding dynamic parameter of the Get-Content cmdlet to get the contents of the Download.zip file and save it in the $b variable. Because the command omits the ReadCount parameter, it uses the default value of 1. -The third and fourth commands show the same sequence without the ReadCount parameter. +The fourth command uses the Set-Content cmdlet to write the bytes in the $b variable to the Download.zip file on a file share. Because the content is a collection of objects, rather than a single object that contains a byte array, the command fails. -The third command uses the Encoding dynamic parameter of the Get-Content cmdlet to get the contents of the Download.zip file and save it in the $b variable. Because the command omits the ReadCount parameter, it uses the default value of 1. +``` -The fourth command uses the Set-Content cmdlet to write the bytes in the $b variable to the Download.zip file on a file share. Because the content is a collection of objects, rather than a single object that contains a byte array, the command fails. - -``` - -## See Also - [FileSystem Provider](../FileSystem-Provider.md) - [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) - [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) - [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) +## See Also + [FileSystem Provider](../FileSystem-Provider.md) + [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) + [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) + [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) + [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) + [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) + [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) + [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Set-Content-for-FileSystem.md b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Set-Content-for-FileSystem.md index 8c62b5e182fd..ae67263f126e 100644 --- a/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Set-Content-for-FileSystem.md +++ b/reference/6/Microsoft.PowerShell.Core/Providers/FileSystem-Provider/Set-Content-for-FileSystem.md @@ -8,187 +8,176 @@ online version: http://go.microsoft.com/fwlink/?LinkId=834955 --- # Set-Content for FileSystem -Replaces the contents of a file with contents that you specify. +Replaces the contents of a file with contents that you specify. -## Syntax +## Syntax -``` -Set-Content [-Encoding { | | | | | | | | | | }] [-Force] [-Stream ] [-Confirm] [-WhatIf] [-UseTransaction] [] +``` +Set-Content [-Encoding { | | | | | | | | | | }] [-Force] [-Stream ] [-Confirm] [-WhatIf] [] -``` +``` -## Description - In file system drives, the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet overwrites or replaces the content of one or more files with the content that you specify. This cmdlet is not valid on folders. +## Description + In file system drives, the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet overwrites or replaces the content of one or more files with the content that you specify. This cmdlet is not valid on folders. - Note: This custom cmdlet help file explains how the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet works in a file system drive. For information about the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) -Path $null" or see [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) at http://go.microsoft.com/fwlink/?LinkID=113392. + Note: This custom cmdlet help file explains how the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet works in a file system drive. For information about the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet in all drives, type "[Get-Help](../../Get-Help.md)[Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) -Path $null" or see [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) at http://go.microsoft.com/fwlink/?LinkID=113392. -## Parameters +## Parameters -### -Encoding - Specifies the file encoding. The default is ASCII. +### -Encoding + Specifies the file encoding. The default is ASCII. - Valid values are: + Valid values are: - -- ASCII: Uses the encoding for the ASCII (7-bit) character set. + -- ASCII: Uses the encoding for the ASCII (7-bit) character set. - -- BigEndianUnicode: Encodes in UTF-16 format using the big-endian byte order. + -- BigEndianUnicode: Encodes in UTF-16 format using the big-endian byte order. - -- Byte: Encodes a set of characters into a sequence of bytes. + -- Byte: Encodes a set of characters into a sequence of bytes. - -- String: Uses the encoding type for a string. + -- String: Uses the encoding type for a string. - -- Unicode: Encodes in UTF-16 format using the little-endian byte order. + -- Unicode: Encodes in UTF-16 format using the little-endian byte order. - -- UTF7: Encodes in UTF-7 format. + -- UTF7: Encodes in UTF-7 format. - -- UTF8: Encodes in UTF-8 format. + -- UTF8: Encodes in UTF-8 format. - -- Unknown: The encoding type is unknown or invalid. The data can be treated as binary. + -- Unknown: The encoding type is unknown or invalid. The data can be treated as binary. - Encoding is a dynamic parameter that the FileSystem provider adds to the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet. This parameter works only in file system drives. + Encoding is a dynamic parameter that the FileSystem provider adds to the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet. This parameter works only in file system drives. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|ASCII| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|ASCII| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -Force - Replaces the contents of a file, even if the file is read-only. Without this parameter, read-only files are not changed. +### -Force + Replaces the contents of a file, even if the file is read-only. Without this parameter, read-only files are not changed. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -Stream - Creates or replaces the content in the specified alternate data stream. If the stream does not yet exist, [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) creates it. Enter the stream name. Wildcards are not supported. +### -Stream + Creates or replaces the content in the specified alternate data stream. If the stream does not yet exist, [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) creates it. Enter the stream name. Wildcards are not supported. - Stream is a dynamic parameter that the FileSystem provider adds to the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet. This parameter works only in file system drives. + Stream is a dynamic parameter that the FileSystem provider adds to the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet. This parameter works only in file system drives. - You can use the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet to change the content of the Zone.Identifier alternate data stream. However, it is not the recommended way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. + You can use the [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) cmdlet to change the content of the Zone.Identifier alternate data stream. However, it is not the recommended way to eliminate security checks that block files that are downloaded from the Internet. If you verify that a downloaded file is safe, use the Unblock-File cmdlet. - This parameter is introduced in Windows PowerShell 3.0. + This parameter is introduced in Windows PowerShell 3.0. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -Confirm - Prompts you for confirmation before executing the command. +### -Confirm + Prompts you for confirmation before executing the command. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -WhatIf - Describes what would happen if you executed the command without actually executing the command. +### -WhatIf + Describes what would happen if you executed the command without actually executing the command. -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +||| +|-|-| +|Required?|false| +|Position?|named| +|Default Value|| +|Accept Pipeline Input?|false| +|Accept Wildcard Characters?|false| -### -UseTransaction - Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see [about_Transactions](../../About/about_Transactions.md). +### + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). -||| -|-|-| -|Required?|false| -|Position?|named| -|Default Value|| -|Accept Pipeline Input?|false| -|Accept Wildcard Characters?|false| +## 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. -### - This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, -OutVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../About/about_CommonParameters.md). +||| +|-|-| +|Inputs|System.Object[], System.String[], System.Management.Automation.PSCredential

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

    When you use the Passthru parameter, Set-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output.| -## 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. +## Example 1 -||| -|-|-| -|Inputs|System.Object[], System.String[], System.Management.Automation.PSCredential

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

    When you use the Passthru parameter, Set-Content generates a System.String object representing the content. Otherwise, this cmdlet does not generate any output.| +``` +C:\PS>Set-Content -Path C:\Test1\test*.txt -Value "Hello, World" -## Example 1 +Description +----------- +This command replaces the contents of all files in the Test1 directory that have names beginning with "test" with "Hello, World". This example shows how to specify content by typing it in the command. -``` -C:\PS>Set-Content -Path C:\Test1\test*.txt -Value "Hello, World" +``` -Description ------------ -This command replaces the contents of all files in the Test1 directory that have names beginning with "test" with "Hello, World". This example shows how to specify content by typing it in the command. +## Example 2 -``` +``` +C:\PS>Get-Date | Set-Content C:\Test1\date.csv -## Example 2 +Description +----------- +This command creates a comma-separated variable-length (csv) file that contains only the current date and time. It uses the Get-Date cmdlet to get the current system date and time. The pipeline operator passes the result to Set-Content, which creates the file and writes the content. -``` -C:\PS>Get-Date | Set-Content C:\Test1\date.csv +If the Test1 directory does not exist, the command fails, but if the file does not exist, the command will create it. -Description ------------ -This command creates a comma-separated variable-length (csv) file that contains only the current date and time. It uses the Get-Date cmdlet to get the current system date and time. The pipeline operator passes the result to Set-Content, which creates the file and writes the content. +``` -If the Test1 directory does not exist, the command fails, but if the file does not exist, the command will create it. +## Example 3 -``` +``` +C:\PS>Get-Content Notice.txt | ForEach-Object {$_ -replace "Warning", "Caution"} | Set-Content Notice.txt -## Example 3 +Description +----------- +This command replaces all instances of "Warning" with "Caution" in the Notice.txt file. -``` -C:\PS>Get-Content Notice.txt | ForEach-Object {$_ -replace "Warning", "Caution"} | Set-Content Notice.txt +It uses the Get-Content cmdlet to get the content of Notice.txt. The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in Get-Content. The expression uses the "$_" symbol to refer to the current item and the Replace parameter to specify the text to be replaced. -Description ------------ -This command replaces all instances of "Warning" with "Caution" in the Notice.txt file. +Another pipeline operator sends the changed content to Set-Content which replaces the text in Notice.txt with the new content. -It uses the Get-Content cmdlet to get the content of Notice.txt. The pipeline operator sends the results to the ForEach-Object cmdlet, which applies the expression to each line of content in Get-Content. The expression uses the "$_" symbol to refer to the current item and the Replace parameter to specify the text to be replaced. +The parentheses around the Get-Content command ensure that the Get operation is complete before the Set operation begins. Without them, the command will fail because the two functions will be trying to access the same file. -Another pipeline operator sends the changed content to Set-Content which replaces the text in Notice.txt with the new content. +``` -The parentheses around the Get-Content command ensure that the Get operation is complete before the Set operation begins. Without them, the command will fail because the two functions will be trying to access the same file. +## Example 4 -``` +``` +C:\PS>Get-Content test.xml | Set-Content final.xml -Force -Encoding UTF8 -## Example 4 +Description +----------- +This command replaces the contents of the final.xml file with the contents of the test.xml file. -``` -C:\PS>Get-Content test.xml | Set-Content final.xml -Force -Encoding UTF8 +The command uses the Force parameter so that the command is successful even if the Final.xml file is read-only. It uses the Encoding dynamic parameter to specify an encoding of UTF-8. -Description ------------ -This command replaces the contents of the final.xml file with the contents of the test.xml file. +``` -The command uses the Force parameter so that the command is successful even if the Final.xml file is read-only. It uses the Encoding dynamic parameter to specify an encoding of UTF-8. - -``` - -## See Also - [FileSystem Provider](../FileSystem-Provider.md) - [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) - [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) - [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) - [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) - [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) +## See Also + [FileSystem Provider](../FileSystem-Provider.md) + [Clear-Content](../../../Microsoft.PowerShell.Management/Clear-Content.md) + [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) + [Get-ChildItem](../../../Microsoft.PowerShell.Management/Get-ChildItem.md) + [Get-Content](../../../Microsoft.PowerShell.Management/Get-Content.md) + [Get-Item](../../../Microsoft.PowerShell.Management/Get-Item.md) + [Remove-Item](../../../Microsoft.PowerShell.Management/Remove-Item.md) + [Set-Content](../../../Microsoft.PowerShell.Management/Set-Content.md) [Test-Path](../../../Microsoft.PowerShell.Management/Test-Path.md) diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/Function-Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/Function-Provider.md index 567749152b9a..535fdd8b8d21 100644 --- a/reference/6/Microsoft.PowerShell.Core/Providers/Function-Provider.md +++ b/reference/6/Microsoft.PowerShell.Core/Providers/Function-Provider.md @@ -13,43 +13,41 @@ online version: http://go.microsoft.com/fwlink/?LinkId=834961 ## Provider name - Function + Function ## Drives - `Function:` + `Function:` ## Short description - Provides access to the functions defined in Windows PowerShell. + Provides access to the functions defined in Windows PowerShell. ## Detailed description - The Windows PowerShell **Function** provider lets you get, add, change, clear, and delete the functions and filters in Windows PowerShell. + The Windows PowerShell **Function** provider lets you get, add, change, clear, and delete the functions and filters in Windows PowerShell. - A function is a named block of code that performs an action. When you type the function name, the code in the function runs. A filter is a named block of code that establishes conditions for an action. You can type the name of the filter in place of the condition, such as in a [Where-Object](../Where-Object.md) command. + A function is a named block of code that performs an action. When you type the function name, the code in the function runs. A filter is a named block of code that establishes conditions for an action. You can type the name of the filter in place of the condition, such as in a [Where-Object](../Where-Object.md) command. - In the `Function:` drive, functions are preceded by the label "Function" and filters are preceded by the label "Filter", but they operate properly when used in the correct context regardless of the label. + In the `Function:` drive, functions are preceded by the label "Function" and filters are preceded by the label "Filter", but they operate properly when used in the correct context regardless of the label. - The **Function** provider is a flat namespace that contains only the function and filter objects. Neither functions nor filters have child items. + The **Function** provider is a flat namespace that contains only the function and filter objects. Neither functions nor filters have child items. - Each function is an instance of the [System.Management.Automation.FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) class. Each filter is an instance of the [System.Management.Automation.FilterInfo](https://msdn.microsoft.com/library/system.management.automation.filterinfo) class. + Each function is an instance of the [System.Management.Automation.FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) class. Each filter is an instance of the [System.Management.Automation.FilterInfo](https://msdn.microsoft.com/library/system.management.automation.filterinfo) class. - The examples in this section show how to manage functions, but the same methods can be used with filters. + The examples in this section show how to manage functions, but the same methods can be used with filters. - The **Function** provider exposes its data store in the `Function:` drive. To work with functions, you can change your location to the `Function:` drive (`set-location Function:`). Or, you can work from another Windows PowerShell drive. To reference a function from another location, use the drive name (`Function:`) in the path. + The **Function** provider exposes its data store in the `Function:` drive. To work with functions, you can change your location to the `Function:` drive (`set-location Function:`). Or, you can work from another Windows PowerShell drive. To reference a function from another location, use the drive name (`Function:`) in the path. - The **Function** provider supports all of the cmdlets whose names contain the *Item* noun (the `*-Item` cmdlets), except for [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md). And, it supports the [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) and [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) cmdlets. However, it does not support the cmdlets whose names contain the *ItemProperty* noun (the `*-ItemProperty` cmdlets), and it does not support the `-Filter` parameter in any cmdlet. - - All changes to the functions affect the current console only. To save the changes, add the function to the Windows PowerShell profile, or use [Export-Console](there-should-be-an-external-link) to save the current console. + The **Function** provider supports all of the cmdlets whose names contain the *Item* noun (the `*-Item` cmdlets), except for [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md). And, it supports the [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) and [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) cmdlets. However, it does not support the cmdlets whose names contain the *ItemProperty* noun (the `*-ItemProperty` cmdlets), and it does not support the `-Filter` parameter in any cmdlet. ## Capabilities - ShouldProcess + ShouldProcess ## Examples @@ -60,7 +58,7 @@ online version: http://go.microsoft.com/fwlink/?LinkId=834961 #### Example 1 - Changes the current location to the `Function:` drive. You can use this command from any drive in Windows PowerShell. To return to a file system drive, type the drive name. For example, type `set-location c:`. + Changes the current location to the `Function:` drive. You can use this command from any drive in Windows PowerShell. To return to a file system drive, type the drive name. For example, type `set-location c:`. ```powershell Set-Location Function: @@ -72,7 +70,7 @@ Set-Location Function: #### Example 1 - This command gets the list of all the functions in the current session. You can use this command from any Windows PowerShell drive. + This command gets the list of all the functions in the current session. You can use this command from any Windows PowerShell drive. ```powershell Get-ChildItem -Path Function: @@ -81,26 +79,26 @@ Get-ChildItem -Path Function: #### Example 2 - This command gets the `man` function from the `Function:` drive. It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get the function. The pipeline operator (`|`) sends the result to [Format-Table](../../Microsoft.PowerShell.Utility/Format-Table.md). + This command gets the `man` function from the `Function:` drive. It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get the function. The pipeline operator (`|`) sends the result to [Format-Table](../../Microsoft.PowerShell.Utility/Format-Table.md). - The `-Wrap` parameter directs text that does not fit on the line onto the next line. The `-Autosize` parameter resizes the table columns to accommodate the text. + The `-Wrap` parameter directs text that does not fit on the line onto the next line. The `-Autosize` parameter resizes the table columns to accommodate the text. ```powershell Get-Item -Path man | Format-Table -Wrap -Autosize ``` - If you are in a different drive, add the drive name (`Function:`) to the path. + If you are in a different drive, add the drive name (`Function:`) to the path. #### Example 3 - These commands both get the function named `c:`. The first command can be used in any drive. The second command is used in the `Function:` drive. + These commands both get the function named `c:`. The first command can be used in any drive. The second command is used in the `Function:` drive. - Because the name ends in a colon, which is the syntax for a drive, you must qualify the path with the drive name. Within the `Function:` drive, you can use either format. In the second command, the dot (`.`) represents the current location. + Because the name ends in a colon, which is the syntax for a drive, you must qualify the path with the drive name. Within the `Function:` drive, you can use either format. In the second command, the dot (`.`) represents the current location. ``` c:\PS> Get-Item -Path Function:c: -PS Function> Get-Item -Path .\c: +PS Function> Get-Item -Path .\c: ``` @@ -109,25 +107,25 @@ PS Function> Get-Item -Path .\c: #### Example 1 - This command uses the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create a function called `HKLM:`. The expression in braces is the script block that is represented by the function name. + This command uses the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create a function called `HKLM:`. The expression in braces is the script block that is represented by the function name. ```powershell New-Item -Path Function:HKLM: -Value {Set-Location HKLM:} ``` - You can also create a function by typing it at the Windows PowerShell command line. For example, tpe `Function:HKLM: {set-location HKLM:}`. If you are in the `Function:` drive, you can omit the drive name. -Because you cannot specify the "Filter" label in [New-Item](../../Microsoft.PowerShell.Management/New-Item.md), filters are labeled as functions, but they operate properly with any label. To create a filter with the "Filter" label, type the filter at the command line. For example, type `filter:Running {$_.Status -eq "Running"}`. + You can also create a function by typing it at the Windows PowerShell command line. For example, tpe `Function:HKLM: {set-location HKLM:}`. If you are in the `Function:` drive, you can omit the drive name. +Because you cannot specify the "Filter" label in [New-Item](../../Microsoft.PowerShell.Management/New-Item.md), filters are labeled as functions, but they operate properly with any label. To create a filter with the "Filter" label, type the filter at the command line. For example, type `filter:Running {$_.Status -eq "Running"}`. #### Example 2 - This command uses the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create a function called `Csrss`. It uses the `-Options` dynamic parameter to specify a value of `ReadOnly` for the **Options** property of the function. + This command uses the [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) cmdlet to create a function called `Csrss`. It uses the `-Options` dynamic parameter to specify a value of `ReadOnly` for the **Options** property of the function. ```powershell New-Item -Path Function: -Name csrss -Options readonly -Value {Get-Process csrss} ``` - This command works from any location. If you are in the `Function:` drive, you can use a dot (`.`) to specify the path. The dot represents the current location. + This command works from any location. If you are in the `Function:` drive, you can use a dot (`.`) to specify the path. The dot represents the current location. ### Deleting a function @@ -135,7 +133,7 @@ New-Item -Path Function: -Name csrss -Options readonly -Value {Get-Process csrss #### Example 1 - This command deletes the `HKLM:` function from the current session. + This command deletes the `HKLM:` function from the current session. ```powershell Remove-Item Function:HKLM: @@ -144,13 +142,13 @@ Remove-Item Function:HKLM: #### Example 2 - This command deletes all the functions from the current session except for the functions whose **Options** property has a value of `Constant`. Without the `-Force` parameter, the command does not delete functions whose **Options** property has a value of `ReadOnly`. + This command deletes all the functions from the current session except for the functions whose **Options** property has a value of `Constant`. Without the `-Force` parameter, the command does not delete functions whose **Options** property has a value of `ReadOnly`. ```powershell Remove-Item Function:* -Force ``` - When you delete all the functions, the command prompt changes because the prompt function, which defines the content of the command prompt, is deleted. + When you delete all the functions, the command prompt changes because the prompt function, which defines the content of the command prompt, is deleted. ### Displaying the properties and methods of functions @@ -158,19 +156,19 @@ Remove-Item Function:* -Force #### Example 1 - This command uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get all the functions. The pipeline operator sends the results to the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) cmdlet, which displays the methods and the properties of the object. + This command uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get all the functions. The pipeline operator sends the results to the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) cmdlet, which displays the methods and the properties of the object. ```powershell Get-Item -Path Function:* | Get-Member ``` - When you pipe a collection of objects (such as the collection of functions in the `Function:` drive) to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates each object in the collection separately and returns information about each object type that it finds. If all of the objects are of the same type, it returns information about the single object type. In this case, all of the functions are [FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) objects. -To get information about the collection of [FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) objects, use the `-InputObject` parameter of [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md). For example, type `Get-Member -InputObject (Get-Item Function:*)`. When you use the `-InputObject` parameter, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates the collection, not the objects in the collection. + When you pipe a collection of objects (such as the collection of functions in the `Function:` drive) to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates each object in the collection separately and returns information about each object type that it finds. If all of the objects are of the same type, it returns information about the single object type. In this case, all of the functions are [FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) objects. +To get information about the collection of [FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) objects, use the `-InputObject` parameter of [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md). For example, type `Get-Member -InputObject (Get-Item Function:*)`. When you use the `-InputObject` parameter, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates the collection, not the objects in the collection. #### Example 2 - This command lists the values of the properties of the `prompt` function. It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get an object that represents the `prompt` function. The pipeline operator (`|`) sends the results to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command. The [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command uses the `-Property` parameter with a wildcard character (`*`) to format and to display the values of all of the properties of the `prompt` function. + This command lists the values of the properties of the `prompt` function. It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get an object that represents the `prompt` function. The pipeline operator (`|`) sends the results to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command. The [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command uses the `-Property` parameter with a wildcard character (`*`) to format and to display the values of all of the properties of the `prompt` function. ```powershell Get-Item Function:prompt | Format-List -Property * @@ -182,9 +180,9 @@ Get-Item Function:prompt | Format-List -Property * #### Example 1 - You can use the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet with the `-Options` dynamic parameter to change the value of the **Options** property of a function. + You can use the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet with the `-Options` dynamic parameter to change the value of the **Options** property of a function. - This command sets the `AllScope` and `ReadOnly` options for the `prompt` function. This command uses the `-Options` dynamic parameter of the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet. The `-Options` parameter is available in [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) only when you use it with the **Alias** or **Function** provider. + This command sets the `AllScope` and `ReadOnly` options for the `prompt` function. This command uses the `-Options` dynamic parameter of the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet. The `-Options` parameter is available in [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) only when you use it with the **Alias** or **Function** provider. ```powershell Set-Item -Path Function:prompt -Options "AllScope,ReadOnly" @@ -193,18 +191,18 @@ Set-Item -Path Function:prompt -Options "AllScope,ReadOnly" #### Example 2 - This command uses the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet to change the `prompt` function so that it displays the time before the path. + This command uses the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet to change the `prompt` function so that it displays the time before the path. ```powershell Set-Item -Path Function:prompt -Value {'PS '+ $(Get-Date -Format t) + " " + $(Get-Location) + '> '} ``` - The change affects both the **Definition** and **ScriptBlock** properties of the [FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) object. To see the effect of the change, type `Get-Item -Path Function:prompt | Format-List -Property *`. + The change affects both the **Definition** and **ScriptBlock** properties of the [FunctionInfo](https://msdn.microsoft.com/library/system.management.automation.functioninfo) object. To see the effect of the change, type `Get-Item -Path Function:prompt | Format-List -Property *`. #### Example 3 - This command uses the [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) cmdlet to change the name of the `help` function to `gh`. + This command uses the [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) cmdlet to change the name of the `help` function to `gh`. ```powershell Rename-Item -Path Function:help -NewName gh @@ -216,9 +214,9 @@ Rename-Item -Path Function:help -NewName gh #### Example 1 - This command copies the `prompt` function to `oldPrompt`, effectively creating a new name for the script block that is associated with the prompt function. You can use this to save the original prompt function if you plan to change it. + This command copies the `prompt` function to `oldPrompt`, effectively creating a new name for the script block that is associated with the prompt function. You can use this to save the original prompt function if you plan to change it. - The **Options** property of the new function has a value of `None`. To change the value of the **Options** property, use [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md). + The **Options** property of the new function has a value of `None`. To change the value of the **Options** property, use [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md). ```powershell Copy-Item -Path Function:prompt -Destination Function:oldPrompt @@ -227,32 +225,32 @@ Copy-Item -Path Function:prompt -Destination Function:oldPrompt ## 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. + 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. ### `Options` <[System.Management.Automation.ScopedItemOptions](https://msdn.microsoft.com/library/system.management.automation.scopeditemoptions)> - Determines the value of the **Options** property of a function. + Determines the value of the **Options** property of a function. -|Value|Description| -|-----------|-----------------| -|`None`|No options. `None` is the default.| -|`Constant`|The function cannot be deleted, and its properties cannot be changed. `Constant` is available only when you are creating a function. You cannot change the option of an existing function to `Constant`.| -|`Private`|The function is visible only in the current scope (not in child scopes).| -|`ReadOnly`|The properties of the function cannot be changed except by using the `-Force` parameter. You can use [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) to delete the function.| -|`AllScope`|The function is copied to any new scopes that are created.| +|Value|Description| +|-----------|-----------------| +|`None`|No options. `None` is the default.| +|`Constant`|The function cannot be deleted, and its properties cannot be changed. `Constant` is available only when you are creating a function. You cannot change the option of an existing function to `Constant`.| +|`Private`|The function is visible only in the current scope (not in child scopes).| +|`ReadOnly`|The properties of the function cannot be changed except by using the `-Force` parameter. You can use [Remove-Item](../../Microsoft.PowerShell.Management/Remove-Item.md) to delete the function.| +|`AllScope`|The function is copied to any new scopes that are created.| #### Cmdlets supported: -- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) +- [New-Item](../../Microsoft.PowerShell.Management/New-Item.md) -- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) +- [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) ## See also - [about_Functions](../About/about_Functions.md) + [about_Functions](../About/about_Functions.md) [about_Providers](../About/about_Providers.md) diff --git a/reference/6/Microsoft.PowerShell.Core/Providers/Variable-Provider.md b/reference/6/Microsoft.PowerShell.Core/Providers/Variable-Provider.md index 5def5c3f3a32..54fee4a291cf 100644 --- a/reference/6/Microsoft.PowerShell.Core/Providers/Variable-Provider.md +++ b/reference/6/Microsoft.PowerShell.Core/Providers/Variable-Provider.md @@ -13,51 +13,49 @@ online version: http://go.microsoft.com/fwlink/?LinkId=834963 ## Provider name - Variable + Variable ## Drives - `Variable:` + `Variable:` ## Short description - Provides access to the Windows PowerShell variables and to their values. + Provides access to the Windows PowerShell variables and to their values. ## Detailed description - The Windows PowerShell **Variable** provider lets you get, add, change, clear, and delete Windows PowerShell variables in the current console. + The Windows PowerShell **Variable** provider lets you get, add, change, clear, and delete Windows PowerShell variables in the current console. - The Windows PowerShell **Variable** provider supports the variables that Windows PowerShell creates, including the automatic variables, the preference variables, and the variables that you create. + The Windows PowerShell **Variable** provider supports the variables that Windows PowerShell creates, including the automatic variables, the preference variables, and the variables that you create. - The **Variable** provider is a flat namespace that contains only the variable objects. The variables have no child items. + The **Variable** provider is a flat namespace that contains only the variable objects. The variables have no child items. - Most of the variables are instances of the [System.Management.Automation.PSVariable](https://msdn.microsoft.com/library/system.management.automation.psvariable) class. However, there are some variations. For example, the `?` variable is a member of the `QuestionMarkVariable` internal class, and the `MaximumVariableCount` variable is a member of the `SessionStateCapacityVariable` internal class. + Most of the variables are instances of the [System.Management.Automation.PSVariable](https://msdn.microsoft.com/library/system.management.automation.psvariable) class. However, there are some variations. For example, the `?` variable is a member of the `QuestionMarkVariable` internal class, and the `MaximumVariableCount` variable is a member of the `SessionStateCapacityVariable` internal class. - The **Variable** provider exposes its data store in the `Variable:` drive. To work with variables, you can change your location to the `Variable:` drive (`set-location Variable:`), or you can work from any other Windows PowerShell drive. To reference a variable from another location, use the drive name (`Variable:`) in the path. + The **Variable** provider exposes its data store in the `Variable:` drive. To work with variables, you can change your location to the `Variable:` drive (`set-location Variable:`), or you can work from any other Windows PowerShell drive. To reference a variable from another location, use the drive name (`Variable:`) in the path. - Windows PowerShell includes a set of cmdlets designed especially to view and to change variables: + Windows PowerShell includes a set of cmdlets designed especially to view and to change variables: - - [Get-Variable](../../Microsoft.PowerShell.Utility/Get-Variable.md) - - [New-Variable](../../Microsoft.PowerShell.Utility/New-Variable.md) - - [Set-Variable](../../Microsoft.PowerShell.Utility/Set-Variable.md) - - [Remove-Variable](../../Microsoft.PowerShell.Utility/Remove-Variable.md) - - [Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) + - [Get-Variable](../../Microsoft.PowerShell.Utility/Get-Variable.md) + - [New-Variable](../../Microsoft.PowerShell.Utility/New-Variable.md) + - [Set-Variable](../../Microsoft.PowerShell.Utility/Set-Variable.md) + - [Remove-Variable](../../Microsoft.PowerShell.Utility/Remove-Variable.md) + - [Clear-Variable](../../Microsoft.PowerShell.Utility/Clear-Variable.md) - When you use these cmdlets, you do not need to specify the `Variable:` drive in the name. + When you use these cmdlets, you do not need to specify the `Variable:` drive in the name. - The **Variable** provider supports all of the cmdlets whose names contain the *Item* noun (the `*-Item` cmdlets), except for [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md). The **Variable** provider supports the [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) and [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) cmdlets. However, it does not support the cmdlets whose names contain the *ItemProperty* noun (the `*-ItemProperty` cmdlets), and it does not support the `-Filter` parameter in any cmdlet. + The **Variable** provider supports all of the cmdlets whose names contain the *Item* noun (the `*-Item` cmdlets), except for [Invoke-Item](../../Microsoft.PowerShell.Management/Invoke-Item.md). The **Variable** provider supports the [Get-Content](../../Microsoft.PowerShell.Management/Get-Content.md) and [Set-Content](../../Microsoft.PowerShell.Management/Set-Content.md) cmdlets. However, it does not support the cmdlets whose names contain the *ItemProperty* noun (the `*-ItemProperty` cmdlets), and it does not support the `-Filter` parameter in any cmdlet. - You can also use the Windows PowerShell expression parser to create, view, and change the values of variables without using the cmdlets. When working with variables directly, use a dollar sign (`$`) to identify the name as a variable and the assignment operator (`=`) to establish and change its value. For example, `$p = Get-Process` creates the `p` variable and stores the results of a `Get-Process` command in it. - - All changes to the variables affect the current session only. To save the changes, add the changes to the Windows PowerShell profile, or use [Export-Console](there-should-be-an-external-link) to save the current console. + You can also use the Windows PowerShell expression parser to create, view, and change the values of variables without using the cmdlets. When working with variables directly, use a dollar sign (`$`) to identify the name as a variable and the assignment operator (`=`) to establish and change its value. For example, `$p = Get-Process` creates the `p` variable and stores the results of a `Get-Process` command in it. ## Capabilities - ShouldProcess + ShouldProcess ## Examples @@ -68,7 +66,7 @@ online version: http://go.microsoft.com/fwlink/?LinkId=834963 #### Example 1 - This command changes the current location to the `Variable:` drive. You can use this command from any drive in Windows PowerShell. To return to a file system drive, type the drive name. For example, type `set-location c:`. + This command changes the current location to the `Variable:` drive. You can use this command from any drive in Windows PowerShell. To return to a file system drive, type the drive name. For example, type `set-location c:`. ```powershell Set-Location Variable: @@ -80,7 +78,7 @@ Set-Location Variable: #### Example 1 - This command gets the list of all the variables and their values in the current session. You can use this command from any Windows PowerShell drive. + This command gets the list of all the variables and their values in the current session. You can use this command from any Windows PowerShell drive. ```powershell Get-ChildItem -Path Variable: @@ -89,20 +87,20 @@ Get-ChildItem -Path Variable: #### Example 2 - This command gets the variables with names that begin with "max". You can use this command from any Windows PowerShell drive. + This command gets the variables with names that begin with "max". You can use this command from any Windows PowerShell drive. ```powershell Get-ChildItem -Path Variable:max* ``` - If you are in the `Variable:` drive, you can omit the drive name from the path. + If you are in the `Variable:` drive, you can omit the drive name from the path. #### Example 3 - This command gets the value of the `WhatIfPreference` variable by typing it at the command line. + This command gets the value of the `WhatIfPreference` variable by typing it at the command line. - The name of the variable is preceded by a dollar sign (`$`) to indicate that it is a variable. The `Variable:` drive name is not specified. + The name of the variable is preceded by a dollar sign (`$`) to indicate that it is a variable. The `Variable:` drive name is not specified. ```powershell $WhatIfPreference @@ -111,18 +109,18 @@ $WhatIfPreference #### Example 4 - This command uses the `-LiteralPath` parameter of [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) to get the value of the `?` variable from within the `Variable:` drive. [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) does not attempt to resolve any wildcards in the values of the `-LiteralPath` parameter. + This command uses the `-LiteralPath` parameter of [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) to get the value of the `?` variable from within the `Variable:` drive. [Get-ChildItem](../../Microsoft.PowerShell.Management/Get-ChildItem.md) does not attempt to resolve any wildcards in the values of the `-LiteralPath` parameter. ```powershell Get-ChildItem -Literalpath ? ``` - To display the value of a variable with a special character name without a cmdlet, type a dollar sign (`$`) and the variable name. For example, to display the value of the `?` variable, type `$?`. + To display the value of a variable with a special character name without a cmdlet, type a dollar sign (`$`) and the variable name. For example, to display the value of the `?` variable, type `$?`. #### Example 5 - This command gets the variables that have the values of `ReadOnly` or `Constant` for their **Options** property. + This command gets the variables that have the values of `ReadOnly` or `Constant` for their **Options** property. ```powershell Get-ChildItem -Path Variable: | Where-Object {$_.options -Match "Constant" -or $_.options -Match "ReadOnly"} | Format-List -Property name, value, options @@ -134,28 +132,28 @@ Get-ChildItem -Path Variable: | Where-Object {$_.options -Match "Constant" -or $ #### Example 1 - This command creates the `services` variable and stores the results of a [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command in it. Because the current location is in the `Variable:` drive, the value of the `-Path` parameter is a dot (`.`), which represents the current location. + This command creates the `services` variable and stores the results of a [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command in it. Because the current location is in the `Variable:` drive, the value of the `-Path` parameter is a dot (`.`), which represents the current location. - The parentheses around the [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command ensure that the command is executed before the variable is created. Without the parentheses, the value of the new variable is a "Get-Service" string. + The parentheses around the [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command ensure that the command is executed before the variable is created. Without the parentheses, the value of the new variable is a "Get-Service" string. ```powershell New-Item -Path . -Name services -Value (Get-Service) ``` - If you are not in the `Variable:` drive, include the `Variable:` drive name in the path. + If you are not in the `Variable:` drive, include the `Variable:` drive name in the path. #### Example 2 - This command creates a `services` variable and stores the result of a [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command in it. + This command creates a `services` variable and stores the result of a [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command in it. - The command uses a dollar sign (`$`) to indicate a variable and the assignment operator (`=`) to assign the result of the [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command to the newly created variable. + The command uses a dollar sign (`$`) to indicate a variable and the assignment operator (`=`) to assign the result of the [Get-Service](../../Microsoft.PowerShell.Management/Get-Service.md) command to the newly created variable. ```powershell $services = Get-Service ``` - To create a variable without a value, omit the assignment operator. + To create a variable without a value, omit the assignment operator. ### Displaying the properties and methods of variables @@ -163,19 +161,19 @@ $services = Get-Service #### Example 1 - This command uses the Get-Item cmdlet to get all variables. The pipeline operator (`|`) sends the results to the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) cmdlet, which displays the methods and properties of the object. + This command uses the Get-Item cmdlet to get all variables. The pipeline operator (`|`) sends the results to the [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) cmdlet, which displays the methods and properties of the object. ```powershell Get-Item -Path Variable:* | Get-Member ``` - When you pipe a collection of objects (such as the collection of variables in the `Variable:` drive) to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates each object in the collection separately and returns information about each of the object types that it finds. -To get information about the collection of objects in the `Variable:` drive, use the `-InputObject` parameter of [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md). For example, `Get-Member -InputObject (Get-Item Variable:*)`. When you use `-InputObject`, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates the collection, not the objects in the collection. + When you pipe a collection of objects (such as the collection of variables in the `Variable:` drive) to [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md), [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates each object in the collection separately and returns information about each of the object types that it finds. +To get information about the collection of objects in the `Variable:` drive, use the `-InputObject` parameter of [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md). For example, `Get-Member -InputObject (Get-Item Variable:*)`. When you use `-InputObject`, [Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) evaluates the collection, not the objects in the collection. #### Example 2 - This command lists the values of the properties of the `home` variable. It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get an object that represents the `home` variable. The pipeline operator (`|`) sends the results to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command. The [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command uses the `-Property` parameter with a wildcard character (`*`) to format and to display the values of all of the properties of the `home` variable. + This command lists the values of the properties of the `home` variable. It uses the [Get-Item](../../Microsoft.PowerShell.Management/Get-Item.md) cmdlet to get an object that represents the `home` variable. The pipeline operator (`|`) sends the results to the [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command. The [Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) command uses the `-Property` parameter with a wildcard character (`*`) to format and to display the values of all of the properties of the `home` variable. ```powershell Get-Item Variable:home | Format-List -Property * @@ -187,7 +185,7 @@ Get-Item Variable:home | Format-List -Property * #### Example 1 - This command uses the [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) cmdlet to change the name of the `a` variable to `processes`. + This command uses the [Rename-Item](../../Microsoft.PowerShell.Management/Rename-Item.md) cmdlet to change the name of the `a` variable to `processes`. ```powershell Rename-Item -Path Variable:a -NewName processes @@ -196,7 +194,7 @@ Rename-Item -Path Variable:a -NewName processes #### Example 2 - This command uses the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet to change the value of the `ErrorActionPreference` variable to "Stop". + This command uses the [Set-Item](../../Microsoft.PowerShell.Management/Set-Item.md) cmdlet to change the value of the `ErrorActionPreference` variable to "Stop". ```powershell Set-Item -Path Variable:ErrorActionPreference -Value Stop @@ -205,9 +203,9 @@ Set-Item -Path Variable:ErrorActionPreference -Value Stop #### Example 3 - This command changes the value of the `ErrorActionPreference` variable to "Stop". + This command changes the value of the `ErrorActionPreference` variable to "Stop". - It uses a dollar sign (`$`) to indicate a variable and the assignment operator (`=`) to assign the value. + It uses a dollar sign (`$`) to indicate a variable and the assignment operator (`=`) to assign the value. ```powershell $ErrorActionPreference = Stop @@ -219,18 +217,18 @@ $ErrorActionPreference = Stop #### Example 1 - This command uses the [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md) cmdlet to copy the `processes` variable to `old_processes`. This creates a new variable named `old_processes` that has the same value as the `processes` variable. + This command uses the [Copy-Item](../../Microsoft.PowerShell.Management/Copy-Item.md) cmdlet to copy the `processes` variable to `old_processes`. This creates a new variable named `old_processes` that has the same value as the `processes` variable. ```powershell Copy-Item -Path Variable:processes -Destination Variable:old_processes ``` - If the command is issued from within the `Variable:` drive, you can omit the drive name from the value of the `-Path` parameter. + If the command is issued from within the `Variable:` drive, you can omit the drive name from the value of the `-Path` parameter. #### Example 2 - This command copies the `processes` variable to `old_processes` without using a cmdlet. It uses the dollar sign (`$`) to indicate variables and the assignment operator to assign the value of `$processes` to `old_processes`. + This command copies the `processes` variable to `old_processes` without using a cmdlet. It uses the dollar sign (`$`) to indicate variables and the assignment operator to assign the value of `$processes` to `old_processes`. ```powershell $old_processes = $processes @@ -242,7 +240,7 @@ $old_processes = $processes #### Example 1 - This command deletes the `serv` variable from the current session. You can use this command in any Windows PowerShell drive. + This command deletes the `serv` variable from the current session. You can use this command in any Windows PowerShell drive. ```powershell Remove-Variable -Path Variable:serv @@ -251,7 +249,7 @@ Remove-Variable -Path Variable:serv #### Example 2 - This command deletes all variables from the current session except for the variables whose **Options** property has a value of `Constant`. Without the `-Force` parameter, the command does not delete variables whose **Options** property has a value of `ReadOnly`. + This command deletes all variables from the current session except for the variables whose **Options** property has a value of `Constant`. Without the `-Force` parameter, the command does not delete variables whose **Options** property has a value of `ReadOnly`. ```powershell Remove-Item Variable:* -Force @@ -263,7 +261,7 @@ Remove-Item Variable:* -Force #### Example 1 - This command uses the [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) cmdlet to change the value of the `processes` variable to NULL. + This command uses the [Clear-Item](../../Microsoft.PowerShell.Management/Clear-Item.md) cmdlet to change the value of the `processes` variable to NULL. ```powershell Clear-Item -Path Variable:processes @@ -272,7 +270,7 @@ Clear-Item -Path Variable:processes #### Example 2 - This command clears the value of the `processes` variable by assigning a null value to it. It uses the `$null` automatic variable to represent the NULL value. + This command clears the value of the `processes` variable by assigning a null value to it. It uses the `$null` automatic variable to represent the NULL value. ```powershell $processes = $null @@ -281,7 +279,7 @@ $processes = $null ## See also - [about_Variables](../About/about_Variables.md) - [about_Automatic_Variables](../About/about_Automatic_Variables.md) + [about_Variables](../About/about_Variables.md) + [about_Automatic_Variables](../About/about_Automatic_Variables.md) [about_Providers](../About/about_Providers.md) diff --git a/reference/docfx.json b/reference/docfx.json index 04bbc9671568..ffb21c5245ab 100644 --- a/reference/docfx.json +++ b/reference/docfx.json @@ -1,289 +1,50 @@ { "build": { - "content": [{ - "files": [ - "bread-pscore/toc.yml" - ] - }, - { - "files": [ - "toc.yml" - ], - "src": "docs-conceptual", - "version": "powershell-3.0", - "dest": "scripting/powershell-3.0" - }, - { - "files": [ - "**/*.md" - ], - "src": "docs-conceptual", - "version": "powershell-3.0", - "dest": "scripting" - }, - { - "files": [ - "toc.yml" - ], - "src": "3.0", - "version": "powershell-3.0", - "dest": "module/psdocs" - }, - { - "files": [ - "**/*.md" - ], - "src": "3.0", - "version": "powershell-3.0", - "exclude": [ - "docs-conceptual/**" - ], - "dest": "module" - }, - { - "files": [ - "toc.yml" - ], - "src": "docs-conceptual", - "version": "powershell-4.0", - "dest": "scripting/powershell-4.0" - }, - { - "files": [ - "**/*.md" - ], - "src": "docs-conceptual", - "version": "powershell-4.0", - "dest": "scripting" - }, - { - "files": [ - "toc.yml" - ], - "src": "4.0", - "version": "powershell-4.0", - "dest": "module/psdocs" - }, - { - "files": [ - "**/*.md" - ], - "src": "4.0", - "version": "powershell-4.0", - "exclude": [ - "docs-conceptual/**" - ], - "dest": "module" - }, - { - "files": [ - "toc.yml" - ], - "src": "docs-conceptual", - "version": "powershell-5.0", - "dest": "scripting/powershell-5.0" - }, - { - "files": [ - "**/*.md" - ], - "src": "docs-conceptual", - "version": "powershell-5.0", - "dest": "scripting" - }, - { - "files": [ - "toc.yml" - ], - "src": "5.0", - "version": "powershell-5.0", - "dest": "module/psdocs" - }, - { - "files": [ - "**/*.md" - ], - "src": "5.0", - "version": "powershell-5.0", - "exclude": [ - "docs-conceptual/**" - ], - "dest": "module" - }, - { - "files": [ - "toc.yml" - ], - "src": "docs-conceptual", - "version": "powershell-5.1", - "dest": "scripting/powershell-5.1" - }, - { - "files": [ - "**/*.md" - ], - "src": "docs-conceptual", - "version": "powershell-5.1", - "dest": "scripting" - }, - { - "files": [ - "toc.yml" - ], - "src": "5.1", - "version": "powershell-5.1", - "dest": "module/psdocs" - }, - { - "files": [ - "**/*.md" - ], - "src": "5.1", - "version": "powershell-5.1", - "exclude": [ - "docs-conceptual/**" - ], - "dest": "module" - }, - { - "files": [ - "toc.yml" - ], - "src": "docs-conceptual", - "version": "powershell-6", - "dest": "scripting/powershell-6" - }, - { - "files": [ - "**/*.md" - ], - "src": "docs-conceptual", - "version": "powershell-6", - "dest": "scripting" - }, - { - "files": [ - "toc.yml" - ], - "src": "6", - "version": "powershell-6", - "dest": "module/psdocs" - }, - { - "files": [ - "**/*.md" - ], - "src": "6", - "version": "powershell-6", - "exclude": [ - "docs-conceptual/**" - ], - "dest": "module" - }, - { - "files": [ - "**/*.md" - ], - "src": "virtual-directory", - "dest": "scripting" - }, - { - "files": [ - "**/*.md" - ], - "src": "virtual-directory-module", - "dest": "module" - } + "content": [ + { "files": [ "bread-pscore/toc.yml" ] }, + + { "files": [ "toc.yml" ], "src": "docs-conceptual", "version": "powershell-3.0", "dest": "scripting/powershell-3.0" }, + { "files": [ "**/*.md" ], "src": "docs-conceptual", "version": "powershell-3.0", "dest": "scripting" }, + { "files": [ "toc.yml" ], "src": "3.0", "version": "powershell-3.0", "dest": "module/psdocs" }, + { "files": [ "**/*.md" ], "src": "3.0", "version": "powershell-3.0", "exclude": [ "docs-conceptual/**" ], "dest": "module" }, + + { "files": [ "toc.yml" ], "src": "docs-conceptual", "version": "powershell-4.0", "dest": "scripting/powershell-4.0" }, + { "files": [ "**/*.md" ], "src": "docs-conceptual", "version": "powershell-4.0", "dest": "scripting" }, + { "files": [ "toc.yml" ], "src": "4.0", "version": "powershell-4.0", "dest": "module/psdocs" }, + { "files": [ "**/*.md" ], "src": "4.0", "version": "powershell-4.0", "exclude": [ "docs-conceptual/**" ], "dest": "module" }, + + { "files": [ "toc.yml" ], "src": "docs-conceptual", "version": "powershell-5.0", "dest": "scripting/powershell-5.0" }, + { "files": [ "**/*.md" ], "src": "docs-conceptual", "version": "powershell-5.0", "dest": "scripting" }, + { "files": [ "toc.yml" ], "src": "5.0", "version": "powershell-5.0", "dest": "module/psdocs" }, + { "files": [ "**/*.md" ], "src": "5.0", "version": "powershell-5.0", "exclude": [ "docs-conceptual/**" ], "dest": "module" }, + + { "files": [ "toc.yml" ], "src": "docs-conceptual", "version": "powershell-5.1", "dest": "scripting/powershell-5.1" }, + { "files": [ "**/*.md" ], "src": "docs-conceptual", "version": "powershell-5.1", "dest": "scripting" }, + { "files": [ "toc.yml" ], "src": "5.1", "version": "powershell-5.1", "dest": "module/psdocs" }, + { "files": [ "**/*.md" ], "src": "5.1", "version": "powershell-5.1", "exclude": [ "docs-conceptual/**" ], "dest": "module" }, + + { "files": [ "toc.yml" ], "src": "docs-conceptual", "version": "powershell-6", "dest": "scripting/powershell-6" }, + { "files": [ "**/*.md" ], "src": "docs-conceptual", "version": "powershell-6", "dest": "scripting" }, + { "files": [ "toc.yml" ], "src": "6", "version": "powershell-6", "dest": "module/psdocs" }, + { "files": [ "**/*.md" ], "src": "6", "version": "powershell-6", "exclude": [ "docs-conceptual/**" ], "dest": "module" }, + + { "files": [ "**/*.md" ], "src": "virtual-directory", "dest": "scripting" }, + { "files": [ "**/*.md" ], "src": "virtual-directory-module", "dest": "module" } ], "resource": [ - { - "files": [ - "**/images/**", - "**/*.png", - "**/*.jpg" - ], - "exclude": [ - "**/obj/**", - "**/includes/**" - ] - }, - { - "files": [ - "**/images/**", - "**/*.png", - "**/*.jpg" - ], - "exclude": [ - "**/obj/**", - "**/includes/**" - ], - "version": "powershell-3.0" - }, - { - "files": [ - "**/images/**", - "**/*.png", - "**/*.jpg" - ], - "exclude": [ - "**/obj/**", - "**/includes/**" - ], - "version": "powershell-4.0" - }, - { - "files": [ - "**/images/**", - "**/*.png", - "**/*.jpg" - ], - "exclude": [ - "**/obj/**", - "**/includes/**" - ], - "version": "powershell-5.0" - }, - { - "files": [ - "**/images/**", - "**/*.png", - "**/*.jpg" - ], - "exclude": [ - "**/obj/**", - "**/includes/**" - ], - "version": "powershell-5.1" - }, - { - "files": [ - "**/images/**", - "**/*.png", - "**/*.jpg" - ], - "exclude": [ - "**/obj/**", - "**/includes/**" - ], - "version": "powershell-6" - } + { "files": [ "**/images/**", "**/*.png", "**/*.gif", "**/*.jpeg", "**/*.jpg", "**/*.svg" ], "exclude": [ "**/obj/**", "**/includes/**" ] }, + { "files": [ "**/images/**", "**/*.png", "**/*.gif", "**/*.jpeg", "**/*.jpg", "**/*.svg" ], "exclude": [ "**/obj/**", "**/includes/**" ], "version": "powershell-3.0" }, + { "files": [ "**/images/**", "**/*.png", "**/*.gif", "**/*.jpeg", "**/*.jpg", "**/*.svg" ], "exclude": [ "**/obj/**", "**/includes/**" ], "version": "powershell-4.0" }, + { "files": [ "**/images/**", "**/*.png", "**/*.gif", "**/*.jpeg", "**/*.jpg", "**/*.svg" ], "exclude": [ "**/obj/**", "**/includes/**" ], "version": "powershell-5.0" }, + { "files": [ "**/images/**", "**/*.png", "**/*.gif", "**/*.jpeg", "**/*.jpg", "**/*.svg" ], "exclude": [ "**/obj/**", "**/includes/**" ], "version": "powershell-5.1" }, + { "files": [ "**/images/**", "**/*.png", "**/*.gif", "**/*.jpeg", "**/*.jpg", "**/*.svg" ], "exclude": [ "**/obj/**", "**/includes/**" ], "version": "powershell-6" } ], "versions": { - "powershell-3.0": { - "dest": "powershell-3.0" - }, - "powershell-4.0": { - "dest": "powershell-4.0" - }, - "powershell-5.0": { - "dest": "powershell-5.0" - }, - "powershell-5.1": { - "dest": "powershell-5.1" - }, - "powershell-6": { - "dest": "powershell-6" - } + "powershell-3.0": { "dest": "powershell-3.0" }, + "powershell-4.0": { "dest": "powershell-4.0" }, + "powershell-5.0": { "dest": "powershell-5.0" }, + "powershell-5.1": { "dest": "powershell-5.1" }, + "powershell-6": { "dest": "powershell-6" } }, "overwrite": [], "externalReference": [], diff --git a/reference/docs-conceptual/core-powershell/console-guide.md b/reference/docs-conceptual/core-powershell/console-guide.md deleted file mode 100644 index 14ce91ffdc25..000000000000 --- a/reference/docs-conceptual/core-powershell/console-guide.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -ms.date: 2017-06-05 -keywords: powershell,cmdlet -title: console guide ---- - -# PowerShell Console Window Guide - -Find in this guide: -- [PowerShell.exe Command Line Help](console/PowerShell.exe-Command-Line-Help.md) -- [Using Tab Expansion](console/Using-Tab-Expansion.md) - diff --git a/reference/docs-conceptual/core-powershell/ise-guide.md b/reference/docs-conceptual/core-powershell/ise-guide.md deleted file mode 100644 index 4356c2494e82..000000000000 --- a/reference/docs-conceptual/core-powershell/ise-guide.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -ms.date: 2017-06-05 -keywords: powershell,cmdlet -title: ise guide ---- - -# ISE Guide - -- [How to Create a PowerShell Tab in Windows PowerShell ISE](ise/How-to-Create-a-PowerShell-Tab-in-Windows-PowerShell-ISE.md) -- [How to Debug Scripts in Windows PowerShell ISE](ise/How-to-Debug-Scripts-in-Windows-PowerShell-ISE.md) -- [How to Use Profiles in Windows PowerShell ISE](ise/How-to-Use-Profiles-in-Windows-PowerShell-ISE.md) -- [How to Use Tab Completion in the Script Pane and Console Pane](ise/How-to-Use-Tab-Completion-in-the-Script-Pane-and-Console-Pane.md) -- [How to Use the Console Pane in the Windows PowerShell ISE](ise/How-to-Use-the-Console-Pane-in-the-Windows-PowerShell-ISE.md) -- [How to Write and Run Scripts in the Windows PowerShell ISE](ise/How-to-Write-and-Run-Scripts-in-the-Windows-PowerShell-ISE.md) -- [Introducing the Windows PowerShell ISE](ise/Introducing-the-Windows-PowerShell-ISE.md) -- [ISE Module](ise/ISE-Module.md) -- [Keyboard Shortcuts for the Windows PowerShell ISE](ise/Keyboard-Shortcuts-for-the-Windows-PowerShell-ISE.md) -- [Purpose of the Windows PowerShell ISE Scripting Object Model](ise/Purpose-of-the-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [The ISE Object Model Hierarchy](ise/The-ISE-Object-Model-Hierarchy.md) -- [The ISEAddOnTool Object](ise/The-ISEAddOnTool-Object.md) -- [The ISEAddOnToolCollection Object](ise/The-ISEAddOnToolCollection-Object.md) -- [The ISEEditor Object](ise/The-ISEEditor-Object.md) -- [The ISEFile Object](ise/The-ISEFile-Object.md) -- [The ISEFileCollection Object](ise/The-ISEFileCollection-Object.md) -- [The ISEMenuItem Object](ise/The-ISEMenuItem-Object.md) -- [The ISEMenuItemCollection Object](ise/The-ISEMenuItemCollection-Object.md) -- [The ISEOptions Object](ise/The-ISEOptions-Object.md) -- [The ISESnippetCollection Object](ise/The-ISESnippetCollection-Object.md) -- [The ISESnippetObject](ise/The-ISESnippetObject.md) -- [The ObjectModelRoot Object](ise/The-ObjectModelRoot-Object.md) -- [The PowerShellTab Object](ise/The-PowerShellTab-Object.md) -- [The PowerShellTabCollection Object](ise/The-PowerShellTabCollection-Object.md) -- [The Windows PowerShell ISE Scripting Object Model](ise/The-Windows-PowerShell-ISE-Scripting-Object-Model.md) -- [Using the Windows PowerShell ISE](ise/Using-the-Windows-PowerShell-ISE.md) -- [Windows PowerShell ISE Object Model Reference](ise/Windows-PowerShell-ISE-Object-Model-Reference.md) - diff --git a/reference/docs-conceptual/getting-started/fundamental/Windows-PowerShell-Integrated-Scripting-Environment--ISE-.md b/reference/docs-conceptual/getting-started/fundamental/Windows-PowerShell-Integrated-Scripting-Environment--ISE-.md index e93fab433ffe..fa8a43a45ed6 100644 --- a/reference/docs-conceptual/getting-started/fundamental/Windows-PowerShell-Integrated-Scripting-Environment--ISE-.md +++ b/reference/docs-conceptual/getting-started/fundamental/Windows-PowerShell-Integrated-Scripting-Environment--ISE-.md @@ -63,5 +63,5 @@ Note that any entries labelled "Preview" are pre-release code and are not featur > Because Windows PowerShell ISE requires a graphical user interface, you can’t run it on the Server Core option of Windows Server. ## See also -- [Using the Windows PowerShell Integrated Scripting Environment](Using-the-Windows-PowerShell-ISE.md) +- [Using the Windows PowerShell Integrated Scripting Environment](../../core-powershell/ise/Using-the-Windows-PowerShell-ISE.md) diff --git a/reference/docs-conceptual/getting-started/understanding-concepts-reference.md b/reference/docs-conceptual/getting-started/understanding-concepts-reference.md deleted file mode 100644 index 75f3180da47b..000000000000 --- a/reference/docs-conceptual/getting-started/understanding-concepts-reference.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -ms.date: 2017-06-05 -keywords: powershell,cmdlet -title: understanding concepts reference ---- - -# Understanding Concepts - -* Objects in PowerShell -* [The Pipeline](./fundamental/understanding-the-windows-powershell-pipeline.md) -* Command Parsing -* Evaluating expressions -* Quoting and Escaping -* Operators -* [Variables and assignment](./fundamental/using-variables-to-store-objects.md) -* Command or cmdlet execution -* Native apps execution and parameter passing -* [Implicit and explicit output formatting](./cookbooks/using-format-commands-to-change-output-view.md) -* Developing a Formatting File -* Scripting language elements -* Integration with OS and Services -* Providers -* Drivers -* [Updating help](/powershell/module/Microsoft.PowerShell.Core/Update-Help) - diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index ef6d0676491c..95cefcc2907e 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -11,8 +11,6 @@ href: core-powershell/console/powershell.exe-command-line-help.md - name: Using Tab Expansion href: core-powershell/console/using-tab-expansion.md - - name: Console Guide - href: core-powershell/console-guide.md - name: ISE href: core-powershell/ise/introducing-the-windows-powershell-ise.md items: @@ -70,8 +68,6 @@ href: core-powershell/ise/using-the-windows-powershell-ise.md - name: Windows PowerShell ISE Object Model Reference href: core-powershell/ise/windows-powershell-ise-object-model-reference.md - - name: ISE Guide - href: core-powershell/ise-guide.md - name: Visual Studio Code items: - name: Using Visual Studio Code @@ -211,8 +207,6 @@ href: getting-started/getting-started-with-windows-powershell.md - name: More PowerShell learning href: getting-started/more-powershell-learning.md - - name: Understanding concepts reference - href: getting-started/understanding-concepts-reference.md - name: Setup href: '' items: diff --git a/reference/mapping/monikerMapping.json b/reference/mapping/monikerMapping.json index c188d50d7bc5..7e92667dc05f 100644 --- a/reference/mapping/monikerMapping.json +++ b/reference/mapping/monikerMapping.json @@ -54,13 +54,13 @@ "Microsoft.PowerShell.Security":{}, "Microsoft.PowerShell.Utility":{}, "Microsoft.WsMan.Management":{}, + "PackageManagement":{}, + "PowershellGet":{}, "PSDesiredStateConfiguration":{}, "PSReadline":{}, "PSScheduledJob":{}, "PSWorkflow":{}, - "PSWorkflowUtility":{}, - "PackageManagement":{}, - "PowershellGet":{} + "PSWorkflowUtility":{} } }, "powershell-5.1": { @@ -81,13 +81,13 @@ "Microsoft.PowerShell.Security":{}, "Microsoft.PowerShell.Utility":{}, "Microsoft.WsMan.Management":{}, + "PackageManagement":{}, + "PowershellGet":{}, "PSDesiredStateConfiguration":{}, "PSReadline":{}, "PSScheduledJob":{}, "PSWorkflow":{}, - "PSWorkflowUtility":{}, - "PackageManagement":{}, - "PowershellGet":{} + "PSWorkflowUtility":{} } }, "powershell-6": { @@ -101,18 +101,15 @@ "Microsoft.PowerShell.Core": {}, "Microsoft.PowerShell.Diagnostics":{}, "Microsoft.PowerShell.Host":{}, - "Microsoft.PowerShell.LocalAccounts":{}, "Microsoft.PowerShell.Management":{}, "Microsoft.PowerShell.Security":{}, "Microsoft.PowerShell.Utility":{}, "Microsoft.WSMan.Management":{}, + "PackageManagement":{}, + "PowerShellGet":{}, "PSDesiredStateConfiguration":{}, "PSDiagnostics":{}, - "PSReadLine":{}, - "PackageManagement":{}, - "Pester":{}, - "PowerShellGet":{} - + "PSReadLine":{} } } } From cf5f956ed3743869c8d22b2a1e0b7e8af4686b55 Mon Sep 17 00:00:00 2001 From: Jason Berberich Date: Fri, 12 Jan 2018 16:38:13 -0600 Subject: [PATCH 180/188] Update New-PSSessionOption.md (#2052) Missing "are" between "they" and "effective". --- reference/5.1/Microsoft.PowerShell.Core/New-PSSessionOption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/New-PSSessionOption.md b/reference/5.1/Microsoft.PowerShell.Core/New-PSSessionOption.md index cf625d218b25..82c7ae329fd3 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/New-PSSessionOption.md +++ b/reference/5.1/Microsoft.PowerShell.Core/New-PSSessionOption.md @@ -34,7 +34,7 @@ Because all of the properties can be edited, you can use the resulting object as You can also save a session option object in the **$PSSessionOption** preference variable. The values of this variable establish new default values for the session options. -They effective when no session options are set for the session and they take precedence over options set in the session configuration, but you can override them by specifying session options or a session option object in a cmdlet that creates a session. +They are effective when no session options are set for the session and they take precedence over options set in the session configuration, but you can override them by specifying session options or a session option object in a cmdlet that creates a session. For more information about the **$PSSessionOption** preference variable, see [about_Preference_Variables](About/about_Preference_Variables.md). When you use a session option object in a cmdlet that creates a session, the session option values take precedence over default values for sessions set in the $PSSessionOption preference variable and in the session configuration. From 78a132da70d65f03c58c350a447402ee6113d733 Mon Sep 17 00:00:00 2001 From: Shane Hoey Date: Tue, 16 Jan 2018 10:25:17 +1000 Subject: [PATCH 181/188] Update Add-Member.md example layouts (#2055) * Update Add-Member.md fixed layout of examples 1,2 ,3 * fixed format of example 5 --- .../Add-Member.md | 31 ++++++------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Utility/Add-Member.md b/reference/6/Microsoft.PowerShell.Utility/Add-Member.md index d81088e3732a..fec3545b2ac3 100644 --- a/reference/6/Microsoft.PowerShell.Utility/Add-Member.md +++ b/reference/6/Microsoft.PowerShell.Utility/Add-Member.md @@ -70,7 +70,8 @@ For more information, see the *PassThru* parameter description. 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.StatusDone +PS C:\> $A.Status +Done ``` These commands add the Status note property with a value of "Done" to the FileInfo object that represents the Test.txt file. @@ -89,7 +90,8 @@ As the output shows, the value is "Done". ``` PS C:\> $A = dir c:\ps-test\test.txt PS C:\> $A | Add-Member -MemberType AliasProperty -Name FileLength -Value Length -PS C:\> $A.FileLength2394 +PS C:\> $A.FileLength +2394 ``` These commands add the FileLength alias property to the object that represents the Test.txt file. @@ -104,7 +106,8 @@ The third command uses dot notation to get the value of the new FileLength prope ### Example 3: Add a StringUse note property to a string ``` PS C:\> $A = "A string"PS C:\> $A = $A | Add-Member @{StringUse="Display"} -PassThru -PS C:\> $A.StringUseDisplay +PS C:\> $A.StringUse +Display ``` These commands add the **StringUse** note property to a string. @@ -144,28 +147,16 @@ The third command uses dot notation to call the new PadBoth script method on the PS C:\> $Event = Get-EventLog -LogName System -Newest 1 PS C:\> $Event.TimeWritten | Get-MemberTypeName: System.DateTime Name MemberType Definition - - ---- ---------- ---------- - - Add Method System.DateTime Add(System.TimeSpan value) - - AddDays Method System.DateTime AddDays(double value) - - AddHours Method System.DateTime AddHours(double value) - - 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-MemberTypeName: System.String + Name MemberType Definition ---- ---------- ---------- Clone Method System.Object Clone() @@ -492,18 +483,16 @@ When you use the *PassThru* parameter, this cmdlet returns the newly-extended ob 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 instance, 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 instance, 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. +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*, and *SecondValue*. If you include the parameter names, the parameters can appear in any order. - You can use the $this automatic variable in script blocks that define the values of new properties and methods. +You can use the $this automatic variable in script blocks that define the values of new properties and methods. 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. -* - ## RELATED LINKS [Export-Clixml](Export-Clixml.md) From 8f3410a1c5fad51aebe368f01bbfeb6238524bbe Mon Sep 17 00:00:00 2001 From: Kirill Nikolaev Date: Wed, 17 Jan 2018 01:35:16 +0200 Subject: [PATCH 182/188] Removes unnecessary description about the RunAsAdministrator parameter (#2057) There is no need to have documentation for functions which do not exists in the product. There is no need to specify in which version this feature was added. Otherwise we need to add such remarks to many other features as well --- .../About/about_Requires.md | 13 ------------- .../About/about_Requires.md | 3 +-- .../About/about_Requires.md | 3 +-- .../About/about_Requires.md | 3 +-- .../About/about_Requires.md | 3 +-- 5 files changed, 4 insertions(+), 21 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Requires.md index c2e71e2f1753..469c02279ace 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Requires.md @@ -98,19 +98,6 @@ For example, #Requires -ShellId MyLocalShell ``` --RunAsAdministrator - -When this switch parameter is added to your requires statement, it specifies -that the Windows PowerShell session in which you are running the script must -be started with elevated user rights (Run as Administrator). This switch was -introduced in PowerShell 4. - -For example, - -```powershell -#Requires -RunAsAdministrator -``` - ### EXAMPLES The following script has two \#Requires statements. If the requirements diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Requires.md index c2e71e2f1753..0a46dc1445d9 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Requires.md @@ -102,8 +102,7 @@ For example, When this switch parameter is added to your requires statement, it specifies that the Windows PowerShell session in which you are running the script must -be started with elevated user rights (Run as Administrator). This switch was -introduced in PowerShell 4. +be started with elevated user rights (Run as Administrator). For example, diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Requires.md index c2e71e2f1753..0a46dc1445d9 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Requires.md @@ -102,8 +102,7 @@ For example, When this switch parameter is added to your requires statement, it specifies that the Windows PowerShell session in which you are running the script must -be started with elevated user rights (Run as Administrator). This switch was -introduced in PowerShell 4. +be started with elevated user rights (Run as Administrator). For example, diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md index c2e71e2f1753..0a46dc1445d9 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Requires.md @@ -102,8 +102,7 @@ For example, When this switch parameter is added to your requires statement, it specifies that the Windows PowerShell session in which you are running the script must -be started with elevated user rights (Run as Administrator). This switch was -introduced in PowerShell 4. +be started with elevated user rights (Run as Administrator). For example, diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Requires.md b/reference/6/Microsoft.PowerShell.Core/About/about_Requires.md index 93f468542189..c0f7610b59b2 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Requires.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Requires.md @@ -102,8 +102,7 @@ For example, When this switch parameter is added to your requires statement, it specifies that the Windows PowerShell session in which you are running the script must -be started with elevated user rights (Run as Administrator). This switch was -introduced in PowerShell 4. +be started with elevated user rights (Run as Administrator). For example, From a4439529d67e1d20ff726c97ef5790c18499e481 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Wed, 17 Jan 2018 08:36:40 +0900 Subject: [PATCH 183/188] Fix Example 2 in Set-PSReadlineKeyHandler.md (#2058) --- reference/5.0/PSReadline/Set-PSReadlineKeyHandler.md | 10 +++++----- reference/5.1/PSReadline/Set-PSReadlineKeyHandler.md | 10 +++++----- reference/6/PSReadLine/Set-PSReadlineKeyHandler.md | 10 +++++----- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/reference/5.0/PSReadline/Set-PSReadlineKeyHandler.md b/reference/5.0/PSReadline/Set-PSReadlineKeyHandler.md index fc00b5c9d45b..0383b1f133ac 100644 --- a/reference/5.0/PSReadline/Set-PSReadlineKeyHandler.md +++ b/reference/5.0/PSReadline/Set-PSReadlineKeyHandler.md @@ -41,11 +41,11 @@ PS C:\> Set-PSReadlineKeyHandler -Chord UpArrow -Function HistorySearchBackward This command binds the up arrow key to the function HistorySearchBackward, which uses the currently-entered command line as the start of the search string when it is searching through command history. ### Example 2: Bind a key to a script block -``` -PS C:\> Set-PSReadlineKeyHandler -Chord Shift+Ctrl+B -ScriptBlock { - [PSConsoleUtilities.PSConsoleReadLine]::RevertLine() - [PSConsoleUtilities.PSConsoleReadLine]::Insert('build') - [PSConsoleUtilities.PSConsoleReadLine]::AcceptLine() +```powershell +Set-PSReadlineKeyHandler -Chord Ctrl+Shift+B -ScriptBlock { + [Microsoft.PowerShell.PSConsoleReadLine]::RevertLine() + [Microsoft.PowerShell.PSConsoleReadLine]::Insert('build') + [Microsoft.PowerShell.PSConsoleReadLine]::AcceptLine() } ``` diff --git a/reference/5.1/PSReadline/Set-PSReadlineKeyHandler.md b/reference/5.1/PSReadline/Set-PSReadlineKeyHandler.md index 5e4b96db7bfc..9abafec5d5e6 100644 --- a/reference/5.1/PSReadline/Set-PSReadlineKeyHandler.md +++ b/reference/5.1/PSReadline/Set-PSReadlineKeyHandler.md @@ -41,11 +41,11 @@ PS C:\> Set-PSReadlineKeyHandler -Chord UpArrow -Function HistorySearchBackward This command binds the up arrow key to the function HistorySearchBackward, which uses the currently-entered command line as the start of the search string when it is searching through command history. ### Example 2: Bind a key to a script block -``` -PS C:\> Set-PSReadlineKeyHandler -Chord Shift+Ctrl+B -ScriptBlock { - [PSConsoleUtilities.PSConsoleReadLine]::RevertLine() - [PSConsoleUtilities.PSConsoleReadLine]::Insert('build') - [PSConsoleUtilities.PSConsoleReadLine]::AcceptLine() +```powershell +Set-PSReadlineKeyHandler -Chord Ctrl+Shift+B -ScriptBlock { + [Microsoft.PowerShell.PSConsoleReadLine]::RevertLine() + [Microsoft.PowerShell.PSConsoleReadLine]::Insert('build') + [Microsoft.PowerShell.PSConsoleReadLine]::AcceptLine() } ``` diff --git a/reference/6/PSReadLine/Set-PSReadlineKeyHandler.md b/reference/6/PSReadLine/Set-PSReadlineKeyHandler.md index 5e4b96db7bfc..9abafec5d5e6 100644 --- a/reference/6/PSReadLine/Set-PSReadlineKeyHandler.md +++ b/reference/6/PSReadLine/Set-PSReadlineKeyHandler.md @@ -41,11 +41,11 @@ PS C:\> Set-PSReadlineKeyHandler -Chord UpArrow -Function HistorySearchBackward This command binds the up arrow key to the function HistorySearchBackward, which uses the currently-entered command line as the start of the search string when it is searching through command history. ### Example 2: Bind a key to a script block -``` -PS C:\> Set-PSReadlineKeyHandler -Chord Shift+Ctrl+B -ScriptBlock { - [PSConsoleUtilities.PSConsoleReadLine]::RevertLine() - [PSConsoleUtilities.PSConsoleReadLine]::Insert('build') - [PSConsoleUtilities.PSConsoleReadLine]::AcceptLine() +```powershell +Set-PSReadlineKeyHandler -Chord Ctrl+Shift+B -ScriptBlock { + [Microsoft.PowerShell.PSConsoleReadLine]::RevertLine() + [Microsoft.PowerShell.PSConsoleReadLine]::Insert('build') + [Microsoft.PowerShell.PSConsoleReadLine]::AcceptLine() } ``` From 8fd856c9350c8e41b8d1b33f3b45bcafc0dfb2b3 Mon Sep 17 00:00:00 2001 From: Matt Gucci Date: Wed, 17 Jan 2018 08:37:41 +0900 Subject: [PATCH 184/188] Fix Example 1 in Remove-PSReadlineKeyHandler.md (#2059) --- reference/5.0/PSReadline/Remove-PSReadlineKeyHandler.md | 6 +++--- reference/5.1/PSReadline/Remove-PSReadlineKeyHandler.md | 6 +++--- reference/6/PSReadLine/Remove-PSReadlineKeyHandler.md | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/reference/5.0/PSReadline/Remove-PSReadlineKeyHandler.md b/reference/5.0/PSReadline/Remove-PSReadlineKeyHandler.md index bd237daac096..3edb58c919f1 100644 --- a/reference/5.0/PSReadline/Remove-PSReadlineKeyHandler.md +++ b/reference/5.0/PSReadline/Remove-PSReadlineKeyHandler.md @@ -26,12 +26,12 @@ Create a key binding by running the Set-PSReadlineKeyHandler cmdlet. ## EXAMPLES ### Example 1: Remove a binding -``` -PS C:\> Remove-PSReadlineKeyHandler -Chord "Shift+Ctrl+B" +```powershell +Remove-PSReadlineKeyHandler -Chord Ctrl+Shift+B ``` This command removes the binding from the key combination, or chord, Ctrl+Shift+B. -The Ctrl+Shift+B chord is created in the Set-PSReadlineKeyHandler topic. +The Ctrl+Shift+B chord is created in the `Set-PSReadlineKeyHandler` topic. ## PARAMETERS diff --git a/reference/5.1/PSReadline/Remove-PSReadlineKeyHandler.md b/reference/5.1/PSReadline/Remove-PSReadlineKeyHandler.md index 8a94a74668c4..50d31ee3863f 100644 --- a/reference/5.1/PSReadline/Remove-PSReadlineKeyHandler.md +++ b/reference/5.1/PSReadline/Remove-PSReadlineKeyHandler.md @@ -26,12 +26,12 @@ Create a key binding by running the Set-PSReadlineKeyHandler cmdlet. ## EXAMPLES ### Example 1: Remove a binding -``` -PS C:\> Remove-PSReadlineKeyHandler -Chord "Shift+Ctrl+B" +```powershell +Remove-PSReadlineKeyHandler -Chord Ctrl+Shift+B ``` This command removes the binding from the key combination, or chord, Ctrl+Shift+B. -The Ctrl+Shift+B chord is created in the Set-PSReadlineKeyHandler topic. +The Ctrl+Shift+B chord is created in the `Set-PSReadlineKeyHandler` topic. ## PARAMETERS diff --git a/reference/6/PSReadLine/Remove-PSReadlineKeyHandler.md b/reference/6/PSReadLine/Remove-PSReadlineKeyHandler.md index 8a94a74668c4..50d31ee3863f 100644 --- a/reference/6/PSReadLine/Remove-PSReadlineKeyHandler.md +++ b/reference/6/PSReadLine/Remove-PSReadlineKeyHandler.md @@ -26,12 +26,12 @@ Create a key binding by running the Set-PSReadlineKeyHandler cmdlet. ## EXAMPLES ### Example 1: Remove a binding -``` -PS C:\> Remove-PSReadlineKeyHandler -Chord "Shift+Ctrl+B" +```powershell +Remove-PSReadlineKeyHandler -Chord Ctrl+Shift+B ``` This command removes the binding from the key combination, or chord, Ctrl+Shift+B. -The Ctrl+Shift+B chord is created in the Set-PSReadlineKeyHandler topic. +The Ctrl+Shift+B chord is created in the `Set-PSReadlineKeyHandler` topic. ## PARAMETERS From 2de1cc3cf381f91cdb670a063e864e768a51231d Mon Sep 17 00:00:00 2001 From: George Chakhidze <0xfeeddeadbeef@gmail.com> Date: Wed, 17 Jan 2018 03:40:08 +0400 Subject: [PATCH 185/188] Fix minor Markdown syntax error (#2060) "Backwards compatibility with Windows PowerShell" anchor reference had incorrect Markdown syntax. --- .../whats-new/What-s-New-in-PowerShell-Core-60.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md index 8b2a5edecb44..4b748e849f3c 100644 --- a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-Core-60.md @@ -14,7 +14,7 @@ This means that Windows PowerShell exposes the API set offered by .NET Framework The APIs shared between .NET Core and .NET Framework are defined as part of [.NET Standard][]. For more information on how this affects module/script compatibility between PowerShell Core and Windows PowerShell, -see [Backwards compatibility with Windows PowerShell][#backwards-compatibility-with-windows-powershell] +see [Backwards compatibility with Windows PowerShell](#backwards-compatibility-with-windows-powershell). ## Support for macOS and Linux @@ -400,4 +400,4 @@ You can find out more about how we use this data in this [blog post][telemetry-b [docker-hub]: https://hub.docker.com/r/microsoft/powershell/ [docker]: https://github.com/PowerShell/PowerShell/tree/master/docker [windowspsmodulepath]: https://www.powershellgallery.com/packages/WindowsPSModulePath/ -[semi-annual]: https://docs.microsoft.com/windows-server/get-started/semi-annual-channel-overview \ No newline at end of file +[semi-annual]: https://docs.microsoft.com/windows-server/get-started/semi-annual-channel-overview From 8d53e257f87fd6a893cf949327825f17202a8402 Mon Sep 17 00:00:00 2001 From: Egor Yudkin Date: Tue, 16 Jan 2018 18:41:07 -0500 Subject: [PATCH 186/188] Update secureMOF.md (#2061) Update "On the Target Node: create and export the certificate" section --- dsc/secureMOF.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/dsc/secureMOF.md b/dsc/secureMOF.md index 1fc354b06969..aa1bef8921e5 100644 --- a/dsc/secureMOF.md +++ b/dsc/secureMOF.md @@ -99,7 +99,7 @@ The following example: 3. imports the public key certificate into the **my** certificate store on the **Authoring node**. #### On the Target Node: create and export the certificate ->Authoring Node: Windows Server 2016 and Windows 10 +>Target Node: Windows Server 2016 and Windows 10 ```powershell # note: These steps need to be performed in an Administrator PowerShell session @@ -109,7 +109,7 @@ $cert | Export-Certificate -FilePath "$env:temp\DscPublicKey.cer" -Force ``` Once exported, the ```DscPublicKey.cer``` would need to be copied to the **Authoring Node**. ->Authoring Node: Windows Server 2012 R2/Windows 8.1 and earlier +>Target Node: Windows Server 2012 R2/Windows 8.1 and earlier Because the New-SelfSignedCertificate cmdlet on Windows Operating Systems prior to Windows 10 and Windows Server 2016 do not support the **Type** parameter, an alternate method of creating this certificate is required on these operating systems. In this case you can use ```makecert.exe``` or ```certutil.exe``` to create the certificate. @@ -127,7 +127,6 @@ New-SelfsignedCertificateEx ` -FriendlyName 'DSC Credential Encryption certificate' ` -Exportable ` -StoreLocation 'LocalMachine' ` - -StoreName 'My' ` -KeyLength 2048 ` -ProviderName 'Microsoft Enhanced Cryptographic Provider v1.0' ` -AlgorithmName 'RSA' ` From a75c4053ccc4003cf0249c7d58cb36925da51307 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 16 Jan 2018 15:55:04 -0800 Subject: [PATCH 187/188] remove eric and jp from metadata --- dsc/DSCAutomationHostEnabled.md | 1 - dsc/PackageManagementDscResource.md | 1 - dsc/PackageManagementSourceDscResource.md | 1 - dsc/archiveResource.md | 23 +++++++++---------- dsc/authoringResource.md | 11 ++++----- dsc/authoringResourceClass.md | 1 - dsc/authoringResourceComposite.md | 1 - dsc/authoringResourceMOF.md | 1 - dsc/authoringResourceMofCS.md | 1 - dsc/authoringResourceMofDesigner.md | 1 - dsc/azureDsc.md | 1 - dsc/bootstrapDsc.md | 1 - dsc/builtInResource.md | 1 - dsc/compositeConfigs.md | 1 - dsc/configData.md | 1 - dsc/configDataCredentials.md | 1 - dsc/configHelp.md | 1 - dsc/configurations.md | 1 - dsc/crossNodeDependencies.md | 1 - dsc/debugResource.md | 1 - dsc/decisionMaker.md | 1 - dsc/directCallResource.md | 1 - dsc/dscCiCd.md | 1 - dsc/dscExamples.md | 1 - dsc/environmentResource.md | 1 - dsc/fileResource.md | 1 - dsc/gettingStarted.md | 1 - dsc/groupSetResource.md | 1 - dsc/lnxArchiveResource.md | 1 - dsc/lnxBuiltInResources.md | 1 - dsc/lnxEnvironmentResource.md | 1 - dsc/lnxFileLineResource.md | 1 - dsc/lnxFileResource.md | 1 - dsc/lnxGettingStarted.md | 1 - dsc/lnxGroupResource.md | 1 - dsc/lnxPackageResource.md | 1 - dsc/lnxScriptResource.md | 1 - dsc/lnxServiceResource.md | 1 - dsc/lnxSshAuthorizedKeysResource.md | 1 - dsc/lnxUserResource.md | 1 - dsc/logResource.md | 1 - ...configurationmanager-applyconfiguration.md | 1 - ...rationmanager-disabledebugconfiguration.md | 1 - ...urationmanager-enabledebugconfiguration.md | 1 - ...alconfigurationmanager-getconfiguration.md | 1 - ...ionmanager-getconfigurationresultoutput.md | 1 - ...igurationmanager-getconfigurationstatus.md | 1 - ...nfigurationmanager-getmetaconfiguration.md | 1 - ...ager-performrequiredconfigurationchecks.md | 1 - ...onfigurationmanager-removeconfiguration.md | 1 - ...sclocalconfigurationmanager-resourceget.md | 1 - ...sclocalconfigurationmanager-resourceset.md | 1 - ...clocalconfigurationmanager-resourcetest.md | 1 - ...t-dsclocalconfigurationmanager-rollback.md | 1 - ...lconfigurationmanager-sendconfiguration.md | 1 - ...igurationmanager-sendconfigurationapply.md | 1 - ...tionmanager-sendconfigurationapplyasync.md | 1 - ...ationmanager-sendmetaconfigurationapply.md | 1 - ...lconfigurationmanager-stopconfiguration.md | 1 - ...lconfigurationmanager-testconfiguration.md | 1 - dsc/msft-dsclocalconfigurationmanager.md | 1 - dsc/nanoDsc.md | 1 - dsc/overview.md | 1 - dsc/packageResource.md | 1 - dsc/partialConfigs.md | 1 - dsc/processSetResource.md | 1 - dsc/pullClient.md | 1 - dsc/pullClientConfigID.md | 1 - dsc/pullClientConfigID4.md | 1 - dsc/pullClientConfigNames.md | 1 - dsc/pullServer.md | 1 - dsc/pullServerSMB.md | 1 - dsc/queryServerNodes.md | 1 - dsc/quickStart.md | 1 - dsc/registryResource.md | 1 - dsc/reportServer.md | 1 - dsc/resourceAuthoringChecklist.md | 1 - dsc/resources.md | 1 - dsc/runAsUser.md | 1 - dsc/scriptResource.md | 1 - dsc/secureMOF.md | 1 - dsc/secureServer.md | 1 - dsc/separatingEnvData.md | 1 - dsc/serviceResource.md | 1 - dsc/serviceSetResource.md | 1 - dsc/singleInstance.md | 1 - dsc/sxsResource.md | 1 - dsc/troubleshooting.md | 1 - dsc/userResource.md | 1 - dsc/waitForAllResource.md | 1 - dsc/waitForAnyResource.md | 1 - dsc/waitForSomeResource.md | 1 - dsc/whitepapers.md | 1 - dsc/windowsFeatureSetResource.md | 1 - dsc/windowsOptionalFeatureResource.md | 1 - dsc/windowsOptionalFeatureSetResource.md | 1 - dsc/windowsPackageCabResource.md | 1 - dsc/windowsProcessResource.md | 1 - dsc/windowsfeatureResource.md | 1 - .../cmdlets/add-pswaauthorizationrule.md | 2 -- .../cmdlets/get-pswaauthorizationrule.md | 2 -- .../cmdlets/install-pswawebapplication.md | 2 -- .../cmdlets/remove-pswaauthorizationrule.md | 2 -- .../cmdlets/test-pswaauthorizationrule.md | 2 -- .../cmdlets/uninstall-pswawebapplication.md | 2 -- .../web-access/cmdlets/web-access-cmdlets.md | 2 -- 106 files changed, 16 insertions(+), 129 deletions(-) diff --git a/dsc/DSCAutomationHostEnabled.md b/dsc/DSCAutomationHostEnabled.md index 4a573f9de473..f433c4edf8fd 100644 --- a/dsc/DSCAutomationHostEnabled.md +++ b/dsc/DSCAutomationHostEnabled.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSCAutomationHostEnabled registry key diff --git a/dsc/PackageManagementDscResource.md b/dsc/PackageManagementDscResource.md index 9117da548e95..3e5bf9eebb4e 100644 --- a/dsc/PackageManagementDscResource.md +++ b/dsc/PackageManagementDscResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC PackageManagement Resource diff --git a/dsc/PackageManagementSourceDscResource.md b/dsc/PackageManagementSourceDscResource.md index cadb83c4408f..8b87a836e99a 100644 --- a/dsc/PackageManagementSourceDscResource.md +++ b/dsc/PackageManagementSourceDscResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC PackageManagementSource Resource diff --git a/dsc/archiveResource.md b/dsc/archiveResource.md index f3b6cb13e50b..9362dbdd4ace 100644 --- a/dsc/archiveResource.md +++ b/dsc/archiveResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC Archive Resource @@ -12,7 +11,7 @@ title: DSC Archive Resource The Archive resource in Windows PowerShell Desired State Configuration (DSC) provides a mechanism to unpack archive (.zip) files at a specific path. -## Syntax +## Syntax ```MOF Archive [string] #ResourceName { @@ -28,15 +27,15 @@ Archive [string] #ResourceName ## Properties -| Property | Description | -|---|---| -| Destination| Specifies the location where you want to ensure the archive contents are extracted.| -| Path| Specifies the source path of the archive file.| -| __Checksum__| Defines the type to use when determining whether two files are the same. If __Checksum__ is not specified, only the file or directory name is used for comparison. Valid values include: SHA-1, SHA-256, SHA-512, createdDate, modifiedDate, none (default). If you specify __Checksum__ without __Validate__, the configuration will fail.| -| Ensure| Determines whether to check if the content of the archive exists at the __Destination__. Set this property to __Present__ to ensure the contents exist. Set it to __Absent__ to ensure they do not exist. The default value is __Present__.| -| DependsOn | Indicates that the configuration of another resource must run before this resource is configured. For example, if the ID of the resource configuration script block that you want to run first is ResourceName and its type is __ResourceType__, the syntax for using this property is `DependsOn = "[ResourceType]ResourceName"`.| -| Validate| Uses the Checksum property to determine if the archive matches the signature. If you specify Checksum without Validate, the configuration will fail. If you specify Validate without Checksum, a SHA-256 checksum is used by default.| -| Force| Certain file operations (such as overwriting a file or deleting a directory that is not empty) will result in an error. Using the Force property overrides such errors. The default value is False.| +| Property | Description | +|---|---| +| Destination| Specifies the location where you want to ensure the archive contents are extracted.| +| Path| Specifies the source path of the archive file.| +| __Checksum__| Defines the type to use when determining whether two files are the same. If __Checksum__ is not specified, only the file or directory name is used for comparison. Valid values include: SHA-1, SHA-256, SHA-512, createdDate, modifiedDate, none (default). If you specify __Checksum__ without __Validate__, the configuration will fail.| +| Ensure| Determines whether to check if the content of the archive exists at the __Destination__. Set this property to __Present__ to ensure the contents exist. Set it to __Absent__ to ensure they do not exist. The default value is __Present__.| +| DependsOn | Indicates that the configuration of another resource must run before this resource is configured. For example, if the ID of the resource configuration script block that you want to run first is ResourceName and its type is __ResourceType__, the syntax for using this property is `DependsOn = "[ResourceType]ResourceName"`.| +| Validate| Uses the Checksum property to determine if the archive matches the signature. If you specify Checksum without Validate, the configuration will fail. If you specify Validate without Checksum, a SHA-256 checksum is used by default.| +| Force| Certain file operations (such as overwriting a file or deleting a directory that is not empty) will result in an error. Using the Force property overrides such errors. The default value is False.| ## Example @@ -47,6 +46,6 @@ Archive ArchiveExample { Ensure = "Present" # You can also set Ensure to "Absent" Path = "C:\Users\Public\Documents\Test.zip" Destination = "C:\Users\Public\Documents\ExtractionPath" -} +} ``` diff --git a/dsc/authoringResource.md b/dsc/authoringResource.md index 01ea11d28003..fb3b6d256d33 100644 --- a/dsc/authoringResource.md +++ b/dsc/authoringResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Build Custom Windows PowerShell Desired State Configuration Resources @@ -16,9 +15,9 @@ Windows PowerShell Desired State Configuration (DSC) has built-in resources that A DSC resource is a Windows PowerShell module. The module contains both the schema (the definition of the configurable properties) and the implementation (the code that does the actual work specified by a configuration) for the resource. A DSC resource schema can be defined in a MOF file, and the implementation is performed by a script module. Beginning with the support of PowerShell classes in version 5, the schema and implementation can both be defined in a class. The following topics describe in more detail how to create DSC resources. -* [Writing a custom DSC resource with MOF](authoringResourceMOF.md) -* [Implementing a DSC resource in C#](authoringResourceMofCS.md) -* [Writing a custom DSC resource with PowerShell classes](authoringResourceClass.md) -* [Composite resources: Using a DSC configuration as a resource](authoringResourceComposite.md) -* [Using the Resource Designer tool](authoringResourceMofDesigner.md) +* [Writing a custom DSC resource with MOF](authoringResourceMOF.md) +* [Implementing a DSC resource in C#](authoringResourceMofCS.md) +* [Writing a custom DSC resource with PowerShell classes](authoringResourceClass.md) +* [Composite resources: Using a DSC configuration as a resource](authoringResourceComposite.md) +* [Using the Resource Designer tool](authoringResourceMofDesigner.md) diff --git a/dsc/authoringResourceClass.md b/dsc/authoringResourceClass.md index b2b1eeeb9d85..9b0fe40312a9 100644 --- a/dsc/authoringResourceClass.md +++ b/dsc/authoringResourceClass.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Writing a custom DSC resource with PowerShell classes diff --git a/dsc/authoringResourceComposite.md b/dsc/authoringResourceComposite.md index d80c6983b814..ae15b6ca8e62 100644 --- a/dsc/authoringResourceComposite.md +++ b/dsc/authoringResourceComposite.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Composite resources--Using a DSC configuration as a resource diff --git a/dsc/authoringResourceMOF.md b/dsc/authoringResourceMOF.md index 22e0d855381d..083e56bdfd58 100644 --- a/dsc/authoringResourceMOF.md +++ b/dsc/authoringResourceMOF.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Writing a custom DSC resource with MOF diff --git a/dsc/authoringResourceMofCS.md b/dsc/authoringResourceMofCS.md index 29e07ced8e7f..71a937078713 100644 --- a/dsc/authoringResourceMofCS.md +++ b/dsc/authoringResourceMofCS.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Authoring a DSC resource in C# diff --git a/dsc/authoringResourceMofDesigner.md b/dsc/authoringResourceMofDesigner.md index 9bf59707ba0d..16d205f1f9f9 100644 --- a/dsc/authoringResourceMofDesigner.md +++ b/dsc/authoringResourceMofDesigner.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Using the Resource Designer tool diff --git a/dsc/azureDsc.md b/dsc/azureDsc.md index 9d4fa6dd3ebe..28e88a4e9ee7 100644 --- a/dsc/azureDsc.md +++ b/dsc/azureDsc.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Using DSC on Microsoft Azure diff --git a/dsc/bootstrapDsc.md b/dsc/bootstrapDsc.md index e4ec966f0256..d59e1b218145 100644 --- a/dsc/bootstrapDsc.md +++ b/dsc/bootstrapDsc.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Configure a virtual machines at initial boot-up by using DSC diff --git a/dsc/builtInResource.md b/dsc/builtInResource.md index 735c92ac786d..0450ff90ba49 100644 --- a/dsc/builtInResource.md +++ b/dsc/builtInResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Built-In Windows PowerShell Desired State Configuration Resources diff --git a/dsc/compositeConfigs.md b/dsc/compositeConfigs.md index f29aa951ba0c..ada75d00a383 100644 --- a/dsc/compositeConfigs.md +++ b/dsc/compositeConfigs.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Nesting configurations diff --git a/dsc/configData.md b/dsc/configData.md index 62bcd1520241..514c8d06c62f 100644 --- a/dsc/configData.md +++ b/dsc/configData.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Using configuration data diff --git a/dsc/configDataCredentials.md b/dsc/configDataCredentials.md index 4a998aa4eca8..2ab781b0faae 100644 --- a/dsc/configDataCredentials.md +++ b/dsc/configDataCredentials.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Credentials Options in Configuration Data diff --git a/dsc/configHelp.md b/dsc/configHelp.md index 2aa7790b5d3f..c4b84abf93f1 100644 --- a/dsc/configHelp.md +++ b/dsc/configHelp.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Writing help for DSC configurations diff --git a/dsc/configurations.md b/dsc/configurations.md index d30cde9ba65b..8e374a7ba176 100644 --- a/dsc/configurations.md +++ b/dsc/configurations.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC Configurations diff --git a/dsc/crossNodeDependencies.md b/dsc/crossNodeDependencies.md index 37e7a1bf7d2d..30c5253800a6 100644 --- a/dsc/crossNodeDependencies.md +++ b/dsc/crossNodeDependencies.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Specifying cross-node dependencies diff --git a/dsc/debugResource.md b/dsc/debugResource.md index 5d3d467bc782..56b723e4508d 100644 --- a/dsc/debugResource.md +++ b/dsc/debugResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Debugging DSC resources diff --git a/dsc/decisionMaker.md b/dsc/decisionMaker.md index 4698a44a2d1d..0ccd3492ed9f 100644 --- a/dsc/decisionMaker.md +++ b/dsc/decisionMaker.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Desired State Configuration Overview for Decision Makers diff --git a/dsc/directCallResource.md b/dsc/directCallResource.md index 5609691d6407..755d03c2f7b6 100644 --- a/dsc/directCallResource.md +++ b/dsc/directCallResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Calling DSC resource methods directly diff --git a/dsc/dscCiCd.md b/dsc/dscCiCd.md index 37e2fbe01912..b6fa3b662e17 100644 --- a/dsc/dscCiCd.md +++ b/dsc/dscCiCd.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Building a Continuous Integration and Continuous Deployment pipeline with DSC diff --git a/dsc/dscExamples.md b/dsc/dscExamples.md index 0cce01d20e70..abf3d75fc0d2 100644 --- a/dsc/dscExamples.md +++ b/dsc/dscExamples.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC Examples diff --git a/dsc/environmentResource.md b/dsc/environmentResource.md index cdd5db82550b..bed250e387ff 100644 --- a/dsc/environmentResource.md +++ b/dsc/environmentResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC Environment Resource diff --git a/dsc/fileResource.md b/dsc/fileResource.md index 32d8087cf889..ad322b80d5eb 100644 --- a/dsc/fileResource.md +++ b/dsc/fileResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC File Resource diff --git a/dsc/gettingStarted.md b/dsc/gettingStarted.md index 5628584a0d58..b9f2608ecb1b 100644 --- a/dsc/gettingStarted.md +++ b/dsc/gettingStarted.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Getting Started with PowerShell Desired State Configuration diff --git a/dsc/groupSetResource.md b/dsc/groupSetResource.md index 938f782ba871..a4a73cc370f7 100644 --- a/dsc/groupSetResource.md +++ b/dsc/groupSetResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup description: Provides a mechanism to manage local groups on the target node. diff --git a/dsc/lnxArchiveResource.md b/dsc/lnxArchiveResource.md index 34d293deb9af..76e1123c1bea 100644 --- a/dsc/lnxArchiveResource.md +++ b/dsc/lnxArchiveResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC for Linux nxArchive Resource diff --git a/dsc/lnxBuiltInResources.md b/dsc/lnxBuiltInResources.md index 346a682f54e7..69c0e03b0d1f 100644 --- a/dsc/lnxBuiltInResources.md +++ b/dsc/lnxBuiltInResources.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Built-In Desired State Configuration Resources for Linux diff --git a/dsc/lnxEnvironmentResource.md b/dsc/lnxEnvironmentResource.md index 502d7e85d97e..6d2200230525 100644 --- a/dsc/lnxEnvironmentResource.md +++ b/dsc/lnxEnvironmentResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC for Linux nxEnvironment Resource diff --git a/dsc/lnxFileLineResource.md b/dsc/lnxFileLineResource.md index 89ba684c6ab1..e918d19399c3 100644 --- a/dsc/lnxFileLineResource.md +++ b/dsc/lnxFileLineResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC for Linux nxFileLine Resource diff --git a/dsc/lnxFileResource.md b/dsc/lnxFileResource.md index 8efc800fb76e..3ef39b207ff6 100644 --- a/dsc/lnxFileResource.md +++ b/dsc/lnxFileResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC for Linux nxFile Resource diff --git a/dsc/lnxGettingStarted.md b/dsc/lnxGettingStarted.md index f95069df5f21..83340b3c701b 100644 --- a/dsc/lnxGettingStarted.md +++ b/dsc/lnxGettingStarted.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Get started with Desired State Configuration (DSC) for Linux diff --git a/dsc/lnxGroupResource.md b/dsc/lnxGroupResource.md index b4ce43e5d6c7..ff1fc9fb5536 100644 --- a/dsc/lnxGroupResource.md +++ b/dsc/lnxGroupResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC for Linux nxGroup Resource diff --git a/dsc/lnxPackageResource.md b/dsc/lnxPackageResource.md index 58c7928bb681..3caf6a2f5af7 100644 --- a/dsc/lnxPackageResource.md +++ b/dsc/lnxPackageResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC for Linux nxPackage Resource diff --git a/dsc/lnxScriptResource.md b/dsc/lnxScriptResource.md index c37bb344d0ac..5242a682b36c 100644 --- a/dsc/lnxScriptResource.md +++ b/dsc/lnxScriptResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC for Linux nxScript Resource diff --git a/dsc/lnxServiceResource.md b/dsc/lnxServiceResource.md index 80ad7cd6d660..9aa349140482 100644 --- a/dsc/lnxServiceResource.md +++ b/dsc/lnxServiceResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC for Linux nxService Resource diff --git a/dsc/lnxSshAuthorizedKeysResource.md b/dsc/lnxSshAuthorizedKeysResource.md index e1555dbe7357..687a17e039f1 100644 --- a/dsc/lnxSshAuthorizedKeysResource.md +++ b/dsc/lnxSshAuthorizedKeysResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC for Linux nxSshAuthorizedKeys Resource diff --git a/dsc/lnxUserResource.md b/dsc/lnxUserResource.md index 12cb1b5502eb..3506ec8c5f9e 100644 --- a/dsc/lnxUserResource.md +++ b/dsc/lnxUserResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC for Linux nxUser Resource diff --git a/dsc/logResource.md b/dsc/logResource.md index 6d620d08621b..3005c026e1ce 100644 --- a/dsc/logResource.md +++ b/dsc/logResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC Log Resource diff --git a/dsc/msft-dsclocalconfigurationmanager-applyconfiguration.md b/dsc/msft-dsclocalconfigurationmanager-applyconfiguration.md index 93483f161a97..29b6184c204d 100644 --- a/dsc/msft-dsclocalconfigurationmanager-applyconfiguration.md +++ b/dsc/msft-dsclocalconfigurationmanager-applyconfiguration.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: ApplyConfiguration method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-disabledebugconfiguration.md b/dsc/msft-dsclocalconfigurationmanager-disabledebugconfiguration.md index 171847d508bc..69a69fc2e037 100644 --- a/dsc/msft-dsclocalconfigurationmanager-disabledebugconfiguration.md +++ b/dsc/msft-dsclocalconfigurationmanager-disabledebugconfiguration.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DisableDebugConfiguration method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-enabledebugconfiguration.md b/dsc/msft-dsclocalconfigurationmanager-enabledebugconfiguration.md index 43fbc2fbccc8..a3fdefad9f01 100644 --- a/dsc/msft-dsclocalconfigurationmanager-enabledebugconfiguration.md +++ b/dsc/msft-dsclocalconfigurationmanager-enabledebugconfiguration.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: EnableDebugConfiguration method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-getconfiguration.md b/dsc/msft-dsclocalconfigurationmanager-getconfiguration.md index 6f78a4ea05ef..22d0b4484eed 100644 --- a/dsc/msft-dsclocalconfigurationmanager-getconfiguration.md +++ b/dsc/msft-dsclocalconfigurationmanager-getconfiguration.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: GetConfiguration method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-getconfigurationresultoutput.md b/dsc/msft-dsclocalconfigurationmanager-getconfigurationresultoutput.md index 25d759826769..a33ad24c8294 100644 --- a/dsc/msft-dsclocalconfigurationmanager-getconfigurationresultoutput.md +++ b/dsc/msft-dsclocalconfigurationmanager-getconfigurationresultoutput.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: GetConfigurationResultOutput method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-getconfigurationstatus.md b/dsc/msft-dsclocalconfigurationmanager-getconfigurationstatus.md index cddda3642bf9..5b2ff8bfe2e9 100644 --- a/dsc/msft-dsclocalconfigurationmanager-getconfigurationstatus.md +++ b/dsc/msft-dsclocalconfigurationmanager-getconfigurationstatus.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: GetConfigurationStatus method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-getmetaconfiguration.md b/dsc/msft-dsclocalconfigurationmanager-getmetaconfiguration.md index 88e502e3ac3f..129212e51841 100644 --- a/dsc/msft-dsclocalconfigurationmanager-getmetaconfiguration.md +++ b/dsc/msft-dsclocalconfigurationmanager-getmetaconfiguration.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: GetMetaConfiguration method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-performrequiredconfigurationchecks.md b/dsc/msft-dsclocalconfigurationmanager-performrequiredconfigurationchecks.md index b04d4ec0170d..46ebed5960e4 100644 --- a/dsc/msft-dsclocalconfigurationmanager-performrequiredconfigurationchecks.md +++ b/dsc/msft-dsclocalconfigurationmanager-performrequiredconfigurationchecks.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: PerformRequiredConfigurationChecks method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-removeconfiguration.md b/dsc/msft-dsclocalconfigurationmanager-removeconfiguration.md index 9d25e2d934b3..16df11d6bd12 100644 --- a/dsc/msft-dsclocalconfigurationmanager-removeconfiguration.md +++ b/dsc/msft-dsclocalconfigurationmanager-removeconfiguration.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: RemoveConfiguration method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-resourceget.md b/dsc/msft-dsclocalconfigurationmanager-resourceget.md index b9c3153b8f08..3476d34f39dc 100644 --- a/dsc/msft-dsclocalconfigurationmanager-resourceget.md +++ b/dsc/msft-dsclocalconfigurationmanager-resourceget.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: ResourceGet method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-resourceset.md b/dsc/msft-dsclocalconfigurationmanager-resourceset.md index 746fe8bb4e0a..48daddbc27ff 100644 --- a/dsc/msft-dsclocalconfigurationmanager-resourceset.md +++ b/dsc/msft-dsclocalconfigurationmanager-resourceset.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: ResourceSet method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-resourcetest.md b/dsc/msft-dsclocalconfigurationmanager-resourcetest.md index fc842ffdf86a..fb0375f263fd 100644 --- a/dsc/msft-dsclocalconfigurationmanager-resourcetest.md +++ b/dsc/msft-dsclocalconfigurationmanager-resourcetest.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: ResourceTest method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-rollback.md b/dsc/msft-dsclocalconfigurationmanager-rollback.md index 6f0c058dbb1f..6392f5ab3e99 100644 --- a/dsc/msft-dsclocalconfigurationmanager-rollback.md +++ b/dsc/msft-dsclocalconfigurationmanager-rollback.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: RollBack method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-sendconfiguration.md b/dsc/msft-dsclocalconfigurationmanager-sendconfiguration.md index 5a6bd3462d4c..41ebd15265b5 100644 --- a/dsc/msft-dsclocalconfigurationmanager-sendconfiguration.md +++ b/dsc/msft-dsclocalconfigurationmanager-sendconfiguration.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: SendConfiguration method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-sendconfigurationapply.md b/dsc/msft-dsclocalconfigurationmanager-sendconfigurationapply.md index 1d062f91bbf2..1856e4ab7a32 100644 --- a/dsc/msft-dsclocalconfigurationmanager-sendconfigurationapply.md +++ b/dsc/msft-dsclocalconfigurationmanager-sendconfigurationapply.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: SendConfigurationApply method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-sendconfigurationapplyasync.md b/dsc/msft-dsclocalconfigurationmanager-sendconfigurationapplyasync.md index cd39f3189fd5..0486adafae62 100644 --- a/dsc/msft-dsclocalconfigurationmanager-sendconfigurationapplyasync.md +++ b/dsc/msft-dsclocalconfigurationmanager-sendconfigurationapplyasync.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: SendConfigurationApplyAsync method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-sendmetaconfigurationapply.md b/dsc/msft-dsclocalconfigurationmanager-sendmetaconfigurationapply.md index e74c01f11840..f9f52773014b 100644 --- a/dsc/msft-dsclocalconfigurationmanager-sendmetaconfigurationapply.md +++ b/dsc/msft-dsclocalconfigurationmanager-sendmetaconfigurationapply.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: SendMetaConfigurationApply method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-stopconfiguration.md b/dsc/msft-dsclocalconfigurationmanager-stopconfiguration.md index 2920060425d7..29ec1b689e76 100644 --- a/dsc/msft-dsclocalconfigurationmanager-stopconfiguration.md +++ b/dsc/msft-dsclocalconfigurationmanager-stopconfiguration.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: StopConfiguration method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager-testconfiguration.md b/dsc/msft-dsclocalconfigurationmanager-testconfiguration.md index 551d26e2c7e3..b9c2557aed72 100644 --- a/dsc/msft-dsclocalconfigurationmanager-testconfiguration.md +++ b/dsc/msft-dsclocalconfigurationmanager-testconfiguration.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: TestConfiguration method of the MSFT_DSCLocalConfigurationManager class diff --git a/dsc/msft-dsclocalconfigurationmanager.md b/dsc/msft-dsclocalconfigurationmanager.md index c5a764680e84..31272389e85e 100644 --- a/dsc/msft-dsclocalconfigurationmanager.md +++ b/dsc/msft-dsclocalconfigurationmanager.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: MSFT_DSCLocalConfigurationManager class diff --git a/dsc/nanoDsc.md b/dsc/nanoDsc.md index b66ea720d6b1..07ff9160b5fd 100644 --- a/dsc/nanoDsc.md +++ b/dsc/nanoDsc.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Using DSC on Nano Server diff --git a/dsc/overview.md b/dsc/overview.md index f60e77da4c37..edfaafe7638f 100644 --- a/dsc/overview.md +++ b/dsc/overview.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Windows PowerShell Desired State Configuration Overview diff --git a/dsc/packageResource.md b/dsc/packageResource.md index fceef095449c..7a3b27f5af90 100644 --- a/dsc/packageResource.md +++ b/dsc/packageResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC Package Resource diff --git a/dsc/partialConfigs.md b/dsc/partialConfigs.md index 1ed916c1d422..e75790fb5821 100644 --- a/dsc/partialConfigs.md +++ b/dsc/partialConfigs.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: PowerShell Desired State Configuration partial configurations diff --git a/dsc/processSetResource.md b/dsc/processSetResource.md index 3c75a3444d16..bc08e284ae08 100644 --- a/dsc/processSetResource.md +++ b/dsc/processSetResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC ProcessSet Resource diff --git a/dsc/pullClient.md b/dsc/pullClient.md index d795ea432738..611d95840b39 100644 --- a/dsc/pullClient.md +++ b/dsc/pullClient.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Setting up a DSC pull client diff --git a/dsc/pullClientConfigID.md b/dsc/pullClientConfigID.md index d66b6d440e1f..8734c3902cd7 100644 --- a/dsc/pullClientConfigID.md +++ b/dsc/pullClientConfigID.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Setting up a pull client using configuration ID diff --git a/dsc/pullClientConfigID4.md b/dsc/pullClientConfigID4.md index 19699aea09f0..44423b8af9ef 100644 --- a/dsc/pullClientConfigID4.md +++ b/dsc/pullClientConfigID4.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Setting up a pull client using configuration ID in PowerShell 4.0 diff --git a/dsc/pullClientConfigNames.md b/dsc/pullClientConfigNames.md index 5cc594a88f82..0bba50910c7b 100644 --- a/dsc/pullClientConfigNames.md +++ b/dsc/pullClientConfigNames.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Setting up a pull client using configuration names diff --git a/dsc/pullServer.md b/dsc/pullServer.md index 4d331893fe9d..8d6be97ab283 100644 --- a/dsc/pullServer.md +++ b/dsc/pullServer.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Setting up a DSC web pull server diff --git a/dsc/pullServerSMB.md b/dsc/pullServerSMB.md index e2a33b257152..46164c051d97 100644 --- a/dsc/pullServerSMB.md +++ b/dsc/pullServerSMB.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Setting up a DSC SMB pull server diff --git a/dsc/queryServerNodes.md b/dsc/queryServerNodes.md index e010f183e321..24cf59764d69 100644 --- a/dsc/queryServerNodes.md +++ b/dsc/queryServerNodes.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC function to query node information from pull server. diff --git a/dsc/quickStart.md b/dsc/quickStart.md index 702df60ddc5d..e67a6ab45d54 100644 --- a/dsc/quickStart.md +++ b/dsc/quickStart.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Desired State Configuration Quick Start diff --git a/dsc/registryResource.md b/dsc/registryResource.md index 7873455f5736..963e5ae225e9 100644 --- a/dsc/registryResource.md +++ b/dsc/registryResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC Registry Resource diff --git a/dsc/reportServer.md b/dsc/reportServer.md index 1e1fface368e..225ca13f683f 100644 --- a/dsc/reportServer.md +++ b/dsc/reportServer.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Using a DSC report server diff --git a/dsc/resourceAuthoringChecklist.md b/dsc/resourceAuthoringChecklist.md index 016972497b81..63271524614a 100644 --- a/dsc/resourceAuthoringChecklist.md +++ b/dsc/resourceAuthoringChecklist.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Resource authoring checklist diff --git a/dsc/resources.md b/dsc/resources.md index ca7f8e027e82..1eb299d04034 100644 --- a/dsc/resources.md +++ b/dsc/resources.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC Resources diff --git a/dsc/runAsUser.md b/dsc/runAsUser.md index e7eae34079cc..0161d5880579 100644 --- a/dsc/runAsUser.md +++ b/dsc/runAsUser.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Running DSC with user credentials diff --git a/dsc/scriptResource.md b/dsc/scriptResource.md index 57d83484638f..c10a1e8ca73e 100644 --- a/dsc/scriptResource.md +++ b/dsc/scriptResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC Script Resource diff --git a/dsc/secureMOF.md b/dsc/secureMOF.md index aa1bef8921e5..3e3505500462 100644 --- a/dsc/secureMOF.md +++ b/dsc/secureMOF.md @@ -1,6 +1,5 @@ --- ms.date: 2017-10-31 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Securing the MOF File diff --git a/dsc/secureServer.md b/dsc/secureServer.md index ae8b72abd232..fd07448a0b2b 100644 --- a/dsc/secureServer.md +++ b/dsc/secureServer.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Pull server best practices diff --git a/dsc/separatingEnvData.md b/dsc/separatingEnvData.md index cb229942ea49..67bbb51e1128 100644 --- a/dsc/separatingEnvData.md +++ b/dsc/separatingEnvData.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Separating configuration and environment data diff --git a/dsc/serviceResource.md b/dsc/serviceResource.md index ae78593551e2..a17cacbc4fc8 100644 --- a/dsc/serviceResource.md +++ b/dsc/serviceResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC Service Resource diff --git a/dsc/serviceSetResource.md b/dsc/serviceSetResource.md index 72c4450ebca2..37693ebf36f3 100644 --- a/dsc/serviceSetResource.md +++ b/dsc/serviceSetResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC ServiceSet Resource diff --git a/dsc/singleInstance.md b/dsc/singleInstance.md index 55827993e962..c124b72f0b0a 100644 --- a/dsc/singleInstance.md +++ b/dsc/singleInstance.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Writing a single-instance DSC resource (best practice) diff --git a/dsc/sxsResource.md b/dsc/sxsResource.md index 5163ecae4f45..05529c9e8497 100644 --- a/dsc/sxsResource.md +++ b/dsc/sxsResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Using resources with multiple versions diff --git a/dsc/troubleshooting.md b/dsc/troubleshooting.md index 9c32abfaaf84..56281c9f3f67 100644 --- a/dsc/troubleshooting.md +++ b/dsc/troubleshooting.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Troubleshooting DSC diff --git a/dsc/userResource.md b/dsc/userResource.md index f2bf53ba5dfb..3fee140743f1 100644 --- a/dsc/userResource.md +++ b/dsc/userResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC User Resource diff --git a/dsc/waitForAllResource.md b/dsc/waitForAllResource.md index fb8f6357d039..d242f4ea8e11 100644 --- a/dsc/waitForAllResource.md +++ b/dsc/waitForAllResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC WaitForAll Resource diff --git a/dsc/waitForAnyResource.md b/dsc/waitForAnyResource.md index a051e0447383..08aced75cc0a 100644 --- a/dsc/waitForAnyResource.md +++ b/dsc/waitForAnyResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC WaitForAny Resource diff --git a/dsc/waitForSomeResource.md b/dsc/waitForSomeResource.md index 82b23aca68bc..46505c636f0d 100644 --- a/dsc/waitForSomeResource.md +++ b/dsc/waitForSomeResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC WaitForSome Resource diff --git a/dsc/whitepapers.md b/dsc/whitepapers.md index ccff72f051f5..96c7ab036c86 100644 --- a/dsc/whitepapers.md +++ b/dsc/whitepapers.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: Whitepapers diff --git a/dsc/windowsFeatureSetResource.md b/dsc/windowsFeatureSetResource.md index a3edba4cf56f..7e5ba1e7ef38 100644 --- a/dsc/windowsFeatureSetResource.md +++ b/dsc/windowsFeatureSetResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC WindowsFeatureSet Resource diff --git a/dsc/windowsOptionalFeatureResource.md b/dsc/windowsOptionalFeatureResource.md index 09b91140c92a..0b6d7775c878 100644 --- a/dsc/windowsOptionalFeatureResource.md +++ b/dsc/windowsOptionalFeatureResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC WindowsOptionalFeature Resource diff --git a/dsc/windowsOptionalFeatureSetResource.md b/dsc/windowsOptionalFeatureSetResource.md index 6fa9fc8fe1bd..df794644d0ab 100644 --- a/dsc/windowsOptionalFeatureSetResource.md +++ b/dsc/windowsOptionalFeatureSetResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC WindowsOptionalFeatureSet Resource diff --git a/dsc/windowsPackageCabResource.md b/dsc/windowsPackageCabResource.md index aa01ee632bd2..9e9da0869527 100644 --- a/dsc/windowsPackageCabResource.md +++ b/dsc/windowsPackageCabResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC WindowsPackageCab Resource diff --git a/dsc/windowsProcessResource.md b/dsc/windowsProcessResource.md index 3bc9d43a38db..e96a07109630 100644 --- a/dsc/windowsProcessResource.md +++ b/dsc/windowsProcessResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC WindowsProcess Resource diff --git a/dsc/windowsfeatureResource.md b/dsc/windowsfeatureResource.md index 344c32529e68..54cc943eee23 100644 --- a/dsc/windowsfeatureResource.md +++ b/dsc/windowsfeatureResource.md @@ -1,6 +1,5 @@ --- ms.date: 2017-06-12 -author: eslesar ms.topic: conceptual keywords: dsc,powershell,configuration,setup title: DSC WindowsFeature Resource diff --git a/reference/docs-conceptual/core-powershell/web-access/cmdlets/add-pswaauthorizationrule.md b/reference/docs-conceptual/core-powershell/web-access/cmdlets/add-pswaauthorizationrule.md index c67a436820cf..db2631637612 100644 --- a/reference/docs-conceptual/core-powershell/web-access/cmdlets/add-pswaauthorizationrule.md +++ b/reference/docs-conceptual/core-powershell/web-access/cmdlets/add-pswaauthorizationrule.md @@ -1,8 +1,6 @@ --- description: -manager: carmonm ms.topic: article -author: jpjofre ms.prod: powershell keywords: powershell,cmdlet ms.date: 2016-12-12 diff --git a/reference/docs-conceptual/core-powershell/web-access/cmdlets/get-pswaauthorizationrule.md b/reference/docs-conceptual/core-powershell/web-access/cmdlets/get-pswaauthorizationrule.md index 8d1c67432449..0d73455f93ce 100644 --- a/reference/docs-conceptual/core-powershell/web-access/cmdlets/get-pswaauthorizationrule.md +++ b/reference/docs-conceptual/core-powershell/web-access/cmdlets/get-pswaauthorizationrule.md @@ -1,8 +1,6 @@ --- description: -manager: carmonm ms.topic: article -author: jpjofre ms.prod: powershell keywords: powershell,cmdlet ms.date: 2016-12-12 diff --git a/reference/docs-conceptual/core-powershell/web-access/cmdlets/install-pswawebapplication.md b/reference/docs-conceptual/core-powershell/web-access/cmdlets/install-pswawebapplication.md index eb942e915535..e2d275fe141b 100644 --- a/reference/docs-conceptual/core-powershell/web-access/cmdlets/install-pswawebapplication.md +++ b/reference/docs-conceptual/core-powershell/web-access/cmdlets/install-pswawebapplication.md @@ -1,8 +1,6 @@ --- description: -manager: carmonm ms.topic: article -author: jpjofre ms.prod: powershell keywords: powershell,cmdlet ms.date: 2016-12-12 diff --git a/reference/docs-conceptual/core-powershell/web-access/cmdlets/remove-pswaauthorizationrule.md b/reference/docs-conceptual/core-powershell/web-access/cmdlets/remove-pswaauthorizationrule.md index ec68f13e25f6..80ffc21c97ad 100644 --- a/reference/docs-conceptual/core-powershell/web-access/cmdlets/remove-pswaauthorizationrule.md +++ b/reference/docs-conceptual/core-powershell/web-access/cmdlets/remove-pswaauthorizationrule.md @@ -1,8 +1,6 @@ --- description: -manager: carmonm ms.topic: article -author: jpjofre ms.prod: powershell keywords: powershell,cmdlet ms.date: 2016-12-12 diff --git a/reference/docs-conceptual/core-powershell/web-access/cmdlets/test-pswaauthorizationrule.md b/reference/docs-conceptual/core-powershell/web-access/cmdlets/test-pswaauthorizationrule.md index 0957043a3b23..24b1cf96e56e 100644 --- a/reference/docs-conceptual/core-powershell/web-access/cmdlets/test-pswaauthorizationrule.md +++ b/reference/docs-conceptual/core-powershell/web-access/cmdlets/test-pswaauthorizationrule.md @@ -1,8 +1,6 @@ --- description: -manager: carmonm ms.topic: article -author: jpjofre ms.prod: powershell keywords: powershell,cmdlet ms.date: 2016-12-12 diff --git a/reference/docs-conceptual/core-powershell/web-access/cmdlets/uninstall-pswawebapplication.md b/reference/docs-conceptual/core-powershell/web-access/cmdlets/uninstall-pswawebapplication.md index 7d5d8af6f619..a2a142a1b521 100644 --- a/reference/docs-conceptual/core-powershell/web-access/cmdlets/uninstall-pswawebapplication.md +++ b/reference/docs-conceptual/core-powershell/web-access/cmdlets/uninstall-pswawebapplication.md @@ -1,8 +1,6 @@ --- description: -manager: carmonm ms.topic: article -author: jpjofre ms.prod: powershell keywords: powershell,cmdlet ms.date: 2016-12-12 diff --git a/reference/docs-conceptual/core-powershell/web-access/cmdlets/web-access-cmdlets.md b/reference/docs-conceptual/core-powershell/web-access/cmdlets/web-access-cmdlets.md index 21830cbbeb82..39d96dcd87cc 100644 --- a/reference/docs-conceptual/core-powershell/web-access/cmdlets/web-access-cmdlets.md +++ b/reference/docs-conceptual/core-powershell/web-access/cmdlets/web-access-cmdlets.md @@ -1,8 +1,6 @@ --- description: -manager: carmonm ms.topic: article -author: jpjofre ms.prod: powershell keywords: powershell,cmdlet ms.date: 2016-12-12 From db54ddf3113a74cd8d93f004fdd87e87d19745b1 Mon Sep 17 00:00:00 2001 From: Steve Lee Date: Tue, 16 Jan 2018 18:11:05 -0800 Subject: [PATCH 188/188] update docs to reflect change by https://github.com/PowerShell/PowerShell/pull/5923y (#2064) --- reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md b/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md index a5a12f94a2f7..8a8bb3a5f233 100644 --- a/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md +++ b/reference/6/Microsoft.PowerShell.Core/New-ModuleManifest.md @@ -47,7 +47,7 @@ Unless specified in the parameter description, if you omit a parameter from the In Windows PowerShell 2.0, **New-ModuleManifest** prompts you for the values of frequently used parameters that are not specified in the command, in addition to required parameter values. Starting in Windows PowerShell 3.0, it prompts only when required parameter values are not specified. -Module manifest (.psd1) file encoding depends on environment: if it is PowerShell Core running on Linux then encoding is UTF-8 (no BOM); otherwise encoding is UTF-16 (with BOM). +Module manifest (.psd1) file encoding is UTF-8 (no BOM) on all platforms. ## EXAMPLES