From b16728daeeaf3cd83a5169b91a675f081db64d69 Mon Sep 17 00:00:00 2001 From: Bobby Reed Date: Wed, 25 Apr 2018 12:52:38 -0400 Subject: [PATCH 1/6] Fixing issue with faulty links from issue (2322) --- .../About/about_windows_powershell_5.1.md | 9 +++++---- wmf/5.1/scenarios-features.md | 9 +++++---- 2 files changed, 10 insertions(+), 8 deletions(-) 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 d4a9c3b75d75..f84694156335 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 @@ -59,10 +59,11 @@ Starting with version 5.1, PowerShell is available in different editions which d editions of Windows such as Nano Server and Windows IoT. **Learn more about using PowerShell Editions** -- [Determine running edition of PowerShell]() -- [Declare a module's compatibility to specific PowerShell versions]() -- [Filter Get-Module results by CompatiblePSEditions]() -- [Prevent script execution unless run on a compatible edition of PowerShell]() + +- [Determine running edition of PowerShell using $PSVersionTable](/powershell/module/microsoft.powershell.core/about/about_automatic_variables) +- [Filter Get-Module results by CompatiblePSEditions using PSEdition parameter](/powershell/module/microsoft.powershell.core/get-module) +- [Prevent script execution unless run on a compatible edition of PowerShell](/powershell/gallery/psget/script/scriptwithpseditionsupport) +- [Declare a module's compatibility to specific PowerShell versions](/powershell/gallery/psget/module/modulewithpseditionsupport) ### Catalog Cmdlets diff --git a/wmf/5.1/scenarios-features.md b/wmf/5.1/scenarios-features.md index 496d44819232..7a3722b53704 100644 --- a/wmf/5.1/scenarios-features.md +++ b/wmf/5.1/scenarios-features.md @@ -17,10 +17,11 @@ Starting with version 5.1, PowerShell is available in different editions which d - **Core Edition:** Built on .NET Core and provides compatibility with scripts and modules targeting versions of PowerShell running on reduced footprint editions of Windows such as Nano Server and Windows IoT. **Learn more about using PowerShell Editions** -- [Determine running edition of PowerShell]() -- [Declare a module's compatibility to specific PowerShell versions]() -- [Filter Get-Module results by CompatiblePSEditions]() -- [Prevent script execution unless run on a compatible edition of PowerShell]() + +- [Determine running edition of PowerShell using $PSVersionTable](/powershell/module/microsoft.powershell.core/about/about_automatic_variables) +- [Filter Get-Module results by CompatiblePSEditions using PSEdition parameter](/powershell/module/microsoft.powershell.core/get-module) +- [Prevent script execution unless run on a compatible edition of PowerShell](/powershell/gallery/psget/script/scriptwithpseditionsupport) +- [Declare a module's compatibility to specific PowerShell versions](/powershell/gallery/psget/module/modulewithpseditionsupport) ## Catalog Cmdlets From c6ea429a97ab9c6661f1d9416615f06ddf252845 Mon Sep 17 00:00:00 2001 From: Bobby Reed Date: Wed, 25 Apr 2018 13:51:40 -0400 Subject: [PATCH 2/6] Trying smaller pull requests to test Script Automation --- .../About/about_Aliases.md | 7 +- .../About/about_Arithmetic_Operators.md | 23 ++- .../About/about_Arrays.md | 11 +- .../About/about_Assignment_Operators.md | 3 +- .../About/about_Automatic_Variables.md | 8 +- .../About/about_Break.md | 3 +- .../About/about_Command_Precedence.md | 7 +- .../About/about_Command_Syntax.md | 3 +- .../About/about_Comment_Based_Help.md | 32 ++-- .../About/about_CommonParameters.md | 38 ++--- .../About/about_Comparison_Operators.md | 142 +++++++++--------- .../About/about_Continue.md | 3 +- .../About/about_Core_Commands.md | 3 +- .../About/about_Data_Sections.md | 11 +- .../About/about_Debuggers.md | 111 ++++++-------- .../About/about_Do.md | 15 +- .../About/about_Environment_Variables.md | 9 +- .../About/about_Eventlogs.md | 11 +- .../About/about_Execution_Policies.md | 16 +- .../About/about_For.md | 6 +- .../About/about_Foreach.md | 3 +- .../About/about_Format.ps1xml.md | 25 ++- .../About/about_Functions.md | 31 ++-- .../About/about_Functions_Advanced.md | 5 +- .../About/about_Functions_Advanced_Methods.md | 3 +- 25 files changed, 255 insertions(+), 274 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md index a78090e0193a..ecf93d074e5d 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Aliases --- - # About Aliases ## SHORT DESCRIPTION @@ -148,7 +147,7 @@ Get-Alias returns only one type of object, an AliasInfo object include a hyphen, such as "cd" are displayed in the following format: ```powershell -PS C:\> Get-Alias ac +PS> Get-Alias ac CommandType Name Version Source ----------- ---- ------- ------ @@ -177,7 +176,7 @@ For example, the following command creates the syslog function. This function represents the `Get-Eventlog -LogName System` command: ```powershell -function Get-SystemEventlog {Get-Eventlog -LogName System} +function Get-SystemEventlog {Get-EventLog -LogName System} Set-Alias -Name syslog -Value Get-SystemEventlog ``` 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 f86b5c3783ee..e914c6f46864 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 @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Arithmetic_Operators --- - # About Arithmetic Operators ## SHORT DESCRIPTION @@ -364,7 +363,7 @@ The following examples show how to use the arithmetic operators in expressions with PowerShell commands: ```powershell -(get-date) + (new-timespan -day 1) +(Get-Date) + (New-TimeSpan -Days 1) ``` The parenthesis operator forces the evaluation of the `get-date` cmdlet and @@ -456,7 +455,7 @@ For example, the binary complement of 0 is -1, the maximum unsigned integer (0xffffffff), and the binary complement of -1 is 0. ```powershell -PS C:\> -bNot 10 +PS> -bNot 10 -11 ``` @@ -509,11 +508,11 @@ right operand determine how many bits of the left operand are shifted. ## SEE ALSO -* [about_arrays](about_Arrays.md) -* [about_assignment_operators](about_Assignment_Operators.md) -* [about_comparison_operators](about_Comparison_Operators.md) -* [about_hash_tables](about_Hash_Tables.md) -* [about_operators](about_Operators.md) -* [about_variables](about_Variables.md) -* [Get-Date](../../Microsoft.PowerShell.Utility/Get-Date.md) -* [New-TimeSpan](../../Microsoft.PowerShell.Utility/New-TimeSpan.md) \ No newline at end of file +- [about_arrays](about_Arrays.md) +- [about_assignment_operators](about_Assignment_Operators.md) +- [about_comparison_operators](about_Comparison_Operators.md) +- [about_hash_tables](about_Hash_Tables.md) +- [about_operators](about_Operators.md) +- [about_variables](about_Variables.md) +- [Get-Date](../../Microsoft.PowerShell.Utility/Get-Date.md) +- [New-TimeSpan](../../Microsoft.PowerShell.Utility/New-TimeSpan.md) \ No newline at end of file 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 e411fc2b53a0..175aae55fb66 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Arrays --- - # About Arrays # SHORT DESCRIPTION @@ -89,12 +88,12 @@ You can use the array operator to create an array of zero or one object. For example: ```powershell -PS C:\> $a = @("Hello World") -PS C:\> $a.Count +PS> $a = @("Hello World") +PS> $a.Count 1 -PS C:\> $b = @() -PS C:\> $b.Count +PS> $b = @() +PS> $b.Count 0 ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md index b19af2c9c6dc..ac0f1b34c5e6 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md @@ -1,10 +1,9 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 keywords: powershell,cmdlet title: about_Assignment_Operators --- - # About Assignment Operators ## SHORT DESCRIPTION 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 17a43e1cf95d..beef82762869 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,11 +1,10 @@ ---- +--- ms.date: 12/21/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Automatic_Variables --- - # About Automatic Variables ## SHORT DESCRIPTION @@ -286,13 +285,13 @@ profile in commands. For example, you can use it in a command to determine whether a profile has been created: ```powershell -test-path $profile +Test-Path $profile ``` Or, you can use it in a command to create a profile: ```powershell -new-item -type file -path $pshome -force +New-Item -ItemType file -Path $pshome -Force ``` You can also use it in a command to open the profile in Notepad: @@ -460,6 +459,7 @@ this variable can also be found in the Sender property of the PSEventArgs Contains the identifier of the current shell. ### $STACKTRACE + Contains a stack trace for the most recent error. ### $THIS diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Break.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Break.md index a3a67a8190fd..6b1fc476f4c8 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Break.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Break.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Break --- - # About Break ## SHORT DESCRIPTION diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md index 7592f0883d3b..9873216a068b 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md @@ -1,10 +1,9 @@ ---- +--- ms.date: 06/27/2017 schema: 2.0.0 keywords: powershell,cmdlet title: about_Command_Precedence --- - # About Command Precedence ## SHORT DESCRIPTION @@ -210,7 +209,7 @@ For example, if you have a function named "Map" that is hidden by an alias named "Map", use the following command to run the function. ```powershell -&(Get-Command -Name Map -Type Function) +&(Get-Command -Name Map -CommandType Function) ``` or @@ -225,7 +224,7 @@ For example, the following command saves the "Map" function in the "$myMap" variable and then uses the `Call` operator to run it. ```powershell -$myMap = (Get-Command -Name map -Type function) +$myMap = (Get-Command -Name map -CommandType function) &($myMap) ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Syntax.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Syntax.md index db7f64b974ef..4416c054a296 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Syntax.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Syntax.md @@ -1,10 +1,9 @@ ---- +--- ms.date: 06/27/2017 schema: 2.0.0 keywords: powershell,cmdlet title: about_Command_Syntax --- - # About Command Syntax # SHORT DESCRIPTION diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index dcdce243b7d4..552885d55443 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 keywords: powershell,cmdlet @@ -515,17 +515,17 @@ or file name. .EXAMPLE -C:\PS> extension -name "File" +PS> extension -name "File" File.txt .EXAMPLE -C:\PS> extension -name "File" -extension "doc" +PS> extension -name "File" -extension "doc" File.doc .EXAMPLE -C:\PS> extension "File" "doc" +PS> extension "File" "doc" File.doc .LINK @@ -600,17 +600,17 @@ file name. Example 1 -C:\PS> extension -name "File" +PS> extension -name "File" File.txt Example 2 -C:\PS> extension -name "File" -extension "doc" +PS> extension -name "File" -extension "doc" File.doc Example 3 -C:\PS> extension "File" "doc" +PS> extension "File" "doc" File.doc RELATED LINKS @@ -664,17 +664,17 @@ file name. .EXAMPLE -C:\PS> extension -name "File" +PS> extension -name "File" File.txt .EXAMPLE -C:\PS> extension -name "File" -extension "doc" +PS> extension -name "File" -extension "doc" File.doc .EXAMPLE -C:\PS> extension "File" "doc" +PS> extension "File" "doc" File.doc .LINK @@ -726,15 +726,15 @@ None. Update-Month.ps1 does not generate any output. .EXAMPLE -C:\PS> .\Update-Month.ps1 +PS> .\Update-Month.ps1 .EXAMPLE -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv +PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv .EXAMPLE -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath ` +PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath ` C:\Reports\2009\January.csv #> @@ -809,15 +809,15 @@ None. Update-Month.ps1 does not generate any output. Example 1 -C:\PS> .\Update-Month.ps1 +PS> .\Update-Month.ps1 Example 2 -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv +PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv Example 3 -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath +PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv # RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md index fcfbf4a21901..605234508e32 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_CommonParameters --- - # About CommonParameters ## SHORT DESCRIPTION @@ -37,22 +36,22 @@ to user data usually offer these parameters. The following list displays the common parameters. Their aliases are listed in parentheses. -* Debug (db) -* ErrorAction (ea) -* ErrorVariable (ev) -* InformationAction (infa) -* InformationVariable (iv) -* OutVariable (ov) -* OutBuffer (ob) -* PipelineVariable (pv) -* Verbose (vb) -* WarningAction (wa) -* WarningVariable (wv) +- Debug (db) +- ErrorAction (ea) +- ErrorVariable (ev) +- InformationAction (infa) +- InformationVariable (iv) +- OutVariable (ov) +- OutBuffer (ob) +- PipelineVariable (pv) +- Verbose (vb) +- WarningAction (wa) +- WarningVariable (wv) The risk mitigation parameters are: -* WhatIf (wi) -* Confirm (cf) +- WhatIf (wi) +- Confirm (cf) For more information about preference variables, type: help about_Preference_Variables @@ -127,7 +126,7 @@ Stores error messages about the command in the specified variable and in the $Error automatic variable. For more information, type the following command: ```powershell -get-help about_Automatic_Variables +Get-Help about_Automatic_Variables ``` By default, new error messages overwrite error messages that are already @@ -140,6 +139,7 @@ errors in it: ```powershell Get-Process -Id 6 -ErrorVariable a ``` + The following command adds any error messages to the $a variable: ```powershell @@ -275,9 +275,9 @@ that the results should be displayed as "Left range member * Right range member = product". ```powershell -1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } | - Foreach-Object -PV Right -Process { 1..10 } | - Foreach-Object -Process { "$Left * $Right = " + ($Left*$Right) } +1..10 | ForEach-Object -PipelineVariable Left -Process { $_ } | + ForEach-Object -PipelineVariable Right -Process { 1..10 } | + ForEach-Object -Process { "$Left * $Right = " + ($Left*$Right) } ``` ```output diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index d8a05dd57df0..911677d507a1 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Comparison_Operators --- - # About Comparison Operators ## SHORT DESCRIPTION @@ -94,13 +93,13 @@ False C:PS> 1,2,3 -eq 2 2 -PS C:\> "abc" -eq "abc" +PS> "abc" -eq "abc" True -PS C:\> "abc" -eq "abc", "def" +PS> "abc" -eq "abc", "def" False -PS C:\> "abc", "def" -eq "abc" +PS> "abc", "def" -eq "abc" abc ``` @@ -109,17 +108,18 @@ abc Description: Not equal to. Includes a different value. Example: + ```powershell -PS C:\> "abc" -ne "def" +PS> "abc" -ne "def" True -PS C:\> "abc" -ne "abc" +PS> "abc" -ne "abc" False -PS C:\> "abc" -ne "abc", "def" +PS> "abc" -ne "abc", "def" True -PS C:\> "abc", "def" -ne "abc" +PS> "abc", "def" -ne "abc" def ``` @@ -130,10 +130,10 @@ Description: Greater-than. Example: ```powershell -PS C:\> 8 -gt 6 +PS> 8 -gt 6 True -PS C:\> 7, 8, 9 -gt 8 +PS> 7, 8, 9 -gt 8 9 ``` @@ -144,10 +144,10 @@ Description: Greater-than or equal to. Example: ```powershell -PS C:\> 8 -ge 8 +PS> 8 -ge 8 True -PS C:\> 7, 8, 9 -ge 8 +PS> 7, 8, 9 -ge 8 8 9 ``` @@ -160,10 +160,10 @@ Example: ```powershell -PS C:\> 8 -lt 6 +PS> 8 -lt 6 False -PS C:\> 7, 8, 9 -lt 8 +PS> 7, 8, 9 -lt 8 7 ``` @@ -174,10 +174,10 @@ Description: Less-than or equal to. Example: ```powershell -PS C:\> 6 -le 8 +PS> 6 -le 8 True -PS C:\> 7, 8, 9 -le 8 +PS> 7, 8, 9 -le 8 7 8 ``` @@ -217,10 +217,10 @@ Description: Match using the wildcard character (\*). Example: ```powershell -PS C:\> "PowerShell" -like "*shell" +PS> "PowerShell" -like "*shell" True -PS C:\> "PowerShell", "Server" -like "*shell" +PS> "PowerShell", "Server" -like "*shell" PowerShell ``` @@ -231,10 +231,10 @@ Description: Does not match using the wildcard character (\*). Example: ```powershell -PS C:\> "PowerShell" -notlike "*shell" +PS> "PowerShell" -notlike "*shell" False -PS C:\> "PowerShell", "Server" -notlike "*shell" +PS> "PowerShell", "Server" -notlike "*shell" Server ``` @@ -255,11 +255,11 @@ For example, the following command submits a collection of strings to the that match. It does not populate the `$Matches` automatic variable. ```powershell -PS C:\> "Sunday", "Monday", "Tuesday" -match "sun" +PS> "Sunday", "Monday", "Tuesday" -match "sun" Sunday -PS C:\> $matches -PS C:\> +PS> $matches +PS> ``` In contrast, the following command submits a single string to the `-match` @@ -267,10 +267,10 @@ operator. The `-match` operator returns a Boolean value and populates the `$Matches` automatic variable. ```powershell -PS C:\> "Sunday" -match "sun" +PS> "Sunday" -match "sun" True -PS C:\> $matches +PS> $matches Name Value ---- ----- @@ -281,16 +281,16 @@ The `-notmatch` operator populates the `$Matches` automatic variable when the input is scalar and the result is False, that it, when it detects a match. ```powershell -PS C:\> "Sunday" -notmatch "rain" +PS> "Sunday" -notmatch "rain" True -PS C:\> $matches -PS C:\> +PS> $matches +PS> -PS C:\> "Sunday" -notmatch "day" +PS> "Sunday" -notmatch "day" False -PS C:\> $matches +PS> $matches Name Value ---- ----- @@ -305,15 +305,15 @@ is scalar, it populates the `$Matches` automatic variable. Example: ```powershell -PS C:\> "Sunday" -notmatch "sun" +PS> "Sunday" -notmatch "sun" False -PS C:\> $matches +PS> $matches Name Value ---- ----- 0 sun -PS C:\> "Sunday", "Monday" -notmatch "sun" +PS> "Sunday", "Monday" -notmatch "sun" Monday ``` @@ -348,23 +348,23 @@ Syntax: Examples: ```powershell -PS C:\> "abc", "def" -contains "def" +PS> "abc", "def" -contains "def" True -PS C:\> "Windows", "PowerShell" -contains "Shell" +PS> "Windows", "PowerShell" -contains "Shell" False #Not an exact match # Does the list of computers in $DomainServers include $ThisComputer? -PS C:\> $DomainServers -contains $thisComputer +PS> $DomainServers -contains $thisComputer True -PS C:\> "abc", "def", "ghi" -contains "abc", "def" +PS> "abc", "def", "ghi" -contains "abc", "def" False -PS C:\> $a = "abc", "def" -PS C:\> "abc", "def", "ghi" -contains $a +PS> $a = "abc", "def" +PS> "abc", "def", "ghi" -contains $a False -PS C:\> $a, "ghi" -contains $a +PS> $a, "ghi" -contains $a True ``` @@ -385,7 +385,7 @@ Syntax: Examples: ```powershell -PS C:\> "Windows", "PowerShell" -notcontains "Shell" +PS> "Windows", "PowerShell" -notcontains "Shell" True #Not an exact match # Get cmdlet parameters, but exclude common parameters @@ -402,9 +402,9 @@ function get-parms ($cmdlet) } # Find unapproved verbs in the functions in my module -PS C:\> $ApprovedVerbs = Get-Verb | foreach {$_.verb} -PS C:\> $myVerbs = Get-Command -Module MyModule | foreach {$_.verb} -PS C:\> $myVerbs | where {$ApprovedVerbs -notcontains $_} +PS> $ApprovedVerbs = Get-Verb | foreach {$_.verb} +PS> $myVerbs = Get-Command -Module MyModule | foreach {$_.verb} +PS> $myVerbs | where {$ApprovedVerbs -notcontains $_} ForEach Sort Tee @@ -430,24 +430,24 @@ Syntax: Examples: ```powershell -PS C:\> "def" -in "abc", "def" +PS> "def" -in "abc", "def" True -PS C:\> "Shell" -in "Windows", "PowerShell" +PS> "Shell" -in "Windows", "PowerShell" False #Not an exact match -PS C:\> "Windows" -in "Windows", "PowerShell" +PS> "Windows" -in "Windows", "PowerShell" True #An exact match -PS C:\> "Windows", "PowerShell" -in "Windows", "PowerShell", "ServerManager" +PS> "Windows", "PowerShell" -in "Windows", "PowerShell", "ServerManager" False #Using reference equality -PS C:\> $a = "Windows", "PowerShell" -PS C:\> $a -in $a, "ServerManager" +PS> $a = "Windows", "PowerShell" +PS> $a -in $a, "ServerManager" True #Using reference equality -# Does the list of computers in $domainServers include $thisComputer? -PS C:\> $thisComputer -in $domainServers +# Does the list of computers in $DomainServers include $ThisComputer? +PS> $thisComputer -in $domainServers True ``` @@ -470,23 +470,23 @@ Syntax: Examples: ```powershell -PS C:\> "def" -notin "abc", "def" +PS> "def" -notin "abc", "def" False -PS C:\> "ghi" -notin "abc", "def" +PS> "ghi" -notin "abc", "def" True -PS C:\> "Shell" -notin "Windows", "PowerShell" +PS> "Shell" -notin "Windows", "PowerShell" True #Not an exact match -PS C:\> "Windows" -notin "Windows", "PowerShell" +PS> "Windows" -notin "Windows", "PowerShell" False #An exact match # Find unapproved verbs in the functions in my module -PS C:\> $ApprovedVerbs = Get-Verb | foreach {$_.verb} -PS C:\> $MyVerbs = Get-Command -Module MyModule | foreach {$_.verb} +PS> $ApprovedVerbs = Get-Verb | foreach {$_.verb} +PS> $MyVerbs = Get-Command -Module MyModule | foreach {$_.verb} -PS C:\> $MyVerbs | where {$_ -notin $ApprovedVerbs} +PS> $MyVerbs | where {$_ -notin $ApprovedVerbs} ForEach Sort Tee @@ -515,17 +515,17 @@ sensitive, use `-creplace`. To make it explicitly case-insensitive, use `-ireplace`. Consider the following examples: ```powershell -PS C:\> "book" -replace "B", "C" +PS> "book" -replace "B", "C" Cook ``` ```powershell -PS C:\> "book" -ireplace "B", "C" +PS> "book" -ireplace "B", "C" Cook ``` ```powershell -PS C:\> "book" -creplace "B", "C" +PS> "book" -creplace "B", "C" book ``` @@ -543,11 +543,11 @@ Syntax: Example: ```powershell -PS C:\> $a = 1 -PS C:\> $b = "1" -PS C:\> $a -is [int] +PS> $a = 1 +PS> $b = "1" +PS> $a -is [int] True -PS C:\> $a -is $b.GetType() +PS> $a -is $b.GetType() False ``` @@ -560,11 +560,11 @@ Syntax: Example: ```powershell -PS C:\> $a = 1 -PS C:\> $b = "1" -PS C:\> $a -isnot $b.GetType() +PS> $a = 1 +PS> $b = "1" +PS> $a -isnot $b.GetType() True -PS C:\> $b -isnot [int] +PS> $b -isnot [int] True ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Continue.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Continue.md index 1db1ad2a2583..5f55a5db4023 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Continue.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Continue.md @@ -1,10 +1,9 @@ ---- +--- ms.date: 06/25/2017 schema: 2.0.0 keywords: powershell,cmdlet title: about_Continue --- - # About Continue ## SHORT DESCRIPTION diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Core_Commands.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Core_Commands.md index ae597f47e377..4ffcfb822f6e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Core_Commands.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Core_Commands.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Core_Commands --- - # About Core Commands ## SHORT DESCRIPTION diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Data_Sections.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Data_Sections.md index 8e39b2c1a71b..352a70844795 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Data_Sections.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Data_Sections.md @@ -1,12 +1,12 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Data_Sections --- - # About Data Sections + ## about_Data_Sections @@ -39,6 +39,7 @@ sections will not run in Windows PowerShell 1.0 without revision. ### Syntax The syntax for a Data section is as follows: + ```powershell DATA [-supportedCommand ] { @@ -83,6 +84,8 @@ a ```powershell @( "red", "green", "blue" ) ``` + + ```powershell @{ a = 0x1; b = "great"; c ="script" } ``` @@ -179,7 +182,7 @@ A single-quoted here-string that uses the ConvertFrom-StringData cmdlet: ```powershell DATA { - ConvertFrom-StringData -stringdata @' + ConvertFrom-StringData -StringData @' Text001 = Windows 7 Text002 = Windows Server 2008 R2 '@ @@ -190,7 +193,7 @@ A double-quoted here-string that uses the ConvertFrom-StringData cmdlet: ```powershell DATA { - ConvertFrom-StringData -stringdata @" + ConvertFrom-StringData -StringData @" Msg1 = To start, press any key. Msg2 = To exit, type "quit". "@ 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 e9801c1ed08d..a0648b04cb62 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Debuggers.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Debuggers.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Debuggers --- - # About Debuggers ## SHORT DESCRIPTION @@ -223,7 +222,7 @@ For example, the following command gets the variables in the local (script) scope: ```powershell -get-variable -scope 0 +Get-Variable -Scope 0 ``` You can abbreviate the command as: @@ -273,13 +272,13 @@ debugger steps into the workflow function, the debugger prompt changes to [WFDBG]. ```powershell -PS C:> Set-PSBreakpoint -Script C:\TestWFDemo1.ps1 -Line 8 +PS> Set-PSBreakpoint -Script C:\TestWFDemo1.ps1 -Line 8 ID Script Line Command Variable Action -- ------ ---- ------- -------- ------ 0 TestWFDemo1.ps1 8 -PS C:> C:\TestWFDemo1.ps1 +PS> C:\TestWFDemo1.ps1 Entering debug mode. Use h or ? for help. Hit Line breakpoint on 'C:\TestWFDemo1.ps1:8' @@ -288,69 +287,60 @@ At C:\TestWFDemo1.ps1:8 char:5 + Write-Output -InputObject "Now writing output:" # +!INCLUDE[]~~~~~ -[WFDBG:localhost]: PS C:>> list +[WFDBG:localhost]: PS>> list # 3: 4: workflow SampleWorkflowTest 5: { -6: param ($MyOutput) -# 7: +6: param ($MyOutput)# 7: 8:* Write-Output -InputObject "Now writing output:" -9: Write-Output -Input $MyOutput -# 10: +9: Write-Output -Input $MyOutput# 10: 11: Write-Output -InputObject "Get PowerShell process:" -12: Get-Process -Name powershell -# 13: +12: Get-Process -Name powershell# 13: 14: Write-Output -InputObject "Workflow function complete." -15: } -# 16: +15: }# 16: 17: # Call workflow function 18: SampleWorkflowTest -MyOutput "Hello" -[WFDBG:localhost]: PS C:>> $MyOutput +[WFDBG:localhost]: PS>> $MyOutput Hello -[WFDBG:localhost]: PS C:>> stepOver +[WFDBG:localhost]: PS>> stepOver Now writing output: At C:\TestWFDemo1.ps1:9 char:5 + Write-Output -Input $MyOutput # +!INCLUDE[]~ -[WFDBG:localhost]: PS C:>> list +[WFDBG:localhost]: PS>> list 4: workflow SampleWorkflowTest 5: { -6: param ($MyOutput) -# 7: +6: param ($MyOutput)# 7: 8: Write-Output -InputObject "Now writing output:" -9:* Write-Output -Input $MyOutput -# 10: +9:* Write-Output -Input $MyOutput# 10: 11: Write-Output -InputObject "Get PowerShell process:" -12: Get-Process -Name powershell -# 13: +12: Get-Process -Name powershell# 13: 14: Write-Output -InputObject "Workflow function complete." -15: } -# 16: +15: }# 16: 17: # Call workflow function -18: SampleWorkflowTest -MyOutput "Hello" -# 19: +18: SampleWorkflowTest -MyOutput "Hello"# 19: -[WFDBG:localhost]: PS C:>> stepOver +[WFDBG:localhost]: PS>> stepOver Hello At C:\TestWFDemo1.ps1:11 char:5 + Write-Output -InputObject "Get PowerShell process:" # +!INCLUDE[]~~~~~~~~~ -[WFDBG:localhost]: PS C:>> stepOut +[WFDBG:localhost]: PS>> stepOut Get PowerShell process: Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName @@ -371,19 +361,19 @@ For example: ```powershell function test-cmdlet { begin { - write-output "Begin" + Write-Output "Begin" } process { - write-output "Process" + Write-Output "Process" } end { - write-output "End" + Write-Output "End" } } -C:\PS> set-psbreakpoint -command test-cmdlet +PS> set-psbreakpoint -command test-cmdlet -C:\PS> test-cmdlet +PS> test-cmdlet Begin Entering debug mode. Use h or ? for help. @@ -392,7 +382,7 @@ Hit Command breakpoint on 'prompt:test-cmdlet' test-cmdlet -[DBG]: C:\PS> c +[DBG]: PS> c Process Entering debug mode. Use h or ? for help. @@ -400,7 +390,7 @@ Hit Command breakpoint on 'prompt:test-cmdlet' test-cmdlet -[DBG]: C:\PS> c +[DBG]: PS> c End Entering debug mode. Use h or ? for help. @@ -408,7 +398,7 @@ Hit Command breakpoint on 'prompt:test-cmdlet' test-cmdlet -# [DBG]: C:\PS> +# [DBG]: PS> ``` ## Debugging Remote Scripts @@ -427,7 +417,7 @@ on which the session is running, and the DBG prompt that lets you know you are in debugging mode. ```powershell -Enter-Pssession -Cn localhost +Enter-PSSession -ComputerName localhost [localhost]: PS C:\psscripts> Set-PSBreakpoint .\ttest19.ps1 6,11,22,25 ID Script Line Command Variable Action @@ -441,27 +431,24 @@ ID Script Line Command Variable Action Hit Line breakpoint on 'C:\psscripts\ttest19.ps1:11' At C:\psscripts\ttest19.ps1:11 char:1 -+ $winRMName = "WinRM" -# + ~ ++ $winRMName = "WinRM"# + ~ [localhost]: [DBG]: PS C:\psscripts>> list -6: 1..5 | foreach { sleep 1; Write-Output "hello2day $_" } +6: 1..5 | ForEach-Object { Start-Sleep 1; Write-Output "hello2day $_" } 7: } # 8: 9: $count = 10 10: $psName = "PowerShell" 11:* $winRMName = "WinRM" -12: $myVar = 102 -# 13: +12: $myVar = 102# 13: 14: for ($i=0; $i -lt $count; $i++) 15: { -16: sleep 1 +16: Start-Sleep 1 17: Write-Output "Loop iteration is: $i" -18: Write-Output "MyVar is $myVar" -# 19: +18: Write-Output "MyVar is $myVar"# 19: 20: hello2day # 21: @@ -469,8 +456,7 @@ At C:\psscripts\ttest19.ps1:11 char:1 [localhost]: [DBG]: PS C:\psscripts>> stepover At C:\psscripts\ttest19.ps1:12 char:1 -+ $myVar = 102 -# + ~ ++ $myVar = 102# + ~ [localhost]: [DBG]: PS C:\psscripts>> quit [localhost]: PS C:\psscripts> Exit-PSSession @@ -552,8 +538,7 @@ Entering debug mode. Use h or ? for help. Hit Line breakpoint on 'C:\ps-test\test.ps1:1' -test.ps1:1 function psversion { -# DBG> +test.ps1:1 function psversion {# DBG> ``` Use the Step command (s) to execute the first statement in the script and to @@ -571,8 +556,7 @@ verify the value of the variable by displaying its value. In this case, the value is \$null. ```powershell -DBG> $scriptname -# DBG> +DBG> $scriptname# DBG> ``` Use another Step command (s) to execute the current statement and to @@ -610,7 +594,7 @@ steps to the next statement in the script. ```powershell DBG> o Windows PowerShell 2.0 -Have you run a background job today (start-job)? +Have you run a background job today (Start-Job)? test.ps1:13 "Done $scriptname" ``` @@ -669,15 +653,13 @@ 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> +test.ps1:11 $scriptname = $MyInvocation.mycommand.path# DBG> ``` Display the current value of the \$scriptname variable, which is \$null. ```powershell -DBG> $scriptname -# DBG> +DBG> $scriptname# DBG> ``` Use a Step command (s) to execute the statement that populates the variable. @@ -703,7 +685,7 @@ displayed, but it is not executed. ```powershell DBG> v Windows PowerShell 2.0 -Have you run a background job today (start-job)? +Have you run a background job today (Start-Job)? test.ps1:13 "Done $scriptname" ``` @@ -742,8 +724,7 @@ Now, run the script. PS C:\ps-test> .\test.ps1 Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion' -test.ps1:12 psversion -# DBG> +test.ps1:12 psversion# DBG> ``` The script reaches the breakpoint at the function call. At this point, the @@ -759,10 +740,10 @@ 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)? +Have you run a background job today (Start-Job)? Done C:\ps-test\test.ps1 -PS C:\ps-test> get-psbreakpoint | remove-psbreakpoint +PS C:\ps-test> get-psbreakpoint | Remove-PSBreakpoint PS C:\ps-test> ``` @@ -774,8 +755,8 @@ 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} +-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 @@ -785,7 +766,7 @@ 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 }} +-action { if ((Get-ExecutionPolicy) -eq "RemoteSigned") { break }} ``` The Break keyword in the action directs the debugger to execute the diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Do.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Do.md index 93dd570312ef..858bfb241a7a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Do.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Do.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Do --- - # About Do ## SHORT DESCRIPTION @@ -56,9 +55,9 @@ The following example of a Do statement counts the items in an array until it reaches an item with a value of 0. ```powershell -C:\PS> $x = 1,2,78,0 -C:\PS> do { $count++; $a++; } while ($x[$a] -ne 0) -C:\PS> $count +PS> $x = 1,2,78,0 +PS> do { $count++; $a++; } while ($x[$a] -ne 0) +PS> $count 3 ``` @@ -66,9 +65,9 @@ The following example uses the Until keyword. Notice that the not equal to operator (`-ne`) is replaced by the equal to operator (`-eq`). ```powershell -C:\PS> $x = 1,2,78,0 -C:\PS> do { $count++; $a++; } until ($x[$a] -eq 0) -C:\PS> $count +PS> $x = 1,2,78,0 +PS> do { $count++; $a++; } until ($x[$a] -eq 0) +PS> $count 3 ``` 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 4fa771a6171d..cedb91b2524d 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 @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Environment_Variables --- - # About Environment Variables ## SHORT DESCRIPTION @@ -92,7 +91,7 @@ by the name of the variable. For example, to display the value of the COMPUTERNAME environment variable, type: ```powershell -Get-Childitem Env:Computername +Get-ChildItem Env:Computername ``` To display the values of all the environment variables, type: @@ -220,7 +219,7 @@ more information about preference variables, see The environment variables that store preferences include: -* PSExecutionPolicyPreference +- PSExecutionPolicyPreference Stores the execution policy set for the current session. This environment variable exists only when you set an execution policy for a single session. @@ -235,7 +234,7 @@ The environment variables that store preferences include: For more information, see [about_Execution_Policies](about_Execution_Policies.md). -* PSModulePath +- PSModulePath Stores the paths to the default module directories. Windows PowerShell looks for modules in the specified directories when you do not specify a full path diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md index 94f7d8ccec24..40917a15d595 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Eventlogs --- - # About Eventlogs ## Short Description @@ -109,10 +108,10 @@ The following table lists the event log preference variables. By default, only the following event types are enabled: -* $LogEngineLifeCycleEvent -* $LogEngineHealthEvent -* $LogProviderLifeCycleEvent -* $LogProviderHealthEvent +- $LogEngineLifeCycleEvent +- $LogEngineHealthEvent +- $LogProviderLifeCycleEvent +- $LogProviderHealthEvent To enable an event type, set the preference variable for that event type to $true. For example, to enable command life-cycle events, type: diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index 3e185fb66558..99b79446a7f8 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Execution_Policies --- - # About Execution Policies ## Short Description @@ -41,6 +40,7 @@ The Windows PowerShell execution policies are as follows: "Restricted" is the default policy. ### Restricted + - Default execution policy in Windows 8, Windows Server 2012, and Windows 8.1. @@ -53,6 +53,7 @@ script files (.psm1), and Windows PowerShell profiles (.ps1). ### AllSigned + - Scripts can run. - Requires that all scripts and configuration files @@ -66,6 +67,7 @@ untrusted. - Risks running signed, but malicious, scripts. ### RemoteSigned + - Scripts can run. This is the default execution policy in Windows Server 2012 R2. @@ -86,6 +88,7 @@ as by using the Unblock-File cmdlet. than the Internet and signed, but malicious, scripts. ### Unrestricted + - Unsigned scripts can run. (This risks running malicious scripts.) @@ -93,6 +96,7 @@ scripts.) files that are downloaded from the Internet. ### Bypass + - Nothing is blocked and there are no warnings or prompts. @@ -103,6 +107,7 @@ Windows PowerShell is the foundation for a program that has its own security model. ### Undefined + - There is no execution policy set in the current scope. - If the execution policy in all scopes is Undefined, the @@ -125,6 +130,7 @@ execution policy. The Scope values are listed in precedence order. ### Process + The execution policy affects only the current session (the current Windows PowerShell process). @@ -135,10 +141,12 @@ session is closed. You cannot change the policy by editing the variable value. ### CurrentUser + The execution policy affects only the current user. It is stored in the HKEY_CURRENT_USER registry subkey. ### LocalMachine + The execution policy affects all users on the current computer. It is stored in the HKEY_LOCAL_MACHINE registry subkey. @@ -221,6 +229,7 @@ Set-ExecutionPolicy -ExecutionPolicy ``` For example: + ```powershell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned ``` @@ -232,6 +241,7 @@ Set-ExecutionPolicy -ExecutionPolicy -Scope ``` For example: + ```powershell Set-ExecutionPolicy RemoteSigned -Scope CurrentUser ``` @@ -254,6 +264,7 @@ the local computer, type: ```powershell Set-ExecutionPolicy Undefined ``` + Or, type: ```powershell @@ -275,6 +286,7 @@ the **ExecutionPolicy** parameter of powershell.exe to set the execution policy. For example: + ```powershell powershell.exe -ExecutionPolicy AllSigned ``` 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 712698ba32eb..c1a6a940a662 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_For.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_For.md @@ -1,18 +1,19 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_For --- - # About For ## SHORT DESCRIPTION + Describes a language command you can use to run statements based on a conditional test. ## LONG DESCRIPTION + The For statement (also known as a For loop) is a language construct you can use to create a loop that runs commands in a command block while a specified condition evaluates to true. @@ -22,6 +23,7 @@ operate on a subset of these values. In most cases, if you want to iterate all the values in an array, consider using a Foreach statement. ### Syntax + The following shows the For statement syntax. ```powershell diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md index 74a94ec39300..149961acc46b 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Foreach --- - # About ForEach ## SHORT DESCRIPTION diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index f06a452fb02c..21e038584207 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Format.ps1xml --- - # About Format.ps1xml ## Short Description @@ -279,7 +278,7 @@ To test the change, type `Get-Culture`, and then review the output, which includes the Calendar property. ```powershell -PS C:\> Get-Culture +PS> Get-Culture LCID Name Calendar DisplayName ---- ---- -------- ----------- @@ -292,11 +291,11 @@ The ViewDefinitions section of each Format.ps1xml file contains the `` tags that define each view. A typical `` tag includes the following tags: -* `` identifies the name of the view -* `` specifies the object type or types to which the view +- `` identifies the name of the view +- `` specifies the object type or types to which the view applies -* `` specifies how items in the view will be combined in groups -* ``, ``, ``, and `` +- `` specifies how items in the view will be combined in groups +- ``, ``, ``, and `` contain the tags that specify how each item will be displayed The `` tag can contain a `` tag for each object type @@ -367,9 +366,9 @@ The default displays of some basic object types are defined in the Types.ps1xml file in the `$PSHOME` directory. The nodes are named PsStandardMembers, and the subnodes use one of the following tags: -* `` -* `` -* `` +- `` +- `` +- `` For more information, see [about_Types.ps1xml](about_Types.ps1xml.md). @@ -379,9 +378,9 @@ To detect errors in the loading or application of Format.ps1xml files, use the `Trace-Command` cmdlet with any of the following format components as the value of the **Name** parameter: -* FormatFileLoading -* FormatViewBinding -* UpdateFormatData +- FormatFileLoading +- FormatViewBinding +- UpdateFormatData For more information, see [Trace-Command](../../Microsoft.PowerShell.Utility/Trace-Command.md) 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 a67e993a0423..bc67aea23c6a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Functions --- - # About Functions # SHORT DESCRIPTION @@ -99,7 +98,7 @@ function Get-NewPix { $start = Get-Date -Month 1 -Day 1 -Year 2010 $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse - $allpix | where {$_.LastWriteTime -gt $Start} + $allpix | Where-Object {$_.LastWriteTime -gt $Start} } ``` @@ -169,7 +168,7 @@ value of the $size parameter, and it excludes directories: ```powershell function Get-SmallFiles { Param($Size) - Get-ChildItem $HOME | where { + Get-ChildItem $HOME | Where-Object { $_.Length -lt $Size -and !$_.PSIsContainer } } @@ -198,7 +197,7 @@ Get-SmallFiles example: ```powershell function Get-SmallFiles ($Size = 100) { - Get-ChildItem $HOME | where { + Get-ChildItem $HOME | Where-Object { $_.Length -lt $Size -and !$_.PSIsContainer } } @@ -248,7 +247,7 @@ function Get-Extension { ``` ```powershell -C:\PS> Get-Extension myTextFile +PS> Get-Extension myTextFile myTextFile.txt ``` @@ -272,10 +271,10 @@ When you type the On switch parameter after the function name, the function displays "Switch on". Without the switch parameter, it displays "Switch off". ```powershell -C:\PS> Switch-Item -on +PS> Switch-Item -on Switch on -C:\PS> Switch-Item +PS> Switch-Item Switch off ``` @@ -283,10 +282,10 @@ You can also assign a Boolean value to a switch when you run the function, as shown in the following example: ```powershell -C:\PS> Switch-Item -on:$true +PS> Switch-Item -on:$true Switch on -C:\PS> Switch-Item -on:$false +PS> Switch-Item -on:$false Switch off ``` @@ -311,7 +310,7 @@ Get-MyCommand function. The parameters and parameter values are passed to the command using @Args. ```powershell -PS C:> Get-MyCommand -Name Get-ChildItem +PS> Get-MyCommand -Name Get-ChildItem CommandType Name ModuleName ----------- ---- ---------- Cmdlet Get-ChildItem Microsoft.PowerShell.Management @@ -360,7 +359,7 @@ To demonstrate this function, enter an list of numbers separated by commas, as shown in the following example: ```powershell -C:\PS> 1,2,4 | Get-Pipeline +PS> 1,2,4 | Get-Pipeline The value is: 1 The value is: 2 The value is: 4 @@ -387,7 +386,7 @@ If this function is run by using the pipeline, it displays the following results: ```powershell -C:\PS> 1,2,4 | Get-PipelineBeginEnd +PS> 1,2,4 | Get-PipelineBeginEnd Begin: The input is End: The input is 1 2 4 ``` @@ -412,7 +411,7 @@ at a time. The $input automatic variable is empty when the function reaches the End keyword. ```powershell -C:\PS> 1,2,4 | Get-PipelineInput +PS> 1,2,4 | Get-PipelineInput Processing: 1 Processing: 2 Processing: 4 @@ -436,7 +435,7 @@ either the whole entry or only the message portion of the entry: ```powershell filter Get-ErrorLog ([switch]$message) { - if ($message) { out-host -inputobject $_.Message } + if ($message) { Out-Host -InputObject $_.Message } else { $_ } } ``` @@ -454,7 +453,7 @@ the global scope in the following example: ```powershell function global:Get-DependentSvs { - Get-Service | where {$_.DependentServices} + Get-Service | Where-Object {$_.DependentServices} } ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md index 99d8549b8113..2cdebe5fad16 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Functions_Advanced --- - # About Functions Advanced # SHORT DESCRIPTION @@ -51,7 +50,7 @@ function Send-Greeting Process { - write-host ("Hello " + $Name + "!") + Write-Host ("Hello " + $Name + "!") } } ``` 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 a3baad979492..4724a01ba389 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,11 +1,10 @@ ---- +--- ms.date: 01/03/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Functions_Advanced_Methods --- - # About Functions Advanced Methods ## SHORT DESCRIPTION From e7d088d3e72b08cc62fc8e479ce0a7745995b51a Mon Sep 17 00:00:00 2001 From: Bobby Reed Date: Wed, 25 Apr 2018 11:03:59 -0700 Subject: [PATCH 3/6] Testing script automation with a smaller batch of files (#2359) * Fixing issue with faulty links from issue (2322) * Trying smaller pull requests to test Script Automation --- .../About/about_Aliases.md | 7 +- .../About/about_Arithmetic_Operators.md | 23 ++- .../About/about_Arrays.md | 11 +- .../About/about_Assignment_Operators.md | 3 +- .../About/about_Automatic_Variables.md | 8 +- .../About/about_Break.md | 3 +- .../About/about_Command_Precedence.md | 7 +- .../About/about_Command_Syntax.md | 3 +- .../About/about_Comment_Based_Help.md | 32 ++-- .../About/about_CommonParameters.md | 38 ++--- .../About/about_Comparison_Operators.md | 142 +++++++++--------- .../About/about_Continue.md | 3 +- .../About/about_Core_Commands.md | 3 +- .../About/about_Data_Sections.md | 11 +- .../About/about_Debuggers.md | 111 ++++++-------- .../About/about_Do.md | 15 +- .../About/about_Environment_Variables.md | 9 +- .../About/about_Eventlogs.md | 11 +- .../About/about_Execution_Policies.md | 16 +- .../About/about_For.md | 6 +- .../About/about_Foreach.md | 3 +- .../About/about_Format.ps1xml.md | 25 ++- .../About/about_Functions.md | 31 ++-- .../About/about_Functions_Advanced.md | 5 +- .../About/about_Functions_Advanced_Methods.md | 3 +- .../About/about_windows_powershell_5.1.md | 9 +- wmf/5.1/scenarios-features.md | 9 +- 27 files changed, 265 insertions(+), 282 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md index a78090e0193a..ecf93d074e5d 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Aliases.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Aliases --- - # About Aliases ## SHORT DESCRIPTION @@ -148,7 +147,7 @@ Get-Alias returns only one type of object, an AliasInfo object include a hyphen, such as "cd" are displayed in the following format: ```powershell -PS C:\> Get-Alias ac +PS> Get-Alias ac CommandType Name Version Source ----------- ---- ------- ------ @@ -177,7 +176,7 @@ For example, the following command creates the syslog function. This function represents the `Get-Eventlog -LogName System` command: ```powershell -function Get-SystemEventlog {Get-Eventlog -LogName System} +function Get-SystemEventlog {Get-EventLog -LogName System} Set-Alias -Name syslog -Value Get-SystemEventlog ``` 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 f86b5c3783ee..e914c6f46864 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 @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Arithmetic_Operators --- - # About Arithmetic Operators ## SHORT DESCRIPTION @@ -364,7 +363,7 @@ The following examples show how to use the arithmetic operators in expressions with PowerShell commands: ```powershell -(get-date) + (new-timespan -day 1) +(Get-Date) + (New-TimeSpan -Days 1) ``` The parenthesis operator forces the evaluation of the `get-date` cmdlet and @@ -456,7 +455,7 @@ For example, the binary complement of 0 is -1, the maximum unsigned integer (0xffffffff), and the binary complement of -1 is 0. ```powershell -PS C:\> -bNot 10 +PS> -bNot 10 -11 ``` @@ -509,11 +508,11 @@ right operand determine how many bits of the left operand are shifted. ## SEE ALSO -* [about_arrays](about_Arrays.md) -* [about_assignment_operators](about_Assignment_Operators.md) -* [about_comparison_operators](about_Comparison_Operators.md) -* [about_hash_tables](about_Hash_Tables.md) -* [about_operators](about_Operators.md) -* [about_variables](about_Variables.md) -* [Get-Date](../../Microsoft.PowerShell.Utility/Get-Date.md) -* [New-TimeSpan](../../Microsoft.PowerShell.Utility/New-TimeSpan.md) \ No newline at end of file +- [about_arrays](about_Arrays.md) +- [about_assignment_operators](about_Assignment_Operators.md) +- [about_comparison_operators](about_Comparison_Operators.md) +- [about_hash_tables](about_Hash_Tables.md) +- [about_operators](about_Operators.md) +- [about_variables](about_Variables.md) +- [Get-Date](../../Microsoft.PowerShell.Utility/Get-Date.md) +- [New-TimeSpan](../../Microsoft.PowerShell.Utility/New-TimeSpan.md) \ No newline at end of file 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 e411fc2b53a0..175aae55fb66 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Arrays.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Arrays.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Arrays --- - # About Arrays # SHORT DESCRIPTION @@ -89,12 +88,12 @@ You can use the array operator to create an array of zero or one object. For example: ```powershell -PS C:\> $a = @("Hello World") -PS C:\> $a.Count +PS> $a = @("Hello World") +PS> $a.Count 1 -PS C:\> $b = @() -PS C:\> $b.Count +PS> $b = @() +PS> $b.Count 0 ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md index b19af2c9c6dc..ac0f1b34c5e6 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Assignment_Operators.md @@ -1,10 +1,9 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 keywords: powershell,cmdlet title: about_Assignment_Operators --- - # About Assignment Operators ## SHORT DESCRIPTION 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 17a43e1cf95d..beef82762869 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,11 +1,10 @@ ---- +--- ms.date: 12/21/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Automatic_Variables --- - # About Automatic Variables ## SHORT DESCRIPTION @@ -286,13 +285,13 @@ profile in commands. For example, you can use it in a command to determine whether a profile has been created: ```powershell -test-path $profile +Test-Path $profile ``` Or, you can use it in a command to create a profile: ```powershell -new-item -type file -path $pshome -force +New-Item -ItemType file -Path $pshome -Force ``` You can also use it in a command to open the profile in Notepad: @@ -460,6 +459,7 @@ this variable can also be found in the Sender property of the PSEventArgs Contains the identifier of the current shell. ### $STACKTRACE + Contains a stack trace for the most recent error. ### $THIS diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Break.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Break.md index a3a67a8190fd..6b1fc476f4c8 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Break.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Break.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Break --- - # About Break ## SHORT DESCRIPTION diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md index 7592f0883d3b..9873216a068b 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md @@ -1,10 +1,9 @@ ---- +--- ms.date: 06/27/2017 schema: 2.0.0 keywords: powershell,cmdlet title: about_Command_Precedence --- - # About Command Precedence ## SHORT DESCRIPTION @@ -210,7 +209,7 @@ For example, if you have a function named "Map" that is hidden by an alias named "Map", use the following command to run the function. ```powershell -&(Get-Command -Name Map -Type Function) +&(Get-Command -Name Map -CommandType Function) ``` or @@ -225,7 +224,7 @@ For example, the following command saves the "Map" function in the "$myMap" variable and then uses the `Call` operator to run it. ```powershell -$myMap = (Get-Command -Name map -Type function) +$myMap = (Get-Command -Name map -CommandType function) &($myMap) ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Syntax.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Syntax.md index db7f64b974ef..4416c054a296 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Syntax.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Command_Syntax.md @@ -1,10 +1,9 @@ ---- +--- ms.date: 06/27/2017 schema: 2.0.0 keywords: powershell,cmdlet title: about_Command_Syntax --- - # About Command Syntax # SHORT DESCRIPTION diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md index dcdce243b7d4..552885d55443 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 keywords: powershell,cmdlet @@ -515,17 +515,17 @@ or file name. .EXAMPLE -C:\PS> extension -name "File" +PS> extension -name "File" File.txt .EXAMPLE -C:\PS> extension -name "File" -extension "doc" +PS> extension -name "File" -extension "doc" File.doc .EXAMPLE -C:\PS> extension "File" "doc" +PS> extension "File" "doc" File.doc .LINK @@ -600,17 +600,17 @@ file name. Example 1 -C:\PS> extension -name "File" +PS> extension -name "File" File.txt Example 2 -C:\PS> extension -name "File" -extension "doc" +PS> extension -name "File" -extension "doc" File.doc Example 3 -C:\PS> extension "File" "doc" +PS> extension "File" "doc" File.doc RELATED LINKS @@ -664,17 +664,17 @@ file name. .EXAMPLE -C:\PS> extension -name "File" +PS> extension -name "File" File.txt .EXAMPLE -C:\PS> extension -name "File" -extension "doc" +PS> extension -name "File" -extension "doc" File.doc .EXAMPLE -C:\PS> extension "File" "doc" +PS> extension "File" "doc" File.doc .LINK @@ -726,15 +726,15 @@ None. Update-Month.ps1 does not generate any output. .EXAMPLE -C:\PS> .\Update-Month.ps1 +PS> .\Update-Month.ps1 .EXAMPLE -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv +PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv .EXAMPLE -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath ` +PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath ` C:\Reports\2009\January.csv #> @@ -809,15 +809,15 @@ None. Update-Month.ps1 does not generate any output. Example 1 -C:\PS> .\Update-Month.ps1 +PS> .\Update-Month.ps1 Example 2 -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv +PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv Example 3 -C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath +PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv # RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md index fcfbf4a21901..605234508e32 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_CommonParameters --- - # About CommonParameters ## SHORT DESCRIPTION @@ -37,22 +36,22 @@ to user data usually offer these parameters. The following list displays the common parameters. Their aliases are listed in parentheses. -* Debug (db) -* ErrorAction (ea) -* ErrorVariable (ev) -* InformationAction (infa) -* InformationVariable (iv) -* OutVariable (ov) -* OutBuffer (ob) -* PipelineVariable (pv) -* Verbose (vb) -* WarningAction (wa) -* WarningVariable (wv) +- Debug (db) +- ErrorAction (ea) +- ErrorVariable (ev) +- InformationAction (infa) +- InformationVariable (iv) +- OutVariable (ov) +- OutBuffer (ob) +- PipelineVariable (pv) +- Verbose (vb) +- WarningAction (wa) +- WarningVariable (wv) The risk mitigation parameters are: -* WhatIf (wi) -* Confirm (cf) +- WhatIf (wi) +- Confirm (cf) For more information about preference variables, type: help about_Preference_Variables @@ -127,7 +126,7 @@ Stores error messages about the command in the specified variable and in the $Error automatic variable. For more information, type the following command: ```powershell -get-help about_Automatic_Variables +Get-Help about_Automatic_Variables ``` By default, new error messages overwrite error messages that are already @@ -140,6 +139,7 @@ errors in it: ```powershell Get-Process -Id 6 -ErrorVariable a ``` + The following command adds any error messages to the $a variable: ```powershell @@ -275,9 +275,9 @@ that the results should be displayed as "Left range member * Right range member = product". ```powershell -1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } | - Foreach-Object -PV Right -Process { 1..10 } | - Foreach-Object -Process { "$Left * $Right = " + ($Left*$Right) } +1..10 | ForEach-Object -PipelineVariable Left -Process { $_ } | + ForEach-Object -PipelineVariable Right -Process { 1..10 } | + ForEach-Object -Process { "$Left * $Right = " + ($Left*$Right) } ``` ```output diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md index d8a05dd57df0..911677d507a1 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Comparison_Operators.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Comparison_Operators --- - # About Comparison Operators ## SHORT DESCRIPTION @@ -94,13 +93,13 @@ False C:PS> 1,2,3 -eq 2 2 -PS C:\> "abc" -eq "abc" +PS> "abc" -eq "abc" True -PS C:\> "abc" -eq "abc", "def" +PS> "abc" -eq "abc", "def" False -PS C:\> "abc", "def" -eq "abc" +PS> "abc", "def" -eq "abc" abc ``` @@ -109,17 +108,18 @@ abc Description: Not equal to. Includes a different value. Example: + ```powershell -PS C:\> "abc" -ne "def" +PS> "abc" -ne "def" True -PS C:\> "abc" -ne "abc" +PS> "abc" -ne "abc" False -PS C:\> "abc" -ne "abc", "def" +PS> "abc" -ne "abc", "def" True -PS C:\> "abc", "def" -ne "abc" +PS> "abc", "def" -ne "abc" def ``` @@ -130,10 +130,10 @@ Description: Greater-than. Example: ```powershell -PS C:\> 8 -gt 6 +PS> 8 -gt 6 True -PS C:\> 7, 8, 9 -gt 8 +PS> 7, 8, 9 -gt 8 9 ``` @@ -144,10 +144,10 @@ Description: Greater-than or equal to. Example: ```powershell -PS C:\> 8 -ge 8 +PS> 8 -ge 8 True -PS C:\> 7, 8, 9 -ge 8 +PS> 7, 8, 9 -ge 8 8 9 ``` @@ -160,10 +160,10 @@ Example: ```powershell -PS C:\> 8 -lt 6 +PS> 8 -lt 6 False -PS C:\> 7, 8, 9 -lt 8 +PS> 7, 8, 9 -lt 8 7 ``` @@ -174,10 +174,10 @@ Description: Less-than or equal to. Example: ```powershell -PS C:\> 6 -le 8 +PS> 6 -le 8 True -PS C:\> 7, 8, 9 -le 8 +PS> 7, 8, 9 -le 8 7 8 ``` @@ -217,10 +217,10 @@ Description: Match using the wildcard character (\*). Example: ```powershell -PS C:\> "PowerShell" -like "*shell" +PS> "PowerShell" -like "*shell" True -PS C:\> "PowerShell", "Server" -like "*shell" +PS> "PowerShell", "Server" -like "*shell" PowerShell ``` @@ -231,10 +231,10 @@ Description: Does not match using the wildcard character (\*). Example: ```powershell -PS C:\> "PowerShell" -notlike "*shell" +PS> "PowerShell" -notlike "*shell" False -PS C:\> "PowerShell", "Server" -notlike "*shell" +PS> "PowerShell", "Server" -notlike "*shell" Server ``` @@ -255,11 +255,11 @@ For example, the following command submits a collection of strings to the that match. It does not populate the `$Matches` automatic variable. ```powershell -PS C:\> "Sunday", "Monday", "Tuesday" -match "sun" +PS> "Sunday", "Monday", "Tuesday" -match "sun" Sunday -PS C:\> $matches -PS C:\> +PS> $matches +PS> ``` In contrast, the following command submits a single string to the `-match` @@ -267,10 +267,10 @@ operator. The `-match` operator returns a Boolean value and populates the `$Matches` automatic variable. ```powershell -PS C:\> "Sunday" -match "sun" +PS> "Sunday" -match "sun" True -PS C:\> $matches +PS> $matches Name Value ---- ----- @@ -281,16 +281,16 @@ The `-notmatch` operator populates the `$Matches` automatic variable when the input is scalar and the result is False, that it, when it detects a match. ```powershell -PS C:\> "Sunday" -notmatch "rain" +PS> "Sunday" -notmatch "rain" True -PS C:\> $matches -PS C:\> +PS> $matches +PS> -PS C:\> "Sunday" -notmatch "day" +PS> "Sunday" -notmatch "day" False -PS C:\> $matches +PS> $matches Name Value ---- ----- @@ -305,15 +305,15 @@ is scalar, it populates the `$Matches` automatic variable. Example: ```powershell -PS C:\> "Sunday" -notmatch "sun" +PS> "Sunday" -notmatch "sun" False -PS C:\> $matches +PS> $matches Name Value ---- ----- 0 sun -PS C:\> "Sunday", "Monday" -notmatch "sun" +PS> "Sunday", "Monday" -notmatch "sun" Monday ``` @@ -348,23 +348,23 @@ Syntax: Examples: ```powershell -PS C:\> "abc", "def" -contains "def" +PS> "abc", "def" -contains "def" True -PS C:\> "Windows", "PowerShell" -contains "Shell" +PS> "Windows", "PowerShell" -contains "Shell" False #Not an exact match # Does the list of computers in $DomainServers include $ThisComputer? -PS C:\> $DomainServers -contains $thisComputer +PS> $DomainServers -contains $thisComputer True -PS C:\> "abc", "def", "ghi" -contains "abc", "def" +PS> "abc", "def", "ghi" -contains "abc", "def" False -PS C:\> $a = "abc", "def" -PS C:\> "abc", "def", "ghi" -contains $a +PS> $a = "abc", "def" +PS> "abc", "def", "ghi" -contains $a False -PS C:\> $a, "ghi" -contains $a +PS> $a, "ghi" -contains $a True ``` @@ -385,7 +385,7 @@ Syntax: Examples: ```powershell -PS C:\> "Windows", "PowerShell" -notcontains "Shell" +PS> "Windows", "PowerShell" -notcontains "Shell" True #Not an exact match # Get cmdlet parameters, but exclude common parameters @@ -402,9 +402,9 @@ function get-parms ($cmdlet) } # Find unapproved verbs in the functions in my module -PS C:\> $ApprovedVerbs = Get-Verb | foreach {$_.verb} -PS C:\> $myVerbs = Get-Command -Module MyModule | foreach {$_.verb} -PS C:\> $myVerbs | where {$ApprovedVerbs -notcontains $_} +PS> $ApprovedVerbs = Get-Verb | foreach {$_.verb} +PS> $myVerbs = Get-Command -Module MyModule | foreach {$_.verb} +PS> $myVerbs | where {$ApprovedVerbs -notcontains $_} ForEach Sort Tee @@ -430,24 +430,24 @@ Syntax: Examples: ```powershell -PS C:\> "def" -in "abc", "def" +PS> "def" -in "abc", "def" True -PS C:\> "Shell" -in "Windows", "PowerShell" +PS> "Shell" -in "Windows", "PowerShell" False #Not an exact match -PS C:\> "Windows" -in "Windows", "PowerShell" +PS> "Windows" -in "Windows", "PowerShell" True #An exact match -PS C:\> "Windows", "PowerShell" -in "Windows", "PowerShell", "ServerManager" +PS> "Windows", "PowerShell" -in "Windows", "PowerShell", "ServerManager" False #Using reference equality -PS C:\> $a = "Windows", "PowerShell" -PS C:\> $a -in $a, "ServerManager" +PS> $a = "Windows", "PowerShell" +PS> $a -in $a, "ServerManager" True #Using reference equality -# Does the list of computers in $domainServers include $thisComputer? -PS C:\> $thisComputer -in $domainServers +# Does the list of computers in $DomainServers include $ThisComputer? +PS> $thisComputer -in $domainServers True ``` @@ -470,23 +470,23 @@ Syntax: Examples: ```powershell -PS C:\> "def" -notin "abc", "def" +PS> "def" -notin "abc", "def" False -PS C:\> "ghi" -notin "abc", "def" +PS> "ghi" -notin "abc", "def" True -PS C:\> "Shell" -notin "Windows", "PowerShell" +PS> "Shell" -notin "Windows", "PowerShell" True #Not an exact match -PS C:\> "Windows" -notin "Windows", "PowerShell" +PS> "Windows" -notin "Windows", "PowerShell" False #An exact match # Find unapproved verbs in the functions in my module -PS C:\> $ApprovedVerbs = Get-Verb | foreach {$_.verb} -PS C:\> $MyVerbs = Get-Command -Module MyModule | foreach {$_.verb} +PS> $ApprovedVerbs = Get-Verb | foreach {$_.verb} +PS> $MyVerbs = Get-Command -Module MyModule | foreach {$_.verb} -PS C:\> $MyVerbs | where {$_ -notin $ApprovedVerbs} +PS> $MyVerbs | where {$_ -notin $ApprovedVerbs} ForEach Sort Tee @@ -515,17 +515,17 @@ sensitive, use `-creplace`. To make it explicitly case-insensitive, use `-ireplace`. Consider the following examples: ```powershell -PS C:\> "book" -replace "B", "C" +PS> "book" -replace "B", "C" Cook ``` ```powershell -PS C:\> "book" -ireplace "B", "C" +PS> "book" -ireplace "B", "C" Cook ``` ```powershell -PS C:\> "book" -creplace "B", "C" +PS> "book" -creplace "B", "C" book ``` @@ -543,11 +543,11 @@ Syntax: Example: ```powershell -PS C:\> $a = 1 -PS C:\> $b = "1" -PS C:\> $a -is [int] +PS> $a = 1 +PS> $b = "1" +PS> $a -is [int] True -PS C:\> $a -is $b.GetType() +PS> $a -is $b.GetType() False ``` @@ -560,11 +560,11 @@ Syntax: Example: ```powershell -PS C:\> $a = 1 -PS C:\> $b = "1" -PS C:\> $a -isnot $b.GetType() +PS> $a = 1 +PS> $b = "1" +PS> $a -isnot $b.GetType() True -PS C:\> $b -isnot [int] +PS> $b -isnot [int] True ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Continue.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Continue.md index 1db1ad2a2583..5f55a5db4023 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Continue.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Continue.md @@ -1,10 +1,9 @@ ---- +--- ms.date: 06/25/2017 schema: 2.0.0 keywords: powershell,cmdlet title: about_Continue --- - # About Continue ## SHORT DESCRIPTION diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Core_Commands.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Core_Commands.md index ae597f47e377..4ffcfb822f6e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Core_Commands.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Core_Commands.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Core_Commands --- - # About Core Commands ## SHORT DESCRIPTION diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Data_Sections.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Data_Sections.md index 8e39b2c1a71b..352a70844795 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Data_Sections.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Data_Sections.md @@ -1,12 +1,12 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Data_Sections --- - # About Data Sections + ## about_Data_Sections @@ -39,6 +39,7 @@ sections will not run in Windows PowerShell 1.0 without revision. ### Syntax The syntax for a Data section is as follows: + ```powershell DATA [-supportedCommand ] { @@ -83,6 +84,8 @@ a ```powershell @( "red", "green", "blue" ) ``` + + ```powershell @{ a = 0x1; b = "great"; c ="script" } ``` @@ -179,7 +182,7 @@ A single-quoted here-string that uses the ConvertFrom-StringData cmdlet: ```powershell DATA { - ConvertFrom-StringData -stringdata @' + ConvertFrom-StringData -StringData @' Text001 = Windows 7 Text002 = Windows Server 2008 R2 '@ @@ -190,7 +193,7 @@ A double-quoted here-string that uses the ConvertFrom-StringData cmdlet: ```powershell DATA { - ConvertFrom-StringData -stringdata @" + ConvertFrom-StringData -StringData @" Msg1 = To start, press any key. Msg2 = To exit, type "quit". "@ 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 e9801c1ed08d..a0648b04cb62 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Debuggers.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Debuggers.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Debuggers --- - # About Debuggers ## SHORT DESCRIPTION @@ -223,7 +222,7 @@ For example, the following command gets the variables in the local (script) scope: ```powershell -get-variable -scope 0 +Get-Variable -Scope 0 ``` You can abbreviate the command as: @@ -273,13 +272,13 @@ debugger steps into the workflow function, the debugger prompt changes to [WFDBG]. ```powershell -PS C:> Set-PSBreakpoint -Script C:\TestWFDemo1.ps1 -Line 8 +PS> Set-PSBreakpoint -Script C:\TestWFDemo1.ps1 -Line 8 ID Script Line Command Variable Action -- ------ ---- ------- -------- ------ 0 TestWFDemo1.ps1 8 -PS C:> C:\TestWFDemo1.ps1 +PS> C:\TestWFDemo1.ps1 Entering debug mode. Use h or ? for help. Hit Line breakpoint on 'C:\TestWFDemo1.ps1:8' @@ -288,69 +287,60 @@ At C:\TestWFDemo1.ps1:8 char:5 + Write-Output -InputObject "Now writing output:" # +!INCLUDE[]~~~~~ -[WFDBG:localhost]: PS C:>> list +[WFDBG:localhost]: PS>> list # 3: 4: workflow SampleWorkflowTest 5: { -6: param ($MyOutput) -# 7: +6: param ($MyOutput)# 7: 8:* Write-Output -InputObject "Now writing output:" -9: Write-Output -Input $MyOutput -# 10: +9: Write-Output -Input $MyOutput# 10: 11: Write-Output -InputObject "Get PowerShell process:" -12: Get-Process -Name powershell -# 13: +12: Get-Process -Name powershell# 13: 14: Write-Output -InputObject "Workflow function complete." -15: } -# 16: +15: }# 16: 17: # Call workflow function 18: SampleWorkflowTest -MyOutput "Hello" -[WFDBG:localhost]: PS C:>> $MyOutput +[WFDBG:localhost]: PS>> $MyOutput Hello -[WFDBG:localhost]: PS C:>> stepOver +[WFDBG:localhost]: PS>> stepOver Now writing output: At C:\TestWFDemo1.ps1:9 char:5 + Write-Output -Input $MyOutput # +!INCLUDE[]~ -[WFDBG:localhost]: PS C:>> list +[WFDBG:localhost]: PS>> list 4: workflow SampleWorkflowTest 5: { -6: param ($MyOutput) -# 7: +6: param ($MyOutput)# 7: 8: Write-Output -InputObject "Now writing output:" -9:* Write-Output -Input $MyOutput -# 10: +9:* Write-Output -Input $MyOutput# 10: 11: Write-Output -InputObject "Get PowerShell process:" -12: Get-Process -Name powershell -# 13: +12: Get-Process -Name powershell# 13: 14: Write-Output -InputObject "Workflow function complete." -15: } -# 16: +15: }# 16: 17: # Call workflow function -18: SampleWorkflowTest -MyOutput "Hello" -# 19: +18: SampleWorkflowTest -MyOutput "Hello"# 19: -[WFDBG:localhost]: PS C:>> stepOver +[WFDBG:localhost]: PS>> stepOver Hello At C:\TestWFDemo1.ps1:11 char:5 + Write-Output -InputObject "Get PowerShell process:" # +!INCLUDE[]~~~~~~~~~ -[WFDBG:localhost]: PS C:>> stepOut +[WFDBG:localhost]: PS>> stepOut Get PowerShell process: Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName @@ -371,19 +361,19 @@ For example: ```powershell function test-cmdlet { begin { - write-output "Begin" + Write-Output "Begin" } process { - write-output "Process" + Write-Output "Process" } end { - write-output "End" + Write-Output "End" } } -C:\PS> set-psbreakpoint -command test-cmdlet +PS> set-psbreakpoint -command test-cmdlet -C:\PS> test-cmdlet +PS> test-cmdlet Begin Entering debug mode. Use h or ? for help. @@ -392,7 +382,7 @@ Hit Command breakpoint on 'prompt:test-cmdlet' test-cmdlet -[DBG]: C:\PS> c +[DBG]: PS> c Process Entering debug mode. Use h or ? for help. @@ -400,7 +390,7 @@ Hit Command breakpoint on 'prompt:test-cmdlet' test-cmdlet -[DBG]: C:\PS> c +[DBG]: PS> c End Entering debug mode. Use h or ? for help. @@ -408,7 +398,7 @@ Hit Command breakpoint on 'prompt:test-cmdlet' test-cmdlet -# [DBG]: C:\PS> +# [DBG]: PS> ``` ## Debugging Remote Scripts @@ -427,7 +417,7 @@ on which the session is running, and the DBG prompt that lets you know you are in debugging mode. ```powershell -Enter-Pssession -Cn localhost +Enter-PSSession -ComputerName localhost [localhost]: PS C:\psscripts> Set-PSBreakpoint .\ttest19.ps1 6,11,22,25 ID Script Line Command Variable Action @@ -441,27 +431,24 @@ ID Script Line Command Variable Action Hit Line breakpoint on 'C:\psscripts\ttest19.ps1:11' At C:\psscripts\ttest19.ps1:11 char:1 -+ $winRMName = "WinRM" -# + ~ ++ $winRMName = "WinRM"# + ~ [localhost]: [DBG]: PS C:\psscripts>> list -6: 1..5 | foreach { sleep 1; Write-Output "hello2day $_" } +6: 1..5 | ForEach-Object { Start-Sleep 1; Write-Output "hello2day $_" } 7: } # 8: 9: $count = 10 10: $psName = "PowerShell" 11:* $winRMName = "WinRM" -12: $myVar = 102 -# 13: +12: $myVar = 102# 13: 14: for ($i=0; $i -lt $count; $i++) 15: { -16: sleep 1 +16: Start-Sleep 1 17: Write-Output "Loop iteration is: $i" -18: Write-Output "MyVar is $myVar" -# 19: +18: Write-Output "MyVar is $myVar"# 19: 20: hello2day # 21: @@ -469,8 +456,7 @@ At C:\psscripts\ttest19.ps1:11 char:1 [localhost]: [DBG]: PS C:\psscripts>> stepover At C:\psscripts\ttest19.ps1:12 char:1 -+ $myVar = 102 -# + ~ ++ $myVar = 102# + ~ [localhost]: [DBG]: PS C:\psscripts>> quit [localhost]: PS C:\psscripts> Exit-PSSession @@ -552,8 +538,7 @@ Entering debug mode. Use h or ? for help. Hit Line breakpoint on 'C:\ps-test\test.ps1:1' -test.ps1:1 function psversion { -# DBG> +test.ps1:1 function psversion {# DBG> ``` Use the Step command (s) to execute the first statement in the script and to @@ -571,8 +556,7 @@ verify the value of the variable by displaying its value. In this case, the value is \$null. ```powershell -DBG> $scriptname -# DBG> +DBG> $scriptname# DBG> ``` Use another Step command (s) to execute the current statement and to @@ -610,7 +594,7 @@ steps to the next statement in the script. ```powershell DBG> o Windows PowerShell 2.0 -Have you run a background job today (start-job)? +Have you run a background job today (Start-Job)? test.ps1:13 "Done $scriptname" ``` @@ -669,15 +653,13 @@ 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> +test.ps1:11 $scriptname = $MyInvocation.mycommand.path# DBG> ``` Display the current value of the \$scriptname variable, which is \$null. ```powershell -DBG> $scriptname -# DBG> +DBG> $scriptname# DBG> ``` Use a Step command (s) to execute the statement that populates the variable. @@ -703,7 +685,7 @@ displayed, but it is not executed. ```powershell DBG> v Windows PowerShell 2.0 -Have you run a background job today (start-job)? +Have you run a background job today (Start-Job)? test.ps1:13 "Done $scriptname" ``` @@ -742,8 +724,7 @@ Now, run the script. PS C:\ps-test> .\test.ps1 Hit Command breakpoint on 'C:\ps-test\test.ps1:psversion' -test.ps1:12 psversion -# DBG> +test.ps1:12 psversion# DBG> ``` The script reaches the breakpoint at the function call. At this point, the @@ -759,10 +740,10 @@ 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)? +Have you run a background job today (Start-Job)? Done C:\ps-test\test.ps1 -PS C:\ps-test> get-psbreakpoint | remove-psbreakpoint +PS C:\ps-test> get-psbreakpoint | Remove-PSBreakpoint PS C:\ps-test> ``` @@ -774,8 +755,8 @@ 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} +-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 @@ -785,7 +766,7 @@ 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 }} +-action { if ((Get-ExecutionPolicy) -eq "RemoteSigned") { break }} ``` The Break keyword in the action directs the debugger to execute the diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Do.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Do.md index 93dd570312ef..858bfb241a7a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Do.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Do.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Do --- - # About Do ## SHORT DESCRIPTION @@ -56,9 +55,9 @@ The following example of a Do statement counts the items in an array until it reaches an item with a value of 0. ```powershell -C:\PS> $x = 1,2,78,0 -C:\PS> do { $count++; $a++; } while ($x[$a] -ne 0) -C:\PS> $count +PS> $x = 1,2,78,0 +PS> do { $count++; $a++; } while ($x[$a] -ne 0) +PS> $count 3 ``` @@ -66,9 +65,9 @@ The following example uses the Until keyword. Notice that the not equal to operator (`-ne`) is replaced by the equal to operator (`-eq`). ```powershell -C:\PS> $x = 1,2,78,0 -C:\PS> do { $count++; $a++; } until ($x[$a] -eq 0) -C:\PS> $count +PS> $x = 1,2,78,0 +PS> do { $count++; $a++; } until ($x[$a] -eq 0) +PS> $count 3 ``` 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 4fa771a6171d..cedb91b2524d 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 @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Environment_Variables --- - # About Environment Variables ## SHORT DESCRIPTION @@ -92,7 +91,7 @@ by the name of the variable. For example, to display the value of the COMPUTERNAME environment variable, type: ```powershell -Get-Childitem Env:Computername +Get-ChildItem Env:Computername ``` To display the values of all the environment variables, type: @@ -220,7 +219,7 @@ more information about preference variables, see The environment variables that store preferences include: -* PSExecutionPolicyPreference +- PSExecutionPolicyPreference Stores the execution policy set for the current session. This environment variable exists only when you set an execution policy for a single session. @@ -235,7 +234,7 @@ The environment variables that store preferences include: For more information, see [about_Execution_Policies](about_Execution_Policies.md). -* PSModulePath +- PSModulePath Stores the paths to the default module directories. Windows PowerShell looks for modules in the specified directories when you do not specify a full path diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md index 94f7d8ccec24..40917a15d595 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Eventlogs.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/27/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Eventlogs --- - # About Eventlogs ## Short Description @@ -109,10 +108,10 @@ The following table lists the event log preference variables. By default, only the following event types are enabled: -* $LogEngineLifeCycleEvent -* $LogEngineHealthEvent -* $LogProviderLifeCycleEvent -* $LogProviderHealthEvent +- $LogEngineLifeCycleEvent +- $LogEngineHealthEvent +- $LogProviderLifeCycleEvent +- $LogProviderHealthEvent To enable an event type, set the preference variable for that event type to $true. For example, to enable command life-cycle events, type: diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md index 3e185fb66558..99b79446a7f8 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Execution_Policies.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Execution_Policies --- - # About Execution Policies ## Short Description @@ -41,6 +40,7 @@ The Windows PowerShell execution policies are as follows: "Restricted" is the default policy. ### Restricted + - Default execution policy in Windows 8, Windows Server 2012, and Windows 8.1. @@ -53,6 +53,7 @@ script files (.psm1), and Windows PowerShell profiles (.ps1). ### AllSigned + - Scripts can run. - Requires that all scripts and configuration files @@ -66,6 +67,7 @@ untrusted. - Risks running signed, but malicious, scripts. ### RemoteSigned + - Scripts can run. This is the default execution policy in Windows Server 2012 R2. @@ -86,6 +88,7 @@ as by using the Unblock-File cmdlet. than the Internet and signed, but malicious, scripts. ### Unrestricted + - Unsigned scripts can run. (This risks running malicious scripts.) @@ -93,6 +96,7 @@ scripts.) files that are downloaded from the Internet. ### Bypass + - Nothing is blocked and there are no warnings or prompts. @@ -103,6 +107,7 @@ Windows PowerShell is the foundation for a program that has its own security model. ### Undefined + - There is no execution policy set in the current scope. - If the execution policy in all scopes is Undefined, the @@ -125,6 +130,7 @@ execution policy. The Scope values are listed in precedence order. ### Process + The execution policy affects only the current session (the current Windows PowerShell process). @@ -135,10 +141,12 @@ session is closed. You cannot change the policy by editing the variable value. ### CurrentUser + The execution policy affects only the current user. It is stored in the HKEY_CURRENT_USER registry subkey. ### LocalMachine + The execution policy affects all users on the current computer. It is stored in the HKEY_LOCAL_MACHINE registry subkey. @@ -221,6 +229,7 @@ Set-ExecutionPolicy -ExecutionPolicy ``` For example: + ```powershell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned ``` @@ -232,6 +241,7 @@ Set-ExecutionPolicy -ExecutionPolicy -Scope ``` For example: + ```powershell Set-ExecutionPolicy RemoteSigned -Scope CurrentUser ``` @@ -254,6 +264,7 @@ the local computer, type: ```powershell Set-ExecutionPolicy Undefined ``` + Or, type: ```powershell @@ -275,6 +286,7 @@ the **ExecutionPolicy** parameter of powershell.exe to set the execution policy. For example: + ```powershell powershell.exe -ExecutionPolicy AllSigned ``` 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 712698ba32eb..c1a6a940a662 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_For.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_For.md @@ -1,18 +1,19 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_For --- - # About For ## SHORT DESCRIPTION + Describes a language command you can use to run statements based on a conditional test. ## LONG DESCRIPTION + The For statement (also known as a For loop) is a language construct you can use to create a loop that runs commands in a command block while a specified condition evaluates to true. @@ -22,6 +23,7 @@ operate on a subset of these values. In most cases, if you want to iterate all the values in an array, consider using a Foreach statement. ### Syntax + The following shows the For statement syntax. ```powershell diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md index 74a94ec39300..149961acc46b 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Foreach.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Foreach --- - # About ForEach ## SHORT DESCRIPTION diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index f06a452fb02c..21e038584207 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Format.ps1xml --- - # About Format.ps1xml ## Short Description @@ -279,7 +278,7 @@ To test the change, type `Get-Culture`, and then review the output, which includes the Calendar property. ```powershell -PS C:\> Get-Culture +PS> Get-Culture LCID Name Calendar DisplayName ---- ---- -------- ----------- @@ -292,11 +291,11 @@ The ViewDefinitions section of each Format.ps1xml file contains the `` tags that define each view. A typical `` tag includes the following tags: -* `` identifies the name of the view -* `` specifies the object type or types to which the view +- `` identifies the name of the view +- `` specifies the object type or types to which the view applies -* `` specifies how items in the view will be combined in groups -* ``, ``, ``, and `` +- `` specifies how items in the view will be combined in groups +- ``, ``, ``, and `` contain the tags that specify how each item will be displayed The `` tag can contain a `` tag for each object type @@ -367,9 +366,9 @@ The default displays of some basic object types are defined in the Types.ps1xml file in the `$PSHOME` directory. The nodes are named PsStandardMembers, and the subnodes use one of the following tags: -* `` -* `` -* `` +- `` +- `` +- `` For more information, see [about_Types.ps1xml](about_Types.ps1xml.md). @@ -379,9 +378,9 @@ To detect errors in the loading or application of Format.ps1xml files, use the `Trace-Command` cmdlet with any of the following format components as the value of the **Name** parameter: -* FormatFileLoading -* FormatViewBinding -* UpdateFormatData +- FormatFileLoading +- FormatViewBinding +- UpdateFormatData For more information, see [Trace-Command](../../Microsoft.PowerShell.Utility/Trace-Command.md) 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 a67e993a0423..bc67aea23c6a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Functions --- - # About Functions # SHORT DESCRIPTION @@ -99,7 +98,7 @@ function Get-NewPix { $start = Get-Date -Month 1 -Day 1 -Year 2010 $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse - $allpix | where {$_.LastWriteTime -gt $Start} + $allpix | Where-Object {$_.LastWriteTime -gt $Start} } ``` @@ -169,7 +168,7 @@ value of the $size parameter, and it excludes directories: ```powershell function Get-SmallFiles { Param($Size) - Get-ChildItem $HOME | where { + Get-ChildItem $HOME | Where-Object { $_.Length -lt $Size -and !$_.PSIsContainer } } @@ -198,7 +197,7 @@ Get-SmallFiles example: ```powershell function Get-SmallFiles ($Size = 100) { - Get-ChildItem $HOME | where { + Get-ChildItem $HOME | Where-Object { $_.Length -lt $Size -and !$_.PSIsContainer } } @@ -248,7 +247,7 @@ function Get-Extension { ``` ```powershell -C:\PS> Get-Extension myTextFile +PS> Get-Extension myTextFile myTextFile.txt ``` @@ -272,10 +271,10 @@ When you type the On switch parameter after the function name, the function displays "Switch on". Without the switch parameter, it displays "Switch off". ```powershell -C:\PS> Switch-Item -on +PS> Switch-Item -on Switch on -C:\PS> Switch-Item +PS> Switch-Item Switch off ``` @@ -283,10 +282,10 @@ You can also assign a Boolean value to a switch when you run the function, as shown in the following example: ```powershell -C:\PS> Switch-Item -on:$true +PS> Switch-Item -on:$true Switch on -C:\PS> Switch-Item -on:$false +PS> Switch-Item -on:$false Switch off ``` @@ -311,7 +310,7 @@ Get-MyCommand function. The parameters and parameter values are passed to the command using @Args. ```powershell -PS C:> Get-MyCommand -Name Get-ChildItem +PS> Get-MyCommand -Name Get-ChildItem CommandType Name ModuleName ----------- ---- ---------- Cmdlet Get-ChildItem Microsoft.PowerShell.Management @@ -360,7 +359,7 @@ To demonstrate this function, enter an list of numbers separated by commas, as shown in the following example: ```powershell -C:\PS> 1,2,4 | Get-Pipeline +PS> 1,2,4 | Get-Pipeline The value is: 1 The value is: 2 The value is: 4 @@ -387,7 +386,7 @@ If this function is run by using the pipeline, it displays the following results: ```powershell -C:\PS> 1,2,4 | Get-PipelineBeginEnd +PS> 1,2,4 | Get-PipelineBeginEnd Begin: The input is End: The input is 1 2 4 ``` @@ -412,7 +411,7 @@ at a time. The $input automatic variable is empty when the function reaches the End keyword. ```powershell -C:\PS> 1,2,4 | Get-PipelineInput +PS> 1,2,4 | Get-PipelineInput Processing: 1 Processing: 2 Processing: 4 @@ -436,7 +435,7 @@ either the whole entry or only the message portion of the entry: ```powershell filter Get-ErrorLog ([switch]$message) { - if ($message) { out-host -inputobject $_.Message } + if ($message) { Out-Host -InputObject $_.Message } else { $_ } } ``` @@ -454,7 +453,7 @@ the global scope in the following example: ```powershell function global:Get-DependentSvs { - Get-Service | where {$_.DependentServices} + Get-Service | Where-Object {$_.DependentServices} } ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md index 99d8549b8113..2cdebe5fad16 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Functions_Advanced --- - # About Functions Advanced # SHORT DESCRIPTION @@ -51,7 +50,7 @@ function Send-Greeting Process { - write-host ("Hello " + $Name + "!") + Write-Host ("Hello " + $Name + "!") } } ``` 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 a3baad979492..4724a01ba389 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,11 +1,10 @@ ---- +--- ms.date: 01/03/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Functions_Advanced_Methods --- - # About Functions Advanced Methods ## SHORT DESCRIPTION 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 d4a9c3b75d75..f84694156335 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 @@ -59,10 +59,11 @@ Starting with version 5.1, PowerShell is available in different editions which d editions of Windows such as Nano Server and Windows IoT. **Learn more about using PowerShell Editions** -- [Determine running edition of PowerShell]() -- [Declare a module's compatibility to specific PowerShell versions]() -- [Filter Get-Module results by CompatiblePSEditions]() -- [Prevent script execution unless run on a compatible edition of PowerShell]() + +- [Determine running edition of PowerShell using $PSVersionTable](/powershell/module/microsoft.powershell.core/about/about_automatic_variables) +- [Filter Get-Module results by CompatiblePSEditions using PSEdition parameter](/powershell/module/microsoft.powershell.core/get-module) +- [Prevent script execution unless run on a compatible edition of PowerShell](/powershell/gallery/psget/script/scriptwithpseditionsupport) +- [Declare a module's compatibility to specific PowerShell versions](/powershell/gallery/psget/module/modulewithpseditionsupport) ### Catalog Cmdlets diff --git a/wmf/5.1/scenarios-features.md b/wmf/5.1/scenarios-features.md index 496d44819232..7a3722b53704 100644 --- a/wmf/5.1/scenarios-features.md +++ b/wmf/5.1/scenarios-features.md @@ -17,10 +17,11 @@ Starting with version 5.1, PowerShell is available in different editions which d - **Core Edition:** Built on .NET Core and provides compatibility with scripts and modules targeting versions of PowerShell running on reduced footprint editions of Windows such as Nano Server and Windows IoT. **Learn more about using PowerShell Editions** -- [Determine running edition of PowerShell]() -- [Declare a module's compatibility to specific PowerShell versions]() -- [Filter Get-Module results by CompatiblePSEditions]() -- [Prevent script execution unless run on a compatible edition of PowerShell]() + +- [Determine running edition of PowerShell using $PSVersionTable](/powershell/module/microsoft.powershell.core/about/about_automatic_variables) +- [Filter Get-Module results by CompatiblePSEditions using PSEdition parameter](/powershell/module/microsoft.powershell.core/get-module) +- [Prevent script execution unless run on a compatible edition of PowerShell](/powershell/gallery/psget/script/scriptwithpseditionsupport) +- [Declare a module's compatibility to specific PowerShell versions](/powershell/gallery/psget/module/modulewithpseditionsupport) ## Catalog Cmdlets From 745108f3e71d33a31558ca803fca8002d10476e8 Mon Sep 17 00:00:00 2001 From: Bobby Reed Date: Fri, 27 Apr 2018 12:21:33 -0700 Subject: [PATCH 4/6] Git Batch testing 15 files (#2371) * Git Batch testing 15 files * re run automation to fix bad link replacement --- .../Microsoft.PowerShell.Core/Add-History.md | 46 +++-- .../Microsoft.PowerShell.Core/Add-PSSnapin.md | 56 ++++-- .../Clear-History.md | 48 +++++- .../Connect-PSSession.md | 84 ++++++--- .../Disable-PSRemoting.md | 69 +++++--- .../Disable-PSSessionConfiguration.md | 52 ++++-- .../Disconnect-PSSession.md | 82 ++++++--- .../Enable-PSRemoting.md | 42 +++-- .../Enable-PSSessionConfiguration.md | 44 ++++- .../Enter-PSSession.md | 94 +++++++--- .../Exit-PSSession.md | 40 +++-- .../Export-Console.md | 61 +++++-- .../Export-ModuleMember.md | 52 ++++-- .../ForEach-Object.md | 64 +++++-- .../Microsoft.PowerShell.Core/Get-Command.md | 110 +++++++++--- .../3.0/Microsoft.PowerShell.Core/Get-Help.md | 114 +++++++++--- .../Microsoft.PowerShell.Core/Get-History.md | 42 ++++- .../3.0/Microsoft.PowerShell.Core/Get-Job.md | 116 +++++++++---- .../Microsoft.PowerShell.Core/Get-Module.md | 85 ++++++--- .../Get-PSSession.md | 84 +++++++-- .../Get-PSSessionConfiguration.md | 69 +++++--- .../Microsoft.PowerShell.Core/Get-PSSnapin.md | 31 +++- .../Import-Module.md | 143 +++++++++++----- .../Invoke-Command.md | 162 +++++++++++++----- .../Invoke-History.md | 43 ++++- .../Microsoft.PowerShell.Core.md | 61 ++++++- .../Microsoft.PowerShell.Core/New-Module.md | 71 ++++++-- .../New-ModuleManifest.md | 78 +++++++-- .../New-PSSession.md | 87 ++++++++-- .../New-PSSessionConfigurationFile.md | 87 +++++++--- .../New-PSSessionOption.md | 88 +++++++--- .../New-PSTransportOption.md | 48 ++++-- 32 files changed, 1782 insertions(+), 571 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Add-History.md b/reference/3.0/Microsoft.PowerShell.Core/Add-History.md index 955b4b2d6404..ab56164a8558 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Add-History.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Add-History.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113279 external help file: System.Management.Automation.dll-Help.xml title: Add-History --- - # Add-History + ## SYNOPSIS + Appends entries to the session history. + ## SYNTAX ``` @@ -18,16 +20,19 @@ Add-History [[-InputObject] ] [-Passthru] [] ``` ## DESCRIPTION + The **Add-History** cmdlet adds entries to the end of the session history, that is, the list of commands entered during the current session. You can use the Get-History cmdlet to get the commands and pass them to **Add-History**, or you can export the commands to a CSV or XML file, then import the commands, and pass the imported file to **Add-History**. You can use this cmdlet to add specific commands to the history or to create a single history file that includes commands from more than one session. + ## EXAMPLES ### Example 1 + ``` -PS C:\> get-history | export-csv c:\testing\history.csv -PS C:\> import-csv history.csv | add-history +PS> get-history | export-csv c:\testing\history.csv +PS> import-csv history.csv | add-history ``` These commands add the commands typed in one Windows PowerShell session to the history of a different Windows PowerShell session. @@ -35,9 +40,11 @@ The first command gets objects representing the commands in the history and expo The second command is typed at the command line of a different session. It uses the Import-Csv cmdlet to import the objects in the History.csv file. The pipeline operator passes the objects to the **Add-History** cmdlet, which adds the objects representing the commands in the History.csv file to the current session history. + ### Example 2 + ``` -PS C:\> import-clixml c:\temp\history.xml | add-history -passthru | foreach-object -process {invoke-history} +PS> import-clixml c:\temp\history.xml | add-history -passthru | foreach-object -process {invoke-history} ``` This command imports commands from the History.xml file, adds them to the current session history, and then executes the commands in the combined history. @@ -48,19 +55,23 @@ The PassThru parameter passes the objects representing the added commands down t The command then uses the ForEach-Object cmdlet to apply the Invoke-History command to each of the commands in the combined history. The **Invoke-History** command is formatted as a script block (enclosed in braces) as required by the **Process** parameter of the **ForEach-Object** cmdlet. + ### Example 3 + ``` -PS C:\> get-history -id 5 -count 5 | add-history +PS> get-history -id 5 -count 5 | add-history ``` This command adds the first five commands in the history to the end of the history list. It uses the Get-History cmdlet to get the five commands ending in command 5. The pipeline operator (|) passes them to the **Add-History** cmdlet, which appends them to the current history. The **Add-History** command does not include any parameters, but Windows PowerShell associates the objects passed through the pipeline with the **InputObject** parameter of ** Add-History**. + ### Example 4 + ``` -PS C:\> $a = import-csv c:\testing\history.csv -PS C:\> add-history -inputobject $a -passthru +PS> $a = import-csv c:\testing\history.csv +PS> add-history -inputobject $a -passthru ``` These commands add the commands in the History.csv file to the current session history. @@ -68,18 +79,22 @@ The first command uses the Import-Csv cmdlet to import the commands in the Histo The second command uses the **Add-History** cmdlet to add the commands from History.csv to the current session history. It uses the **InputObject** parameter to specify the $a variable and the **PassThru** parameter to generate an object to display at the command line. Without the **PassThru** parameter, the **Add-History** cmdlet does not generate any output. + ### Example 5 + ``` -PS C:\> add-history -inputobject (import-clixml c:\temp\history01.xml) +PS> add-history -inputobject (import-clixml c:\temp\history01.xml) ``` This command adds the commands in the History01.xml file to the current session history. It uses the **InputObject** parameter to pass the results of the command in parentheses to the **Add-History** cmdlet. The command in parentheses, which is executed first, imports the History01.xml file into Windows PowerShell. The **Add-History** cmdlet then adds the commands in the file to the session history. + ## PARAMETERS ### -InputObject + Adds the specified HistoryInfo object to the session history. You can use this parameter to submit a HistoryInfo object, such as the ones that are returned by the Get-History, Import-Clixml, or Import-Csv cmdlets, to **Add-History**. @@ -96,6 +111,7 @@ Accept wildcard characters: False ``` ### -Passthru + Returns a history object for each history entry. By default, this cmdlet does not generate any output. @@ -112,18 +128,25 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### Microsoft.PowerShell.Commands.HistoryInfo + You can pipe a HistoryInfo object to **Add-History**. + ## OUTPUTS ### None or Microsoft.PowerShell.Commands.HistoryInfo + When you use the **PassThru** parameter, **Add-History** returns a HistoryInfo object. Otherwise, this cmdlet does not generate any output. + ## NOTES -* The session history is a list of the commands entered during the session along with the ID. 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 session history, see about_History. + +- The session history is a list of the commands entered during the session along with the ID. 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 session history, see about_History. To specify the commands to add to the history, use the **InputObject** parameter. The **Add-History** command accepts only **HistoryInfo** objects, such as those returned for each command by the Get-History cmdlet. @@ -139,7 +162,8 @@ If you intend to pass the objects back to **Add-History**, do not use the **NoTy To edit the session history, export the session to a CSV or XML file, edit the file, import the file, and use **Add-History** to append it to the current session history. -* +- + ## RELATED LINKS [Clear-History](Clear-History.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Add-PSSnapin.md b/reference/3.0/Microsoft.PowerShell.Core/Add-PSSnapin.md index b90f81eeb490..96207bf13e23 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Add-PSSnapin.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Add-PSSnapin.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113281 external help file: System.Management.Automation.dll-Help.xml title: Add-PSSnapin --- - # Add-PSSnapin + ## SYNOPSIS + Adds one or more Windows PowerShell snap-ins to the current session. + ## SYNTAX ``` @@ -18,6 +20,7 @@ Add-PSSnapin [-Name] [-PassThru] [] ``` ## DESCRIPTION + The Add-PSSnapin cmdlet adds registered Windows PowerShell snap-ins to the current session. After the snap-ins are added, you can use the cmdlets and providers that the snap-ins support in the current session. @@ -28,55 +31,63 @@ Beginning in Windows PowerShell 3.0, the core commands that are included in Wind The exception is **Microsoft.PowerShell.Core**, which is a snap-in (PSSnapin). By default, only the **Microsoft.PowerShell.Core** snap-in is added to the session. Modules are imported automatically on first use and you can use the Import-Module cmdlet to import them. + ## EXAMPLES ### Example 1 + ``` -PS C:\> add-PSSnapIn Microsoft.Exchange, Microsoft.Windows.AD +PS> add-PSSnapIn Microsoft.Exchange, Microsoft.Windows.AD ``` This command adds the Microsoft Exchange and Active Directory snap-ins to the current session. + ### Example 2 + ``` -PS C:\> get-pssnapin -registered | add-pssnapin -passthru +PS> get-pssnapin -registered | add-pssnapin -passthru ``` This command adds all of the registered Windows PowerShell snap-ins to the session. It uses the Get-PSSnapin cmdlet with the Registered parameter to get objects representing each of the registered snap-ins. The pipeline operator (|) passes the result to Add-PSSnapin, which adds them to the session. The PassThru parameter returns objects that represent each of the added snap-ins. + ### Example 3 + ``` The first command gets snap-ins that have been added to the current session, including the snap-ins that are installed with Windows PowerShell. In this example, ManagementFeatures is not returned. This indicates that it has not been added to the session. -PS C:\> get-pssnapin +PS> get-pssnapin The second command gets snap-ins that have been registered on your system (including those that have already been added to the session). It does not include the snap-ins that are installed with Windows PowerShell.In this case, the command does not return any snap-ins. This indicates that the ManagementFeatures snapin has not been registered on the system. -PS C:\> get-pssnapin -registered +PS> get-pssnapin -registered The third command creates an alias, "installutil", for the path to the InstallUtil tool in .NET Framework. -PS C:\> set-alias installutil $env:windir\Microsoft.NET\Framework\v2.0.50727\installutil.exe +PS> set-alias installutil $env:windir\Microsoft.NET\Framework\v2.0.50727\installutil.exe The fourth command uses the InstallUtil tool to register the snap-in. The command specifies the path to ManagementCmdlets.dll, the file name or "module name" of the snap-in. -PS C:\> installutil C:\Dev\Management\ManagementCmdlets.dll +PS> installutil C:\Dev\Management\ManagementCmdlets.dll The fifth command is the same as the second command. This time, you use it to verify that the ManagementCmdlets snap-in is registered. -PS C:\> get-pssnapin -registered +PS> get-pssnapin -registered The sixth command uses the Add-PSSnapin cmdlet to add the ManagementFeatures snap-in to the session. It specifies the name of the snap-in, ManagementFeatures, not the file name. -PS C:\> add-pssnapin ManagementFeatures +PS> add-pssnapin ManagementFeatures To verify that the snap-in is added to the session, the seventh command uses the Module parameter of the Get-Command cmdlet. It displays the items that were added to the session by a snap-in or module. -PS C:\> get-command -module ManagementFeatures +PS> get-command -module ManagementFeatures You can also use the PSSnapin property of the object that the Get-Command cmdlet returns to find the snap-in or module in which a cmdlet originated. The eighth command uses dot notation to find the value of the PSSnapin property of the Set-Alias cmdlet. -PS C:\> (get-command set-alias).pssnapin +PS> (get-command set-alias).pssnapin ``` This example demonstrates the process of registering a snap-in on your system and then adding it to your session. It uses ManagementFeatures, a fictitious snap-in implemented in a file called ManagementCmdlets.dll. + ## PARAMETERS ### -Name + Specifies the name of the snap-in. (This is the Name, not the AssemblyName or ModuleName.) Wildcards are permitted. @@ -95,6 +106,7 @@ Accept wildcard characters: True ``` ### -PassThru + Returns an object representing each added snap-in. By default, this cmdlet does not generate any output. @@ -111,26 +123,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 ### None + You cannot pipe objects to Add-PSSnapin. + ## OUTPUTS ### None or System.Management.Automation.PSSnapInInfo + When you use the PassThru parameter, Add-PSSnapin returns a PSSnapInInfo object that represents the snap-in. Otherwise, this cmdlet does not generate any output. + ## NOTES -* Beginning in Windows PowerShell 3.0, the core commands that are installed with Windows PowerShell are packaged in modules. In Windows PowerShell 2.0, and in host programs that create older-style sessions in later versions of Windows PowerShell, the core commands are packaged in snap-ins ("PSSnapins"). The exception is **Microsoft.PowerShell.Core**, which is always a snap-in. Also, remote sessions, such as those started by the New-PSSession cmdlet, are older-style sessions that include core snap-ins. + +- Beginning in Windows PowerShell 3.0, the core commands that are installed with Windows PowerShell are packaged in modules. In Windows PowerShell 2.0, and in host programs that create older-style sessions in later versions of Windows PowerShell, the core commands are packaged in snap-ins ("PSSnapins"). The exception is **Microsoft.PowerShell.Core**, which is always a snap-in. Also, remote sessions, such as those started by the New-PSSession cmdlet, are older-style sessions that include core snap-ins. For information about the **CreateDefault2** method that creates newer-style sessions with core modules, see [CreateDefault2 Method](https://msdn.microsoft.com/library/system.management.automation.runspaces.initialsessionstate.createdefault2) in the MSDN library. -* For more information about snap-ins, see [about_PSSnapins](About/about_PSSnapins.md) and [How to Create a Windows PowerShell Snap-in](https://go.microsoft.com/fwlink/?LinkId=144762) in the MSDN library. -* Add-PSSnapin adds the snap-in only to the current session. To add the snap-in to all Windows PowerShell sessions, add it to your Windows PowerShell profile. For more information, see about_Profiles. -* You can add any snap-in that has been registered by using the Microsoft .NET Framework install utility. 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 a list of snap-ins that are registered on your computer, type get-pssnapin -registered. -* Before adding a snap-in, Add-PSSnapin checks the version of the snap-in to verify that it is compatible with the current version of Windows PowerShell. If the snap-in fails the version check, Windows PowerShell reports an error. +- For more information about snap-ins, see [about_PSSnapins](About/about_PSSnapins.md) and [How to Create a Windows PowerShell Snap-in](https://go.microsoft.com/fwlink/?LinkId=144762) in the MSDN library. +- Add-PSSnapin adds the snap-in only to the current session. To add the snap-in to all Windows PowerShell sessions, add it to your Windows PowerShell profile. For more information, see about_Profiles. +- You can add any snap-in that has been registered by using the Microsoft .NET Framework install utility. 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 a list of snap-ins that are registered on your computer, type get-pssnapin -registered. +- Before adding a snap-in, Add-PSSnapin checks the version of the snap-in to verify that it is compatible with the current version of Windows PowerShell. If the snap-in fails the version check, Windows PowerShell reports an error. + ## RELATED LINKS [Get-PSSnapin](Get-PSSnapin.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Clear-History.md b/reference/3.0/Microsoft.PowerShell.Core/Clear-History.md index 9c5d6fb162c1..e691a6ed67db 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Clear-History.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Clear-History.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,61 +7,78 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135199 external help file: System.Management.Automation.dll-Help.xml title: Clear-History --- - # Clear-History + ## SYNOPSIS + Deletes entries from the command history. + ## SYNTAX ### IDParameter (Default) + ``` Clear-History [[-Id] ] [[-Count] ] [-Newest] [-WhatIf] [-Confirm] [] ``` ### CommandLineParameter + ``` Clear-History [-CommandLine ] [[-Count] ] [-Newest] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The Clear-History cmdlet deletes commands from the command history, that is, the list of commands entered during the current session. Without parameters, Clear-History deletes all commands from the session history, but you can use the parameters of Clear-History to delete selected commands. + ## EXAMPLES ### Example 1 + ``` -PS C:\> clear-history +PS> clear-history ``` Deletes all commands from the session history. + ### Example 2 + ``` -PS C:\> clear-history -id 23, 25 +PS> clear-history -id 23, 25 ``` Deletes the commands with history IDs 23 and 25. + ### Example 3 + ``` -PS C:\> clear-history -command *help*, *command +PS> clear-history -command *help*, *command ``` Deletes commands that include "help" or end in "command". + ### Example 4 + ``` -PS C:\> clear-history -count 10 -newest +PS> clear-history -count 10 -newest ``` Deletes the 10 newest commands from the history. + ### Example 5 + ``` -PS C:\> clear-history -id 10 -count 3 +PS> clear-history -id 10 -count 3 ``` Deletes the three oldest commands, beginning with the entry with ID 10. + ## PARAMETERS ### -CommandLine + Deletes commands with the specified text strings. If you enter more than one string, Clear-History deletes commands with any of the strings. @@ -78,6 +95,7 @@ Accept wildcard characters: True ``` ### -Count + Clears the specified number of history entries, beginning with the oldest entry in the history. If you use the Count and Id parameters in the same command, the cmdlet clears the number of entries specified by the Count parameter, beginning with the entry specified by the Id parameter. @@ -98,6 +116,7 @@ Accept wildcard characters: False ``` ### -Id + Deletes commands with the specified history IDs. To find the history ID of a command, use Get-History. @@ -115,6 +134,7 @@ Accept wildcard characters: False ``` ### -Newest + Deletes the newest entries in the history. By default, Clear-History deletes the oldest entries in the history. @@ -131,6 +151,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -146,6 +167,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -162,21 +184,29 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe objects to Clear-History. + ## OUTPUTS ### None + This cmdlet does not generate any output. + ## NOTES -* The session history is a list of the commands entered during the session. You can view the history, add and delete commands, and run commands from the history. For more information, see about_History. + +- The session history is a list of the commands entered during the session. You can view the history, add and delete commands, and run commands from the history. For more information, see about_History. Deleting a command from the history does not change the history IDs of the remaining items in the command history. -* +- + ## RELATED LINKS [Add-History](Add-History.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Connect-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Connect-PSSession.md index bd37872c7d58..99fed7e363bb 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Connect-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Connect-PSSession.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,23 +7,28 @@ online version: http://go.microsoft.com/fwlink/?LinkID=210604 external help file: System.Management.Automation.dll-Help.xml title: Connect-PSSession --- - # Connect-PSSession + ## SYNOPSIS + Reconnects to disconnected sessions + ## SYNTAX ### Name (Default) + ``` Connect-PSSession -Name [-ThrottleLimit ] [-WhatIf] [-Confirm] [] ``` ### Session + ``` Connect-PSSession [-Session] [-ThrottleLimit ] [-WhatIf] [-Confirm] [] ``` ### ComputerNameGuid + ``` Connect-PSSession [-ComputerName] [-ApplicationName ] [-ConfigurationName ] -InstanceId [-Credential ] [-Authentication ] @@ -32,6 +37,7 @@ Connect-PSSession [-ComputerName] [-ApplicationName ] [-Confi ``` ### ComputerName + ``` Connect-PSSession [-ComputerName] [-ApplicationName ] [-ConfigurationName ] [-Name ] [-Credential ] [-Authentication ] @@ -40,6 +46,7 @@ Connect-PSSession [-ComputerName] [-ApplicationName ] [-Confi ``` ### ConnectionUri + ``` Connect-PSSession [-ConfigurationName ] [-ConnectionUri] [-AllowRedirection] [-Name ] [-Credential ] [-Authentication ] [-CertificateThumbprint ] @@ -47,6 +54,7 @@ Connect-PSSession [-ConfigurationName ] [-ConnectionUri] [-Allow ``` ### ConnectionUriGuid + ``` Connect-PSSession [-ConfigurationName ] [-ConnectionUri] [-AllowRedirection] -InstanceId [-Credential ] [-Authentication ] @@ -55,16 +63,19 @@ Connect-PSSession [-ConfigurationName ] [-ConnectionUri] [-Allow ``` ### InstanceId + ``` Connect-PSSession -InstanceId [-ThrottleLimit ] [-WhatIf] [-Confirm] [] ``` ### Id + ``` Connect-PSSession [-ThrottleLimit ] [-Id] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Connect-PSSession** cmdlet reconnects to user-managed Windows PowerShell sessions ("PSSessions") that were disconnected. It works on sessions that are disconnected intentionally, such as by using the Disconnect-PSSession cmdlet or the **InDisconnectedSession** parameter of the Invoke-Command cmdlet, and those that were disconnected unintentionally, such as by a temporary network outage. @@ -76,11 +87,13 @@ Also you cannot connect sessions to sessions started by other users, unless you For more information about the Disconnected Sessions feature, see about_Remote_Disconnected_Sessions. This cmdlet is introduced in Windows PowerShell 3.0. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Connect-PSSession -ComputerName Server01 -Name ITTask +PS> Connect-PSSession -ComputerName Server01 -Name ITTask Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 4 ITTask Server01 Opened ITTasks Available @@ -90,23 +103,25 @@ This command reconnects to the ITTask session on the Server01 computer. The output shows that the command was successful. The **State** of the session is **Opened** and the **Availability** is **Available**, indicating that you can run commands in the session. + ### Example 2 + ``` -PS C:\> Get-PSSession +PS> Get-PSSession Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 Backups Localhost Opened Microsoft.PowerShell Available -PS C:\> Get-PSSession | Disconnect-PSSession +PS> Get-PSSession | Disconnect-PSSession Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 Backups Localhost Disconnected Microsoft.PowerShell None -PS C:\> Get-PSSession | Connect-PSSession +PS> Get-PSSession | Connect-PSSession Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ @@ -130,32 +145,34 @@ The output shows that the Backups session was reconnected. The **State** of the session is **Opened** and the **Availability** is **Available**. If you use the **Connect-PSSession** cmdlet on a session that is not disconnected, the command has no effect on the session and it does not generate any errors. + ### Example 3 + ``` The administrator begins by creating a sessions on a remote computer and running a script in the session.The first command uses the New-PSSession cmdlet to create the ITTask session on the Server01 remote computer. The command uses the **ConfigurationName** parameter to specify the ITTasks session configuration. The command saves the sessions in the $s variable. -PS C:\> $s = New-PSSession -ComputerName Server01 -Name ITTask -ConfigurationName ITTasks +PS> $s = New-PSSession -ComputerName Server01 -Name ITTask -ConfigurationName ITTasks The second command **Invoke-Command** cmdlet to start a background job in the session in the $s variable. It uses the **FilePath** parameter to run the script in the background job. -PS C:\> Invoke-Command -Session $s {Start-Job -FilePath \\Server30\Scripts\Backup-SQLDatabase.ps1} +PS> Invoke-Command -Session $s {Start-Job -FilePath \\Server30\Scripts\Backup-SQLDatabase.ps1} Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- 2 Job2 Running True Server01 \\Server30\Scripts\Backup... The third command uses the Disconnect-PSSession cmdlet to disconnect from the session in the $s variable. The command uses the **OutputBufferingMode** parameter with a value of **Drop** to prevent the script from being blocked by having to deliver output to the session. It uses the **IdleTimeoutSec** parameter to extend the session timeout to 15 hours.When the command completes, the administrator locks her computer and goes home for the evening. -PS C:\> Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15 +PS> Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15 Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 ITTask Server01 Disconnected ITTasks None Later that evening, the administrator starts her home computer, logs on to the corporate network, and starts Windows PowerShell. The fourth command uses the Get-PSSession cmdlet to get the sessions on the Server01 computer. The command finds the ITTask session.The fifth command uses the **Connect-PSSession** cmdlet to connect to the ITTask session. The command saves the session in the $s variable. -PS C:\> Get-PSSession -ComputerName Server01 -Name ITTask +PS> Get-PSSession -ComputerName Server01 -Name ITTask Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 ITTask Server01 Disconnected ITTasks None -PS C:\> $s = Connect-PSSession -ComputerName Server01 -Name ITTask +PS> $s = Connect-PSSession -ComputerName Server01 -Name ITTask Id Name ComputerName State ConfigurationName Availability @@ -165,18 +182,18 @@ Id Name ComputerName State ConfigurationName Availabil The sixth command uses the Invoke-Command cmdlet to run a Get-Job command in the session in the $s variable. The output shows that the job completed successfully.The seventh command uses the **Invoke-Command** cmdlet to run a Receive-Job command in the session in the $s variable in the session. The command saves the results in the $BackupSpecs variable.The eighth command uses the **Invoke-Command** cmdlet to runs another script in the session. The command uses the value of the $BackupSpecs variable in the session as input to the script. -PS C:\> Invoke-Command -Session $s {Get-Job} +PS> Invoke-Command -Session $s {Get-Job} Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- 2 Job2 Completed True Server01 \\Server30\Scripts\Backup... -PS C:\> Invoke-Command -Session $s {$BackupSpecs = Receive-Job -JobName Job2} +PS> Invoke-Command -Session $s {$BackupSpecs = Receive-Job -JobName Job2} -PS C:\> Invoke-Command -Session $s {\\Server30\Scripts\New-SQLDatabase.ps1 -InitData $BackupSpecs.Initialization} +PS> Invoke-Command -Session $s {\\Server30\Scripts\New-SQLDatabase.ps1 -InitData $BackupSpecs.Initialization} The ninth command disconnects from the session in the $s variable.The administrator closes Windows PowerShell and closes the computer. She can reconnect to the session on the next day and check the script status from her work computer. -PS C:\> Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15 +PS> Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15 Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 ITTask Server01 Disconnected ITTasks None @@ -186,9 +203,11 @@ This series of commands shows how the **Connect-PSSession** cmdlet might be used In this case, a system administrator starts a long-running job in a session on a remote computer. After starting the job, the administrator disconnects from the session and goes home. Later that evening, the administrator logs on to her home computer and verifies that the job ran to completion. + ## PARAMETERS ### -Authentication + Specifies the mechanism that is used to authenticate the user's credentials in the command to reconnect to the disconnected session. Valid values are **Default**, **Basic**, **Credssp**, **Digest**, **Kerberos**, **Negotiate**, and **NegotiateWithImplicitCredential**. The default value is **Default**. @@ -212,6 +231,7 @@ Accept wildcard characters: False ``` ### -CertificateThumbprint + Specifies the digital public key certificate (X509) of a user account that has permission to connect to the disconnected session. Enter the certificate thumbprint of the certificate. @@ -233,6 +253,7 @@ Accept wildcard characters: False ``` ### -ComputerName + Specifies the computers on which the disconnected sessions are stored. Sessions are stored on the computer that is at the "server-side" or receiving end of a connection. The default is the local computer. @@ -254,6 +275,7 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to connect to the disconnected session. The default is the current user. @@ -274,6 +296,7 @@ Accept wildcard characters: False ``` ### -Id + Specifies the IDs of the disconnected sessions. The ID parameter works only when the disconnected session was previously connected to the current session. @@ -292,6 +315,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Specifies the instance IDs of the disconnected sessions. The instance ID is a GUID that uniquely identifies a PSSession on a local or remote computer. @@ -311,6 +335,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the friendly names of the disconnected sessions. ```yaml @@ -338,6 +363,7 @@ Accept wildcard characters: False ``` ### -Port + Specifies the network port on the remote computer that is used to reconnect to the session. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). @@ -366,6 +392,7 @@ Accept wildcard characters: False ``` ### -Session + Specifies the disconnected sessions. Enter a variable that contains the PSSessions or a command that creates or gets the PSSessions, such as a Get-PSSession command. @@ -382,6 +409,7 @@ Accept wildcard characters: False ``` ### -SessionOption + Sets advanced options for the session. Enter a **SessionOption** object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. @@ -408,6 +436,7 @@ Accept wildcard characters: False ``` ### -ThrottleLimit + Specifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0, the default value, 32, is used. @@ -426,6 +455,7 @@ Accept wildcard characters: False ``` ### -UseSSL + Uses the Secure Sockets Layer (SSL) protocol to connect to the disconnected session. By default, SSL is not used. @@ -447,6 +477,7 @@ Accept wildcard characters: False ``` ### -AllowRedirection + Allows redirection of this connection to an alternate Uniform Resource Identifier (URI). When you use the **ConnectionURI** parameter, the remote destination can return an instruction to redirect to a different URI. @@ -469,6 +500,7 @@ Accept wildcard characters: False ``` ### -ApplicationName + Connects only to sessions that use the specified application. Enter the application name segment of the connection URI. @@ -491,6 +523,7 @@ Accept wildcard characters: False ``` ### -ConfigurationName + Connects only to sessions that use the specified session configuration. Enter a configuration name or the fully qualified resource URI for a session configuration. @@ -515,6 +548,7 @@ Accept wildcard characters: False ``` ### -ConnectionUri + Specifies the Uniform Resource Identifiers (URIs) of the connection endpoints for the disconnected sessions. The URI must be fully qualified. @@ -547,6 +581,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -562,6 +597,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -578,20 +614,27 @@ 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.Runspaces.PSSession + You can pipe a session (PSSession) to the **Connect-PSSession** cmdlet. + ## OUTPUTS ### System.Management.Automation.Runspaces.PSSession + **Connect-PSSession** returns an object that represents the session to which it reconnected. + ## NOTES -* **Connect-PSSession** reconnects only to sessions that are disconnected, that is, sessions that have a value of **Disconnected** for the **State** property. Only sessions that are connected to (terminate at) computers running Windows PowerShell 3.0 or later can be disconnected and reconnected. -* If you use the **Connect-PSSession** cmdlet on a session that is not disconnected, the command has no effect on the session and it does not generate errors. -* Disconnected loopback sessions with interactive tokens (those created with the **EnableNetworkAccess** parameter) can be reconnected only from the computer on which the session was created. This restriction protects the computer from malicious access. -* The value of the **State** property of a PSSession is relative to the current session. Therefore, a value of **Disconnected** means that the PSSession is not connected to the current session. However, it does not mean that the PSSession is disconnected from all sessions. It might be connected to a different session. To determine whether you can connect or reconnect to the session, use the **Availability** property. + +- **Connect-PSSession** reconnects only to sessions that are disconnected, that is, sessions that have a value of **Disconnected** for the **State** property. Only sessions that are connected to (terminate at) computers running Windows PowerShell 3.0 or later can be disconnected and reconnected. +- If you use the **Connect-PSSession** cmdlet on a session that is not disconnected, the command has no effect on the session and it does not generate errors. +- Disconnected loopback sessions with interactive tokens (those created with the **EnableNetworkAccess** parameter) can be reconnected only from the computer on which the session was created. This restriction protects the computer from malicious access. +- The value of the **State** property of a PSSession is relative to the current session. Therefore, a value of **Disconnected** means that the PSSession is not connected to the current session. However, it does not mean that the PSSession is disconnected from all sessions. It might be connected to a different session. To determine whether you can connect or reconnect to the session, use the **Availability** property. An **Availability** value of **None** indicates that you can connect to the session. A value of **Busy** indicates that you cannot connect to the PSSession because it is connected to another session. @@ -600,12 +643,13 @@ A value of **Busy** indicates that you cannot connect to the PSSession because i For more information about the values of the **Availability** property of sessions, see [RunspaceAvailability Enumeration](https://msdn.microsoft.com/library/system.management.automation.runspaces.runspaceavailability) in the MSDN library. -* You cannot change the idle timeout value of a PSSession when you connect to the PSSession. The **SessionOption** parameter of **Connect-PSSession** takes a **SessionOption** object that has an **IdleTimeout** value. However, the **IdleTimeout** value of the **SessionOption** object and the **IdleTimeout** value of the **$PSSessionOption** variable are ignored when connecting to a PSSession. +- You cannot change the idle timeout value of a PSSession when you connect to the PSSession. The **SessionOption** parameter of **Connect-PSSession** takes a **SessionOption** object that has an **IdleTimeout** value. However, the **IdleTimeout** value of the **SessionOption** object and the **IdleTimeout** value of the **$PSSessionOption** variable are ignored when connecting to a PSSession. You can set and change the idle timeout of a PSSession when you create the PSSession (by using the New-PSSession or Invoke-Command cmdlets) and when you disconnect from the PSSession. The **IdleTimeout** property of a PSSession is critical to disconnected sessions, because it determines how long a disconnected session is maintained on the remote computer. Disconnected sessions are considered to be idle from the moment that they are disconnected, even if commands are running in the disconnected session. + ## RELATED LINKS [Connect-PSSession](Connect-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Disable-PSRemoting.md b/reference/3.0/Microsoft.PowerShell.Core/Disable-PSRemoting.md index f51558c92d02..ac1a3f470101 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Disable-PSRemoting.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Disable-PSRemoting.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=144298 external help file: System.Management.Automation.dll-Help.xml title: Disable-PSRemoting --- - # Disable-PSRemoting + ## SYNOPSIS + Prevents remote users from running commands on the local computer. + ## SYNTAX ``` @@ -18,6 +20,7 @@ Disable-PSRemoting [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Disable-PSRemoting** cmdlet prevents users on other computers from running commands on the local computer. **Disable-PSRemoting** blocks remote access to all session configurations on the local computer. @@ -37,33 +40,39 @@ To run this cmdlet, start Windows PowerShell with the "Run as administrator" opt CAUTION: On systems that have both Windows PowerShell 3.0 and the Windows PowerShell 2.0 engine, do not use Windows PowerShell 2.0 to run the **Enable-PSRemoting** and Disable-PSRemoting cmdlets. The commands might appear to succeed, but the remoting is not configured correctly. Remote commands, and later attempts to enable and disable remoting, are likely to fail. + ## EXAMPLES ### Example 1 + ``` -C:\PS>Disable-PSRemoting +PS>Disable-PSRemoting ``` This command prevents remote access to all session configurations on the computer. + ### Example 2 + ``` -C:\PS>Disable-PSRemoting -Force +PS>Disable-PSRemoting -Force ``` This command prevents remote access all session configurations on the computer without prompting. + ### Example 3 + ``` -C:\PS>Disable-PSRemoting -Force +PS>Disable-PSRemoting -Force -[ADMIN] PS C:\> New-PSSession -ComputerName localhost +[ADMIN] PS> New-PSSession -ComputerName localhost Id Name ComputerName State Configuration Availability -- ---- ------------ ----- ------------- ------------ 1 Session1 Server02... Opened Microsoft.PowerShell Available # On Server02 remote computer: -PS C:\> New-PSSession -ComputerName Server01 +PS> New-PSSession -ComputerName Server01 [SERVER01] Connecting to remote server failed with the following error message : Access is denied. For more information, see the about_Remote_Troubleshooting Help topic. @@ -82,11 +91,13 @@ The command succeeds. The third command is run on the Server02 remote computer. The command uses the **New-PSSession** cmdlet to create a session to the Server01 remote computer. Because remote access is disabled, the command fails. + ### Example 4 + ``` -C:\PS>Disable-PSRemoting -force +PS>Disable-PSRemoting -force -[ADMIN] PS C:\> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Auto +[ADMIN] PS> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Auto Name Permission ---- ---------- @@ -97,11 +108,11 @@ microsoft.ServerManager NT AUTHORITY\NETWORK AccessDenied, BUILTIN\Adminis WithProfile NT AUTHORITY\NETWORK AccessDenied, BUILTIN\Administrators AccessAllowed -[ADMIN] PS C:\> Enable-PSRemoting -Force +[ADMIN] PS> Enable-PSRemoting -Force WinRM already is set up to receive requests on this machine. WinRM already is set up for remote management on this machine. -[ADMIN] PS C:\> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Auto +[ADMIN] PS> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Auto Name Permission ---- ---------- @@ -129,11 +140,13 @@ The command uses the **Force** parameter to suppress all user prompts and to res The fourth command uses the Get-PSSessionConfiguration and Format-Table cmdlets to display the names and permissions of the session configurations. The results show that the "AccessDenied" security descriptors have been removed from all session configurations. + ### Example 5 + ``` -C:\PS>Register-PSSessionConfiguration -Name Test -FilePath .\TestEndpoint.pssc -ShowSecurityDescriptorUI +PS>Register-PSSessionConfiguration -Name Test -FilePath .\TestEndpoint.pssc -ShowSecurityDescriptorUI -[ADMIN] PS C:\> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Wrap +[ADMIN] PS> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Wrap Name Permission ---- ---------- @@ -141,10 +154,10 @@ microsoft.powershell BUILTIN\Administrators AccessAllowed Test NT AUTHORITY\INTERACTIVE AccessAllowed, BUILTIN\Administrators AccessAllowed, DOMAIN01\User01 AccessAllowed -[ADMIN] PS C:\> Disable-PSRemoting -Force +[ADMIN] PS> Disable-PSRemoting -Force -[ADMIN] PS C:\> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Wrap +[ADMIN] PS> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Wrap Name Permission ---- ---------- @@ -154,7 +167,7 @@ BUILTIN\Administrators AccessAllowed, DOMAIN01\User01 AccessAllowed # Domain01\User01 -PS C:\> New-PSSession -ComputerName Server01 -ConfigurationName Test +PS> New-PSSession -ComputerName Server01 -ConfigurationName Test [Server01] Connecting to remote server failed with the following error message : Access is denied. For more information, see the about_Rem ote_Troubleshooting Help topic. + CategoryInfo : OpenError: (System.Manageme....RemoteRunspace:RemoteRunspace) [], PSRemotingTransportException @@ -177,12 +190,14 @@ The output shows that an AccessDenied security descriptor for all network users Although the other security desriptors are not changed, the "network_deny_all" security descriptor takes precedence. The fifth command shows that the **Disable-PSRemoting** command prevents even the Domain01\User01 user with special permissions to the Test session configuration from using the Test session configuration to connect to the computer remotely. + ### Example 6 + ``` -C:\PS>Disable-PSRemoting -Force +PS>Disable-PSRemoting -Force -[ADMIN] PS C:\> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Auto +[ADMIN] PS> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Auto Name Permission ---- ---------- @@ -192,9 +207,9 @@ microsoft.powershell32 NT AUTHORITY\NETWORK AccessDenied, BUILTIN\Adminis microsoft.ServerManager NT AUTHORITY\NETWORK AccessDenied, BUILTIN\Administrators AccessAllowed WithProfile NT AUTHORITY\NETWORK AccessDenied, BUILTIN\Administrators AccessAllowed -[ADMIN] PS C:\> Set-PSSessionConfiguration -Name Microsoft.ServerManager -AccessMode Remote -Force +[ADMIN] PS> Set-PSSessionConfiguration -Name Microsoft.ServerManager -AccessMode Remote -Force -[ADMIN] PS C:\> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Auto +[ADMIN] PS> Get-PSSessionConfiguration | Format-Table -Property Name, Permission -Auto Name Permission ---- ---------- @@ -218,9 +233,11 @@ You can also use the **AccessMode** parameter to enable Local access and to disa The fourth command uses the **Get-PSSessionConfiguration** and **Format-Table** cmdlets to display the session configurations and their properties. The output shows that the AccessDenied security descriptor for all network users is removed, thereby restoring remote access to the Microsoft.ServerManager session configuration. + ## PARAMETERS ### -Force + Suppresses all user prompts. By default, you are prompted to confirm each operation. @@ -237,6 +254,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -252,6 +270,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -268,17 +287,24 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### None + This cmdlet does not return any object. + ## NOTES -* Disabling the session configurations does not undo all the changes made by the Enable-PSRemoting or Enable-PSSessionConfiguration cmdlets. You might have to undo the following changes manually. + +- Disabling the session configurations does not undo all the changes made by the Enable-PSRemoting or Enable-PSSessionConfiguration cmdlets. You might have to undo the following changes manually. 1. Stop and disable the WinRM service. @@ -306,6 +332,7 @@ In Windows PowerShell 3.0, **Disable-PSRemoting** is the equivalent of "`Set-PSS In Windows PowerShell 2.0, **Disable-PSRemoting** is a function. Beginning in Windows PowerShell 3.0, it is a cmdlet. + ## RELATED LINKS [Disable-PSSessionConfiguration](Disable-PSSessionConfiguration.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Disable-PSSessionConfiguration.md b/reference/3.0/Microsoft.PowerShell.Core/Disable-PSSessionConfiguration.md index f18f315d1bb4..42dfc17be146 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Disable-PSSessionConfiguration.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Disable-PSSessionConfiguration.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=144299 external help file: System.Management.Automation.dll-Help.xml title: Disable-PSSessionConfiguration --- - # Disable-PSSessionConfiguration + ## SYNOPSIS + Disables session configurations on the local computer. + ## SYNTAX ``` @@ -18,6 +20,7 @@ Disable-PSSessionConfiguration [[-Name] ] [-Force] [-WhatIf] [-Confirm ``` ## DESCRIPTION + The **Disable-PSSessionConfiguration** cmdlet disables session configurations on the local computer, thereby preventing all users from using the session configurations to create a user-managed sessions ("PSSessions") on the local computer. This is an advanced cmdlet that is designed to be used by system administrators to manage customized session configurations for their users. @@ -29,39 +32,49 @@ Without parameters, **Disable-PSSessionConfiguration** disables the Microsoft.Po Unless the user specifies a different configuration, both local and remote users are effectively prevented from creating any sessions that connect to the computer. To disable all session configurations on the computer, use Disable-PSRemoting. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Disable-PSSessionConfiguration +PS> Disable-PSSessionConfiguration ``` This command disables the Microsoft.PowerShell session configuration. + ### Example 2 + ``` -PS C:\> Disable-PSSessionConfiguration -Name * +PS> Disable-PSSessionConfiguration -Name * ``` This command disables all registered session configurations on the computer. + ### Example 3 + ``` -PS C:\> Disable-PSSessionConfiguration -Name Microsoft* -Force +PS> Disable-PSSessionConfiguration -Name Microsoft* -Force ``` This command disables all session configurations that have names that begin with "Microsoft". The command uses the **Force** parameter to suppress all user prompts from the command. + ### Example 4 + ``` -PS C:\> Get-PSSessionConfiguration -Name MaintenanceShell, AdminShell | Disable-PSSessionConfiguration +PS> Get-PSSessionConfiguration -Name MaintenanceShell, AdminShell | Disable-PSSessionConfiguration ``` This command disables the MaintenanceShell and AdminShell session configurations. The command uses a pipeline operator (|) to send the results of a Get-PSSessionConfiguration command to Disable-PSSessionConfiguration. + ### Example 5 + ``` The first command uses the Get-PSSessionConfiguration and Format-Table cmdlets to display only the **Name** and **Permission** properties of the session configuration objects. This table format makes it easier to see the values of the objects. The results show that members of the Administrators group are permitted to use the session configurations. -PS C:\> Get-PSSessionConfiguration | format-table -property Name, Permission -auto +PS> Get-PSSessionConfiguration | format-table -property Name, Permission -auto Name Permission ---- ---------- @@ -71,10 +84,10 @@ microsoft.powershell32 BUILTIN\Administrators AccessAllowed The second command uses the **Disable-PSSessionConfiguration** cmdlet to disable the MaintenanceShell session configuration. The command uses the **Force** parameter to suppress all user prompts. -PS C:\> Disable-PSSessionConfiguration -name MaintenanceShell -force +PS> Disable-PSSessionConfiguration -name MaintenanceShell -force The third command repeats the first command. The results show that you can still get the object that represents the MaintenanceShell session configuration even though everyone is denied access to it. The "AccessDenied" entry takes precedence over all other entries in the security descriptor. -PS C:\> Get-PSSessionConfiguration | format-table -property Name, Permission -auto +PS> Get-PSSessionConfiguration | format-table -property Name, Permission -auto Name Permission ---- ---------- @@ -84,7 +97,7 @@ microsoft.powershell32 BUILTIN\Administrators AccessAllowed The fourth command uses the Set-PSSessionConfiguration cmdlet to increase the MaximumDataSizePerCommandMB setting on the MaintenanceShell session configuration to 60. The results show that the command was successful even though everyone is denied access to the configuration. -PS C:\> Set-PSSessionConfiguration -name MaintenanceShell -MaximumReceivedDataSizePerCommandMB 60 +PS> Set-PSSessionConfiguration -name MaintenanceShell -MaximumReceivedDataSizePerCommandMB 60 ParamName ParamValue --------- ---------- @@ -95,7 +108,7 @@ WinRM service need to be restarted to make the changes effective. Do you want to The fifth command attempts to use the MaintenanceShell session configuration in a session. It uses the New-PSSession cmdlet to create a new session and the ConfigurationName parameter to specify the MaintenanceShell configuration.The results show that the **New-PSSession** command fails because the user is denied access to the configuration. -PS C:\> new-pssession -computername localhost -configurationName MaintenanceShell +PS> new-pssession -computername localhost -configurationName MaintenanceShell [localhost] Connecting to remote server failed with the following error message : Access is denied. For more information, see the about_Remote_Troubl eshooting Help topic. + CategoryInfo : OpenError: (System.Manageme....RemoteRunspace:RemoteRunspace) [], PSRemotingTransportException @@ -103,9 +116,11 @@ eshooting Help topic. ``` This example shows the effect of disabling a session configuration. + ## PARAMETERS ### -Force + Suppresses all user prompts. By default, you are prompted to confirm each operation. @@ -122,6 +137,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the names of session configurations to disable. Enter one or more configuration names. Wildcards are permitted. @@ -142,6 +158,7 @@ Accept wildcard characters: True ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -157,6 +174,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -173,19 +191,27 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### Microsoft.PowerShell.Commands.PSSessionConfigurationCommands#PSSessionConfiguration, System.String + You can pipe a session configuration object or a string that contains the name of a session configuration to Disable-PSSessionConfiguration. + ## OUTPUTS ### None + This cmdlet does not return any objects. + ## NOTES -* To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, you must start Windows PowerShell with the "Run as administrator" option. -* +- To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, you must start Windows PowerShell with the "Run as administrator" option. + +- + ## RELATED LINKS [Disable-PSSessionConfiguration](Disable-PSSessionConfiguration.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Disconnect-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Disconnect-PSSession.md index 351f9ad5379b..ca1370388eff 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Disconnect-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Disconnect-PSSession.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=210605 external help file: System.Management.Automation.dll-Help.xml title: Disconnect-PSSession --- - # Disconnect-PSSession + ## SYNOPSIS + Disconnects from a session. + ## SYNTAX ### Session (Default) + ``` Disconnect-PSSession [-Session] [-IdleTimeoutSec ] [-OutputBufferingMode ] [-ThrottleLimit ] [-WhatIf] [-Confirm] @@ -21,24 +24,28 @@ Disconnect-PSSession [-Session] [-IdleTimeoutSec ] ``` ### Name + ``` Disconnect-PSSession [-IdleTimeoutSec ] [-OutputBufferingMode ] [-ThrottleLimit ] -Name [-WhatIf] [-Confirm] [] ``` ### InstanceId + ``` Disconnect-PSSession [-IdleTimeoutSec ] [-OutputBufferingMode ] [-ThrottleLimit ] -InstanceId [-WhatIf] [-Confirm] [] ``` ### Id + ``` Disconnect-PSSession [-IdleTimeoutSec ] [-OutputBufferingMode ] [-ThrottleLimit ] [-Id] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Disconnect-PSSession** cmdlet disconnects a Windows PowerShell session ("PSSession"), such as one started by using the New-PSSession cmdlet, from the current session. As a result, the PSSession is in a disconnected state. You can connect to the disconnected PSSession from the current session or from another session on the local computer or a different computer. @@ -55,11 +62,13 @@ To change the output buffering mode, use the **OutputBufferingMode** parameter Y For more information about the Disconnected Sessions feature, see about_Remote_Disconnected_Sessions. This cmdlet is introduced in Windows PowerShell 3.0. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Disconnect-PSSession -Name UpdateSession +PS> Disconnect-PSSession -Name UpdateSession Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 UpdateSession Server01 Disconnected Microsoft.PowerShell None @@ -70,9 +79,11 @@ The command uses the **Name** parameter to identify the PSSession. The output shows that the attempt to disconnect was successful. The session state is Disconnected and the Availability is None, which indicates that the session is not busy and can be reconnected. + ### Example 2 + ``` -PS C:\> Get-PSSession -ComputerName Server12 -Name ITTask | Disconnect-PSSession -OutputBufferingMode Drop -IdleTimeoutSec 86400 +PS> Get-PSSession -ComputerName Server12 -Name ITTask | Disconnect-PSSession -OutputBufferingMode Drop -IdleTimeoutSec 86400 Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 ITTask Server12 Disconnected ITTasks None @@ -88,21 +99,23 @@ Because the script writes its output to a report on a file share, other output c The command also uses the **IdleTimeoutSec** parameter to extend the idle timeout of the session to 24 hours. This setting allows time for this administrator or other administrators to reconnect to the session to verify that the script ran and troubleshoot if needed. + ### Example 3 + ``` The technician begins by creating sessions on several remote computers and running a script in each session.The first command uses the New-PSSession cmdlet to create the ITTask session on three remote computers. The command saves the sessions in the $s variable. The second command uses the **FilePath** parameter of the Invoke-Command cmdlet to run a script in the sessions in the $s variable. -PS C:\> $s = New-PSSession -ComputerName Srv1, Srv2, Srv30 -Name ITTask +PS> $s = New-PSSession -ComputerName Srv1, Srv2, Srv30 -Name ITTask -PS C:\> Invoke-Command $s -FilePath \\Server01\Scripts\Get-PatchStatus.ps1 +PS> Invoke-Command $s -FilePath \\Server01\Scripts\Get-PatchStatus.ps1 The script running on the Srv1 computer generates unexpected errors. The technician contacts his manager and asks for assistance. The manager directs the technician to disconnect from the session so he can investigate.The second command uses the Get-PSSession cmdlet to get the ITTask session on the Srv1 computer and the **Disconnect-PSSession** cmdlet to disconnect it. This command does not affect the ITTask sessions on the other computers. -PS C:\> Get-PSSession -Name ITTask -ComputerName Srv1 | Disconnect-PSSession +PS> Get-PSSession -Name ITTask -ComputerName Srv1 | Disconnect-PSSession Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 ITTask Srv1 Disconnected Microsoft.PowerShell None The third command uses the **Get-PSSession** cmdlet to get the ITTask sessions. The output shows that the ITTask sessions on the Srv2 and Srv30 computers were not affected by the command to disconnect. -PS C:\> Get-PSSession -ComputerName Srv1, Srv2, Srv30 -Name ITTask +PS> Get-PSSession -ComputerName Srv1, Srv2, Srv30 -Name ITTask Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 ITTask Srv1 Disconnected Microsoft.PowerShell None @@ -110,44 +123,46 @@ Id Name ComputerName State ConfigurationName Availabil 3 ITTask Srv30 Opened Microsoft.PowerShell Available The manager logs on to his home computer, connects to his corporate network, starts Windows PowerShell, and uses the Get-PSSession cmdlet to get the ITTask session on the Srv1 computer. He uses the credentials of the technician to access the session. -PS C:\> Get-PSSession -ComputerName Srv1 -Name ITTask -Credential Domain01\User01 +PS> Get-PSSession -ComputerName Srv1 -Name ITTask -Credential Domain01\User01 Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 ITTask Srv1 Disconnected Microsoft.PowerShell None Next, the manager uses the Connect-PSSession cmdlet to connect to the ITTask session on the Srv1 computer. The command saves the session in the $s variable. -PS C:\> $s = Connect-PSSession -ComputerName Srv1 -Name ITTask -Credential Domain01\User01 +PS> $s = Connect-PSSession -ComputerName Srv1 -Name ITTask -Credential Domain01\User01 The manager uses the Invoke-Command cmdlet to run some diagnostic commands in the session in the $s variable. He recognizes that the script failed because it did not find a required directory. The manager uses the MkDir function to create the directory, and then he restarts the Get-PatchStatus.ps1 script and disconnects from the session.The manager reports his findings to the technician, suggests that he reconnect to the session to complete the tasks, and asks him to add a command to the Get-PatchStatus.ps1 script that creates the required directory if it does not exist. -PS C:\> Invoke-Command -Session $s {dir $home\Scripts\PatchStatusOutput.ps1} +PS> Invoke-Command -Session $s {dir $home\Scripts\PatchStatusOutput.ps1} -PS C:\> Invoke-Command -Session $s {mkdir $home\Scripts\PatchStatusOutput} +PS> Invoke-Command -Session $s {mkdir $home\Scripts\PatchStatusOutput} -PS C:\> Invoke-Command -Session $s -FilePath \\Server01\Scripts\Get-PatchStatus.ps1 +PS> Invoke-Command -Session $s -FilePath \\Server01\Scripts\Get-PatchStatus.ps1 -PS C:\> Disconnect-PSSession -Session $s +PS> Disconnect-PSSession -Session $s ``` This series of commands shows how the **Disconnect-PSSession** cmdlet might be used in an enterprise scenario. In this case, a new technician starts a script in a session on a remote computer and runs into a problem. The technician disconnects from the session so that a more experienced manager can connect to the session and resolve the problem. + ### Example 4 + ``` The first command uses the New-PSSessionOption cmdlet to create a session option object. It uses the **IdleTimeout** parameter to set an idle timeout of 48 hours (172800000 milliseconds). The command saves the session option object in the $Timeout variable. -PS C:\> $Timeout = New-PSSessionOption -IdleTimeout 172800000 +PS> $Timeout = New-PSSessionOption -IdleTimeout 172800000 The second command uses the New-PSSession cmdlet to create the ITTask session on the Server01 computer. The command save the session in the $s variable. The value of the **SessionOption** parameter is the 48-hour idle timeout in the $Timeout variable. -PS C:\> $s = New-PSSession -Computer Server01 -Name ITTask -SessionOption $Timeout +PS> $s = New-PSSession -Computer Server01 -Name ITTask -SessionOption $Timeout The third command disconnects the ITTask session in the $s variable. The command fails because the idle timeout value of the session exceeds the **MaxIdleTimeoutMs** quota in the session configuration. Because the idle timeout is not used until the session is disconnected, this violation can go undetected while the session is in use. -PS C:\> Disconnect-PSSession -Session $s +PS> Disconnect-PSSession -Session $s Disconnect-PSSession : The session ITTask cannot be disconnected because the specified idle timeout value 172800(seconds) is either greater than the server maximum allowed 43200 (seconds) or less that the minimum allowed60(seconds). Choose an idle time out value that is within the allowed range and try again. The fourth command uses the Invoke-Command cmdlet to run a Get-PSSessionConfiguration command for the Microsoft.PowerShell session configuration on the Server01 computer. The command uses the Format-List cmdlet to display all properties of the session configuration in a list.The output shows that the **MaxIdleTimeoutMS** property, which establishes the maximum permitted **IdleTimeout** value for sessions that use the session configuration, is 43200000 milliseconds (12 hours). -PS C:\> Invoke-Command -ComputerName Server01 {Get-PSSessionConfiguration Microsoft.PowerShell} | Format-List -Property * +PS> Invoke-Command -ComputerName Server01 {Get-PSSessionConfiguration Microsoft.PowerShell} | Format-List -Property * Architecture : 64 Filename : %windir%\system32\pwrshplugin.dll ResourceUri : http://schemas.microsoft.com/powershell/microsoft.powershell @@ -185,7 +200,7 @@ PSShowComputerName : True The fifth command gets the session option values of the session in the $s variable. The values of many session options are properties of the **ConnectionInfo** property of the **Runspace** property of the session.The output shows that the value of the **IdleTimeout** property of the session is 172800000 milliseconds (48 hours), which violates the **MaxIdleTimeoutMs** quota of 12 hours in the session configuration.To resolve this conflict, you can use the **ConfigurationName** parameter to select a different session configuration or use the **IdleTimeout** parameter to reduce the idle timeout of the session. -PS C:\> $s.Runspace.ConnectionInfo +PS> $s.Runspace.ConnectionInfo ConnectionUri : http://Server01/wsman ComputerName : Server01 Scheme : http @@ -218,13 +233,13 @@ OperationTimeout : 180000 IdleTimeout : 172800000 The sixth command disconnects the session. It uses the **IdleTimeoutSec** parameter to set the idle timeout to the 12-hour maximum. -PS C:\> Disconnect-PSSession $s -IdleTimeoutSec 43200 +PS> Disconnect-PSSession $s -IdleTimeoutSec 43200 Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 4 ITTask Server01 Disconnected Microsoft.PowerShell None The seventh command gets the value of the **IdleTimeout** property of the disconnected session, which is measured in milliseconds. The output confirms that the command was successful. -PS C:\> $s.Runspace.ConnectionInfo.IdleTimeout +PS> $s.Runspace.ConnectionInfo.IdleTimeout 43200000 ``` @@ -234,9 +249,11 @@ The idle timeout property of a session is critical to disconnected sessions, bec You can set the idle timeout option when you create a session and when you disconnect it. The default values for the idle timeout of a session are set in the **$PSSessionOption** preference variable on the local computer and in the session configuration on the remote computer. Values set for the session take precedence over values set in the session configuration, but session values cannot exceed quotas set in the session configuration, such as the **MaxIdleTimeoutMs** value. + ## PARAMETERS ### -Id + Disconnects from sessions with the specified session ID. Type one or more IDs (separated by commas), or use the range operator (..) to specify a range of IDs. @@ -256,6 +273,7 @@ Accept wildcard characters: False ``` ### -IdleTimeoutSec + Changes the idle timeout value of the disconnected PSSession. Enter a value in seconds. The minimum value is 60 (1 minute). @@ -285,6 +303,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Disconnects from sessions with the specified instance IDs. The instance ID is a GUID that uniquely identifies a session on a local or remote computer. @@ -306,6 +325,7 @@ Accept wildcard characters: False ``` ### -Name + Disconnects from sessions with the specified friendly names. Wildcards are permitted. @@ -325,6 +345,7 @@ Accept wildcard characters: False ``` ### -Session + Disconnects from the specified PSSessions. Enter PSSession objects, such as those that the New-PSSession cmdlet returns. You can also pipe a PSSession object to Disconnect-PSSession. @@ -346,6 +367,7 @@ Accept wildcard characters: False ``` ### -ThrottleLimit + Sets the throttle limit for the **Disconnect-PSSession** command. The throttle limit is the maximum number of concurrent connections that can be established to run this command. @@ -366,6 +388,7 @@ Accept wildcard characters: False ``` ### -OutputBufferingMode + Determines how command output is managed in the disconnected session when the output buffer is full. The default value is **Block**. @@ -393,6 +416,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -408,6 +432,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -424,20 +449,27 @@ 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.Runspaces.PSSession + You can pipe a session to **Disconnect-PSSession**. + ## OUTPUTS ### System.Management.Automation.Runspaces.PSSession + **Disconnect-PSSession** returns an object that represents the session that it disconnected. + ## NOTES -* The **Disconnect-PSSession** cmdlet works only when the local and remote computers are running Windows PowerShell 3.0 or later versions of Windows PowerShell. -* If you use the **Disconnect-PSSession** cmdlet on a disconnected session, the command has no effect on the session and it does not generate errors. -* Disconnected loopback sessions with interactive security tokens (those created with the **EnableNetworkAccess** parameter) can be reconnected only from the computer on which the session was created. This restriction protects the computer from malicious access. -* When you disconnect a PSSession, the session state is **Disconnected** and the availability is **None**. + +- The **Disconnect-PSSession** cmdlet works only when the local and remote computers are running Windows PowerShell 3.0 or later versions of Windows PowerShell. +- If you use the **Disconnect-PSSession** cmdlet on a disconnected session, the command has no effect on the session and it does not generate errors. +- Disconnected loopback sessions with interactive security tokens (those created with the **EnableNetworkAccess** parameter) can be reconnected only from the computer on which the session was created. This restriction protects the computer from malicious access. +- When you disconnect a PSSession, the session state is **Disconnected** and the availability is **None**. The value of the **State** property is relative to the current session. Therefore, a value of **Disconnected** means that the PSSession is not connected to the current session. diff --git a/reference/3.0/Microsoft.PowerShell.Core/Enable-PSRemoting.md b/reference/3.0/Microsoft.PowerShell.Core/Enable-PSRemoting.md index 944783548098..26070278d8a5 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Enable-PSRemoting.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Enable-PSRemoting.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=144300 external help file: System.Management.Automation.dll-Help.xml title: Enable-PSRemoting --- - # Enable-PSRemoting + ## SYNOPSIS + Configures the computer to receive remote commands. + ## SYNTAX ``` @@ -18,6 +20,7 @@ Enable-PSRemoting [-Force] [-SkipNetworkProfileCheck] [-WhatIf] [-Confirm] [ Enable-PSRemoting +PS> Enable-PSRemoting ``` This command configures the computer to receive remote commands. + ### Example 2 + ``` -PS C:\> Enable-PSRemoting -Force +PS> Enable-PSRemoting -Force ``` This command configures the computer to receive remote commands. It uses the Force parameter to suppress the user prompts. + ### Example 3 + ``` -PS C:\> Enable-PSRemoting -SkipNetworkProfileCheck -Force +PS> Enable-PSRemoting -SkipNetworkProfileCheck -Force -PS C:\> Set-NetFirewallRule -Name "WINRM-HTTP-In-TCP-PUBLIC" -RemoteAddress Any +PS> Set-NetFirewallRule -Name "WINRM-HTTP-In-TCP-PUBLIC" -RemoteAddress Any ``` This example shows how to allow remote access from public networks on client versions of Windows. @@ -82,9 +91,11 @@ The **SkipNetworkProfileCheck** parameter has no effect on server version of Win The second command eliminates the subnet restriction. The command uses the **Set-NetFirewallRule** cmdlet in the **NetSecurity** module to add a firewall rule that allows remote access from public networks from any remote location, including locations in different subnets. + ## PARAMETERS ### -Force + Suppresses all user prompts. By default, you are prompted to confirm each operation. @@ -101,6 +112,7 @@ Accept wildcard characters: False ``` ### -SkipNetworkProfileCheck + Enables remoting on client versions of Windows when the computer is on a public network. This parameter enables a firewall rule for public networks that allows remote access only from computers in the same local subnet. @@ -125,6 +137,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -140,6 +153,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -156,17 +170,24 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### System.String + Enable-PSRemoting returns strings that describe its results. + ## NOTES -* In Windows PowerShell 3.0, **Enable-PSRemoting** creates the following firewall exceptions for WS-Management communications. + +- In Windows PowerShell 3.0, **Enable-PSRemoting** creates the following firewall exceptions for WS-Management communications. On server versions of Windows, **Enable-PSRemoting** creates firewall rules for private and domain networks that allow remote access, and creates a firewall rule for public networks that allows remote access only from computers in the same local subnet. @@ -175,7 +196,7 @@ To create a firewall rule for public networks that allows remote access from the On client or server versions of Windows, to create a firewall rule for public networks that removes the local subnet restriction and allows remote access , use the **Set-NetFirewallRule** cmdlet in the NetSecurity module to run the following command: `Set-NetFirewallRule -Name "WINRM-HTTP-In-TCP-PUBLIC" -RemoteAddress Any` -* In Windows PowerShell 2.0, **Enable-PSRemoting** creates the following firewall exceptions for WS-Management communications. +- In Windows PowerShell 2.0, **Enable-PSRemoting** creates the following firewall exceptions for WS-Management communications. On server versions of Windows, it creates firewall rules for all networks that allow remote access. @@ -183,8 +204,9 @@ To create a firewall rule for public networks that allows remote access from the To minimize security risks, **Enable-PSRemoting** does not create a firewall rule for public networks on client versions of Windows. When the current network location is public, **Enable-PSRemoting** returns the following message: "Unable to check the status of the firewall." -* Beginning in Windows PowerShell 3.0, **Enable-PSRemoting** enables all session configurations by setting the value of the **Enabled** property of all session configurations (WSMan:\\\\Plugin\\\\Enabled) to True ($true). -* In Windows PowerShell 2.0, **Enable-PSRemoting** removes the Deny_All setting from the security descriptor of session configurations. In Windows PowerShell 3.0, **Enable-PSRemoting** removes the Deny_All and Network_Deny_All settings, thereby providing remote access to session configurations that were reserved for local use. +- Beginning in Windows PowerShell 3.0, **Enable-PSRemoting** enables all session configurations by setting the value of the **Enabled** property of all session configurations (WSMan:\\\\Plugin\\\\Enabled) to True ($true). +- In Windows PowerShell 2.0, **Enable-PSRemoting** removes the Deny_All setting from the security descriptor of session configurations. In Windows PowerShell 3.0, **Enable-PSRemoting** removes the Deny_All and Network_Deny_All settings, thereby providing remote access to session configurations that were reserved for local use. + ## RELATED LINKS [Disable-PSSessionConfiguration](Disable-PSSessionConfiguration.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Enable-PSSessionConfiguration.md b/reference/3.0/Microsoft.PowerShell.Core/Enable-PSSessionConfiguration.md index 8fb11f4884bc..bbc67be35325 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Enable-PSSessionConfiguration.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Enable-PSSessionConfiguration.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=144301 external help file: System.Management.Automation.dll-Help.xml title: Enable-PSSessionConfiguration --- - # Enable-PSSessionConfiguration + ## SYNOPSIS + Enables the session configurations on the local computer. + ## SYNTAX ``` @@ -19,6 +21,7 @@ Enable-PSSessionConfiguration [[-Name] ] [-Force] [-SecurityDescriptor ``` ## DESCRIPTION + The **Enable-PSSessionConfiguration** cmdlet enables registered session configurations that have been disabled, such as by using the Disable-PSSessionConfiguration or Disable-PSRemoting cmdlets, or the **AccessMode** parameter of Register-PSSessionConfiguration. This is an advanced cmdlet that is designed to be used by system administrators to manage customized session configurations for their users. @@ -31,39 +34,49 @@ However, **Enable-PSSessionConfiguration** does not remove or change the "Netwo The **Enable-PSSessionConfiguration** cmdlet calls the **Set-WSManQuickConfig** cmdlet. However, it should not be used to enable remoting on the computer. Instead, use the more comprehensive cmdlet, Enable-PSRemoting. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Enable-PSSessionConfiguration +PS> Enable-PSSessionConfiguration ``` This command re-enables the Microsoft.PowerShell default session configuration on the computer. + ### Example 2 + ``` -PS C:\> Enable-PSSessionConfiguration -name MaintenanceShell, AdminShell +PS> Enable-PSSessionConfiguration -name MaintenanceShell, AdminShell ``` This command re-enables the MaintenanceShell and AdminShell session configurations on the computer. + ### Example 3 + ``` -PS C:\> Enable-PSSessionConfiguration -name * -PS C:\> Get-PSSessionConfiguration | Enable-PSSessionConfiguration +PS> Enable-PSSessionConfiguration -name * +PS> Get-PSSessionConfiguration | Enable-PSSessionConfiguration ``` These commands re-enable all session configurations on the computer. The commands are equivalent, so you can use either one. Enable-PSSessionConfiguration does not generate an error if you enable a session configuration that is already enabled. + ### Example 4 + ``` -PS C:\> Enable-PSSessionConfiguration -name MaintenanceShell -securityDescriptorSDDL "O:NSG:BAD:P(A;;GXGWGR;;;BA)(A;;GAGR;;;S-1-5-21-123456789-188441444-3100496)S:P" +PS> Enable-PSSessionConfiguration -name MaintenanceShell -securityDescriptorSDDL "O:NSG:BAD:P(A;;GXGWGR;;;BA)(A;;GAGR;;;S-1-5-21-123456789-188441444-3100496)S:P" ``` This command re-enables the MaintenanceShell session configuration and specifies a new security descriptor for the configuration. + ## PARAMETERS ### -Force + Suppresses all user prompts, and restarts the WinRM service without prompting. Restarting the service makes the configuration change effective. @@ -82,6 +95,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the names of session configurations to enable. Enter one or more configuration names. Wildcards are permitted. @@ -103,6 +117,7 @@ Accept wildcard characters: True ``` ### -SecurityDescriptorSddl + Replaces the security descriptor on the session configuration with the specified security descriptor. If you omit this parameter, Enable-PSSessionConfiguration just deletes the "deny all" item from the security descriptor. @@ -120,6 +135,7 @@ Accept wildcard characters: False ``` ### -SkipNetworkProfileCheck + Enables the session configuration when the computer is on a public network. This parameter enables a firewall rule for public networks that allows remote access only from computers in the same local subnet. By default, **Enable-PSSessionConfiguration** fails on a public network. @@ -146,6 +162,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -161,6 +178,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -177,19 +195,27 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### Microsoft.PowerShell.Commands.PSSessionConfigurationCommands#PSSessionConfiguration, System.String + You can pipe a session configuration object or a string that contains the name of a session configuration to Enable-PSSessionConfiguration. + ## OUTPUTS ### None + This cmdlet does not return any objects. + ## NOTES -* To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, you must start Windows PowerShell with the "Run as administrator" option. -* +- To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, you must start Windows PowerShell with the "Run as administrator" option. + +- + ## RELATED LINKS [Disable-PSSessionConfiguration](Disable-PSSessionConfiguration.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Enter-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Enter-PSSession.md index 4ab76e56560e..719e6a27b9f8 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Enter-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Enter-PSSession.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135210 external help file: System.Management.Automation.dll-Help.xml title: Enter-PSSession --- - # Enter-PSSession + ## SYNOPSIS + Starts an interactive session with a remote computer. + ## SYNTAX ### ComputerName (Default) + ``` Enter-PSSession [-ComputerName] [-EnableNetworkAccess] [-Credential ] [-Port ] [-UseSSL] [-ConfigurationName ] [-ApplicationName ] [-SessionOption ] @@ -21,11 +24,13 @@ Enter-PSSession [-ComputerName] [-EnableNetworkAccess] [-Credential ] [] ``` ### Uri + ``` Enter-PSSession [[-ConnectionUri] ] [-EnableNetworkAccess] [-Credential ] [-ConfigurationName ] [-AllowRedirection] [-SessionOption ] @@ -33,21 +38,25 @@ Enter-PSSession [[-ConnectionUri] ] [-EnableNetworkAccess] [-Credential ] [] ``` ### Id + ``` Enter-PSSession [[-Id] ] [] ``` ### Name + ``` Enter-PSSession [-Name ] [] ``` ## DESCRIPTION + The **Enter-PSSession** cmdlet starts an interactive session with a single remote computer. During the session, the commands that you type run on the remote computer, just as though you were typing directly on the remote computer. You can have only one interactive session at a time. @@ -57,60 +66,70 @@ However, you can also use a session that you create by using the New-PSSession c However, you cannot use the Disconnect-PSSession, Connect-PSSession, or Receive-PSSession cmdlets to disconnect from or re-connect to an interactive session. To end the interactive session and disconnect from the remote computer, use the Exit-PSSession cmdlet, or type "exit". + ## EXAMPLES ### Example 1 + ``` -PS C:\> Enter-PSSession -[localhost]: PS C:\> +PS> Enter-PSSession +[localhost]: PS> ``` This command starts an interactive session on the local computer. The command prompt changes to indicate that you are now running commands in a different session. The commands that you enter run in the new session, and the results are returned to the default session as text. + ### Example 2 + ``` The first command uses the Enter-PSSession cmdlet to start an interactive session with Server01, a remote computer. When the session starts, the command prompt changes to include the computer name. -PS C:\> Enter-PSSession -Computer Server01 -[Server01]: PS C:\> +PS> Enter-PSSession -Computer Server01 +[Server01]: PS> The second command gets the PowerShell process and redirects the output to the Process.txt file. The command is submitted to the remote computer, and the file is saved on the remote computer. -[Server01]: PS C:\> Get-Process Powershell > C:\ps-test\Process.txt +[Server01]: PS> Get-Process Powershell > C:\ps-test\Process.txt The third command uses the Exit keyword to end the interactive session and close the connection. -[Server01]: PS C:\> exit -PS C:\> +[Server01]: PS> exit +PS> The fourth command confirms that the Process.txt file is on the remote computer. A Get-ChildItem ("dir") command on the local computer cannot find the file. -PS C:\> dir C:\ps-test\process.txt +PS> dir C:\ps-test\process.txt Get-ChildItem : Cannot find path 'C:\ps-test\process.txt' because it does not exist. At line:1 char:4 + dir <<<< c:\ps-test\process.txt ``` This command shows how to work in an interactive session with a remote computer. + ### Example 3 + ``` -PS C:\> $s = New-PSSession -ComputerName Server01 -PS C:\> Enter-PSSession -Session $s -[Server01]: PS C:\> +PS> $s = New-PSSession -ComputerName Server01 +PS> Enter-PSSession -Session $s +[Server01]: PS> ``` These commands use the Session parameter of Enter-PSSession to run the interactive session in an existing Windows PowerShell session (PSSession). + ### Example 4 + ``` -PS C:\> Enter-PSSession -ComputerName Server01 -Port 90 -Credential Domain01\User01 -[Server01]: PS C:\> +PS> Enter-PSSession -ComputerName Server01 -Port 90 -Credential Domain01\User01 +[Server01]: PS> ``` This command starts an interactive session with the Server01 computer. It uses the Port parameter to specify the port and the Credential parameter to specify the account of a user with permission to connect to the remote computer. + ### Example 5 + ``` -PS C:\> Enter-PSSession -ComputerName Server01 -[Server01]: PS C:\> Exit-PSSession -PS C:\> +PS> Enter-PSSession -ComputerName Server01 +[Server01]: PS> Exit-PSSession +PS> ``` This example shows how to start and stop an interactive session. @@ -119,9 +138,11 @@ The first command uses the Enter-PSSession cmdlet to start an interactive sessio The second command uses the Exit-PSSession cmdlet to end the session. You can also use the Exit keyword to end the interactive session. Exit-PSSession and Exit have the same effect. + ## PARAMETERS ### -AllowRedirection + Allows redirection of this connection to an alternate Uniform Resource Identifier (URI). By default, redirection is not allowed. @@ -145,6 +166,7 @@ Accept wildcard characters: False ``` ### -ApplicationName + Specifies the application name segment of the connection URI. Use this parameter to specify the application name when you are not using the ConnectionURI parameter in the command. @@ -169,6 +191,7 @@ Accept wildcard characters: False ``` ### -Authentication + Specifies the mechanism that is used to authenticate the user's credentials. Valid values are "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate", and "NegotiateWithImplicitCredential". The default value is "Default". @@ -194,6 +217,7 @@ Accept wildcard characters: False ``` ### -CertificateThumbprint + Specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate. @@ -215,6 +239,7 @@ Accept wildcard characters: False ``` ### -ComputerName + Starts an interactive session with the specified remote computer. Enter only one computer name. The default is the local computer. @@ -241,6 +266,7 @@ Accept wildcard characters: False ``` ### -ConfigurationName + Specifies the session configuration that is used for the interactive session. Enter a configuration name or the fully qualified resource URI for a session configuration. @@ -266,6 +292,7 @@ Accept wildcard characters: False ``` ### -ConnectionUri + Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint for the session. The URI must be fully qualified. The format of this string is as follows: @@ -297,6 +324,7 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. @@ -317,6 +345,7 @@ Accept wildcard characters: False ``` ### -EnableNetworkAccess + Adds an interactive security token to loopback sessions. The interactive token lets you run commands in the loopback session that get data from other computers. For example, you can run a command in the session that copies XML files from a remote computer to the local computer. @@ -346,6 +375,7 @@ Accept wildcard characters: False ``` ### -Id + Specifies the ID of an existing session. Enter-PSSession uses the specified session for the interactive session. @@ -364,6 +394,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Specifies the instance ID of an existing session. Enter-PSSession uses the specified session for the interactive session. @@ -385,6 +416,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the friendly name of an existing session. Enter-PSSession uses the specified session for the interactive session. @@ -407,6 +439,7 @@ Accept wildcard characters: False ``` ### -Port + Specifies the network port on the remote computer used for this command. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). @@ -437,6 +470,7 @@ Accept wildcard characters: False ``` ### -Session + Specifies a Windows PowerShell session (PSSession) to use for the interactive session. This parameter takes a session object. You can also use the Name, InstanceID, or ID parameters to specify a PSSession. @@ -461,6 +495,7 @@ Accept wildcard characters: False ``` ### -SessionOption + Sets advanced options for the session. Enter a **SessionOption** object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. @@ -487,6 +522,7 @@ Accept wildcard characters: False ``` ### -UseSSL + Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used. @@ -508,23 +544,31 @@ 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 or System.Management.Automation.Runspaces.PSSession + You can pipe a computer name (a string) or a session object to Enter-PSSession. + ## OUTPUTS ### None + The cmdlet does not return any output. + ## NOTES -* To connect to a remote computer, you must be a member of the Administrators group on the remote computer. -* In Windows Vista and later versions of Windows, to start an interactive session on the local computer, you must start Windows PowerShell with the "Run as administrator" option. -* When you use Enter-PSSession, your user profile on the remote computer is used for the interactive session. The commands in the remote user profile, including commands to add Windows PowerShell snap-ins and to change the command prompt, run before the remote prompt is displayed. -* Enter-PSSession uses the UI culture setting on the local computer for the interactive session. To find the local UI culture, use the $UICulture automatic variable. -* Enter-PSSession requires the Get-Command, Out-Default, and Exit-PSSession cmdlets. If these cmdlets are not included in the session configuration on the remote computer, the Enter-PSSession commands fails. -* Unlike Invoke-Command, which parses and interprets the commands before sending them to the remote computer, Enter-PSSession sends the commands directly to the remote computer without interpretation. -* If the session that you want to enter is busy processing a command, there might be a delay before Windows PowerShell responds to the Enter-PSSession command. You will be connected as soon as the session is available. To cancel the Enter-PSSession command, press CTRL+C. + +- To connect to a remote computer, you must be a member of the Administrators group on the remote computer. +- In Windows Vista and later versions of Windows, to start an interactive session on the local computer, you must start Windows PowerShell with the "Run as administrator" option. +- When you use Enter-PSSession, your user profile on the remote computer is used for the interactive session. The commands in the remote user profile, including commands to add Windows PowerShell snap-ins and to change the command prompt, run before the remote prompt is displayed. +- Enter-PSSession uses the UI culture setting on the local computer for the interactive session. To find the local UI culture, use the $UICulture automatic variable. +- Enter-PSSession requires the Get-Command, Out-Default, and Exit-PSSession cmdlets. If these cmdlets are not included in the session configuration on the remote computer, the Enter-PSSession commands fails. +- Unlike Invoke-Command, which parses and interprets the commands before sending them to the remote computer, Enter-PSSession sends the commands directly to the remote computer without interpretation. +- If the session that you want to enter is busy processing a command, there might be a delay before Windows PowerShell responds to the Enter-PSSession command. You will be connected as soon as the session is available. To cancel the Enter-PSSession command, press CTRL+C. + ## RELATED LINKS [Exit-PSSession](Exit-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Exit-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Exit-PSSession.md index f451c109c193..81c836915df4 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Exit-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Exit-PSSession.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135212 external help file: System.Management.Automation.dll-Help.xml title: Exit-PSSession --- - # Exit-PSSession + ## SYNOPSIS + Ends an interactive session with a remote computer. + ## SYNTAX ``` @@ -18,26 +20,31 @@ Exit-PSSession [] ``` ## DESCRIPTION + The Exit-PSSession cmdlet ends interactive sessions that you started by using Enter-PSSession. You can also use the Exit keyword to end an interactive session. The effect is the same as using Exit-PSSession. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Enter-PSSession -computername Server01 +PS> Enter-PSSession -computername Server01 Server01\PS> Exit-PSSession -PS C:\> +PS> ``` These commands start and then stop an interactive session with the Server01 remote computer. + ### Example 2 + ``` -PS C:\> $s = new-pssession -computername Server01 -PS C:\> Enter-PSSession -session $s +PS> $s = new-pssession -computername Server01 +PS> Enter-PSSession -session $s Server01\PS> Exit-PSSession -PS C:\> $s +PS> $s Id Name ComputerName State ConfigurationName -- ---- ------------ ----- ----------------- 1 Session1 Server01 Opened Microsoft.PowerShell @@ -57,31 +64,42 @@ The third command uses the Exit-PSSession cmdlet to stop the interactive session The final command displays the PSSession in the $s variable. The State property shows the PSSession is still open and available for use. + ### Example 3 + ``` -PS C:\> Enter-PSSession -computername Server01 +PS> Enter-PSSession -computername Server01 Server01\PS> exit -PS C:\> +PS> ``` This command uses the Exit keyword to stop an interactive session started by using the Enter-PSSession cmdlet. The Exit keyword has the same effect as using Exit-PSSession. + ## PARAMETERS ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe objects to Exit-PSSession. + ## OUTPUTS ### None + This cmdlet does not return any output. + ## NOTES -* This cmdlet takes only the common parameters. -* +- This cmdlet takes only the common parameters. + +- + ## RELATED LINKS [Connect-PSSession](Connect-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Export-Console.md b/reference/3.0/Microsoft.PowerShell.Core/Export-Console.md index da2bd55fad4e..0a5684768fe2 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Export-Console.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Export-Console.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113298 external help file: System.Management.Automation.dll-Help.xml title: Export-Console --- - # Export-Console + ## SYNOPSIS + Exports the names of snap-ins in the current session to a console file. + ## SYNTAX ``` @@ -18,34 +20,41 @@ Export-Console [[-Path] ] [-Force] [-NoClobber] [-WhatIf] [-Confirm] [ export-console -path $pshome\Consoles\ConsoleS1.psc1 +PS> export-console -path $pshome\Consoles\ConsoleS1.psc1 ``` This command exports the names of Windows PowerShell snap-ins in the current session to the ConsoleS1.psc1 file in the Consoles subdirectory of the Windows PowerShell installation directory, $pshome. + ### Example 2 + ``` -PS C:\> export-console +PS> export-console ``` This command exports the names of Windows PowerShell snap-ins from current session to the Windows PowerShell console file that was most recently used in the current session. It overwrites the previous file contents. If you have not exported a console file during the current session, you are prompted for permission to continue and then prompted for a file name. + ### Example 3 + ``` -PS C:\> add-pssnapin NewPSSnapin -PS C:\> export-console -path NewPSSnapinConsole.psc1 -PS C:\> powershell.exe -PsConsoleFile NewPsSnapinConsole.psc1 +PS> add-pssnapin NewPSSnapin +PS> export-console -path NewPSSnapinConsole.psc1 +PS> powershell.exe -PsConsoleFile NewPsSnapinConsole.psc1 ``` These commands add the NewPSSnapin Windows PowerShell snap-in to the current session, export the names of Windows PowerShell snap-ins in the current session to a console file, and then start a Windows PowerShell session with the console file. @@ -57,10 +66,12 @@ The second command exports the Windows PowerShell snap-in names to the NewPSSnap The third command starts Windows PowerShell with the NewPSSnapinConsole.psc1 file. Because the console file includes the Windows PowerShell snap-in name, the cmdlets and providers in the snap-in are available in the current session. + ### Example 4 + ``` -PS C:\> export-console -path Console01 -PS C:\> notepad console01.psc1 +PS> export-console -path Console01 +PS> notepad console01.psc1 2.0 @@ -73,14 +84,16 @@ PS C:\> notepad console01.psc1 This command exports the names of the Windows PowerShell snap-ins in the current session to the Console01.psc1 file in the current directory. The second command displays the contents of the Console01.psc1 file in Notepad. + ### Example 5 + ``` -PS C:\> powershell.exe -PSConsoleFile Console01.psc1 -PS C:\> add-pssnapin MySnapin -PS C:\> export-console NewConsole.psc1 -PS C:\> $consolefilename -PS C:\> add-pssnapin SnapIn03 -PS C:\> export-console +PS> powershell.exe -PSConsoleFile Console01.psc1 +PS> add-pssnapin MySnapin +PS> export-console NewConsole.psc1 +PS> $consolefilename +PS> add-pssnapin SnapIn03 +PS> export-console ``` This example shows how to use the $ConsoleFileName automatic variable to determine the console file that will be updated if you use Export-Console without a Path parameter value. @@ -98,9 +111,11 @@ The fifth command adds SnapIn03 to the current console. The sixth command uses the ExportConsole cmdlet without a Path parameter. This command exports the names of all the Windows PowerShell snap-ins in the current session to the most recently used file, NewConsole.psc1. + ## PARAMETERS ### -Force + Overwrites the data in a console file without warning, even if the file has the read-only attribute. The read-only attribute is changed and is not reset when the command completes. @@ -117,6 +132,7 @@ Accept wildcard characters: False ``` ### -NoClobber + Will not overwrite (replace the contents of) an existing console file. By default, if a file exists in the specified path, Export-Console overwrites the file without warning. @@ -133,6 +149,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies a path and file name for the console file (*.psc1). Enter a path (optional) and name. Wildcards are not permitted. @@ -159,6 +176,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -174,6 +192,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -190,17 +209,24 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.String + You can pipe a path string to Export-Console. + ## OUTPUTS ### System.IO.FileInfo + Export-Console creates a file that contains the exported aliases. + ## NOTES -* When a console file (.psc1) is used to start the session, the name of the console file is automatically stored in the $ConsoleFileName automatic variable. The value of $ConsoleFileName is updated when you use the Path parameter of Export-Console to specify a new console file. When no console file is used, $ConsoleFileName has no value ($null). + +- When a console file (.psc1) is used to start the session, the name of the console file is automatically stored in the $ConsoleFileName automatic variable. The value of $ConsoleFileName is updated when you use the Path parameter of Export-Console to specify a new console file. When no console file is used, $ConsoleFileName has no value ($null). To use a Windows PowerShell console file in a new session, use the following syntax to start Windows PowerShell: @@ -209,7 +235,8 @@ Export-Console creates a file that contains the exported aliases. You can also save Windows PowerShell snap-ins for future sessions by adding an Add-PSSnapin command to your Windows PowerShell profile. For more information, see about_Profiles. -* +- + ## RELATED LINKS [Add-PSSnapin](Add-PSSnapin.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Export-ModuleMember.md b/reference/3.0/Microsoft.PowerShell.Core/Export-ModuleMember.md index e37a4247b0cf..fbf87b64eeb8 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Export-ModuleMember.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Export-ModuleMember.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=141551 external help file: System.Management.Automation.dll-Help.xml title: Export-ModuleMember --- - # Export-ModuleMember + ## SYNOPSIS + Specifies the module members that are exported. + ## SYNTAX ``` @@ -19,6 +21,7 @@ Export-ModuleMember [[-Function] ] [-Cmdlet ] [-Variable Export-ModuleMember -function * -alias * +PS> Export-ModuleMember -function * -alias * ``` This command exports the aliases defined in the script module, along with the functions defined in the script module. To export the aliases, which are not exported by default, you must also explicitly specify the functions. Otherwise, only the aliases will be exported. + ### Example 2 + ``` -PS C:\> Export-ModuleMember -function Get-Test, New-Test, Start-Test -alias gtt, ntt, stt +PS> Export-ModuleMember -function Get-Test, New-Test, Start-Test -alias gtt, ntt, stt ``` This command exports three aliases and three functions defined in the script module. You can use this command format to specify the names of module members. + ### Example 3 + ``` -PS C:\> Export-ModuleMember +PS> Export-ModuleMember ``` This command specifies that no members defined in the script module are exported. This command prevents the module members from being exported, but it does not hide the members. Users can read and copy module members or use the call operator (&) to invoke module members that are not exported. + ### Example 4 + ``` -PS C:\> Export-ModuleMember -variable increment +PS> Export-ModuleMember -variable increment ``` This command exports only the $increment variable from the script module. No other members are exported. If you want to export a variable, in addition to exporting the functions in a module, the Export-ModuleMember command must include the names of all of the functions and the name of the variable. + ### Example 5 + ``` -PS C:\> # From TestModule.psm1 +PS> # From TestModule.psm1 function new-test { } export-modulemember -function new-test @@ -85,17 +98,21 @@ These commands create three functions and one alias, and then they export two of Without the Export-ModuleMember commands, all three of the functions would be exported, but the alias would not be exported. With the Export-ModuleMember commands, only the Get-Test and Start-Test functions and the STT alias are exported. + ### Example 6 + ``` -PS C:\> new-module -script {function SayHello {"Hello!"}; set-alias Hi SayHello; Export-ModuleMember -alias Hi -function SayHello} +PS> new-module -script {function SayHello {"Hello!"}; set-alias Hi SayHello; Export-ModuleMember -alias Hi -function SayHello} ``` This command shows how to use Export-ModuleMember in a dynamic module that is created by using the New-Module cmdlet. In this example, Export-ModuleMember is used to export both the "Hi" alias and the "SayHello" function in the dynamic module. + ### Example 7 + ``` -PS C:\> function export +PS> function export { param ([parameter(mandatory=$true)] [validateset("function","variable")] $type, [parameter(mandatory=$true)] $name, @@ -135,9 +152,11 @@ export variable \ \ The commands in the example show the correct format. In this example, only the New-Test function and the $Interval variable are exported. + ## PARAMETERS ### -Alias + Specifies the aliases that are exported from the script module file. Enter the alias names. Wildcards are permitted. @@ -155,6 +174,7 @@ Accept wildcard characters: True ``` ### -Cmdlet + Specifies the cmdlets that are exported from the script module file. Enter the cmdlet names. Wildcards are permitted. @@ -174,6 +194,7 @@ Accept wildcard characters: True ``` ### -Function + Specifies the functions that are exported from the script module file. Enter the function names. Wildcards are permitted. @@ -192,6 +213,7 @@ Accept wildcard characters: True ``` ### -Variable + Specifies the variables that are exported from the script module file. Enter the variable names (without a dollar sign). Wildcards are permitted. @@ -209,19 +231,27 @@ Accept wildcard characters: True ``` ### 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 function name strings to Export-ModuleMember. + ## OUTPUTS ### None + This cmdlet does not generate any output. + ## NOTES -* To exclude a member from the list of exported members, add an Export-ModuleMember command that lists all other members but omits the member that you want to exclude. -* +- To exclude a member from the list of exported members, add an Export-ModuleMember command that lists all other members but omits the member that you want to exclude. + +- + ## RELATED LINKS [Get-Module](Get-Module.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/3.0/Microsoft.PowerShell.Core/ForEach-Object.md index ad0a2bcae066..9b5916c65fd2 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/ForEach-Object.md +++ b/reference/3.0/Microsoft.PowerShell.Core/ForEach-Object.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,25 +7,30 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113300 external help file: System.Management.Automation.dll-Help.xml title: ForEach-Object --- - # ForEach-Object + ## SYNOPSIS + Performs an operation against each item in a collection of input objects. + ## SYNTAX ### ScriptBlockSet (Default) + ``` ForEach-Object [-InputObject ] [-Begin ] [-Process] [-End ] [-RemainingScripts ] [-WhatIf] [-Confirm] [] ``` ### PropertyAndMethodSet + ``` ForEach-Object [-InputObject ] [-MemberName] [-ArgumentList ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **ForEach-Object** cmdlet performs an operation on each item in a collection of input objects. The input objects can be piped to the cmdlet or specified by using the InputObject parameter. @@ -53,28 +58,34 @@ For example, the following command also gets the value of the **ProcessName** pr When using the script block format, in addition to using the script block that describes the operations that are performed on each input object, you can provide two additional script blocks. The Begin script block, which is the value of the **Begin** parameter, runs before the first input object is processed. The End script block, which is the value of the **End** parameter, runs after the last input object is processed. + ## EXAMPLES ### Example 1 + ``` -PS C:\> 30000, 56798, 12432 | ForEach-Object -Process {$_/1024} +PS> 30000, 56798, 12432 | ForEach-Object -Process {$_/1024} 29.296875 55.466796875 12.140625 ``` This command takes an array of three integers and divides each one of them by 1024. + ### Example 2 + ``` -PS C:\> Get-ChildItem $pshome | ForEach-Object -Process {if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; "" }} +PS> Get-ChildItem $pshome | ForEach-Object -Process {if (!$_.PSIsContainer) {$_.Name; $_.Length / 1024; "" }} ``` This command gets the files and directories in the Windows PowerShell installation directory ($pshome) and passes them to the ForEach-Object cmdlet. If the object is not a directory (the value of the PSISContainer property is false), the script block gets the name of the file, divides the value of its Length property by 1024, and adds a space ("") to separate it from the next entry. + ### Example 3 + ``` -PS C:\> $Events = Get-EventLog -LogName System -Newest 1000 -PS C:\> $events | ForEach-Object -Begin {Get-Date} -Process {Out-File -Filepath Events.txt -Append -InputObject $_.Message} -End {Get-Date} +PS> $Events = Get-EventLog -LogName System -Newest 1000 +PS> $events | ForEach-Object -Begin {Get-Date} -Process {Out-File -Filepath Events.txt -Append -InputObject $_.Message} -End {Get-Date} ``` This command gets the 1000 most recent events from the System event log and stores them in the $Events variable. @@ -83,9 +94,11 @@ It then pipes the events to the **ForEach-Object** cmdlet. The **Begin** parameter displays the current date and time. Next, the **Process** parameter uses the **Out-File** cmdlet to create a text file named events.txt and stores the message property of each of the events in that file. Last, the **End** parameter is used to display the date and time after all of the processing has completed. + ### Example 4 + ``` -PS C:\> Get-ItemProperty -Path HKCU:\Network\* | ForEach-Object {Set-ItemProperty -Path $_.PSPath -Name RemotePath -Value $_.RemotePath.ToUpper();} +PS> Get-ItemProperty -Path HKCU:\Network\* | ForEach-Object {Set-ItemProperty -Path $_.PSPath -Name RemotePath -Value $_.RemotePath.ToUpper();} ``` This command changes the value of the **RemotePath** registry entry in all of the subkeys under the HKCU:\Network key to uppercase text. @@ -100,9 +113,11 @@ In the **Set-ItemProperty** command, the path is the value of the **PSPath** pro (This is a property of the Microsoft .NET Framework object that represents the registry key; it is not a registry entry.) The command uses the ToUpper() method of the RemotePath value, which is a string (REG_SZ). Because **Set-ItemProperty** is changing the property of each key, the **ForEach-Object** cmdlet is required to access the property. + ### Example 5 + ``` -PS C:\> 1, 2, $null, 4 | ForEach-Object {"Hello"} +PS> 1, 2, $null, 4 | ForEach-Object {"Hello"} Hello Hello Hello @@ -114,10 +129,12 @@ This example shows the effect of piping the $null automatic variable to the **Fo Because Windows PowerShell treats null as an explicit placeholder, the **ForEach-Object** cmdlet generates a value for $null, just as it does for other objects that you pipe to it. For more information about the $null automatic variable, see about_Automatic_Variables. + ### Example 6 + ``` -PS C:\> Get-Module -List | ForEach-Object -MemberName Path -PS C:\> Get-Module -List | Foreach Path +PS> Get-Module -List | ForEach-Object -MemberName Path +PS> Get-Module -List | Foreach Path ``` These commands gets the value of the **Path** property of all installed Windows PowerShell modules. @@ -127,11 +144,13 @@ The second command is equivalent to the first. It uses the **Foreach** alias of the **Foreach-Object** cmdlet and omits the name of the **MemberName** parameter, which is optional. The **ForEach-Object** cmdlet is very useful for getting property values, because it gets the value without changing the type, unlike the **Format** cmdlets or the Select-Object cmdlet, which change the property value type. + ### Example 7 + ``` -PS C:\> "Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | ForEach-Object {$_.Split(".")} -PS C:\> "Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | ForEach-Object -MemberName Split -ArgumentList "." -PS C:\> "Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | Foreach Split "." +PS> "Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | ForEach-Object {$_.Split(".")} +PS> "Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | ForEach-Object -MemberName Split -ArgumentList "." +PS> "Microsoft.PowerShell.Core", "Microsoft.PowerShell.Host" | Foreach Split "." Microsoft PowerShell Core @@ -155,9 +174,11 @@ The output of these three commands, shown below, is identical. **Split** is just one of many useful methods of strings. To see all of the properties and methods of strings, pipe a string to the Get-Member cmdlet. + ## PARAMETERS ### -Begin + Specifies a script block that runs before processing any input objects. ```yaml @@ -173,6 +194,7 @@ Accept wildcard characters: False ``` ### -End + Specifies a script block that runs after processing all input objects. ```yaml @@ -188,6 +210,7 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the input objects. ForEach-Object runs the script block or operation statement on each input object. Enter a variable that contains the objects, or type a command or expression that gets the objects. @@ -208,6 +231,7 @@ Accept wildcard characters: False ``` ### -Process + Specifies the operation that is performed on each input object. Enter a script block that describes the operation. @@ -224,6 +248,7 @@ Accept wildcard characters: False ``` ### -RemainingScripts + Takes all script blocks that are not taken by the **Process** parameter. This parameter is introduced in Windows PowerShell 3.0. @@ -241,6 +266,7 @@ Accept wildcard characters: False ``` ### -ArgumentList + Specifies the arguments to a method call. This parameter is introduced in Windows PowerShell 3.0. @@ -258,6 +284,7 @@ Accept wildcard characters: False ``` ### -MemberName + Specifies the property to get or the method to call. Wildcard characters are permitted, but work only if the resulting string resolves to a unique value. If, for example, you run Get-Process | ForEach -MemberName *Name, and more than one member exists with a name that contains the string Name--such as the ProcessName and Name properties--the command fails. @@ -277,6 +304,7 @@ Accept wildcard characters: True ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -292,6 +320,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -308,15 +337,22 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.PSObject + You can pipe any object to ForEach-Object. + ## OUTPUTS ### System.Management.Automation.PSObject + The objects that ForEach-Object returns are determined by the input. + ## NOTES -* The **ForEach-Object** cmdlet works much like the **Foreach** statement, except that you cannot pipe input to a **Foreach** statement. For more information about the **Foreach** statement, see about_Foreach (http://go.microsoft.com/fwlink/?LinkID=113229). + +- The **ForEach-Object** cmdlet works much like the **Foreach** statement, except that you cannot pipe input to a **Foreach** statement. For more information about the **Foreach** statement, see about_Foreach (http://go.microsoft.com/fwlink/?LinkID=113229). ## RELATED LINKS \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md b/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md index ca8bb8326b22..58310c99c2ec 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-Command.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113309 external help file: System.Management.Automation.dll-Help.xml title: Get-Command --- - # Get-Command + ## SYNOPSIS + Gets all commands. + ## SYNTAX ### CmdletSet (Default) + ``` Get-Command [-Verb ] [-Noun ] [-Module ] [-TotalCount ] [-Syntax] [[-ArgumentList] ] [-All] [-ListImported] [-ParameterName ] @@ -21,6 +24,7 @@ Get-Command [-Verb ] [-Noun ] [-Module ] [-TotalCo ``` ### AllCommandSet + ``` Get-Command [[-Name] ] [-Module ] [-CommandType ] [-TotalCount ] [-Syntax] [[-ArgumentList] ] [-All] [-ListImported] [-ParameterName ] @@ -28,6 +32,7 @@ Get-Command [[-Name] ] [-Module ] [-CommandType Get-Command +PS> Get-Command ``` This command gets the Windows PowerShell cmdlets, functions, and aliases that are installed on the computer. + ### Example 2 + ``` -PS C:\> Get-Command -ListImported +PS> Get-Command -ListImported ``` This command uses the **ListImported** parameter to get only the commands in the current session. + ### Example 3 + ``` -PS C:\> Get-Command -Type Cmdlet | Sort-Object -Property Noun | Format-Table -GroupBy Noun +PS> Get-Command -Type Cmdlet | Sort-Object -Property Noun | Format-Table -GroupBy Noun ``` This command gets all of the cmdlets, sorts them alphabetically by the noun in the cmdlet name, and then displays them in noun-based groups. This display can help you find the cmdlets for a task. + ### Example 4 + ``` -PS C:\> Get-Command -Module Microsoft.PowerShell.Security, PSScheduledJob +PS> Get-Command -Module Microsoft.PowerShell.Security, PSScheduledJob ``` This command uses the **Module** parameter to get the commands in the Microsoft.PowerShell.Security and PSScheduledJob modules. + ### Example 5 + ``` -PS C:\> Get-Command Get-AppLockerPolicy +PS> Get-Command Get-AppLockerPolicy ``` This command gets information about the **Get-AppLockerPolicy** cmdlet. @@ -83,9 +98,11 @@ When a module is imported automatically, the effect is the same as using the Imp 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). + ### Example 6 + ``` -PS C:\> Get-Command Get-Childitem -Args Cert: -Syntax +PS> Get-Command Get-Childitem -Args Cert: -Syntax ``` This command uses the **ArgumentList** and **Syntax** parameters to get the syntax of the Get-ChildItem cmdlet when it is used in the Cert: drive. @@ -94,14 +111,16 @@ The Cert: drive is a Windows PowerShell drive that the Certificate Provider adds When you compare the syntax displayed in the output with the syntax that is displayed when you omit the Args (ArgumentList) parameter, you'll see that the **Certificate provider** adds a dynamic parameter, **CodeSigningCert**, to the Get-ChildItem cmdlet. For more information about the Certificate provider, see Certificate Provider. + ### Example 7 + ``` -PS C:\> function Get-DynamicParameters +PS> function Get-DynamicParameters { param ($Cmdlet, $PSDrive) (Get-Command $Cmdlet -ArgumentList $PSDrive).ParameterSets | ForEach-Object {$_.Parameters} | Where-Object { $_.IsDynamic } | Select-Object -Property Name -Unique } -PS C:\> Get-DynamicParameters -Cmdlet Get-ChildItem -PSDrive Cert: +PS> Get-DynamicParameters -Cmdlet Get-ChildItem -PSDrive Cert: Name ---- @@ -113,25 +132,31 @@ This is an alternative to the method used in the previous example. Dynamic parameter can be added to a cmdlet by another cmdlet or a provider. The command in the example uses the **Get-DynamicParameters** function to get the dynamic parameters that the Certificate provider adds to the Get-ChildItem cmdlet when it is used in the Cert: drive. + ### Example 8 + ``` -PS C:\> Get-Command * +PS> Get-Command * ``` This command gets all commands of all types on the local computer, including executable files in the paths of the **Path** environment variable ($env:path). It returns an **ApplicationInfo** object (System.Management.Automation.ApplicationInfo) for each file, not a **FileInfo** object (System.IO.FileInfo). + ### Example 9 + ``` -PS C:\> Get-Command -ParameterName *Auth* -ParameterType AuthenticationMechanism +PS> Get-Command -ParameterName *Auth* -ParameterType AuthenticationMechanism ``` This command gets cmdlets that have a parameter whose name includes "Auth" and whose type is **AuthenticationMechanism**. You can use a command like this one to find cmdlets that let you specify the method that is used to authenticate the user. The **ParameterType** parameter distinguishes parameters that take an **AuthenticationMechanism** value from those that take an **AuthenticationLevel** parameter, even when they have similar names. + ### Example 10 + ``` -PS C:\> Get-Command dir +PS> Get-Command dir CommandType Name ModuleName ----------- ---- ---------- Alias dir -> Get-ChildItem @@ -142,9 +167,11 @@ Although it is typically used on cmdlets and functions, **Get-Command** also get The output of the command shows the special view of the **Name** property value for aliases. The view shows the alias and the full command name. + ### Example 11 + ``` -PS C:\> Get-Command Notepad -All | Format-Table CommandType, Name, Definition +PS> Get-Command Notepad -All | Format-Table CommandType, Name, Definition CommandType Name Definition ----------- ---- ---------- @@ -160,9 +187,11 @@ With the **All** parameter, **Get-Command** gets all commands with the specified To run a command other than the first one in the list, type the fully qualified path to the command. For more information about command precedence, see about_Command_Precedence (http://go.microsoft.com/fwlink/?LinkID=113214). + ### Example 12 + ``` -PS C:\> (Get-Command Get-Date).ModuleName +PS> (Get-Command Get-Date).ModuleName Microsoft.PowerShell.Utility ``` @@ -170,9 +199,11 @@ This command gets the name of the snap-in or module in which the Get-Date cmdlet The command uses the **ModuleName** property of all commands. This command format works on commands in Windows PowerShell modules and snap-ins, even if they are not imported into the session. + ### Example 13 + ``` -PS C:\> Get-Command -Type Cmdlet | Where-Object OutputType | Format-List -Property Name, OutputType +PS> Get-Command -Type Cmdlet | Where-Object OutputType | Format-List -Property Name, OutputType ``` This command gets the cmdlets and functions that have an output type and the type of objects that they return. @@ -182,9 +213,11 @@ A pipeline operator (|) sends the cmdlets to the Where-Object cmdlet, which sele Another pipeline operator sends the selected cmdlet objects to the Format-List cmdlet, which displays the name and output type of each cmdlet in a list. The **OutputType** property of a **CommandInfo** object has a non-null value only when the cmdlet code defines the **OutputType** attribute for the cmdlet. + ### Example 14 + ``` -PS C:\> Get-Command -ParameterType (((Get-NetAdapter)[0]).PSTypeNames) +PS> Get-Command -ParameterType (((Get-NetAdapter)[0]).PSTypeNames) CommandType Name ModuleName ----------- ---- ---------- Function Disable-NetAdapter NetAdapter @@ -199,9 +232,11 @@ You can use this command format to find the cmdlets that accept the type of obje The command uses the **PSTypeNames** intrinsic property of all objects, which gets the types that describe the object. To get the **PSTypeNames** property of a net adapter, and not the **PSTypeNames** property of a collection of net adapters, the command uses array notation to get the first net adapter that the cmdlet returns. + ## PARAMETERS ### -All + Gets all commands, including commands of the same type that have the same name. By default, **Get-Command** gets only the commands that run when you type the command name. @@ -225,6 +260,7 @@ Accept wildcard characters: False ``` ### -ArgumentList + Gets information about a cmdlet or function when it is used with the specified parameters ("arguments"). The alias for **ArgumentList** is **Args**. @@ -247,6 +283,7 @@ Accept wildcard characters: False ``` ### -CommandType + Gets only the specified types of commands. Enter one or more command types. Use **CommandType** or its alias, **Type**. @@ -276,6 +313,7 @@ Accept wildcard characters: False ``` ### -Module + Gets the commands that came from the specified modules or snap-ins. Enter the names of modules or snap-ins, or enter snap-in or module objects. @@ -297,6 +335,7 @@ Accept wildcard characters: False ``` ### -Name + Gets only commands with the specified name. Enter a name or name pattern. Wildcards are permitted. @@ -317,6 +356,7 @@ Accept wildcard characters: False ``` ### -Noun + Gets commands (cmdlets, functions, workflows, and aliases) that have names that include the specified noun. Enter one or more nouns or noun patterns. Wildcards are permitted. @@ -334,12 +374,13 @@ Accept wildcard characters: False ``` ### -Syntax + Gets only specified data about the command. -* For aliases, gets the standard name. -* For cmdlets, gets the syntax. -* For functions and filters, gets the function definition. -* For scripts and applications (files), gets the path and filename. +- For aliases, gets the standard name. +- For cmdlets, gets the syntax. +- For functions and filters, gets the function definition. +- For scripts and applications (files), gets the path and filename. ```yaml Type: SwitchParameter @@ -354,6 +395,7 @@ Accept wildcard characters: False ``` ### -TotalCount + Gets the specified number of commands. You can use this parameter to limit the output of a command. @@ -370,6 +412,7 @@ Accept wildcard characters: False ``` ### -Verb + Gets commands (cmdlets, functions, workflows, and aliases) that have names that include the specified verb. Enter one or more verbs or verb patterns. Wildcards are permitted. @@ -387,6 +430,7 @@ Accept wildcard characters: False ``` ### -ListImported + Gets only commands in the current session. Beginning in Windows PowerShell 3.0, by default, **Get-Command** gets all installed commands, including, but not limited to, the commands in the current session. @@ -407,6 +451,7 @@ Accept wildcard characters: False ``` ### -ParameterName + Gets commands in the session that have the specified parameters. Enter parameter names and/or parameter aliases. Wildcard are supported. @@ -428,6 +473,7 @@ Accept wildcard characters: False ``` ### -ParameterType + Gets commands in the session that have parameters of the specified type. Enter the full name or partial name of a parameter type. Wildcards are supported. @@ -449,29 +495,45 @@ 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 command names to **Get-Command**. + ## OUTPUTS ### System.Management.Automation.CommandInfo + All **Get-Command** output types are derived from this class. The type of object that is returned depends on the type of command that Get-Command gets. + ### System.Management.Automation.AliasInfo + Represents aliases. + ### System.Management.Automation.ApplicationInfo + Represents or applications and files + ### System.Management.Automation.CmdletInfo + Represents cmdlets. + ### System.Management.Automation.FunctionInfo + Represents functions and filters + ### System.Management.Automation.WorkflowInfo ## 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](About/about_Preference_Variables.md). + +- 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](About/about_Preference_Variables.md). + ## RELATED LINKS [Export-PSSession](../Microsoft.PowerShell.Utility/Export-PSSession.md) @@ -484,4 +546,4 @@ Represents functions and filters [Import-PSSession](../Microsoft.PowerShell.Utility/Import-PSSession.md) -[about_Command_Precedence](About/about_Command_Precedence.md) +[about_Command_Precedence](About/about_Command_Precedence.md) \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-Help.md b/reference/3.0/Microsoft.PowerShell.Core/Get-Help.md index f35b6df433c6..fd2315049c50 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-Help.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-Help.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,49 +7,58 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113316 external help file: System.Management.Automation.dll-Help.xml title: Get-Help --- - # Get-Help + ## SYNOPSIS + Displays information about Windows PowerShell commands and concepts. + ## SYNTAX ### AllUsersView (Default) + ``` Get-Help [[-Name] ] [-Path ] [-Category ] [-Component ] [-Functionality ] [-Role ] [-Full] [] ``` ### DetailedView + ``` Get-Help [[-Name] ] [-Path ] [-Category ] [-Component ] [-Functionality ] [-Role ] [-Detailed] [] ``` ### Examples + ``` Get-Help [[-Name] ] [-Path ] [-Category ] [-Component ] [-Functionality ] [-Role ] [-Examples] [] ``` ### Parameters + ``` Get-Help [[-Name] ] [-Path ] [-Category ] [-Component ] [-Functionality ] [-Role ] -Parameter [] ``` ### Online + ``` Get-Help [[-Name] ] [-Path ] [-Category ] [-Component ] [-Functionality ] [-Role ] [-Online] [] ``` ### ShowWindow + ``` Get-Help [[-Name] ] [-Path ] [-Category ] [-Component ] [-Functionality ] [-Role ] [-ShowWindow] [] ``` ## DESCRIPTION + The **Get-Help** cmdlet displays information about Windows PowerShell concepts and commands, including cmdlets, functions, CIM commands, workflows, providers, aliases and scripts. To get help for a Windows PowerShell command, type "Get-Help" followed by the command name, such as: `Get-Help Get-Process`. @@ -89,33 +98,41 @@ For information about parameter attributes, such as **Required** and **Position* **TROUBLESHOOTING NOTE**: In Windows PowerShell 3.0, **Get-Help** cannot find About topics in modules unless the module is imported into the current session. This is a known issue. To get About topics in a module, import the module, either by using the Import-Module cmdlet or by using a cmdlet in the module. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Get-Help +PS> Get-Help ``` This command displays help about the Windows PowerShell help system. + ### Example 2 + ``` -PS C:\> Get-Help * +PS> Get-Help * ``` This command displays a list of the available help topics. + ### Example 3 + ``` -PS C:\> Get-Help Get-Alias -PS C:\> Help Get-Alias -PS C:\> Get-Alias -? +PS> Get-Help Get-Alias +PS> Help Get-Alias +PS> Get-Alias -? ``` These commands display basic information about the Get-Alias cmdlet. The "Get-Help" and "-?" commands display the information on a single page. The "Help" command displays the information one page at a time. + ### Example 4 + ``` -PS C:\> Get-Help about_* +PS> Get-Help about_* ``` This command displays a list of the conceptual topics included in Windows PowerShell help. @@ -124,10 +141,12 @@ To display a particular help file, type "get-help \, for example, " This command displays the conceptual topics only when the help files for those topics are installed on the computer. For information about downloading and installing help files in Windows PowerShell 3.0, see Update-Help. + ### Example 5 + ``` The first command uses the **Get-Help** cmdlet to get help for the Get-Command cmdlet. Without help files, **Get-Help** display the cmdlet name, syntax and alias of **Get-Command**, and prompts you to use the Update-Help cmdlet to get the newest help files. -PS C:\> Get-Help Get-Command +PS> Get-Help Get-Command NAME Get-Command @@ -155,10 +174,10 @@ REMARKS for this cmdlet, use Update-Help. The second command runs the Update-Help cmdlet without parameters. This command downloads help files from the Internet for all of the modules in the current session and installs them on the local computer.This command works only when the local computer is connected to the Internet. If your computer is not connected to the Internet, you might be able to install help files from a network share. For more information, see Save-Help. -PS C:\> Update-Help +PS> Update-Help Now that the help files are downloaded, we can repeat the first command in the sequence. This command gets help for the **Get-Command** cmdlet. The cmdlet now gets more extensive help for **Get-Command** and you can use the **Detailed**, **Full**, **Example**, and **Parameter** parameters of **Get-Help** to customize the displays.You can use the **Get-Help** cmdlet as soon as the Update-Help command completes. You do not need to restart Windows PowerShell. -PS C:\> Get-Help Get-Command +PS> Get-Help Get-Command ``` This example shows how to download and install new or updated help files for a module. @@ -170,67 +189,83 @@ You can use the same command sequence to update the help files on your computer To download and install the help files for the commands that come with Windows PowerShell, and for any modules in the $pshome\Modules directory, open Windows PowerShell with the "Run as administrator" option. If you are not a member of the Administrators group on the computer, you cannot download help for these modules. However, you can use the **Online** parameter to open the online version of help for a command, and you can read the help for Windows PowerShell in the TechNet Library beginning at http://go.microsoft.com/fwlink/?LinkID=107116http://go.microsoft.com/fwlink/?LinkID=107116. + ### Example 6 + ``` -PS C:\> Get-Help ls -Detailed +PS> Get-Help ls -Detailed ``` This command displays detailed help for the Get-ChildItem cmdlet by specifying one of its aliases, "ls." The **Detailed** parameter of **Get-Help** gets the detailed view of the help topic, which includes parameter descriptions and examples. To see the complete help topic for a cmdlet, use the **Full** parameter. The **Full** and **Detailed** parameters are effective only when help files for the command are installed on the computer. + ### Example 7 + ``` -PS C:\> Get-Help Format-Table -Full +PS> Get-Help Format-Table -Full ``` This command uses the **Full** parameter of **Get-Help** to display the full view help for the Format-Table cmdlet. The full view of help includes parameter descriptions, examples, and a table of technical details about the parameters. The **Full** parameter is effective only when help files for the command are installed on the computer. + ### Example 8 + ``` -PS C:\> Get-Help Start-Service -Examples +PS> Get-Help Start-Service -Examples ``` This command displays examples of using the Start-Service cmdlet. It uses the **Examples** parameter of **Get-Help** to display only the Examples section of the cmdlet help topics. The **Examples** parameter is effective only when help files for the command are installed on the computer. + ### Example 9 + ``` -PS C:\> Get-Help Format-List -Parameter GroupBy +PS> Get-Help Format-List -Parameter GroupBy ``` This command uses the **Parameter** parameter of **Get-Help** to display a detailed description of the **GroupBy** parameter of the Format-List cmdlet. For detailed descriptions of all parameters of the **Format-List** cmdlet, type "`Get-Help Format-List -Parameter *`". + ### Example 10 + ``` -PS C:\> Get-Help Add-Member -Full | Out-String -Stream | Select-String -Pattern Clixml +PS> Get-Help Add-Member -Full | Out-String -Stream | Select-String -Pattern Clixml ``` This example shows how to search for a word in particular cmdlet help topic. This command searches for the word "Clixml" in the full version of the help topic for the Add-Member cmdlet. Because the **Get-Help** cmdlet generates a **MamlCommandHelpInfo** object, not a string, you need to use a cmdlet that transforms the help topic content into a string, such as Out-String or Out-File. + ### Example 11 + ``` -PS C:\> Get-Help Get-Member -Online +PS> Get-Help Get-Member -Online ``` This command displays the online version of the help topic for the Get-Member cmdlet. + ### Example 12 + ``` -PS C:\> Get-Help remoting +PS> Get-Help remoting ``` This command displays a list of topics that include the word "remoting." When you enter a word that does not appear in any topic title, **Get-Help** displays a list of topics that include that word. + ### Example 13 + ``` The first command uses the **Path** parameter of **Get-Help** to specify the provider path. This command can be entered at any path location. -PS C:\> Get-Help Get-Item -Path SQLSERVER:\DataCollection +PS> Get-Help Get-Item -Path SQLSERVER:\DataCollection NAME @@ -246,7 +281,7 @@ SYNOPSIS ... The second command uses the Set-Location cmdlet (alias = "cd") to navigate to the provider path. From that location, even without the **Path** parameter, the **Get-Help** command gets the provider-specific help for the **Get-Item** cmdlet. -PS C:\> cd SQLSERVER:\DataCollection +PS> cd SQLSERVER:\DataCollection SQLSERVER:\DataCollection> Get-Help Get-Item NAME @@ -264,7 +299,7 @@ SYNOPSIS The third command shows that a **Get-Help** command in a file system path, and without the **Path** parameter, gets the standard help for the **Get-Item** cmdlet. -PS C:\> Get-Item +PS> Get-Item NAME @@ -282,16 +317,20 @@ The example shows two ways of getting the provider-specific help for **Get-Item* You can also get provider-specific help for cmdlets online in the section that describes the provider. For example, for provider-specific online help for the New-Item cmdlet in each WSMan provider path, see http://go.microsoft.com/fwlink/?LinkID=158676http://go.microsoft.com/fwlink/?LinkID=158676. + ### Example 14 + ``` -PS C:\> Get-Help C:\PS-Test\MyScript.ps1 +PS> Get-Help C:\PS-Test\MyScript.ps1 ``` This command gets help for the MyScript.ps1 script. For information about writing help for your functions and scripts, see about_Comment_Based_Helphttp://go.microsoft.com/fwlink/?LinkID=144309. + ## PARAMETERS ### -Category + Displays help only for items in the specified category and their aliases. Valid values are **Alias**, **Cmdlet**, **Function**, **Provider**, **Workflow**, and **HelpFile**. Conceptual topics are in the **HelpFile** category. @@ -309,6 +348,7 @@ Accept wildcard characters: False ``` ### -Component + Displays commands with the specified component value, such as "Exchange." Enter a component name. Wildcards are permitted. @@ -327,6 +367,7 @@ Accept wildcard characters: True ``` ### -Detailed + Adds parameter descriptions and examples to the basic help display. This parameter is effective only when help files are for the command are installed on the computer. @@ -345,6 +386,7 @@ Accept wildcard characters: False ``` ### -Examples + Displays only the name, synopsis, and examples. To display only the examples, type "(Get-Help \).Examples". @@ -364,6 +406,7 @@ Accept wildcard characters: False ``` ### -Full + Displays the entire help topic for a cmdlet, including parameter descriptions and attributes, examples, input and output object types, and additional notes. This parameter is effective only when help files are for the command are installed on the computer. @@ -382,6 +425,7 @@ Accept wildcard characters: False ``` ### -Functionality + Displays help for items with the specified functionality. Enter the functionality. Wildcards are permitted. @@ -401,6 +445,7 @@ Accept wildcard characters: True ``` ### -Name + Gets help about the specified command or concept. Enter the name of a cmdlet, function, provider, script, or workflow, such as "Get-Member", a conceptual topic name, such as "about_Objects", or an alias, such as "ls". Wildcards are permitted in cmdlet and provider names, but you cannot use wildcards to find the names of function help and script help topics. @@ -426,6 +471,7 @@ Accept wildcard characters: True ``` ### -Online + Displays the online version of a help topic in the default Internet browser. This parameter is valid only for cmdlet, function, workflow and script help topics. You cannot use the **Online** parameter in **Get-Help** commands in a remote session. @@ -445,6 +491,7 @@ Accept wildcard characters: False ``` ### -Parameter + Displays only the detailed descriptions of the specified parameters. Wildcards are permitted. @@ -463,6 +510,7 @@ Accept wildcard characters: True ``` ### -Path + Gets help that explains how the cmdlet works in the specified provider path. Enter a Windows PowerShell provider path. @@ -489,6 +537,7 @@ Accept wildcard characters: False ``` ### -Role + Displays help customized for the specified user role. Enter a role. Wildcards are permitted. @@ -510,6 +559,7 @@ Accept wildcard characters: True ``` ### -ShowWindow + Displays the help topic in a window for easier reading. The window includes a "Find" search feature and a "Settings" box that lets you set options for the display, including options to display only selected sections of a help topic. @@ -531,27 +581,38 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe objects to this cmdlet. + ## OUTPUTS ### ExtendedCmdletHelpInfo + If you run **Get-Help** on a command that does not have a help file, **Get-Help** returns an ExtendedCmdletHelpInfo object that represents autogenerated help. + ### System.String + If you get a conceptual help topic, **Get-Help** returns it as a string. + ### MamlCommandHelpInfo + If you get a command that has a help file, **Get-Help** returns a **MamlCommandHelpInfo** object. + ## NOTES -* Without parameters, "Get-Help" displays information about the Windows PowerShell help system. -* Windows PowerShell 3.0 does not come with help files. To download and install the help files that **Get-Help** reads, use the Update-Help cmdlet. You can use the **Update-Help** cmdlet to download and install help files for the core commands that come with Windows PowerShell and for any modules that you install. You can also use it to update the help files so that the help on your computer is never outdated. + +- Without parameters, "Get-Help" displays information about the Windows PowerShell help system. +- Windows PowerShell 3.0 does not come with help files. To download and install the help files that **Get-Help** reads, use the Update-Help cmdlet. You can use the **Update-Help** cmdlet to download and install help files for the core commands that come with Windows PowerShell and for any modules that you install. You can also use it to update the help files so that the help on your computer is never outdated. You can also read the help topics about the commands that come with Windows PowerShell online beginning at http://go.microsoft.com/fwlink/?LinkID=107116. -* **Get-Help** displays help in the locale set for Windows or in the fallback language for that locale. If you do not have help files for the primary or fallback locale, **Get-Help** behaves as though there are no help files on the computer. To get help for a different locale, use Region and Language in Control Panel to change the settings for Windows. -* The full view of help (-Full) includes a table of information about the parameters. The table includes the following fields: +- **Get-Help** displays help in the locale set for Windows or in the fallback language for that locale. If you do not have help files for the primary or fallback locale, **Get-Help** behaves as though there are no help files on the computer. To get help for a different locale, use Region and Language in Control Panel to change the settings for Windows. +- The full view of help (-Full) includes a table of information about the parameters. The table includes the following fields: - Required: Indicates whether the parameter is required (true) or optional (false). @@ -570,6 +631,7 @@ When the parameter name is used, the parameter can appear anywhere in the comman "By Property Name" means that the pipelined object must have a property with the same name as the parameter name. - Accepts wildcard characters: Indicates whether the value of a parameter can include wildcard characters, such as * and ?. + ## RELATED LINKS [Updatable Help Status Table (http://go.microsoft.com/fwlink/?LinkID=270007)](http://go.microsoft.com/fwlink/?LinkID=270007) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-History.md b/reference/3.0/Microsoft.PowerShell.Core/Get-History.md index 599525b71d7d..3f2eccb9e7fe 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-History.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-History.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113317 external help file: System.Management.Automation.dll-Help.xml title: Get-History --- - # Get-History + ## SYNOPSIS + Gets a list of the commands entered during the current session. + ## SYNTAX ``` @@ -18,6 +20,7 @@ Get-History [[-Id] ] [[-Count] ] [] ``` ## DESCRIPTION + The **Get-History** cmdlet gets the session history, that is, the list of commands entered during the current session. Windows PowerShell automatically maintains a history of each session. @@ -28,50 +31,62 @@ You can save the session history in XML or CSV format. By default, history files are saved in the home directory, but you can save the file in any location. For more information about the history features in Windows PowerShell, see about_History (http://go.microsoft.com/fwlink/?LinkID=113233). + ## EXAMPLES ### Example 1 + ``` -PS C:\> Get-History +PS> Get-History ``` This command gets the entries in the session history. The default display shows each command and its ID, which indicates the order of execution. + ### Example 2 + ``` -PS C:\> Get-History | Where-Object {$_.CommandLine -like "*Service*"} +PS> Get-History | Where-Object {$_.CommandLine -like "*Service*"} ``` This command gets entries in the command history that include "service". The first command gets all entries in the session history. The pipeline operator (|) passes the results to the Where-Object cmdlet, which selects only the commands that include "service". + ### Example 3 + ``` -PS C:\> Get-History -ID 7 -Count 5 | Export-Csv History.csv +PS> Get-History -ID 7 -Count 5 | Export-Csv History.csv ``` This command gets the five most recent history entries ending with entry 7. The pipeline operator (|) passes the result to the Export-Csv cmdlet, which formats the history as comma-separated text and saves it in the History.csv file. The file includes the data that is displayed when you format the history as a list, including the status and start and end times of the command. + ### Example 4 + ``` -PS C:\> Get-History -Count 1 +PS> Get-History -Count 1 ``` This command gets the last (most recently entered) command in the command history. It uses the **Count** parameter to display just one command. By default, **Get-History** gets the most recent commands. This command can be abbreviated to "h -c 1" and is equivalent to pressing the up-arrow key. + ### Example 5 + ``` -PS C:\> Get-History | Format-List -Property * +PS> Get-History | Format-List -Property * ``` This command displays all of the properties of entries in the session history. The pipeline operator (|) passes the results of a **Get-History** command to the Format-List cmdlet, which displays all of the properties of each history entry, including the ID, status, and start and end times of the command. + ## PARAMETERS ### -Count + Displays the specified number of the most recent history entries. By, default, Get-History gets all entries in the session history. If you use both the **Count** and **Id** parameters in a command, the display ends with the command that is specified by the **Id** parameter. @@ -91,6 +106,7 @@ Accept wildcard characters: False ``` ### -Id + Specifies the ID number of an entry in the session history. **Get-History** gets only the specified entry. If you use both the **Id** and **Count** parameters in a command, **Get-History** gets the most recent entries ending with the entry specified by the **Id** parameter. @@ -108,18 +124,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). + ## INPUTS ### Int64 + You can pipe a history ID to Get-History. + ## OUTPUTS ### Microsoft.PowerShell.Commands.HistoryInfo + 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](About/about_Preference_Variables.md). + +- 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](About/about_Preference_Variables.md). + ## RELATED LINKS [Add-History](Add-History.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-Job.md b/reference/3.0/Microsoft.PowerShell.Core/Get-Job.md index c268d71d9866..fcb3f4a1cfc7 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-Job.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-Job.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,48 +7,57 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113328 external help file: System.Management.Automation.dll-Help.xml title: Get-Job --- - # Get-Job + ## SYNOPSIS + Gets Windows PowerShell background jobs that are running in the current session. + ## SYNTAX ### SessionIdParameterSet (Default) + ``` Get-Job [-IncludeChildJob] [-ChildJobState ] [-HasMoreData ] [-Before ] [-After ] [-Newest ] [[-Id] ] [] ``` ### CommandParameterSet + ``` Get-Job [-IncludeChildJob] [-ChildJobState ] [-HasMoreData ] [-Before ] [-After ] [-Newest ] [-Command ] [] ``` ### StateParameterSet + ``` Get-Job [-IncludeChildJob] [-ChildJobState ] [-HasMoreData ] [-Before ] [-After ] [-Newest ] [-State] [] ``` ### InstanceIdParameterSet + ``` Get-Job [-IncludeChildJob] [-ChildJobState ] [-HasMoreData ] [-Before ] [-After ] [-Newest ] [-InstanceId] [] ``` ### NameParameterSet + ``` Get-Job [-IncludeChildJob] [-ChildJobState ] [-HasMoreData ] [-Before ] [-After ] [-Newest ] [-Name] [] ``` ### FilterParameterSet + ``` Get-Job [-Filter] [] ``` ## DESCRIPTION + The **Get-Job** cmdlet gets objects that represent the background jobs that were started in the current session. You can use **Get-Job** to get jobs that were started by using the Start-Job cmdlet, or by using the **AsJob** parameter of any cmdlet. @@ -67,83 +76,97 @@ To find the job type of a job, use the **PSJobTypeName** property of the job. To enable **Get-Job** to get a custom job type, import the module that supports the custom job type into the session before running a **Get-Job** command, either by using the Import-Module cmdlet or by using or getting a cmdlet in the module. For information about a particular custom job type, see the documentation of the custom job type feature. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Get-Job +PS> Get-Job ``` This command gets all background jobs started in the current session. It does not include jobs created in other sessions, even if the jobs run on the local computer. + ### Example 2 + ``` The first command uses the **Get-Job** cmdlet to get a job. It uses the Name parameter to identify the job. The command stores the job object that **Get-Job** returns in the $j variable. In this example, there is only one job with the specified name. -PS C:\> $j = Get-Job -Name Job1 +PS> $j = Get-Job -Name Job1 The second command gets the **InstanceId** property of the object in the $j variable and stores it in the $ID variable. -PS C:\> $ID = $j.InstanceID +PS> $ID = $j.InstanceID The third command displays the value of the $ID variable. -PS C:\> $ID +PS> $ID Guid ---- 03c3232e-1d23-453b-a6f4-ed73c9e29d55 The fourth command uses Stop-Job cmdlet to stop the job. It uses the **InstanceId** parameter to identify the job and $ID variable to represent the instance ID of the job. -PS C:\> Stop-Job -InstanceId $ID +PS> Stop-Job -InstanceId $ID ``` These commands show how to get the instance ID of a job and then use it to stop a job. Unlike the name of a job, which is not unique, the instance ID is unique. + ### Example 3 + ``` -PS C:\> Get-Job -Command "*get-process*" +PS> Get-Job -Command "*get-process*" ``` This command gets the jobs on the system that include a Get-Process command. The command uses the **Command** parameter of **Get-Job** to limit the jobs retrieved. The command uses wildcard characters (*) to get jobs that include a **Get-Process** command anywhere within the command string. + ### Example 4 + ``` -PS C:\> "*get-process*" | Get-Job +PS> "*get-process*" | Get-Job ``` Like the command in the previous example, this command gets the jobs on the system that include a Get-Process command. The command uses a pipeline operator (|) to send a string (in quotation marks) to the **Get-Job** cmdlet. It is the equivalent of the previous command. + ### Example 5 + ``` -PS C:\> Get-Job -State NotStarted +PS> Get-Job -State NotStarted ``` This command gets only those jobs that have been created but have not yet been started. This includes jobs that are scheduled to run in the future and those not yet scheduled. + ### Example 6 + ``` -PS C:\> Get-Job -name Job* +PS> Get-Job -name Job* ``` This command gets all jobs that have job names beginning with "job". Because "job\" is the default name for a job, this command gets all jobs that do not have an explicitly assigned name. + ### Example 7 + ``` The first command uses the Start-Jobcmdlet to start a background job that runs a **Get-Process** command on the local computer. The command uses the **Name** parameter of **Start-Job** to assign a friendly name to the job. -PS C:\> Start-Job -ScriptBlock {Get-Process} -Name MyJob +PS> Start-Job -ScriptBlock {Get-Process} -Name MyJob The second command uses Get-Job to get the job. It uses the **Name** parameter of **Get-Job** to identify the job. The command saves the resulting job object in the $j variable. -PS C:\> +PS> $j = Get-Job -Name MyJob The third command displays the value of the job object in the $j variable. The value of the **State** property shows that the job is complete. The value of the **HasMoreData** property shows that there are results available from the job that have not yet been retrieved. -PS C:\> $j +PS> $j Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 6 MyJob BackgroundJob Completed True localhost Get-Process The fourth command uses the Receive-Job cmdlet to get the results of the job. It uses the job object in the $j variable to represent the job. You can also use a pipeline operator to send a job object to Receive-Job. -PS C:\> Receive-Job -Job $j +PS> Receive-Job -Job $j Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 124 4 13572 12080 59 1140 audiodg @@ -153,47 +176,51 @@ Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ``` This example shows how to use **Get-Job** to get a job object, and then it shows how to use the job object to represent the job in a command. + ### Example 8 + ``` The first command uses the Start-Job cmdlet to start a job on the local computer. -PS C:\> Start-Job -ScriptBlock {Get-EventLog System} +PS> Start-Job -ScriptBlock {Get-EventLog System} The second command uses the **AsJob** parameter of the Invoke-Command cmdlet to start a job on the S1 computer. Even though the commands in the job run on the remote computer, the job object is created on the local computer, so you use local commands to manage the job. -PS C:\> Invoke-Command -ComputerName S1 -ScriptBlock {Get-EventLog System} -AsJob +PS> Invoke-Command -ComputerName S1 -ScriptBlock {Get-EventLog System} -AsJob The third command uses the **Invoke-Command** cmdlet to run a **Start-Job** command on the S2 computer. With this method, the job object is created on the remote computer, so you use remote commands to manage the job. -PS C:\> Invoke-Command -ComputerName S2 -ScriptBlock {Start-Job -ScriptBlock {Get-EventLog System}} +PS> Invoke-Command -ComputerName S2 -ScriptBlock {Start-Job -ScriptBlock {Get-EventLog System}} The fourth command uses **Get-Job** to get the jobs stored on the local computer. The **PSJobTypeName** property of jobs, introduced in Windows PowerShell 3.0, shows that the local job started by using the Start-Job cmdlet is a background job and the job started in a remote session by using the Invoke-Command cmdlet is a remote job.. -PS C:\> Get-Job +PS> Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Running True localhost Get-EventLog System 2 Job2 RemoteJob Running True S1 Get-EventLog System The fifth command uses **Invoke-Command** to run a **Get-Job** command on the S2 computer.The sample output shows the results of the Get-Job command. On the S2 computer, the job appears to be a local job. The computer name is "localhost" and the job type is a background job.For more information about running background jobs on remote computers, see about_Remote_Jobs. -PS C:\> Invoke-Command -ComputerName S2 -ScriptBlock {Start-Job -ScriptBlock {Get-EventLog System}} +PS> Invoke-Command -ComputerName S2 -ScriptBlock {Start-Job -ScriptBlock {Get-EventLog System}} Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- ------- ------- 4 Job4 BackgroundJob Running True localhost Get-Eventlog System ``` This example demonstrates that the Get-Job cmdlet can get all of the jobs that were started in the current session, even if they were started by using different methods. + ### Example 9 + ``` The first command uses the Start-Job cmdlet to start a job on the local computer. The job object that **Start-Job** returns shows that the job failed. The value of the **State** property is "Failed". -PS C:\> Start-Job -ScriptBlock {Get-Process} +PS> Start-Job -ScriptBlock {Get-Process} Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 1 Job1 BackgroundJob Failed False localhost Get-Process The second command uses the **Get-Job** cmdlet to get the job. The command uses the dot method to get the value of the **JobStateInfo** property of the object. It uses a pipeline operator to send the object in the **JobStateInfo** property to the Format-List cmdlet, which formats all of the properties of the object (*) in a list.The result of the **Format-List** command shows that the value of the **Reason** property of the job is blank. -PS C:\> (Get-Job).JobStateInfo | Format-List -Property * +PS> (Get-Job).JobStateInfo | Format-List -Property * State : Failed Reason : The third command investigates further. It uses a **Get-Job** command to get the job and then uses a pipeline operator to send the entire job object to the **Format-List** cmdlet, which displays all of the properties of the job in a list.The display of all properties in the job object shows that the job contains a child job named "Job2". -PS C:\> Get-Job | Format-List -Property * +PS> Get-Job | Format-List -Property * HasMoreData : False StatusMessage : @@ -229,22 +256,24 @@ Warning : {} StateChanged : The fourth command uses **Get-Job** to get the job object that represents the Job2 child job. This is the job in which the command actually ran. It uses the dot method to get the **Reason** property of the **JobStateInfo** property.The result shows that the job failed because of an "Access Denied" error. In this case, the user forgot to use the "Run as administrator" option when opening Windows PowerShell.Because background jobs use the remoting features of Windows PowerShell, the computer must be configured for remoting to run a job, even when the job runs on the local computer.For information about requirements for remoting in Windows PowerShell, see about_Remote_Requirements. For troubleshooting tips, see about_Remote_Troubleshooting. -PS C:\> (Get-Job -Name job2).JobStateInfo.Reason +PS> (Get-Job -Name job2).JobStateInfo.Reason Connecting to remote server using WSManCreateShellEx api failed. The async callback gave the following error message : Access is denied. ``` This command shows how to use the job object that Get-Job returns to investigate why a job failed. It also shows how to get the child jobs of each job. + ### Example 10 + ``` The first command uses the **Workflow** keyword to create the "WFProcess" workflow. -PS C:\> Workflow WFProcess {Get-Process} +PS> Workflow WFProcess {Get-Process} The second command uses the **AsJob** parameter of the WFProcess workflow to run the workflow as a background job. It uses the **JobName** parameter of the workflow to specify a name for the job, and the **PSPrivateMetadata** parameter of the workflow to specify a custom ID. -PS C:\> WFProcess -AsJob -JobName WFProcessJob -PSPrivateMetadata @{MyCustomId = 92107} +PS> WFProcess -AsJob -JobName WFProcessJob -PSPrivateMetadata @{MyCustomId = 92107} The third command uses the **Filter** parameter of **Get-Job** to get the job by custom ID that was specified in the **PSPrivateMetadata** parameter. -PS C:\> Get-Job -Filter @{MyCustomId = 92107} +PS> Get-Job -Filter @{MyCustomId = 92107} Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- @@ -254,10 +283,12 @@ Id Name State HasMoreData Location Comman This example shows how to use the **Filter** parameter to get a workflow job. The **Filter** parameter, introduced in Windows PowerShell 3.0 is valid only on custom job types, such as workflow jobs and scheduled jobs. + ### Example 11 + ``` The first command gets the jobs in the current session. The output includes a background job, a remote job and several instances of a scheduled job. The remote job, Job4, appears to have failed. -PS C:\> Get-Job +PS> Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 Job2 BackgroundJob Completed True localhost .\Get-Archive.ps1 @@ -268,7 +299,7 @@ Id Name PSJobTypeName State HasMoreData Location 10 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help The second command uses the **IncludeChildJob** parameter of **Get-Job**. The output adds the child jobs of all jobs that have child jobs.In this case, the revised output shows that only the Job5 child job of Job4 failed. -PS C:\> Get-Job -IncludeChildJob +PS> Get-Job -IncludeChildJob Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 Job2 BackgroundJob Completed True localhost .\Get-Archive.ps1 @@ -282,7 +313,7 @@ Id Name PSJobTypeName State HasMoreData Location 10 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help The third command uses the **ChildJobState** parameter with a value of **Failed**.The output includes all parent jobs and only the child jobs that failed. -PS C:\> Get-Job -Name Job4 -ChildJobState Failed +PS> Get-Job -Name Job4 -ChildJobState Failed Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 2 Job2 BackgroundJob Completed True localhost .\Get-Archive.ps1 @@ -294,16 +325,18 @@ Id Name PSJobTypeName State HasMoreData Location 10 UpdateHelpJob PSScheduledJob Completed True localhost Update-Help The fifth command uses the **JobStateInfo** property of jobs and its **Reason** property to find out why Job5 failed. -PS C:\> (Get-Job -Name Job5).JobStateInfo.Reason +PS> (Get-Job -Name Job5).JobStateInfo.Reason Connecting to remote server Server01 failed with the following error message : Access is denied. For more information, see the about_Remote_Troubleshooting Help topic. ``` This example shows the effect of using the **IncludeChildJob** and **ChildJobState** parameters of the **Get-Job** cmdlet. + ## PARAMETERS ### -Command + Gets the jobs that include the specified command. The default is all jobs. Enter a command (as a string). @@ -322,6 +355,7 @@ Accept wildcard characters: False ``` ### -Filter + Gets jobs that satisfy all of the conditions established in the associated hash table. Enter a hash table where the keys are job properties and the values are job property values. @@ -344,6 +378,7 @@ Accept wildcard characters: False ``` ### -Id + Gets only jobs with the specified IDs. The ID is an integer that uniquely identifies the job within the current session. @@ -364,6 +399,7 @@ Accept wildcard characters: False ``` ### -IncludeChildJob + Returns child jobs, in addition to parent jobs. This parameter is particularly useful for investigating workflow jobs, for which **Get-Job** returns a container parent job, and job failures, because the reason for the failure is saved in a property of the child job. @@ -383,6 +419,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Gets jobs with the specified instance IDs. The default is all jobs. @@ -402,6 +439,7 @@ Accept wildcard characters: False ``` ### -Name + Gets the job with the specified friendly names. Enter a job name, or use wildcard characters to enter a job name pattern. By default, **Get-Job** gets all jobs in the current session. @@ -419,6 +457,7 @@ Accept wildcard characters: False ``` ### -State + Gets only jobs in the specified state. Valid values are NotStarted, Running, Completed, Failed, Stopped, Blocked, Suspended, Disconnected, Suspending, Stopping. By default, **Get-Job** gets all the jobs in the current session. @@ -438,6 +477,7 @@ Accept wildcard characters: False ``` ### -After + Gets completed jobs that ended after the specified date and time. Enter a **DateTime** object, such as one returned by the Get-Date cmdlet or a string that can be converted to a **DateTime** object, such as "Dec 1, 2012 2:00 AM" or "11/06". @@ -460,6 +500,7 @@ Accept wildcard characters: False ``` ### -Before + Gets completed jobs that ended before the specified date and time. Enter a **DateTime** object, such as one returned by the Get-Date cmdlet or a string that can be converted to a **DateTime** object, such as "Dec 1, 2012 2:00 AM" or "11/06". @@ -482,6 +523,7 @@ Accept wildcard characters: False ``` ### -ChildJobState + Gets only the child jobs that have the specified state. Valid values are: **NotStarted**, **Running**, **Completed**, **Failed**, **Stopped**, **Blocked**, **Suspended**, **Disconnected**, **Suspending**, and **Stopping**. @@ -504,6 +546,7 @@ Accept wildcard characters: False ``` ### -HasMoreData + Gets only jobs with the specified **HasMoreData** property value. The **HasMoreData** property indicates whether all job results have been received in the current session. To get jobs that have more results, type `-HaveMoreData:true`. @@ -535,6 +578,7 @@ Accept wildcard characters: False ``` ### -Newest + Gets the jobs that ended most recently. Enter the number of jobs to return. @@ -556,23 +600,31 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### System.Management.Automation.RemotingJob + **Get-Job** returns objects that represent the jobs in the session. + ## NOTES -* The **PSJobTypeName** property of jobs indicates the job type of the job. The property value is determined by the job type author. The following list shows common job types. + +- The **PSJobTypeName** property of jobs indicates the job type of the job. The property value is determined by the job type author. The following list shows common job types. - **BackgroundJob**: Local job started by using the Start-Job cmdlet. - **RemoteJob**: Job started in a PSSession by using the **AsJob** parameter of the Invoke-Command cmdlet. - **PSWorkflowJob**: Job started by using the **AsJob** common parameter of workflows. + ## RELATED LINKS [Invoke-Command](Invoke-Command.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-Module.md b/reference/3.0/Microsoft.PowerShell.Core/Get-Module.md index c7f836659460..24e0495f7475 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-Module.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-Module.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,34 +7,41 @@ online version: http://go.microsoft.com/fwlink/?LinkID=141552 external help file: System.Management.Automation.dll-Help.xml title: Get-Module --- - # Get-Module + ## SYNOPSIS + Gets the modules that have been imported or that can be imported into the current session. + ## SYNTAX ### Loaded (Default) + ``` Get-Module [[-Name] ] [-All] [] ``` ### Available + ``` Get-Module [[-Name] ] [-All] [-ListAvailable] [-Refresh] [] ``` ### PsSession + ``` Get-Module [[-Name] ] [-ListAvailable] [-Refresh] -PSSession [] ``` ### CimSession + ``` Get-Module [[-Name] ] [-ListAvailable] [-Refresh] -CimSession [-CimResourceUri ] [-CimNamespace ] [] ``` ## DESCRIPTION + The **Get-Module** cmdlet gets the Windows PowerShell modules that have been imported, or that can be imported, into a Windows PowerShell session. The module object that **Get-Module** returns contains valuable information about the module. You can also pipe the module objects to other cmdlets, such as the Import-Module and Remove-Module cmdlets. @@ -65,32 +72,40 @@ Begin by creating a "CIM session" on the remote computer; a connection to Windo Then use the **CIMSession** parameter of **Get-Module** to get CIM modules from the CIM session. When you import a CIM module (by using the **Import-Module** cmdlet) and then run the imported commands, the commands run implicitly on the remote computer. You can use this WMI and CIM strategy to manage the remote computer. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Get-Module +PS> Get-Module ``` This command gets modules that have been imported into the current session. + ### Example 2 + ``` -PS C:\> Get-Module -ListAvailable +PS> Get-Module -ListAvailable ``` This command gets the modules that are installed on the computer and can be imported into the current session. **Get-Module** looks for available modules in the path specified by the **$env:PSModulePath** environment variable. For more information about **PSModulePath**, see about_Modules and about_Environment_Variables. + ### Example 3 + ``` -PS C:\> Get-Module -ListAvailable -All +PS> Get-Module -ListAvailable -All ``` This command gets all of the exported files for all available modules. + ### Example 4 + ``` -PS C:\> Get-Module | Get-Member -MemberType Property | Format-Table Name +PS> Get-Module | Get-Member -MemberType Property | Format-Table Name Name @@ -182,8 +197,9 @@ For more information about the properties, see [PSModuleInfo Properties](http:// The output includes the new properties, such as **Author** and **CompanyName**, that were introduced in Windows PowerShell 3.0 ### Example 5 + ``` -PS C:\> Get-Module -ListAvailable -All | Format-Table -Property Name, Moduletype, Path -Groupby Name +PS> Get-Module -ListAvailable -All | Format-Table -Property Name, Moduletype, Path -Groupby Name Name: AppLocker @@ -234,13 +250,15 @@ BitsTransfer Manifest C:\Windows\system32\WindowsPowerShell\v1.0\Modules\BitsT This command gets all module files (imported and available) and groups them by module name. This lets you see the module files that each script is exporting. + ### Example 6 + ``` The first command gets the **PSModuleInfo** object that represents BitsTransfer module. It saves the object in the $m variable. -PS C:\> $m = Get-Module -list -Name BitsTransfer +PS> $m = Get-Module -list -Name BitsTransfer The second command uses the Get-Content cmdlet to get the content of the manifest file in the specified path. It uses dot notation to get the path to the manifest file, which is stored in the **Path** property of the object.The output shows the contents of the module manifest. -PS C:\> Get-Content $m.Path +PS> Get-Content $m.Path @{ GUID="{8FA5064B-8479-4c5c-86EA-0D311FE48875}" @@ -261,9 +279,11 @@ These commands display the contents of the module manifest for the Windows Power Modules are not required to have manifest files and, when they do have a manifest file, the manifest file is required only to include a version number. However, manifest files often provide useful information about a module, its requirements, and its contents. + ### Example 7 + ``` -PS C:\> dir (Get-Module -ListAvailable FileTransfer).ModuleBase +PS> dir (Get-Module -ListAvailable FileTransfer).ModuleBase Directory: C:\Windows\system32\WindowsPowerShell\v1.0\Modules\FileTransfer Mode LastWriteTime Length Name ---- ------------- ------ ---- @@ -276,11 +296,13 @@ d---- 12/16/2008 12:36 PM en-US This command lists the files in the module's directory. This is another way to determine what is in a module before you import it. Some modules might have help files or ReadMe files that describe the module. + ### Example 8 + ``` -PS C:\> $s = New-PSSession -ComputerName Server01 +PS> $s = New-PSSession -ComputerName Server01 -PS C:\> Get-Module -PSSession $s -ListAvailable +PS> Get-Module -PSSession $s -ListAvailable ``` These commands get the modules that are installed on the Server01 computer. @@ -294,16 +316,18 @@ If you pipe modules from other sessions to the **Import-Module** cmdlet, **Impor This is equivalent to using the Import-PSSession cmdlet. You can use the cmdlets from the module in the current session, but commands that use these cmdlets actually run the remote session. For more information, see Import-Module and Import-PSSession. + ### Example 9 + ``` The first command uses the **New-CimSession** cmdlet to create a session on the RSDGF03 remote computer. The session connects to WMI on the remote computer. The command saves the CIM session in the $cs variable. -PS C:\> $cs = New-CimSession -ComputerName RSDGF03 +PS> $cs = New-CimSession -ComputerName RSDGF03 The second command uses in the CIM session in the $cs variable to run a **Get-Module** command on the RSDGF03 computer. The command uses the **Name** parameter to specify the Storage module.The command uses a pipeline operator (|) to send the Storage module to the **Import-Module** cmdlet, which imports it into the local session. -PS C:\> Get-Module -CimSession $cs -Name Storage | Import-Module +PS> Get-Module -CimSession $cs -Name Storage | Import-Module The third command runs the **Get-Command** cmdlet on the **Get-Disk** command in the Storage module.When you import a CIM module into the local session, Windows PowerShell converts the CDXML files that represent in the CIM module into Windows PowerShell scripts, which appear as functions in the local session. -PS C:\> Get-Command Get-Disk +PS> Get-Command Get-Disk CommandType Name ModuleName ----------- ---- ---------- @@ -311,7 +335,7 @@ CommandType Name ModuleName Function Get-Disk Storage The fourth command runs the **Get-Disk** command. Although the command is typed in the local session, it runs implicitly on the remote computer from which it was imported.The command gets objects from the remote computer and returns them to the local session. -PS C:\> Get-Disk +PS> Get-Disk Number Friendly Name OperationalStatus Total Size Partition Style ------ ------------- ----------------- ---------- --------------- @@ -321,9 +345,11 @@ Number Friendly Name OperationalStatus Total Size Partitio The commands in this example enable you to manage the storage systems of a remote computer that is not running a Windows operating system. In this example, because the administrator of the computer has installed the Module Discovery WMI provider, the CIM commands can use the default values, which are designed for the provider. + ## PARAMETERS ### -All + Gets all modules in each module folder, including nested modules, manifest (.psd1) files, script module (.psm1) files, and binary module (.dll) files. Without the **All** parameter, Get-Module gets only the default module in each module folder. @@ -340,6 +366,7 @@ Accept wildcard characters: False ``` ### -CimNamespace + Specifies the namespace of an alternate CIM provider that exposes CIM modules. The default value is the namespace of the Module Discovery WMI provider. @@ -360,6 +387,7 @@ Accept wildcard characters: False ``` ### -CimResourceUri + Specifies an alternate location for CIM modules. The default value is the resource URI of the Module Discovery WMI provider on the remote computer. @@ -380,6 +408,7 @@ Accept wildcard characters: False ``` ### -ListAvailable + 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. @@ -410,6 +439,7 @@ Accept wildcard characters: False ``` ### -Name + Gets only modules with the specified names or name patterns. Wildcards are permitted. You can also pipe the names to **Get-Module**. @@ -427,6 +457,7 @@ Accept wildcard characters: True ``` ### -CimSession + Specifies a CIM session on the remote computer. Enter a variable that contains the CIM session or a command that gets the CIM session, such as a [Get-CimSession](https://docs.microsoft.com/en-us/powershell/module/cimcmdlets/get-cimsession) command. @@ -451,6 +482,7 @@ Accept wildcard characters: False ``` ### -PSSession + Gets the modules in the specified user-managed Windows PowerShell session (PSSession). Enter a variable that contains the session, a command that gets the session, such as a Get-PSSession command, or a command that creates the session, such as a New-PSSession command. @@ -473,6 +505,7 @@ Accept wildcard characters: False ``` ### -Refresh + Refreshes the cache of installed commands. The command cache is created when the session starts. It enables the Get-Command cmdlet to get commands from modules that are not imported into the session. @@ -496,34 +529,42 @@ 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 module names to **Get-Module**. + ## OUTPUTS ### System.Management.Automation.PSModuleInfo + Get-Module returns objects that represent modules. When you use the **ListAvailable** parameter, Get-Module returns a **ModuleInfoGrouping** object, which is a type of **PSModuleInfo** object that has the same properties and methods. + ## NOTES -* Beginning in Windows PowerShell 3.0, the core commands that are included in Windows PowerShell are packaged in modules. The exception is **Microsoft.PowerShell.Core**, which is a snap-in (PSSnapin). By default, only the **Microsoft.PowerShell.Core** snap-in is added to the session by default. Modules are imported automatically on first use and you can use the Import-Module cmdlet to import them. -* Beginning in Windows PowerShell 3.0, the core commands that are installed with Windows PowerShell are packaged in modules. In Windows PowerShell 2.0, and in host programs that create older-style sessions in later versions of Windows PowerShell, the core commands are packaged in snap-ins ("PSSnapins"). The exception is **Microsoft.PowerShell.Core**, which is always a snap-in. Also, remote sessions, such as those started by the New-PSSession cmdlet, are older-style sessions that include core snap-ins. + +- Beginning in Windows PowerShell 3.0, the core commands that are included in Windows PowerShell are packaged in modules. The exception is **Microsoft.PowerShell.Core**, which is a snap-in (PSSnapin). By default, only the **Microsoft.PowerShell.Core** snap-in is added to the session by default. Modules are imported automatically on first use and you can use the Import-Module cmdlet to import them. +- Beginning in Windows PowerShell 3.0, the core commands that are installed with Windows PowerShell are packaged in modules. In Windows PowerShell 2.0, and in host programs that create older-style sessions in later versions of Windows PowerShell, the core commands are packaged in snap-ins ("PSSnapins"). The exception is **Microsoft.PowerShell.Core**, which is always a snap-in. Also, remote sessions, such as those started by the New-PSSession cmdlet, are older-style sessions that include core snap-ins. For information about the **CreateDefault2** method that creates newer-style sessions with core modules, see [CreateDefault2 Method](https://msdn.microsoft.com/library/system.management.automation.runspaces.initialsessionstate.createdefault2) in the MSDN library. -* **Get-Module** only gets modules in locations that are stored in the value of the **PSModulePath** environment variable ($env:PSModulePath). You can use the **Path** parameter of the Import-Module cmdlet to import modules in other locations, but you cannot use the **Get-Module** cmdlet to get them. -* Also, beginning in Windows PowerShell 3.0, new properties have been added to the object that **Get-Module** returns that make it easier to learn about modules even before they are imported. All properties are populated before importing, including the **ExportedCommands**, **ExportedCmdlets** and **ExportedFunctions** properties that list the commands that the module exports. -* The **ListAvailable** parameter gets only well-formed modules, that is, folders that contain at least one file whose base name (the name without the file name extension) is the same as the name of the module folder. Folders that contain files with different names are considered to be containers, but not modules. +- **Get-Module** only gets modules in locations that are stored in the value of the **PSModulePath** environment variable ($env:PSModulePath). You can use the **Path** parameter of the Import-Module cmdlet to import modules in other locations, but you cannot use the **Get-Module** cmdlet to get them. +- Also, beginning in Windows PowerShell 3.0, new properties have been added to the object that **Get-Module** returns that make it easier to learn about modules even before they are imported. All properties are populated before importing, including the **ExportedCommands**, **ExportedCmdlets** and **ExportedFunctions** properties that list the commands that the module exports. +- The **ListAvailable** parameter gets only well-formed modules, that is, folders that contain at least one file whose base name (the name without the file name extension) is the same as the name of the module folder. Folders that contain files with different names are considered to be containers, but not modules. To get modules that are implemented as .dll files, but are not enclosed in a module folder, use both the **ListAvailable** and **All** parameters. -* To use the CIM session feature, the remote computer must have WS-Management remoting and Windows Management Instrumentation (WMI), which is the Microsoft implementation of the Common Information Model (CIM) standard. The computer must also have the Module Discovery WMI provider or an alternate WMI provider that has the same basic features. +- To use the CIM session feature, the remote computer must have WS-Management remoting and Windows Management Instrumentation (WMI), which is the Microsoft implementation of the Common Information Model (CIM) standard. The computer must also have the Module Discovery WMI provider or an alternate WMI provider that has the same basic features. You can use the CIM session feature on computers that are not running a Windows operating system and on Windows computers that have Windows PowerShell, but do not have Windows PowerShell remoting enabled. You can also use the CIM parameters to get CIM modules from computers that have Windows PowerShell remoting enabled, including the local computer. When you create a CIM session on the local computer, Windows PowerShell uses DCOM, instead of WMI, to create the session. + ## RELATED LINKS [Get-CimSession](https://docs.microsoft.com/en-us/powershell/module/cimcmdlets/get-cimsession) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Get-PSSession.md index f6f170411334..88fdcd00c806 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-PSSession.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,18 +7,22 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135219 external help file: System.Management.Automation.dll-Help.xml title: Get-PSSession --- - # Get-PSSession + ## SYNOPSIS + Gets the Windows PowerShell sessions on local and remote computers. + ## SYNTAX ### Name (Default) + ``` Get-PSSession [-Name ] [] ``` ### ComputerName + ``` Get-PSSession [-ComputerName] [-ApplicationName ] [-ConfigurationName ] [-Name ] [-Credential ] [-Authentication ] @@ -27,6 +31,7 @@ Get-PSSession [-ComputerName] [-ApplicationName ] [-Configura ``` ### ComputerInstanceId + ``` Get-PSSession [-ComputerName] [-ApplicationName ] [-ConfigurationName ] -InstanceId [-Credential ] [-Authentication ] @@ -35,6 +40,7 @@ Get-PSSession [-ComputerName] [-ApplicationName ] [-Configura ``` ### ConnectionUri + ``` Get-PSSession [-ConnectionUri] [-ConfigurationName ] [-AllowRedirection] [-Name ] [-Credential ] [-Authentication ] [-CertificateThumbprint ] @@ -42,6 +48,7 @@ Get-PSSession [-ConnectionUri] [-ConfigurationName ] [-AllowRedi ``` ### ConnectionUriInstanceId + ``` Get-PSSession [-ConnectionUri] [-ConfigurationName ] [-AllowRedirection] -InstanceId [-Credential ] [-Authentication ] [-CertificateThumbprint ] @@ -49,16 +56,19 @@ Get-PSSession [-ConnectionUri] [-ConfigurationName ] [-AllowRedi ``` ### InstanceId + ``` Get-PSSession [-InstanceId ] [] ``` ### Id + ``` Get-PSSession [-Id] [] ``` ## DESCRIPTION + The **Get-PSSession** cmdlet gets the user-managed Windows PowerShell sessions ("PSSessions") on local and remote computers. Beginning in Windows PowerShell 3.0, sessions are stored on the computers at the remote end of each connection. @@ -74,27 +84,33 @@ NOTE: In Windows PowerShell 2.0, without parameters, **Get-PSSession** gets all The **ComputerName** parameter gets sessions that were created in the current session and connect to the specified computer. For more information about Windows PowerShell sessions, see about_PSSessions (http://go.microsoft.com/fwlink/?LinkID=135181). + ## EXAMPLES ### Example 1 + ``` -PS C:\> Get-PSSession +PS> Get-PSSession ``` This command gets all of 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 they connect to this computer. + ### Example 2 + ``` -PS C:\> Get-PSSession -ComputerName localhost +PS> Get-PSSession -ComputerName localhost ``` This command gets the PSSessions that are connected to the local computer. To indicate the local computer, type the computer name, "localhost" or a dot (.) The command returns all of the sessions on the local computer, even if they were created in different sessions or on different computers. + ### Example 3 + ``` -PS C:\> Get-PSSession -ComputerName Server02 +PS> Get-PSSession -ComputerName Server02 Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 2 Session3 Server02 Disconnected ITTasks Busy @@ -109,10 +125,12 @@ The command returns all of the sessions on Server02, even if they were created i The output shows that two of the sessions have a Disconnected state and a Busy availability. They were created in different sessions and are currently in use. The "ScheduledJobs" session, which is Opened and Available, was created in the current session. + ### Example 4 + ``` -PS C:\> New-PSSession -ComputerName Server01, Server02, Server03 -PS C:\> $s1, $s2, $s3 = Get-PSSession +PS> New-PSSession -ComputerName Server01, Server02, Server03 +PS> $s1, $s2, $s3 = Get-PSSession ``` This example shows how to save the results of a Get-PSSession command in multiple variables. @@ -125,11 +143,13 @@ It then saves each of the PSSessions in a separate variable. When Windows PowerShell assigns an array of objects to an array of variables, it assigns the first object to the first variable, the second object to the second variable, and so on. If there are more objects than variables, it assigns all remaining objects to the last variable in the array. If there are more variables than objects, the extra variables are not used. + ### Example 5 + ``` -PS C:\> Get-PSSession | Format-Table -Property ComputerName, InstanceID -PS C:\> $s = Get-PSSession -InstanceID a786be29-a6bb-40da-80fb-782c67f7db0f -PS C:\> Remove-PSSession -Session $s +PS> Get-PSSession | Format-Table -Property ComputerName, InstanceID +PS> $s = Get-PSSession -InstanceID a786be29-a6bb-40da-80fb-782c67f7db0f +PS> Remove-PSSession -Session $s ``` This example shows how to get a PSSession by using its instance ID, and then to delete the PSSession. @@ -141,19 +161,21 @@ The second command uses the **Get-PSSession** cmdlet to get a particular PSSessi The command uses the **InstanceID** parameter to identify the PSSession. The third command uses the Remove-PSSession cmdlet to delete the PSSession in the $s variable. + ### Example 6 + ``` The first command gets sessions on the Server02 and Server12 remote computers that have names that begin with "BackupJob" and use the ITTasks session configuration.The command uses the **Name** parameter to specify the name pattern and the **ConfigurationName** parameter to specify the session configuration. The value of the **SessionOption** parameter is a hash table that sets the value of the **OperationTimeout** to 240000 milliseconds (4 minutes). This setting gives the command more time to complete.The **ConfigurationName** and **SessionOption** parameters are used to configure the temporary sessions in which the **Get-PSSession** cmdlet runs on each computer.The output shows that the command returns the BackupJob04 session. The session is disconnected and the Availability is None, which indicates that it is not in use. -PS C:\> Get-PSSession -ComputerName Server02, Server12 -Name BackupJob* -ConfigurationName ITTasks -SessionOption @{OperationTimeout=240000} +PS> Get-PSSession -ComputerName Server02, Server12 -Name BackupJob* -ConfigurationName ITTasks -SessionOption @{OperationTimeout=240000} Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 3 BackupJob04 Server02 Disconnected ITTasks None The second command uses the **Get-PSSession** cmdlet to get to the BackupJob04 session and the Connect-PSSession cmdlet to connect to the session. The command saves the session in the $s variable. -PS C:\> $s = Get-PSSession -ComputerName Server02 -Name BackupJob04 -ConfigurationName ITTasks | Connect-PSSession +PS> $s = Get-PSSession -ComputerName Server02 -Name BackupJob04 -ConfigurationName ITTasks | Connect-PSSession The third command gets the session in the $s variable. The output shows that the **Connect-PSSession** command was successful. The session is in the **Opened** state and is available for use. -PS C:\> $s +PS> $s Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 5 BackupJob04 Server02 Opened ITTasks Available @@ -161,16 +183,20 @@ Id Name ComputerName State ConfigurationName Availabil The commands in this example find a session that has a particular name format and uses a particular session configuration and then connect to the session. You can use a command like this one to find a session in which a colleague started a task and connect to finish the task. + ### Example 7 + ``` -PS C:\> Get-PSSession -ID 2 +PS> Get-PSSession -ID 2 ``` This command gets the PSSession with ID 2. Because the value of the ID property is unique only in the current session, the ID parameter is valid only for local commands. + ## PARAMETERS ### -Authentication + Specifies the mechanism that is used to authenticate credentials for the session in which the **Get-PSSession** command runs. This parameter configures the temporary connection that is created to run a **Get-PSSession** command with the **ComputerName** or **ConnectionUri** parameter. @@ -199,6 +225,7 @@ Accept wildcard characters: False ``` ### -CertificateThumbprint + Specifies the digital public key certificate (X509) of a user account that has permission to create the session in which the **Get-PSSession** command runs. Enter the certificate thumbprint of the certificate. @@ -224,6 +251,7 @@ Accept wildcard characters: False ``` ### -ComputerName + Gets the sessions that connect to the specified computers. Wildcards are not permitted. There is no default value. @@ -250,6 +278,7 @@ Accept wildcard characters: False ``` ### -Credential + Runs the command with the permissions of the specified user. Specify a user account that has permission to connect to the remote computer and run a **Get-PSSession** command. The default is the current user. @@ -273,6 +302,7 @@ Accept wildcard characters: False ``` ### -Id + Gets only the sessions with the specified IDs. Type one or more IDs (separated by commas), or use the range operator (..) to specify a range of IDs. You cannot use the ID parameter with the **ComputerName** parameter. @@ -294,6 +324,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Gets only the sessions with the specified instance IDs. The instance ID is a GUID that uniquely identifies a session on a local or remote computer. @@ -326,6 +357,7 @@ Accept wildcard characters: False ``` ### -Name + Gets only the sessions with the specified friendly names. Wildcards are permitted. @@ -356,6 +388,7 @@ Accept wildcard characters: False ``` ### -Port + Specifies the specified network port that is used for the temporary connection in which the **Get-PSSession** command runs. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). @@ -389,6 +422,7 @@ Accept wildcard characters: False ``` ### -State + Gets only sessions in the specified state. Valid values are: All, Opened, Disconnected, Closed, and Broken. The default value is All. @@ -413,6 +447,7 @@ Accept wildcard characters: False ``` ### -ThrottleLimit + Specifies the maximum number of concurrent connections that can be established to run the **Get-PSSession** command. If you omit this parameter or enter a value of 0 (zero), the default value, 32, is used. The throttle limit applies only to the current command, not to the session or to the computer. @@ -432,6 +467,7 @@ Accept wildcard characters: False ``` ### -UseSSL + Uses the Secure Sockets Layer (SSL) protocol to establish the connection in which the **Get-PSSession** command runs. By default, SSL is not used. If you use this parameter, but SSL is not available on the port used for the command, the command fails. @@ -453,6 +489,7 @@ Accept wildcard characters: False ``` ### -AllowRedirection + Allows redirection of this connection to an alternate Uniform Resource Identifier (URI). By default, Windows PowerShell does not redirect connections. @@ -473,6 +510,7 @@ Accept wildcard characters: False ``` ### -ApplicationName + Connects only to sessions that use the specified application. Enter the application name segment of the connection URI. @@ -495,6 +533,7 @@ Accept wildcard characters: False ``` ### -ConfigurationName + Gets only to sessions that use the specified session configuration. Enter a configuration name or the fully qualified resource URI for a session configuration. @@ -519,6 +558,7 @@ Accept wildcard characters: False ``` ### -ConnectionUri + Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint for the temporary session in which the **Get-PSSession** command runs. The URI must be fully qualified. @@ -553,6 +593,7 @@ Accept wildcard characters: False ``` ### -SessionOption + Sets advanced options for the session. Enter a **SessionOption** object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. @@ -579,21 +620,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). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### System.Management.Automation.Runspaces.PSSession ## NOTES -* **Get-PSSession** gets user-managed sessions "PSSessions," such as those that are created by using the New-PSSession, Enter-PSSession, and Invoke-Command cmdlets. It does not get the system-managed session that is created when you start Windows PowerShell. -* Beginning in Windows PowerShell 3.0, PSSessions are stored on the computer that is at the "server-side" or receiving end of a connection. To get the sessions that are stored on the local computer or a remote computer, Windows PowerShell establishes a temporary session to the specified computer and runs query commands in the session. -* To get sessions that connect to a remote computer, use the **ComputerName** or **ConnectionUri** parameters to specify the remote computer. To filter the sessions that **Get-PSSession** gets, use the **Name**, **ID**, **InstanceID**, and **State** parameters. Use the remaining parameters to configure the temporary session that **Get-PSSession** uses. -* When you use the **ComputerName** or **ConnectionUri** parameters, **Get-PSSession** gets only sessions from computers running Windows PowerShell 3.0 and later versions of Windows PowerShell. -* The value of the **State** property of a PSSession is relative to the current session. Therefore, a value of **Disconnected** means that the PSSession is not connected to the current session. However, it does not mean that the PSSession is disconnected from all sessions. It might be connected to a different session. To determine whether you can connect or reconnect to the PSSession from the current session, use the **Availability** property. + +- **Get-PSSession** gets user-managed sessions "PSSessions," such as those that are created by using the New-PSSession, Enter-PSSession, and Invoke-Command cmdlets. It does not get the system-managed session that is created when you start Windows PowerShell. +- Beginning in Windows PowerShell 3.0, PSSessions are stored on the computer that is at the "server-side" or receiving end of a connection. To get the sessions that are stored on the local computer or a remote computer, Windows PowerShell establishes a temporary session to the specified computer and runs query commands in the session. +- To get sessions that connect to a remote computer, use the **ComputerName** or **ConnectionUri** parameters to specify the remote computer. To filter the sessions that **Get-PSSession** gets, use the **Name**, **ID**, **InstanceID**, and **State** parameters. Use the remaining parameters to configure the temporary session that **Get-PSSession** uses. +- When you use the **ComputerName** or **ConnectionUri** parameters, **Get-PSSession** gets only sessions from computers running Windows PowerShell 3.0 and later versions of Windows PowerShell. +- The value of the **State** property of a PSSession is relative to the current session. Therefore, a value of **Disconnected** means that the PSSession is not connected to the current session. However, it does not mean that the PSSession is disconnected from all sessions. It might be connected to a different session. To determine whether you can connect or reconnect to the PSSession from the current session, use the **Availability** property. An **Availability** value of **None** indicates that you can connect to the session. A value of **Busy** indicates that you cannot connect to the PSSession because it is connected to another session. diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md b/reference/3.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md index 6a10a55be129..b2ea50a1da33 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-PSSessionConfiguration.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=144304 external help file: System.Management.Automation.dll-Help.xml title: Get-PSSessionConfiguration --- - # Get-PSSessionConfiguration + ## SYNOPSIS + Gets the registered session configurations on the computer. + ## SYNTAX ``` @@ -18,6 +20,7 @@ Get-PSSessionConfiguration [[-Name] ] [] ``` ## DESCRIPTION + The **Get-PSSessionConfiguration** cmdlet gets the session configurations that have been registered on the local computer. This is an advanced cmdlet that is designed to be used by system administrators to manage customized session configurations for their users. @@ -30,17 +33,21 @@ These properties make it easier for users and session configuration authors to e To create and register a session configuration, use the Register-PSSessionConfiguration cmdlet. For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). + ## EXAMPLES ### Example 1 + ``` -PS C:\> Get-PSSessionConfiguration +PS> Get-PSSessionConfiguration ``` This command gets the session configurations on the local computer. + ### Example 2 + ``` -PS C:\> Get-PSSessionConfiguration -Name Microsoft* +PS> Get-PSSessionConfiguration -Name Microsoft* Name PSVersion StartupScript Permission ---- --------- ------------- ---------- @@ -50,9 +57,11 @@ microsoft.powershell32 2.0 BUILTIN\Administrators This command gets the two default session configurations that come with Windows PowerShell. The command uses the **Name** parameter of **Get-PSSessionConfiguration** to get only the session configurations with names that begin with "Microsoft". + ### Example 3 + ``` -PS C:\> Get-PSSessionConfiguration -Name Full | Format-List -Property * +PS> Get-PSSessionConfiguration -Name Full | Format-List -Property * Copyright : (c) 2011 User01. All rights reserved. @@ -105,9 +114,11 @@ The output of this command has very useful information, including the author of This view of a session configuration is used for sessions that include a session configuration file. For more information about session configuration files, see about_Session_Configuration_Files (http://go.microsoft.com/fwlink/?LinkID=236023). + ### Example 4 + ``` -PS C:\> (Get-PSSessionConfiguration Microsoft.PowerShell.Workflow).PSObject.Properties | Select-Object Name,Value | Sort-Object Name +PS> (Get-PSSessionConfiguration Microsoft.PowerShell.Workflow).PSObject.Properties | Select-Object Name,Value | Sort-Object Name Name Value @@ -220,9 +231,11 @@ This command gets the properties of the Microsoft.PowerShell.Worfklow session co You can use this command format in a function to get this display for any session configuration. This example was contributed by Shay Levy, a Windows PowerShell MVP from Sderot, Israel. + ### Example 5 + ``` -PS C:\> dir wsman:\localhost\plugin +PS> dir wsman:\localhost\plugin Type Keys Name ---- ---- ---- Container {Name=Event Forwarding Plugin} Event Forwarding Plugin @@ -238,13 +251,15 @@ This command uses the Get-ChildItem cmdlet (alias = dir) in the WSMan: provider This is another way to look at the session configurations on the computer. The **PlugIn** node contains **ContainerElement** objects (Microsoft.WSMan.Management.WSManConfigContainerElement) that represent the registered Windows PowerShell session configurations, along with other plug-ins for WS-Management. + ### Example 6 + ``` The first command uses the Connect-WSMan cmdlet to connect to the WinRM service on the Server01 remote computer. -PS C:\> Connect-WSMan -ComputerName Server01 +PS> Connect-WSMan -ComputerName Server01 The second command uses the Get-ChildItem cmdlet ("dir") in the WSMan: drive to get the items in the Server01\Plugin path.The output shows the items in the Plugin directory on the Server01 computer. The items include the session configurations, which are a type of WSMan plug-in, along with other types of plug-ins on the computer. -PS C:\> dir WSMan:\Server01\Plugin +PS> dir WSMan:\Server01\Plugin WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin Type Keys Name @@ -264,7 +279,7 @@ Container {Name=WithProfile} WithProfile Container {Name=WMI Provider} WMI Provider The third command returns the names of the plugins that are session configurations. The command searches for a value of **Shell** in the **Capability** property, which is in the Plugin\Resources\ path in the WSMan: drive. -PS C:\> dir WSMan:\Server01\Plugin\*\Resources\Resource*\Capability | where {$_.Value -eq "Shell"} | foreach {($_.PSPath.split("\"))[3] } +PS> dir WSMan:\Server01\Plugin\*\Resources\Resource*\Capability | where {$_.Value -eq "Shell"} | foreach {($_.PSPath.split("\"))[3] } Empty Full microsoft.powershell @@ -279,19 +294,21 @@ WithProfile This example shows how to use the WSMan provider to view the session configurations on a remote computer. This method does not provide as much information as a **Get-PSSessionConfiguration** command, but the user does not need to be a member of the Administrators group to run this command. + ### Example 7 + ``` The first command uses the Enable-WSManCredSSP cmdlet to enable **CredSSP** delegation from the Server01 local computer to the Server02 remote computer. This configures the **CredSSP** client setting on the local computer. -PS C:\> Enable-WSManCredSSP -Delegate Server02 +PS> Enable-WSManCredSSP -Delegate Server02 The second command uses the Connect-WSMan cmdlet to connect to the Server02 computer. This action adds a node for the Server02 computer to the WSMan: drive on the local computer, allowing you to view and change the WS-Management settings on the Server02 computer. -PS C:\> Connect-WSMan Server02 +PS> Connect-WSMan Server02 The third command uses the Set-Item cmdlet to change the value of the **CredSSP** item in the Service node of the Server02 computer to True. This configures the service settings on the remote computer. -PS C:\> Set-Item WSMan:\Server02*\Service\Auth\CredSSP -Value $true +PS> Set-Item WSMan:\Server02*\Service\Auth\CredSSP -Value $true The fourth command uses the Invoke-Command cmdlet to run a **Get-PSSessionConfiguration** command on the Server02 computer. The command uses the **Credential** parameter, and it uses the **Authentication** parameter with a value of **CredSSP**.The output shows the session configurations on the Server02 remote computer. -PS C:\> Invoke-Command -ScriptBlock {Get-PSSessionConfiguration} -ComputerName Server02 -Authentication CredSSP -Credential Domain01\Admin01 +PS> Invoke-Command -ScriptBlock {Get-PSSessionConfiguration} -ComputerName Server02 -Authentication CredSSP -Credential Domain01\Admin01 Name PSVersion StartupScript Permission PSComputerName ---- --------- ------------- ---------- -------------- @@ -304,9 +321,11 @@ This example shows how to run a **Get-PSSessionConfiguration** command on a remo The command requires that CredSSP delegation be enabled in the client settings on the local computer and in the service settings on the remote computer. To run the commands in this example, you must be a member of the Administrators group on the local computer and the remote computer and you must start Windows PowerShell with the "Run as administrator" option. + ### Example 8 + ``` -PS C:\> (Get-PSSessionConfiguration -Name CustomShell).resourceURI +PS> (Get-PSSessionConfiguration -Name CustomShell).resourceURI http://schemas.microsoft.com/powershell/microsoft.CustomShell ``` @@ -317,9 +336,11 @@ 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](About/about_Preference_Variables.md). + ## PARAMETERS ### -Name + Gets only the session configurations with the specified name or name pattern. Enter one or more session configuration names. Wildcards are permitted. @@ -337,22 +358,28 @@ Accept wildcard characters: True ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### Microsoft.PowerShell.Commands.PSSessionConfigurationCommands#PSSessionConfiguration ## NOTES -* To run this cmdlet, start Windows PowerShell with the "Run as administrator" option. -* To view the session configurations on the computer, you must be a member of the Administrators group on the computer. -* To run a **Get-PSSessionConfiguration** command on a remote computer, Credential Security Service Provider (CredSSP) authentication must be enabled in the client settings on the local computer (by using the Enable-WSManCredSSP cmdlet) and in the service settings on the remote computer, and you must use the **CredSSP** value of the **Authentication** parameter when establishing the remote session. Otherwise, access is denied. -* The note properties of the object that **Get-PSSessionConfiguration** returns appear on the object only when they have a value. Only session configurations that were created by using a session configuration file have all of the defined properties. -* 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. -* You can use commands in the WSMan: drive to change the properties of session configurations. However, you cannot use the WSMan: drive in Windows PowerShell 2.0 to change session configuration properties that are introduced in Windows PowerShell 3.0, such as **OutputBufferingMode**. Windows PowerShell 2.0 commands do not generate an error, but they are ineffective. To change properties introduced in Windows PowerShell 3.0, use the WSMan: drive in Windows PowerShell 3.0. + +- To run this cmdlet, start Windows PowerShell with the "Run as administrator" option. +- To view the session configurations on the computer, you must be a member of the Administrators group on the computer. +- To run a **Get-PSSessionConfiguration** command on a remote computer, Credential Security Service Provider (CredSSP) authentication must be enabled in the client settings on the local computer (by using the Enable-WSManCredSSP cmdlet) and in the service settings on the remote computer, and you must use the **CredSSP** value of the **Authentication** parameter when establishing the remote session. Otherwise, access is denied. +- The note properties of the object that **Get-PSSessionConfiguration** returns appear on the object only when they have a value. Only session configurations that were created by using a session configuration file have all of the defined properties. +- 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. +- You can use commands in the WSMan: drive to change the properties of session configurations. However, you cannot use the WSMan: drive in Windows PowerShell 2.0 to change session configuration properties that are introduced in Windows PowerShell 3.0, such as **OutputBufferingMode**. Windows PowerShell 2.0 commands do not generate an error, but they are ineffective. To change properties introduced in Windows PowerShell 3.0, use the WSMan: drive in Windows PowerShell 3.0. + ## RELATED LINKS [Disable-PSSessionConfiguration](Disable-PSSessionConfiguration.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Get-PSSnapin.md b/reference/3.0/Microsoft.PowerShell.Core/Get-PSSnapin.md index ec235a24d999..13bb5cfd3257 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Get-PSSnapin.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Get-PSSnapin.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113330 external help file: System.Management.Automation.dll-Help.xml title: Get-PSSnapin --- - # Get-PSSnapin + ## SYNOPSIS + Gets the Windows PowerShell snap-ins on the computer. + ## SYNTAX ``` @@ -18,6 +20,7 @@ Get-PSSnapin [[-Name] ] [-Registered] [] ``` ## DESCRIPTION + The Get-PSSnapin cmdlet gets the Windows PowerShell snap-ins that have been added to the current session or that have been registered on the system. The snap-ins are listed in the order in which they are detected. @@ -29,31 +32,39 @@ Beginning in Windows PowerShell 3.0, the core commands that are included in Wind The exception is **Microsoft.PowerShell.Core**, which is a snap-in (PSSnapin). Only the **Microsoft.PowerShell.Core** snap-in is added to the session by default. Modules are imported automatically on first use and you can use the Import-Module cmdlet to import them. + ## EXAMPLES ### Example 1 + ``` -PS C:\> get-PSSnapIn +PS> get-PSSnapIn ``` This command gets the Windows PowerShell snap-ins that are currently loaded in the session. This includes the snap-ins that are installed with Windows PowerShell and those that have been added to the session. + ### Example 2 + ``` -PS C:\> get-PSSnapIn -registered +PS> get-PSSnapIn -registered ``` This command gets the Windows PowerShell snap-ins that have been registered on the computer, including those that have already been added to the session. The output does not include snap-ins that are installed with Windows PowerShell or Windows PowerShell snap-in dynamic-link libraries (DLLs) that have not yet been registered on the system. + ### Example 3 + ``` -PS C:\> get-PSSnapIn smp* +PS> get-PSSnapIn smp* ``` This command gets the Windows PowerShell snap-ins in the current session that have names that begin with "smp". + ## PARAMETERS ### -Name + Gets only the specified Windows PowerShell snap-ins. Enter the names of one or more Windows PowerShell snap-ins. Wildcards are permitted. @@ -73,6 +84,7 @@ Accept wildcard characters: True ``` ### -Registered + Gets the Windows PowerShell snap-ins that have been registered on the system (even if they have not yet been added to the session). The snap-ins that are installed with Windows PowerShell do not appear in this list. @@ -92,17 +104,24 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to Get-PSSnapin. + ## OUTPUTS ### System.Management.Automation.PSSnapInInfo + Get-PSSnapin returns an object for each snap-in that it gets. + ## NOTES -* Beginning in Windows PowerShell 3.0, the core commands that are installed with Windows PowerShell are packaged in modules. In Windows PowerShell 2.0, and in host programs that create older-style sessions in later versions of Windows PowerShell, the core commands are packaged in snap-ins ("PSSnapins"). The exception is **Microsoft.PowerShell.Core**, which is always a snap-in. Also, remote sessions, such as those started by the New-PSSession cmdlet, are older-style sessions that include core snap-ins. + +- Beginning in Windows PowerShell 3.0, the core commands that are installed with Windows PowerShell are packaged in modules. In Windows PowerShell 2.0, and in host programs that create older-style sessions in later versions of Windows PowerShell, the core commands are packaged in snap-ins ("PSSnapins"). The exception is **Microsoft.PowerShell.Core**, which is always a snap-in. Also, remote sessions, such as those started by the New-PSSession cmdlet, are older-style sessions that include core snap-ins. For information about the **CreateDefault2** method that creates newer-style sessions with core modules, see [CreateDefault2 Method](https://msdn.microsoft.com/library/system.management.automation.runspaces.initialsessionstate.createdefault2) in the MSDN library. diff --git a/reference/3.0/Microsoft.PowerShell.Core/Import-Module.md b/reference/3.0/Microsoft.PowerShell.Core/Import-Module.md index fc1f54b976df..5040b4931344 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Import-Module.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Import-Module.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=141553 external help file: System.Management.Automation.dll-Help.xml title: Import-Module --- - # Import-Module + ## SYNOPSIS + Adds modules to the current session. + ## SYNTAX ### Name (Default) + ``` Import-Module [-Global] [-Prefix ] [-Name] [-Function ] [-Cmdlet ] [-Variable ] [-Alias ] [-Force] [-PassThru] [-AsCustomObject] [-MinimumVersion ] @@ -22,6 +25,7 @@ Import-Module [-Global] [-Prefix ] [-Name] [-Function ] [-Name] [-Function ] [-Cmdlet ] [-Variable ] [-Alias ] [-Force] [-PassThru] [-AsCustomObject] [-MinimumVersion ] @@ -30,6 +34,7 @@ Import-Module [-Global] [-Prefix ] [-Name] [-Function ] [-Name] [-Function ] [-Cmdlet ] [-Variable ] [-Alias ] [-Force] [-PassThru] [-AsCustomObject] [-MinimumVersion ] @@ -38,6 +43,7 @@ Import-Module [-Global] [-Prefix ] [-Name] [-Function ] [-Assembly] [-Function ] [-Cmdlet ] [-Variable ] [-Alias ] [-Force] [-PassThru] [-AsCustomObject] [-ArgumentList ] @@ -45,6 +51,7 @@ Import-Module [-Global] [-Prefix ] [-Assembly] [-Function < ``` ### ModuleInfo + ``` Import-Module [-Global] [-Prefix ] [-Function ] [-Cmdlet ] [-Variable ] [-Alias ] [-Force] [-PassThru] [-AsCustomObject] [-ModuleInfo] @@ -52,6 +59,7 @@ Import-Module [-Global] [-Prefix ] [-Function ] [-Cmdlet Import-Module -Name BitsTransfer +PS> Import-Module -Name BitsTransfer ``` This command imports the members of the **BitsTransfer** module into the current session. @@ -99,16 +109,20 @@ The **Name** parameter name (-Name) is optional and can be omitted. By default, **Import-Module** does not generate any output when it imports a module. To request output, use the **PassThru** or **AsCustomObject** parameter, or the **Verbose** common parameter. + ### Example 2 + ``` -PS C:\> Get-Module -ListAvailable | Import-Module +PS> Get-Module -ListAvailable | Import-Module ``` This command imports all available modules in the path specified by the PSModulePath environment variable ($env:PSModulePath) into the current session. + ### Example 3 + ``` -PS C:\> $m = Get-Module -ListAvailable BitsTransfer, ServerManager -PS C:\> Import-Module -ModuleInfo $m +PS> $m = Get-Module -ListAvailable BitsTransfer, ServerManager +PS> Import-Module -ModuleInfo $m ``` These commands import the members of the **BitsTransfer** and **ServerManager** modules into the current session. @@ -120,9 +134,11 @@ The **ListAvailable** parameter is required when you are getting modules that ar The second command uses the **ModuleInfo** parameter of **Import-Module** to import the modules into the current session. These commands are equivalent to using a pipeline operator (|) to send the output of a **Get-Module** command to **Import-Module**. + ### Example 4 + ``` -PS C:\> Import-Module -Name c:\ps-test\modules\test -Verbose +PS> Import-Module -Name c:\ps-test\modules\test -Verbose VERBOSE: Loading module from path 'C:\ps-test\modules\Test\Test.psm1'. VERBOSE: Exporting function 'my-parm'. VERBOSE: Exporting function 'Get-Parameter'. @@ -136,9 +152,10 @@ It also uses the **Verbose** common parameter to get a list of the items importe Without the **Verbose**, **PassThru**, or **AsCustomObject** parameter, **Import-Module** does not generate any output when it imports a module. ### Example 5 + ``` -PS C:\> Import-Module BitsTransfer -Cmdlet Add-BitsFile, Get-BitsTransfer -PS C:\> (Get-Module BitsTransfer).ExportedCmdlets +PS> Import-Module BitsTransfer -Cmdlet Add-BitsFile, Get-BitsTransfer +PS> (Get-Module BitsTransfer).ExportedCmdlets Key Value --- ----- @@ -151,7 +168,7 @@ Set-BitsTransfer Set-BitsTransfer Start-BitsTransfer Start-BitsTransfer Suspend-BitsTransfer Suspend-BitsTransfer -PS C:\> Get-Command -Module BitsTransfer +PS> Get-Command -Module BitsTransfer CommandType Name Version Source ----------- ---- ------- ------ @@ -172,14 +189,15 @@ The third command uses the **Module** parameter of the Get-Command cmdlet to get The results confirm that only the **Add-BitsFile** and **Get-BitsTransfer** cmdlets were imported. ### Example 6 + ``` -PS C:\> Import-Module BitsTransfer -Prefix PS -PassThru +PS> Import-Module BitsTransfer -Prefix PS -PassThru ModuleType Name ExportedCommands ---------- ---- ---------------- Manifest bitstransfer {Add-BitsFile, Complete-... -PS C:\> Get-Command -Module BitsTransfer +PS> Get-Command -Module BitsTransfer CommandType Name ModuleName ----------- ---- ---------- @@ -212,9 +230,11 @@ The output shows that the module members were correctly prefixed. The prefix that you use applies only to the members in the current session. It does not change the module. + ### Example 7 + ``` -PS C:\> Get-Module -List | Format-Table -Property Name, ModuleType -AutoSize +PS> Get-Module -List | Format-Table -Property Name, ModuleType -AutoSize Name ModuleType ---- ---------- @@ -223,9 +243,9 @@ BitsTransfer Manifest PSDiagnostics Manifest TestCmdlets Script -PS C:\> $a = Import-Module -Name Show-Calendar -AsCustomObject -Passthru +PS> $a = Import-Module -Name Show-Calendar -AsCustomObject -Passthru -PS C:\> $a | Get-Member +PS> $a | Get-Member TypeName: System.Management.Automation.PSCustomObject Name MemberType Definition @@ -236,7 +256,7 @@ GetType Method type GetType() ToString Method string ToString() Show-Calendar ScriptMethod System.Object Show-Calendar(); -PS C:\> $a."Show-Calendar"() +PS> $a."Show-Calendar"() ``` These commands demonstrate how to get and use the custom object that **Import-Module** returns. @@ -262,10 +282,12 @@ The output shows a **Show-Calendar** script method. The last command uses the **Show-Calendar** script method. The method name must be enclosed in quotation marks, because it includes a hyphen. + ### Example 8 + ``` -PS C:\> Import-Module BitsTransfer -PS C:\> Import-Module BitsTransfer -force -Prefix PS +PS> Import-Module BitsTransfer +PS> Import-Module BitsTransfer -force -Prefix PS ``` This example shows how to use the **Force** parameter of **Import-Module** when you are re-importing a module into the same session. @@ -275,24 +297,26 @@ The second command imports the module again, this time using the **Prefix** para The second command also includes the **Force** parameter, which removes the module and then imports it again. Without this parameter, the session would include two copies of each **BitsTransfer** cmdlet, one with the standard name and one with the prefixed name. + ### Example 9 + ``` -PS C:\> Get-Date +PS> Get-Date Thursday, March 15, 2012 6:47:04 PM -PS C:\> Import-Module TestModule +PS> Import-Module TestModule -PS C:\> Get-Date +PS> Get-Date 12075 -PS C:\> Get-Command Get-Date -All | Format-Table -Property CommandType, Name, ModuleName -AutoSize +PS> Get-Command Get-Date -All | Format-Table -Property CommandType, Name, ModuleName -AutoSize CommandType Name ModuleName ----------- ---- ---------- Function Get-Date TestModule Cmdlet Get-Date Microsoft.PowerShell.Utility -PS C:\> Microsoft.PowerShell.Utility\Get-Date +PS> Microsoft.PowerShell.Utility\Get-Date Saturday, September 12, 2009 6:33:23 PM ``` @@ -313,31 +337,35 @@ The results show that there are two **Get-Date** commands in the session, a func The fifth command runs the hidden cmdlet by qualifying the command name with the module name. For more information about command precedence in Windows PowerShell, see about_Command_Precedence (http://go.microsoft.com/fwlink/?LinkID=113214). + ### Example 10 + ``` -PS C:\> Import-Module -Name PSWorkflow -MinimumVersion 3.0.0.0 +PS> Import-Module -Name PSWorkflow -MinimumVersion 3.0.0.0 ``` This command imports the PSWorkflow module. It uses the **MinimumVersion** (alias=Version) parameter of **Import-Module** to import only version 3.0.0.0 or greater of the module. You can also use the **RequiredVersion** parameter to import a particular version of a module, or use the **Module** and **Version** parameters of the **#Requires** keyword to require a particular version of a module in a script. + ### Example 11 + ``` The first command uses the New-PSSession cmdlet to create a remote session (PSSession) to the Server01 computer. The command saves the PSSession in the $s variable -PS C:\> $s = New-PSSession -ComputerName Server01 +PS> $s = New-PSSession -ComputerName Server01 The second command uses the **PSSession** parameter of the Get-Module cmdlet to get the **NetSecurity** module in the session in the $s variable.This command is equivalent to using the Invoke-Command cmdlet to run a **Get-Module** command in the session in $s ([CODE_Snippit]Invoke-Command $s {Get-Module -ListAvailable -Name NetSecurity[CODE_Snippit]).The output shows that the **NetSecurity** module is installed on the computer and is available to the session in the $s variable. -PS C:\> Get-Module -PSSession $s -ListAvailable -Name NetSecurity +PS> Get-Module -PSSession $s -ListAvailable -Name NetSecurity ModuleType Name ExportedCommands ---------- ---- ---------------- Manifest NetSecurity {New-NetIPsecAuthProposal, New-NetIPsecMainModeCryptoProposal, New-Ne... The third command uses the **PSSession** parameter of the **Import-Module** cmdlet to import the **NetSecurity** module from the session in the $s variable into the current session. -PS C:\> Import-Module -PSSession $s -Name NetSecurity +PS> Import-Module -PSSession $s -Name NetSecurity The fourth command uses the **Get-Command** cmdlet to get commands that begin with "Get" and include "Firewall" from the Net-Security module.The output gets the commands and confirms that the module and its cmdlets were imported into the current session. -PS C:\> Get-Command -Module NetSecurity -Name Get-*Firewall* +PS> Get-Command -Module NetSecurity -Name Get-*Firewall* CommandType Name ModuleName ----------- ---- ---------- Function Get-NetFirewallAddressFilter NetSecurity @@ -352,7 +380,7 @@ Function Get-NetFirewallServiceFilter NetSecurity Function Get-NetFirewallSetting NetSecurity The fifth command uses the **Get-NetFirewallRule** cmdlet to get Windows Remote Management firewall rules on the Server01 computer. This command is equivalent to using the Invoke-Command cmdlet to run a **Get-NetFirewallRule** command on the session in the $s variable ([CODE_Snippit]Invoke-Command -Session $s {Get-NetFirewallRule -DisplayName "Windows Remote Management*"[CODE_Snippit]}). -PS C:\> Get-NetFirewallRule -DisplayName "Windows Remote Management*" | Format-Table -Property DisplayName, Name -AutoSize +PS> Get-NetFirewallRule -DisplayName "Windows Remote Management*" | Format-Table -Property DisplayName, Name -AutoSize DisplayName Name ----------- ---- Windows Remote Management (HTTP-In) WINRM-HTTP-In-TCP @@ -365,22 +393,24 @@ This command uses the Implicit Remoting feature of Windows PowerShell. When you import modules from another session, you can use the cmdlets in the current session. However, commands that use the cmdlets actually run in the remote session. + ### Example 12 + ``` The first command uses the **New-CimSession** cmdlet to create a session on the RSDGF03 remote computer. The session connects to WMI on the remote computer. The command saves the CIM session in the $cs variable. -PS C:\> $cs = New-CimSession -ComputerName RSDGF03 +PS> $cs = New-CimSession -ComputerName RSDGF03 The second command uses the CIM session in the $cs variable to run an **Import-Module** command on the RSDGF03 computer. The command uses the **Name** parameter to specify the **Storage** CIM module. -PS C:\> Import-Module -CimSession $cs -Name Storage +PS> Import-Module -CimSession $cs -Name Storage The third command runs the a **Get-Command** command on the **Get-Disk** command in the Storage module.When you import a CIM module into the local session, Windows PowerShell converts the CDXML files for each command into Windows PowerShell scripts, which appear as functions in the local session. -PS C:\> Get-Command Get-Disk +PS> Get-Command Get-Disk CommandType Name ModuleName ----------- ---- ---------- Function Get-Disk Storage The fourth command runs the **Get-Disk** command. Although the command is typed in the local session, it runs implicitly on the remote computer from which it was imported.The command gets objects from the remote computer and returns them to the local session. -PS C:\> Get-Disk +PS> Get-Disk Number Friendly Name OperationalStatus Total Size Partition Style ------ ------------- ----------------- ---------- --------------- 0 Virtual HD ATA Device Online 40 GB MBR @@ -388,9 +418,11 @@ Number Friendly Name OperationalStatus Total Size Partitio The commands in this example enable you to manage the storage systems of a remote computer that is not running a Windows operating system. In this example, because the administrator of the computer has installed the Module Discovery WMI provider, the CIM commands can use the default values, which are designed for the provider. + ## PARAMETERS ### -Alias + Imports only the specified aliases from the module into the current session. Enter a comma-separated list of aliases. Wildcard characters are permitted. @@ -411,6 +443,7 @@ Accept wildcard characters: True ``` ### -ArgumentList + Specifies arguments (parameter values) that are passed to a script module during the Import-Module command. This parameter is valid only when you are importing a script module. @@ -430,6 +463,7 @@ Accept wildcard characters: False ``` ### -AsCustomObject + Returns a custom object with members that represent the imported module members. This parameter is valid only for script modules. @@ -449,6 +483,7 @@ Accept wildcard characters: False ``` ### -Assembly + Imports the cmdlets and providers implemented in the specified assembly objects. Enter a variable that contains assembly objects or a command that creates assembly objects. You can also pipe an assembly object to Import-Module. @@ -470,6 +505,7 @@ Accept wildcard characters: False ``` ### -CimNamespace + Specifies the namespace of an alternate CIM provider that exposes CIM modules. The default value is the namespace of the Module Discovery WMI provider. @@ -490,6 +526,7 @@ Accept wildcard characters: False ``` ### -CimResourceUri + Specifies an alternate location for CIM modules. The default value is the resource URI of the Module Discovery WMI provider on the remote computer. @@ -510,6 +547,7 @@ Accept wildcard characters: False ``` ### -Cmdlet + Imports only the specified cmdlets from the module into the current session. Enter a list of cmdlets. Wildcard characters are permitted. @@ -530,6 +568,7 @@ Accept wildcard characters: True ``` ### -DisableNameChecking + Suppresses the message that warns you when you import a cmdlet or function whose name includes an unapproved verb or a prohibited character. By default, when a module that you import exports cmdlets or functions that have unapproved verbs in their names, the Windows PowerShell displays the following warning message: @@ -554,6 +593,7 @@ Accept wildcard characters: False ``` ### -Force + Re-imports a module and its members, even if the module or its members have an access mode of read-only. ```yaml @@ -569,6 +609,7 @@ Accept wildcard characters: False ``` ### -Function + Imports only the specified functions from the module into the current session. Enter a list of functions. Wildcard characters are permitted. @@ -589,6 +630,7 @@ Accept wildcard characters: True ``` ### -Global + Imports modules into the global session state so they are available to all commands in the session. By default, the commands in a module, including commands from nested modules, are imported into the caller's session state. To restrict the commands that a module exports, use an Export-ModuleMember command in the script module. @@ -608,6 +650,7 @@ Accept wildcard characters: False ``` ### -ModuleInfo + Specifies module objects to import. Enter a variable that contains the module objects, or a command that gets the module objects, such as a "Get-Module -ListAvailable" command. You can also pipe module objects to Import-Module. @@ -625,6 +668,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the names of the modules to import. Enter the name of the module or the name of a file in the module, such as a .psd1, .psm1, .dll, or ps1 file. File paths are optional. @@ -650,6 +694,7 @@ Accept wildcard characters: True ``` ### -NoClobber + Does not import commands that have the same names as existing commands in the current session. By default, **Import-Module** imports all exported module commands. @@ -672,6 +717,7 @@ Accept wildcard characters: False ``` ### -PassThru + Returns objects that represent the modules that were imported. By default, this cmdlet does not generate any output. @@ -688,6 +734,7 @@ Accept wildcard characters: False ``` ### -Prefix + Adds the specified prefix to the nouns in the names of imported module members. Use this parameter to avoid name conflicts that might occur when different members in the session have the same name. @@ -711,6 +758,7 @@ Accept wildcard characters: False ``` ### -Variable + Imports only the specified variables from the module into the current session. Enter a list of variables. Wildcard characters are permitted. @@ -731,6 +779,7 @@ Accept wildcard characters: True ``` ### -CimSession + Specifies a CIM session on the remote computer. Enter a variable that contains the CIM session or a command that gets the CIM session, such as a [Get-CimSession](https://docs.microsoft.com/en-us/powershell/module/cimcmdlets/get-cimsession) command. @@ -754,6 +803,7 @@ Accept wildcard characters: False ``` ### -MinimumVersion + Imports only a version of the module that is greater than or equal to the specified value. If no version qualifies, **Import-Module** generates an error. @@ -779,6 +829,7 @@ Accept wildcard characters: False ``` ### -PSSession + Imports modules from the specified Windows PowerShell user-managed session ("PSSession") into the current session. Enter a variable that contains a PSSession or a command that gets a PSSession, such as a Get-PSSession command. @@ -806,6 +857,7 @@ Accept wildcard characters: False ``` ### -RequiredVersion + Imports only the specified version of the module. If the version is not installed, **Import-Module** generates an error. @@ -832,6 +884,7 @@ Accept wildcard characters: False ``` ### -Scope + Imports the module only into the specified scope. Valid values are: @@ -856,32 +909,39 @@ 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.Management.Automation.PSModuleInfo, System.Reflection.Assembly + You can pipe a module name, module object, or assembly object to Import-Module. + ## OUTPUTS ### None, System.Management.Automation.PSModuleInfo, or System.Management.Automation.PSCustomObject + By default, Import-Module does not generate any output. If you use the PassThru parameter, it generates a System.Management.Automation.PSModuleInfo object that represents the module. If you use the AsCustomObject parameter, it generates a PSCustomObject object. + ## NOTES -* Before you can import a module, the module must be installed on the local computer, that is, the module directory must be copied to a directory that is accessible to your local computer. For more information, see about_Modules (http://go.microsoft.com/fwlink/?LinkID=144311). + +- Before you can import a module, the module must be installed on the local computer, that is, the module directory must be copied to a directory that is accessible to your local computer. For more information, see about_Modules (http://go.microsoft.com/fwlink/?LinkID=144311). You can also use the **PSSession** and **CIMSession** parameters to import modules that are installed on remote computers. However, commands that use the cmdlets in these modules actually run in the remote session on the remote computer. -* If you import members with the same name and the same type into your session, Windows PowerShell uses the member imported last by default. Variables and aliases are replaced, and the originals are not accessible. Functions, cmdlets and providers are merely "shadowed" by the new members, and they can be accessed by qualifying the command name with the name of its snap-in, module, or function path. -* To update the formatting data for commands that have been imported from a module, use the Update-FormatData cmdlet. **Update-FormatData** also updates the formatting data for commands in the session that were imported from modules. If the formatting file for a module changes, you can run an **Update-FormatData** command to update the formatting data for imported commands. You do not need to import the module again. -* Beginning in Windows PowerShell 3.0, the core commands that are installed with Windows PowerShell are packaged in modules. In Windows PowerShell 2.0, and in host programs that create older-style sessions in later versions of Windows PowerShell, the core commands are packaged in snap-ins ("PSSnapins"). The exception is **Microsoft.PowerShell.Core**, which is always a snap-in. Also, remote sessions, such as those started by the New-PSSession cmdlet, are older-style sessions that include core snap-ins. +- If you import members with the same name and the same type into your session, Windows PowerShell uses the member imported last by default. Variables and aliases are replaced, and the originals are not accessible. Functions, cmdlets and providers are merely "shadowed" by the new members, and they can be accessed by qualifying the command name with the name of its snap-in, module, or function path. +- To update the formatting data for commands that have been imported from a module, use the Update-FormatData cmdlet. **Update-FormatData** also updates the formatting data for commands in the session that were imported from modules. If the formatting file for a module changes, you can run an **Update-FormatData** command to update the formatting data for imported commands. You do not need to import the module again. +- Beginning in Windows PowerShell 3.0, the core commands that are installed with Windows PowerShell are packaged in modules. In Windows PowerShell 2.0, and in host programs that create older-style sessions in later versions of Windows PowerShell, the core commands are packaged in snap-ins ("PSSnapins"). The exception is **Microsoft.PowerShell.Core**, which is always a snap-in. Also, remote sessions, such as those started by the New-PSSession cmdlet, are older-style sessions that include core snap-ins. For information about the **CreateDefault2** method that creates newer-style sessions with core modules, see [CreateDefault2 Method](https://msdn.microsoft.com/library/system.management.automation.runspaces.initialsessionstate.createdefault2) in the MSDN library. -* **Import-Module** cannot import Windows PowerShell Core modules from another session. The Windows PowerShell Core modules have names that begin with Microsoft.PowerShell. -* In Windows PowerShell 2.0, some of the property values of the module object, such as the **ExportedCmdlets** and **NestedModules** property values, were not populated until the module was imported and were not available on the module object that the **PassThru** parameter returns. In Windows PowerShell 3.0, all module property values are populated. -* If you attempt to import a module that contains mixed-mode assemblies that are not compatible with Windows PowerShell 3.0, **Import-Module** returns an error message like the following one. +- **Import-Module** cannot import Windows PowerShell Core modules from another session. The Windows PowerShell Core modules have names that begin with Microsoft.PowerShell. +- In Windows PowerShell 2.0, some of the property values of the module object, such as the **ExportedCmdlets** and **NestedModules** property values, were not populated until the module was imported and were not available on the module object that the **PassThru** parameter returns. In Windows PowerShell 3.0, all module property values are populated. +- If you attempt to import a module that contains mixed-mode assemblies that are not compatible with Windows PowerShell 3.0, **Import-Module** returns an error message like the following one. `Import-Module : Mixed mode assembly is built against version 'v2.0.50727' of the runtime and cannot be loaded in the 4.0 runtime without additional configuration information.` @@ -891,12 +951,13 @@ However, commands that use the cmdlets in these modules actually run in the remo `PowerShell.exe -Version 2.0` -* To use the CIM session feature, the remote computer must have WS-Management remoting and Windows Management Instrumentation (WMI), which is the Microsoft implementation of the Common Information Model (CIM) standard. The computer must also have the Module Discovery WMI provider or an alternate CIM provider that has the same basic features. +- To use the CIM session feature, the remote computer must have WS-Management remoting and Windows Management Instrumentation (WMI), which is the Microsoft implementation of the Common Information Model (CIM) standard. The computer must also have the Module Discovery WMI provider or an alternate CIM provider that has the same basic features. You can use the CIM session feature on computers that are not running a Windows operating system and on Windows computers that have Windows PowerShell, but do not have Windows PowerShell remoting enabled. You can also use the CIM parameters to get CIM modules from computers that have Windows PowerShell remoting enabled, including the local computer. When you create a CIM session on the local computer, Windows PowerShell uses DCOM, instead of WMI, to create the session. + ## RELATED LINKS [Export-ModuleMember](Export-ModuleMember.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/3.0/Microsoft.PowerShell.Core/Invoke-Command.md index 63bbdcc99b26..bf397c66983c 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Invoke-Command.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Invoke-Command.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,19 +7,23 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135225 external help file: System.Management.Automation.dll-Help.xml title: Invoke-Command --- - # Invoke-Command + ## SYNOPSIS + Runs commands on local and remote computers. + ## SYNTAX ### InProcess (Default) + ``` Invoke-Command [-ScriptBlock] [-NoNewScope] [-InputObject ] [-ArgumentList ] [] ``` ### Session + ``` Invoke-Command [[-Session] ] [-ThrottleLimit ] [-AsJob] [-HideComputerName] [-JobName ] [-ScriptBlock] [-InputObject ] [-ArgumentList ] @@ -27,6 +31,7 @@ Invoke-Command [[-Session] ] [-ThrottleLimit ] [-AsJob] [-Hi ``` ### FilePathRunspace + ``` Invoke-Command [[-Session] ] [-ThrottleLimit ] [-AsJob] [-HideComputerName] [-JobName ] [-FilePath] [-InputObject ] [-ArgumentList ] @@ -34,6 +39,7 @@ Invoke-Command [[-Session] ] [-ThrottleLimit ] [-AsJob] [-Hi ``` ### ComputerName + ``` Invoke-Command [[-ComputerName] ] [-Credential ] [-Port ] [-UseSSL] [-ConfigurationName ] [-ApplicationName ] [-ThrottleLimit ] [-AsJob] @@ -44,6 +50,7 @@ Invoke-Command [[-ComputerName] ] [-Credential ] [-Port ``` ### FilePathComputerName + ``` Invoke-Command [[-ComputerName] ] [-Credential ] [-Port ] [-UseSSL] [-ConfigurationName ] [-ApplicationName ] [-ThrottleLimit ] [-AsJob] @@ -53,6 +60,7 @@ Invoke-Command [[-ComputerName] ] [-Credential ] [-Port ``` ### FilePathUri + ``` Invoke-Command [-Credential ] [-ConfigurationName ] [-ThrottleLimit ] [[-ConnectionUri] ] [-AsJob] [-InDisconnectedSession] [-HideComputerName] [-JobName ] @@ -62,6 +70,7 @@ Invoke-Command [-Credential ] [-ConfigurationName ] [-Thro ``` ### Uri + ``` Invoke-Command [-Credential ] [-ConfigurationName ] [-ThrottleLimit ] [[-ConnectionUri] ] [-AsJob] [-InDisconnectedSession] [-HideComputerName] [-JobName ] @@ -71,6 +80,7 @@ Invoke-Command [-Credential ] [-ConfigurationName ] [-Thro ``` ## DESCRIPTION + The **Invoke-Command** cmdlet runs commands on a local or remote computer and returns all output from the commands, including errors. With a single **Invoke-Command** command, you can run commands on multiple computers. @@ -86,20 +96,24 @@ To start an interactive session with a remote computer, use the Enter-PSSession To establish a persistent connection to a remote computer, use the New-PSSession cmdlet. Before using **Invoke-Command** to run commands on a remote computer, read about_Remote (http://go.microsoft.com/fwlink/?LinkID=135182). + ## EXAMPLES ### Example 1 + ``` -PS C:\> Invoke-Command -FilePath c:\scripts\test.ps1 -ComputerName Server01 +PS> Invoke-Command -FilePath c:\scripts\test.ps1 -ComputerName Server01 ``` This command runs the Test.ps1 script on the Server01 computer. The command uses the **FilePath** parameter to specify a script that is located on the local computer. The script runs on the remote computer and the results are returned to the local computer. + ### Example 2 + ``` -PS C:\> Invoke-Command -ComputerName server01 -Credential domain01\user01 -ScriptBlock {Get-Culture} +PS> Invoke-Command -ComputerName server01 -Credential domain01\user01 -ScriptBlock {Get-Culture} ``` This command runs a Get-Culture command on the Server01 remote computer. @@ -109,10 +123,12 @@ It uses the **ScriptBlock** parameter to specify the command to be run on the re In response, Windows PowerShell displays a dialog box that requests the password and an authentication method for the User01 account. It then runs the command on the Server01 computer and returns the result. + ### Example 3 + ``` -PS C:\> $s = New-PSSession -ComputerName Server02 -Credential Domain01\User01 -PS C:\> Invoke-Command -Session $s -ScriptBlock {Get-Culture} +PS> $s = New-PSSession -ComputerName Server02 -Credential Domain01\User01 +PS> Invoke-Command -Session $s -ScriptBlock {Get-Culture} ``` This example runs the same "Get-Culture" command in a session (a persistent connection) on the Server02 remote computer. @@ -125,14 +141,16 @@ The second command uses the **Invoke-Command** cmdlet to run the Get-Culture com It uses the **Session** parameter to specify the session saved in the $s variable. In response, Windows PowerShell runs the command in the session on the Server02 computer. + ### Example 4 + ``` -PS C:\> Invoke-Command -ComputerName Server02 -ScriptBlock {$p = Get-Process PowerShell} -PS C:\> Invoke-Command -ComputerName Server02 -ScriptBlock {$p.VirtualMemorySize} -PS C:\> -PS C:\> $s = New-PSSession -ComputerName Server02 -PS C:\> Invoke-Command -Session $s -ScriptBlock {$p = Get-Process PowerShell} -PS C:\> Invoke-Command -Session $s -ScriptBlock {$p.VirtualMemorySize} +PS> Invoke-Command -ComputerName Server02 -ScriptBlock {$p = Get-Process PowerShell} +PS> Invoke-Command -ComputerName Server02 -ScriptBlock {$p.VirtualMemorySize} +PS> +PS> $s = New-PSSession -ComputerName Server02 +PS> Invoke-Command -Session $s -ScriptBlock {$p = Get-Process PowerShell} +PS> Invoke-Command -Session $s -ScriptBlock {$p.VirtualMemorySize} 17930240 ``` @@ -155,10 +173,12 @@ Then it saves the session in the $s variable. The fourth and fifth commands repeat the series of commands used in the first set, but in this case, the **Invoke-Command** command uses the **Session** parameter to run both of the commands in the same session. In this case, because both commands run in the same session, the commands succeed, and the $p value remains active in the $s session for later use. + ### Example 5 + ``` -PS C:\> $command = { Get-EventLog -log "Windows PowerShell" | where {$_.Message -like "*certificate*"} } -PS C:\> Invoke-Command -ComputerName S1, S2 -ScriptBlock $command +PS> $command = { Get-EventLog -log "Windows PowerShell" | where {$_.Message -like "*certificate*"} } +PS> Invoke-Command -ComputerName S1, S2 -ScriptBlock $command ``` This example shows how to enter a command that is saved in a local variable. @@ -170,9 +190,11 @@ The first command saves a Get-EventLog command in the $command variable. The command is formatted as a script block. The second command uses the Invoke-Command cmdlet to run the command in $command on the S1 and S2 remote computers. + ### Example 6 + ``` -PS C:\> Invoke-Command -ComputerName Server01, Server02, TST-0143, localhost -ConfigurationName MySession.PowerShell -ScriptBlock {Get-EventLog "Windows PowerShell"} +PS> Invoke-Command -ComputerName Server01, Server02, TST-0143, localhost -ConfigurationName MySession.PowerShell -ScriptBlock {Get-EventLog "Windows PowerShell"} ``` This example demonstrates how to use the** Invoke-Command** cmdlet to run a single command on multiple computers. @@ -184,9 +206,11 @@ The list of computers includes the "localhost" value, which represents the local The command uses the **ConfigurationName** parameter to specify an alternate session configuration for Windows PowerShell and the **ScriptBlock** parameter to specify the command. In this example, the command in the script block gets the events in the Windows PowerShell event log on each remote computer. + ### Example 7 + ``` -PS C:\> $version = Invoke-Command -ComputerName (Get-Content Machines.txt) -ScriptBlock {(Get-Host).Version} +PS> $version = Invoke-Command -ComputerName (Get-Content Machines.txt) -ScriptBlock {(Get-Host).Version} ``` This command gets the version of the Windows PowerShell host program running on 200 remote computers. @@ -202,18 +226,20 @@ To specify the computers, it uses the Get-Content cmdlet to get the contents of These commands run synchronously (one at a time). When the commands complete, the output of the commands from all of the computers is saved in the $version variable. The output includes the name of the computer from which the data originated. + ### Example 8 + ``` -PS C:\> $s = New-PSSession -ComputerName Server01, Server02 -PS C:\> Invoke-Command -Session $s -ScriptBlock {Get-EventLog system} -AsJob +PS> $s = New-PSSession -ComputerName Server01, Server02 +PS> Invoke-Command -Session $s -ScriptBlock {Get-EventLog system} -AsJob Id Name State HasMoreData Location Command --- ---- ----- ----- ----------- --------------- 1 Job1 Running True Server01,Server02 Get-EventLog system -PS C:\> $j = Get-Job +PS> $j = Get-Job -PS C:\> $j | Format-List -Property * +PS> $j | Format-List -Property * HasMoreData : True StatusMessage : @@ -233,7 +259,7 @@ Debug : {} Warning : {} StateChanged : -PS C:\> $results = $j | Receive-Job +PS> $results = $j | Receive-Job ``` These commands run a background job on two remote computers. @@ -251,10 +277,12 @@ The fourth command uses a pipeline operator (|) to send the value of the $j vari The fifth command gets the results of the jobs. It pipes the job object in $j to the Receive-Job cmdlet and stores the results in the $results variable. + ### Example 9 + ``` -PS C:\> $MWFO_Log = "Microsoft-Windows-Forwarding/Operational" -PS C:\> Invoke-Command -ComputerName Server01 -ScriptBlock {Get-EventLog -LogName $Using:MWFO_Log -Newest 10} +PS> $MWFO_Log = "Microsoft-Windows-Forwarding/Operational" +PS> Invoke-Command -ComputerName Server01 -ScriptBlock {Get-EventLog -LogName $Using:MWFO_Log -Newest 10} ``` This example shows how to include the values of local variables in a command run on a remote computer. @@ -267,16 +295,18 @@ The first command saves the name of the Microsoft-Windows-Forwarding/Operational The second command uses the **Invoke-Command** cmdlet to run a Get-EventLog command on the Server01 remote computer that gets the 10 newest events from the Microsoft-Windows-Forwarding/Operational event log on Server01. The value of the **LogName** parameter is the $MWFO_Log variable, which is prefixed by the Using scope modifier to indicate that it was created in the local session, not in the remote session. + ### Example 10 + ``` -PS C:\> Invoke-Command -ComputerName S1, S2 -ScriptBlock {Get-Process PowerShell} +PS> Invoke-Command -ComputerName S1, S2 -ScriptBlock {Get-Process PowerShell} PSComputerName Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName -------------- ------- ------ ----- ----- ----- ------ -- ----------- S1 575 15 45100 40988 200 4.68 1392 PowerShell S2 777 14 35100 30988 150 3.68 67 PowerShell -PS C:\> Invoke-Command -ComputerName S1, S2 -ScriptBlock {Get-Process PowerShell} -HideComputerName +PS> Invoke-Command -ComputerName S1, S2 -ScriptBlock {Get-Process PowerShell} -HideComputerName Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- @@ -292,9 +322,11 @@ The output of the second command, which uses the **HideComputerName** parameter, Using the **HideComputerName** parameter does not change the object; it just changes the display. You can still use the Format cmdlets to display the **PsComputerName** property of any of the affected objects. + ### Example 11 + ``` -PS C:\> Invoke-Command -ComputerName (Get-Content Servers.txt) -FilePath C:\Scripts\Sample.ps1 -ArgumentList Process, Service +PS> Invoke-Command -ComputerName (Get-Content Servers.txt) -FilePath C:\Scripts\Sample.ps1 -ArgumentList Process, Service ``` This example uses the **Invoke-Command** cmdlet to run the Sample.ps1 script on all of the computers listed in the Servers.txt file. @@ -303,11 +335,13 @@ This command allows you to run the script on the remote computers, even if the s When you submit the command, the content of the Sample.ps1 file is copied into a script block and the script block is run on each of the remote computers. This procedure is equivalent to using the **ScriptBlock** parameter to submit the contents of the script. + ### Example 12 + ``` -PS C:\> $LiveCred = Get-Credential +PS> $LiveCred = Get-Credential -PS C:\> Invoke-Command -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.exchangelabs.com/PowerShell -Credential $LiveCred -Authentication Basic -ScriptBlock {Set-Mailbox Dan -DisplayName "Dan Park"} +PS> Invoke-Command -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.exchangelabs.com/PowerShell -Credential $LiveCred -Authentication Basic -ScriptBlock {Set-Mailbox Dan -DisplayName "Dan Park"} ``` This example shows how to run a command on a remote computer that is identified by a URI (Internet address). @@ -324,11 +358,13 @@ The **ConnectionURI** parameter specifies the URL of the Exchange server endpoin The **Credential** parameter specifies the Windows Live credentials stored in the $LiveCred variable. The **AuthenticationMechanism** parameter specifies the use of basic authentication. The **ScriptBlock** parameter specifies a script block that contains the command. + ### Example 13 + ``` -PS C:\> $max = New-PSSessionOption -MaximumRedirection 1 +PS> $max = New-PSSessionOption -MaximumRedirection 1 -PS C:\> Invoke-Command -ConnectionUri https://ps.exchangelabs.com/PowerShell -ScriptBlock {Get-Mailbox dan} -AllowRedirection -SessionOption $max +PS> Invoke-Command -ConnectionUri https://ps.exchangelabs.com/PowerShell -ScriptBlock {Get-Mailbox dan} -AllowRedirection -SessionOption $max ``` This command shows how to use the **AllowRedirection** and **SessionOption** parameters to manage URI redirection in a remote command. @@ -341,10 +377,12 @@ The command uses the **AllowRedirection** parameter to provide explicit permissi It also uses the **SessionOption** parameter to specify the session object in the $max variable. As a result, if the remote computer specified by the **ConnectionURI** parameter returns a redirection message, Windows PowerShell will redirect the connection, but if the new destination returns another redirection message, the redirection count value of 1 is exceeded, and Invoke-Command returns a non-terminating error. + ### Example 14 + ``` -PS C:\> $so = New-PSSessionOption -SkipCACheck -SkipCNCheck –SkipRevocationCheck -PS C:\> Invoke-Command -ComputerName server01 -UseSSL -ScriptBlock { Get-Hotfix } -SessionOption $so -Credential server01\user01 +PS> $so = New-PSSessionOption -SkipCACheck -SkipCNCheck –SkipRevocationCheck +PS> Invoke-Command -ComputerName server01 -UseSSL -ScriptBlock { Get-Hotfix } -SessionOption $so -Credential server01\user01 ``` This example shows how to create and use a SessionOption parameter. @@ -354,13 +392,15 @@ It saves the resulting **SessionOption** object in the $so parameter. The second command uses the **Invoke-Command** cmdlet to run a Get-HotFix command remotely. The value of the **SessionOption** parameter is the **SessionOption** object in the $so variable. + ### Example 15 + ``` -PS C:\> Enable-WSManCredSSP -Delegate Server02 -PS C:\> Connect-WSMan Server02 -PS C:\> Set-Item WSMan:\Server02*\Service\Auth\CredSSP -Value $true -PS C:\> $s = New-PSSession Server02 -PS C:\> Invoke-Command -Session $s -ScriptBlock {Get-Item \\Net03\Scripts\LogFiles.ps1} -Authentication CredSSP -Credential Domain01\Admin01 +PS> Enable-WSManCredSSP -Delegate Server02 +PS> Connect-WSMan Server02 +PS> Set-Item WSMan:\Server02*\Service\Auth\CredSSP -Value $true +PS> $s = New-PSSession Server02 +PS> Invoke-Command -Session $s -ScriptBlock {Get-Item \\Net03\Scripts\LogFiles.ps1} -Authentication CredSSP -Credential Domain01\Admin01 ``` This example shows how to access a network share from within a remote session. @@ -382,9 +422,11 @@ It saves the PSSession in the $s variable. The fifth command uses the **Invoke-Command** cmdlet to run a Get-Item command in the session in $s that gets a script from the Net03\Scripts network share. The command uses the **Credential** parameter and it uses the **Authentication** parameter with a value of **CredSSP**. + ### Example 16 + ``` -PS C:\> Invoke-Command -ComputerName (Get-Content Servers.txt) -InDisconnectedSession -FilePath \\Scripts\Public\ConfigInventory.ps1 -SessionOption @{OutputBufferingMode="Drop";IdleTimeout=43200000} +PS> Invoke-Command -ComputerName (Get-Content Servers.txt) -InDisconnectedSession -FilePath \\Scripts\Public\ConfigInventory.ps1 -SessionOption @{OutputBufferingMode="Drop";IdleTimeout=43200000} ``` This command runs a script on more than a hundred computers. @@ -399,9 +441,11 @@ The value of the **FilePath** parameter is the script that **Invoke-Command** ru The value of the **SessionOption** parameter is a hash table that sets the value of the **OutputBufferingMode** option to **Drop** and the value of the **IdleTimeout** option to 43200000 milliseconds (12 hours). To get the results of commands and scripts that run in disconnected sessions, use the Receive-PSSession cmdlet. + ## PARAMETERS ### -AllowRedirection + Allows redirection of this connection to an alternate Uniform Resource Identifier (URI). When you use the **ConnectionURI** parameter, the remote destination can return an instruction to redirect to a different URI. @@ -424,6 +468,7 @@ Accept wildcard characters: False ``` ### -ApplicationName + Specifies the application name segment of the connection URI. Use this parameter to specify the application name when you are not using the **ConnectionURI** parameter in the command. @@ -448,6 +493,7 @@ Accept wildcard characters: False ``` ### -ArgumentList + Supplies the values of local variables in the command. The variables in the command are replaced by these values before the command is run on the remote computer. Enter the values in a comma-separated list. @@ -476,6 +522,7 @@ Accept wildcard characters: False ``` ### -AsJob + Runs the command as a background job on a remote computer. Use this parameter to run commands that take an extensive time to complete. @@ -502,6 +549,7 @@ Accept wildcard characters: False ``` ### -Authentication + Specifies the mechanism that is used to authenticate the user's credentials. Valid values are **Default**, **Basic**, **Credssp**, **Digest**, **Kerberos**, **Negotiate**, and **NegotiateWithImplicitCredential**. The default value is **Default**. @@ -527,6 +575,7 @@ Accept wildcard characters: False ``` ### -CertificateThumbprint + Specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate. @@ -548,6 +597,7 @@ Accept wildcard characters: False ``` ### -ComputerName + Specifies the computers on which the command runs. The default is the local computer. @@ -576,6 +626,7 @@ Accept wildcard characters: False ``` ### -ConfigurationName + Specifies the session configuration that is used for the new PSSession. Enter a configuration name or the fully qualified resource URI for a session configuration. @@ -601,6 +652,7 @@ Accept wildcard characters: False ``` ### -ConnectionUri + Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint of the session. The URI must be fully qualified. @@ -633,6 +685,7 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. @@ -652,6 +705,7 @@ Accept wildcard characters: False ``` ### -EnableNetworkAccess + Adds an interactive security token to loopback sessions. The interactive token lets you run commands in the loopback session that get data from other computers. For example, you can run a command in the session that copies XML files from a remote computer to the local computer. @@ -685,6 +739,7 @@ Accept wildcard characters: False ``` ### -FilePath + Runs the specified local script on one or more remote computers. Enter the path and file name of the script, or pipe a script path to Invoke-Command. The script must reside on the local computer or in a directory that the local computer can access. @@ -705,6 +760,7 @@ Accept wildcard characters: False ``` ### -HideComputerName + Omits the computer name of each object from the output display. By default, the name of the computer that generated the object appears in the display. @@ -724,6 +780,7 @@ Accept wildcard characters: False ``` ### -InDisconnectedSession + Runs a command or script in a disconnected session. When you use the **InDisconnectedSession** parameter, **Invoke-Command** creates a persistent session on each remote computer, starts the command specified by the **ScriptBlock** or **FilePath** parameter, and then disconnects from the session. @@ -758,6 +815,7 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies input to the command. Enter a variable that contains the objects or type a command or expression that gets the objects. @@ -776,6 +834,7 @@ Accept wildcard characters: False ``` ### -JobName + Specifies a friendly name for the background job. By default, jobs are named "Job\", where \ is an ordinal number. @@ -796,6 +855,7 @@ Accept wildcard characters: False ``` ### -Port + Specifies the network port on the remote computer used for this command. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). @@ -824,6 +884,7 @@ Accept wildcard characters: False ``` ### -ScriptBlock + Specifies the commands to run. Enclose the commands in braces ( { } ) to create a script block. This parameter is required. @@ -844,6 +905,7 @@ Accept wildcard characters: False ``` ### -Session + Runs the command in the specified Windows PowerShell sessions (PSSessions). Enter a variable that contains the PSSessions or a command that creates or gets the PSSessions, such as a New-PSSession or Get-PSSession command. @@ -870,6 +932,7 @@ Accept wildcard characters: False ``` ### -SessionOption + Sets advanced options for the session. Enter a **SessionOption** object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. @@ -896,6 +959,7 @@ Accept wildcard characters: False ``` ### -ThrottleLimit + Specifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0, the default value, 32, is used. @@ -914,6 +978,7 @@ Accept wildcard characters: False ``` ### -UseSSL + Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used. @@ -935,6 +1000,7 @@ Accept wildcard characters: False ``` ### -NoNewScope + Runs the specified command in the current scope. By default, Invoke-Command runs commands in their own scope. @@ -955,6 +1021,7 @@ Accept wildcard characters: False ``` ### -SessionName + Specifies a friendly name for a disconnected session. You can use the name to refer to the session in subsequent commands, such as a Get-PSSession command. This parameter is valid only with the **InDisconnectedSession** parameter. @@ -974,31 +1041,38 @@ 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.ScriptBlock + You can pipe a command in a script block to **Invoke-Command**. Use the $input automatic variable to represent the input objects in the command. + ## OUTPUTS ### System.Management.Automation.PSRemotingJob, System.Management.Automation.Runspaces.PSSession, or the output of the invoked command + When you use the **AsJob** parameter, **Invoke-Command** returns a job object. When you use the **InDisconnectedSession** parameter, **Invoke-Command** returns a PSSession object. Otherwise, it returns the output of the invoked command (the value of the **ScriptBlock** parameter). + ## NOTES -* On Windows Vista, and later versions of Windows, to use the **ComputerName** parameter of **Invoke-Command** to run a command on the local computer, you must open Windows PowerShell with the "Run as administrator" option. -* When you run commands on multiple computers, Windows PowerShell connects to the computers in the order in which they appear in the list. However, the command output is displayed in the order that it is received from the remote computers, which might be different. -* Errors that result from the command that **Invoke-Command** runs are included in the command results. Errors that would be terminating errors in a local command are treated as non-terminating errors in a remote command. This strategy ensures that terminating errors on one computer do not terminate the command on all computers on which it is run. This practice is used even when a remote command is run on a single computer. -* If the remote computer is not in a domain that the local computer trusts, the computer might not be able to authenticate the user's credentials. To add the remote computer to the list of "trusted hosts" in WS-Management, use the following command in the WSMAN provider, where \ is the name of the remote computer: + +- On Windows Vista, and later versions of Windows, to use the **ComputerName** parameter of **Invoke-Command** to run a command on the local computer, you must open Windows PowerShell with the "Run as administrator" option. +- When you run commands on multiple computers, Windows PowerShell connects to the computers in the order in which they appear in the list. However, the command output is displayed in the order that it is received from the remote computers, which might be different. +- Errors that result from the command that **Invoke-Command** runs are included in the command results. Errors that would be terminating errors in a local command are treated as non-terminating errors in a remote command. This strategy ensures that terminating errors on one computer do not terminate the command on all computers on which it is run. This practice is used even when a remote command is run on a single computer. +- If the remote computer is not in a domain that the local computer trusts, the computer might not be able to authenticate the user's credentials. To add the remote computer to the list of "trusted hosts" in WS-Management, use the following command in the WSMAN provider, where \ is the name of the remote computer: Set-Item -Path WSMan:\Localhost\Client\TrustedHosts -Value \ -* In Windows PowerShell 2.0, you cannot use the Select-Object cmdlet to select the **PSComputerName** property of the object that **Invoke-Command** returns. Instead, to display the value of the **PSComputerName** property, use the dot method to get the **PSComputerName** property value ($result.PSComputerName), use a Format cmdlet, such as the Format-Table cmdlet, to display the value of the **PSComputerName** property, or use a Select-Object command where the value of the property parameter is a calculated property that has a label other than "PSComputerName". +- In Windows PowerShell 2.0, you cannot use the Select-Object cmdlet to select the **PSComputerName** property of the object that **Invoke-Command** returns. Instead, to display the value of the **PSComputerName** property, use the dot method to get the **PSComputerName** property value ($result.PSComputerName), use a Format cmdlet, such as the Format-Table cmdlet, to display the value of the **PSComputerName** property, or use a Select-Object command where the value of the property parameter is a calculated property that has a label other than "PSComputerName". This limitation does not apply to Windows PowerShell 3.0 or later versions of Windows PowerShell. -* When you disconnect a PSSession, such as by using the **InDisconnectedSession** parameter, the session state is **Disconnected** and the availability is **None**. +- When you disconnect a PSSession, such as by using the **InDisconnectedSession** parameter, the session state is **Disconnected** and the availability is **None**. The value of the **State** property is relative to the current session. Therefore, a value of **Disconnected** means that the PSSession is not connected to the current session. diff --git a/reference/3.0/Microsoft.PowerShell.Core/Invoke-History.md b/reference/3.0/Microsoft.PowerShell.Core/Invoke-History.md index 3594c2b19ff8..a06e4686963f 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Invoke-History.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Invoke-History.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113344 external help file: System.Management.Automation.dll-Help.xml title: Invoke-History --- - # Invoke-History + ## SYNOPSIS + Runs commands from the session history. + ## SYNTAX ``` @@ -18,51 +20,64 @@ Invoke-History [[-Id] ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Invoke-History** cmdlet runs commands from the session history. You can pass objects representing the commands from **Get-History** to **Invoke-History**, or you can identify commands in the current history by using their ID number. To find the identification number of a command, use the Get-History cmdlet. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Invoke-History +PS> Invoke-History ``` This command runs the last (most recent) command in the session history. You can abbreviate this command as "r" (think "repeat" or "rerun"), the alias for **Invoke-History**. + ### Example 2 + ``` -PS C:\> Invoke-History -Id 132 +PS> Invoke-History -Id 132 ``` This command runs the command in the session history with ID 132. Because the name of the **Id** parameter is optional, you can abbreviate this command as "`Invoke-History 132", "ihy 132", or "r 132`". + ### Example 3 + ``` -PS C:\> Invoke-History get-pr +PS> Invoke-History get-pr ``` This command runs the most recent **Get-Process** command in the session history. When you type characters for the **Id** parameter, **Invoke-History** runs the first command that it finds that matches the pattern, beginning with the most recent commands. This command uses the **Id** parameter, but it omits the optional parameter name. + ### Example 4 + ``` -PS C:\> 16..24 | ForEach {Invoke-History -Id $_ } +PS> 16..24 | ForEach {Invoke-History -Id $_ } ``` This command runs commands 16 through 24. Because you can list only one ID value, the command uses the ForEach-Object cmdlet to run the **Invoke-History** command once for each ID value. + ### Example 5 + ``` -PS C:\> Get-History -Id 255 -Count 7 | ForEach {Invoke-History -Id $_.Id} +PS> Get-History -Id 255 -Count 7 | ForEach {Invoke-History -Id $_.Id} ``` This command runs the 7 commands in the history that end with command 255 (typically 249 through 255). It uses the Get-History cmdlet to retrieve the commands. Because you can list only one ID value, the command uses the ForEach-Object cmdlet to run the **Invoke-History** command once for each ID value. + ## PARAMETERS ### -Id + Identifies a command in the history. You can type the ID number of the command or the first few characters of the command. @@ -84,6 +99,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -99,6 +115,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -115,22 +132,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.String + You can pipe a history ID to Invoke-History. + ## OUTPUTS ### None + **Invoke-Histor**y does not generate any output, but output might be generated by the commands that **Invoke-History** runs. + ## NOTES -* The session history is a list of the commands entered during the session along with the ID. 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 session history, see about_History (http://go.microsoft.com/fwlink/?LinkID=113233). + +- The session history is a list of the commands entered during the session along with the ID. 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 session history, see about_History (http://go.microsoft.com/fwlink/?LinkID=113233). You can also refer to **Invoke-History** by its built-in aliases, "r" and "ihy". For more information, see about_Aliases (http://go.microsoft.com/fwlink/?LinkID=113207). -* +- + ## RELATED LINKS [Add-History](Add-History.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Microsoft.PowerShell.Core.md b/reference/3.0/Microsoft.PowerShell.Core/Microsoft.PowerShell.Core.md index 5b8ed6c3a331..03438c61c49f 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Microsoft.PowerShell.Core.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Microsoft.PowerShell.Core.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -9,227 +9,284 @@ Module Guid: 00000000-0000-0000-0000-000000000000 title: Microsoft.PowerShell.Core Module Name: Microsoft.PowerShell.Core --- - # Microsoft.PowerShell.Core Module + ## Description + This section contains the help topics for the cmdlets that are installed with Windows PowerShell Microsoft.PowerShell.Core module. The Core module contains cmdlets and providers that manage the basic features of Windows PowerShell. ## Microsoft.PowerShell.Core Cmdlets + ### [Add-History](Add-History.md) + Appends entries to the session history. ### [Add-PSSnapin](Add-PSSnapin.md) + Adds one or more Windows PowerShell snap-ins to the current session. ### [Clear-History](Clear-History.md) + Deletes entries from the command history. ### [Connect-PSSession](Connect-PSSession.md) + Reconnects to disconnected sessions ### [Disable-PSRemoting](Disable-PSRemoting.md) + Prevents remote users from running commands on the local computer. ### [Disable-PSSessionConfiguration](Disable-PSSessionConfiguration.md) + Disables session configurations on the local computer. ### [Disconnect-PSSession](Disconnect-PSSession.md) + Disconnects from a session. ### [Enable-PSRemoting](Enable-PSRemoting.md) + Configures the computer to receive remote commands. ### [Enable-PSSessionConfiguration](Enable-PSSessionConfiguration.md) + Enables the session configurations on the local computer. ### [Enter-PSSession](Enter-PSSession.md) + Starts an interactive session with a remote computer. ### [Exit-PSSession](Exit-PSSession.md) + Ends an interactive session with a remote computer. ### [Export-Console](Export-Console.md) + Exports the names of snap-ins in the current session to a console file. ### [Export-ModuleMember](Export-ModuleMember.md) + Specifies the module members that are exported. ### [ForEach-Object](ForEach-Object.md) + Performs an operation against each item in a collection of input objects. ### [Get-Command](Get-Command.md) + Gets all commands. ### [Get-Help](Get-Help.md) + Displays information about Windows PowerShell commands and concepts. ### [Get-History](Get-History.md) + Gets a list of the commands entered during the current session. ### [Get-Job](Get-Job.md) + Gets Windows PowerShell background jobs that are running in the current session. ### [Get-Module](Get-Module.md) + Gets the modules that have been imported or that can be imported into the current session. ### [Get-PSSessionConfiguration](Get-PSSessionConfiguration.md) + Gets the registered session configurations on the computer. ### [Get-PSSession](Get-PSSession.md) + Gets the Windows PowerShell sessions on local and remote computers. ### [Get-PSSnapin](Get-PSSnapin.md) + Gets the Windows PowerShell snap-ins on the computer. ### [Import-Module](Import-Module.md) + Adds modules to the current session. ### [Invoke-Command](Invoke-Command.md) + Runs commands on local and remote computers. ### [Invoke-History](Invoke-History.md) + Runs commands from the session history. ### [New-ModuleManifest](New-ModuleManifest.md) + Creates a new module manifest. ### [New-Module](New-Module.md) + Creates a new dynamic module that exists only in memory. ### [New-PSSessionConfigurationFile](New-PSSessionConfigurationFile.md) + Creates a file that defines a session configuration. ### [New-PSSessionOption](New-PSSessionOption.md) + Creates an object that contains advanced options for a PSSession. ### [New-PSSession](New-PSSession.md) + Creates a persistent connection to a local or remote computer. ### [New-PSTransportOption](New-PSTransportOption.md) + Creates an object that contains advanced options for a session configuration. ### [Out-Default](Out-Default.md) + Sends the output to the default formatter and to the default output cmdlet. ### [Out-Host](Out-Host.md) + Sends output to the command line. ### [Out-Null](Out-Null.md) + Deletes output instead of sending it down the pipeline. ### [Receive-Job](Receive-Job.md) + Gets the results of the Windows PowerShell background jobs in the current session. ### [Receive-PSSession](Receive-PSSession.md) + Gets results of commands in disconnected sessions ### [Register-PSSessionConfiguration](Register-PSSessionConfiguration.md) + Creates and registers a new session configuration. ### [Remove-Job](Remove-Job.md) + Deletes a Windows PowerShell background job. ### [Remove-Module](Remove-Module.md) + Removes modules from the current session. ### [Remove-PSSession](Remove-PSSession.md) + Closes one or more Windows PowerShell sessions (PSSessions). ### [Remove-PSSnapin](Remove-PSSnapin.md) + Removes Windows PowerShell snap-ins from the current session. ### [Resume-Job](Resume-Job.md) + Restarts a suspended job ### [Save-Help](Save-Help.md) + Downloads and saves the newest help files to a file system directory. ### [Set-PSDebug](Set-PSDebug.md) + Turns script debugging features on and off, sets the trace level, and toggles strict mode. ### [Set-PSSessionConfiguration](Set-PSSessionConfiguration.md) + Changes the properties of a registered session configuration. ### [Set-StrictMode](Set-StrictMode.md) + Establishes and enforces coding rules in expressions, scripts, and script blocks. ### [Start-Job](Start-Job.md) + Starts a Windows PowerShell background job. ### [Stop-Job](Stop-Job.md) + Stops a Windows PowerShell background job. ### [Suspend-Job](Suspend-Job.md) + Temporarily stops workflow jobs. ### [Test-ModuleManifest](Test-ModuleManifest.md) + Verifies that a module manifest file accurately describes the contents of a module. ### [Test-PSSessionConfigurationFile](Test-PSSessionConfigurationFile.md) + Verifies the keys and values in a session configuration file. ### [Unregister-PSSessionConfiguration](Unregister-PSSessionConfiguration.md) + Deletes registered session configurations from the computer. ### [Update-Help](Update-Help.md) + Downloads and installs the newest help files on your computer. ### [Wait-Job](Wait-Job.md) + Suppresses the command prompt until one or all of the Windows PowerShell background jobs running in the session are complete. ### [Where-Object](Where-Object.md) + Selects objects from a collection based on their property values. \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Core/New-Module.md b/reference/3.0/Microsoft.PowerShell.Core/New-Module.md index 4ef6dbf7eddc..8b6655b4d52d 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/New-Module.md +++ b/reference/3.0/Microsoft.PowerShell.Core/New-Module.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,25 +7,30 @@ online version: http://go.microsoft.com/fwlink/?LinkID=141554 external help file: System.Management.Automation.dll-Help.xml title: New-Module --- - # New-Module + ## SYNOPSIS + Creates a new dynamic module that exists only in memory. + ## SYNTAX ### ScriptBlock (Default) + ``` New-Module [-ScriptBlock] [-Function ] [-Cmdlet ] [-ReturnResult] [-AsCustomObject] [-ArgumentList ] [] ``` ### Name + ``` New-Module [-Name] [-ScriptBlock] [-Function ] [-Cmdlet ] [-ReturnResult] [-AsCustomObject] [-ArgumentList ] [] ``` ## DESCRIPTION + The New-Module cmdlet creates a dynamic module from a script block. The members of the dynamic module, such as functions and variables, are immediately available in the session and remain available until you close the session. @@ -41,11 +46,13 @@ Get-Module cannot get a dynamic module, but Get-Command can get the exported mem To make a dynamic module available to Get-Module, pipe a New-Module command to Import-Module, or pipe the module object that New-Module returns to Import-Module. This action adds the dynamic module to the Get-Module list, but it does not save the module to disk or make it persistent. + ## EXAMPLES ### Example 1 + ``` -PS C:\> new-module -scriptblock {function Hello {"Hello!"}} +PS> new-module -scriptblock {function Hello {"Hello!"}} Name : __DynamicModule_2ceb1d0a-990f-45e4-9fe4-89f0f6ead0e5 Path : 2ceb1d0a-990f-45e4-9fe4-89f0f6ead0e5 @@ -65,9 +72,11 @@ NestedModules : {} This command creates a new dynamic module with a function called "Hello". The command returns a module object that represents the new dynamic module. + ### Example 2 + ``` -PS C:\> new-module -scriptblock {function Hello {"Hello!"}} +PS> new-module -scriptblock {function Hello {"Hello!"}} Name : __DynamicModule_2ceb1d0a-990f-45e4-9fe4-89f0f6ead0e5 Path : 2ceb1d0a-990f-45e4-9fe4-89f0f6ead0e5 @@ -83,9 +92,9 @@ ExportedCmdlets : {} ExportedFunctions : {[Hello, Hello]} ExportedVariables : {} NestedModules : {} -PS C:\> get-module -PS C:\> -PS C:\> get-command Hello +PS> get-module +PS> +PS> get-command Hello CommandType Name Definition ----------- ---- ---------- @@ -93,15 +102,17 @@ Function Hello "Hello!" ``` This example demonstrates that dynamic modules are not returned by the Get-Module cmdlet, but the members that they export are returned by the Get-Command cmdlet. + ### Example 3 + ``` -PS C:\> New-Module -scriptblock {$SayHelloHelp="Type 'SayHello', a space, and a name."; function SayHello ($name) { "Hello, $name" }; Export-ModuleMember -function SayHello -Variable SayHelloHelp} +PS> New-Module -scriptblock {$SayHelloHelp="Type 'SayHello', a space, and a name."; function SayHello ($name) { "Hello, $name" }; Export-ModuleMember -function SayHello -Variable SayHelloHelp} -PS C:\> $SayHelloHelp +PS> $SayHelloHelp Type 'SayHello', a space, and a name. -PS C:\> SayHello Jeffrey +PS> SayHello Jeffrey Hello, Jeffrey ``` @@ -109,10 +120,12 @@ This command uses the Export-ModuleMember cmdlet to export a variable into the c Without the Export-ModuleMember command, only the function is exported. The output shows that both the variable and the function were exported into the session. + ### Example 4 + ``` -PS C:\> new-module -scriptblock {function Hello {"Hello!"}} -name GreetingModule | import-module -PS C:\> get-module +PS> new-module -scriptblock {function Hello {"Hello!"}} -name GreetingModule | import-module +PS> get-module Name : GreetingModule Path : d54dfdac-4531-4db2-9dec-0b4b9c57a1e5 @@ -129,7 +142,7 @@ ExportedFunctions : {[Hello, Hello]} ExportedVariables : {} NestedModules : {} -PS C:\> get-command hello +PS> get-command hello CommandType Name Definition ----------- ---- ---------- @@ -146,11 +159,13 @@ The second command uses the Get-Module cmdlet to get the modules in the session. The result shows that Get-Module can get the new dynamic module. The third command uses the Get-Command cmdlet to get the Hello function that the dynamic module exports. + ### Example 5 + ``` -PS C:\> $m = new-module -scriptblock {function Hello ($name) {"Hello, $name"}; function Goodbye ($name) {"Goodbye, $name"}} -AsCustomObject -PS C:\> $m -PS C:\> $m | get-member +PS> $m = new-module -scriptblock {function Hello ($name) {"Hello, $name"}; function Goodbye ($name) {"Goodbye, $name"}} -AsCustomObject +PS> $m +PS> $m | get-member TypeName: System.Management.Automation.PSCustomObject Name MemberType Definition @@ -182,18 +197,22 @@ The third command uses a pipeline operator (|) to send the custom object to the The output shows that the object has script methods that represent the Hello and Goodbye functions. The fourth and fifth commands use the script method format to call the Hello and Goodbye functions. + ### Example 6 + ``` -PS C:\> new-module -scriptblock {function SayHello {"Hello, World!"}; SayHello} -returnResult +PS> new-module -scriptblock {function SayHello {"Hello, World!"}; SayHello} -returnResult Hello, World! ``` This command uses the ReturnResult parameter to request the results of running the script block instead of requesting a module object. The script block in the new module defines the SayHello function and then calls the function. + ## PARAMETERS ### -ArgumentList + Specifies arguments (parameter values) that are passed to the script block. ```yaml @@ -209,6 +228,7 @@ Accept wildcard characters: False ``` ### -AsCustomObject + Returns a custom object that represents the dynamic module. The module members are implemented as script methods of the custom object, but they are not imported into the session. You can save the custom object in a variable and use dot notation to invoke the members. @@ -228,6 +248,7 @@ Accept wildcard characters: False ``` ### -Cmdlet + Exports only the specified cmdlets from the module into the current session. Enter a comma-separated list of cmdlets. Wildcard characters are permitted. @@ -248,6 +269,7 @@ Accept wildcard characters: True ``` ### -Function + Exports only the specified functions from the module into the current session. Enter a comma-separated list of functions. Wildcard characters are permitted. @@ -266,6 +288,7 @@ Accept wildcard characters: True ``` ### -Name + Specifies a name for the new module. You can also pipe a module name to New-Module. @@ -284,6 +307,7 @@ Accept wildcard characters: False ``` ### -ReturnResult + Runs the script block and returns the script block results instead of returning a module object. ```yaml @@ -299,6 +323,7 @@ Accept wildcard characters: False ``` ### -ScriptBlock + Specifies the contents of the dynamic module. Enclose the contents in braces ( { } ) to create a script block. This parameter is required. @@ -316,21 +341,29 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.String + You can pipe a module name string to New-Module. + ## OUTPUTS ### System.Management.Automation.PSModuleInfo, System.Management.Automation.PSCustomObject, or None + By default, New-Module generates a PSModuleInfo object. If you use the AsCustomObject parameter, it generates a PSCustomObject object. If you use the ReturnResult parameter, it returns the result of evaluating the script block in the dynamic module. + ## NOTES -* You can also refer to New-Module by its alias, "nmo". For more information, see about_Aliases. -* +- You can also refer to New-Module by its alias, "nmo". For more information, see about_Aliases. + +- + ## RELATED LINKS [Export-ModuleMember](Export-ModuleMember.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/New-ModuleManifest.md b/reference/3.0/Microsoft.PowerShell.Core/New-ModuleManifest.md index cd49d013fe5e..5e495b26ba59 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/New-ModuleManifest.md +++ b/reference/3.0/Microsoft.PowerShell.Core/New-ModuleManifest.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=141555 external help file: System.Management.Automation.dll-Help.xml title: New-ModuleManifest --- - # New-ModuleManifest + ## SYNOPSIS + Creates a new module manifest. + ## SYNTAX ``` @@ -26,6 +28,7 @@ New-ModuleManifest [-Path] [-NestedModules ] [-Guid ] [ ``` ## DESCRIPTION + The **New-ModuleManifest** cmdlet creates a new module manifest (.psd1) file, populates its values, and saves the manifest file in the specified path. Module authors can use this cmdlet to create a manifest for their module. @@ -42,11 +45,13 @@ 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 commonly used parameters that are not specified in the command, in addition to required parameter values. Beginning in Windows PowerShell 3.0, it prompts only when required parameter values are not specified. + ## EXAMPLES ### Example 1 + ``` -PS C:\> New-ModuleManifest -Path C:\Users\User01\Documents\WindowsPowerShell\Modules\Test-Module\Test-Module.psd1 -PassThru +PS> New-ModuleManifest -Path C:\Users\User01\Documents\WindowsPowerShell\Modules\Test-Module\Test-Module.psd1 -PassThru ## Module manifest for module 'TestModule' ## Generated by: User01 @@ -104,16 +109,20 @@ This command creates a new module manifest in the file that is specified by the The **PassThru** parameter sends the output to the pipeline as well as to the file. The output shows the default values of all keys in the manifest. + ### Example 2 + ``` -PS C:\> New-ModuleManifest -PowerShellVersion 1.0 -AliasesToExport JKBC, DRC, TAC -Path C:\ps-test\ManifestTest.psd1 +PS> New-ModuleManifest -PowerShellVersion 1.0 -AliasesToExport JKBC, DRC, TAC -Path C:\ps-test\ManifestTest.psd1 ``` This command creates a new module manifest. It uses the **PowerShellVersion** and **AliasesToExport** parameters to add values to the corresponding manifest keys. + ### Example 3 + ``` -PS C:\> New-ModuleManifest -RequiredModules BitsTransfer,@{ModuleName="PSScheduledJob";ModuleVersion="1.0.0.0";GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"} +PS> New-ModuleManifest -RequiredModules BitsTransfer,@{ModuleName="PSScheduledJob";ModuleVersion="1.0.0.0";GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"} ``` This example shows how to use the string and hash table formats of the **ModuleList**, **RequiredModules**, and **NestedModules** parameter. @@ -122,9 +131,11 @@ You can combine strings and hash tables in the same parameter value. This command commands creates a module manifest for a module that requires the **BitsTransfer** and **PSScheduledJob** modules. The command uses a string format to specify the name of the **BitsTransfer** module and the hash table format to specify the name, a GUID, and a version of the **PSScheduledJob** module. + ### Example 4 + ``` -PS C:\> New-ModuleManifest -HelpInfoUri "http://http://go.microsoft.com/fwlink/?LinkID=603" +PS> New-ModuleManifest -HelpInfoUri "http://http://go.microsoft.com/fwlink/?LinkID=603" ``` This example shows creates a module manifest for a module that supports the Updatable Help feature. @@ -136,9 +147,11 @@ This value tells the Updatable Help system where to find the HelpInfo XML updata For information about Updatable Help, see about_Updatable_Help (http://go.microsoft.com/fwlink/?LinkID=235801). For information about the HelpInfo XML file, see "Supporting Updatable Help" in MSDN. + ### Example 5 + ``` -PS C:\> Get-Module PSScheduledJob -List | Format-List -Property * +PS> Get-Module PSScheduledJob -List | Format-List -Property * LogPipelineExecutionDetails : FalseName : @@ -179,7 +192,7 @@ OnRemove : ExportedFormatFiles : {C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\PSScheduledJob\PSScheduledJob.Format.ps1xml} ExportedTypeFiles : {C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\PSScheduledJob\PSScheduledJob.types.ps1xml} -PS C:\> Get-Module -List | Format-Table -Property Name, PowerShellVersion +PS> Get-Module -List | Format-Table -Property Name, PowerShellVersion Name PowerShellVersion ---- ----------------- @@ -211,9 +224,11 @@ The command sends the module to the Format-List cmdlet, which displays all prope The second command uses the Format-Table cmdlet to display the PowerShellVersion property of all installed modules in a table. The PowerShellVersion property is defined in the module manifest. + ## PARAMETERS ### -AliasesToExport + Specifies the aliases that the module exports. Wildcards are permitted. @@ -235,6 +250,7 @@ Accept wildcard characters: True ``` ### -Author + Specifies the module author. If you omit this parameter, **New-ModuleManifest** creates an **Author** key with the name of the current user. @@ -252,6 +268,7 @@ Accept wildcard characters: False ``` ### -ClrVersion + Specifies the minimum version of the Common Language Runtime (CLR) of the Microsoft .NET Framework that the module requires. ```yaml @@ -267,6 +284,7 @@ Accept wildcard characters: False ``` ### -CmdletsToExport + Specifies the cmdlets that the module exports. Wildcards are permitted. @@ -288,6 +306,7 @@ Accept wildcard characters: True ``` ### -CompanyName + Identifies the company or vendor who created the module. If you omit this parameter, **New-ModuleManifest** creates a **CompanyName** key with a value of "Unknown". @@ -305,6 +324,7 @@ Accept wildcard characters: False ``` ### -Copyright + Specifies a copyright statement for the module. If you omit this parameter, **New-ModuleManifest** creates a **Copyright** key with a value of "(c) \ \. @@ -323,6 +343,7 @@ Accept wildcard characters: False ``` ### -Description + Describes the contents of the module. ```yaml @@ -338,6 +359,7 @@ Accept wildcard characters: False ``` ### -DotNetFrameworkVersion + Specifies the minimum version of the Microsoft .NET Framework that the module requires. ```yaml @@ -353,6 +375,7 @@ Accept wildcard characters: False ``` ### -FileList + Specifies all items that are included in the module. This key is designed to act as a module inventory. The files listed in the key are included when the module is published, but any functions are not automatically exported. @@ -370,6 +393,7 @@ Accept wildcard characters: False ``` ### -FormatsToProcess + Specifies the formatting files (.ps1xml) that run when the module is imported. When you import a module, Windows PowerShell runs the Update-FormatData cmdlet with the specified files. @@ -388,6 +412,7 @@ Accept wildcard characters: False ``` ### -FunctionsToExport + Specifies the functions that the module exports. Wildcards are permitted. @@ -409,6 +434,7 @@ Accept wildcard characters: True ``` ### -Guid + Specifies a unique identifier for the module. The GUID can be used to distinguish among modules with the same name. @@ -429,6 +455,7 @@ Accept wildcard characters: False ``` ### -HelpInfoUri + Specifies the Internet address of the HelpInfo XML file for the module. Enter an Uniform Resource Identifier (URI) that begins with "http" or "https". @@ -452,6 +479,7 @@ Accept wildcard characters: False ``` ### -ModuleList + Lists all modules that are included in this module. Enter each module name as a string or as a hash table with **ModuleName** and **ModuleVersion** keys. @@ -475,6 +503,7 @@ Accept wildcard characters: False ``` ### -ModuleVersion + Specifies the version of the module. This parameter is not required by the cmdlet, but a **ModuleVersion** key is required in the manifest. @@ -493,6 +522,7 @@ Accept wildcard characters: False ``` ### -NestedModules + Specifies script modules (.psm1) and binary modules (.dll) that are imported into the module's session state. The files in the **NestedModules** key run in the order in which they are listed in the value. @@ -522,6 +552,7 @@ Accept wildcard characters: False ``` ### -PassThru + Writes the resulting module manifest to the console, in addition to creating a .psd1 file. By default, this cmdlet does not generate any output. @@ -538,6 +569,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path and file name of the new module manifest. Enter a path and file name with a .psd1 file name extension, such as "$pshome\Modules\MyModule\MyModule.psd1". This parameter is required. @@ -562,6 +594,7 @@ Accept wildcard characters: False ``` ### -PowerShellHostName + Specifies the name of the Windows PowerShell host program that the module requires. Enter the name of the host program, such as "Windows PowerShell ISE Host" or "ConsoleHost". Wildcards are not permitted. @@ -581,6 +614,7 @@ Accept wildcard characters: False ``` ### -PowerShellHostVersion + Specifies the minimum version of the Windows PowerShell host program that works with the module. Enter a version number, such as 1.1. @@ -597,6 +631,7 @@ Accept wildcard characters: False ``` ### -PowerShellVersion + Specifies the minimum version of Windows PowerShell that will work with this module. For example, you can enter 1.0, 2.0, or 3.0 as the value of this parameter. @@ -613,6 +648,7 @@ Accept wildcard characters: False ``` ### -PrivateData + Specifies data that is passed to the module when it is imported. ```yaml @@ -628,6 +664,7 @@ Accept wildcard characters: False ``` ### -ProcessorArchitecture + Specifies the processor architecture that the module requires. Valid values are x86, AMD64, IA64, and None (unknown or unspecified). @@ -644,6 +681,7 @@ Accept wildcard characters: False ``` ### -RequiredAssemblies + Specifies the assembly (.dll) files that the module requires. Enter the assembly file names. Windows PowerShell loads the specified assemblies before updating types or formats, importing nested modules, or importing the module file that is specified in the value of the **RootModule** key. @@ -663,6 +701,7 @@ Accept wildcard characters: False ``` ### -RequiredModules + Specifies modules that must be in the global session state. If the required modules are not in the global session state, Windows PowerShell imports them. If the required modules are not available, the Import-Module command fails. @@ -688,6 +727,7 @@ Accept wildcard characters: False ``` ### -ScriptsToProcess + Specifies script (.ps1) files that run in the caller's session state when the module is imported. You can use these scripts to prepare an environment, just as you might use a login script. @@ -706,6 +746,7 @@ Accept wildcard characters: False ``` ### -TypesToProcess + Specifies the type files (.ps1xml) that run when the module is imported. When you import the module, Windows PowerShell runs the Update-TypeData cmdlet with the specified files. @@ -724,6 +765,7 @@ Accept wildcard characters: False ``` ### -VariablesToExport + Specifies the variables that the module exports. Wildcards are permitted. @@ -745,6 +787,7 @@ Accept wildcard characters: True ``` ### -DefaultCommandPrefix + Specifies a prefix that is prepended to the nouns of all commands in the module when they are imported into a session. Enter a prefix string. Prefixes prevent command name conflicts in a user's session. @@ -766,6 +809,7 @@ Accept wildcard characters: False ``` ### -RootModule + Specifies the primary or "root" file of the module. Enter the file name of a script (.ps1), a script module (.psm1), a module manifest(.psd1), an assembly (.dll), a cmdlet definition XML file (.cdxml), or a workflow (.xaml). When the module is imported, the members that are exported from the root module file are imported into the caller's session state. @@ -790,6 +834,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -805,6 +850,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -821,24 +867,32 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### None or System.String + By default, New-ModuleManifest does not generate any output. However, if you use the PassThru parameter, it generates a System.String object representing the module manifest.. + ## NOTES -* Module manifests are usually optional. However, a module manifest is required to export an assembly that is installed in the global assembly cache. -* To add or change files in the $pshome\Modules directory (%Windir%\System32\WindowsPowerShell\v1.0\Modules), start Windows PowerShell with the "Run as administrator" option. -* In Windows PowerShell 2.0, many parameters of **New-ModuleManifest** are mandatory, even though they are not required in a module manifest. In Windows PowerShell 3.0, only the **Path** parameter is mandatory. -* A "session" is an instance of the Windows PowerShell execution environment. A session can have one or more session states. By default, a session has only a global session state, but each imported module has its own session state. Session states allow the commands in a module to run without affecting the global session state. + +- Module manifests are usually optional. However, a module manifest is required to export an assembly that is installed in the global assembly cache. +- To add or change files in the $pshome\Modules directory (%Windir%\System32\WindowsPowerShell\v1.0\Modules), start Windows PowerShell with the "Run as administrator" option. +- In Windows PowerShell 2.0, many parameters of **New-ModuleManifest** are mandatory, even though they are not required in a module manifest. In Windows PowerShell 3.0, only the **Path** parameter is mandatory. +- A "session" is an instance of the Windows PowerShell execution environment. A session can have one or more session states. By default, a session has only a global session state, but each imported module has its own session state. Session states allow the commands in a module to run without affecting the global session state. The "caller's session state" is the session state into which a module is imported. Typically, it refers to the global session state, but when a module imports nested modules, the "caller" is the module and the "caller's session state" is the module's session state. + ## RELATED LINKS [Export-ModuleMember](Export-ModuleMember.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md index ad88728897f3..6dc1ca6f5407 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/New-PSSession.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135237 external help file: System.Management.Automation.dll-Help.xml title: New-PSSession --- - # New-PSSession + ## SYNOPSIS + Creates a persistent connection to a local or remote computer. + ## SYNTAX ### ComputerName (Default) + ``` New-PSSession [[-ComputerName] ] [-Credential ] [-Name ] [-EnableNetworkAccess] [-Port ] [-UseSSL] [-ConfigurationName ] [-ApplicationName ] @@ -22,6 +25,7 @@ New-PSSession [[-ComputerName] ] [-Credential ] [-Name < ``` ### Uri + ``` New-PSSession [-Credential ] [-Name ] [-EnableNetworkAccess] [-ConfigurationName ] [-ThrottleLimit ] [-ConnectionUri] [-AllowRedirection] @@ -30,12 +34,14 @@ New-PSSession [-Credential ] [-Name ] [-EnableNetworkAcc ``` ### Session + ``` New-PSSession [[-Session] ] [-Name ] [-EnableNetworkAccess] [-ThrottleLimit ] [] ``` ## DESCRIPTION + The **New-PSSession** cmdlet creates a Windows PowerShell session (PSSession) on a local or remote computer. When you create a PSSession, Windows PowerShell establishes a persistent connection to the remote computer. @@ -46,28 +52,34 @@ For more information, see about_PSSessions (http://go.microsoft.com/fwlink/?Link You can run commands on a remote computer without creating a PSSession by using the **ComputerName** parameters of **Enter-PSSession** or **Invoke-Command**. When you use the **ComputerName** parameter, Windows PowerShell creates a temporary connection that is used for the command and is then closed. + ## EXAMPLES ### Example 1 + ``` -PS C:\> $s = New-PSSession +PS> $s = New-PSSession ``` This command creates a new PSSession on the local computer and saves the PSSession in the $s variable. You can now use this PSSession to run commands on the local computer. + ### Example 2 + ``` -PS C:\> $Server01 = New-PSSession -ComputerName Server01 +PS> $Server01 = New-PSSession -ComputerName Server01 ``` This command creates a new PSSession on the Server01 computer and saves it in the $Server01 variable. When creating multiple PSSessions, assign them to variables with useful names. This will help you manage the PSSessions in subsequent commands. + ### Example 3 + ``` -PS C:\> $s1, $s2, $s3 = New-PSSession -ComputerName Server1,Server2,Server3 +PS> $s1, $s2, $s3 = New-PSSession -ComputerName Server1,Server2,Server3 ``` This command creates three new PSSessions, one on each of the computers specified by the ComputerName parameter. @@ -78,9 +90,11 @@ It assigns the Server01 PSSession to $s1, the Server02 PSSession to $s2, and the When you assign multiple objects to an array of variables, Windows PowerShell assigns each object to a variable in the array respectively. If there are more objects than variables, all remaining objects are assigned to the last variable. If there are more variables than objects, the remaining variables are empty (null). + ### Example 4 + ``` -PS C:\> New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12 +PS> New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12 ``` This command creates a new PSSession on the Server01 computer that connects to server port 8081 and uses the SSL protocol. @@ -88,9 +102,11 @@ The new PSSession uses an alternate session configuration called "E12". Before setting the port, you must configure the WinRM listener on the remote computer to listen on port 8081. For more information, see the description of the **Port** parameter. + ### Example 5 + ``` -PS C:\> New-PSSession -Session $s -Credential Domain01\User01 +PS> New-PSSession -Session $s -Credential Domain01\User01 ``` This command creates a new PSSession with the same properties as an existing PSSession. @@ -98,9 +114,11 @@ You can use this command format when the resources of an existing PSSession are The command uses the **Session** parameter of **New-PSSession** to specify the PSSession saved in the $s variable. It uses the credentials of the Domain1\Admin01 user to complete the command. + ### Example 6 + ``` -PS C:\> $global:s = New-PSSession -ComputerName Server1.Domain44.Corpnet.Fabrikam.com -Credential Domain01\Admin01 +PS> $global:s = New-PSSession -ComputerName Server1.Domain44.Corpnet.Fabrikam.com -Credential Domain01\Admin01 ``` This example shows how to create a PSSession with a global scope on a computer in a different domain. @@ -112,27 +130,33 @@ In this case, the $s variable is cast to a global scope. The command uses the **ComputerName** parameter to specify the remote computer. Because the computer is in a different domain than the user account, the full name of the computer is specified along with the credentials of the user. + ### Example 7 + ``` -PS C:\> $rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50 +PS> $rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50 ``` This command creates a PSSession on each of the 200 computers listed in the Servers.txt file and it stores the resulting PSSession in the $rs variable. The PSSessions have a throttle limit of 50. You can use this command format when the names of computers are stored in a database, spreadsheet, text file, or other text-convertible format. + ### Example 8 + ``` -PS C:\> $s = New-PSSession -URI http://Server01:91/NewSession -Credential Domain01\User01 +PS> $s = New-PSSession -URI http://Server01:91/NewSession -Credential Domain01\User01 ``` This command creates a PSSession on the Server01 computer and stores it in the $s variable. It uses the URI parameter to specify the transport protocol, the remote computer, the port, and an alternate session configuration. It also uses the **Credential** parameter to specify a user account with permission to create a session on the remote computer. + ### Example 9 + ``` -PS C:\> $s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16 -PS C:\> Invoke-Command -Session $s -ScriptBlock {Get-Process PowerShell} -AsJob +PS> $s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16 +PS> Invoke-Command -Session $s -ScriptBlock {Get-Process PowerShell} -AsJob ``` These commands create a set of PSSessions and then run a background job in each of the PSSessions. @@ -149,15 +173,18 @@ The second command uses the **AsJob** parameter of the Invoke-Command cmdlet to For more information about Windows PowerShell background jobs, see [about_Jobs](About/about_Jobs.md) and [about_Remote_Jobs](About/about_Remote_Jobs.md). ### Example 10 + ``` -PS C:\> New-PSSession -ConnectionURI https://management.exchangelabs.com/Management +PS> New-PSSession -ConnectionURI https://management.exchangelabs.com/Management ``` This command creates a new PSSession that connects to a computer that is specified by a URI instead of a computer name. + ### Example 11 + ``` -PS C:\> $so = New-PSSessionOption -SkipCACheck -PS C:\> New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential Server01\Admin01 +PS> $so = New-PSSessionOption -SkipCACheck +PS> New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential Server01\Admin01 ``` This example shows how to create a session option object and use the **SessionOption** parameter. @@ -168,9 +195,11 @@ It saves the resulting **SessionOption** object in the $so parameter. The second command uses the option in a new session. The command uses the **New-PSSession** cmdlet to create a new session. The value of the SessionOption parameter is the **SessionOption** object in the $so variable. + ## PARAMETERS ### -AllowRedirection + Allows redirection of this connection to an alternate Uniform Resource Identifier (URI). When you use the **ConnectionURI** parameter, the remote destination can return an instruction to redirect to a different URI. @@ -193,6 +222,7 @@ Accept wildcard characters: False ``` ### -ApplicationName + Specifies the application name segment of the connection URI. Use this parameter to specify the application name when you are not using the **ConnectionURI** parameter in the command. @@ -217,6 +247,7 @@ Accept wildcard characters: False ``` ### -Authentication + Specifies the mechanism that is used to authenticate the user's credentials. Valid values are "**Default**", "**Basic**", "**Credssp**", "**Digest**", "**Kerberos**", "**Negotiate**", and "**NegotiateWithImplicitCredential**". The default value is "**Default**". @@ -240,6 +271,7 @@ Accept wildcard characters: False ``` ### -CertificateThumbprint + Specifies the digital public key certificate (X509) of a user account that has permission to perform this action. Enter the certificate thumbprint of the certificate. @@ -261,6 +293,7 @@ Accept wildcard characters: False ``` ### -ComputerName + Creates a persistent connection (PSSession) to the specified computer. If you enter multiple computer names, **New-PSSession** creates multiple PSSessions, one for each computer. The default is the local computer. @@ -289,6 +322,7 @@ Accept wildcard characters: False ``` ### -ConfigurationName + Specifies the session configuration that is used for the new PSSession. Enter a configuration name or the fully qualified resource Uniform Resource Identifier (URI) for a session configuration. @@ -314,6 +348,7 @@ Accept wildcard characters: False ``` ### -ConnectionUri + Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint for the session. The URI must be fully qualified. The format of this string is as follows: @@ -345,6 +380,7 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. @@ -365,6 +401,7 @@ Accept wildcard characters: False ``` ### -EnableNetworkAccess + Adds an interactive security token to loopback sessions. The interactive token lets you run commands in the loopback session that get data from other computers. For example, you can run a command in the session that copies XML files from a remote computer to the local computer. @@ -398,6 +435,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies a friendly name for the PSSession. You can use the name to refer to the PSSession when using other cmdlets, such as Get-PSSession and Enter-PSSession. @@ -416,6 +454,7 @@ Accept wildcard characters: False ``` ### -Port + Specifies the network port on the remote computer that is used for this connection. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). @@ -446,6 +485,7 @@ Accept wildcard characters: False ``` ### -Session + Uses the specified PSSession as a model for the new PSSession. This parameter creates new PSSessions with the same properties as the specified PSSessions. @@ -466,6 +506,7 @@ Accept wildcard characters: False ``` ### -SessionOption + Sets advanced options for the session. Enter a **SessionOption** object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. @@ -492,6 +533,7 @@ Accept wildcard characters: False ``` ### -ThrottleLimit + Specifies the maximum number of concurrent connections that can be established to run this command. If you omit this parameter or enter a value of 0 (zero), the default value, 32, is used. @@ -510,6 +552,7 @@ Accept wildcard characters: False ``` ### -UseSSL + Uses the Secure Sockets Layer (SSL) protocol to establish a connection to the remote computer. By default, SSL is not used. @@ -531,21 +574,27 @@ 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.URI, System.Management.Automation.Runspaces.PSSession + You can pipe a computer name (string), ConnectionURI (URI), or session (PSSession) object to **New-PSSession**. + ## OUTPUTS ### 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](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. -* +- 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. + +- + ## RELATED LINKS [Connect-PSSession](Connect-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionConfigurationFile.md b/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionConfigurationFile.md index 7e1d20dd41eb..80679784ced4 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionConfigurationFile.md +++ b/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionConfigurationFile.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=217036 external help file: System.Management.Automation.dll-Help.xml title: New-PSSessionConfigurationFile --- - # New-PSSessionConfigurationFile + ## SYNOPSIS + Creates a file that defines a session configuration. + ## SYNTAX ``` @@ -25,6 +27,7 @@ New-PSSessionConfigurationFile [-Path] [-SchemaVersion ] [-Gui ``` ## DESCRIPTION + The **New-PSSessionConfigurationFile** cmdlet creates a file of settings that define a session configuration and the environment of sessions that are created by using the session configuration. To use the file in a session configuration, use the **Path** parameters of the Register-PSSessionConfiguration or Set-PSSessionConfiguration cmdlets. @@ -44,11 +47,13 @@ The settings in the file are used in addition to the optional startup script and For more information about session configurations and session configuration files, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152) and about_Session_Configuration_Files (http://go.microsoft.com/fwlink/?LinkID=236023). This cmdlet is introduced in Windows PowerShell 3.0. + ## EXAMPLES ### Example 1: Designing a specialized session + ``` -PS C:\> New-PSSessionConfigurationFile -ModulesToImport DMSCmdlets, *Microsoft* -ScriptsToProcess \\Server01\Scripts\Get-DMSServers.ps1 +PS> New-PSSessionConfigurationFile -ModulesToImport DMSCmdlets, *Microsoft* -ScriptsToProcess \\Server01\Scripts\Get-DMSServers.ps1 ``` The following command creates a session configuration file for IT technical sessions on a cloud-based document management server. @@ -57,28 +62,30 @@ You can use the resulting file to create a customized session configuration on t The ACLs on the session configuration determine who can use the session configuration to create a session on the server. Customized sessions that include the cmdlets, functions and scripts that technical users need make it easier for those users to write scripts that automate common tasks. + ### Example 2: Restricting Language in a Session + ``` The first pair of commands uses the **New-PSSessionConfigurationFile** cmdlet to create two session configuration files. The first command creates a no-language file. The second command creates a restricted-language file. Other than the value of the **LanguageMode** parameter, the session configuration files are equivalent. -PS C:\> New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage +PS> New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage -PS C:\> New-PSSessionConfigurationFile -Path .\RestrictedLanguage.pssc -LanguageMode RestrictedLanguage +PS> New-PSSessionConfigurationFile -Path .\RestrictedLanguage.pssc -LanguageMode RestrictedLanguage The second pair of commands uses the configuration files to create session configurations on the local computer. -PS C:\> Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force +PS> Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force -PS C:\> Register-PSSessionConfiguration -Path .\RestrictedLanguage.pssc -Name RestrictedLanguage -Force +PS> Register-PSSessionConfiguration -Path .\RestrictedLanguage.pssc -Name RestrictedLanguage -Force The third pair of commands creates two sessions, each of which uses one of the session configurations that were created in the previous command pair. -PS C:\> $NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage +PS> $NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage -PS C:\> $RestrictedLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage +PS> $RestrictedLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage The seventh command uses the Invoke-Command cmdlet to run an If statement in the no-Language session. The command fails, because the language elements in the command are not permitted in a no-language session. -PS C:\> Invoke-Command -Session $NoLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } +PS> Invoke-Command -Session $NoLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } The syntax is not supported by this runspace. This might be because it is in no-language mode. + CategoryInfo : ParserError: (if ((Get-Date) ...") {"Before"} :String) [], ParseException + FullyQualifiedErrorId : ScriptsNotAllowed @@ -86,7 +93,7 @@ The syntax is not supported by this runspace. This might be because it is in no- The eighth command uses the **Invoke-Command** cmdlet to run the same If statement in the restricted-language session. Because these language elements are permitted in the restricted-language session, the command succeeds. -PS C:\> Invoke-Command -Session $RestrictedLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } +PS> Invoke-Command -Session $RestrictedLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } Before ``` @@ -95,36 +102,42 @@ The example shows the effect of using the **LanguageMode** parameter of **New-PS To run the commands in this example, start Windows PowerShell with the "Run as administrator" option. This option is required to run the Register-PSSessionConfiguration cmdlet. + ### Example 3: Changing a Session Configuration File + ``` The first command uses the **New-PSSessionConfigurationFile** cmdlet to create a session configuration file that imports the required modules. -PS C:\> New-PSSessionConfigurationFile -Path .\New-ITTasks.pssc -ModulesToImport Microsoft*, ITTasks, PSScheduledJob +PS> New-PSSessionConfigurationFile -Path .\New-ITTasks.pssc -ModulesToImport Microsoft*, ITTasks, PSScheduledJob The second command uses the Set-PSSessionConfiguration cmdlet to replace the current .pssc file with the new one. Changes to the session configuration affects all sessions created after the change completes. -PS C:\> Set-PSSessionConfiguration -Name ITTasks -Path .\New-ITTasks.pssc +PS> Set-PSSessionConfiguration -Name ITTasks -Path .\New-ITTasks.pssc ``` This example shows how to change the session configuration file that is used in a session configuration. In this scenario, the administrator wants to add the PSScheduledJob module to sessions created with the ITTasks session configuration. Previously, these sessions had only the core modules and an internal "ITTasks" module. + ### Example 4: Editing a Session Configuration File + ``` The first command uses the Get-PSSessionConfiguration command to get the path to the configuration file for the ITConfig session configuration. The path is stored in the **ConfigFilePath** property of the session configuration. -PS C:\> (Get-PSSessionConfiguration -Name ITConfig).ConfigFilePath +PS> (Get-PSSessionConfiguration -Name ITConfig).ConfigFilePath C:\WINDOWS\System32\WindowsPowerShell\v1.0\SessionConfig\ITConfig_1e9cb265-dae0-4bd3-89a9-8338a47698a1.pssc To edit the session configuration copy of the configuration file, you might need to edit the file permissions.In this case, the current user, who is a member of the Administrators group on the system, was explicitly granted full control of the file by using the following method: Right-click the file icon, and then click **Properties**. On the **Security** tab, click **Edit**, and then click **Add**. Add the user, and then, in the **Full control** column, click **Allow**.Now the user can edit the file. A new "slst" alias for the Select-String cmdlet is added to the file. -PS C:\> AliasDefinitions = @(@{Name='slst';Value='Select-String'}) +PS> AliasDefinitions = @(@{Name='slst';Value='Select-String'}) The second command uses the Test-PSSessionConfigurationFile cmdlet to test the edited file. The command uses the **Verbose** parameter, which displays the file errors that the cmdlet detects, if any.In this case, the cmdlet returns True ($true), which indicates that it did not detect any errors in the file. -PS C:\> Test-PSSessionConfigurationFile -Path (Get-PSSessionConfiguration -Name ITConfig).ConfigFilePath +PS> Test-PSSessionConfigurationFile -Path (Get-PSSessionConfiguration -Name ITConfig).ConfigFilePath True ``` This example shows how to change a session configuration by editing the active session configuration copy of the configuration file. + ### Example 5: Sample Configuration File + ``` -PS C:\> New-PSSessionConfigurationFile +PS> New-PSSessionConfigurationFile -Path .\SampleFile.pssc -Schema "1.0.0.0" -Author "User01" @@ -253,14 +266,17 @@ This example displays a **New-PSSessionConfigurationFile** command that uses all It is included to show the correct input format for each parameter. The resulting SampleFile.pssc is displayed in the output. + ### 1: + ``` -PS C:\> +PS> ``` ## PARAMETERS ### -AliasDefinitions + Adds the specified aliases to sessions that use the session configuration. Enter a hash table with the following keys: @@ -284,6 +300,7 @@ Accept wildcard characters: False ``` ### -AssembliesToLoad + Specifies the assemblies to load into the sessions that use the session configuration. ```yaml @@ -299,6 +316,7 @@ Accept wildcard characters: False ``` ### -Author + Identifies the author of the session configuration or the configuration file. The default is the current user. The value of this parameter is visible in the session configuration file, but it is not a property of the session configuration object. @@ -316,6 +334,7 @@ Accept wildcard characters: False ``` ### -CompanyName + Identifies the company that created the session configuration or the configuration file. The default value is "**Unknown**". The value of this parameter is visible in the session configuration file, but it is not a property of the session configuration object. @@ -333,6 +352,7 @@ Accept wildcard characters: False ``` ### -Copyright + Adds a copyright to the session configuration file. The value of this parameter is visible in the session configuration file, but it is not a property of the session configuration object. @@ -351,6 +371,7 @@ Accept wildcard characters: False ``` ### -Description + Describes the session configuration or the session configuration file. The value of this parameter is visible in the session configuration file, but it is not a property of the session configuration object. @@ -367,6 +388,7 @@ Accept wildcard characters: False ``` ### -EnvironmentVariables + Adds environment variables to the session. Enter a hash table in which the keys are the environment variable names and the values are the environment variable values. @@ -385,6 +407,7 @@ Accept wildcard characters: False ``` ### -ExecutionPolicy + Specifies the execution policy of sessions that use the session configuration. If you omit this parameter, the value of the **ExecutionPolicy** key in the session configuration file is "Restricted". For information about execution policies in Windows PowerShell, see about_Execution_Policies (http://go.microsoft.com/fwlink/?LinkID=135170). @@ -402,6 +425,7 @@ Accept wildcard characters: False ``` ### -FormatsToProcess + Specifies the formatting files (.ps1xml) that run in sessions that use the session configuration. The value of this parameter must be a full or absolute path to the formatting files. @@ -418,6 +442,7 @@ Accept wildcard characters: False ``` ### -FunctionDefinitions + Adds the specified functions to sessions that use the session configuration. Enter a hash table with the following keys: @@ -440,6 +465,7 @@ Accept wildcard characters: False ``` ### -Guid + Specifies a unique identifier for the session configuration file. If you omit this parameter, **New-PSSessionConfigurationFile** generates a GUID for the file. To create a new GUID in Windows PowerShell, type "`\[guid\]::NewGuid()`". @@ -457,6 +483,7 @@ Accept wildcard characters: False ``` ### -LanguageMode + Determines which elements of the Windows PowerShell language are permitted in sessions that use this session configuration. You can use this parameter to restrict the commands that particular users can run on the computer. @@ -486,6 +513,7 @@ Accept wildcard characters: False ``` ### -ModulesToImport + Specifies the modules and snap-ins that are automatically imported into sessions that use the session configuration. By default, only the Microsoft.PowerShell.Core snap-in is imported into remote sessions, but unless the cmdlets are excluded, users can use the Import-Module and Add-PSSnapin cmdlets to add modules and snap-ins to the session. @@ -515,6 +543,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path and file name of the session configuration file. The file must have a **.pssc** file name extension. @@ -531,6 +560,7 @@ Accept wildcard characters: False ``` ### -PowerShellVersion + Specifies the version of the Windows PowerShell engine in sessions that use the session configuration. Valid values are 2.0 and 3.0. If you omit this parameter, the PowerShellVersion key is commented-out and newest version of Windows PowerShell runs in the session. @@ -550,6 +580,7 @@ Accept wildcard characters: False ``` ### -SchemaVersion + Specifies the version of the session configuration file schema. The default value is "1.0.0.0". @@ -566,6 +597,7 @@ Accept wildcard characters: False ``` ### -ScriptsToProcess + Adds the specified scripts to sessions that use the session configuration. Enter the path and file names of the scripts. The value of this parameter must be a full or absolute path to script file names. @@ -583,6 +615,7 @@ Accept wildcard characters: False ``` ### -SessionType + Specifies the type of session that is created by using the session configuration. The default value is **Default**. Valid values are: @@ -604,6 +637,7 @@ Accept wildcard characters: False ``` ### -TypesToProcess + Adds the specified type files (.ps1xml) to sessions that use the session configuration. Enter the type file names. The value of this parameter must be a full or absolute path to type file names. @@ -621,6 +655,7 @@ Accept wildcard characters: False ``` ### -VariableDefinitions + Adds the specified variables to sessions that use the session configuration. Enter a hash table with the following keys: @@ -643,6 +678,7 @@ Accept wildcard characters: False ``` ### -VisibleAliases + Limits the aliases in the session to those specified in the value of this parameter, plus any aliases that you define in the **AliasDefinition** parameter. Wildcards are supported. By default, all aliases that are defined by the Windows PowerShell engine and all aliases that modules export are visible in the session. @@ -664,6 +700,7 @@ Accept wildcard characters: False ``` ### -VisibleCmdlets + Limits the cmdlets in the session to those specified in the value of this parameter. Wildcards are supported. @@ -685,6 +722,7 @@ Accept wildcard characters: False ``` ### -VisibleFunctions + Limits the functions in the session to those specified in the value of this parameter, plus any functions that you define in the **FunctionDefinition** parameter. Wildcards are supported. @@ -706,6 +744,7 @@ Accept wildcard characters: False ``` ### -VisibleProviders + Limits the Windows PowerShell providers in the session to those specified in the value of this parameter. Wildcards are supported. @@ -727,24 +766,32 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + This cmdlet does not take input from the pipeline. + ## OUTPUTS ### None + This cmdlet does not generate any output. + ## NOTES -* The Visible parameters, such as **VisibleCmdlets** and **VisibleProviders**, do not import items into the session. Instead, they select from among the items imported into the session. For example, if the value of the **VisibleProviders** parameter is the Certificate provider, but the **ModulesToImport** parameter doesn't specify the Microsoft.PowerShell.Security module that contains the Certificate provider, the Certificate provider is not visible in the session. -* **New-PSSessionConfigurationFile** creates a session configuration file with a .pssc file name extension in the path that you specify in the **Path** parameter. When you use the session configuration file to create a session configuration, the Register-PSSessionConfiguration cmdlet copies the configuration file and saves an active copy of the file in the **SessionConfig** subdirectory of the $pshome directory. + +- The Visible parameters, such as **VisibleCmdlets** and **VisibleProviders**, do not import items into the session. Instead, they select from among the items imported into the session. For example, if the value of the **VisibleProviders** parameter is the Certificate provider, but the **ModulesToImport** parameter doesn't specify the Microsoft.PowerShell.Security module that contains the Certificate provider, the Certificate provider is not visible in the session. +- **New-PSSessionConfigurationFile** creates a session configuration file with a .pssc file name extension in the path that you specify in the **Path** parameter. When you use the session configuration file to create a session configuration, the Register-PSSessionConfiguration cmdlet copies the configuration file and saves an active copy of the file in the **SessionConfig** subdirectory of the $pshome directory. The **ConfigFilePath** property of the session configuration contains the fully qualified path to the active session configuration file. You can edit the active configuration file in the $pshome directory at any time, either by using Windows PowerShell ISE or any text editor. The changes that you make affect all new sessions that use the session configuration, but not existing sessions. Before using an edited session configuration file, use the Test-PSSessionConfigurationFile cmdlet to verify that the configuration file entries are valid. + ## RELATED LINKS [Disable-PSSessionConfiguration](Disable-PSSessionConfiguration.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionOption.md b/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionOption.md index 23d28967f924..21510de49097 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionOption.md +++ b/reference/3.0/Microsoft.PowerShell.Core/New-PSSessionOption.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=144305 external help file: System.Management.Automation.dll-Help.xml title: New-PSSessionOption --- - # New-PSSessionOption + ## SYNOPSIS + Creates an object that contains advanced options for a PSSession. + ## SYNTAX ``` @@ -24,6 +26,7 @@ New-PSSessionOption [-MaximumRedirection ] [-NoCompression] [-NoMachinePr ``` ## DESCRIPTION + The **New-PSSessionOption** cmdlet creates an object that contains advanced options for a user-managed session ("PSSession"). You can use the object as the value of the **SessionOption** parameter of cmdlets that create a PSSession, such as New-PSSession, Enter-PSSession, and Invoke-Command. @@ -38,11 +41,13 @@ For more information about the **$PSSessionOption** preference variable, see [ab 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. For more information about session configurations, see about_Session_Configurations (http://go.microsoft.com/fwlink/?LinkID=145152). + ## EXAMPLES ### Example 1 + ``` -PS C:\> New-PSSessionOption +PS> New-PSSessionOption MaximumConnectionRedirectionCount : 5 NoCompression : False @@ -67,10 +72,12 @@ IdleTimeout : 00:04:00 ``` This command creates a session option object with all of the default values. + ### Example 2 + ``` -PS C:\> $pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB -PS C:\> New-PSSession -ComputerName Server01 -SessionOption $pso +PS> $pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB +PS> New-PSSession -ComputerName Server01 -SessionOption $pso ``` This example shows how to use a session option object to configure a session. @@ -79,18 +86,22 @@ The first command creates a new session option object and saves it in the value The second command uses the New-PSSession cmdlet to create a session on the Server01 remote computer. The command uses the session option object in the value of the $pso variable as the value of the SessionOption parameter of the command. + ### Example 3 + ``` -PS C:\> Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression) +PS> Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression) ``` This command uses the Enter-PSSession cmdlet to start an interactive session with the Server01 computer. The value of the **SessionOption** parameter is a **New-PSSessionOption** command with the **NoEncryption** and **NoCompression** switch parameters. The **New-PSSessionOption** command is enclosed in parentheses to make sure that it runs before the **Enter-PSSession** command. + ### Example 4 + ``` -PS C:\> $a = New-PSSessionOption +PS> $a = New-PSSessionOption MaximumConnectionRedirectionCount : 5 NoCompression : False @@ -113,10 +124,10 @@ OpenTimeout : 00:03:00 CancelTimeout : 00:01:00 IdleTimeout : 00:04:00 -PS C:\> $a.UICulture = (Get-UICulture) -PS C:\> $a.OpenTimeout = (New-Timespan -Minutes 4) -PS C:\> $a.MaximumConnectionRedirectionCount = 1 -PS C:\> $a +PS> $a.UICulture = (Get-UICulture) +PS> $a.OpenTimeout = (New-Timespan -Minutes 4) +PS> $a.MaximumConnectionRedirectionCount = 1 +PS> $a MaximumConnectionRedirectionCount : 1 NoCompression : False @@ -144,9 +155,11 @@ This example demonstrates that you can edit the session option object. All properties have read/write values. Use this method to create a standard session object for your enterprise, and then create customized versions of it for particular uses. + ### Example 5 + ``` -PS C:\> $PSSessionOption = New-PSSessionOption -OpenTimeOut 120000 +PS> $PSSessionOption = New-PSSessionOption -OpenTimeOut 120000 ``` This command creates a **$PSSessionOption** preference variable. @@ -157,10 +170,12 @@ To make the **$PSSessionOption** variable available in all sessions, add it to y 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 + ``` -PS C:\> $skipCN = New-PSSessionOption -SkipCNCheck -PS C:\> New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN +PS> $skipCN = New-PSSessionOption -SkipCNCheck +PS> New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN ``` This example shows how to use a **SessionOption** object to fulfill the requirements for a remote session configuration. @@ -173,12 +188,14 @@ The $skipCN check variable is used in the value of the **SessionOption** paramet Because the computer is identified by its IP address, the value of the **ComputerName** parameter does not match any of the common names in the certificate used for Secure Sockets Layer (SSL). As a result, the **SkipCNCheck** option is required. + ### Example 7 + ``` -PS C:\> $team = @{Team="IT"; Use="Testing"} -PS C:\> $TeamOption = New-PSSessionOption -ApplicationArguments $team -PS C:\> $s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption -PS C:\> Invoke-Command -Session $s {$PSSenderInfo.SpplicationArguments} +PS> $team = @{Team="IT"; Use="Testing"} +PS> $TeamOption = New-PSSessionOption -ApplicationArguments $team +PS> $s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption +PS> Invoke-Command -Session $s {$PSSenderInfo.SpplicationArguments} Name Value ---- ----- @@ -186,7 +203,7 @@ Team IT Use Testing PSVersionTable {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...} -PS C:\> Invoke-Command -Session $s {if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {.\logFiles.ps1} else {"Just testing."}} +PS> Invoke-Command -Session $s {if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {.\logFiles.ps1} else {"Just testing."}} Just testing. ``` @@ -210,9 +227,11 @@ The data appears in the **ApplicationArguments** property of the $PSSenderInfo a The fifth command shows how the data might be used. The command uses the Invoke-Command cmdlet to run a script only when the value of the Use property is not "Testing". When the value of Use is "Testing", the command returns "Just testing." + ## PARAMETERS ### -ApplicationArguments + Specifies a primitive dictionary that is sent to the remote session. Commands and scripts in the remote session, including startup scripts in the session configuration, can find this dictionary in the **ApplicationArguments** property of the **$PSSenderInfo** automatic variable. You can use this parameter to send data to the remote session. @@ -235,6 +254,7 @@ Accept wildcard characters: False ``` ### -CancelTimeout + Determines how long Windows PowerShell waits for a cancel operation (CTRL + C) to complete before terminating it. Enter a value in milliseconds. @@ -254,6 +274,7 @@ Accept wildcard characters: False ``` ### -Culture + Specifies the culture to use for the session. Enter a culture name in \-\ format, such as "ja-jP", a variable that contains a CultureInfo object, or a command that gets a CultureInfo object, such as "get-culture". @@ -272,6 +293,7 @@ Accept wildcard characters: False ``` ### -IdleTimeout + Determines how long the session stays open if the remote computer does not receive any communication from the local computer, including the heartbeat signal. When the interval expires, the session closes. @@ -310,6 +332,7 @@ Accept wildcard characters: False ``` ### -MaximumReceivedDataSizePerCommand + Specifies the maximum number of bytes that the local computer can receive from the remote computer in a single command. Enter a value in bytes. By default, there is no data size limit. @@ -329,6 +352,7 @@ Accept wildcard characters: False ``` ### -MaximumReceivedObjectSize + Specifies the maximum size of an object that the local computer can receive from the remote computer. This option is designed to protect the resources on the client computer. Enter a value in bytes. @@ -349,6 +373,7 @@ Accept wildcard characters: False ``` ### -MaximumRedirection + Determines how many times Windows PowerShell redirects a connection to an alternate Uniform Resource Identifier (URI) before the connection fails. The default value is 5. A value of 0 (zero) prevents all redirection. @@ -368,6 +393,7 @@ Accept wildcard characters: False ``` ### -NoCompression + Turns off packet compression in the session. Compression uses more processor cycles, but it makes transmission faster. @@ -384,6 +410,7 @@ Accept wildcard characters: False ``` ### -NoEncryption + Turns off data encryption. ```yaml @@ -399,6 +426,7 @@ Accept wildcard characters: False ``` ### -NoMachineProfile + Prevents loading the user's Windows user profile. As a result, the session might be created faster, but user-specific registry settings, items such as environment variables, and certificates are not available in the session. @@ -415,6 +443,7 @@ Accept wildcard characters: False ``` ### -OpenTimeout + Determines how long the client computer waits for the session connection to be established. When the interval expires, the command to establish the connection fails. Enter a value in milliseconds. @@ -435,6 +464,7 @@ Accept wildcard characters: False ``` ### -OperationTimeout + Determines the maximum time that any operation in the session can run. When the interval expires, the operation fails. Enter a value in milliseconds. @@ -455,6 +485,7 @@ Accept wildcard characters: False ``` ### -OutputBufferingMode + Determines how command output is managed in disconnected sessions when the output buffer becomes full. If the output buffering mode is not set in the session or in the session configuration, the default value is **Block**. @@ -486,6 +517,7 @@ Accept wildcard characters: False ``` ### -ProxyAccessType + Determines which mechanism is used to resolve the host name. Valid values are **IEConfig**, **WinHttpConfig**, **AutoDetect**, **NoProxyServer** and **None**. The default value is **None**. @@ -505,6 +537,7 @@ Accept wildcard characters: False ``` ### -ProxyAuthentication + Specifies the authentication method that is used for proxy resolution. Valid values are **Basic**, **Digest**, and **Negotiate**. The default value is **Negotiate**. @@ -524,6 +557,7 @@ Accept wildcard characters: False ``` ### -ProxyCredential + Specifies the credentials to use for proxy authentication. Enter a variable that contains a **PSCredential** object or a command that gets a **PSCredential** object, such as a Get-Credential command. If this option is not set, no credentials are specified. @@ -541,6 +575,7 @@ Accept wildcard characters: False ``` ### -SkipCACheck + Specifies that when connecting over HTTPS, the client does not validate that the server certificate is signed by a trusted certification authority (CA). Use this option only when the remote computer is trusted by using another mechanism, such as when the remote computer is part of a network that is physically secure and isolated or when the remote computer is listed as a trusted host in a WinRM configuration. @@ -558,6 +593,7 @@ Accept wildcard characters: False ``` ### -SkipCNCheck + Specifies that the certificate common name (CN) of the server does not need to match the hostname of the server. This option is used only in remote operations that use the HTTPS protocol. @@ -576,6 +612,7 @@ Accept wildcard characters: False ``` ### -SkipRevocationCheck + Does not validate the revocation status of the server certificate. ```yaml @@ -591,6 +628,7 @@ Accept wildcard characters: False ``` ### -UICulture + Specifies the UI culture to use for the session. Enter a culture name in \-\ format, such as "ja-jP", a variable that contains a **CultureInfo** object, or a command that gets a CultureInfo object, such as a Get-Culture command. @@ -610,6 +648,7 @@ Accept wildcard characters: False ``` ### -UseUTF16 + Encode the request in UTF16 format rather than UTF8 format. ```yaml @@ -625,6 +664,7 @@ Accept wildcard characters: False ``` ### -IncludePortInSPN + Includes the port number in the Service Principal Name (SPN) used for Kerberos authentication, for example, "HTTP/\:5985". This option allows a client that uses a non-default SPN to authenticate against a remote computer that uses Kerberos authentication. @@ -650,18 +690,24 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### 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](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. + +- 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 [Enter-PSSession](Enter-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/New-PSTransportOption.md b/reference/3.0/Microsoft.PowerShell.Core/New-PSTransportOption.md index a081808eecef..10ef20836981 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/New-PSTransportOption.md +++ b/reference/3.0/Microsoft.PowerShell.Core/New-PSTransportOption.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=210608 external help file: System.Management.Automation.dll-Help.xml title: New-PSTransportOption --- - # New-PSTransportOption + ## SYNOPSIS + Creates an object that contains advanced options for a session configuration. + ## SYNTAX ``` @@ -21,6 +23,7 @@ New-PSTransportOption [-MaxIdleTimeoutSec ] [-ProcessIdleTimeoutSec New-PSTransportOption +PS> New-PSTransportOption ProcessIdleTimeoutSec : MaxIdleTimeoutSec : MaxSessions : @@ -59,16 +64,18 @@ OutputBufferingMode : This command runs the **New-PSTransportOption** with no parameters. The output shows that the cmdlet generates a transport option object with null values for all properties. + ### Example 2 + ``` The first command uses the **New-PSTransportOption** cmdlet to create a transport options object, which it saves in the $t variable. The command uses the **MaxSessions** parameter to increase the maximum number of sessions to 40. -PS C:\> $t = New-PSTransportOption -MaxSessions 40 +PS> $t = New-PSTransportOption -MaxSessions 40 The second command uses the **Register-PSSessionConfiguration** cmdlet create the ITTasks session configuration. The command uses the TransportOption parameter to specify the transport options object in the $t variable. -PS C:\> Register-PSSessionConfiguration -Name ITTaska -TransportOption $t +PS> Register-PSSessionConfiguration -Name ITTaska -TransportOption $t The third command uses the Get-PSSessionConfiguration cmdlet to get the ITTasks session configurations and the Format-List cmdlet to display all of the properties of the session configuration object in a list. The output shows that the value of the **MaxShells** property of the session configuration is 40. -PS C:\> Get-PSSessionConfiguration -Name ITTasks | Format-List -Property * +PS> Get-PSSessionConfiguration -Name ITTasks | Format-List -Property * Architecture : 64 Filename : %windir%\system32\pwrshplugin.dll ResourceUri : http://schemas.microsoft.com/powershell/ITTasks @@ -100,19 +107,21 @@ Permission : ``` This example shows how to use a transport options object to set session configuration options + ### Example 3 + ``` The first command uses the **New-PSTransportOption** cmdlet to create a transport option object. The command uses the **IdleTimeoutSec** parameter to set the **IdleTimeoutSec** property value of the object to one hour (3600 seconds). The command saves the transport objects object in the $t variable. -PS C:\> $t = New-PSTransportOption -IdleTimeoutSec 3600 +PS> $t = New-PSTransportOption -IdleTimeoutSec 3600 The second command uses the Set-PSSessionConfiguration cmdlet to change the transport options of the ITTasks session configuration. The command uses the **TransportOption** parameter to specify the transport options object in the $t variable. -PS C:\> Set-PSSessionConfiguration -Name ITTasks -TransportOption $t +PS> Set-PSSessionConfiguration -Name ITTasks -TransportOption $t The third command uses the New-PSSession cmdlet to create the MyITTasks session on the local computer. The command uses the **ConfigurationName** property to specify the ITTasks session configuration. The command saves the session in the $s variable.Notice that the command does not use the **SessionOption** parameter of **New-PSSession** to set a custom idle timeout for the session. If it did, the idle timeout value set in the session option would take precedence over the idle timeout set in the session configuration. -PS C:\> $s = New-PSSession -Name MyITTasks -ConfigurationName ITTasks +PS> $s = New-PSSession -Name MyITTasks -ConfigurationName ITTasks The fourth command uses the Format-List cmdlet to display all properties of the session in the $s variable in a list. The output shows that the session has an idle timeout of one hour (360,000 milliseconds). -PS C:\> $s | Format-List -Property * +PS> $s | Format-List -Property * State : Opened IdleTimeout : 3600000 OutputBufferingMode : Block @@ -127,9 +136,11 @@ Runspace : System.Management.Automation.RemoteRunspace ``` This command shows the effect of setting a transport option in a session configuration on the sessions that use the session configuration. + ## PARAMETERS ### -IdleTimeoutSec + Determines how long each session stays open if the remote computer does not receive any communication from the local computer, including the heartbeat signal. When the interval expires, the session closes. @@ -160,6 +171,7 @@ Accept wildcard characters: False ``` ### -MaxConcurrentCommandsPerSession + Limits the number of commands that can run concurrently in each session to the specified value. The default value is 1000. @@ -178,6 +190,7 @@ Accept wildcard characters: False ``` ### -MaxConcurrentUsers + Limits the number of users who can run commands concurrently in each session to the specified value. The default value is 5. @@ -194,6 +207,7 @@ Accept wildcard characters: False ``` ### -MaxIdleTimeoutSec + Limits the idle timeout set for each session to the specified value. The default value is \[Int\]::MaxValue (~25 days). @@ -215,6 +229,7 @@ Accept wildcard characters: False ``` ### -MaxMemoryPerSessionMB + Limits the memory used by each session to the specified value. Enter a value in megabytes. The default value is 1024 megabytes (1 GB). @@ -234,6 +249,7 @@ Accept wildcard characters: False ``` ### -MaxProcessesPerSession + Limits the number of processes running in each session to the specified value. The default value is 15. @@ -252,6 +268,7 @@ Accept wildcard characters: False ``` ### -MaxSessions + Limits the number of sessions that use the session configuration. The default value is 25. @@ -270,6 +287,7 @@ Accept wildcard characters: False ``` ### -MaxSessionsPerUser + Limits the number of sessions that use the session configuration and run with the credentials of a given user to the specified value. The default value is 25. @@ -290,6 +308,7 @@ Accept wildcard characters: False ``` ### -OutputBufferingMode + Determines how command output is managed in disconnected sessions when the output buffer becomes full. The default value of the **OutputBufferingMode** property of sessions is **Block**. @@ -313,6 +332,7 @@ Accept wildcard characters: False ``` ### -ProcessIdleTimeoutSec + Limits the timeout for each host process to the specified value. The default value, 0, means that there is no timeout value for the process. @@ -332,17 +352,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 ### None + This cmdlet does not take input from the pipeline. + ## OUTPUTS ### Microsoft.PowerShell.Commands.WSManConfigurationOption ## NOTES -* 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. + +- 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 [about_Session_Configurations](About/about_Session_Configurations.md) From 5ab8971dea096b0cf64d229683a45edd892a83a2 Mon Sep 17 00:00:00 2001 From: Bobby Reed Date: Fri, 27 Apr 2018 12:27:13 -0700 Subject: [PATCH 5/6] Batch automation: Formatting fixes (#2372) * Batch automation: Formatting fixes * re-running automation to fix bad link replacement --- .../Microsoft.PowerShell.Core/Out-Default.md | 12 +- .../3.0/Microsoft.PowerShell.Core/Out-Host.md | 36 ++++-- .../3.0/Microsoft.PowerShell.Core/Out-Null.md | 25 +++- .../Microsoft.PowerShell.Core/Receive-Job.md | 66 ++++++++-- .../Receive-PSSession.md | 121 +++++++++++++----- .../Register-PSSessionConfiguration.md | 94 ++++++++++---- .../Microsoft.PowerShell.Core/Remove-Job.md | 71 +++++++--- .../Remove-Module.md | 39 +++++- .../Remove-PSSession.md | 64 +++++++-- .../Remove-PSSnapin.md | 36 +++++- .../Microsoft.PowerShell.Core/Resume-Job.md | 71 +++++++--- .../Microsoft.PowerShell.Core/Save-Help.md | 61 ++++++--- .../Microsoft.PowerShell.Core/Set-PSDebug.md | 36 +++++- .../Set-PSSessionConfiguration.md | 74 ++++++++--- .../Set-StrictMode.md | 58 ++++++--- .../Microsoft.PowerShell.Core/Start-Job.md | 70 ++++++++-- 16 files changed, 721 insertions(+), 213 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Out-Default.md b/reference/3.0/Microsoft.PowerShell.Core/Out-Default.md index a244ab732a16..b53fe4379ad7 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Out-Default.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Out-Default.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113362 external help file: System.Management.Automation.dll-Help.xml title: Out-Default --- - # Out-Default + ## SYNOPSIS + Sends the output to the default formatter and to the default output cmdlet. + ## SYNTAX ``` @@ -18,12 +20,15 @@ Out-Default [-InputObject ] [] ``` ## DESCRIPTION + The **Out-Default** cmdlet sends output to the default formatter and the default output cmdlet. This cmdlet has no effect on the formatting or output of Windows PowerShell commands. It is a placeholder that lets you write your own **Out-Default** function or cmdlet. + ## EXAMPLES ### 1: + ``` ``` @@ -31,6 +36,7 @@ It is a placeholder that lets you write your own **Out-Default** function or cmd ## PARAMETERS ### -InputObject + Accepts input to the cmdlet. ```yaml @@ -46,7 +52,9 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ## OUTPUTS diff --git a/reference/3.0/Microsoft.PowerShell.Core/Out-Host.md b/reference/3.0/Microsoft.PowerShell.Core/Out-Host.md index b54781ecdfdc..49ff5bff04dc 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Out-Host.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Out-Host.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113365 external help file: System.Management.Automation.dll-Help.xml title: Out-Host --- - # Out-Host + ## SYNOPSIS + Sends output to the command line. + ## SYNTAX ``` @@ -18,14 +20,17 @@ Out-Host [-Paging] [-InputObject ] [] ``` ## DESCRIPTION + The **Out-Host** cmdlet sends output to the Windows PowerShell host for display. The host displays the output at the command line. Because **Out-Host** is the default, you do not need to specify it unless you want to use its parameters to change the display. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Get-Process | Out-Host -Paging +PS> Get-Process | Out-Host -Paging ``` This command displays the processes on the system one page at a time. @@ -35,18 +40,22 @@ The **Paging** parameter displays one page of data at a time. The same command format is used for the Help function that is built into Windows PowerShell. That function gets data from the Get-Help cmdlet and then uses the **Paging** parameter of **Out-Host** to display the data one page at a time by using this command format: `Get-Help $Args\[0\] | Out-Host -Paging`. + ### Example 2 + ``` -PS C:\> $a = Get-History -PS C:\> Out-Host -InputObject $a +PS> $a = Get-History +PS> Out-Host -InputObject $a ``` These commands display the session history at the command line. The first command uses the Get-History cmdlet to get the session history, and then it stores the history in the $a variable. The second command uses **Out-Host** to display the content of the $a variable, and it uses the **InputObject** parameter to specify the variable to **Out-Host**. + ## PARAMETERS ### -InputObject + Specifies the objects that are written to the console. Enter a variable that contains the objects, or type a command or expression that gets the objects. @@ -63,6 +72,7 @@ Accept wildcard characters: False ``` ### -Paging + Displays one page of output at a time, and waits for user input before displaying the remaining pages, much like the traditional "more" command. By default, all of the output is displayed on a single page. The page size is determined by the characteristics of the host. @@ -80,22 +90,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 **Out-Host**. + ## OUTPUTS ### None + **Out-Host** does not generate any output. However, the host might display the objects that **Out-Host** sends to it. + ## NOTES -* The cmdlets that contain the Out verb (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 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. -* **Out-Host** sends data, but it does not emit any output objects. If you pipe the output of **Out-Host** to the Get-Member cmdlet, **Get-Member** reports that no objects have been specified. -* +- The cmdlets that contain the Out verb (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 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. +- **Out-Host** sends data, but it does not emit any output objects. If you pipe the output of **Out-Host** to the Get-Member cmdlet, **Get-Member** reports that no objects have been specified. + +- + ## RELATED LINKS [Clear-Host](Functions/Clear-Host.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Out-Null.md b/reference/3.0/Microsoft.PowerShell.Core/Out-Null.md index 2a7d2838ef67..48f3f734ba15 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Out-Null.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Out-Null.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113366 external help file: System.Management.Automation.dll-Help.xml title: Out-Null --- - # Out-Null + ## SYNOPSIS + Hides the output instead of sending it down the pipeline or displaying it. + ## SYNTAX ``` @@ -18,21 +20,26 @@ Out-Null [-InputObject ] [] ``` ## DESCRIPTION + The **Out-Null** cmdlet sends its output to NULL, in effect, removing it from the pipeline and preventing the output to be displayed at the screen. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Get-ChildItem | Out-Null +PS> Get-ChildItem | Out-Null ``` This command gets items in the current location/directory, but its output is not passed through the pipeline nor displayed at the command line. This is useful for hiding output that you do not need. + ## PARAMETERS ### -InputObject + Specifies the object to be sent to NULL (removed from pipeline). Enter a variable that contains the objects, or type a command or expression that gets the objects. @@ -49,22 +56,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 **Out-Null**. + ## OUTPUTS ### None + **Out-Null** does not generate any output. + ## NOTES -* The cmdlets that contain the Out verb (the Out cmdlets) do not have parameters for names or file paths. To send data to 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 more information, see the examples. -* +- The cmdlets that contain the Out verb (the Out cmdlets) do not have parameters for names or file paths. To send data to 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 more information, see the examples. + +- **Out-Null** does not return any output objects. If you pipe the output of **Out-Null** to the Get-Member cmdlet, **Get-Member** reports that no objects have been specified. + ## RELATED LINKS [Out-Default](Out-Default.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md b/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md index eb78f029b3f4..b64418827072 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,49 +7,58 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113372 external help file: System.Management.Automation.dll-Help.xml title: Receive-Job --- - # Receive-Job + ## SYNOPSIS + Gets the results of the Windows PowerShell background jobs in the current session. + ## SYNTAX ### Location (Default) + ``` Receive-Job [-Job] [[-Location] ] [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [] ``` ### ComputerName + ``` Receive-Job [-Job] [[-ComputerName] ] [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [] ``` ### Session + ``` Receive-Job [-Job] [[-Session] ] [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [] ``` ### NameParameterSet + ``` Receive-Job [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [-Name] [] ``` ### InstanceIdParameterSet + ``` Receive-Job [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [-InstanceId] [] ``` ### SessionIdParameterSet + ``` Receive-Job [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [-Id] [] ``` ## DESCRIPTION + The **Receive-Job** cmdlet gets the results of Windows PowerShell background jobs, such as those started by using the Start-Job cmdlet or the **AsJob** parameter of any cmdlet. You can get the results of all jobs or identify jobs by their name, ID, instance ID, computer name, location, or session, or by submitting a job object. @@ -68,12 +77,14 @@ To delete the job results, run the **Receive-Job** command again (without the ** Beginning in Windows PowerShell 3.0, **Receive-Job** also gets the results of custom job types, such as workflow jobs and instances of scheduled jobs. To enable **Receive-Job** to get the results a custom job type, import the module that supports the custom job type into the session before running a **Receive-Job** command, either by using the Import-Module cmdlet or by using or getting a cmdlet in the module. For information about a particular custom job type, see the documentation of the custom job type feature. + ## EXAMPLES ### Example 1 + ``` -PS C:\> $job = Start-Job -ScriptBlock {Get-Process} -PS C:\> Receive-Job -Job $job +PS> $job = Start-Job -ScriptBlock {Get-Process} +PS> Receive-Job -Job $job ``` These commands use the **Job** parameter of **Receive-Job** to get the results of a particular job. @@ -83,24 +94,28 @@ The command uses the assignment operator (=) to save the resulting job object in The second command uses the **Receive-Job** cmdlet to get the results of the job. It uses the **Job** parameter to specify the job. + ### Example 2 + ``` -PS C:\> $job = Start-Job -ScriptBlock {Get-Process} -PS C:\> $job | Receive-Job +PS> $job = Start-Job -ScriptBlock {Get-Process} +PS> $job | Receive-Job ``` This example is the same as Example 2, except that the command uses a pipeline operator (|) to send the job object to **Receive-Job**. As a result, the command does not need a **Job** parameter to specify the job. + ### Example 3 + ``` The first command uses the Invoke-Command cmdlet to start a background job that runs a Get-Service command on three remote computers. The command uses the **AsJob** parameter to run the command as a background job. The command saves the resulting job object in the $j variable.When you use the **AsJob** parameter of **Invoke-Command** to start a job, the job object is created on the local computer, even though the job runs on the remote computers. As a result, you use local commands to manage the job.Also, when you use **AsJob**, Windows PowerShell returns one job object that contains a child job for each job that was started. In this case, the job object contains three child jobs, one for each job on each remote computer. -PS C:\> +PS> -PS C:\> $j = Invoke-Command -ComputerName Server01, Server02, Server03 -ScriptBlock {Get-Service} -AsJob +PS> $j = Invoke-Command -ComputerName Server01, Server02, Server03 -ScriptBlock {Get-Service} -AsJob The second command uses the dot method to display the value of the **ChildJobs** property of the job object in $j. The display shows that the command created three child jobs, one for the job on each remote computer. -PS C:\> $j.ChildJobs +PS> $j.ChildJobs Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- @@ -109,7 +124,7 @@ Id Name State HasMoreData Location Command 4 Job4 Completed True Server03 Get-Service The third command uses the **Receive-Job** cmdlet to get the results of the Job3 child job that ran on the Server02 computer. It uses the Name parameter to specify the name of the child job and the Keep parameter to save the job results even after they are received. -PS C:\> Receive-Job -Name Job3 -Keep +PS> Receive-Job -Name Job3 -Keep Status Name DisplayName PSComputerName ------ ----------- ----------- -------------- @@ -120,16 +135,18 @@ Running AppMgmt Application Management Server02 ``` These commands get the results of one of several background jobs run on remote computers. + ### Example 4 + ``` The first command uses the New-PSSession cmdlet to create three user-managed sessions ("PSSessions), one on each of the servers specified in the command. It saves the sessions in the $s variable. -PS C:\> $s = new-pssession -computername Server01, Server02, Server03 +PS> $s = new-pssession -computername Server01, Server02, Server03 The second command uses the Invoke-Command cmdlet to run a Start-Job command in each of the PSSessions in the $s variable. The job runs a Get-Eventlog command that gets the events in the System log. The command saves the results in the $j variable.Because the command used Invoke-Command to run the Start-Job command, the command actually started three independent jobs on each of the three computers. As a result, the command returned three job objects representing three jobs run locally on three different computers. -PS C:\> $j = invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog -logname system}} +PS> $j = invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog -logname system}} The third command displays the three job objects in $j. -PS C:\> $j +PS> $j Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- @@ -139,13 +156,15 @@ Id Name State HasMoreData Location Command The fourth command uses Invoke-Command to run a **Receive-Job** command in each of the sessions in $s and save the results in the $Results variable.Because $j is a local variable, the script block uses the **Using** scope modifier to identify the $j variable. For more information about the **Using** scope modifier, see about_Remote_Variables (http://go.microsoft.com/fwlink/?LinkID=252653). -PS C:\> $results = Invoke-Command -Session $s -ScriptBlock {Receive-Job -Job $Using:j} +PS> $results = Invoke-Command -Session $s -ScriptBlock {Receive-Job -Job $Using:j} ``` This example shows how to get the results of background jobs run on three remote computers. + ## PARAMETERS ### -ComputerName + Gets the results of jobs that were run on the specified computers. Enter the computer names. Wildcards are supported. @@ -168,6 +187,7 @@ Accept wildcard characters: True ``` ### -Id + Gets the results of jobs with the specified IDs. The default is all jobs in the current session. @@ -189,6 +209,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Gets the results of jobs with the specified instance IDs. The default is all jobs in the current session. @@ -208,6 +229,7 @@ Accept wildcard characters: False ``` ### -Job + Specifies the job for which results are being retrieved. This parameter is required in a **Receive-Job** command. Enter a variable that contains the job or a command that gets the job. @@ -226,6 +248,7 @@ Accept wildcard characters: False ``` ### -Keep + Saves the job results in the system, even after you have received them. By default, the job results are deleted when they are retrieved. @@ -244,6 +267,7 @@ Accept wildcard characters: False ``` ### -Location + Gets only the results of jobs with the specified location. The default is all jobs in the current session. @@ -260,6 +284,7 @@ Accept wildcard characters: False ``` ### -Name + Gets the results of jobs with the specified friendly name. Wildcards are supported. The default is all jobs in the current session. @@ -277,6 +302,7 @@ Accept wildcard characters: True ``` ### -NoRecurse + Gets results only from the specified job. By default, **Receive-Job** also gets the results of all child jobs of the specified job. @@ -293,6 +319,7 @@ Accept wildcard characters: False ``` ### -Session + Gets the results of jobs that were run in the specified Windows Powershell session (PSSession). Enter a variable that contains the PSSession or a command that gets the PSSession, such as a Get-PSSession command. The default is all jobs in the current session. @@ -310,6 +337,7 @@ Accept wildcard characters: False ``` ### -Wait + Suppresses the command prompt until all job results are received. By default, **Receive-Job** immediately returns the available results. @@ -331,6 +359,7 @@ Accept wildcard characters: False ``` ### -AutoRemoveJob + Deletes the job after returning the job results. If the job has more results, the job is still deleted, but **Receive-Job** displays a message. @@ -354,6 +383,7 @@ Accept wildcard characters: False ``` ### -WriteEvents + Reports changes in the job state while waiting for the job to complete. This parameter is valid only when the **Wait** parameter is used in the command and the **Keep** parameter is omitted. @@ -373,6 +403,7 @@ Accept wildcard characters: False ``` ### -WriteJobInResults + Returns the job object followed by the results. This parameter is valid only when the **Wait** parameter is used in the command and the **Keep** parameter is omitted. @@ -392,6 +423,7 @@ Accept wildcard characters: False ``` ### -Force + Continues waiting if jobs are in the **Suspended** or **Disconnected** state. By default, the **Wait** parameter of **Receive-Job** returns (terminates the wait) when jobs are in one of the following states: Completed, Failed, Stopped, Suspended, or Disconnected. @@ -412,15 +444,21 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.Job + You can pipe job objects to **Receive-Job**. + ## OUTPUTS ### PSObject + **Receive-Job** returns the results of the commands in the job. + ## NOTES ## 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 4aff204fb219..465c7fef28ad 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Receive-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Receive-PSSession.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,25 +7,30 @@ online version: http://go.microsoft.com/fwlink/?LinkID=217037 external help file: System.Management.Automation.dll-Help.xml title: Receive-PSSession --- - # Receive-PSSession + ## SYNOPSIS + Gets results of commands in disconnected sessions + ## SYNTAX ### Session (Default) + ``` Receive-PSSession [-Session] [-OutTarget ] [-JobName ] [-WhatIf] [-Confirm] [] ``` ### Id + ``` Receive-PSSession [-Id] [-OutTarget ] [-JobName ] [-WhatIf] [-Confirm] [] ``` ### ComputerSessionName + ``` Receive-PSSession [-ComputerName] [-ApplicationName ] [-ConfigurationName ] [-Name] [-OutTarget ] [-JobName ] [-Credential ] @@ -34,6 +39,7 @@ Receive-PSSession [-ComputerName] [-ApplicationName ] [-Configu ``` ### ComputerInstanceId + ``` Receive-PSSession [-ComputerName] [-ApplicationName ] [-ConfigurationName ] -InstanceId [-OutTarget ] [-JobName ] [-Credential ] @@ -42,6 +48,7 @@ Receive-PSSession [-ComputerName] [-ApplicationName ] [-Configu ``` ### ConnectionUriSessionName + ``` Receive-PSSession [-ConfigurationName ] [-ConnectionUri] [-AllowRedirection] [-Name] [-OutTarget ] [-JobName ] [-Credential ] @@ -50,6 +57,7 @@ Receive-PSSession [-ConfigurationName ] [-ConnectionUri] [-AllowRe ``` ### ConnectionUriInstanceId + ``` Receive-PSSession [-ConfigurationName ] [-ConnectionUri] [-AllowRedirection] -InstanceId [-OutTarget ] [-JobName ] [-Credential ] @@ -58,18 +66,21 @@ Receive-PSSession [-ConfigurationName ] [-ConnectionUri] [-AllowRe ``` ### InstanceId + ``` Receive-PSSession -InstanceId [-OutTarget ] [-JobName ] [-WhatIf] [-Confirm] [] ``` ### SessionName + ``` Receive-PSSession [-Name] [-OutTarget ] [-JobName ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Receive-PSSession** cmdlet gets the results of commands running in Windows PowerShell sessions ("PSSession") that were disconnected. If the session is currently connected, **Receive-PSSession** gets the results of commands that were running when the session was disconnected. If the session is still disconnected, **Receive-PSSession** connects to the session, resumes any commands that were suspended, and gets the results of commands running in the session. @@ -84,27 +95,33 @@ If you use the **Receive-PSSession** cmdlet to connect to a session in which no For more information about the Disconnected Sessions feature, see about_Remote_Disconnected_Sessions. This cmdlet is introduced in Windows PowerShell 3.0. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Receive-PSSession -ComputerName Server01 -Name ITTask +PS> Receive-PSSession -ComputerName Server01 -Name ITTask ``` This command uses the **Receive-PSSession** cmdlet to connect to the ITTask session on the Server01 computer and get the results of commands that were running in the session. Because the command does not use the **OutTarget** parameter, the results appear at the command line. + ### Example 2 + ``` -PS C:\> Get-PSSession -ComputerName Server01, Server02 | Receive-PSSession +PS> Get-PSSession -ComputerName Server01, Server02 | Receive-PSSession ``` This command gets the results of all commands running in all disconnected sessions on the Server01 and Server02 computers. If any session was not disconnected or is not running commands, **Receive-PSSession** does not connect to the session and does not return any output or errors. + ### Example 3 + ``` -PS C:\> Receive-PSSession -ComputerName Server01 -Name ITTask -OutTarget Job -JobName ITTaskJob01 -Credential Domain01\Admin01 +PS> Receive-PSSession -ComputerName Server01 -Name ITTask -OutTarget Job -JobName ITTaskJob01 -Credential Domain01\Admin01 Id Name State HasMoreData Location -- ---- ----- ----------- -------- 16 ITTaskJob01 Running True Server01 @@ -119,18 +136,20 @@ The command uses the **Credential** parameter to run the **Receive-PSSession** c The output shows that **Receive-PSSession** returned the results as a job in the current session. To get the job results, use a Receive-Job command + ### Example 4 + ``` The first command uses the New-PSSession cmdlet to create a session on the Server01 computer. The command saves the session in the $s variable.The second command gets the session in the $s variable. Notice that the **State** is **Opened** and the **Availability** is **Available**. These values indicate that you are connected to the session and can run commands in the session. -PS C:\> $s = New-PSSession -ComputerName Server01 -Name AD -ConfigurationName ADEndpoint -PS C:\> $s +PS> $s = New-PSSession -ComputerName Server01 -Name AD -ConfigurationName ADEndpoint +PS> $s Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 8 AD Server01 Opened ADEndpoint Available The third command uses the Invoke-Command cmdlet to run a script in the session in the $s variable.The script begins to run and return data, but a network outage occurs that interrupts the session. The user has to exit the session and restart the local computer. -PS C:\> Invoke-Command -Session $s -FilePath \\Server12\Scripts\SharedScripts\New-ADResolve.ps1 +PS> Invoke-Command -Session $s -FilePath \\Server12\Scripts\SharedScripts\New-ADResolve.ps1 Running "New-ADResolve.ps1" ….exit # Network outage @@ -138,7 +157,7 @@ PS C:\> Invoke-Command -Session $s -FilePath \\Server12\Scripts\SharedScripts\Ne # Network access is not re-established within 4 minutes When the computer restarts, the user starts Windows PowerShell and runs a Get-PSSession command to get sessions on the Server01 computer. The output shows that the AD session still exists on the Server01 computer. The **State** indicates that it is disconnected and the **Availability** value, **None**, indicates that it is not connected to any client sessions. -PS C:\> Get-PSSession -ComputerName Server01 +PS> Get-PSSession -ComputerName Server01 Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ @@ -147,13 +166,13 @@ PS C:\> Get-PSSession -ComputerName Server01 The fifth command uses the **Receive-PSSession** cmdlet to reconnect to the AD session and get the results of the script that ran in the session. The command uses the **OutTarget** parameter to request the results in a job named "ADJob".The command returns a job object. The output indicates that the script is still running. -PS C:\> Receive-PSSession -ComputerName Server01 -Name AD -OutTarget Job -JobName AD +PS> Receive-PSSession -ComputerName Server01 -Name AD -OutTarget Job -JobName AD Job Id Name State HasMoreData Location -- ---- ----- ----------- -------- 16 ADJob Running True Server01 The sixth command uses the Get-PSSession cmdlet to check the job state. The output confirms that, in addition to resuming script execution and getting the script results, the **Receive-PSSession** cmdlet reconnected to the AD session, which is now open and available for commands. -PS C:\> Get-PSSession -ComputerName Server01 +PS> Get-PSSession -ComputerName Server01 Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 Backup Server01 Disconnected Microsoft.PowerShell Busy @@ -162,16 +181,18 @@ Id Name ComputerName State ConfigurationName Availability This example uses the **Receive-PSSession** cmdlet to get the results of a job after a network outage disrupts a session connection. Windows PowerShell automatically attempts to reconnect the session once each second for the next four minutes and abandons the effort only if all attempts in the four-minute interval fail. + ### Example 5 + ``` The first command uses the Invoke-Command cmdlet to run a script on the three remote computers. Because the scripts gathers and summarize data from multiple databases, it often takes the script an extended time to complete. The command uses the **InDisconnectedSession** parameter, which starts the scripts and then immediately disconnects the sessions.The command uses the **SessionOption** parameter to extend the **IdleTimeout** value of the disconnected session. Disconnected sessions are considered to be idle from the moment they are disconnected, so it's important to set the idle timeout for a long enough period that the commands can complete and you can reconnect to the session, if necessary. You can set the IdleTimeout only when you create the PSSession and change it only when you disconnect from it. You cannot change the **IdleTimeout** value when connecting to a PSSession or receiving its results.After running the command, the user exits Windows PowerShell and closes the computer . -PS C:\> Invoke-Command -InDisconnectedSession -ComputerName Server01, Server02, Server30 -FilePath \\Server12\Scripts\SharedScripts\Get-BugStatus.ps1 -Name BugStatus -SessionOption @{IdleTimeout = 86400000} -ConfigurationName ITTasks# Exit +PS> Invoke-Command -InDisconnectedSession -ComputerName Server01, Server02, Server30 -FilePath \\Server12\Scripts\SharedScripts\Get-BugStatus.ps1 -Name BugStatus -SessionOption @{IdleTimeout = 86400000} -ConfigurationName ITTasks# Exit # Start Windows PowerShell on a different computer. On the next day, the user resumes Windows and starts Windows PowerShell. The second command uses the Get-PSSession cmdlet to get the sessions in which the scripts were running. The command identifies the sessions by the computer name, session name, and the name of the session configuration and saves the sessions in the $s variable.The third command displays the value of the $s variable. The output shows that the sessions are disconnected, but not busy, as expected. -PS C:\> $s = Get-PSSession -ComputerName Server01, Server02, Server30 -Name BugStatus - PS C:\> $s +PS> $s = Get-PSSession -ComputerName Server01, Server02, Server30 -Name BugStatus + PS> $s Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 ITTask Server01 Disconnected ITTasks None @@ -180,8 +201,8 @@ Id Name ComputerName State ConfigurationName Availability The fourth command uses the **Receive-PSSession** cmdlet to connect to the sessions in the $s variable and get their results. The command saves the results in the $Results variable..Another display of the $s variable shows that the sessions are connected and available for commands. -PS C:\> $Results = Receive-PSSession -Session $s -PS C:\> $s +PS> $Results = Receive-PSSession -Session $s +PS> $s Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 ITTask Server01 Opened ITTasks Available @@ -190,7 +211,7 @@ PS C:\> $s The fifth command displays the script results in the $Results variable. If any of the results are unexpected, the user can run commands in the sessions to investigate. -PS C:\> $Results +PS> $Results Bug Report - Domain 01 ---------------------- ComputerName BugCount LastUpdated @@ -201,49 +222,52 @@ Server01 121 Friday, December 30, 2011 5:03:34 PMâ This example uses the **Receive-PSSession** cmdlet to reconnect to sessions that were intentionally disconnected and get the results of jobs that were running in the sessions. ### Example 6 + ``` The first command uses the New-PSSession cmdlet to create the Test session on the Server01 computer. The command saves the session in the $s variable. -PS C:\> $s = New-PSSession -ComputerName Server01 -Name Test +PS> $s = New-PSSession -ComputerName Server01 -Name Test The second command uses the Invoke-Command cmdlet to run a command in the session in the $s variable. The command uses the **AsJob** parameter to run the command as a job and to create the job object in the current session. The command returns a job object, which is saved in the $j variable.The third command displays the job object in the $j variable. -PS C:\> $j = Invoke-Command -Session $s { 1..1500 | Foreach-Object {"Return $_"; sleep 30}} -AsJob +PS> $j = Invoke-Command -Session $s { 1..1500 | Foreach-Object {"Return $_"; sleep 30}} -AsJob -PS C:\> $j +PS> $j Id Name State HasMoreData Location -- ---- ----- ----------- -------- 16 Job1 Running True Server01 The fourth command disconnects the session in the $s variable. -PS C:\> $s | Disconnect-PSSession +PS> $s | Disconnect-PSSession Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 Test Server01 Disconnected Microsoft.PowerShell None The fifth command shows the effect of disconnecting on the job object in the $j variable. The job state is now Disconnected. -PS C:\> $j +PS> $j Id Name State HasMoreData Location -- ---- ----- ----------- -------- 16 Job1 Disconnected True Server01 The sixth command runs a Receive-Job command on the job in the $j variable. The output shows that the job began to return output before the session (and the job) were disconnected. -PS C:\> Receive-Job $j -Keep +PS> Receive-Job $j -Keep Return 1Return 2 The seventh command is run in the same client session. The command uses the Connect-PSSession cmdlet to reconnect to the Test session on the Server01 computer and saves the session in the $s2 variable. -PS C:\> $s2 = Connect-PSSession -ComputerName Server01 -Name Test +PS> $s2 = Connect-PSSession -ComputerName Server01 -Name Test The eighth command uses the **Receive-PSSession** cmdlet to get the results of the job that was running in the session. Because the command is run in the same session, **Receive-PSSession** returns the results as a job by default and reuses the same job object. The command saves the job in the $j2 variable.The ninth command uses the **Receive-Job** cmdlet to get the results of the job in the $j variable. -PS C:\> $j2 = Receive-PSSession -ComputerName Server01 -Name Test +PS> $j2 = Receive-PSSession -ComputerName Server01 -Name Test -PS C:\> Receive-Job $j +PS> Receive-Job $j Return 3 Return 4… ``` This example shows what happens to a job that is running in a disconnected session. + ## PARAMETERS ### -Authentication + Specifies the mechanism that is used to authenticate the user's credentials in the command to reconnect to the disconnected session. Valid values are **Default**, **Basic**, **Credssp**, **Digest**, **Kerberos**, **Negotiate**, and **NegotiateWithImplicitCredential**. The default value is **Default**. @@ -267,6 +291,7 @@ Accept wildcard characters: False ``` ### -CertificateThumbprint + Specifies the digital public key certificate (X509) of a user account that has permission to connect to the disconnected session. Enter the certificate thumbprint of the certificate. @@ -288,6 +313,7 @@ Accept wildcard characters: False ``` ### -ComputerName + Specifies the computer on which the disconnected session is stored. Sessions are stored on the computer that is at the "server-side" or receiving end of a connection. The default is the local computer. @@ -309,6 +335,7 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to connect to the disconnected session. The default is the current user. @@ -329,6 +356,7 @@ Accept wildcard characters: False ``` ### -Id + Specifies the ID of the disconnected session. The ID parameter works only when the disconnected session was previously connected to the current session. @@ -347,6 +375,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Specifies the instance ID of the disconnected session. The instance ID is a GUID that uniquely identifies a PSSession on a local or remote computer. @@ -378,6 +407,7 @@ Accept wildcard characters: False ``` ### -JobName + Specifies a friendly name for the job that **Receive-PSSession** returns. **Receive-PSSession** returns a job when the value of the **OutTarget** parameter is **Job** or the job that is running in the disconnected session was started in the current session. @@ -402,6 +432,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the friendly name of the disconnected session. ```yaml @@ -429,6 +460,7 @@ Accept wildcard characters: False ``` ### -OutTarget + Determines how the session results are returned. Valid values are: @@ -456,6 +488,7 @@ Accept wildcard characters: False ``` ### -Port + Specifies the network port on the remote computer that is used to reconnect to the session. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). @@ -484,6 +517,7 @@ Accept wildcard characters: False ``` ### -Session + Specifies the disconnected session. Enter a variable that contains the PSSession or a command that creates or gets the PSSession, such as a Get-PSSession command. @@ -500,6 +534,7 @@ Accept wildcard characters: False ``` ### -UseSSL + Uses the Secure Sockets Layer (SSL) protocol to connect to the disconnected session. By default, SSL is not used. @@ -521,6 +556,7 @@ Accept wildcard characters: False ``` ### -AllowRedirection + Allows redirection of this connection to an alternate Uniform Resource Identifier (URI). When you use the **ConnectionURI** parameter, the remote destination can return an instruction to redirect to a different URI. @@ -543,6 +579,7 @@ Accept wildcard characters: False ``` ### -ApplicationName + Connects only to sessions that use the specified application. Enter the application name segment of the connection URI. @@ -565,6 +602,7 @@ Accept wildcard characters: False ``` ### -ConfigurationName + Connects only to sessions that use the specified session configuration. Enter a configuration name or the fully qualified resource URI for a session configuration. @@ -589,6 +627,7 @@ Accept wildcard characters: False ``` ### -ConnectionUri + Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint that is used to reconnect to the disconnected session. The URI must be fully qualified. @@ -621,6 +660,7 @@ Accept wildcard characters: False ``` ### -SessionOption + Sets advanced options for the session. Enter a **SessionOption** object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. @@ -647,6 +687,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -662,6 +703,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -678,35 +720,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). + ## INPUTS ### System.Management.Automation.Runspaces.PSSession + You can pipe session objects, such as those returned by the Get-PSSession cmdlet to Receive-PSSession. + ### System.Int32 + You can pipe session IDs to Receive-PSSession. + ### System.Guid + You can pipe the instance IDs of sessions to Receive-PSSession. + ### System.String + You can pipe session names to Receive-PSSession. + ## OUTPUTS ### System.Management.Automation.Job or PSObject + **Receive-PSSession** gets the results of commands that ran in the disconnected session, if any. If the value or default value of the **OutTarget** parameter is **Job**, **Receive-PSSession** returns a job object. Otherwise, it returns objects that represent that command results. + ## NOTES -* **Receive-PSSession** gets results only from sessions that were disconnected. Only sessions that are connected to (terminate at) computers running Windows PowerShell 3.0 or later can be disconnected and reconnected. -* If the commands that were running in the disconnected session did not generate results or if the results were already returned to another session, **Receive-PSSession** does not generate any output. -* The output buffering mode of a session determines how commands in the session manage output when the session is disconnected. When the value of the **OutputBufferingMode** option of the session is **Drop** and the output buffer is full, the command begins to delete output. Receive-PSSession cannot recover this output. For more information about the output buffering mode option, see the help topics for the New-PSSessionOption and New-PSTransportOption cmdlets. -* You cannot change the idle timeout value of a PSSession when you connect to the PSSession or receive results. The **SessionOption** parameter of **Receive-PSSession** takes a **SessionOption** object that has an **IdleTimeout** value. However, the **IdleTimeout** value of the **SessionOption** object and the **IdleTimeout** value of the **$PSSessionOption** variable are ignored when connecting to a PSSession or receiving results. + +- **Receive-PSSession** gets results only from sessions that were disconnected. Only sessions that are connected to (terminate at) computers running Windows PowerShell 3.0 or later can be disconnected and reconnected. +- If the commands that were running in the disconnected session did not generate results or if the results were already returned to another session, **Receive-PSSession** does not generate any output. +- The output buffering mode of a session determines how commands in the session manage output when the session is disconnected. When the value of the **OutputBufferingMode** option of the session is **Drop** and the output buffer is full, the command begins to delete output. Receive-PSSession cannot recover this output. For more information about the output buffering mode option, see the help topics for the New-PSSessionOption and New-PSTransportOption cmdlets. +- You cannot change the idle timeout value of a PSSession when you connect to the PSSession or receive results. The **SessionOption** parameter of **Receive-PSSession** takes a **SessionOption** object that has an **IdleTimeout** value. However, the **IdleTimeout** value of the **SessionOption** object and the **IdleTimeout** value of the **$PSSessionOption** variable are ignored when connecting to a PSSession or receiving results. You can set and change the idle timeout of a PSSession when you create the PSSession (by using the New-PSSession or Invoke-Command cmdlets) and when you disconnect from the PSSession. The **IdleTimeout** property of a PSSession is critical to disconnected sessions, because it determines how long a disconnected session is maintained on the remote computer. Disconnected sessions are considered to be idle from the moment that they are disconnected, even if commands are running in the disconnected session. -* If you start a start a job in a remote session by using the **AsJob** parameter of the Invoke-Command cmdlet, the job object is created in the current session, even though the job runs in the remote session. If you disconnect the remote session, the job object in the current session is now disconnected from the job. The job object still contains any results that were returned to it, but it does not receive new results from the job in the disconnected session. +- If you start a start a job in a remote session by using the **AsJob** parameter of the Invoke-Command cmdlet, the job object is created in the current session, even though the job runs in the remote session. If you disconnect the remote session, the job object in the current session is now disconnected from the job. The job object still contains any results that were returned to it, but it does not receive new results from the job in the disconnected session. If a different client connects to the session that contains the running job, the results that were delivered to the original job object in the original session are not available in the newly connected session. Only results that were not delivered to the original job object are available in the reconnected session. @@ -721,8 +776,8 @@ In this case, the job object is created in the remote session. You cannot use the **Receive-PSSession** cmdlet to get the job results. Instead, use the **Connect-PSSession** cmdlet to connect to the session and then use the **Invoke-Command** cmdlet to run a Receive-Job command in the session. -* When a session that contains a running job is disconnected and then reconnected, the original job object is reused only if the job is disconnected and reconnected to the same session, and the command to reconnect does not specify a new job name. If the session is reconnected to a different client session or a new job name is specified, Windows PowerShell creates a new job object for the new session. -* When you disconnect a PSSession, the session state is **Disconnected** and the availability is **None**. +- When a session that contains a running job is disconnected and then reconnected, the original job object is reused only if the job is disconnected and reconnected to the same session, and the command to reconnect does not specify a new job name. If the session is reconnected to a different client session or a new job name is specified, Windows PowerShell creates a new job object for the new session. +- When you disconnect a PSSession, the session state is **Disconnected** and the availability is **None**. The value of the **State** property is relative to the current session. Therefore, a value of **Disconnected** means that the PSSession is not connected to the current session. diff --git a/reference/3.0/Microsoft.PowerShell.Core/Register-PSSessionConfiguration.md b/reference/3.0/Microsoft.PowerShell.Core/Register-PSSessionConfiguration.md index 2b1618e0acb0..5c9781c27116 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Register-PSSessionConfiguration.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Register-PSSessionConfiguration.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=144306 external help file: System.Management.Automation.dll-Help.xml title: Register-PSSessionConfiguration --- - # Register-PSSessionConfiguration + ## SYNOPSIS + Creates and registers a new session configuration. + ## SYNTAX ### NameParameterSet (Default) + ``` Register-PSSessionConfiguration [-ProcessorArchitecture ] [-SessionType ] [-Name] [-ApplicationBase ] [-RunAsCredential ] @@ -26,6 +29,7 @@ Register-PSSessionConfiguration [-ProcessorArchitecture ] [-SessionType ``` ### AssemblyNameParameterSet + ``` Register-PSSessionConfiguration [-ProcessorArchitecture ] [-Name] [-AssemblyName] [-ApplicationBase ] [-ConfigurationTypeName] [-RunAsCredential ] @@ -38,6 +42,7 @@ Register-PSSessionConfiguration [-ProcessorArchitecture ] [-Name] ] [-Name] [-RunAsCredential ] [-ThreadApartmentState ] [-ThreadOptions ] @@ -48,6 +53,7 @@ Register-PSSessionConfiguration [-ProcessorArchitecture ] [-Name] Register-PSSessionConfiguration -Name NewShell -ApplicationBase c:\MyShells\ -AssemblyName MyShell.dll -ConfigurationTypeName MyClass +PS> Register-PSSessionConfiguration -Name NewShell -ApplicationBase c:\MyShells\ -AssemblyName MyShell.dll -ConfigurationTypeName MyClass ``` This command registers the NewShell session configuration. @@ -75,9 +83,11 @@ It uses the **AssemblyName** and **ApplicationBase** parameters to specify the l It also uses the **ConfigurationTypeName** parameter to specify a new class that further configures the session. To use this configuration, type "new-pssession -configurationname newshell". + ### Example 2 + ``` -PS C:\> Register-PSSessionConfiguration -name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 +PS> Register-PSSessionConfiguration -name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 ``` This command registers the MaintenanceShell configuration on the local computer. @@ -86,10 +96,12 @@ The command uses the **StartupScript** parameter to specify the Maintenance.ps1 When a user uses a New-PSSession command and selects the MaintenanceShell configuration, the Maintenance.ps1 script runs in the new session. The script can configure the session, including importing modules, adding Windows PowerShell snap-ins, and setting the execution policy for the session. If the script generates any errors, including non-terminating errors, the **New-PSSession** command fails. + ### Example 3 + ``` -PS C:\> $sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)" -PS C:\> Register-PSSessionConfiguration -name AdminShell -SecurityDescriptorSDDL $sddl -MaximumReceivedObjectSizeMB 20 -StartupScript C:\scripts\AdminShell.ps1 +PS> $sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)" +PS> Register-PSSessionConfiguration -name AdminShell -SecurityDescriptorSDDL $sddl -MaximumReceivedObjectSizeMB 20 -StartupScript C:\scripts\AdminShell.ps1 ``` This example registers the AdminShell session configuration. @@ -102,13 +114,15 @@ It also uses the **StartupScript** parameter to specify a script that configures As an alternative to using the **SecurityDescriptorSDDL** parameter, you can use the **ShowSecurityDescriptorUI** parameter, which displays a property sheet that you can use to set permissions for the session configuration. When you click "OK" in the property sheet, the tool generates an SDDL for the session configuration. + ### Example 4 + ``` The first command uses the **Register-PSSessionConfiguration** cmdlet to register the MaintenanceShell configuration. It saves the object that the cmdlet returns in the $s variable. -PS C:\> $s = Register-PSSessionConfiguration -name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 +PS> $s = Register-PSSessionConfiguration -name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 The second command displays the contents of the $s variable. -PS C:\> $s +PS> $s WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin Name Type Keys @@ -117,13 +131,13 @@ MaintenanceShell Container {Name=MaintenanceShell} The third command uses the **GetType** method and its **FullName** property to display the type name of the object that **Register-PSSessionConfiguration** returns. -PS C:\> $s.GetType().FullName +PS> $s.GetType().FullName TypeName: Microsoft.WSMan.Management.WSManConfigContainerElement The fourth command uses the Format-List cmdlet to display all the properties of the object that Register-PSSessionConfiguration returns in a list. The **PSPath** property shows that the object is stored in a directory of the WSMan: drive. -PS C:\> $s | Format-List -Property * +PS> $s | Format-List -Property * PSPath : Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell PSParentPath : Microsoft.WSMan.Management\WSMan::localhost\Plugin @@ -137,7 +151,7 @@ TypeNameOfElement : Container The fifth command uses the Get-ChildItem cmdlet to display the items in the WSMan:\LocalHost\PlugIn path. These include the new MaintenanceShell configuration and the two default configurations that come with Windows PowerShell. -PS C:\> dir WSMan:\LocalHost\Plugin +PS> dir WSMan:\LocalHost\Plugin Name Type Keys ---- ---- ---- @@ -148,9 +162,11 @@ microsoft.powershell32 Container {Name=microsoft.powershell32} This example shows that a Register-PSSessionConfiguration command returns a WSManConfigContainerElement. It also shows how to find the container elements in the WSMan: drive. + ### Example 5 + ``` -PS C:\> Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1 +PS> Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1 # Add-Profile.ps1 . c:\users\admin01\documents\windowspowershell\profile.ps1 @@ -164,22 +180,24 @@ The script contains a single command that uses dot sourcing to run the user's ** For more information about profiles, see about_Profiles. For more information about dot sourcing, see about_Scopes. + ### Example 6 + ``` The first pair of commands use the **New-PSSessionConfigurationFile** cmdlet to create two session configuration files. The first command creates a no-Language file. The second command creates a restricted-language file. Other than the value of the **LanguageMode** parameter, the session configuration files are equivalent. -PS C:\> New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage -PS C:\> New-PSSessionConfigurationFile -Path .\RestrictedLanguage.pssc -LanguageMode Restricted +PS> New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage +PS> New-PSSessionConfigurationFile -Path .\RestrictedLanguage.pssc -LanguageMode Restricted The second pair of commands use the configuration files to create session configurations on the local computer. -PS C:\> Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force -PS C:\> Register-PSSessionConfiguration -Path .\RestrictedLanguage.pssc -Name RestrictedLanguage -Force +PS> Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force +PS> Register-PSSessionConfiguration -Path .\RestrictedLanguage.pssc -Name RestrictedLanguage -Force The third pair of command creates two sessions, each of which uses one of the session configurations that was created in the previous command pair. -PS C:\> $NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage -PS C:\> $RestrictedLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage +PS> $NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage +PS> $RestrictedLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage The seventh command uses the Invoke-Command cmdlet to run an If statement in the no-Language session. The command fails, because the language elements in the command are not permitted in a no-language session. -PS C:\> Invoke-Command -Session $NoLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } +PS> Invoke-Command -Session $NoLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } The syntax is not supported by this runspace. This might be because it is in no-language mode. + CategoryInfo : ParserError: (if ((Get-Date) ...") {"Before"} :String) [], ParseException + FullyQualifiedErrorId : ScriptsNotAllowed @@ -187,7 +205,7 @@ The syntax is not supported by this runspace. This might be because it is in no- The eighth command uses the **Invoke-Command** cmdlet to run the same If statement in the restricted-language session. Because these language elements are permitted in the restricted-language session, the command succeeds. -PS C:\> Invoke-Command -Session $RestrictedLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } +PS> Invoke-Command -Session $RestrictedLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } Before ``` @@ -196,9 +214,11 @@ The example shows the effect of using the **LanguageMode** parameter of **New-PS To run the commands in this example, start Windows PowerShell with the "Run as administrator" option. This option is required to run the Register-PSSessionConfiguration cmdlet . + ## PARAMETERS ### -AccessMode + Enables and disables the session configuration and determines whether it can be used for remote or local sessions on the computer. **Remote** is the default. @@ -226,6 +246,7 @@ Accept wildcard characters: False ``` ### -ApplicationBase + Specifies the path to the assembly file (*.dll) that is specified in the value of the **AssemblyName** parameter. Use this parameter when the value of the **AssemblyName** parameter does not include a path. The default is the current directory. @@ -243,6 +264,7 @@ Accept wildcard characters: False ``` ### -AssemblyName + Specifies the name of an assembly file (*.dll) in which the configuration type is defined. You can specify the path to the .dll in this parameter or in the value of the **ApplicationBase** parameter. @@ -261,6 +283,7 @@ Accept wildcard characters: False ``` ### -ConfigurationTypeName + Specifies the fully qualified name of the Microsoft .NET Framework type that is used for this configuration. The type that you specify must implement the **System.Management.Automation.Remoting.PSSessionConfiguration** class. @@ -283,6 +306,7 @@ Accept wildcard characters: False ``` ### -Force + Suppresses all users prompts and restarts the WinRM service without prompting. Restarting the service makes the configuration change effective. @@ -301,6 +325,7 @@ Accept wildcard characters: False ``` ### -MaximumReceivedDataSizePerCommandMB + Limits the amount of data that can be sent to this computer in any single remote command. Enter the data size in megabytes (MB). The default is 50 MB. @@ -320,6 +345,7 @@ Accept wildcard characters: False ``` ### -MaximumReceivedObjectSizeMB + Limits the amount of data that can be sent to this computer in any single object. Enter the data size in megabytes (MB). The default is 10 MB. @@ -339,6 +365,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies a name for the session configuration. This parameter is required. @@ -355,6 +382,7 @@ Accept wildcard characters: False ``` ### -NoServiceRestart + Does not restart the WinRM service, and suppresses the prompt to restart the service. By default, when you enter a **Register-PSSessionConfiguration** command, you are prompted to restart the WinRM service to make the new session configuration effective. @@ -376,6 +404,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path and file name of a session configuration file (.pssc), such as one created by the New-PSSessionConfigurationFile cmdlet. If you omit the path, the default is the current directory. @@ -394,6 +423,7 @@ Accept wildcard characters: False ``` ### -ProcessorArchitecture + Determines whether a 32-bit or 64-bit version of the Windows PowerShell process is started in sessions that use this session configuration. Valid values are x86 (32-bit) and AMD64 (64-bit). The default value is determined by the processor architecture of the computer that hosts the session configuration. @@ -414,6 +444,7 @@ Accept wildcard characters: False ``` ### -PSVersion + Specifies the version of Windows PowerShell in sessions that use this session configuration. The value of this parameter takes precedence over the value of the **PowerShellVersion** key in the session configuration file. @@ -433,6 +464,7 @@ Accept wildcard characters: False ``` ### -RunAsCredential + Runs commands in the session with the permissions of the specified user. By default, commands run with the permissions of the current user. @@ -451,6 +483,7 @@ Accept wildcard characters: False ``` ### -SecurityDescriptorSddl + Specifies a Security Descriptor Definition Language (SDDL) string for the configuration. This string determines the permissions that are required to use the new session configuration. @@ -477,6 +510,7 @@ Accept wildcard characters: False ``` ### -SessionType + Specifies the type of session that is created by using the session configuration. The default value is **Default**. Valid values are: @@ -502,6 +536,7 @@ Accept wildcard characters: False ``` ### -SessionTypeOption + Sets type-specific options for the session configuration. Enter a session type options object, such as the **PSWorkflowExecutionOption** object that the New-PSWorkflowExecutionOption cmdlet returns. @@ -524,6 +559,7 @@ Accept wildcard characters: False ``` ### -ShowSecurityDescriptorUI + Displays a property sheet that helps you to create the SDDL for the session configuration. The property sheet appears after you enter the **Register-PSSessionConfiguration** command and then restart the WinRM service. @@ -544,6 +580,7 @@ Accept wildcard characters: False ``` ### -StartupScript + Specifies the fully qualified path to a Windows PowerShell script. The specified script runs in the new session that uses the session configuration. @@ -563,6 +600,7 @@ Accept wildcard characters: False ``` ### -ThreadApartmentState + Determines the apartment state of the threads in the session. Valid values are **STA**, **MTA**, and **Unknown**. **Unknown** is the default. @@ -580,6 +618,7 @@ Accept wildcard characters: False ``` ### -ThreadOptions + Defines how threads are created and used when a command is executed in the session. Valid values are **Default**, **ReuseThread**, **UseCurrentThread**, and **UseNewThread**. **UseCurrentThread** is the default. @@ -599,6 +638,7 @@ Accept wildcard characters: False ``` ### -TransportOption + This parameter is introduced in Windows PowerShell 3.0. ```yaml @@ -614,6 +654,7 @@ Accept wildcard characters: False ``` ### -UseSharedProcess + Use only one process to host all sessions that are started by the same user and use the same session configuration. By default, each session is hosted in its own process. @@ -632,6 +673,7 @@ Accept wildcard characters: False ``` ### -ModulesToImport + Specifies the modules and snap-ins that are automatically imported into sessions that use the session configuration. By default, only the **Microsoft.PowerShell.Core** snap-in is imported into sessions, but unless the cmdlets are excluded, users can use the Import-Module and Add-PSSnapin cmdlets to add modules and snap-ins to the session. @@ -654,6 +696,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -669,6 +712,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -685,21 +729,27 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### Microsoft.WSMan.Management.WSManConfigContainerElement ## NOTES -* To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, start Windows PowerShell with the "Run as administrator" option. + +- To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, start Windows PowerShell with the "Run as administrator" option. This cmdlet generates XML that represents a Web Services for Management (WS-Management) plug-in configuration and sends the XML to WS-Management, which registers the plug-in on the local computer ("new-item wsman:\localhost\plugin"). -* 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. +- 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 [Disable-PSSessionConfiguration](Disable-PSSessionConfiguration.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Remove-Job.md b/reference/3.0/Microsoft.PowerShell.Core/Remove-Job.md index 5d2e97792f5e..ded8983e5af4 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Remove-Job.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Remove-Job.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,48 +7,58 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113377 external help file: System.Management.Automation.dll-Help.xml title: Remove-Job --- - # Remove-Job + ## SYNOPSIS + Deletes a Windows PowerShell background job. + ## SYNTAX ### SessionIdParameterSet (Default) + ``` Remove-Job [-Force] [-Id] [-WhatIf] [-Confirm] [] ``` ### JobParameterSet + ``` Remove-Job [-Job] [-Force] [-WhatIf] [-Confirm] [] ``` ### NameParameterSet + ``` Remove-Job [-Force] [-Name] [-WhatIf] [-Confirm] [] ``` ### InstanceIdParameterSet + ``` Remove-Job [-Force] [-InstanceId] [-WhatIf] [-Confirm] [] ``` ### FilterParameterSet + ``` Remove-Job [-Force] [-Filter] [-WhatIf] [-Confirm] [] ``` ### StateParameterSet + ``` Remove-Job [-State] [-WhatIf] [-Confirm] [] ``` ### CommandParameterSet + ``` Remove-Job [-Command ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Remove-Job** cmdlet deletes Windows PowerShell background jobs that were started by using the Start-Job or the **AsJob** parameter of any cmdlet. You can use this cmdlet to delete all jobs or delete selected jobs based on their name, ID, instance ID, command, or state, or by passing a job object to **Remove-Job**. @@ -62,12 +72,14 @@ If you try to delete a running job, the command fails. You can use the **Force** parameter of **Remove-Job** to delete a running job. If you do not delete a background job, the job remains in the global job cache until you close the session in which the job was created. + ## EXAMPLES ### Example 1 + ``` -PS C:\> $batch = Get-Job -Name BatchJob -PS C:\> $batch | Remove-Job +PS> $batch = Get-Job -Name BatchJob +PS> $batch | Remove-Job ``` These commands delete a background job named BatchJob from the current session. @@ -75,30 +87,38 @@ The first command uses the Get-Job cmdlet to get an object representing the job, The second command uses a pipeline operator (|) to send the job to the Remove-Job cmdlet. This command is equivalent to using the **Job** parameter of **Remove-Job**, for example, "remove-job -job $batch". + ### Example 2 + ``` -PS C:\> Get-job | Remove-Job +PS> Get-job | Remove-Job ``` This command deletes all of the jobs in the current session. + ### Example 3 + ``` -PS C:\> Remove-Job -State NotStarted +PS> Remove-Job -State NotStarted ``` This command deletes all jobs from the current session that have not yet been started. + ### Example 4 + ``` -PS C:\> Remove-Job -Name *batch -Force +PS> Remove-Job -Name *batch -Force ``` This command deletes all jobs with friendly names that end with "batch" from the current session, including jobs that are running. It uses the **Name** parameter of **Remove-Job** to specify a job name pattern, and it uses the **Force** parameter to ensure that all jobs are removed, even those that might be in progress. + ### Example 5 + ``` -PS C:\> $j = Invoke-Command -ComputerName Server01 -ScriptBlock {Get-Process} -AsJob -PS C:\> $j | Remove-Job +PS> $j = Invoke-Command -ComputerName Server01 -ScriptBlock {Get-Process} -AsJob +PS> $j | Remove-Job ``` This example shows how to use the **Remove-Job** cmdlet to remove a job that was started on a remote computer by using the **AsJob** parameter of the Invoke-Command cmdlet. @@ -113,27 +133,31 @@ The second command uses the **Remove-Job** cmdlet to remove the job. It uses a pipeline operator (|) to send the job in $j to **Remove-Job**. Note that this is a local command. A remote command is not required to remove a job that was started by using the **AsJob** parameter. + ### Example 6 + ``` The first command uses the New-PSSession cmdlet to create a PSSession (a persistent connection) to the Server01 computer. A persistent connection is required when running a Start-Job command remotely. The command saves the PSSession in the $s variable. -PS C:\> $s = New-PSSession -ComputerName Server01 +PS> $s = New-PSSession -ComputerName Server01 The second command uses the **Invoke-Command** cmdlet to run a **Start-Job** command in the PSSession in $s. The job runs a **Get-Process** command. It uses the **Name** parameter of **Start-Job** to specify a friendly name for the job. -PS C:\> Invoke-Command -Session $s -ScriptBlock {Start-Job -ScriptBlock {Get-Process} -Name MyJob} +PS> Invoke-Command -Session $s -ScriptBlock {Start-Job -ScriptBlock {Get-Process} -Name MyJob} The third command uses the **Invoke-Command** cmdlet to run a **Remove-Job** command in the PSSession in $s. The command uses the **Name** parameter of Remove-Job to identify the job to be deleted. -PS C:\> Invoke-Command -Session $s -ScriptBlock {Remove-Job -Name MyJob} +PS> Invoke-Command -Session $s -ScriptBlock {Remove-Job -Name MyJob} ``` This example shows how to remove a job that was started by using Invoke-Command to run a Start-Job command. In this case, the job object is created on the remote computer and you use remote commands to manage the job. + ### Example 7 + ``` The first command uses the Start-Job cmdlet to start a background job. The command saves the resulting job object in the $j variable. -PS C:\> $j = Start-Job -ScriptBlock {Get-Process Powershell} +PS> $j = Start-Job -ScriptBlock {Get-Process Powershell} The second command uses a pipeline operator (|) to send the job object in $j to the Format-List cmdlet. The **Format-List** command uses the **Property** parameter with a value of * (all) to display all of the properties of the job object in a list.The job object display shows the values of the **ID** and **InstanceID** properties, along with the other properties of the object. -PS C:\> $j | Format-List -Property * +PS> $j | Format-List -Property * HasMoreData : False StatusMessage : @@ -154,13 +178,15 @@ Warning : {} StateChanged : The third command uses a **Remove-Job** command to remove the job from the current session. To generate the command, you can copy and paste the **InstanceID** value from the object display.To copy a value in the Windows PowerShell console, use the mouse to select the value, and then press Enter to copy it. To paste a value, right-click. -PS C:\> Remove-Job -InstanceID dce2ee73-f8c9-483e-bdd7-a549d8687eed +PS> Remove-Job -InstanceID dce2ee73-f8c9-483e-bdd7-a549d8687eed ``` This example shows how to remove a job based on its instance ID. + ## PARAMETERS ### -Command + Deletes jobs that include the specified words in the command. ```yaml @@ -176,6 +202,7 @@ Accept wildcard characters: False ``` ### -Filter + Deletes jobs that satisfy all of the conditions established in the associated hash table. Enter a hash table where the keys are job properties and the values are job property values. @@ -198,6 +225,7 @@ Accept wildcard characters: False ``` ### -Force + Deletes the job even if the status is "Running". Without the **Force** parameter, **Remove-Job** does not delete running jobs. @@ -214,6 +242,7 @@ Accept wildcard characters: False ``` ### -Id + Deletes background jobs with the specified IDs. The ID is an integer that uniquely identifies the job within the current session. @@ -234,6 +263,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Deletes jobs with the specified instance IDs. An instance ID is a GUID that uniquely identifies the job on the computer. @@ -252,6 +282,7 @@ Accept wildcard characters: False ``` ### -Job + Specifies the jobs to be deleted. Enter a variable that contains the jobs or a command that gets the jobs. You can also use a pipeline operator to submit jobs to the **Remove-Job** cmdlet. @@ -269,6 +300,7 @@ Accept wildcard characters: False ``` ### -Name + Deletes only the jobs with the specified friendly names. Wildcards are permitted. @@ -287,6 +319,7 @@ Accept wildcard characters: False ``` ### -State + Deletes only jobs with the specified status. Valid values are Valid values are NotStarted, Running, Completed, Failed, Stopped, Blocked, Disconnected, Suspending, Stopping, and Suspended. To delete jobs with a state of Running, use the **Force** parameter. @@ -304,6 +337,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -319,6 +353,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -335,15 +370,21 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.Job + You can pipe a job object to Remove-Job. + ## OUTPUTS ### None + This cmdlet does not generate any output. + ## NOTES ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Core/Remove-Module.md b/reference/3.0/Microsoft.PowerShell.Core/Remove-Module.md index e52ec11202cc..7c59646e776e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Remove-Module.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Remove-Module.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,46 +7,57 @@ online version: http://go.microsoft.com/fwlink/?LinkID=141556 external help file: System.Management.Automation.dll-Help.xml title: Remove-Module --- - # Remove-Module + ## SYNOPSIS + Removes modules from the current session. + ## SYNTAX ### name + ``` Remove-Module [-Name] [-Force] [-WhatIf] [-Confirm] [] ``` ### ModuleInfo + ``` Remove-Module [-ModuleInfo] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Remove-Module** cmdlet removes the members of a module, such as cmdlets and functions, from the current session. If the module includes an assembly (.dll), all members that are implemented by the assembly are removed, but the assembly is not unloaded. This cmdlet does not uninstall the module or delete it from the computer. It affects only the current Windows PowerShell session. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Remove-Module -Name BitsTransfer +PS> Remove-Module -Name BitsTransfer ``` This command removes the BitsTransfer module from the current session. + ### Example 2 + ``` -PS C:\> Get-Module | Remove-Module +PS> Get-Module | Remove-Module ``` This command removes all modules from the current session. + ### Example 3 + ``` -PS C:\> "FileTransfer", "PSDiagnostics" | Remove-Module -Verbose +PS> "FileTransfer", "PSDiagnostics" | Remove-Module -Verbose VERBOSE: Performing operation "Remove-Module" on Target "filetransfer (Path: 'C:\Windows\system32\WindowsPowerShell\v1.0\Modules\filetransfer\filetransfer.psd1')". VERBOSE: Performing operation "Remove-Module" on Target "Microsoft.BackgroundIntelligentTransfer.Management (Path: 'C:\Windows\assembly\GAC_MSIL\Microsoft.BackgroundIntelligentTransfer.Management\1.0.0.0__31bf3856ad364e35\Microsoft.BackgroundIntelligentTransfe r.Management.dll')". @@ -72,16 +83,20 @@ It uses the **Verbose** common parameter to get detailed information about the m The Verbose messages show the items that are removed. The messages differ because the BitsTransfer module includes an assembly that implements its cmdlets and a nested module with its own assembly. The PSDiagnostics module includes a module script file (.psm1) that exports functions. + ### Example 4 + ``` -PS C:\> $a = Get-Module BitsTransfer -PS C:\> Remove-Module -ModuleInfo $a +PS> $a = Get-Module BitsTransfer +PS> Remove-Module -ModuleInfo $a ``` This command uses the ModuleInfo parameter to remove the BitsTransfer module. + ## PARAMETERS ### -Force + Removes read-only modules. By default, **Remove-Module** removes only read-write modules. @@ -100,6 +115,7 @@ Accept wildcard characters: False ``` ### -ModuleInfo + Specifies the module objects to remove. Enter a variable that contains a module object (PSModuleInfo) or a command that gets a module object, such as a Get-Module command. You can also pipe module objects to **Remove-Module**. @@ -117,6 +133,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the names of modules to remove. Wildcards are permitted. You can also pipe name strings to **Remove-Module**. @@ -134,6 +151,7 @@ Accept wildcard characters: True ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -149,6 +167,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -165,15 +184,21 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.String, System.Management.Automation.PSModuleInfo + You can pipe module names (strings) and module objects to **Remove-Module**. + ## OUTPUTS ### None + Remove-Module does not generate any output. + ## NOTES ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSession.md index 2af91bdbe2f1..4dd2eacc335a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSession.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,38 +7,46 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135250 external help file: System.Management.Automation.dll-Help.xml title: Remove-PSSession --- - # Remove-PSSession + ## SYNOPSIS + Closes one or more Windows PowerShell sessions (PSSessions). + ## SYNTAX ### Id (Default) + ``` Remove-PSSession [-Id] [-WhatIf] [-Confirm] [] ``` ### Session + ``` Remove-PSSession [-Session] [-WhatIf] [-Confirm] [] ``` ### InstanceId + ``` Remove-PSSession -InstanceId [-WhatIf] [-Confirm] [] ``` ### Name + ``` Remove-PSSession -Name [-WhatIf] [-Confirm] [] ``` ### ComputerName + ``` Remove-PSSession [-ComputerName] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The Remove-PSSession cmdlet closes Windows PowerShell sessions (PSSessions) in the current session. It stops any commands that are running in the PSSessions, ends the PSSession, and releases the resources that the PSSession was using. If the PSSession is connected to a remote computer, Remove-PSSession also closes the connection between the local and remote computers. @@ -46,47 +54,57 @@ If the PSSession is connected to a remote computer, Remove-PSSession also closes To remove a PSSession, enter the Name, ComputerName, ID, or InstanceID of the session. If you have saved the PSSession in a variable, the session object remains in the variable, but the state of the PSSession is "Closed." + ## EXAMPLES ### Example 1 + ``` -PS C:\> remove-pssession -id 1, 2 +PS> remove-pssession -id 1, 2 ``` This command removes the PSSessions that have IDs 1 and 2. + ### Example 2 + ``` -PS C:\> get-pssession | remove-pssession +PS> get-pssession | remove-pssession - or - -PS C:\> remove-pssession -session (get-pssession) +PS> remove-pssession -session (get-pssession) - or - -PS C:\> $s = get-pssession -PS C:\> remove-pssession -session $s +PS> $s = get-pssession +PS> remove-pssession -session $s ``` These commands remove all of the PSSessions in the current session. Although the three command formats look different, they have the same effect. + ### Example 3 + ``` -PS C:\> $r = get-pssession -computername Serv* +PS> $r = get-pssession -computername Serv* $r | remove-pssession ``` These commands close the PSSessions that are connected to computers that have names that begin with "Serv". + ### Example 4 + ``` -PS C:\> get-pssession | where {$_.port -eq 90} | remove-pssession +PS> get-pssession | where {$_.port -eq 90} | remove-pssession ``` This command closes the PSSessions that are connected to port 90. You can use this command format to identify PSSessions by properties other than ComputerName, Name, InstanceID, and ID. + ### Example 5 + ``` -PS C:\> get-pssession | ft computername, instanceID -auto +PS> get-pssession | ft computername, instanceID -auto ComputerName InstanceId ------------ ---------------- @@ -96,7 +114,7 @@ Server02 4699cdbc-61d5-4e0d-b916-84f82ebede1f Server03 4e5a3245-4c63-43e4-88d0-a7798bfc2414 TX-TEST-01 fc4e9dfa-f246-452d-9fa3-1adbdd64ae85 -PS C:\> remove-pssession -InstanceID fc4e9dfa-f246-452d-9fa3-1adbdd64ae85 +PS> remove-pssession -InstanceID fc4e9dfa-f246-452d-9fa3-1adbdd64ae85 ``` These commands show how to close a PSSession based on its instance ID (RemoteRunspaceID). @@ -108,16 +126,20 @@ The AutoSize parameter ("auto") compresses the columns for display. From the resulting display, the administrator can identify the PSSession to be closed, and copy and paste the InstanceID of that PSSession into the second command. The second command uses the Remove-PSSession cmdlet to remove the PSSession with the specified instance ID. + ### Example 6 + ``` -PS C:\> function EndPSS { get-pssession | remove-pssession } +PS> function EndPSS { get-pssession | remove-pssession } ``` This function deletes all of the PSSessions in the current session. After you add this function to your Windows Powershell profile, to delete all sessions, just type "endpss". + ## PARAMETERS ### -ComputerName + Closes the PSSessions that are connected to the specified computers. Wildcards are permitted. @@ -137,6 +159,7 @@ Accept wildcard characters: True ``` ### -Id + Closes the PSSessions with the specified IDs. Type one or more IDs (separated by commas) or use the range operator (..) to specify a range of IDs @@ -157,6 +180,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Closes the PSSessions with the specified instance IDs. The instance ID is a GUID that uniquely identifies a PSSession in the current session. @@ -178,6 +202,7 @@ Accept wildcard characters: False ``` ### -Name + Closes the PSSessions with the specified friendly names. Wildcards are permitted. @@ -196,6 +221,7 @@ Accept wildcard characters: True ``` ### -Session + Specifies the session objects of the PSSessions to close. Enter a variable that contains the PSSessions or a command that creates or gets the PSSessions, such as a New-PSSession or Get-PSSession command. You can also pipe one or more session objects to Remove-PSSession. @@ -213,6 +239,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -228,6 +255,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -244,17 +272,24 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.Runspaces.PSSession + You can pipe a session object to Remove-PSSession. + ## OUTPUTS ### None + Remove-PSSession does not return any objects. + ## NOTES -* The ID parameter is mandatory. You cannot type "remove-pssession" without parameters. To delete all the PSSessions in the current session, type "get-pssession | remove-pssession". + +- The ID parameter is mandatory. You cannot type "remove-pssession" without parameters. To delete all the PSSessions in the current session, type "get-pssession | remove-pssession". A PSSession uses a persistent connection to a remote computer. Create a PSSession to run a series of commands that share data. @@ -263,7 +298,8 @@ For more information, see about_PSSessions. PSSessions are specific to the current session. When you end a session, the PSSessions that you created in that session are forcibly closed. -* +- + ## RELATED LINKS [Connect-PSSession](Connect-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSnapin.md b/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSnapin.md index f46b56d76723..0e08950c634a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSnapin.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSnapin.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113378 external help file: System.Management.Automation.dll-Help.xml title: Remove-PSSnapin --- - # Remove-PSSnapin + ## SYNOPSIS + Removes Windows PowerShell snap-ins from the current session. + ## SYNTAX ``` @@ -18,22 +20,27 @@ Remove-PSSnapin [-Name] [-PassThru] [-WhatIf] [-Confirm] [ remove-pssnapin -name Microsoft.Exchange +PS> remove-pssnapin -name Microsoft.Exchange ``` This command removes the Microsoft.Exchange snap-in from the current session. When the command is complete, the cmdlets and providers that the snap-in supported are not available in the session. + ### Example 2 + ``` -PS C:\> get-PSSnapIn smp* | remove-PSSnapIn +PS> get-PSSnapIn smp* | remove-PSSnapIn ``` This command removes the Windows PowerShell snap-ins that have names beginning with "smp" from the current session. @@ -43,16 +50,20 @@ The pipeline operator (|) sends the results to the Remove-PSSnapin cmdlet, which The providers and cmdlets that this snap-in supports are no longer available in the session. When you pipe objects to Remove-PSSnapin, the names of the objects are associated with the Name parameter, which accepts objects from the pipeline that have a Name property. + ### Example 3 + ``` -PS C:\> remove-pssnapin -name *event* +PS> remove-pssnapin -name *event* ``` This command removes all Windows PowerShell snap-ins that have names that include "event". This command specifies the "Name" parameter name, but the parameter name can be omitted because it is optional. + ## PARAMETERS ### -Name + Specifies the names of Windows PowerShell snap-ins to remove from the current session. The parameter name ("Name") is optional, and wildcard characters (*) are permitted in the value. @@ -69,6 +80,7 @@ Accept wildcard characters: True ``` ### -PassThru + Returns an object representing the snap-in. By default, this cmdlet does not generate any output. @@ -85,6 +97,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -100,6 +113,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -116,18 +130,25 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.PSSnapInInfo + You can pipe a snap-in object to Remove-PSSnapin. + ## OUTPUTS ### None or System.Management.Automation.PSSnapInInfo + By default, Remove-PsSnapin does not generate any output. However, if you use the PassThru parameter, it generates a System.Management.Automation.PSSnapInInfo object representing the snap-in. + ## NOTES -* You can also refer to Remove-PSSnapin by its built-in alias, "rsnp". For more information, see about_Aliases. + +- You can also refer to Remove-PSSnapin by its built-in alias, "rsnp". For more information, see about_Aliases. Remove-PSSnapin does not check the version of Windows PowerShell before removing a snap-in from the session. If a snap-in cannot be removed, a warning appears and the command fails. @@ -136,7 +157,8 @@ If a snap-in cannot be removed, a warning appears and the command fails. If you have added an Add-PSSnapin command to your Windows PowerShell profile, you should delete the command to remove the snap-in from future sessions. For instructions, see about_Profiles. -* +- + ## RELATED LINKS [Add-PSSnapin](Add-PSSnapin.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Resume-Job.md b/reference/3.0/Microsoft.PowerShell.Core/Resume-Job.md index 08b071dff396..de930e0b6579 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Resume-Job.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Resume-Job.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,43 +7,52 @@ online version: http://go.microsoft.com/fwlink/?LinkID=210611 external help file: System.Management.Automation.dll-Help.xml title: Resume-Job --- - # Resume-Job + ## SYNOPSIS + Restarts a suspended job + ## SYNTAX ### SessionIdParameterSet (Default) + ``` Resume-Job [-Wait] [-Id] [-WhatIf] [-Confirm] [] ``` ### JobParameterSet + ``` Resume-Job [-Job] [-Wait] [-WhatIf] [-Confirm] [] ``` ### NameParameterSet + ``` Resume-Job [-Wait] [-Name] [-WhatIf] [-Confirm] [] ``` ### InstanceIdParameterSet + ``` Resume-Job [-Wait] [-InstanceId] [-WhatIf] [-Confirm] [] ``` ### StateParameterSet + ``` Resume-Job [-Wait] [-State] [-WhatIf] [-Confirm] [] ``` ### FilterParameterSet + ``` Resume-Job [-Wait] [-Filter] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Resume-Job** cmdlet resumes a workflow job that was suspended, such as by using the Suspend-Job cmdlet or the about_Suspend-Workflow activity. When a workflow job is resumed, the job engine reconstructs the state, metadata, and output from saved resources, such as checkpoints, so the job is restarted without any loss of state or data. The job state is changed from **Suspended** to **Running**. @@ -64,38 +73,46 @@ To determine whether a particular custom job type supports the **Resume-Job** cm NOTE: Before using a Job cmdlet on a custom job type, import the module that supports the custom job type, either by using the Import-Module cmdlet or getting or using a cmdlet in the module. This cmdlet is introduced in Windows PowerShell 3.0. + ## EXAMPLES ### Example 1: Resume a job by ID + ``` The first command uses the **Get-Job** cmdlet to get the job. The output shows that the job is a suspended workflow job. -PS C:\> Get-Job EventJob +PS> Get-Job EventJob Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 4 EventJob PSWorkflowJob Suspended True Server01 \\Script\Share\Event.ps1 The second command uses the **Id** parameter of the **Resume-Job** cmdlet to resume the job with an **Id** value of 4. -PS C:\> Resume-Job -Id 4 +PS> Resume-Job -Id 4 ``` The commands in this example verify that the job is a suspended workflow job and then resume the job. + ### Example 2: Resume a job by name + ``` -PS C:\> Resume-Job -Name WorkflowJob, InventoryWorkflow, WFTest* +PS> Resume-Job -Name WorkflowJob, InventoryWorkflow, WFTest* ``` This command uses the **Name** parameter to resume several workflow jobs on the local computer. + ### Example 3: Use custom property values + ``` -PS C:\> Resume-Job -Filter @{CustomID="T091291"} -State Suspended +PS> Resume-Job -Filter @{CustomID="T091291"} -State Suspended ``` This command uses the value of a custom property to identify the workflow job to resume. It uses the **Filter** parameter to identify the workflow job by its **CustomID** property. It also uses the **State** parameter to verify that the workflow job is suspended, before it tries to resume it. + ### Example 4: Resume all suspended jobs on a remote computer + ``` -PS C:\> Invoke-Command -ComputerName Srv01 -ScriptBlock {Get-Job -State Suspended | Resume-Job} +PS> Invoke-Command -ComputerName Srv01 -ScriptBlock {Get-Job -State Suspended | Resume-Job} ``` This command resumes all suspended jobs on the Srv01 remote computer. @@ -103,14 +120,18 @@ This command resumes all suspended jobs on the Srv01 remote computer. The command uses the Invoke-Command cmdlet to run a command on the Srv01 computer. The remote command uses the **State** parameter of the Get-Job cmdlet to get all suspended jobs on the computer. A pipeline operator (|) sends the suspended jobs to the **Resume-Job** cmdlet, which resumes them. + ### Example 5: Wait for jobs to resume + ``` -PS C:\> Resume-Job -Name WorkflowJob, InventoryWorkflow, WFTest* -Wait +PS> Resume-Job -Name WorkflowJob, InventoryWorkflow, WFTest* -Wait ``` This command uses the **Wait** parameter to direct Resume-Job to return only after all specified jobs are resumed. The **Wait** parameter is especially useful in scripts that assume that jobs are resumed before the script continues. + ### Example 6: Resume a Workflow that Suspends Itself + ``` This code sample shows the **Suspend-Workflow** activity in a workflow. #SampleWorkflow @@ -122,7 +143,7 @@ Workflow Test-Suspend } The following command runs the Test-Suspend workflow on the Server01 computer.When you run the workflow, the workflow runs the Get-Date activity and saves the result in the $a variable. Then it runs the **Suspend-Workflow** activity. In response, it takes a checkpoint, suspends the workflow, and returns a workflow job object. **Suspend-Workflow** returns a workflow job object even if the workflow is not explicitly run as a job. -PS C:\> Test-Suspend -PSComputerName Server01 +PS> Test-Suspend -PSComputerName Server01 Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -130,7 +151,7 @@ Id Name PSJobTypeName State HasMoreData Location 8 Job8 PSWorkflowJob Suspended True Server01 Test-Suspend The following command resumes the Test-Suspend workflow in Job8. It uses the **Wait** parameter to hold the command prompt until the job is resumed. -PS C:\> Resume-Job -Name Job8 -Wait +PS> Resume-Job -Name Job8 -Wait Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -138,7 +159,7 @@ Id Name PSJobTypeName State HasMoreData Location 8 Job8 PSWorkflowJob Running True Server01 Test-Suspend This command uses the **Receive-Job** cmdlet to get the results of the Test-Suspend workflow. The final command in the workflow returns a TimeSpan object that represents the elapsed time between the current date and time and the date and time that was saved in the $a variable before the workflow was suspended. -PS C:\> Receive-Job -Name Job8 +PS> Receive-Job -Name Job8 Days : 0 Hours : 0 @@ -169,9 +190,11 @@ This activity suspends a workflow from within a workflow. It is valid only in workflows. For information about the Suspend-Workflow, see about_Suspend-Workflow. + ## PARAMETERS ### -Filter + Resumes only jobs that satisfy all of the conditions established in the associated hash table. Enter a hash table where the keys are job properties and the values are job property values. @@ -188,6 +211,7 @@ Accept wildcard characters: False ``` ### -Id + Resumes the jobs with the specified IDs. The ID is an integer that uniquely identifies the job within the current session. @@ -208,6 +232,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Resumes jobs with the specified instance IDs. The default is all jobs. @@ -227,6 +252,7 @@ Accept wildcard characters: False ``` ### -Job + Specifies the jobs to be resumed. Enter a variable that contains the jobs or a command that gets the jobs. You can also pipe jobs to the **Resume-Job** cmdlet. @@ -244,6 +270,7 @@ Accept wildcard characters: False ``` ### -Name + Resumes jobs with the specified friendly names. Enter one or more job names. Wildcards are supported. @@ -261,6 +288,7 @@ Accept wildcard characters: False ``` ### -State + Resumes only those jobs in the specified state. Valid values are NotStarted, Running, Completed, Failed, Stopped, Blocked, Suspended, Disconnected, Suspending, and Stopping, but **Resume-Job** resumes only jobs in the **Suspended** state. @@ -279,6 +307,7 @@ Accept wildcard characters: False ``` ### -Wait + Suspends the command prompt until all specified jobs are resumed. By default, Resume-Job returns immediately. @@ -295,6 +324,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -310,6 +340,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -326,23 +357,31 @@ 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.Job + You can pipe all types of jobs to **Resume-Job**. However, if **Resume-Job** gets a job of an unsupported type, it throws a terminating error. + ## OUTPUTS ### None or System.Management.Automation.Job + If you use the **PassThru** parameter, **Resume-Job** returns the jobs that it tried to resume. Otherwise, this cmdlet does not generate any output. + ## NOTES -* **Resume-Job** can only resume jobs that are suspended. If you submit a job in a different state, **Resume-Job** runs the resume operation on the job, but generates a warning to notify you that the job could not be resumed. To suppress the warning, use the **WarningAction** common parameter with a value of **SilentlyContinue**. -* If a job is not of a type that supports resuming, such as a workflow job (PSWorkflowJob), **Resume-Job** throws a terminating error. -* The mechanism and location for saving a suspended job might vary depending on the job type. For example, suspended workflow jobs are saved in a flat file store by default, but can also be saved in a SQL database. -* When you resume a job, the job state changes from **Suspended** to **Running**. To find the jobs that are running, including those that were resumed by this cmdlet, use the **State** parameter of the Get-Job cmdlet to get jobs in the **Running** state. -* Some job types have options or properties that prevent Windows PowerShell from suspending the job. If attempts to suspend the job fail, verify that the job options and properties allow suspending. + +- **Resume-Job** can only resume jobs that are suspended. If you submit a job in a different state, **Resume-Job** runs the resume operation on the job, but generates a warning to notify you that the job could not be resumed. To suppress the warning, use the **WarningAction** common parameter with a value of **SilentlyContinue**. +- If a job is not of a type that supports resuming, such as a workflow job (PSWorkflowJob), **Resume-Job** throws a terminating error. +- The mechanism and location for saving a suspended job might vary depending on the job type. For example, suspended workflow jobs are saved in a flat file store by default, but can also be saved in a SQL database. +- When you resume a job, the job state changes from **Suspended** to **Running**. To find the jobs that are running, including those that were resumed by this cmdlet, use the **State** parameter of the Get-Job cmdlet to get jobs in the **Running** state. +- Some job types have options or properties that prevent Windows PowerShell from suspending the job. If attempts to suspend the job fail, verify that the job options and properties allow suspending. + ## RELATED LINKS [Get-Job](Get-Job.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Save-Help.md b/reference/3.0/Microsoft.PowerShell.Core/Save-Help.md index 31877db158cf..c6b117418895 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Save-Help.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Save-Help.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,25 +7,30 @@ online version: http://go.microsoft.com/fwlink/?LinkID=210612 external help file: System.Management.Automation.dll-Help.xml title: Save-Help --- - # Save-Help + ## SYNOPSIS + Downloads and saves the newest help files to a file system directory. + ## SYNTAX ### Path (Default) + ``` Save-Help [-DestinationPath] [[-Module] ] [[-UICulture] ] [-Credential ] [-UseDefaultCredentials] [-Force] [] ``` ### LiteralPath + ``` Save-Help -LiteralPath [[-Module] ] [[-UICulture] ] [-Credential ] [-UseDefaultCredentials] [-Force] [] ``` ## DESCRIPTION + The **Save-Help** cmdlet downloads the newest help files for Windows PowerShell modules and saves them to a directory that you specify. This feature allows you to update the help files on computers that do not have access to the Internet and makes it easier to update the help files on multiple computers. @@ -46,18 +51,22 @@ To save the help files for modules in the Windows PowerShell installation direct You must be a member of the Administrators group on the computer to download the help files for these modules. This cmdlet is introduced in Windows PowerShell 3.0. + ## EXAMPLES ### Example 1: Save help for all modules + ``` -PS C:\> Save-Help -DestinationPath \\Server01\FileShare01 +PS> Save-Help -DestinationPath \\Server01\FileShare01 ``` This command downloads the newest help files for all modules in the UI culture set for Windows on the local computer. It saves the help files in the \\\\Server01\Fileshare01 directory. + ### Example 2: Save help for a module on the computer + ``` -PS C:\> Save-Help -Module ServerManager -DestinationPath \\Server01\FileShare01 -Credential Domain01/Admin01 +PS> Save-Help -Module ServerManager -DestinationPath \\Server01\FileShare01 -Credential Domain01/Admin01 ``` This command downloads the newest help files for the ServerManager module and saves them in the \\\\Server01\Fileshare01 directory. @@ -65,9 +74,11 @@ This command downloads the newest help files for the ServerManager module and sa When a module is installed on the computer, you can type the module name as the value of the **Module** parameter, even if the module is not imported into the current session. The command uses the **Credential** parameter to supply the credentials of a user who has permission to write to the file share. + ### Example 3: Save help for a module on a different computer + ``` -PS C:\> Invoke-Command -ComputerName Server02 {Get-Module -Name CustomSQL -ListAvailable} | Save-Help -DestinationPath \\Server01\FileShare01 -Credential Domain01\Admin01 +PS> Invoke-Command -ComputerName Server02 {Get-Module -Name CustomSQL -ListAvailable} | Save-Help -DestinationPath \\Server01\FileShare01 -Credential Domain01\Admin01 ``` These commands download the newest help files for the CustomSQL module and save them in the \\\\Server01\Fileshare01 directory. @@ -75,18 +86,22 @@ These commands download the newest help files for the CustomSQL module and save Because the CustomSQL module is not installed on the computer, the sequence includes an **Invoke-Command** command that gets the module object for the CustomSQL module from the Server02 computer and then pipes the module object to the **Save-Help** cmdlet. When a module is not installed on the computer, **Save-Help** needs the module object, which includes information about the location of the newest help files. + ### Example 4: Save help for a module in multiple languages + ``` -PS C:\> Save-Help -Module Microsoft.PowerShell* -UICulture de-DE, en-US, fr-FR, ja-JP -DestinationPath D:\Help +PS> Save-Help -Module Microsoft.PowerShell* -UICulture de-DE, en-US, fr-FR, ja-JP -DestinationPath D:\Help ``` This command saves help for the Windows PowerShell Core modules in four different UI cultures. The language packs for these locales do not need to be installed on the computer. **Save-Help** can download help files for modules in different UI cultures only when the module owner makes the translated files available on the Internet. + ### Example 5: Save help more than once each day + ``` -PS C:\> Save-Help -Force -DestinationPath \\Server3\AdminShare\Help +PS> Save-Help -Force -DestinationPath \\Server3\AdminShare\Help ``` This command saves help for all modules that are installed on the computer. @@ -96,9 +111,11 @@ The **Force** parameter also overrides the 1 GB restriction and circumvents vers The command uses the **Save-Help** cmdlet to download and save the help files to the specified directory. The **Force** parameter is required when you need to run a **Save-Help** command more than once each day. + ## PARAMETERS ### -Credential + Runs the command with credentials of a user who has permission to access the file system location specified by the **DestinationPath** parameter. This parameter is valid only when the **DestinationPath** or **LiteralPath** parameter is used in the command. @@ -118,6 +135,7 @@ Accept wildcard characters: False ``` ### -DestinationPath + Specifies the path to the directory in which the help files are saved. Enter the path to a directory. Do not specify a file name or file name extension. @@ -135,6 +153,7 @@ Accept wildcard characters: False ``` ### -Force + Overrides the once-per-day limitation, circumvents version checking, and downloads files that exceed the 1 GB limit Without this parameter, only one **Save-Help** command for each module is permitted in each 24-hour period, downloads are limited to 1 GB of uncompressed content per module and help files for a module are installed only when they are newer than the files on the computer. @@ -156,6 +175,7 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies a path to the destination directory. Unlike the value of the **DestinationPath** parameter, the value of the **LiteralPath** parameter is used exactly as it is typed. No characters are interpreted as wildcards. @@ -175,6 +195,7 @@ Accept wildcard characters: False ``` ### -Module + Downloads help for the specified modules. Enter one or more module names or name patters in a comma-separated list or in a file with one module name on each line. Wildcards are permitted. @@ -207,6 +228,7 @@ Accept wildcard characters: True ``` ### -UICulture + Gets updated help files for the specified UI culture. Enter one or more language codes, such as "es-ES", a variable that contains culture objects, or a command that gets culture objects, such as a Get-Culture or Get-UICulture command. @@ -228,6 +250,7 @@ Accept wildcard characters: False ``` ### -UseDefaultCredentials + Runs the command, including the web download, with the credentials of the current user. By default, the command runs without explicit credentials. @@ -246,24 +269,32 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.PSModuleInfo + You can pipe a module object from the Get-Module cmdlet to the **Module** parameter of **Save-Help**. + ## OUTPUTS ### None + **Save-Help** does not generate any output. + ## NOTES -* To save help for modules in the $pshome\Modules directory, start Windows PowerShell with the "Run as administrator" option. Only members of the Administrators group on the computer can download help for the for modules in the $pshome\Modules directory. -* The saved help for each module consists of one help information (HelpInfo XML) file and one cabinet (.cab) file for the help files each UI culture. You do not need to extract the help files from the cabinet file. The Update-Help cmdlet extracts the help files, validates the XML, and then installs the help files and the help information file in a language-specific subdirectory of the module directory. -* The **Save-Help** cmdlet can save help for modules that are not installed on the computer. However, because help files are installed in the module directory, the Update-Help cmdlet can install updated help file only for modules that are installed on the computer. -* If **Save-Help** cannot find updated help files for a module, or cannot find updated help files in the specified language, it continues silently without displaying an error message. To see which files were saved by the command, use the **Verbose** parameter. -* Modules are the smallest unit of updatable help. You cannot save help for a particular cmdlet; only for all cmdlets in module. To find the module that contains a particular cmdlet, use the **ModuleName** property of the Get-Command cmdlet, for example, `(Get-Command \).ModuleName` -* **Save-Help** supports all modules and the Windows PowerShell Core snap-ins. It does not support any other snap-ins. -* The Update-Help and **Save-Help** cmdlets use the following ports to download help files: Port 80 for HTTP and port 443 for HTTPS. -* The **Update-Help** and **Save-Help** cmdlets are not supported on Windows Preinstallation Environment (Windows PE). + +- To save help for modules in the $pshome\Modules directory, start Windows PowerShell with the "Run as administrator" option. Only members of the Administrators group on the computer can download help for the for modules in the $pshome\Modules directory. +- The saved help for each module consists of one help information (HelpInfo XML) file and one cabinet (.cab) file for the help files each UI culture. You do not need to extract the help files from the cabinet file. The Update-Help cmdlet extracts the help files, validates the XML, and then installs the help files and the help information file in a language-specific subdirectory of the module directory. +- The **Save-Help** cmdlet can save help for modules that are not installed on the computer. However, because help files are installed in the module directory, the Update-Help cmdlet can install updated help file only for modules that are installed on the computer. +- If **Save-Help** cannot find updated help files for a module, or cannot find updated help files in the specified language, it continues silently without displaying an error message. To see which files were saved by the command, use the **Verbose** parameter. +- Modules are the smallest unit of updatable help. You cannot save help for a particular cmdlet; only for all cmdlets in module. To find the module that contains a particular cmdlet, use the **ModuleName** property of the Get-Command cmdlet, for example, `(Get-Command \).ModuleName` +- **Save-Help** supports all modules and the Windows PowerShell Core snap-ins. It does not support any other snap-ins. +- The Update-Help and **Save-Help** cmdlets use the following ports to download help files: Port 80 for HTTP and port 443 for HTTPS. +- The **Update-Help** and **Save-Help** cmdlets are not supported on Windows Preinstallation Environment (Windows PE). + ## RELATED LINKS [Updatable Help Status Table (http://go.microsoft.com/fwlink/?LinkID=270007)](http://go.microsoft.com/fwlink/?LinkID=270007) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Set-PSDebug.md b/reference/3.0/Microsoft.PowerShell.Core/Set-PSDebug.md index 6d0e2513f729..db61f67624a9 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Set-PSDebug.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Set-PSDebug.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,33 +7,40 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113398 external help file: System.Management.Automation.dll-Help.xml title: Set-PSDebug --- - # Set-PSDebug + ## SYNOPSIS + Turns script debugging features on and off, sets the trace level, and toggles strict mode. + ## SYNTAX ### on + ``` Set-PSDebug [-Trace ] [-Step] [-Strict] [] ``` ### off + ``` Set-PSDebug [-Off] [] ``` ## DESCRIPTION + The Set-PSDebug cmdlet turns script debugging features on and off, sets the trace level, and toggles strict mode. When the Trace parameter is set to 1, each line of script is traced as it is executed. When the parameter is set to 2, variable assignments, function calls, and script calls are also traced. If the Step parameter is specified, you are prompted before each line of the script is executed. + ## EXAMPLES ### Example 1 + ``` -PS C:\> set-psdebug -trace 2; foreach ($i in 1..3) {$i} +PS> set-psdebug -trace 2; foreach ($i in 1..3) {$i} DEBUG: 1+ Set-PsDebug -trace 2; foreach ($i in 1..3) {$i} DEBUG: 1+ Set-PsDebug -trace 2; foreach ($i in 1..3) {$i} @@ -45,9 +52,11 @@ DEBUG: 1+ Set-PsDebug -trace 2; foreach ($i in 1..3) {$i} ``` This command sets the trace level to 2, and then runs a script that displays the numbers 1, 2, and 3. + ### Example 2 + ``` -PS C:\> set-psdebug -step; foreach ($i in 1..3) {$i} +PS> set-psdebug -step; foreach ($i in 1..3) {$i} DEBUG: 1+ Set-PsDebug -step; foreach ($i in 1..3) {$i} Continue with this operation? @@ -63,27 +72,33 @@ DEBUG: 1+ Set-PsDebug -step; foreach ($i in 1..3) {$i} This command turns on stepping and then runs a script that displays the numbers 1, 2, and 3. + ### Example 3 + ``` -PS C:\> set-psdebug -off; foreach ($i in 1..3) {$i} +PS> set-psdebug -off; foreach ($i in 1..3) {$i} 1 2 3 ``` This command turns off all debugging features, and then runs a script that displays the numbers 1, 2, and 3. + ### Example 4 + ``` -PS C:\> set-psdebug -strict; $NewVar +PS> set-psdebug -strict; $NewVar The variable $NewVar cannot be retrieved because it has not been set yet. At line:1 char:28 + Set-PsDebug -strict;$NewVar <<<< ``` This command puts the interpreter in strict mode, and attempts to access a variable that has not yet been set. + ## PARAMETERS ### -Off + Turns off all script debugging features. Note: A "set-strictmode -off" command disables the verification set by a "set-psdebug -strict" command. @@ -102,6 +117,7 @@ Accept wildcard characters: False ``` ### -Step + Turns on script stepping. Before each line is run, the user is prompted to stop, continue, or enter a new interpreter level to inspect the state of the script. @@ -120,6 +136,7 @@ Accept wildcard characters: False ``` ### -Strict + Specifies that the interpreter should throw an exception if a variable is referenced before a value is assigned to the variable. Note: A "set-strictmode -off" command disables the verification set by a "set-psdebug -strict" command. @@ -138,6 +155,7 @@ Accept wildcard characters: False ``` ### -Trace + Specifies the trace level: 0 - Turn script tracing off @@ -159,15 +177,21 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### None + This cmdlet does not return any output. + ## NOTES ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Core/Set-PSSessionConfiguration.md b/reference/3.0/Microsoft.PowerShell.Core/Set-PSSessionConfiguration.md index 1120a10e2108..deec20b051e2 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Set-PSSessionConfiguration.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Set-PSSessionConfiguration.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=144307 external help file: System.Management.Automation.dll-Help.xml title: Set-PSSessionConfiguration --- - # Set-PSSessionConfiguration + ## SYNOPSIS + Changes the properties of a registered session configuration. + ## SYNTAX ### NameParameterSet (Default) + ``` Set-PSSessionConfiguration [-Name] [-ApplicationBase ] [-RunAsCredential ] [-ThreadApartmentState ] [-ThreadOptions ] @@ -25,6 +28,7 @@ Set-PSSessionConfiguration [-Name] [-ApplicationBase ] [-RunAsC ``` ### AssemblyNameParameterSet + ``` Set-PSSessionConfiguration [-Name] [-AssemblyName] [-ApplicationBase ] [-ConfigurationTypeName] [-RunAsCredential ] [-ThreadApartmentState ] @@ -36,6 +40,7 @@ Set-PSSessionConfiguration [-Name] [-AssemblyName] [-Applicati ``` ### SessionConfigurationFile + ``` Set-PSSessionConfiguration [-Name] [-RunAsCredential ] [-ThreadApartmentState ] [-ThreadOptions ] @@ -46,6 +51,7 @@ Set-PSSessionConfiguration [-Name] [-RunAsCredential ] ``` ## DESCRIPTION + The **Set-PSSessionConfiguration** cmdlet changes the properties of the session configurations on the local computer. Use the **Name** parameter to identify the session configuration that you want to change. @@ -66,31 +72,37 @@ For more information about session configurations, see about_Session_Configurati To see the properties of a session configuration, use the **Get-PSSessionConfiguration** cmdlet or the WSMan Provider. For more information about the WSMan Provider, type "Get-Help WSMan". + ## EXAMPLES ### Example 1 + ``` -PS C:\> Set-PSSessionConfiguration -Name MaintenanceShell -ThreadApartmentState STA +PS> Set-PSSessionConfiguration -Name MaintenanceShell -ThreadApartmentState STA ``` This command changes the thread apartment state in the MaintenanceShell configuration to STA. The change is effective when you restart the WinRM service. + ### Example 2 + ``` The first command uses the Register-PSSessionConfiguration cmdlet to create the AdminShell configuration. -PS C:\> Register-PSSessionConfiguration -name AdminShell -AssemblyName C:\Shells\AdminShell.dll -ConfigurationType AdminClass +PS> Register-PSSessionConfiguration -name AdminShell -AssemblyName C:\Shells\AdminShell.dll -ConfigurationType AdminClass The second command uses the **Set-PSSessionConfiguration** cmdlet to add the AdminConfig.ps1 script to the configuration. The change is effective when you restart WinRM. -PS C:\> Set-PSSessionConfiguration -Name AdminShell -StartupScript AdminConfig.ps1 +PS> Set-PSSessionConfiguration -Name AdminShell -StartupScript AdminConfig.ps1 The third command removes the AdminConfig.ps1 script from the configuration. It uses the **Set-PSSessionConfiguration** cmdlet with a value of $null for the **StartupScript** parameter. -PS C:\> Set-PSSessionConfiguration -Name AdminShell -StartupScript $null +PS> Set-PSSessionConfiguration -Name AdminShell -StartupScript $null ``` This example shows how to create and then change a session configuration. + ### Example 3 + ``` -PS C:\> Set-PSSessionConfiguration -name IncObj -MaximumReceivedObjectSizeMB 20 +PS> Set-PSSessionConfiguration -name IncObj -MaximumReceivedObjectSizeMB 20 WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\IncObj\InitializationParameters ParamName ParamValue @@ -109,10 +121,12 @@ The **Set-PSSessionConfiguration** command returns a **Microsoft.WSMan.Managemen It also prompts you to restart the WinRM service. The **Set-PSSessionConfiguration** change is not effective until the WinRM service is restarted. + ### Example 4 + ``` The first command uses the **Set-PSSessionConfiguration** cmdlet to change the startup script in the MaintenanceShell session configuration to Maintenance.ps1. The output of this command shows the change and prompts you to restart the WinRM service. The response is "y" (yes). -PS C:\> Set-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 +PS> Set-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell\InitializationParameters ParamName ParamValue @@ -126,7 +140,7 @@ the command "restart-service winrm"? The second command uses the Get-PSSessionConfiguration cmdlet to get the MaintenanceShell session configuration. The command uses a pipeline operator (|) to send the results of the command to the Format-List cmdlet, which displays all of the properties of the session configuration object in a list. -PS C:\> Get-PSSessionConfiguration MaintenanceShell | Format-List -Property * +PS> Get-PSSessionConfiguration MaintenanceShell | Format-List -Property * xmlns : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration Name : MaintenanceShell Filename : %windir%\system32\pwrshplugin.dll @@ -142,7 +156,7 @@ Capability : {Shell} Permission : The third command uses the WSMan provider to view the initialization parameters for the MaintenanceShell configuration. The command uses the Get-ChildItem cmdlet (alias = dir) to get the child items in the **InitializationParameters** node for the MaintenanceShell plug-in.For more information about the WSMan provider, type "get-help wsman". -PS C:\> dir WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters +PS> dir WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters ParamName ParamValue --------- ---------- PSVersion 2.0 @@ -150,9 +164,11 @@ startupscript c:\ps-test\Maintenance.ps1 ``` This example shows different ways of viewing the results of a **Set-PSSessionConfiguration** command. + ## PARAMETERS ### -ApplicationBase + Specifies the path to the assembly file (*.dll) that is specified in the value of the **AssemblyName** parameter. ```yaml @@ -168,6 +184,7 @@ Accept wildcard characters: False ``` ### -AssemblyName + Creates a session configuration based on a class that is defined in an assembly. Enter the path (optional) and file name of an assembly (a .dll file) that defines a session configuration. @@ -186,6 +203,7 @@ Accept wildcard characters: False ``` ### -ConfigurationTypeName + Specifies the type of the session configuration that is defined in the assembly in the **AssemblyName** parameter. The type that you specify must implement the System.Management.Automation.Remoting.PSSessionConfiguration class. @@ -204,6 +222,7 @@ Accept wildcard characters: False ``` ### -Force + Suppresses all user prompts, and restarts the WinRM service without prompting. Restarting the service makes the configuration change effective. @@ -222,6 +241,7 @@ Accept wildcard characters: False ``` ### -MaximumReceivedDataSizePerCommandMB + Changes the limit on the amount of data that can be sent to this computer in any single remote command. Enter the data size in megabytes (MB). The default is 50 MB. @@ -241,6 +261,7 @@ Accept wildcard characters: False ``` ### -MaximumReceivedObjectSizeMB + Changes the limits on the amount of data that can be sent to this computer in any single object. Enter the data size in megabytes (MB). The default is 10 MB. @@ -260,6 +281,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the session configuration that you want to change. You cannot use this parameter to change the name of the session configuration. @@ -277,6 +299,7 @@ Accept wildcard characters: False ``` ### -NoServiceRestart + Does not restart the WinRM service, and suppresses the prompt to restart the service. By default, when you enter a Set-PSSessionConfiguration command, you are prompted to restart the WinRM service to make the new session configuration effective. @@ -298,6 +321,7 @@ Accept wildcard characters: False ``` ### -PSVersion + Specifies the version of Windows PowerShell in sessions that use this session configuration. The value of this parameter takes precedence over the value of the **PowerShellVersion** key in the session configuration file. @@ -317,6 +341,7 @@ Accept wildcard characters: False ``` ### -RunAsCredential + Runs commands in the session with the permissions of the specified user. By default, commands run with the permissions of the current user. @@ -335,6 +360,7 @@ Accept wildcard characters: False ``` ### -SecurityDescriptorSddl + Specifies a different Security Descriptor Definition Language (SDDL) string for the configuration. This string determines the permissions that are required to use the new session configuration. @@ -359,6 +385,7 @@ Accept wildcard characters: False ``` ### -ShowSecurityDescriptorUI + Displays a property sheet that helps you to create a new SDDL for the session configuration. The property sheet appears after you enter the Set-PSSessionConfiguration command and then restart the WinRM service. @@ -379,6 +406,7 @@ Accept wildcard characters: False ``` ### -StartupScript + Adds or changes the startup script for the configuration. Enter the fully qualified path to a Windows PowerShell script. The specified script runs in the new session that uses the session configuration. @@ -401,6 +429,7 @@ Accept wildcard characters: False ``` ### -ThreadApartmentState + Changes the apartment state setting for the threads in the session. Valid values are STA, MTA and Unknown. Unknown is the default. @@ -418,6 +447,7 @@ Accept wildcard characters: False ``` ### -ThreadOptions + Changes the thread options setting in the configuration. This setting defines how threads are created and used when a command is executed in the session. Valid values are **Default**, **ReuseThread**, **UseCurrentThread**, and **UseNewThread**. @@ -438,6 +468,7 @@ Accept wildcard characters: False ``` ### -UseSharedProcess + Use only one process to host all sessions that are started by the same user and use the same session configuration. By default, each session is hosted in its own process. @@ -456,6 +487,7 @@ Accept wildcard characters: False ``` ### -AccessMode + Enables and disables the session configuration and determines whether it can be used for remote or local sessions on the computer. **Remote** is the default. @@ -483,6 +515,7 @@ Accept wildcard characters: False ``` ### -SessionTypeOption + Sets type-specific options for the session configuration. Enter a session type options object, such as the **PSWorkflowExecutionOption** object that the New-PSWorkflowExecutionOption cmdlet returns. @@ -505,6 +538,7 @@ Accept wildcard characters: False ``` ### -TransportOption + Sets transport options for the session configuration. Enter a transport options object, such as the **WSManConfigurationOption** object that the New-PSTransportOption cmdlet returns. @@ -527,6 +561,7 @@ Accept wildcard characters: False ``` ### -Path + Adds or replaces a session configuration file (.pssc), such as one created by the New-PSSessionConfigurationFile cmdlet. If you omit the path, the default is the current directory. @@ -547,6 +582,7 @@ Accept wildcard characters: False ``` ### -ModulesToImport + Specifies the modules and snap-ins that are automatically imported into sessions that use the session configuration. Enter the module and snap-in names. @@ -572,6 +608,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -587,6 +624,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -603,21 +641,27 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### Microsoft.WSMan.Management.WSManConfigLeafElement ## NOTES -* To run this cmdlet, start Windows PowerShell with the "Run as administrator" option. -* The **Set-PSSessionConfiguration** cmdlet does not change the configuration name and the WSMan provider does not support the Rename-Item cmdlet. To change the name of a session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the configuration and then use the Register-PSSessionConfiguration cmdlet to create and register a new session configuration. -* You can use the **Set-PSSessionConfiguration** cmdlet to change the default Microsoft.PowerShell and Microsoft.PowerShell32 session configurations. They are not protected. To revert to the original version of a default session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the default session configuration and then use the Enable-PSRemoting cmdlet to restore it. -* 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. -* You can use commands in the WSMan: drive to change the properties of session configurations. However, you cannot use the WSMan: drive in Windows PowerShell 2.0 to change session configuration properties that are introduced in Windows PowerShell 3.0, such as **OutputBufferingMode**. Windows PowerShell 2.0 commands do not generate an error, but they are ineffective. To change properties introduced in Windows PowerShell 3.0, use the WSMan: drive in Windows PowerShell 3.0. + +- To run this cmdlet, start Windows PowerShell with the "Run as administrator" option. +- The **Set-PSSessionConfiguration** cmdlet does not change the configuration name and the WSMan provider does not support the Rename-Item cmdlet. To change the name of a session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the configuration and then use the Register-PSSessionConfiguration cmdlet to create and register a new session configuration. +- You can use the **Set-PSSessionConfiguration** cmdlet to change the default Microsoft.PowerShell and Microsoft.PowerShell32 session configurations. They are not protected. To revert to the original version of a default session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the default session configuration and then use the Enable-PSRemoting cmdlet to restore it. +- 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. +- You can use commands in the WSMan: drive to change the properties of session configurations. However, you cannot use the WSMan: drive in Windows PowerShell 2.0 to change session configuration properties that are introduced in Windows PowerShell 3.0, such as **OutputBufferingMode**. Windows PowerShell 2.0 commands do not generate an error, but they are ineffective. To change properties introduced in Windows PowerShell 3.0, use the WSMan: drive in Windows PowerShell 3.0. + ## RELATED LINKS [Disable-PSSessionConfiguration](Disable-PSSessionConfiguration.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Set-StrictMode.md b/reference/3.0/Microsoft.PowerShell.Core/Set-StrictMode.md index 225f1022f915..997177f45f3d 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Set-StrictMode.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Set-StrictMode.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,23 +7,28 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113450 external help file: System.Management.Automation.dll-Help.xml title: Set-StrictMode --- - # Set-StrictMode + ## SYNOPSIS + Establishes and enforces coding rules in expressions, scripts, and script blocks. + ## SYNTAX ### Version (Default) + ``` Set-StrictMode -Version [] ``` ### Off + ``` Set-StrictMode [-Off] [] ``` ## DESCRIPTION + The Set-StrictMode cmdlet configures strict mode for the current scope (and all child scopes) and turns it on and off. When strict mode is on, Windows PowerShell generates a terminating error when the content of an expression, script, or script block violates basic best-practice coding rules. @@ -34,12 +39,14 @@ Unlike the Set-PSDebug cmdlet, Set-StrictMode affects only the current scope and When Set-StrictMode is off, uninitialized variables (Version 1) are assumed to have a value of 0 (zero) or $null, depending on type. References to non-existent properties return $null, and the results of function syntax that is not valid vary with the error. Unnamed variables are not permitted. + ## EXAMPLES ### Example 1 + ``` -PS C:\> set-strictmode -version 1.0 -PS C:\> $a -gt 5 +PS> set-strictmode -version 1.0 +PS> $a -gt 5 False The variable $a cannot be retrieved because it has not been set yet. At line:1 char:3 @@ -52,19 +59,21 @@ This command turns strict mode on and sets it to version 1.0. As a result, attempts to reference variables that are not initialized will fail. The sample output shows the effect of version 1.0 strict mode. + ### Example 2 + ``` -PS C:\> # set-strictmode -version 2.0 +PS> # set-strictmode -version 2.0 # Strict mode is off by default. -PS C:\> function add ($a, $b) {$a + $b} -PS C:\> add 3 4 +PS> function add ($a, $b) {$a + $b} +PS> add 3 4 7 -PS C:\> add(3,4) +PS> add(3,4) 3 4 -PS C:\> set-strictmode -version 2.0 -PS C:\> add(3,4) +PS> set-strictmode -version 2.0 +PS> add(3,4) The function or command was called like a method. Parameters should be separated by spaces, as described in 'Get-Help about_Parameter.' At line:1 char:4 @@ -72,13 +81,13 @@ At line:1 char:4 + CategoryInfo : InvalidOperation: (:) [], RuntimeException + FullyQualifiedErrorId : StrictModeFunctionCallWithParens -PS C:\> set-strictmode -off -PS C:\> $string = "This is a string." -PS C:\> $string.Month -PS C:\> -PS C:\> set-strictmode -version 2.0 -PS C:\> $string = "This is a string." -PS C:\> $string.Month +PS> set-strictmode -off +PS> $string = "This is a string." +PS> $string.Month +PS> +PS> set-strictmode -version 2.0 +PS> $string = "This is a string." +PS> $string.Month Property 'month' cannot be found on this object; make sure it exists. At line:1 char:9 @@ -97,9 +106,11 @@ With version 2.0 strict mode, it is correctly interpreted as faulty syntax for s Without version 2.0, the reference to the non-existent Month property of a string returns only null. With version 2.0, it is interpreted correctly as a reference error. + ## PARAMETERS ### -Off + Turns strict mode off. This parameter also turns off "Set-PSDebug -Strict". @@ -116,6 +127,7 @@ Accept wildcard characters: False ``` ### -Version + Specifies the conditions that cause an error in strict mode. This parameter is required. @@ -150,19 +162,27 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### None + This cmdlet does not return any output. + ## NOTES -* Set-StrictMode is similar to the Strict parameter of Set-PSDebug. "Set-Strictmode -version 1" is equivalent to "Set-PSDebug -strict", except that Set-PSDebug is effective in all scopes. Set-StrictMode is effective only in the scope in which it is set and in its child scopes. For more information about scopes in Windows PowerShell, see about_Scopes. -* +- Set-StrictMode is similar to the Strict parameter of Set-PSDebug. "Set-Strictmode -version 1" is equivalent to "Set-PSDebug -strict", except that Set-PSDebug is effective in all scopes. Set-StrictMode is effective only in the scope in which it is set and in its child scopes. For more information about scopes in Windows PowerShell, see about_Scopes. + +- + ## RELATED LINKS [Set-PSDebug](Set-PSDebug.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md b/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md index 337ef4ff4986..89fece00add3 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113405 external help file: System.Management.Automation.dll-Help.xml title: Start-Job --- - # Start-Job + ## SYNOPSIS + Starts a Windows PowerShell background job. + ## SYNTAX ### ComputerName (Default) + ``` Start-Job [-Name ] [-ScriptBlock] [-Credential ] [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -21,11 +24,13 @@ Start-Job [-Name ] [-ScriptBlock] [-Credential [[-DefinitionPath] ] [[-Type] ] [] ``` ### LiteralFilePathComputerName + ``` Start-Job [-Name ] [-Credential ] -LiteralPath [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -33,6 +38,7 @@ Start-Job [-Name ] [-Credential ] -LiteralPath ``` ### FilePathComputerName + ``` Start-Job [-Name ] [-Credential ] [-FilePath] [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -40,6 +46,7 @@ Start-Job [-Name ] [-Credential ] [-FilePath] ``` ## DESCRIPTION + The **Start-Job** cmdlet starts a Windows PowerShell background job on the local computer. A Windows PowerShell background job runs a command "in the background" without interacting with the current session. @@ -55,11 +62,13 @@ For more information, see about_Remote_Jobs. Beginning in Windows PowerShell 3.0, **Start-Job** can start instances of custom job types, such as scheduled jobs. For information about using **Start-Job** to start jobs with custom types, see the help topics for the job type feature. + ## EXAMPLES ### Example 1 + ``` -PS C:\> start-job -scriptblock {get-process} +PS> start-job -scriptblock {get-process} Id Name State HasMoreData Location Command --- ---- ----- ----------- -------- ------- @@ -69,9 +78,11 @@ Id Name State HasMoreData Location Command This command starts a background job that runs a Get-Process command. The command returns a job object with information about the job. The command prompt returns immediately so that you can work in the session while the job runs in the background. + ### Example 2 + ``` -PS C:\> $jobWRM = invoke-command -computerName (get-content servers.txt) -scriptblock {get-service winrm} -jobname WinRM -throttlelimit 16 -AsJob +PS> $jobWRM = invoke-command -computerName (get-content servers.txt) -scriptblock {get-service winrm} -jobname WinRM -throttlelimit 16 -AsJob ``` This command uses the Invoke-Command cmdlet and its AsJob parameter to start a background job that runs a "get-service winrm" command on numerous computers. @@ -81,10 +92,12 @@ The command uses the ComputerName parameter to specify the computers on which th The value of the ComputerName parameter is a Get-Content command that gets the text in the Servers.txt file, a file of computer names in a domain. The command uses the ScriptBlock parameter to specify the command and the JobName parameter to specify a friendly name for the job. + ### Example 3 + ``` -PS C:\> $j = start-job -scriptblock {get-eventlog -log system} -credential domain01\user01 -PS C:\> $j | format-list -property * +PS> $j = start-job -scriptblock {get-eventlog -log system} -credential domain01\user01 +PS> $j | format-list -property * HasMoreData : True StatusMessage : @@ -104,10 +117,10 @@ Debug : {} Warning : {} StateChanged : -PS C:\> $j.JobStateInfo.state +PS> $j.JobStateInfo.state Completed -PS C:\> $results = receive-job -job $j -PS C:\> $results +PS> $results = receive-job -job $j +PS> $results Index Time Type Source EventID Message ----- ---- ---- ------ ------- ------- @@ -136,31 +149,39 @@ The fourth command uses the Receive-Job cmdlet to get the results of the job. It stores the results in the $results variable. The final command displays the contents of the $results variable. + ### Example 4 + ``` -PS C:\> start-job -filepath c:\scripts\sample.ps1 +PS> start-job -filepath c:\scripts\sample.ps1 ``` This command runs the Sample.ps1 script as a background job. + ### Example 5 + ``` -PS C:\> start-job -name WinRm -scriptblock {get-process winrm} +PS> start-job -name WinRm -scriptblock {get-process winrm} ``` This command runs a background job that gets the WinRM process on the local computer. The command uses the ScriptBlock parameter to specify the command that runs in the background job. It uses the Name parameter to specify a friendly name for the new job. + ### Example 6 + ``` -PS C:\> start-job -name GetMappingFiles -initializationScript {import-module MapFunctions} -scriptblock {Get-Map -name * | set-content D:\Maps.tif} -runAs32 +PS> start-job -name GetMappingFiles -initializationScript {import-module MapFunctions} -scriptblock {Get-Map -name * | set-content D:\Maps.tif} -runAs32 ``` This command starts a job that collects a large amount of data and saves it in a .tif file. The command uses the InitializationScript parameter to run a script block that imports a required module. It also uses the RunAs32 parameter to run the job in a 32-bit process even if the computer has a 64-bit operating system. + ## PARAMETERS ### -ArgumentList + Specifies the arguments (parameter values) for the script that is specified by the **FilePath** parameter. Because all of the values that follow the ArgumentList parameter name are interpreted as being values of ArgumentList, the ArgumentList parameter should be the last parameter in the command. @@ -178,6 +199,7 @@ Accept wildcard characters: False ``` ### -Authentication + Specifies the mechanism that is used to authenticate the user's credentials. Valid values are **Default**, **Basic**, **Credssp**, **Digest**, **Kerberos**, **Negotiate**, and **NegotiateWithImplicitCredential**. The default value is **Default**. @@ -203,6 +225,7 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. @@ -221,6 +244,7 @@ Accept wildcard characters: False ``` ### -FilePath + Runs the specified local script as a background job. Enter the path and file name of the script or pipe a script path to **Start-Job**. The script must reside on the local computer or in a directory that the local computer can access. @@ -240,6 +264,7 @@ Accept wildcard characters: False ``` ### -InitializationScript + Specifies commands that run before the job starts. Enclose the commands in braces ( { } ) to create a script block. @@ -259,6 +284,7 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies input to the command. Enter a variable that contains the objects, or type a command or expression that generates the objects. @@ -277,6 +303,7 @@ Accept wildcard characters: False ``` ### -LiteralPath + Runs the specified local script as a background job. Enter the path to a script on the local computer. @@ -298,6 +325,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies a friendly name for the new job. You can use the name to identify the job to other job cmdlets, such as Stop-Job. @@ -316,6 +344,7 @@ Accept wildcard characters: False ``` ### -PSVersion + Runs the job with the specified version of Windows PowerShell. Valid values are 2.0 and 3.0. @@ -334,6 +363,7 @@ Accept wildcard characters: False ``` ### -RunAs32 + Runs the job in a 32-bit process. Use this parameter to force the job to run in a 32-bit process on a 64-bit operating system. @@ -352,6 +382,7 @@ Accept wildcard characters: False ``` ### -ScriptBlock + Specifies the commands to run in the background job. Enclose the commands in braces ( { } ) to create a script block. This parameter is required. @@ -369,6 +400,7 @@ Accept wildcard characters: False ``` ### -DefinitionName + Starts the job with the specified job definition name. Use this parameter to start custom job types that have a definition name, such as scheduled jobs. @@ -392,6 +424,7 @@ Accept wildcard characters: False ``` ### -DefinitionPath + Starts the job at the specified path location. Enter the definition path. The concatenation of the values of the **DefinitionPath** and **DefinitionName** parameters should be the fully-qualified path to the job definition. @@ -414,6 +447,7 @@ Accept wildcard characters: False ``` ### -Type + Starts only jobs of the specified custom type. Enter a custom job type name, such as PSScheduledJob for scheduled jobs or PSWorkflowJob for workflows jobs. This parameter is not valid for standard background jobs. @@ -433,20 +467,28 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.String + You can pipe an object with the Name property to the Name parameter. For example, you can pipe a FileInfo object from Get-ChildItem to **Start-Job**. + ## OUTPUTS ### System.Management.Automation.PSRemotingJob + **Start-Job** returns an object that represents the job that it started. + ## NOTES -* To run in the background, **Start-Job** runs in its own session within the current session. When you use the Invoke-Command cmdlet to run a **Start-Job** command in a session on a remote computer, **Start-Job** runs in a session within the remote session. -* +- To run in the background, **Start-Job** runs in its own session within the current session. When you use the Invoke-Command cmdlet to run a **Start-Job** command in a session on a remote computer, **Start-Job** runs in a session within the remote session. + +- + ## RELATED LINKS [Get-Job](Get-Job.md) From b450b4d79900a3f65813015329d0f7112bced81d Mon Sep 17 00:00:00 2001 From: Bobby Reed Date: Mon, 30 Apr 2018 07:23:49 -0700 Subject: [PATCH 6/6] Batch automation: Formatting fixes (#2377) * Batch automation: Formatting fixes * Fixing two broken links that were broken by my code --- .../about_Functions_Advanced_Parameters.md | 15 +++-- .../about_Functions_CmdletBindingAttribute.md | 3 +- .../about_Functions_OutputTypeAttribute.md | 9 ++- .../About/about_Group_Policy_Settings.md | 7 +-- .../About/about_Hash_Tables.md | 59 +++++++++---------- .../About/about_History.md | 3 +- .../About/about_If.md | 5 +- .../About/about_Job_Details.md | 41 ++++++------- .../About/about_Jobs.md | 19 +++--- .../About/about_Join.md | 3 +- .../About/about_Language_Modes.md | 7 +-- .../About/about_Line_Editing.md | 5 +- .../About/about_locations.md | 3 +- .../About/about_logical_operators.md | 3 +- 14 files changed, 87 insertions(+), 95 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index 845df5ff8a24..21a65d4ae5d3 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Functions_Advanced_Parameters --- - # About Functions Advanced Parameters # SHORT DESCRIPTION @@ -514,7 +513,7 @@ greater than or equal to the current date. Param ( [parameter()] - [ValidateScript({$_ -ge (get-date)})] + [ValidateScript({$_ -ge (Get-Date)})] [DateTime] $EventDate ) @@ -524,7 +523,7 @@ In the following example, the value of the variable $date must be greater than or equal to the current date and time. ```powershell -[DateTime][ValidateScript({$_ -ge (get-date)})]$date = (get-date) +[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date) ``` ## ValidateSet Attribute @@ -660,19 +659,19 @@ function Get-Sample { { if ($path -match ".HKLM.:") { - $attributes = new-object -Type ` + $attributes = New-Object -Type ` System.Management.Automation.ParameterAttribute $attributes.ParameterSetName = "__AllParameterSets" $attributes.Mandatory = $false - $attributeCollection = new-object ` + $attributeCollection = New-Object ` -Type System.Collections.ObjectModel.Collection[System.Attribute] $attributeCollection.Add($attributes) - $dynParam1 = new-object -Type ` + $dynParam1 = New-Object -Type ` System.Management.Automation.RuntimeDefinedParameter("dp1", [Int32], $attributeCollection) - $paramDictionary = new-object ` + $paramDictionary = New-Object ` -Type System.Management.Automation.RuntimeDefinedParameterDictionary $paramDictionary.Add("dp1", $dynParam1) return $paramDictionary diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md index bd92c36dbcde..0d5ff885c073 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_CmdletBindingAttribute.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Functions_CmdletBindingAttribute --- - # About Functions CmdletBindingAttribute # SHORT DESCRIPTION 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 0c5b2f4167dc..37fe01117e30 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,11 +1,10 @@ ---- +--- ms.date: 01/03/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Functions_OutputTypeAttribute --- - # About Functions OutputTypeAttribute ## SHORT DESCRIPTION @@ -121,7 +120,7 @@ function Send-Greeting To see the resulting output type property, use the Get-Command cmdlet. ``` -PS C:> (Get-Command Send-Greeting).OutputType +PS> (Get-Command Send-Greeting).OutputType Name Type ---- ---- @@ -178,7 +177,7 @@ function Get-Time The Get-Type method confirms that the function returns a string. ``` -PS C:> (Get-Time -DateTime (Get-Date)).Gettype().FullName +PS> (Get-Time -DateTime (Get-Date)).Gettype().FullName System.String ``` @@ -186,7 +185,7 @@ 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 +PS> (Get-Command Get-Time).OutputType Name Type ---- ---- diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md index c633b6716af8..0d2920f82884 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Group_Policy_Settings.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Group_Policy_Settings --- - # About Group Policy Settings # SHORT DESCRIPTION @@ -101,8 +100,8 @@ The module must be imported into the session and the setting is effective only in the current session. ```powershell -PS C:> Import-Module -PS C:> (Get-Module ).LogPipelineExecutionDetails = $true +PS> Import-Module +PS> (Get-Module ).LogPipelineExecutionDetails = $true ``` To turn on module logging for all sessions on a particular computer, 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 816b8aefe372..b1f9775991d6 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 @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Hash_Tables --- - # About Hash Tables ## SHORT DESCRIPTION @@ -109,7 +108,7 @@ place the ordered attribute before the variable name, the command fails with the following error message. ```powershell -PS C:\> [ordered]$hash = @{} +PS> [ordered]$hash = @{} At line:1 char:1 + [ordered]$hash = @{} + [!INCLUDE[]()] @@ -122,7 +121,7 @@ eption To correct the expression, move the [ordered] attribute. ```powershell -PS C:\> $hash = [ordered]@{} +PS> $hash = [ordered]@{} ``` You can cast an ordered dictionary to a hash table, but you cannot recover the @@ -130,9 +129,9 @@ ordered attribute, even if you clear the variable and enter new values. To re-establish the order, you must remove and recreate the variable. ``` -PS C:\> [hashtable]$hash = [ordered]@{ +PS> [hashtable]$hash = [ordered]@{ >> Number = 1; Shape = "Square"; Color = "Blue"} -PS C:\> $hash +PS> $hash Name Value ---- ----- @@ -148,7 +147,7 @@ By default, a hash tables is displayed as a table with one column for keys and one for values. ```powershell -C:\PS> $hash +PS> $hash Name Value ---- ----- @@ -161,12 +160,12 @@ Hash tables have Keys and Values properties. Use dot notation to display all of the keys or all of the values. ```powershell -C:\PS> $hash.keys +PS> $hash.keys Number Shape Color -C:\PS> $hash.values +PS> $hash.values 1 Square Blue @@ -184,10 +183,10 @@ $hashtable. For example: ```powershell -C:\PS> $hash.Number +PS> $hash.Number 1 -C:\PS> $hash.Color +PS> $hash.Color Blue ``` @@ -203,7 +202,7 @@ Hash tables have a Count property that indicates the number of key-value pairs in the hash table. ```powershell -C:\PS> $hash.count +PS> $hash.count 3 ``` @@ -214,7 +213,7 @@ If the key is a string value, enclose the key name in quotation marks. For example: ```powershell -C:\PS> $hash["Number"] +PS> $hash["Number"] 1 ``` @@ -296,28 +295,28 @@ The following statement creates a hash table of process name strings and process object values and saves it in the \$p variable. ```powershell -$p = @{"PowerShell" = (get-process PowerShell); -"Notepad" = (get-process notepad)} +$p = @{"PowerShell" = (Get-Process PowerShell); +"Notepad" = (Get-Process notepad)} ``` You can display the hash table in \$p and use the key-name properties to display the values. ```powershell -C:\PS> $p +PS> $p Name Value ---- ----- PowerShell System.Diagnostics.Process (PowerShell) Notepad System.Diagnostics.Process (notepad) -C:\PS> $p.PowerShell +PS> $p.PowerShell Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 441 24 54196 54012 571 5.10 1788 PowerShell -C:\PS> $p.keys | foreach {$p.$_.handles} +PS> $p.keys | ForEach-Object {$p.$_.handles} 441 251 ``` @@ -328,14 +327,14 @@ Service object that represents the WinRM service, and the value is the current status of the service. ```powershell -C:\PS> $p = $p + @{(Get-Service WinRM) = ((Get-Service WinRM).Status)} +PS> $p = $p + @{(Get-Service WinRM) = ((Get-Service WinRM).Status)} ``` You can display and access the new key/value pair by using the same methods that you use for other pairs in the hash table. ```powershell -C:\PS> $p +PS> $p Name Value ---- ----- @@ -343,7 +342,7 @@ PowerShell System.Diagnostics.Process (PowerShell) Notepad System.Diagnostics.Process (notepad) System.ServiceProcess.Servi... Running -C:\PS> $p.keys +PS> $p.keys PowerShell Notepad @@ -351,7 +350,7 @@ Status Name DisplayName ------ ---- ----------- Running winrm Windows Remote Management (WS-Manag... -C:\PS> $p.keys | foreach {$_.name} +PS> $p.keys | ForEach-Object {$_.name} winrm ``` @@ -361,13 +360,13 @@ in which the key is a string, Hash2, and the value is a hash table with three key/value pairs. ```powershell -C:\PS> $p = $p + @{"Hash2"= @{a=1; b=2; c=3}} +PS> $p = $p + @{"Hash2"= @{a=1; b=2; c=3}} ``` You can display and access the new values by using the same methods. ```powershell -C:\PS> $p +PS> $p Name Value ---- ----- @@ -376,7 +375,7 @@ Notepad System.Diagnostics.Process (notepad) System.ServiceProcess.Servi... Running Hash2 {a, b, c} -C:\PS> $p.Hash2 +PS> $p.Hash2 Name Value ---- ----- @@ -384,7 +383,7 @@ a 1 b 2 c 3 -C:\PS> $p.Hash2.b +PS> $p.Hash2.b 2 ``` @@ -401,7 +400,7 @@ For example, the following commands enumerate the keys and values in the hash table in the \$p variable and then sort the keys in alphabetical order. ```powershell -C:\PS> $p.GetEnumerator() | Sort-Object -Property key +PS> $p.GetEnumerator() | Sort-Object -Property key Name Value ---- ----- @@ -414,7 +413,7 @@ The following command uses the same procedure to sort the hash values in descending order. ```powershell -C:\PS> $p.getenumerator() | Sort-Object -Property Value -Descending +PS> $p.getenumerator() | Sort-Object -Property Value -Descending Name Value ---- ----- @@ -463,7 +462,7 @@ The following command creates a here-string of the key/value pairs and then saves it in the \$string variable. ```powershell -C:\PS> $string = @" +PS> $string = @" Msg1 = Type "Windows". Msg2 = She said, "Hello, World." Msg3 = Enter an alias (or "nickname"). @@ -474,7 +473,7 @@ This command uses the ConvertFrom-StringData cmdlet to convert the here-string into a hash table. ```powershell -C:\PS> ConvertFrom-StringData $string +PS> ConvertFrom-StringData $string Name Value ---- ----- 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 eca45af0808f..e814fad1adce 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_History.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_History.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_History --- - # About History ## Short Description diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_If.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_If.md index 09c512a0672c..bcd90c6b3698 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_If.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_If.md @@ -1,18 +1,19 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_If --- - # About If ## SHORT DESCRIPTION + Describes a language command you can use to run statement lists based on the results of one or more conditional tests. ## LONG DESCRIPTION + You can use the If statement to run code blocks if a specified conditional test evaluates to true. You can also specify one or more additional conditional tests to run if all the prior tests evaluate to false. Finally, diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md index 1eaf4b1779ec..a7328b50a552 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Job_Details.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/28/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Job_Details --- - # About Job Details # SHORT DESCRIPTION @@ -93,7 +92,7 @@ parameter of the Get-Job cmdlet. The IncludeChildJob parameter is introduced in Windows PowerShell 3.0. ```powershell -C:\PS> Get-Job -IncludeChildJob +PS> Get-Job -IncludeChildJob Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -107,7 +106,7 @@ value, use the ChildJobState parameter of the Get-Job cmdlet. The ChildJobState parameter is introduced in Windows PowerShell 3.0. ```powershell -C:\PS> Get-Job -ChildJobState Failed +PS> Get-Job -ChildJobState Failed Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -119,7 +118,7 @@ To get the child jobs of a job on all versions of Windows PowerShell, use the ChildJob property of the parent job. ```powershell -C:\PS> (Get-Job Job1).ChildJobs +PS> (Get-Job Job1).ChildJobs Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -131,7 +130,7 @@ You can also use a Get-Job command on the child job, as shown in the following command: ```powershell -C:\PS> Get-Job Job3 +PS> Get-Job Job3 Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -168,7 +167,7 @@ background jobs on the local computer and two remote computers. The command saves the job in the \$j variable. ```powershell -PS C:> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` +PS> $j = Invoke-Command -ComputerName localhost, Server01, Server02 ` -Command {Get-Date} -AsJob ``` @@ -177,7 +176,7 @@ shows that the command returned a job object with three child jobs, one for each computer. ```powershell -PS C:> $j | Format-List Name, ChildJobs +PS> $j | Format-List Name, ChildJobs Name : Job3 ChildJobs : {Job4, Job5, Job6} @@ -186,7 +185,7 @@ ChildJobs : {Job4, Job5, Job6} When you display the parent job, it shows that the job failed. ```powershell -C:\PS> $j +PS> $j Id Name PSJobTypeName State HasMoreData Location -- ---- ------------- ----- ----------- -------- @@ -197,7 +196,7 @@ But when you run a Get-Job command that gets the child jobs, the output shows that only one child job failed. ```powershell -PS C:> Get-Job -IncludeChildJobs +PS> Get-Job -IncludeChildJobs Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -212,9 +211,8 @@ the results of the parent job. But you can also get the results of a particular child job, as shown in the following command. ```powershell -C:\PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, ->> DateTime -Auto - +PS> Receive-Job -Name Job6 -Keep | Format-Table ComputerName, +>> DateTime -AutoSize ComputerName DateTime ------------ -------- Server02 Thursday, March 13, 2008 4:16:03 PM @@ -282,7 +280,7 @@ instances of the scheduled job. Start a background job on the local computer. ```powershell -PS C:> Start-Job -Name LocalData {Get-Process} +PS> Start-Job -Name LocalData {Get-Process} Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -292,7 +290,7 @@ Id Name PSJobTypeName State HasMoreData Location Command Start a background job that runs on a remote computer. ```powershell -PS C:> Invoke-Command -ComputerName Server01 {Get-Process} ` +PS> Invoke-Command -ComputerName Server01 {Get-Process} ` -AsJob -JobName RemoteData Id Name PSJobTypeName State HasMoreData Location Command @@ -301,8 +299,9 @@ Id Name PSJobTypeName State HasMoreData Location Command ``` Create a scheduled job + ```powershell -PS C:> Register-ScheduledJob -Name ScheduledJob -ScriptBlock ` +PS> Register-ScheduledJob -Name ScheduledJob -ScriptBlock ` {Get-Process} -Trigger (New-JobTrigger -Once -At "3 PM") Id Name JobTriggers Command Enabled @@ -311,14 +310,16 @@ Id Name JobTriggers Command Enabled ``` Create a workflow. + ```powershell -PS C:> workflow Test-Workflow {Get-Process} +PS> workflow Test-Workflow {Get-Process} ``` Run the workflow as a job. + ```powershell -PS C:> Test-Workflow -AsJob -JobName TestWFJob +PS> Test-Workflow -AsJob -JobName TestWFJob Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -329,7 +330,7 @@ Get the jobs. The `Get-Job` command does not get scheduled jobs, but it gets instances of the scheduled job that are started. ```powershell -PS C:> Get-Job +PS> Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -342,7 +343,7 @@ Id Name PSJobTypeName State HasMoreData Location Command To get scheduled jobs, use the Get-ScheduledJob cmdlet. ```powershell -PS C:> Get-ScheduledJob +PS> Get-ScheduledJob Id Name JobTriggers Command Enabled -- ---- ----------- ------- ------- diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Jobs.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Jobs.md index d177d9c081c1..8f88bb08cdec 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Jobs.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Jobs.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 11/29/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Jobs --- - # About Jobs ## SHORT DESCRIPTION @@ -81,7 +80,7 @@ returns all of the jobs that were started in the current session. For example, the following command gets the jobs in the current session. ```powershell -PS C:> Get-Job +PS> Get-Job Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -165,14 +164,14 @@ The following commands show the results of `Receive-Job` commands run before the job is complete. ```powershell -C:\PS> Receive-Job -Job $job +PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 103 4 11328 9692 56 1176 audiodg 804 14 12228 14108 100 101.74 1740 CcmExec -C:\PS> Receive-Job -Job $job +PS> Receive-Job -Job $job Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- @@ -190,14 +189,14 @@ The following commands show the effect of using the Keep parameter on a job that is not yet complete. ```powershell -C:\PS> Receive-Job -Job $job -Keep +PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 103 4 11328 9692 56 1176 audiodg 804 14 12228 14108 100 101.74 1740 CcmExec -C:\PS> Receive-Job -Job $job -Keep +PS> Receive-Job -Job $job -Keep Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- @@ -253,7 +252,7 @@ for any of the jobs to be completed. The following command uses the Wait-Job cmdlet to wait for a job with ID 10. ```powershell -Wait-Job -ID 10 +Wait-Job -Id 10 ``` As a result, the PowerShell prompt is suppressed until the job is completed. @@ -264,7 +263,7 @@ expires, the command prompt returns, but the job continues to run in the background. ```powershell -Wait-Job -ID 10 -Timeout 120 +Wait-Job -Id 10 -Timeout 120 ``` ## STOPPING A JOB @@ -274,7 +273,7 @@ starts a job to get every entry in the System event log. It saves the job object in the \$job variable. ```powershell -$job = Start-Job -ScriptBlock {Get-EventLog -Log System} +$job = Start-Job -ScriptBlock {Get-EventLog -LogName System} ``` The following command stops the job. It uses a pipeline operator (|) to diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Join.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Join.md index 134c02f7aeae..e0624b2a124c 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Join.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Join.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Join --- - # About join ## SHORT DESCRIPTION diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Language_Modes.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Language_Modes.md index 9e468e91097f..4b9a9f28974f 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Language_Modes.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Language_Modes.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Language_Modes --- - # About Language Modes ## SHORT DESCRIPTION @@ -198,7 +197,7 @@ the session configuration has a LanguageMode property. You can find the language mode by getting the value of the LanguageMode property. ```powershell -PS C:\> (Get-PSSessionConfiguration -Name Test).LanguageMode +PS> (Get-PSSessionConfiguration -Name Test).LanguageMode FullLanguage ``` @@ -215,7 +214,7 @@ state. For example: ```powershell -PS C:> $ExecutionContext.SessionState.LanguageMode +PS> $ExecutionContext.SessionState.LanguageMode ConstrainedLanguage ``` diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Line_Editing.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Line_Editing.md index 8c20f873f9cb..826d88140b78 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Line_Editing.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Line_Editing.md @@ -1,12 +1,12 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Line_Editing --- - # About Line Editing + ## about_Line_Editing @@ -35,6 +35,7 @@ To delete the character in front of the cursor, press the DELETE key. Delete the Remainder of a Line To delete all the characters in the line after the cursor, press + # CTRL+END. diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_locations.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_locations.md index 82f97c6de5b4..c0ee99bbcd73 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_locations.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_locations.md @@ -1,11 +1,10 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Locations --- - # about_Locations ## SHORT DESCRIPTION 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 b3ae17b9ddb5..47a7d8391f41 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,11 +1,10 @@ ---- +--- ms.date: 01/03/2018 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet title: about_Logical_Operators --- - # about_Logical_Operators ## SHORT DESCRIPTION