diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Properties.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Properties.md index 1029807cd83..f9bea619992 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Properties.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Properties.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,278 +7,304 @@ title: about_Properties --- # About Properties -## about_Properties - ## SHORT DESCRIPTION -Describes how to use object properties in Windows PowerShell®. +Describes how to use object properties in PowerShell. ## LONG DESCRIPTION -Windows PowerShell uses structured collections of information called objects to represent the items in data stores or the state of the computer. Typically, you work with object that are part of the Microsoft .NET Framework, but you can also create custom objects in Windows PowerShell. -The association between an item and its object is very close. When you change an object, you usually change the item that it represents. For example, when you get a file in Windows PowerShell, you do not get the actual file. Instead, you get a FileInfo object that represents the file. When you change the FileInfo object, the file changes too. +PowerShell uses structured collections of information called objects to +represent the items in data stores or the state of the computer. Typically, +you work with object that are part of the Microsoft .NET Framework, but you +can also create custom objects in PowerShell. -Most objects have properties. Properties are the data that is associated with an object. Different types of object have different properties. For example, a FileInfo object, which represents a file, has an IsReadOnly property that contains $True if the file the read-only attribute and $False if it does not. A DirectoryInfo object, which represents a file system directory, has a Parent property that contains the path to the parent directory. +The association between an item and its object is very close. When you change +an object, you usually change the item that it represents. For example, when +you get a file in PowerShell, you do not get the actual file. Instead, you get +a FileInfo object that represents the file. When you change the FileInfo +object, the file changes too. +Most objects have properties. Properties are the data that is associated with +an object. Different types of object have different properties. For example, a +FileInfo object, which represents a file, has an **IsReadOnly** property that +contains $True if the file the read-only attribute and $False if it does not. +A DirectoryInfo object, which represents a file system directory, has a Parent +property that contains the path to the parent directory. ### OBJECT PROPERTIES -To get the properties of an object, use the Get-Member cmdlet. For example, to get the properties of a FileInfo object, use the Get-ChildItem cmdlet to get the FileInfo object that represents a file. Then, use a pipeline operator (|) to send the FileInfo object to Get-Member. The following command gets the PowerShell.exe file and sends it to Get-Member. The $Pshome automatic variable contains the path of the Windows PowerShell installation directory. +To get the properties of an object, use the `Get-Member` cmdlet. For example, +to get the properties of a **FileInfo** object, use the `Get-ChildItem` cmdlet +to get the FileInfo object that represents a file. Then, use a pipeline +operator (|) to send the **FileInfo** object to `Get-Member`. The +following command gets the PowerShell.exe file and sends it to `Get-Member`. +The \$Pshome automatic variable contains the path of the PowerShell +installation directory. -``` +```powershell Get-ChildItem $pshome\PowerShell.exe | Get-Member ``` +The output of the command lists the members of the **FileInfo** object. +Members include both properties and methods. When you work in PowerShell, you +have access to all the members of the objects. -The output of the command lists the members of the FileInfo object. Members include both properties and methods. When you work in Windows PowerShell, you have access to all the members of the objects. - -To get only the properties of an object and not the methods, use the MemberType parameter of the Get-Member cmdlet with a value of "property", as shown in the following example. - +To get only the properties of an object and not the methods, use the +MemberType parameter of the `Get-Member` cmdlet with a value of "property", as +shown in the following example. -``` +```powershell Get-ChildItem $pshome\PowerShell.exe | Get-Member -MemberType property ``` - - -``` -TypeName: System.IO.FileInfo - -Name MemberType Definition ----- ---------- ---------- -Attributes Property System.IO.FileAttributes Attributes {get;set;} -CreationTime Property System.DateTime CreationTime {get;set;} -CreationTimeUtc Property System.DateTime CreationTimeUtc {get;set;} -Directory Property System.IO.DirectoryInfo Directory {get;} -DirectoryName Property System.String DirectoryName {get;} -Exists Property System.Boolean Exists {get;} -Extension Property System.String Extension {get;} -FullName Property System.String FullName {get;} -IsReadOnly Property System.Boolean IsReadOnly {get;set;} -LastAccessTime Property System.DateTime LastAccessTime {get;set;} -LastAccessTimeUtc Property System.DateTime LastAccessTimeUtc {get;set;} -LastWriteTime Property System.DateTime LastWriteTime {get;set;} -LastWriteTimeUtc Property System.DateTime LastWriteTimeUtc {get;set;} -Length Property System.Int64 Length {get;} +```Output +TypeName: System.IO.FileInfo + +Name MemberType Definition +---- ---------- ---------- +Attributes Property System.IO.FileAttributes Attributes {get;set;} +CreationTime Property System.DateTime CreationTime {get;set;} +CreationTimeUtc Property System.DateTime CreationTimeUtc {get;set;} +Directory Property System.IO.DirectoryInfo Directory {get;} +DirectoryName Property System.String DirectoryName {get;} +Exists Property System.Boolean Exists {get;} +Extension Property System.String Extension {get;} +FullName Property System.String FullName {get;} +IsReadOnly Property System.Boolean IsReadOnly {get;set;} +LastAccessTime Property System.DateTime LastAccessTime {get;set;} +LastAccessTimeUtc Property System.DateTime LastAccessTimeUtc {get;set;} +LastWriteTime Property System.DateTime LastWriteTime {get;set;} +LastWriteTimeUtc Property System.DateTime LastWriteTimeUtc {get;set;} +Length Property System.Int64 Length {get;} Name Property System.String Name {get;} ``` - -After you find the properties, you can use them in your Windows PowerShell commands. - +After you find the properties, you can use them in your PowerShell commands. ## PROPERTY VALUES -Although every object of a specific type has the same properties, the values of those properties describe the particular object. For example, every FileInfo object has a CreationTime property, but the value of that property differs for each file. - -The most common way to get the values of the properties of an object is to use the dot method. Type a reference to the object, such as a variable that contains the object, or a command that gets the object. Then, type a dot (.) followed by the property name. - -For example, the following command displays the value of the CreationTime property of the PowerShell.exe file. The Get-ChildItem command returns a FileInfo object that represents the PowerShell.exe file. The command is enclosed in parentheses to make sure that it is executed before any properties are accessed. The Get-ChildItem command is followed by a dot and the name of the CreationTime property, as follows: - -``` -C:\PS> (Get-ChildItem $pshome\PowerShell.exe).creationtime +Although every object of a specific type has the same properties, the values +of those properties describe the particular object. For example, every +FileInfo object has a CreationTime property, but the value of that property +differs for each file. + +The most common way to get the values of the properties of an object is to use +the dot method. Type a reference to the object, such as a variable that +contains the object, or a command that gets the object. Then, type a dot (.) +followed by the property name. + +For example, the following command displays the value of the CreationTime +property of the PowerShell.exe file. The `Get-ChildItem` command returns a +FileInfo object that represents the PowerShell.exe file. The command is +enclosed in parentheses to make sure that it is executed before any properties +are accessed. The `Get-ChildItem` command is followed by a dot and the name of +the CreationTime property, as follows: + +```powershell +C:\PS> (Get-ChildItem $pshome\PowerShell.exe).creationtime Tuesday, March 18, 2008 12:07:52 AM ``` +You can also save an object in a variable and then get its properties by using +the dot method, as shown in the following example: -You can also save an object in a variable and then get its properties by using the dot method, as shown in the following example: - - -``` -C:\PS> $a = Get-ChildItem $pshome\PowerShell.exe -C:\PS> $a.CreationTime +```powershell +C:\PS> $a = Get-ChildItem $pshome\PowerShell.exe +C:\PS> $a.CreationTime Tuesday, March 18, 2008 12:07:52 AM ``` +You can also use the `Select-Object` and `Format-List` cmdlets to display the +property values of an object. `Select-Object` and `Format-List` each have a +**Property** parameter. You can use the **Property** parameter to specify one +or more properties and their values. Or, you can use the wildcard character +(\*) to represent all the properties. -You can also use the Select-Object and Format-List cmdlets to display the property values of an object. Select-Object and Format-List each have a Property parameter. You can use the Property parameter to specify one or more properties and their values. Or, you can use the wildcard character (\*) to represent all the properties. - -For example, the following command displays the values of all the properties of the PowerShell.exe file. - +For example, the following command displays the values of all the properties +of the PowerShell.exe file. -``` +```powershell C:\PS> Get-ChildItem $pshome\PowerShell.exe | Format-List -property * ``` - - -``` -PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe -PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\system32\WindowsPowerShell\v1.0 -PSChildName : PowerShell.exe -PSDrive : C -PSProvider : Microsoft.PowerShell.Core\FileSystem -PSIsContainer : False -VersionInfo : File: C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe - InternalName: POWERSHELL - OriginalFilename: PowerShell.EXE.MUI - File Version: 6.1.6570.1 (fbl_srv_PowerShell(nigels).070711-0102) - FileDescription: PowerShell.EXE - Product: Microsoft® Windows® Operating System - ProductVersion: 6.1.6570.1 - Debug: False - Patched: False - PreRelease: False - PrivateBuild: True - SpecialBuild: False +```Output +PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\System3 + 2\WindowsPowerShell\v1.0\PowerShell.exe +PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\System3 + 2\WindowsPowerShell\v1.0 +PSChildName : PowerShell.exe +PSDrive : C +PSProvider : Microsoft.PowerShell.Core\FileSystem +PSIsContainer : False +Mode : -a---- +VersionInfo : File: C:\Windows\System32\WindowsPowerShell\ + v1.0\PowerShell.exe + InternalName: POWERSHELL + OriginalFilename: PowerShell.EXE.MUI + FileVersion: 10.0.16299.15 (WinBuild.160101.0800) + FileDescription: Windows PowerShell + Product: Microsoft® Windows® Operating System + ProductVersion: 10.0.16299.15 + Debug: False + Patched: False + PreRelease: False + PrivateBuild: False + SpecialBuild: False Language: English (United States) -``` - - -``` -BaseName : PowerShell -Mode : -a--- -Name : PowerShell.exe -Length : 160256 -DirectoryName : C:\Windows\system32\WindowsPowerShell\v1.0 -Directory : C:\Windows\system32\WindowsPowerShell\v1.0 -IsReadOnly : False -Exists : True -FullName : C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe -Extension : .exe -CreationTime : 3/18/2008 12:07:52 AM -CreationTimeUtc : 3/18/2008 7:07:52 AM -LastAccessTime : 3/19/2008 8:13:58 AM -LastAccessTimeUtc : 3/19/2008 3:13:58 PM -LastWriteTime : 3/18/2008 12:07:52 AM -LastWriteTimeUtc : 3/18/2008 7:07:52 AM +BaseName : PowerShell +Target : {C:\Windows\WinSxS\amd64_microsoft-windows-powershell-ex + e_31bf3856ad364e35_10.0.16299.15_none_8c022aa6735716ae\p + owershell.exe} +LinkType : HardLink +Name : PowerShell.exe +Length : 449024 +DirectoryName : C:\Windows\System32\WindowsPowerShell\v1.0 +Directory : C:\Windows\System32\WindowsPowerShell\v1.0 +IsReadOnly : False +Exists : True +FullName : C:\Windows\System32\WindowsPowerShell\v1.0\PowerShell.ex +Extension : .exe +CreationTime : 9/29/2017 6:43:19 AM +CreationTimeUtc : 9/29/2017 1:43:19 PM +LastAccessTime : 9/29/2017 6:43:19 AM +LastAccessTimeUtc : 9/29/2017 1:43:19 PM +LastWriteTime : 9/29/2017 6:43:19 AM +LastWriteTimeUtc : 9/29/2017 1:43:19 PM Attributes : Archive ``` - - ### STATIC PROPERTIES -You can use the static properties of .NET classes in Windows PowerShell. Static properties are properties of class, unlike standard properties, which are properties of an object. -To get the static properties of an class, use the Static parameter of the Get-Member cmdlet. +You can use the static properties of .NET classes in PowerShell. Static +properties are properties of class, unlike standard properties, which are +properties of an object. -For example, the following command gets the static properties of the System.DateTime class. +To get the static properties of an class, use the Static parameter of the +Get-Member cmdlet. +For example, the following command gets the static properties of the +`System.DateTime` class. -``` +```powershell Get-Date | Get-Member -MemberType Property -Static ``` +```Output +TypeName: System.DateTime - -``` -TypeName: System.DateTime - -Name MemberType Definition ----- ---------- ---------- -MaxValue Property static datetime MaxValue {get;} -MinValue Property static datetime MinValue {get;} -Now Property datetime Now {get;} -Today Property datetime Today {get;} +Name MemberType Definition +---- ---------- ---------- +MaxValue Property static datetime MaxValue {get;} +MinValue Property static datetime MinValue {get;} +Now Property datetime Now {get;} +Today Property datetime Today {get;} UtcNow Property datetime UtcNow {get;} ``` - To get the value of a static property, use the following syntax. - -``` +```powershell []:: ``` +For example, the following command gets the value of the UtcNow static +property of the `System.DateTime` class. -For example, the following command gets the value of the UtcNow static property of the System.DateTime class. - - -``` +```powershell [System.DateTime]::UtcNow ``` - - ### PROPERTIES OF SCALAR OBJECTS AND COLLECTIONS -The properties of one ("scalar") object of a particular type are often different from the properties of a collection of objects of the same type. -For example, every service has as DisplayName property, but a collection of services does not have a DisplayName property. Similarly, all collections have a Count property that tells how many objects are in the collection, but individual objects do not have a Count property. +The properties of one ("scalar") object of a particular type are often +different from the properties of a collection of objects of the same type. -Beginning in Windows PowerShell 3.0, Windows PowerShell tries to prevent scripting errors that result from the differing properties of scalar objects and collections. +For example, every service has as **DisplayName** property, but a collection +of services does not have a **DisplayName** property. Similarly, all +collections have a **Count** property that tells how many objects are in the +collection, but individual objects do not have a **Count** property. -If you submit a collection, but request a property that exists only on single ("scalar") objects, Windows PowerShell returns the value of that property for every object in the collection. +Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that +result from the differing properties of scalar objects and collections. -If you request the Count or Length property of zero objects or of one object, Windows PowerShell returns the correct value. +If you submit a collection, but request a property that exists only on single +("scalar") objects, PowerShell returns the value of that property for every +object in the collection. -If the property exists on the individual objects and on the collection, Windows PowerShell does not alter the result. +If you request the Count or Length property of zero objects or of one object, +PowerShell returns the correct value. -This feature also works on methods of scalar objects and collections. For more information, see about_Methods. +If the property exists on the individual objects and on the collection, +PowerShell does not alter the result. +This feature also works on methods of scalar objects and collections. For more +information, see about_Methods. ### EXAMPLES -For example, each service has a DisplayName property. The following command gets the value of the DisplayName property of the Audiosrv service. +For example, each service has a DisplayName property. The following command +gets the value of the DisplayName property of the Audiosrv service. -``` -PS C:\> (Get-Service Audiosrv).DisplayName +```powershell +PS C:\> (Get-Service Audiosrv).DisplayName Windows Audio ``` +However, a collection or array of services does not have a **DisplayName**. +The following command tries to get the DisplayName property of all services in +PowerShell 2.0. -However, a collection or array of services does not have a DisplayName. The following command tries to get the DisplayName property of all services in Windows PowerShell 2.0. - - -``` -PS C:\> (Get-Service).DisplayName +```powershell +PS C:\> (Get-Service).DisplayName PS C:\> ``` +Beginning in PowerShell 3.0, the same command returns the value of the +**DisplayName** property of every service that `Get-Service` returns. -Beginning in Windows PowerShell 3.0, the same command returns the value of the DisplayName property of every service that Get-Service returns. - - -``` -PS C:\> (Get-Service).DisplayName -Application Experience -Application Layer Gateway Service -Windows All-User Install Agent -Application Identity -Application Information +```powershell +PS C:\> (Get-Service).DisplayName +Application Experience +Application Layer Gateway Service +Windows All-User Install Agent +Application Identity +Application Information ... ``` +Conversely, a collection of two or more services has a **Count** property, +which contains the number of objects in the collection. -Conversely, a collection of two or more services has a Count property, which contains the number of objects in the collection. - - -``` -PS C:\> (Get-Service).Count +```powershell +PS C:\> (Get-Service).Count 176 ``` +Individual services do not have a Count or Length property, as shown in this +command in PowerShell 2.0. -Individual services do not have a Count or Length property, as shown in this command in Windows PowerShell 2.0. - - -``` -PS C:\> (Get-Service Audiosrv).Count +```powershell +PS C:\> (Get-Service Audiosrv).Count PS C:\> ``` +Beginning in PowerShell 3.0, the command returns the correct Count value. -Beginning in Windows PowerShell 3.0, the command returns the correct Count value. - - -``` -PS C:\> (Get-Service Audiosrv).Count +```powershell +PS C:\> (Get-Service Audiosrv).Count 1 ``` - - ## SEE ALSO [about_Methods](about_Methods.md) [about_Objects](about_Objects.md) -Get-Member - -Select-Object +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) -Format-List +[Select-Object](../../Microsoft.PowerShell.Utility/Select-Object.md) +[Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) \ No newline at end of file diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Redirection.md index d53b982904c..21d289c7f6e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -1,135 +1,145 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us -keywords: powershell,cmdlet +keywords: PowerShell,cmdlet title: about_Redirection --- # About Redirection -## about_Redirection - ## SHORT DESCRIPTION -Explains how to redirect output from Windows PowerShell® to text files. +Explains how to redirect output from PowerShell to text files. ## LONG DESCRIPTION -By default, Windows PowerShell sends its command output to the Windows PowerShell console. However, you can direct the output to a text file, and you can redirect error output to the regular output stream. -You can use the following methods to redirect output: +By default, PowerShell sends its command output to the PowerShell console. +However, you can direct the output to a text file, and you can redirect error +output to the regular output stream. -- Use the Out-File cmdlet, which sends command output to a text file. Typically, you use the Out-File cmdlet when you need to use its parameters, such as the Encoding, Force, Width, or NoClobber parameters. +You can use the following methods to redirect output: -- Use the Tee-Object cmdlet, which sends command output to a text file and then sends it to the pipeline. +- Use the `Out-File` cmdlet, which sends command output to a text file. + Typically, you use the `Out-File` cmdlet when you need to use its parameters, + such as the **Encoding**, **Force**, **Width**, or **NoClobber** parameters. -- Use the Windows PowerShell redirection operators. +- Use the Tee-Object cmdlet, which sends command output to a text file and + then sends it to the pipeline. +- Use the PowerShell redirection operators. -### WINDOWS POWERSHELL REDIRECTION OPERATORS -The redirection operators enable you to send particular types of output to files and to the success output stream. +### POWERSHELL REDIRECTION OPERATORS -The Windows PowerShell redirection operators use the following characters to represent each output type: +The redirection operators enable you to send particular types of output to +files and to the success output stream. +The PowerShell redirection operators use the following characters to represent +each output type: ``` -* All output -1 Success output -2 Errors -3 Warning messages -4 Verbose output +* All output +1 Success output +2 Errors +3 Warning messages +4 Verbose output 5 Debug messages ``` +NOTE: The All (\*), Warning (3), Verbose (4) and Debug (5) redirection +operators were introduced in PowerShell 3.0. They do not work in earlier +versions of PowerShell. -NOTE: The All (\*), Warning (3), Verbose (4) and Debug (5) redirection operators were introduced in Windows PowerShell 3.0. They do not work in earlier versions of Windows PowerShell. +The PowerShell redirection operators are as follows. -The Windows PowerShell redirection operators are as follows. +``` +Operator Description Example +-------- ---------------------- ------------------------------ +> Sends output to the Get-Process > Process.txt + specified file. +>> Appends the output to dir *.ps1 >> Scripts.txt + the contents of the + specified file. -``` -Operator Description Example --------- ---------------------- ------------------------------ -> Sends output to the Get-Process > Process.txt - specified file. - ->> Appends the output to dir *.ps1 >> Scripts.txt - the contents of the - specified file. - -2> Sends errors to the Get-Process none 2> Errors.txt - specified file. - -2>> Appends errors to Get-Process none 2>> Save-Errors.txt - the contents of the - specified file. - -2>&1 Sends errors (2) and Get-Process none, Powershell 2>&1 - success output (1) - to the success - output stream. - -3> Sends warnings to the Write-Warning "Test!" 3> Warnings.txt - specified file. - -3>> Appends warnings to Write-Warning "Test!" 3>> Save-Warnings.txt - the contents of the - specified file. - -3>&1 Sends warnings (3) and function Test-Warning - success output (1) { Get-Process PowerShell; - to the success Write-Warning "Test!" } - output stream. Test-Warning 3>&1 - -4> Sends verbose output to Import-Module * -Verbose 4> Verbose.txt - the specified file. - -4>> Appends verbose output Import-Module * -Verbose 4>> Save-Verbose.txt - to the contents of the - specified file. - -4>&1 Sends verbose output (4) Import-Module * -Verbose 4>&1 - and success output (1) - to the success output - stream. - -5> Sends debug messages to Write-Debug "Starting" 5> Debug.txt - the specified file. - -5>> Appends debug messages Write-Debug "Saving" 5>> Save-Debug.txt - to the contents of the - specified file. - -5>&1 Sends debug messages (5) function Test-Debug - and success output (1) { Get-Process PowerShell - to the success output Write-Debug "PS" } - stream. Test-Debug 5>&1 - -*> Sends all output types function Test-Output - to the specified file. { Get-Process PowerShell, none - Write-Warning "Test!" -*>> Appends all output types Write-Verbose "Test Verbose" - to the contents of the Write-Debug "Test Debug" } - specified file. - Test-Output *> Test-Output.txt -*>&1 Sends all output types Test-Output *>> Test-Output.txt - (*) to the success output Test-Output *>&1 +2> Sends errors to the Get-Process none 2> Errors.txt + specified file. + +2>> Appends errors to Get-Process none 2>> Save-Errors.txt + the contents of the + specified file. + +2>&1 Sends errors (2) and Get-Process none, Powershell 2>&1 + success output (1) + to the success + output stream. + +3> Sends warnings to the Write-Warning "Test!" 3> Warnings.txt + specified file. + +3>> Appends warnings to Write-Warning "Test!" 3>> Warnings.txt + the contents of the + specified file. + +3>&1 Sends warnings (3) and function Test-Warning + success output (1) { Get-Process PowerShell; + to the success Write-Warning "Test!" } + output stream. Test-Warning 3>&1 + +4> Sends verbose output to Import-Module * -Verbose 4> Verbose.txt + the specified file. + +4>> Appends verbose output Import-Module * -Verbose 4>> Verbose.txt + to the contents of the + specified file. + +4>&1 Sends verbose output (4) Import-Module * -Verbose 4>&1 + and success output (1) + to the success output stream. -``` +5> Sends debug messages to Write-Debug "Starting" 5> Debug.txt + the specified file. + +5>> Appends debug messages Write-Debug "Saving" 5>> Debug.txt + to the contents of the + specified file. + +5>&1 Sends debug messages (5) function Test-Debug + and success output (1) { Get-Process PowerShell + to the success output Write-Debug "PS" } + stream. Test-Debug 5>&1 + +*> Sends all output types function Test-Output + to the specified file. { Get-Process PowerShell, none + Write-Warning "Test!" +*>> Appends all output types Write-Verbose "Test Verbose" + to the contents of the Write-Debug "Test Debug" } + specified file. + Test-Output *> Test-Output.txt +*>&1 Sends all output types Test-Output *>> Test-Output.txt + (*) to the success Test-Output *>&1 + output stream. +``` The syntax of the redirection operators is as follows: - ``` [\] ``` +If the specified file already exists, the redirection operators that do not +append data (> and n>) overwrite the current contents of the file without +warning. However, if the file is a read-only, hidden, or system file, the +redirection fails. The append redirection operators (>> and n>>) do not write +to a read-only file, but they append content to a system or hidden file. -If the specified file already exists, the redirection operators that do not append data (> and n>) overwrite the current contents of the file without warning. However, if the file is a read-only, hidden, or system file, the redirection fails. The append redirection operators (>> and n>>) do not write to a read-only file, but they append content to a system or hidden file. - -To force the redirection of content to a read-only, hidden, or system file, use the Out-File cmdlet with its Force parameter. When you are writing to files, the redirection operators use Unicode encoding. If the file has a different encoding, the output might not be formatted correctly. To redirect content to non-Unicode files, use the Out-File cmdlet with its Encoding parameter. - +To force the redirection of content to a read-only, hidden, or system file, +use the Out-File cmdlet with its Force parameter. When you are writing to +files, the redirection operators use Unicode encoding. If the file has a +different encoding, the output might not be formatted correctly. To redirect +content to non-Unicode files, use the Out-File cmdlet with its Encoding +parameter. ## SEE ALSO @@ -142,4 +152,3 @@ Tee-Object [about_Command_Syntax](about_Command_Syntax.md) [about_Path_Syntax](about_Path_Syntax.md) - diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 00bb519f161..9194ac278b4 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -16,50 +16,132 @@ Describes regular expressions in Windows PowerShell. Windows PowerShell supports the following regular expression characters. -| Format | Logic | Example | -| ------- | ----- | ------- | -| value | Matches exact characters anywhere in the original value. | "book" -match "oo" | -| . | Matches any single character. | "copy" -match "c..y" | -| [value] | Matches at least one of the characters in the brackets. | "big" -match "b[iou]g" | -| [range] | Matches at least one of the characters within the range. The use of a hyphen (-) allows you to specify an adjacent character. | "and" -match "[a-e]nd" | -| [^] | Matches any characters except those in brackets. | "and" -match "[^brt]nd" | -| ^ | Matches the beginning characters. | "book" -match "^bo" | -| $ | Matches the end characters. | "book" -match "ok$" | -| * | Matches any instances of the preceding character. | "baggy" -match "g*" | -| ? | Matches zero or one instance of the preceding character. | "baggy" -match "g?" | -| \ | Matches the character that follows as an escaped character. | "Try$" -match "Try\\$" | - -Windows PowerShell supports the character classes available in -Microsoft .NET Framework regular expressions. - -| Format | Logic | Example | -| -------- | ----- | ------- | -| \p{name} | Matches any character in the named character class specified by {name}. Supported names are Unicode groups and block ranges such as Ll, Nd, Z, IsGreek, and IsBoxDrawing. | "abcd defg" -match "\p{Ll}+" | -| \P{name} | Matches text not included in the groups and block ranges specified in {name}. | 1234 -match "\P{Ll}+" | -| \w | Matches any word character. Equivalent to the Unicode character categories [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. If ECMAScript-compliant behavior is specified with the ECMAScript option, \w is equivalent to [a-zA-Z_0-9]. | "abcd defg" -match "\w+" (this matches abcd) | -| \W | Matches any nonword character. Equivalent to the Unicode categories [^\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. | "abcd defg" -match "\W+" (this matches the space) | -| \s | Matches any white-space character. Equivalent to the Unicode character categories [\f\n\r\t\v\x85\p{Z}]. | "abcd defg" -match "\s+" | -| \S | Matches any non-white-space character. Equivalent to the Unicode character categories [^\f\n\r\t\v\x85\p{Z}]. | "abcd defg" -match "\S+" | -| \d | Matches any decimal digit. Equivalent to \p{Nd} for Unicode and [0-9] for non-Unicode behavior. | 12345 -match "\d+" | -| \D | Matches any nondigit. Equivalent to \P{Nd} for Unicode and [^0-9] for non-Unicode behavior. | "abcd" -match "\D+" | - +``` +Format value +Logic Matches exact characters anywhere in the original value. +Example "book" -match "oo" + +Format . +Logic Matches any single character. +Example "copy" -match "c..y" + +Format [value] +Logic Matches at least one of the characters in the brackets. +Example "big" -match "b[iou]g" + +Format [range] +Logic Matches at least one of the characters within the range. The use + of a hyphen (-) allows you to specify an adjacent character. +Example "and" -match "[a-e]nd" + +Format [^] +Logic Matches any characters except those in brackets. +Example "and" -match "[^brt]nd" + +Format ^ +Logic Matches the beginning characters. +Example "book" -match "^bo" + +Format $ +Logic Matches the end characters. +Example "book" -match "ok$" + +Format * +Logic Matches any instances of the preceding character. +Example "baggy" -match "g*" + +Format ? +Logic Matches zero or one instance of the preceding character. +Example "baggy" -match "g?" + +Format \ +Logic Matches the character that follows as an escaped character. +Example "Try$" -match "Try\\$" +``` + +Windows PowerShell supports the character classes available in Microsoft .NET +Framework regular expressions. + +``` +Format: \p{name} +Logic: Matches any character in the named character class specified by + {name}. Supported names are Unicode groups and block ranges such + as Ll, Nd, Z, IsGreek, and IsBoxDrawing. +Example: "abcd defg" -match "\p{Ll}+" + +Format: \P{name} +Logic: Matches text not included in the groups and block ranges specified + in {name}. +Example: 1234 -match "\P{Ll}+" + +Format: \w +Logic: Matches any word character. Equivalent to the Unicode character + categories [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. If ECMAScript- + compliant behavior is specified with the ECMAScript option, \w is + equivalent to [a-zA-Z_0-9]. +Example: "abcd defg" -match "\w+" (this matches abcd) + +Format: \W +Logic: Matches any nonword character. Equivalent to the Unicode categories + [^\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. +Example: "abcd defg" -match "\W+" (this matches the space) + +Format: \s +Logic: Matches any white-space character. Equivalent to the Unicode + character categories [\f\n\r\t\v\x85\p{Z}]. +Example: "abcd defg" -match "\s+" + +Format: \S +Logic: Matches any non-white-space character. Equivalent to the Unicode + character categories [^\f\n\r\t\v\x85\p{Z}]. +Example: "abcd defg" -match "\S+" + +Format: \d +Logic: Matches any decimal digit. Equivalent to \p{Nd} for Unicode and + [0-9] for non-Unicode behavior. +Example: 12345 -match "\d+" + +Format: \D +Logic: Matches any nondigit. Equivalent to \P{Nd} for Unicode and [^0-9] + for non-Unicode behavior. +Example: "abcd" -match "\D+" +``` Windows PowerShell supports the quantifiers available in .NET Framework regular expressions. The following are some examples of quantifiers. -| Format | Logic | Example | -| ------ | ----- | ------- | -| * | Specifies zero or more matches; for example, \wor (abc). Equivalent to {0,}. | "abc" -match "\w*" | -| + | Matches repeating instances of the preceding characters. | "xyxyxy" -match "xy+" | -| ? | Specifies zero or one matches; for example, \w? or (abc)?. Equivalent to {0,1}. | "abc" -match "\w?" | -| {n} | Specifies exactly n matches; for example, (pizza){2}. | "abc" -match "\w{2}" | -| {n,} | Specifies at least n matches; for example, (abc){2,}. | "abc" -match "\w{2,}" | -| {n,m} | Specifies at least n, but no more than m, matches. | "abc" -match "\w{2,3}" | +``` +Format: * +Logic Specifies zero or more matches; for example, \wor (abc). Equivalent + to {0,}. +Example: "abc" -match "\w*" + +Format: + +Logic: Matches repeating instances of the preceding characters. +Example: "xyxyxy" -match "xy+" + +Format: ? +Logic: Specifies zero or one matches; for example, \w? or (abc)?. + Equivalent to {0,1}. +Example: "abc" -match "\w?" + +Format: {n} +Logic: Specifies exactly n matches; for example, (pizza){2}. +Example: "abc" -match "\w{2}" + +Format: {n,} +Logic: Specifies at least n matches; for example, (abc){2,}. +Example: "abc" -match "\w{2,}" + +Format: {n,m} +Logic: Specifies at least n, but no more than m, matches. +Example: "abc" -match "\w{2,3}" +``` All the comparisons shown in the preceding table evaluate to true. -Notice that the escape character for regular expressions, a backslash (\\), -is different from the escape character for Windows PowerShell. The -escape character for Windows PowerShell is the backtick character (`) (ASCII 96). +Notice that the escape character for regular expressions, a backslash (\\), is +different from the escape character for Windows PowerShell. The escape +character for Windows PowerShell is the backtick character (`) (ASCII 96). For more information, see [Regular Expression Language - Quick Reference](https://go.microsoft.com/fwlink/?LinkId=133231). diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md index 9106db823dd..d7a4d220a0c 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,34 +14,31 @@ Explains how to disconnect from and reconnect to a PSSession ## Long Description -Beginning in Windows PowerShell 3.0, you can disconnect from -a PSSession and reconnect to the PSSession at a later time on -the same computer or a different computer. The session state -is maintained and commands in the PSSession continue to -run while the session is disconnected. +Beginning in Windows PowerShell 3.0, you can disconnect from a PSSession and +reconnect to the PSSession at a later time on the same computer or a different +computer. The session state is maintained and commands in the PSSession +continue to run while the session is disconnected. -The Disconnected Sessions feature is available only when the -computer at the remote end of a connection is running Windows -PowerShell 3.0 or a later version of Windows PowerShell. +The Disconnected Sessions feature is available only when the computer at the +remote end of a connection is running Windows PowerShell 3.0 or a later +version of Windows PowerShell. -The Disconnected Sessions feature allows you to close the session -in which a PSSession was created, and even close Windows PowerShell, -and shut down the computer, without disrupting commands running -in the PSSession. It is especially useful for running commands that -take an extended time to complete, and it provides the time and -device flexibility that IT professionals require. +The Disconnected Sessions feature allows you to close the session in which a +PSSession was created, and even close Windows PowerShell, and shut down the +computer, without disrupting commands running in the PSSession. It is +especially useful for running commands that take an extended time to complete, +and it provides the time and device flexibility that IT professionals require. -NOTE: You cannot disconnect from an interactive session that -is started by using the `Enter-PSSession` cmdlet. +NOTE: You cannot disconnect from an interactive session that is started by +using the `Enter-PSSession` cmdlet. -You can use Disconnected Sessions to manage PSSessions that -were disconnected unintentionally as the result of a computer -or network outage. +You can use Disconnected Sessions to manage PSSessions that were disconnected +unintentionally as the result of a computer or network outage. -In real-world use, the Disconnected Sessions feature allows -you to begin solving a problem, turn your attention to a higher -priority issue, and then resume work on the solution, even on a -different computer in a different location. +In real-world use, the Disconnected Sessions feature allows you to begin +solving a problem, turn your attention to a higher priority issue, and then +resume work on the solution, even on a different computer in a different +location. ## Disconnected Session Cmdlets @@ -50,82 +47,77 @@ The following cmdlets support the Disconnected Sessions feature: * `Connect-PSSession`: Connects to a disconnected PSSession * `Disconnect-PSSession`: Disconnects a PSSession * `Get-PSSession`: Gets PSSessions on the local computer or on remote computers -* `Receive-PSSession`: Gets the results of commands that ran in disconnected sessions -* `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and disconnects immediately +* `Receive-PSSession`: Gets the results of commands that ran in disconnected + sessions +* `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and + disconnects immediately ## How the Disconnected Sessions Feature Works -Beginning in Windows PowerShell 3.0, PSSessions are independent -of the sessions in which they are created. Active PSSession are -maintained on the remote computer or "server side" of the -connection, even if the session in which PSSession was -created is closed and the originating computer is shut down -or disconnected from the network. - -In Windows PowerShell 2.0, the PSSession is deleted from the -remote computer when it is disconnected from the originating -session or the session in which it was created ends. - -When you disconnect a PSSession, the PSSession remains active -and is maintained on the remote computer. The session state -changes from Running to Disconnected. You can reconnect to a -disconnected PSSession from the current session or from a different -session on the same computer, or from a different computer. The -remote computer that maintains the session must be running and +Beginning in Windows PowerShell 3.0, PSSessions are independent of the +sessions in which they are created. Active PSSession are maintained on the +remote computer or "server side" of the connection, even if the session in +which PSSession was created is closed and the originating computer is shut +down or disconnected from the network. + +In Windows PowerShell 2.0, the PSSession is deleted from the remote computer +when it is disconnected from the originating session or the session in which +it was created ends. + +When you disconnect a PSSession, the PSSession remains active and is +maintained on the remote computer. The session state changes from Running to +Disconnected. You can reconnect to a disconnected PSSession from the current +session or from a different session on the same computer, or from a different +computer. The remote computer that maintains the session must be running and be connected to the network. -Commands in a disconnected PSSession continue to run -uninterrupted on the remote computer until the command -completes or the output buffer fills. To prevent a full -output buffer from suspending a command, use the +Commands in a disconnected PSSession continue to run uninterrupted on the +remote computer until the command completes or the output buffer fills. To +prevent a full output buffer from suspending a command, use the **OutputBufferingMode** parameter of the `Disconnect-PSSession`, `New-PSSessionOption`, or `New-PSTransportOption` cmdlets. -Disconnected sessions are maintained in the disconnected -state on the remote computer. They are available for you to -reconnect, until you delete the PSSession, such as by using -the `Remove-PSSession` cmdlet, or until the idle timeout of the -PSSession expires. You can adjust the idle timeout of a PSSession -by using the **IdleTimeoutSec** or **IdleTimeout** parameters of the +Disconnected sessions are maintained in the disconnected state on the remote +computer. They are available for you to reconnect, until you delete the +PSSession, such as by using the `Remove-PSSession` cmdlet, or until the idle +timeout of the PSSession expires. You can adjust the idle timeout of a +PSSession by using the **IdleTimeoutSec** or **IdleTimeout** parameters of the `Disconnect-PSSession`, `New-PSSessionOption`, or `New-PSTransportOption` cmdlets. -Another user can connect to PSSessions that you created, -but only if they can supply the credentials that were used -to create the session, or use the RunAs credentials of -the session configuration. +Another user can connect to PSSessions that you created, but only if they can +supply the credentials that were used to create the session, or use the RunAs +credentials of the session configuration. ## How to Get PSSessions Beginning in Windows PowerShell 3.0, the `Get-PSSession` cmdlet gets -PSSessions on the local computer and remote computers. It can also -get PSSessions that were created in the current session. +PSSessions on the local computer and remote computers. It can also get +PSSessions that were created in the current session. To get PSsessions on the local computer or remote computers, use the **ComputerName** or **ConnectionUri** parameters. Without parameters, `Get-PSSession` gets PSSession that were created in the local session, regardless of where they terminate. -When getting PSSessions, remember to look for them on the computer -on which they are maintained, that is, the remote or "server-side" -computer. +When getting PSSessions, remember to look for them on the computer on which +they are maintained, that is, the remote or "server-side" computer. -For example, if you create a PSSession to the Server01 computer, -get the session from the Server01 computer. If you create a PSSession -from another computer to the local computer, get the session from -the local computer. +For example, if you create a PSSession to the Server01 computer, get the +session from the Server01 computer. If you create a PSSession from another +computer to the local computer, get the session from the local computer. The following command sequence shows how `Get-PSSession` works. -The first command creates a session to the Server01 computer. The -session resides on the Server01 computer. +The first command creates a session to the Server01 computer. The session +resides on the Server01 computer. ```powershell PS C:\> New-PSSession -ComputerName Server01 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` To get the session, use the **ComputerName** parameter of `Get-PSSession` @@ -134,15 +126,15 @@ with a value of Server01. ```powershell PS C:\> Get-PSSession -ComputerName Server01 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` If the value of the **ComputerName** parameter of `Get-PSSession` is localhost, `Get-PSSession` gets PSSessions that terminate at and are -maintained on the local computer. It does not get PSSessions on the -Server01 computer, even if they were started on the local computer. +maintained on the local computer. It does not get PSSessions on the Server01 +computer, even if they were started on the local computer. ```powershell PS C:\> Get-PSSession -ComputerName localhost @@ -156,16 +148,16 @@ that was created in the current session and connects to the Server01 computer. ```powershell PS C:\> Get-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` ## How to Disconnect Sessions -To disconnect a PSSession use the `Disconnect-PSSession` cmdlet. To -identify the PSSession, use the **Session** parameter, or pipe a PSSession -from the `New-PSSession` or `Get-PSSession` cmdlets to `Disconnect-PSSession`. +To disconnect a PSSession use the `Disconnect-PSSession` cmdlet. To identify +the PSSession, use the **Session** parameter, or pipe a PSSession from the +`New-PSSession` or `Get-PSSession` cmdlets to `Disconnect-PSSession`. The following command disconnects the PSSession to the Server01 computer. Notice that the value of the State property is Disconnected and the @@ -174,94 +166,96 @@ Availability is None. ```powershell PS C:\> Get-PSSession -ComputerName Server01 | Disconnect-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Disconnected Microsoft.PowerShell None ``` To create a disconnected session, use the **InDisconnectedSession** parameter -of the `Invoke-Command` cmdlet. It creates a session, starts the command, -and disconnects immediately, before the command can return any output. +of the `Invoke-Command` cmdlet. It creates a session, starts the command, and +disconnects immediately, before the command can return any output. -The following command runs a `Get-WinEvent` command in a disconnected -session on the Server02 remote computer. +The following command runs a `Get-WinEvent` command in a disconnected session +on the Server02 remote computer. ```powershell PS C:\> Invoke-Command -ComputerName Server02 -InDisconnectedSession ` -ScriptBlock { Get-WinEvent -LogName "Windows PowerShell" } -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 4 Session3 Server02 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 4 Session3 Server02 Disconnected Microsoft.PowerShell None ``` ## How to Connect to Disconnected Sessions -You can connect to any available disconnected PSSession from the session -in which you created the PSSession or from other sessions on the local -computer or other computers. +You can connect to any available disconnected PSSession from the session in +which you created the PSSession or from other sessions on the local computer +or other computers. -You can create a PSSession, run commands in the PSSession, disconnect from -the PSSession, close Windows PowerShell, and shut down the computer. Hours -later, you can open a different computer, get the PSSession, connect to it, -and get the results of commands that ran in the PSSession while it was -disconnected. Then you can run more commands in the session. +You can create a PSSession, run commands in the PSSession, disconnect from the +PSSession, close Windows PowerShell, and shut down the computer. Hours later, +you can open a different computer, get the PSSession, connect to it, and get +the results of commands that ran in the PSSession while it was disconnected. +Then you can run more commands in the session. To connect a disconnected PSSession, use the `Connect-PSSession` cmdlet. Use -the **ComputerName** or **ConnectionUri** parameters to identify the PSSession, or -pipe a PSSession from `Get-PSSession` to `Connect-PSSession`. +the **ComputerName** or **ConnectionUri** parameters to identify the +PSSession, or pipe a PSSession from `Get-PSSession` to `Connect-PSSession`. -The following command gets the sessions on the Server02 computer. -The output includes two disconnected sessions, both of which are available. +The following command gets the sessions on the Server02 computer. The output +includes two disconnected sessions, both of which are available. ```powershell PS C:\> Get-PSSession -ComputerName Server02 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 juneb-srv8320 Disconnected Microsoft.PowerShell None - 4 Session3 juneb-srv8320 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 juneb-srv8320 Disconnected Microsoft.PowerShell None + 4 Session3 juneb-srv8320 Disconnected Microsoft.PowerShell None ``` -The following command connects to Session2. The PSSession is now open and available. +The following command connects to Session2. The PSSession is now open and +available. ```powershell PS C:\> Connect-PSSession -ComputerName Server02 -Name Session2 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 juneb-srv8320 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 juneb-srv8320 Opened Microsoft.PowerShell Available ``` ## How to Get the Results -To get the results of commands that ran in a disconnected PSSession, use -the `Receive-PSSession` cmdlet. +To get the results of commands that ran in a disconnected PSSession, use the +`Receive-PSSession` cmdlet. You can use `Receive-PSSession` in addition to, or instead of, using the `Connect-PSSession` cmdlet. If the session is already reconnected, -`Receive-PSSession` gets the results of commands that ran when the session -was disconnected. If the PSSession is still disconnected, `Receive-PSSession` +`Receive-PSSession` gets the results of commands that ran when the session was +disconnected. If the PSSession is still disconnected, `Receive-PSSession` connects to it and then gets the results of commands that ran while it was disconnected. -`Receive-PSSession` can return the results in a job (asynchronously) or to -the host program (synchronously). Use the **OutTarget** parameter to select Job -or Host. Host is the default value. However, if the command that is being +`Receive-PSSession` can return the results in a job (asynchronously) or to the +host program (synchronously). Use the **OutTarget** parameter to select Job or +Host. Host is the default value. However, if the command that is being received was started in the current session as a job, it is returned as a job by default. -The following command uses the `Receive-PSSession` cmdlet to connect to the PSSession -on the Server02 computer and get the results of the `Get-WinEvent` command that -ran in the Session3 session. The command uses the **OutTarget** parameter to get the -results in a job. +The following command uses the `Receive-PSSession` cmdlet to connect to the +PSSession on the Server02 computer and get the results of the `Get-WinEvent` +command that ran in the Session3 session. The command uses the **OutTarget** +parameter to get the results in a job. ```powershell -PS C:\> Receive-PSSession -ComputerName Server02 -Name Session3 -OutTarget Job +PS C:\> Receive-PSSession -ComputerName Server02 -Name Session3 ` + -OutTarget Job -Id Name PSJobTypeName State HasMoreData Location --- ---- ------------- ----- ----------- -------- - 3 Job3 RemoteJob Running True Server02 +Id Name PSJobTypeName State HasMoreData Location +-- ---- ------------- ----- ----------- -------- + 3 Job3 RemoteJob Running True Server02 ``` To get the results of the job, use the `Receive-Job` cmdlet. @@ -281,141 +275,135 @@ TimeCreated Id LevelDisplayName Message PSComputerName ## State and Availability -The State and Availability properties of a disconnected PSSession -tell you whether the session is available for you to reconnect to it. +The State and Availability properties of a disconnected PSSession tell you +whether the session is available for you to reconnect to it. -When a PSSession is connected to the current session, its state is -Opened and its availability is Available. When you disconnect from -the PSSession, the PSSession state is Disconnected and its Availability -is none. +When a PSSession is connected to the current session, its state is Opened and +its availability is Available. When you disconnect from the PSSession, the +PSSession state is Disconnected and its Availability is none. -However, 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. However, it does not mean -that the PSSession is disconnected from all sessions. It might be -connected to a different session. +However, 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. 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, -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. +To determine whether you can connect or reconnect to the PSSession, 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. -The following example is run in two sessions (Windows PowerShell -console windows) on the same computer. Note the changing values of the -State and Availability properties in each session as the PSSession is -disconnected and reconnected. +The following example is run in two sessions (Windows PowerShell console +windows) on the same computer. Note the changing values of the State and +Availability properties in each session as the PSSession is disconnected and +reconnected. ```powershell # Session 1 PS C:\> New-PSSession -ComputerName Server30 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Opened Microsoft.PowerShell Available # Session 2 PS C:\> Get-PSSession -ComputerName Server30 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell Busy +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell Busy # Session 1 -PS C:\> Get-PSSession -ComputerName Server30 -Name Test | Disconnect-PSSession +PS C:\> Get-PSSession -ComputerName Server30 -Name Test | +>> Disconnect-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell None # Session 2 PS C:\> Get-PSSession -ComputerName Server30 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell None # Session 2 PS C:\> Connect-PSSession -ComputerName Server01 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -3 Test Server30 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +3 Test Server30 Opened Microsoft.PowerShell Available # Session 1 PS C:\> Get-PSSession -ComputerName Server30 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell Busy +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell Busy # IDLE TIMEOUT ``` -Disconnected sessions are maintained on the remote computer until -you delete them, such as by using the `Remove-PSSession` cmdlet, or -they time out. The IdleTimeout property of a PSSession determines -how long a disconnected session is maintained before it is deleted. +Disconnected sessions are maintained on the remote computer until you delete +them, such as by using the `Remove-PSSession` cmdlet, or they time out. The +IdleTimeout property of a PSSession determines how long a disconnected session +is maintained before it is deleted. PSSessions are idle when the "heartbeat thread" receives no response. -Disconnecting a session makes it idle and starts the Idle Timeout -clock, even if commands are still running in the disconnected session. -Windows PowerShell considers disconnected sessions to be active, but -idle. - -When creating and disconnecting sessions, verify that the idle -timeout in the PSSession is long enough to maintain the session -for your needs, but not so long that it consumes unnecessary -resources on the remote computer. - -The IdleTimeoutMs property of the session configuration -determines the default idle timeout of sessions that use the -session configuration. You can override the default value, but -the value that you use cannot exceed the MaxIdleTimeoutMs -property of the session configuration. - -To find the value of the IdleTimeoutMs and MaxIdleTimeoutMs -values of a session configuration, use the following command -format. +Disconnecting a session makes it idle and starts the Idle Timeout clock, even +if commands are still running in the disconnected session. Windows PowerShell +considers disconnected sessions to be active, but idle. + +When creating and disconnecting sessions, verify that the idle timeout in the +PSSession is long enough to maintain the session for your needs, but not so +long that it consumes unnecessary resources on the remote computer. + +The IdleTimeoutMs property of the session configuration determines the default +idle timeout of sessions that use the session configuration. You can override +the default value, but the value that you use cannot exceed the +MaxIdleTimeoutMs property of the session configuration. + +To find the value of the IdleTimeoutMs and MaxIdleTimeoutMs values of a +session configuration, use the following command format. ```powershell -Get-PSSessionConfiguration | Format-Table Name, IdleTimeoutMs, MaxIdleTimeoutMs +Get-PSSessionConfiguration | + Format-Table Name, IdleTimeoutMs, MaxIdleTimeoutMs ``` -You can override the default value in the session configuration and -set the idle timeout of a PSSession when you create a PSSession and -when you disconnect. +You can override the default value in the session configuration and set the +idle timeout of a PSSession when you create a PSSession and when you +disconnect. -If you are a member of the Administrators group on the remote computer, -you can also create and change the IdleTimeoutMs and MaxIdleTimeoutMs -properties of session configurations. +If you are a member of the Administrators group on the remote computer, you +can also create and change the IdleTimeoutMs and MaxIdleTimeoutMs properties +of session configurations. ## NOTES: -The idle timeout value of session configurations and session -options is in milliseconds. The idle timeout value of sessions -and session configuration options is in seconds. +The idle timeout value of session configurations and session options is in +milliseconds. The idle timeout value of sessions and session configuration +options is in seconds. -You can set the idle timeout of a PSSession when you create the -PSSession (`New-PSSession`, `Invoke-Command`) and when you disconnect -from it (`Disconnect-PSSession`). However, you cannot change the -IdleTimeout value when you connect to the PSSession -(`Connect-PSSession`) or get results (`Receive-PSSession`). +You can set the idle timeout of a PSSession when you create the PSSession +(`New-PSSession`, `Invoke-Command`) and when you disconnect from it +(`Disconnect-PSSession`). However, you cannot change the IdleTimeout value +when you connect to the PSSession (`Connect-PSSession`) or get results +(`Receive-PSSession`). The `Connect-PSSession` and `Receive-PSSession` cmdlets have a -**SessionOption** parameter that takes a SessionOption object, -such as one returned by the `New-PSSessionOption` cmdlet. However, -the IdleTimeout value in SessionOption object and the IdleTimeout -value in the $PSSessionOption preference variable do not change -the value of the IdleTimeout of the PSSession in a `Connect-PSSession` -or `Receive-PSSession` command. +**SessionOption** parameter that takes a SessionOption object, such as one +returned by the `New-PSSessionOption` cmdlet. However, the IdleTimeout value +in SessionOption object and the IdleTimeout value in the $PSSessionOption +preference variable do not change the value of the IdleTimeout of the +PSSession in a `Connect-PSSession` or `Receive-PSSession` command. * To create a PSSession with a particular idle timeout value, create a $PSSessionOption preference variable. Set the value of the IdleTimeout property to the desired value (in milliseconds). - When you create PSSessions, the values in $PSSessionOption variable - take precedence over the values in the session configuration. + When you create PSSessions, the values in $PSSessionOption variable take + precedence over the values in the session configuration. For example, this command sets an idle timeout of 48 hours. @@ -477,38 +465,35 @@ Set-PSSessionConfiguration -Name Test -TransportOption $o ## Output Buffering Mode -The output buffering mode of a PSSession determines how command -output is managed when the output buffer of the PSSession is full. +The output buffering mode of a PSSession determines how command output is +managed when the output buffer of the PSSession is full. -In a disconnected session, the output buffering mode effectively -determines whether the command continues to run while the session -is disconnected. +In a disconnected session, the output buffering mode effectively determines +whether the command continues to run while the session is disconnected. Valid values: * Block - When the output buffer is full, execution is suspended - until the buffer is clear. + When the output buffer is full, execution is suspended until the buffer is + clear. * Drop - When the output buffer is full, execution continues. - As new output is generated, the oldest output is discarded. + When the output buffer is full, execution continues. As new output is + generated, the oldest output is discarded. -Block, the default value, preserves data, but might interrupt -the command. +Block, the default value, preserves data, but might interrupt the command. -A value of Drop allows the command to complete, although data might -be lost. When using the Drop value, redirect the command output to -a file on disk. This value is recommended for disconnected sessions. +A value of Drop allows the command to complete, although data might be lost. +When using the Drop value, redirect the command output to a file on disk. This +value is recommended for disconnected sessions. -The OutputBufferingMode property of the session configuration -determines the default output buffering mode of sessions that -use the session configuration. +The OutputBufferingMode property of the session configuration determines the +default output buffering mode of sessions that use the session configuration. -To find the value of the OutputBufferingMode of a session -configuration, use the following command formats. +To find the value of the OutputBufferingMode of a session configuration, use +the following command formats. ```powershell (Get-PSSessionConfiguration ).OutputBufferingMode @@ -520,12 +505,12 @@ or Get-PSSessionConfiguration | Format-Table Name, OutputBufferingMode ``` -You can override the default value in the session configuration and set -the output buffering mode of a PSSession when you create a PSSession, -when you disconnect, and when you reconnect. +You can override the default value in the session configuration and set the +output buffering mode of a PSSession when you create a PSSession, when you +disconnect, and when you reconnect. -If you are a member of the Administrators group on the remote computer, -you can also create and change the output buffering mode of session +If you are a member of the Administrators group on the remote computer, you +can also create and change the output buffering mode of session configurations. * To create a PSSession with an output buffering mode of Drop, create @@ -609,63 +594,58 @@ Set-PSSessionConfiguration -Name Test -TransportOption $o ## Disconnecting Loopback Sessions -"Loopback sessions" or "local sessions" are PSSessions that -originate and terminate on the same computer. Like other -PSSessions, active loopback sessions are maintained on the -computer on the remote end of the connection (the local -computer), so you can disconnect from and reconnect to -loopback sessions. +"Loopback sessions" or "local sessions" are PSSessions that originate and +terminate on the same computer. Like other PSSessions, active loopback +sessions are maintained on the computer on the remote end of the connection +(the local computer), so you can disconnect from and reconnect to loopback +sessions. -By default, loopback sessions are created with a network security -token that does not permit commands run in the session to access -other computers. You can reconnect to loopback sessions that have a -network security token from any session on the local computer or a -remote computer. +By default, loopback sessions are created with a network security token that +does not permit commands run in the session to access other computers. You can +reconnect to loopback sessions that have a network security token from any +session on the local computer or a remote computer. However, if you use the **EnableNetworkAccess** parameter of the -`New-PSSession`, `Enter-PSSession`, or `Invoke-Command` cmdlet, the -loopback session is created with an interactive security token. -The interactive token enables commands that run in the loopback -session to get data from other computers. +`New-PSSession`, `Enter-PSSession`, or `Invoke-Command` cmdlet, the loopback +session is created with an interactive security token. The interactive token +enables commands that run in the loopback session to get data from other +computers. -You can disconnect loopback sessions with interactive tokens and -then reconnect to them from the same session or a different session -on the same computer. However, to prevent malicious access, you can -reconnect to loopback sessions with interactive tokens only from the -computer on which they were created. +You can disconnect loopback sessions with interactive tokens and then +reconnect to them from the same session or a different session on the same +computer. However, to prevent malicious access, you can reconnect to loopback +sessions with interactive tokens only from the computer on which they were +created. ## Waiting for Jobs in Disconnected Sessions -The `Wait-Job` cmdlet waits until a job completes and then -returns to the command prompt or the next command. By default, -`Wait-Job` returns if the session in which a job is running is -disconnected. To direct the `Wait-Job` cmdlet to wait until the -session is reconnected (in the Opened state), use the **Force** -parameter. For more information, see [Wait-Job](../Wait-Job.md). +The `Wait-Job` cmdlet waits until a job completes and then returns to the +command prompt or the next command. By default, `Wait-Job` returns if the +session in which a job is running is disconnected. To direct the `Wait-Job` +cmdlet to wait until the session is reconnected (in the Opened state), use the +**Force** parameter. For more information, see [Wait-Job](../Wait-Job.md). ## Robust Sessions and Unintentional Disconnection -Occasionally, a PSSession might be disconnected unintentionally -due to a computer failure or network outage. Windows PowerShell -attempts to recover the PSSession, but its success depends upon -the severity and duration of the cause. - -The state of an unintentionally disconnected PSSession might -be Broken or Closed, but it might also be Disconnected. If -the value of State is Disconnected, you can use the same -techniques to manage the PSSession as you would if the -session were disconnected intentionally. For example, you -can use the `Connect-PSSession` cmdlet to reconnect to the session -and the `Receive-PSSession` cmdlet to get results of commands that -ran while the session was disconnected. - -If you close (exit) the session in which a PSSession was -created while commands are running in the PSSession, Windows -PowerShell maintains the PSSession in the Disconnected state -on the remote computer. If you close (exit) the session in -which a PSSession was created, but no commands are running -in the PSSession, Windows PowerShell does not attempt to -maintain the PSSession. +Occasionally, a PSSession might be disconnected unintentionally due to a +computer failure or network outage. Windows PowerShell attempts to recover the +PSSession, but its success depends upon the severity and duration of the +cause. + +The state of an unintentionally disconnected PSSession might be Broken or +Closed, but it might also be Disconnected. If the value of State is +Disconnected, you can use the same techniques to manage the PSSession as you +would if the session were disconnected intentionally. For example, you can use +the `Connect-PSSession` cmdlet to reconnect to the session and the +`Receive-PSSession` cmdlet to get results of commands that ran while the +session was disconnected. + +If you close (exit) the session in which a PSSession was created while +commands are running in the PSSession, Windows PowerShell maintains the +PSSession in the Disconnected state on the remote computer. If you close +(exit) the session in which a PSSession was created, but no commands are +running in the PSSession, Windows PowerShell does not attempt to maintain the +PSSession. ## See Also diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md index 3c4c6936b01..93fb4c492c5 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,344 +7,512 @@ title: about_Remote_FAQ --- # About Remote FAQ -## about_Remote_FAQ - ## SHORT DESCRIPTION -Contains questions and answers about running remote commands in Windows PowerShell®. +Contains questions and answers about running remote commands in Windows +PowerShell. ## LONG DESCRIPTION -When you work remotely, you type commands in Windows PowerShell on one computer (known as the "local computer"), but the commands run on another computer (known as the "remote computer"). The experience of working remotely should be as much like working directly at the remote computer as possible. - - -``` -Note: To use Windows PowerShell remoting, the remote computer - must be configured for remoting. For more information, see - about_Remote_Requirements. -``` +When you work remotely, you type commands in Windows PowerShell on one +computer (known as the "local computer"), but the commands run on another +computer (known as the "remote computer"). The experience of working remotely +should be as much like working directly at the remote computer as possible. +Note: To use Windows PowerShell remoting, the remote computer must be +configured for remoting. For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). ### MUST BOTH COMPUTERS HAVE WINDOWS POWERSHELL INSTALLED? -Yes. To work remotely, the local and remote computers must have Windows PowerShell, the Microsoft .NET Framework, and the Web Services for Management (WS-Management) protocol. Any files and other resources that are needed to execute a particular command must be on the remote computer. -Computers running Windows PowerShell 3.0 and computers running Windows PowerShell 2.0 can connect to each other remotely and run remote commands. However, some features, such as the ability to disconnect from a session and reconnect to it, work only when both computers are running Windows PowerShell 3.0. +Yes. To work remotely, the local and remote computers must have Windows +PowerShell, the Microsoft .NET Framework, and the Web Services for Management +(WS-Management) protocol. Any files and other resources that are needed to +execute a particular command must be on the remote computer. -You must have permission to connect to the remote computer, permission to run Windows PowerShell, and permission to access data stores (such as files and folders), and the registry on the remote computer. +Computers running Windows PowerShell 3.0 and computers running Windows +PowerShell 2.0 can connect to each other remotely and run remote commands. +However, some features, such as the ability to disconnect from a session and +reconnect to it, work only when both computers are running Windows PowerShell +3.0. -For more information, see about_Remote_Requirements. +You must have permission to connect to the remote computer, permission to run +Windows PowerShell, and permission to access data stores (such as files and +folders), and the registry on the remote computer. +For more information, see [about_Remote_Requirements](about_Remote_Requirements.md). ### HOW DOES REMOTING WORK? -When you submit a remote command, the command is transmitted across the network to the Windows PowerShell engine on the remote computer, and it runs in the Windows PowerShell client on the remote computer. The command results are sent back to the local computer and appear in the Windows PowerShell session on the local computer. -To transmit the commands and receive the output, Windows PowerShell uses the WS-Management protocol. For information about the WS-Management protocol, see "WS-Management Protocol" in the MSDN (Microsoft Developer Network) library at http:\/\/go.microsoft.com\/fwlink\/?LinkId\=144634. +When you submit a remote command, the command is transmitted across the +network to the Windows PowerShell engine on the remote computer, and it runs +in the Windows PowerShell client on the remote computer. The command results +are sent back to the local computer and appear in the Windows PowerShell +session on the local computer. -Beginning in Windows PowerShell 3.0, remote sessions are stored on the remote computer. This enables you to disconnect from the session and reconnect from a different session or a different computer without interrupting the commands or losing state. +To transmit the commands and receive the output, Windows PowerShell uses the +WS-Management protocol. For information about the WS-Management protocol, see +[WS-Management Protocol](http://go.microsoft.com\/fwlink/?LinkId=144634) in +the MSDN library. +Beginning in Windows PowerShell 3.0, remote sessions are stored on the remote +computer. This enables you to disconnect from the session and reconnect from a +different session or a different computer without interrupting the commands or +losing state. ### IS WINDOWS POWERSHELL REMOTING SECURE? -When you connect to a remote computer, the system uses the user name and password credentials on the local computer or the credentials that you supply in the command to log you in to the remote computer. The credentials and the rest of the transmission are encrypted. -To add additional protection, you can configure the remote computer to use Secure Sockets Layer (SSL) instead of HTTP to listen for Windows Remote Management (WinRM) requests. Then, users can use the UseSSL parameters of the Invoke-Command, New-PSSession, and Enter-PSSession cmdlets when establishing a connection. This option uses the more secure HTTPS channel instead of HTTP. +When you connect to a remote computer, the system uses the user name and +password credentials on the local computer or the credentials that you supply +in the command to log you in to the remote computer. The credentials and the +rest of the transmission are encrypted. +To add additional protection, you can configure the remote computer to use +Secure Sockets Layer (SSL) instead of HTTP to listen for Windows Remote +Management (WinRM) requests. Then, users can use the UseSSL parameters of the +Invoke-Command, New-PSSession, and Enter-PSSession cmdlets when establishing a +connection. This option uses the more secure HTTPS channel instead of HTTP. ### DO ALL REMOTE COMMANDS REQUIRE WINDOWS POWERSHELL REMOTING? -No. Several cmdlets have a ComputerName parameter that lets you get objects from the remote computer. - -These cmdlets do not use Windows PowerShell remoting. So, you can use them on any computer that is running Windows PowerShell, even if the computer is not configured for Windows PowerShell remoting or if the computer does not meet the requirements for Windows PowerShell remoting. -These cmdlets include the following cmdlets: +No. Several cmdlets have a ComputerName parameter that lets you get objects +from the remote computer. +These cmdlets do not use Windows PowerShell remoting. So, you can use them on +any computer that is running Windows PowerShell, even if the computer is not +configured for Windows PowerShell remoting or if the computer does not meet +the requirements for Windows PowerShell remoting. -``` -Get-Process -Get-Service -Get-WinEvent -Get-EventLog -Get-WmiObject -Test-Connection -``` +These cmdlets include the following: +- Get-Process +- Get-Service +- Get-WinEvent +- Get-EventLog +- Get-WmiObject +- Test-Connection To find all the cmdlets with a ComputerName parameter, type: - -``` -Get-Help * -Parameter ComputerName -or +```powershell +Get-Help * -Parameter ComputerName +# or Get-Command -ParameterName ComputerName ``` +To determine whether the ComputerName parameter of a particular cmdlet +requires Windows PowerShell remoting, see the parameter description. To +display the parameter description, type: -To determine whether the ComputerName parameter of a particular cmdlet requires Windows PowerShell remoting, see the parameter description. To display the parameter description, type: - - -``` +```ppowershell Get-Help -Parameter ComputerName ``` - For example: - -``` +```powershell Get-Help Get-Process -Parameter Computername ``` - For all other commands, use the Invoke-Command cmdlet. - ### HOW DO I RUN A COMMAND ON A REMOTE COMPUTER? + To run a command on a remote computer, use the Invoke-Command cmdlet. -Enclose your command in braces ( {} ) to make it a script block. Use the ScriptBlock parameter of Invoke-Command to specify the command. +Enclose your command in braces ( {} ) to make it a script block. Use the +ScriptBlock parameter of Invoke-Command to specify the command. -You can use the ComputerName parameter of Invoke-Command to specify a remote computer. Or, you can create a persistent connection to a remote computer (a session) and then use the Session parameter of Invoke-Command to run the command in the session. +You can use the ComputerName parameter of Invoke-Command to specify a remote +computer. Or, you can create a persistent connection to a remote computer (a +session) and then use the Session parameter of Invoke-Command to run the +command in the session. For example, the following commands run a Get-Process command remotely. +```powershell +Invoke-Command -ComputerName Server01, Server02 -ScriptBlock {Get-Process} + +# - OR - -``` -Invoke-Command -ComputerName Server01, Server02 -ScriptBlock {Get-Process} - - - OR - - Invoke-Command -Session $s -ScriptBlock {Get-Process} ``` +To interrupt a remote command, type CTRL\+C. The interruption request is +passed to the remote computer, where it terminates the remote command. -To interrupt a remote command, type CTRL\+C. The interruption request is passed to the remote computer, where it terminates the remote command. - -For more information about remote commands, see about_Remote and the Help topics for the cmdlets that support remoting. - +For more information about remote commands, see about_Remote and the Help +topics for the cmdlets that support remoting. ### CAN I JUST "TELNET INTO" A REMOTE COMPUTER? -You can use the Enter-PSSession cmdlet to start an interactive session with a remote computer. -At the Windows PowerShell prompt, type: +You can use the Enter-PSSession cmdlet to start an interactive session with a +remote computer. +At the Windows PowerShell prompt, type: -``` +```powershell Enter-PSSession ``` - -The command prompt changes to show that you are connected to the remote computer. - +The command prompt changes to show that you are connected to the remote +computer. ``` \C:> ``` - -Now, the commands that you type run on the remote computer just as though you typed them directly on the remote computer. +Now, the commands that you type run on the remote computer just as though you +typed them directly on the remote computer. To end the interactive session, type: - -``` +```powershell Exit-PSSession ``` - -An interactive session is a persistent session that uses the WS-Management protocol. It is not the same as using Telnet, but it provides a similar experience. +An interactive session is a persistent session that uses the WS-Management +protocol. It is not the same as using Telnet, but it provides a similar +experience. For more information, see Enter-PSSession. - ### CAN I CREATE A PERSISTENT CONNECTION? -Yes. You can run remote commands by specifying the name of the remote computer, its NetBIOS name, or its IP address. Or, you can run remote commands by specifying a Windows PowerShell session (PSSession) that is connected to the remote computer. -When you use the ComputerName parameter of Invoke-Command or Enter-PSSession, Windows PowerShell establishes a temporary connection. Windows PowerShell uses the connection to run only the current command, and then it closes the connection. This is a very efficient method for running a single command or several unrelated commands, even on many remote computers. +Yes. You can run remote commands by specifying the name of the remote +computer, its NetBIOS name, or its IP address. Or, you can run remote commands +by specifying a Windows PowerShell session (PSSession) that is connected to +the remote computer. -When you use the New-PSSession cmdlet to create a PSSession, Windows PowerShell establishes a persistent connection for the PSSession. Then, you can run multiple commands in the PSSession, including commands that share data. +When you use the ComputerName parameter of Invoke-Command or Enter-PSSession, +Windows PowerShell establishes a temporary connection. Windows PowerShell uses +the connection to run only the current command, and then it closes the +connection. This is a very efficient method for running a single command or +several unrelated commands, even on many remote computers. -Typically, you create a PSSession to run a series of related commands that share data. Otherwise, the temporary connection created by the ComputerName parameter is sufficient for most commands. +When you use the New-PSSession cmdlet to create a PSSession, Windows +PowerShell establishes a persistent connection for the PSSession. Then, you +can run multiple commands in the PSSession, including commands that share +data. -For more information about sessions, see about_PSSessions. +Typically, you create a PSSession to run a series of related commands that +share data. Otherwise, the temporary connection created by the ComputerName +parameter is sufficient for most commands. +For more information about sessions, see about_PSSessions. ### CAN I RUN COMMANDS ON MORE THAN ONE COMPUTER AT A TIME? -Yes. The ComputerName parameter of the Invoke-Command cmdlet accepts multiple computer names, and the Session parameter accepts multiple PSSessions. -When you run an Invoke-Command command, Windows PowerShell runs the commands on all of the specified computers or in all of the specified PSSessions. +Yes. The ComputerName parameter of the Invoke-Command cmdlet accepts multiple +computer names, and the Session parameter accepts multiple PSSessions. -Windows PowerShell can manage hundreds of concurrent remote connections. However, the number of remote commands that you can send might be limited by the resources of your computer and its capacity to establish and maintain multiple network connections. +When you run an Invoke-Command command, Windows PowerShell runs the commands +on all of the specified computers or in all of the specified PSSessions. -For more information, see the example in the Invoke-Command Help topic. +Windows PowerShell can manage hundreds of concurrent remote connections. +However, the number of remote commands that you can send might be limited by +the resources of your computer and its capacity to establish and maintain +multiple network connections. +For more information, see the example in the Invoke-Command Help topic. ### WHERE ARE MY PROFILES? -Windows PowerShell profiles are not run automatically in remote sessions, so the commands that the profile adds are not present in the session. In addition, the $profile automatic variable is not populated in remote sessions. -To run a profile in a session, use the Invoke-Command cmdlet. +Windows PowerShell profiles are not run automatically in remote sessions, so +the commands that the profile adds are not present in the session. In +addition, the \$profile automatic variable is not populated in remote sessions. -For example, the following command runs the CurrentUserCurrentHost profile from the local computer in the session in $s. +To run a profile in a session, use the `Invoke-Command` cmdlet. +For example, the following command runs the CurrentUserCurrentHost profile +from the local computer in the session in \$s. ``` Invoke-Command -Session $s -FilePath $profile ``` +The following command runs the CurrentUserCurrentHost profile from the remote +computer in the session in $s. Because the $profile variable is not populated, +the command uses the explicit path to the profile. -The following command runs the CurrentUserCurrentHost profile from the remote computer in the session in $s. Because the $profile variable is not populated, the command uses the explicit path to the profile. - - -``` -Invoke-Command -Session $s {. "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1"} +```powershell +Invoke-Command -Session $s { + . "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1" +} ``` +After running this command, the commands that the profile adds to the session +are available in $s. -After running this command, the commands that the profile adds to the session are available in $s. - -You can also use a startup script in a session configuration to run a profile in every remote session that uses the session configuration. - -For more information about Windows PowerShell profiles, see about_Profiles. For more information about session configurations, see Register-PSSessionConfiguration. +You can also use a startup script in a session configuration to run a profile +in every remote session that uses the session configuration. +For more information about Windows PowerShell profiles, see about_Profiles. +For more information about session configurations, see +Register-PSSessionConfiguration. ### HOW DOES THROTTLING WORK ON REMOTE COMMANDS? -To help you manage the resources on your local computer, Windows PowerShell includes a per-command throttling feature that lets you limit the number of concurrent remote connections that are established for each command. -The default is 32 concurrent connections, but you can use the ThrottleLimit parameters of the cmdlets to set a custom throttle limit for particular commands. +To help you manage the resources on your local computer, Windows PowerShell +includes a per-command throttling feature that lets you limit the number of +concurrent remote connections that are established for each command. -When you use the throttling feature, remember that it is applied to each command, not to the entire session or to the computer. If you are running commands concurrently in several sessions or PSSessions, the number of concurrent connections is the sum of the concurrent connections in all the sessions. +The default is 32 concurrent connections, but you can use the **ThrottleLimit** +parameters of the cmdlets to set a custom throttle limit for particular +commands. -To find cmdlets with a ThrottleLimit parameter, type: +When you use the throttling feature, remember that it is applied to each +command, not to the entire session or to the computer. If you are running +commands concurrently in several sessions or PSSessions, the number of +concurrent connections is the sum of the concurrent connections in all the +sessions. +To find cmdlets with a ThrottleLimit parameter, type: ``` -Get-Help * -Parameter ThrottleLimit --or- +Get-Help * -Parameter ThrottleLimit +-or- Get-Command -ParameterName ThrottleLimit ``` - ### IS THE OUTPUT OF REMOTE COMMANDS DIFFERENT FROM LOCAL OUTPUT? -When you use Windows PowerShell locally, you send and receive "live" .NET Framework objects; "live" objects are objects that are associated with actual programs or system components. When you invoke the methods or change the properties of live objects, the changes affect the actual program or component. And, when the properties of a program or component change, the properties of the object that represent them also change. -However, because most live objects cannot be transmitted over the network, Windows PowerShell "serializes" most of the objects sent in remote commands, that is, it converts each object into a series of XML (Constraint Language in XML [CLiXML]) data elements for transmission. +When you use Windows PowerShell locally, you send and receive "live" .NET +Framework objects; "live" objects are objects that are associated with actual +programs or system components. When you invoke the methods or change the +properties of live objects, the changes affect the actual program or +component. And, when the properties of a program or component change, the +properties of the object that represent them also change. -When Windows PowerShell receives a serialized object, it converts the XML into a deserialized object type. The deserialized object is an accurate record of the properties of the program or component at a previous time, but it is no longer "live", that is, it is no longer directly associated with the component. And, the methods are removed because they are no longer effective. +However, because most live objects cannot be transmitted over the network, +Windows PowerShell "serializes" most of the objects sent in remote commands, +that is, it converts each object into a series of XML (Constraint Language in +XML [CLiXML]) data elements for transmission. -Typically, you can use deserialized objects just as you would use live objects, but you must be aware of their limitations. Also, the objects that are returned by the Invoke-Command cmdlet have additional properties that help you to determine the origin of the command. +When Windows PowerShell receives a serialized object, it converts the XML into +a deserialized object type. The deserialized object is an accurate record of +the properties of the program or component at a previous time, but it is no +longer "live", that is, it is no longer directly associated with the +component. And, the methods are removed because they are no longer effective. -Some object types, such as DirectoryInfo objects and GUIDs, are converted back into live objects when they are received. These objects do not need any special handling or formatting. +Typically, you can use deserialized objects just as you would use live +objects, but you must be aware of their limitations. Also, the objects that +are returned by the Invoke-Command cmdlet have additional properties that help +you to determine the origin of the command. -For information about interpreting and formatting remote output, see about_Remote_Output. +Some object types, such as DirectoryInfo objects and GUIDs, are converted back +into live objects when they are received. These objects do not need any +special handling or formatting. +For information about interpreting and formatting remote output, see +[about_Remote_Output](about_Remote_Output.md). ### CAN I RUN BACKGROUND JOBS REMOTELY? -Yes. A Windows PowerShell background job is a Windows PowerShell command that runs asynchronously without interacting with the session. When you start a background job, the command prompt returns immediately, and you can continue to work in the session while the job runs even if it runs for an extended period of time. -You can start a background job even while other commands are running because background jobs always run asynchronously in a temporary session. +Yes. A Windows PowerShell background job is a Windows PowerShell command that +runs asynchronously without interacting with the session. When you start a +background job, the command prompt returns immediately, and you can continue +to work in the session while the job runs even if it runs for an extended +period of time. -You can run background jobs on a local or remote computer. By default, a background job runs on the local computer. However, you can use the AsJob parameter of the Invoke-Command cmdlet to run any remote command as a background job. And, you can use Invoke-Command to run a Start-Job command remotely. +You can start a background job even while other commands are running because +background jobs always run asynchronously in a temporary session. -For more information about background jobs in Windows PowerShell , see about_Jobs and about_Remote_Jobs. +You can run background jobs on a local or remote computer. By default, a +background job runs on the local computer. However, you can use the AsJob +parameter of the Invoke-Command cmdlet to run any remote command as a +background job. And, you can use Invoke-Command to run a Start-Job command +remotely. +For more information about background jobs in Windows PowerShell , see +[about_Jobs(about_Jobs.md)] and [about_Remote_Jobs(about_Remote_Jobs.md)]. ### CAN I RUN WINDOWS PROGRAMS ON A REMOTE COMPUTER? -You can use Windows PowerShell remote commands to run Windows-based programs on remote computers. For example, you can run Shutdown.exe or Ipconfig on a remote computer. -However, you cannot use Windows PowerShell commands to open the user interface for any program on a remote computer. +You can use Windows PowerShell remote commands to run Windows-based programs +on remote computers. For example, you can run Shutdown.exe or Ipconfig on a +remote computer. -When you start a Windows program on a remote computer, the command is not completed, and the Windows PowerShell command prompt does not return, until the program is finished or until you press CTRL\+C to interrupt the command. For example, if you run the IpConfig program on a remote computer, the command prompt does not return until IpConfig is completed. +However, you cannot use Windows PowerShell commands to open the user interface +for any program on a remote computer. -If you use remote commands to start a program that has a user interface, the program process starts, but the user interface does not appear. The Windows PowerShell command is not completed, and the command prompt does not return until you stop the program process or until you press CTRL\+C, which interrupts the command and stops the process. +When you start a Windows program on a remote computer, the command is not +completed, and the Windows PowerShell command prompt does not return, until +the program is finished or until you press CTRL\+C to interrupt the command. +For example, if you run the IpConfig program on a remote computer, the command +prompt does not return until IpConfig is completed. -For example, if you use a Windows PowerShell command to run Notepad on a remote computer, the Notepad process starts on the remote computer, but the Notepad user interface does not appear. To interrupt the command and restore the command prompt, press CTRL\+C. +If you use remote commands to start a program that has a user interface, the +program process starts, but the user interface does not appear. The Windows +PowerShell command is not completed, and the command prompt does not return +until you stop the program process or until you press CTRL\+C, which +interrupts the command and stops the process. +For example, if you use a Windows PowerShell command to run Notepad on a +remote computer, the Notepad process starts on the remote computer, but the +Notepad user interface does not appear. To interrupt the command and restore +the command prompt, press CTRL\+C. ### CAN I LIMIT THE COMMANDS THAT USERS CAN RUN REMOTELY ON MY COMPUTER? -Yes. Every remote session must use one of the session configurations on the remote computer. You can manage the session configurations on your computer (and the permissions to those session configurations) to determine who can run commands remotely on your computer and which commands they can run. - -A session configuration configures the environment for the session. You can define the configuration by using an assembly that implements a new configuration class or by using a script that runs in the session. The configuration can determine the commands that are available in the session. And, the configuration can include settings that protect the computer, such as settings that limit the amount of data that the session can receive remotely in a single object or command. You can also specify a security descriptor that determines the permissions that are required to use the configuration. - -The Enable-PSRemoting cmdlet creates the default session configurations on your computer: Microsoft.PowerShell, Microsoft.PowerShell.Workflow, and Microsoft.PowerShell32 (64-bit operating systems only). Enable-PSRemoting sets the security descriptor for the configuration to allow only members of the Administrators group on your computer to use them. - -You can use the session configuration cmdlets to edit the default session configurations, to create new session configurations, and to change the security descriptors of all the session configurations. -Beginning in Windows PowerShell 3.0, the New-PSSessionConfigurationFile cmdlet lets you create custom session configurations by using a text file. The file includes options for setting the language mode and for specifying the cmdlets and modules that are available in sessions that use the session configuration. - -When users use the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets, they can use the ConfigurationName parameter to indicate the session configuration that is used for the session. And, they can change the default configuration that their sessions use by changing the value of the $PSSessionConfigurationName preference variable in the session. - -For more information about session configurations, see the Help for the session configuration cmdlets. To find the session configuration cmdlets, type: - - -``` +Yes. Every remote session must use one of the session configurations on the +remote computer. You can manage the session configurations on your computer +(and the permissions to those session configurations) to determine who can run +commands remotely on your computer and which commands they can run. + +A session configuration configures the environment for the session. You can +define the configuration by using an assembly that implements a new +configuration class or by using a script that runs in the session. The +configuration can determine the commands that are available in the session. +And, the configuration can include settings that protect the computer, such as +settings that limit the amount of data that the session can receive remotely +in a single object or command. You can also specify a security descriptor that +determines the permissions that are required to use the configuration. + +The Enable-PSRemoting cmdlet creates the default session configurations on +your computer: Microsoft.PowerShell, Microsoft.PowerShell.Workflow, and +Microsoft.PowerShell32 (64-bit operating systems only). Enable-PSRemoting sets +the security descriptor for the configuration to allow only members of the +Administrators group on your computer to use them. + +You can use the session configuration cmdlets to edit the default session +configurations, to create new session configurations, and to change the +security descriptors of all the session configurations. + +Beginning in Windows PowerShell 3.0, the New-PSSessionConfigurationFile cmdlet +lets you create custom session configurations by using a text file. The file +includes options for setting the language mode and for specifying the cmdlets +and modules that are available in sessions that use the session configuration. + +When users use the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets, +they can use the ConfigurationName parameter to indicate the session +configuration that is used for the session. And, they can change the default +configuration that their sessions use by changing the value of the +$PSSessionConfigurationName preference variable in the session. + +For more information about session configurations, see the Help for the +session configuration cmdlets. To find the session configuration cmdlets, +type: + +```powershell Get-Command *PSSessionConfiguration ``` - - ### WHAT ARE FAN-IN AND FAN OUT CONFIGURATIONS? -The most common Windows PowerShell remoting scenario involving multiple computers is the one-to-many configuration, in which one local computer (the administrator's computer) runs Windows PowerShell commands on numerous remote computers. This is known as the "fan-out" scenario. -However, in some enterprises, the configuration is many-to-one, where many client computers connect to a single remote computer that is running Windows PowerShell, such as a file server or a kiosk. This is known as the "fan-in" configuration. +The most common Windows PowerShell remoting scenario involving multiple +computers is the one-to-many configuration, in which one local computer (the +administrator's computer) runs Windows PowerShell commands on numerous remote +computers. This is known as the "fan-out" scenario. -Windows PowerShell remoting supports both fan-out and fan-in configurations. +However, in some enterprises, the configuration is many-to-one, where many +client computers connect to a single remote computer that is running Windows +PowerShell, such as a file server or a kiosk. This is known as the "fan-in" +configuration. -For the fan-out configuration, Windows PowerShell uses the Web Services for Management (WS-Management) protocol and the WinRM service that supports the Microsoft implementation of WS-Management. When a local computer connects to a remote computer, WS-Management establishes a connection and uses a plug-in for Windows PowerShell to start the Windows PowerShell host process (Wsmprovhost.exe) on the remote computer. The user can specify an alternate port, an alternate session configuration, and other features to customize the remote connection. +Windows PowerShell remoting supports both fan-out and fan-in configurations. -To support the "fan-in" configuration, Windows PowerShell uses Internet Information Services (IIS) to host WS-Management, to load the Windows PowerShell plug-in, and to start Windows PowerShell. In this scenario, instead of starting each Windows PowerShell session in a separate process, all Windows PowerShell sessions run in the same host process. +For the fan-out configuration, Windows PowerShell uses the Web Services for +Management (WS-Management) protocol and the WinRM service that supports the +Microsoft implementation of WS-Management. When a local computer connects to a +remote computer, WS-Management establishes a connection and uses a plug-in for +Windows PowerShell to start the Windows PowerShell host process +(Wsmprovhost.exe) on the remote computer. The user can specify an alternate +port, an alternate session configuration, and other features to customize the +remote connection. -IIS hosting and fan-in remote management is not supported in Windows XP or in Windows Server 2003. +To support the "fan-in" configuration, Windows PowerShell uses Internet +Information Services (IIS) to host WS-Management, to load the Windows +PowerShell plug-in, and to start Windows PowerShell. In this scenario, instead +of starting each Windows PowerShell session in a separate process, all Windows +PowerShell sessions run in the same host process. -In a fan-in configuration, the user can specify a connection URI and an HTTP endpoint, including the transport, computer name, port, and application name. IIS forwards all the requests with a specified application name to the application. The default is WS-Management, which can host Windows PowerShell. +IIS hosting and fan-in remote management is not supported in Windows XP or in +Windows Server 2003. -You can also specify an authentication mechanism and prohibit or allow redirection from HTTP and HTTPS endpoints. +In a fan-in configuration, the user can specify a connection URI and an HTTP +endpoint, including the transport, computer name, port, and application name. +IIS forwards all the requests with a specified application name to the +application. The default is WS-Management, which can host Windows PowerShell. +You can also specify an authentication mechanism and prohibit or allow +redirection from HTTP and HTTPS endpoints. ### CAN I TEST REMOTING ON A SINGLE COMPUTER \(NOT IN A DOMAIN\)? -Yes. Windows PowerShell remoting is available even when the local computer is not in a domain. You can use the remoting features to connect to sessions and to create sessions on the same computer. The features work the same as they do when you connect to a remote computer. -To run remote commands on a computer in a workgroup, change the following Windows settings on the computer. +Yes. Windows PowerShell remoting is available even when the local computer is +not in a domain. You can use the remoting features to connect to sessions and +to create sessions on the same computer. The features work the same as they do +when you connect to a remote computer. -Caution: These settings affect all users on the system and they can make the system more vulnerable to a malicious attack. Use caution when making these changes. +To run remote commands on a computer in a workgroup, change the following +Windows settings on the computer. --- Windows XP with SP2: +Caution: These settings affect all users on the system and they can make the +system more vulnerable to a malicious attack. Use caution when making these +changes. -Use Local Security Settings (Secpol.msc) to change the setting of the "Network Access: Sharing and security model for local accounts" policy in Security Settings\Local Policies\Security Options to "Classic". +- Windows XP with SP2: --- Windows Vista, Windows 7, Windows 8: + Use Local Security Settings (Secpol.msc) to change the setting of the + "Network Access: Sharing and security model for local accounts" policy in + Security Settings\Local Policies\Security Options to "Classic". -Create the following registry entry, and then set its value to 1: LocalAccountTokenFilterPolicy in HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System +- Windows Vista, Windows 7, Windows 8: -You can use the following Windows PowerShell command to add this entry: + Create the following registry entry, and then set its value to 1: + LocalAccountTokenFilterPolicy in + HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System -New-ItemProperty ` -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System ` -Name LocalAccountTokenFilterPolicy -propertyType DWord -Value 1 + You can use the following Windows PowerShell command to add this entry: --- Windows Server 2003, Windows Server 2008, Windows Server 2012, Windows Server 2012 R2: + ```powershell + $parameters = @{ + Path='HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System' + Name='LocalAccountTokenFilterPolicy' + propertyType='DWord' + Value=1 + } + New-ItemProperty @parameters + ``` -No changes are needed because the default setting of the "Network Access: Sharing and security model for local accounts" policy is "Classic". Verify the setting in case it has changed. +- Windows Server 2003, Windows Server 2008, Windows Server 2012, Windows + Server 2012 R2: + No changes are needed because the default setting of the "Network Access: + Sharing and security model for local accounts" policy is "Classic". Verify + the setting in case it has changed. ### CAN I RUN REMOTE COMMANDS ON A COMPUTER IN ANOTHER DOMAIN? -Yes. Typically, the commands run without error, although you might need to use the Credential parameter of the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets to provide the credentials of a member of the Administrators group on the remote computer. This is sometimes required even when the current user is a member of the Administrators group on the local and remote computers. -However, if the remote computer is not in a domain that the local computer trusts, the remote computer might not be able to authenticate the user's credentials. +Yes. Typically, the commands run without error, although you might need to use +the **Credential** parameter of the `Invoke-Command`, `New-PSSession`, or +`Enter-PSSession` cmdlets to provide the credentials of a member of the +Administrators group on the remote computer. This is sometimes required even +when the current user is a member of the Administrators group on the local and +remote computers. -To enable authentication, use the following command to add the remote computer to the list of trusted hosts for the local computer in WinRM. Type the command at the Windows PowerShell prompt. +However, if the remote computer is not in a domain that the local computer +trusts, the remote computer might not be able to authenticate the user's +credentials. +To enable authentication, use the following command to add the remote computer +to the list of trusted hosts for the local computer in WinRM. Type the command +at the Windows PowerShell prompt. -``` +```powershell Set-Item WSMan:\localhost\Client\TrustedHosts -Value ``` +For example, to add the Server01 computer to the list of trusted hosts on the +local computer, type the following command at the Windows PowerShell prompt: -For example, to add the Server01 computer to the list of trusted hosts on the local computer, type the following command at the Windows PowerShell prompt: - - -``` +```powershell Set-Item WSMan:\localhost\Client\TrustedHosts -Value Server01 ``` - - ## SEE ALSO [about_Remote](about_Remote.md) @@ -357,7 +525,7 @@ Set-Item WSMan:\localhost\Client\TrustedHosts -Value Server01 [about_Remote_Variables](about_Remote_Variables.md) -Invoke-Command +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[New-PSSession](../New-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md index 484b7285a6a..91f9354775f 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,272 +7,338 @@ title: about_Remote_Jobs --- # About Remote Jobs -## about_Remote_Jobs - ## SHORT DESCRIPTION -Describes how to run background jobs on remote computers. +Describes how to run background jobs on remote computers. ## DETAILED DESCRIPTION -A background job is a command that runs asynchronously without interacting with the current session. The command prompt returns immediately, and you can continue to use the session while the job runs. -By default, background jobs run on the local computer. However, you can use several different procedures to run background jobs on remote computers. +A background job is a command that runs asynchronously without interacting +with the current session. The command prompt returns immediately, and you can +continue to use the session while the job runs. -This topic explains how to run a background job on a remote computer. For information about how to run background jobs on a local computer, see about_Jobs. For more information about background jobs, see about_Job_Details. +By default, background jobs run on the local computer. However, you can use +several different procedures to run background jobs on remote computers. +This topic explains how to run a background job on a remote computer. For +information about how to run background jobs on a local computer, see +[about_Jobs](about_Jobs.md). For more information about background jobs, see +[about_Job_Details](about_Job_Details.md). ## REMOTE BACKGROUND JOBS -You can run background jobs on remote computers by using three different methods. --- Start an interactive session with a remote computer, and start a job in the interactive session. The procedures are the same as running a local job, although all actions are performed on the remote computer. +You can run background jobs on remote computers by using three different +methods. --- Run a background job on a remote computer that returns its results to the local computer. Use this method when you want to collect the results of background jobs and maintain them in a central location on the local computer. +- Start an interactive session with a remote computer, and start a job in the + interactive session. The procedures are the same as running a local job, + although all actions are performed on the remote computer. --- Run a background job on a remote computer that maintains its results on the remote computer. Use this method when the job data is more securely maintained on the originating computer. +- Run a background job on a remote computer that returns its results to the + local computer. Use this method when you want to collect the results of + background jobs and maintain them in a central location on the local computer. +- Run a background job on a remote computer that maintains its results on the + remote computer. Use this method when the job data is more securely maintained + on the originating computer. ### START A BACKGROUND JOB IN AN INTERACTIVE SESSION -You can start an interactive session with a remote computer and then start a background job during the interactive session. For more information about interactive sessions, see about_Remote, and see Enter-PSSession. -The procedure for starting a background job in an interactive session is almost identical to the procedure for starting a background job on the local computer. However, all of the operations occur on the remote computer, not the local computer. +You can start an interactive session with a remote computer and then start a +background job during the interactive session. For more information about +interactive sessions, see about_Remote, and see Enter-PSSession. +The procedure for starting a background job in an interactive session is +almost identical to the procedure for starting a background job on the local +computer. However, all of the operations occur on the remote computer, not the +local computer. #### STEP 1: ENTER-PSSESSION -Use the Enter-PSSession cmdlet to start an interactive session with a remote computer. You can use the ComputerName parameter of Enter-PSSession to establish a temporary connection for the interactive session. Or, you can use the Session parameter to run the interactive session in a Windows PowerShell® session (PSSession). -The following command starts an interactive session on the Server01 computer. +Use the Enter-PSSession cmdlet to start an interactive session with a remote +computer. You can use the ComputerName parameter of Enter-PSSession to +establish a temporary connection for the interactive session. Or, you can use +the Session parameter to run the interactive session in a Windows PowerShell +session (PSSession). +The following command starts an interactive session on the Server01 computer. -``` +```powershell C:\PS> Enter-PSSession -computername Server01 ``` - -The command prompt changes to show that you are now connected to the Server01 computer. - +The command prompt changes to show that you are now connected to the Server01 +computer. ``` Server01\C:> ``` - - #### STEP 2: START-JOB -To start a background job in the session, use the Start-Job cmdlet. -The following command runs a background job that gets the events in the Windows PowerShell event log on the Server01 computer. The Start-Job cmdlet returns an object that represents the job. +To start a background job in the session, use the Start-Job cmdlet. -This command saves the job object in the $job variable. +The following command runs a background job that gets the events in the +Windows PowerShell event log on the Server01 computer. The Start-Job cmdlet +returns an object that represents the job. +This command saves the job object in the \$job variable. -``` -Server01\C:> $job = start-job -scriptblock {get-eventlog "Windows PowerShell"} +```powershell +Server01\C:> $job = start-job -scriptblock { + get-eventlog "Windows PowerShell" +} ``` - -While the job runs, you can use the interactive session to run other commands, including other background jobs. However, you must keep the interactive session open until the job is completed. If you end the session, the job is interrupted, and the results are lost. - +While the job runs, you can use the interactive session to run other commands, +including other background jobs. However, you must keep the interactive +session open until the job is completed. If you end the session, the job is +interrupted, and the results are lost. #### STEP 3: GET-JOB -To find out if the job is complete, display the value of the $job variable, or use the Get-Job cmdlet to get the job. The following command uses the Get-Job cmdlet to display the job. +To find out if the job is complete, display the value of the \$job variable, +or use the Get-Job cmdlet to get the job. The following command uses the +Get-Job cmdlet to display the job. -``` -Server01\C:> get-job $job - -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Complete True localhost get-eventlog "Windows PowerShell" -``` - +```powershell +Server01\C:> get-job $job -The Get-Job output shows that job is running on the "localhost" computer because the job was started on and is running on the same computer (in this case, Server01). +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Complete True localhost get-eventlog "Windows... +``` +The Get-Job output shows that job is running on the "localhost" computer +because the job was started on and is running on the same computer (in this +case, Server01). #### STEP 4: RECEIVE-JOB -To get the results of the job, use the Receive-Job cmdlet. You can display the results in the interactive session or save them to a file on the remote computer. The following command gets the results of the job in the $job variable. The command uses the redirection operator (>) to save the results of the job in the PsLog.txt file on the Server01 computer. +To get the results of the job, use the Receive-Job cmdlet. You can display the +results in the interactive session or save them to a file on the remote +computer. The following command gets the results of the job in the $job +variable. The command uses the redirection operator (>) to save the results of +the job in the PsLog.txt file on the Server01 computer. -``` +```powershell Server01\C:> receive-job $job > c:\logs\PsLog.txt ``` - - #### STEP 5: EXIT-PSSESSION -To end the interactive session, use the Exit-PSSession cmdlet. The command prompt changes to show that you are back in the original session on the local computer. +To end the interactive session, use the Exit-PSSession cmdlet. The command +prompt changes to show that you are back in the original session on the local +computer. -``` -Server01\C:> Exit-PSSession +```powershell +Server01\C:> Exit-PSSession C:\PS> ``` - - #### STEP 6: INVOKE-COMMAND: GET-CONTENT -To view the contents of the PsLog.txt file on the Server01 computer at any time, start another interactive session, or run a remote command. This type of command is best run in a PSSession (a persistent connection) in case you want to use several commands to investigate and manage the data in the PsLog.txt file. For more information about PSSessions, see about_PSSessions. -The following commands use the New-PSSession cmdlet to create a PSSession that is connected to the Server01 computer, and they use the Invoke-Command cmdlet to run a Get-Content command in the PSSession to view the contents of the file. +To view the contents of the PsLog.txt file on the Server01 computer at any +time, start another interactive session, or run a remote command. This type of +command is best run in a PSSession (a persistent connection) in case you want +to use several commands to investigate and manage the data in the PsLog.txt +file. For more information about PSSessions, see about_PSSessions. +The following commands use the New-PSSession cmdlet to create a PSSession that +is connected to the Server01 computer, and they use the Invoke-Command cmdlet +to run a Get-Content command in the PSSession to view the contents of the +file. +```powershell +$s = new-pssession -computername Server01 +invoke-command -session $s -scriptblock { + get-content c:\logs\pslog.txt} ``` -C:\PS> $s = new-pssession -computername Server01 -C:\PS> invoke-command -session $s -scriptblock {get-content c:\logs\pslog.txt} -``` - - ### START A REMOTE JOB THAT RETURNS THE RESULTS TO THE LOCAL COMPUTER \(ASJOB\) -To start a background job on a remote computer that returns the command results to the local computer, use the AsJob parameter of a cmdlet such as the Invoke-Command cmdlet. -When you use the AsJob parameter, the job object is actually created on the local computer even though the job runs on the remote computer. When the job is completed, the results are returned to the local computer. +To start a background job on a remote computer that returns the command +results to the local computer, use the AsJob parameter of a cmdlet such as the +Invoke-Command cmdlet. -You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage any job created by any cmdlet. Many of the cmdlets that have AsJob parameters do not use Windows PowerShell remoting, so you can use them even on computers that are not configured for remoting and that do not meet the requirements for remoting. +When you use the AsJob parameter, the job object is actually created on the +local computer even though the job runs on the remote computer. When the job +is completed, the results are returned to the local computer. +You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage +any job created by any cmdlet. Many of the cmdlets that have AsJob parameters +do not use Windows PowerShell remoting, so you can use them even on computers +that are not configured for remoting and that do not meet the requirements for +remoting. #### STEP 1: INVOKE-COMMAND -ASJOB -The following command uses the AsJob parameter of Invoke-Command to start a background job on the Server01 computer. The job runs a Get-Eventlog command that gets the events in the System log. You can use the JobName parameter to assign a display name to the job. +The following command uses the AsJob parameter of Invoke-Command to start a +background job on the Server01 computer. The job runs a Get-Eventlog command +that gets the events in the System log. You can use the JobName parameter to +assign a display name to the job. -``` -invoke-command -computername Server01 -scriptblock {get-eventlog system} -asjob +```powershell +invoke-command -computername Server01 -scriptblock { + get-eventlog system} -asjob ``` - The results of the command resemble the following sample output. - +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Running True Server01 get-eventlog system ``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Running True Server01 get-eventlog system -``` - -When the AsJob parameter is used, Invoke-Command returns the same type of job object that Start-Job returns. You can save the job object in a variable, or you can use a Get-Job command to get the job. - -Note that the value of the Location property shows that the job ran on the Server01 computer. +When the AsJob parameter is used, Invoke-Command returns the same type of job +object that Start-Job returns. You can save the job object in a variable, or +you can use a Get-Job command to get the job. +Note that the value of the Location property shows that the job ran on the +Server01 computer. #### STEP 2: GET-JOB -To manage a job started by using the AsJob parameter of the Invoke-Command cmdlet, use the Job cmdlets. Because the job object that represents the remote job is on the local computer, you do not need to run remote commands to manage the job. -To determine whether the job is complete, use a Get-Job command. The following command gets all of the jobs that were started in the current session. +To manage a job started by using the AsJob parameter of the Invoke-Command +cmdlet, use the Job cmdlets. Because the job object that represents the remote +job is on the local computer, you do not need to run remote commands to manage +the job. +To determine whether the job is complete, use a Get-Job command. The following +command gets all of the jobs that were started in the current session. -``` +```powershell get-job ``` +Because the remote job was started in the current session, a local Get-Job +command gets the job. The State property of the job object shows that the +command was completed successfully. -Because the remote job was started in the current session, a local Get-Job command gets the job. The State property of the job object shows that the command was completed successfully. - - -``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Completed True Server01 get-eventlog system +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Completed True Server01 get-eventlog system ``` - - #### STEP 3: RECEIVE-JOB -To get the results of the job, use the Receive-Job cmdlet. Because the job results are automatically returned to the computer where the job object resides, you can get the results with a local Receive-Job command. -The following command uses the Receive-Job cmdlet to get the results of the job. It uses the session ID to identify the job. This command saves the job results in the $results variable. You can also redirect the results to a file. +To get the results of the job, use the Receive-Job cmdlet. Because the job +results are automatically returned to the computer where the job object +resides, you can get the results with a local Receive-Job command. +The following command uses the Receive-Job cmdlet to get the results of the +job. It uses the session ID to identify the job. This command saves the job +results in the $results variable. You can also redirect the results to a file. -``` +```powershell $results = receive-job -id 1 ``` - - ### START A REMOTE JOB THAT KEEPS THE RESULTS ON THE REMOTE COMPUTER -To start a background job on a remote computer that keeps the command results on the remote computer, use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. You can use this method to run background jobs on multiple computers. -When you run a Start-Job command remotely, the job object is created on the remote computer, and the job results are maintained on the remote computer. From the perspective of the job, all operations are local. You are just running commands remotely to manage a local job on the remote computer. +To start a background job on a remote computer that keeps the command results +on the remote computer, use the Invoke-Command cmdlet to run a Start-Job +command on a remote computer. You can use this method to run background jobs +on multiple computers. +When you run a Start-Job command remotely, the job object is created on the +remote computer, and the job results are maintained on the remote computer. +From the perspective of the job, all operations are local. You are just +running commands remotely to manage a local job on the remote computer. #### STEP 1: INVOKE-COMMAND START-JOB -Use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. -This command requires a PSSession (a persistent connection). If you use the ComputerName parameter of Invoke-Command to establish a temporary connection, the Invoke-Command command is considered to be complete when the job object is returned. As a result, the temporary connection is closed, and the job is canceled. +Use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. -The following command uses the New-PSSession cmdlet to create a PSSession that is connected to the Server01 computer. The command saves the PSSession in the $s variable +This command requires a PSSession (a persistent connection). If you use the +ComputerName parameter of Invoke-Command to establish a temporary connection, +the Invoke-Command command is considered to be complete when the job object is +returned. As a result, the temporary connection is closed, and the job is +canceled. +The following command uses the New-PSSession cmdlet to create a PSSession that +is connected to the Server01 computer. The command saves the PSSession in the +\$s variable. -``` +```powershell $s = new-pssession -computername Server01 ``` +The next command uses the Invoke-Command cmdlet to run a Start-Job command in +the PSSession. The Start-Job command and the Get-Eventlog command are enclosed +in braces. -The next command uses the Invoke-Command cmdlet to run a Start-Job command in the PSSession. The Start-Job command and the Get-Eventlog command are enclosed in braces. - - +```powershell +invoke-command -session $s -scriptblock { + start-job -scriptblock {get-eventlog system}} ``` -invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog system}} -``` - The results resemble the following sample output. - -``` -Id Name State HasMoreData Location Command --- ---- ----- ----------- -------- ------- +```Output +Id Name State HasMoreData Location Command +-- ---- ----- ----------- -------- ------- 2 Job2 Running True Localhost get-eventlog system ``` +When you run a Start-Job command remotely, Invoke-Command returns the same +type of job object that Start-Job returns. You can save the job object in a +variable, or you can use a Get-Job command to get the job. -When you run a Start-Job command remotely, Invoke-Command returns the same type of job object that Start-Job returns. You can save the job object in a variable, or you can use a Get-Job command to get the job. - -Note that the value of the Location property shows that the job ran on the local computer, known as "LocalHost", even though the job ran on the Server01 computer. Because the job object is created on the Server01 computer and the job runs on the same computer, it is considered to be a local background job. - +Note that the value of the Location property shows that the job ran on the +local computer, known as "LocalHost", even though the job ran on the Server01 +computer. Because the job object is created on the Server01 computer and the +job runs on the same computer, it is considered to be a local background job. #### STEP 2: INVOKE-COMMAND GET-JOB -To manage a remote background job, use the Job cmdlets. Because the job object is on the remote computer, you need to run remote commands to get, stop, wait for, or retrieve the job results. -To see if the job is complete, use an Invoke-Command command to run a Get-Job command in the PSSession that is connected to the Server01 computer. +To manage a remote background job, use the Job cmdlets. Because the job object +is on the remote computer, you need to run remote commands to get, stop, wait +for, or retrieve the job results. +To see if the job is complete, use an Invoke-Command command to run a Get-Job +command in the PSSession that is connected to the Server01 computer. -``` +```powershell invoke-command -session $s -scriptblock {get-job} ``` +The command returns a job object. The State property of the job object shows +that the command was completed successfully. -The command returns a job object. The State property of the job object shows that the command was completed successfully. - - +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +2 Job2 Completed True LocalHost get-eventlog system ``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -2 Job2 Completed True LocalHost get-eventlog system -``` - - #### STEP 3: INVOKE-COMMAND RECEIVE-JOB -To get the results of the job, use the Invoke-Command cmdlet to run a Receive-Job command in the PSSession that is connected to the Server01 computer. -The following command uses the Receive-Job cmdlet to get the results of the job. It uses the session ID to identify the job. This command saves the job results in the $results variable. It uses the Keep parameter of Receive-Job to keep the result in the job cache on the remote computer. +To get the results of the job, use the Invoke-Command cmdlet to run a +Receive-Job command in the PSSession that is connected to the Server01 +computer. +The following command uses the Receive-Job cmdlet to get the results of the +job. It uses the session ID to identify the job. This command saves the job +results in the \$results variable. It uses the Keep parameter of Receive-Job +to keep the result in the job cache on the remote computer. +```powershell +$results = invoke-command -session $s -scriptblock { + receive-job -sessionid 2 -keep} ``` -$results = invoke-command -session $s -scriptblock {receive-job -sessionid 2 -keep} -``` - - -You can also redirect the results to a file on the local or remote computer. The following command uses a redirection operator to save the results in a file on the Server01 computer. +You can also redirect the results to a file on the local or remote computer. +The following command uses a redirection operator to save the results in a +file on the Server01 computer. +```powershell +invoke-command -session $s -command { + receive-job -sessionid 2 > c:\logs\pslog.txt} ``` -invoke-command -session $s -command {receive-job -sessionid 2 > c:\logs\pslog.txt} -``` - - ## SEE ALSO @@ -284,21 +350,20 @@ invoke-command -session $s -command {receive-job -sessionid 2 > c:\logs\pslog.tx [about_Remote_Variables](about_Remote_Variables.md) -Invoke-Command - -Start-Job +[Invoke-Command](../Invoke-Command.md) -Get-Job +[Start-Job](../Start-Job.md) -Wait-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Wait-Job](../Wait-Job.md) -Remove-Job +[Stop-Job](../Stop-Job.md) -New-PSSession +[Remove-Job](../Remove-Job.md) -Enter-PSSession +[New-PSSession](../New-PSSession.md) -Exit-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[Exit-PSSession](../Exit-PSSession.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Properties.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Properties.md index 1029807cd83..f9bea619992 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Properties.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Properties.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,278 +7,304 @@ title: about_Properties --- # About Properties -## about_Properties - ## SHORT DESCRIPTION -Describes how to use object properties in Windows PowerShell®. +Describes how to use object properties in PowerShell. ## LONG DESCRIPTION -Windows PowerShell uses structured collections of information called objects to represent the items in data stores or the state of the computer. Typically, you work with object that are part of the Microsoft .NET Framework, but you can also create custom objects in Windows PowerShell. -The association between an item and its object is very close. When you change an object, you usually change the item that it represents. For example, when you get a file in Windows PowerShell, you do not get the actual file. Instead, you get a FileInfo object that represents the file. When you change the FileInfo object, the file changes too. +PowerShell uses structured collections of information called objects to +represent the items in data stores or the state of the computer. Typically, +you work with object that are part of the Microsoft .NET Framework, but you +can also create custom objects in PowerShell. -Most objects have properties. Properties are the data that is associated with an object. Different types of object have different properties. For example, a FileInfo object, which represents a file, has an IsReadOnly property that contains $True if the file the read-only attribute and $False if it does not. A DirectoryInfo object, which represents a file system directory, has a Parent property that contains the path to the parent directory. +The association between an item and its object is very close. When you change +an object, you usually change the item that it represents. For example, when +you get a file in PowerShell, you do not get the actual file. Instead, you get +a FileInfo object that represents the file. When you change the FileInfo +object, the file changes too. +Most objects have properties. Properties are the data that is associated with +an object. Different types of object have different properties. For example, a +FileInfo object, which represents a file, has an **IsReadOnly** property that +contains $True if the file the read-only attribute and $False if it does not. +A DirectoryInfo object, which represents a file system directory, has a Parent +property that contains the path to the parent directory. ### OBJECT PROPERTIES -To get the properties of an object, use the Get-Member cmdlet. For example, to get the properties of a FileInfo object, use the Get-ChildItem cmdlet to get the FileInfo object that represents a file. Then, use a pipeline operator (|) to send the FileInfo object to Get-Member. The following command gets the PowerShell.exe file and sends it to Get-Member. The $Pshome automatic variable contains the path of the Windows PowerShell installation directory. +To get the properties of an object, use the `Get-Member` cmdlet. For example, +to get the properties of a **FileInfo** object, use the `Get-ChildItem` cmdlet +to get the FileInfo object that represents a file. Then, use a pipeline +operator (|) to send the **FileInfo** object to `Get-Member`. The +following command gets the PowerShell.exe file and sends it to `Get-Member`. +The \$Pshome automatic variable contains the path of the PowerShell +installation directory. -``` +```powershell Get-ChildItem $pshome\PowerShell.exe | Get-Member ``` +The output of the command lists the members of the **FileInfo** object. +Members include both properties and methods. When you work in PowerShell, you +have access to all the members of the objects. -The output of the command lists the members of the FileInfo object. Members include both properties and methods. When you work in Windows PowerShell, you have access to all the members of the objects. - -To get only the properties of an object and not the methods, use the MemberType parameter of the Get-Member cmdlet with a value of "property", as shown in the following example. - +To get only the properties of an object and not the methods, use the +MemberType parameter of the `Get-Member` cmdlet with a value of "property", as +shown in the following example. -``` +```powershell Get-ChildItem $pshome\PowerShell.exe | Get-Member -MemberType property ``` - - -``` -TypeName: System.IO.FileInfo - -Name MemberType Definition ----- ---------- ---------- -Attributes Property System.IO.FileAttributes Attributes {get;set;} -CreationTime Property System.DateTime CreationTime {get;set;} -CreationTimeUtc Property System.DateTime CreationTimeUtc {get;set;} -Directory Property System.IO.DirectoryInfo Directory {get;} -DirectoryName Property System.String DirectoryName {get;} -Exists Property System.Boolean Exists {get;} -Extension Property System.String Extension {get;} -FullName Property System.String FullName {get;} -IsReadOnly Property System.Boolean IsReadOnly {get;set;} -LastAccessTime Property System.DateTime LastAccessTime {get;set;} -LastAccessTimeUtc Property System.DateTime LastAccessTimeUtc {get;set;} -LastWriteTime Property System.DateTime LastWriteTime {get;set;} -LastWriteTimeUtc Property System.DateTime LastWriteTimeUtc {get;set;} -Length Property System.Int64 Length {get;} +```Output +TypeName: System.IO.FileInfo + +Name MemberType Definition +---- ---------- ---------- +Attributes Property System.IO.FileAttributes Attributes {get;set;} +CreationTime Property System.DateTime CreationTime {get;set;} +CreationTimeUtc Property System.DateTime CreationTimeUtc {get;set;} +Directory Property System.IO.DirectoryInfo Directory {get;} +DirectoryName Property System.String DirectoryName {get;} +Exists Property System.Boolean Exists {get;} +Extension Property System.String Extension {get;} +FullName Property System.String FullName {get;} +IsReadOnly Property System.Boolean IsReadOnly {get;set;} +LastAccessTime Property System.DateTime LastAccessTime {get;set;} +LastAccessTimeUtc Property System.DateTime LastAccessTimeUtc {get;set;} +LastWriteTime Property System.DateTime LastWriteTime {get;set;} +LastWriteTimeUtc Property System.DateTime LastWriteTimeUtc {get;set;} +Length Property System.Int64 Length {get;} Name Property System.String Name {get;} ``` - -After you find the properties, you can use them in your Windows PowerShell commands. - +After you find the properties, you can use them in your PowerShell commands. ## PROPERTY VALUES -Although every object of a specific type has the same properties, the values of those properties describe the particular object. For example, every FileInfo object has a CreationTime property, but the value of that property differs for each file. - -The most common way to get the values of the properties of an object is to use the dot method. Type a reference to the object, such as a variable that contains the object, or a command that gets the object. Then, type a dot (.) followed by the property name. - -For example, the following command displays the value of the CreationTime property of the PowerShell.exe file. The Get-ChildItem command returns a FileInfo object that represents the PowerShell.exe file. The command is enclosed in parentheses to make sure that it is executed before any properties are accessed. The Get-ChildItem command is followed by a dot and the name of the CreationTime property, as follows: - -``` -C:\PS> (Get-ChildItem $pshome\PowerShell.exe).creationtime +Although every object of a specific type has the same properties, the values +of those properties describe the particular object. For example, every +FileInfo object has a CreationTime property, but the value of that property +differs for each file. + +The most common way to get the values of the properties of an object is to use +the dot method. Type a reference to the object, such as a variable that +contains the object, or a command that gets the object. Then, type a dot (.) +followed by the property name. + +For example, the following command displays the value of the CreationTime +property of the PowerShell.exe file. The `Get-ChildItem` command returns a +FileInfo object that represents the PowerShell.exe file. The command is +enclosed in parentheses to make sure that it is executed before any properties +are accessed. The `Get-ChildItem` command is followed by a dot and the name of +the CreationTime property, as follows: + +```powershell +C:\PS> (Get-ChildItem $pshome\PowerShell.exe).creationtime Tuesday, March 18, 2008 12:07:52 AM ``` +You can also save an object in a variable and then get its properties by using +the dot method, as shown in the following example: -You can also save an object in a variable and then get its properties by using the dot method, as shown in the following example: - - -``` -C:\PS> $a = Get-ChildItem $pshome\PowerShell.exe -C:\PS> $a.CreationTime +```powershell +C:\PS> $a = Get-ChildItem $pshome\PowerShell.exe +C:\PS> $a.CreationTime Tuesday, March 18, 2008 12:07:52 AM ``` +You can also use the `Select-Object` and `Format-List` cmdlets to display the +property values of an object. `Select-Object` and `Format-List` each have a +**Property** parameter. You can use the **Property** parameter to specify one +or more properties and their values. Or, you can use the wildcard character +(\*) to represent all the properties. -You can also use the Select-Object and Format-List cmdlets to display the property values of an object. Select-Object and Format-List each have a Property parameter. You can use the Property parameter to specify one or more properties and their values. Or, you can use the wildcard character (\*) to represent all the properties. - -For example, the following command displays the values of all the properties of the PowerShell.exe file. - +For example, the following command displays the values of all the properties +of the PowerShell.exe file. -``` +```powershell C:\PS> Get-ChildItem $pshome\PowerShell.exe | Format-List -property * ``` - - -``` -PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe -PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\system32\WindowsPowerShell\v1.0 -PSChildName : PowerShell.exe -PSDrive : C -PSProvider : Microsoft.PowerShell.Core\FileSystem -PSIsContainer : False -VersionInfo : File: C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe - InternalName: POWERSHELL - OriginalFilename: PowerShell.EXE.MUI - File Version: 6.1.6570.1 (fbl_srv_PowerShell(nigels).070711-0102) - FileDescription: PowerShell.EXE - Product: Microsoft® Windows® Operating System - ProductVersion: 6.1.6570.1 - Debug: False - Patched: False - PreRelease: False - PrivateBuild: True - SpecialBuild: False +```Output +PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\System3 + 2\WindowsPowerShell\v1.0\PowerShell.exe +PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\System3 + 2\WindowsPowerShell\v1.0 +PSChildName : PowerShell.exe +PSDrive : C +PSProvider : Microsoft.PowerShell.Core\FileSystem +PSIsContainer : False +Mode : -a---- +VersionInfo : File: C:\Windows\System32\WindowsPowerShell\ + v1.0\PowerShell.exe + InternalName: POWERSHELL + OriginalFilename: PowerShell.EXE.MUI + FileVersion: 10.0.16299.15 (WinBuild.160101.0800) + FileDescription: Windows PowerShell + Product: Microsoft® Windows® Operating System + ProductVersion: 10.0.16299.15 + Debug: False + Patched: False + PreRelease: False + PrivateBuild: False + SpecialBuild: False Language: English (United States) -``` - - -``` -BaseName : PowerShell -Mode : -a--- -Name : PowerShell.exe -Length : 160256 -DirectoryName : C:\Windows\system32\WindowsPowerShell\v1.0 -Directory : C:\Windows\system32\WindowsPowerShell\v1.0 -IsReadOnly : False -Exists : True -FullName : C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe -Extension : .exe -CreationTime : 3/18/2008 12:07:52 AM -CreationTimeUtc : 3/18/2008 7:07:52 AM -LastAccessTime : 3/19/2008 8:13:58 AM -LastAccessTimeUtc : 3/19/2008 3:13:58 PM -LastWriteTime : 3/18/2008 12:07:52 AM -LastWriteTimeUtc : 3/18/2008 7:07:52 AM +BaseName : PowerShell +Target : {C:\Windows\WinSxS\amd64_microsoft-windows-powershell-ex + e_31bf3856ad364e35_10.0.16299.15_none_8c022aa6735716ae\p + owershell.exe} +LinkType : HardLink +Name : PowerShell.exe +Length : 449024 +DirectoryName : C:\Windows\System32\WindowsPowerShell\v1.0 +Directory : C:\Windows\System32\WindowsPowerShell\v1.0 +IsReadOnly : False +Exists : True +FullName : C:\Windows\System32\WindowsPowerShell\v1.0\PowerShell.ex +Extension : .exe +CreationTime : 9/29/2017 6:43:19 AM +CreationTimeUtc : 9/29/2017 1:43:19 PM +LastAccessTime : 9/29/2017 6:43:19 AM +LastAccessTimeUtc : 9/29/2017 1:43:19 PM +LastWriteTime : 9/29/2017 6:43:19 AM +LastWriteTimeUtc : 9/29/2017 1:43:19 PM Attributes : Archive ``` - - ### STATIC PROPERTIES -You can use the static properties of .NET classes in Windows PowerShell. Static properties are properties of class, unlike standard properties, which are properties of an object. -To get the static properties of an class, use the Static parameter of the Get-Member cmdlet. +You can use the static properties of .NET classes in PowerShell. Static +properties are properties of class, unlike standard properties, which are +properties of an object. -For example, the following command gets the static properties of the System.DateTime class. +To get the static properties of an class, use the Static parameter of the +Get-Member cmdlet. +For example, the following command gets the static properties of the +`System.DateTime` class. -``` +```powershell Get-Date | Get-Member -MemberType Property -Static ``` +```Output +TypeName: System.DateTime - -``` -TypeName: System.DateTime - -Name MemberType Definition ----- ---------- ---------- -MaxValue Property static datetime MaxValue {get;} -MinValue Property static datetime MinValue {get;} -Now Property datetime Now {get;} -Today Property datetime Today {get;} +Name MemberType Definition +---- ---------- ---------- +MaxValue Property static datetime MaxValue {get;} +MinValue Property static datetime MinValue {get;} +Now Property datetime Now {get;} +Today Property datetime Today {get;} UtcNow Property datetime UtcNow {get;} ``` - To get the value of a static property, use the following syntax. - -``` +```powershell []:: ``` +For example, the following command gets the value of the UtcNow static +property of the `System.DateTime` class. -For example, the following command gets the value of the UtcNow static property of the System.DateTime class. - - -``` +```powershell [System.DateTime]::UtcNow ``` - - ### PROPERTIES OF SCALAR OBJECTS AND COLLECTIONS -The properties of one ("scalar") object of a particular type are often different from the properties of a collection of objects of the same type. -For example, every service has as DisplayName property, but a collection of services does not have a DisplayName property. Similarly, all collections have a Count property that tells how many objects are in the collection, but individual objects do not have a Count property. +The properties of one ("scalar") object of a particular type are often +different from the properties of a collection of objects of the same type. -Beginning in Windows PowerShell 3.0, Windows PowerShell tries to prevent scripting errors that result from the differing properties of scalar objects and collections. +For example, every service has as **DisplayName** property, but a collection +of services does not have a **DisplayName** property. Similarly, all +collections have a **Count** property that tells how many objects are in the +collection, but individual objects do not have a **Count** property. -If you submit a collection, but request a property that exists only on single ("scalar") objects, Windows PowerShell returns the value of that property for every object in the collection. +Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that +result from the differing properties of scalar objects and collections. -If you request the Count or Length property of zero objects or of one object, Windows PowerShell returns the correct value. +If you submit a collection, but request a property that exists only on single +("scalar") objects, PowerShell returns the value of that property for every +object in the collection. -If the property exists on the individual objects and on the collection, Windows PowerShell does not alter the result. +If you request the Count or Length property of zero objects or of one object, +PowerShell returns the correct value. -This feature also works on methods of scalar objects and collections. For more information, see about_Methods. +If the property exists on the individual objects and on the collection, +PowerShell does not alter the result. +This feature also works on methods of scalar objects and collections. For more +information, see about_Methods. ### EXAMPLES -For example, each service has a DisplayName property. The following command gets the value of the DisplayName property of the Audiosrv service. +For example, each service has a DisplayName property. The following command +gets the value of the DisplayName property of the Audiosrv service. -``` -PS C:\> (Get-Service Audiosrv).DisplayName +```powershell +PS C:\> (Get-Service Audiosrv).DisplayName Windows Audio ``` +However, a collection or array of services does not have a **DisplayName**. +The following command tries to get the DisplayName property of all services in +PowerShell 2.0. -However, a collection or array of services does not have a DisplayName. The following command tries to get the DisplayName property of all services in Windows PowerShell 2.0. - - -``` -PS C:\> (Get-Service).DisplayName +```powershell +PS C:\> (Get-Service).DisplayName PS C:\> ``` +Beginning in PowerShell 3.0, the same command returns the value of the +**DisplayName** property of every service that `Get-Service` returns. -Beginning in Windows PowerShell 3.0, the same command returns the value of the DisplayName property of every service that Get-Service returns. - - -``` -PS C:\> (Get-Service).DisplayName -Application Experience -Application Layer Gateway Service -Windows All-User Install Agent -Application Identity -Application Information +```powershell +PS C:\> (Get-Service).DisplayName +Application Experience +Application Layer Gateway Service +Windows All-User Install Agent +Application Identity +Application Information ... ``` +Conversely, a collection of two or more services has a **Count** property, +which contains the number of objects in the collection. -Conversely, a collection of two or more services has a Count property, which contains the number of objects in the collection. - - -``` -PS C:\> (Get-Service).Count +```powershell +PS C:\> (Get-Service).Count 176 ``` +Individual services do not have a Count or Length property, as shown in this +command in PowerShell 2.0. -Individual services do not have a Count or Length property, as shown in this command in Windows PowerShell 2.0. - - -``` -PS C:\> (Get-Service Audiosrv).Count +```powershell +PS C:\> (Get-Service Audiosrv).Count PS C:\> ``` +Beginning in PowerShell 3.0, the command returns the correct Count value. -Beginning in Windows PowerShell 3.0, the command returns the correct Count value. - - -``` -PS C:\> (Get-Service Audiosrv).Count +```powershell +PS C:\> (Get-Service Audiosrv).Count 1 ``` - - ## SEE ALSO [about_Methods](about_Methods.md) [about_Objects](about_Objects.md) -Get-Member - -Select-Object +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) -Format-List +[Select-Object](../../Microsoft.PowerShell.Utility/Select-Object.md) +[Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) \ No newline at end of file diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Redirection.md index d53b982904c..21d289c7f6e 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -1,135 +1,145 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us -keywords: powershell,cmdlet +keywords: PowerShell,cmdlet title: about_Redirection --- # About Redirection -## about_Redirection - ## SHORT DESCRIPTION -Explains how to redirect output from Windows PowerShell® to text files. +Explains how to redirect output from PowerShell to text files. ## LONG DESCRIPTION -By default, Windows PowerShell sends its command output to the Windows PowerShell console. However, you can direct the output to a text file, and you can redirect error output to the regular output stream. -You can use the following methods to redirect output: +By default, PowerShell sends its command output to the PowerShell console. +However, you can direct the output to a text file, and you can redirect error +output to the regular output stream. -- Use the Out-File cmdlet, which sends command output to a text file. Typically, you use the Out-File cmdlet when you need to use its parameters, such as the Encoding, Force, Width, or NoClobber parameters. +You can use the following methods to redirect output: -- Use the Tee-Object cmdlet, which sends command output to a text file and then sends it to the pipeline. +- Use the `Out-File` cmdlet, which sends command output to a text file. + Typically, you use the `Out-File` cmdlet when you need to use its parameters, + such as the **Encoding**, **Force**, **Width**, or **NoClobber** parameters. -- Use the Windows PowerShell redirection operators. +- Use the Tee-Object cmdlet, which sends command output to a text file and + then sends it to the pipeline. +- Use the PowerShell redirection operators. -### WINDOWS POWERSHELL REDIRECTION OPERATORS -The redirection operators enable you to send particular types of output to files and to the success output stream. +### POWERSHELL REDIRECTION OPERATORS -The Windows PowerShell redirection operators use the following characters to represent each output type: +The redirection operators enable you to send particular types of output to +files and to the success output stream. +The PowerShell redirection operators use the following characters to represent +each output type: ``` -* All output -1 Success output -2 Errors -3 Warning messages -4 Verbose output +* All output +1 Success output +2 Errors +3 Warning messages +4 Verbose output 5 Debug messages ``` +NOTE: The All (\*), Warning (3), Verbose (4) and Debug (5) redirection +operators were introduced in PowerShell 3.0. They do not work in earlier +versions of PowerShell. -NOTE: The All (\*), Warning (3), Verbose (4) and Debug (5) redirection operators were introduced in Windows PowerShell 3.0. They do not work in earlier versions of Windows PowerShell. +The PowerShell redirection operators are as follows. -The Windows PowerShell redirection operators are as follows. +``` +Operator Description Example +-------- ---------------------- ------------------------------ +> Sends output to the Get-Process > Process.txt + specified file. +>> Appends the output to dir *.ps1 >> Scripts.txt + the contents of the + specified file. -``` -Operator Description Example --------- ---------------------- ------------------------------ -> Sends output to the Get-Process > Process.txt - specified file. - ->> Appends the output to dir *.ps1 >> Scripts.txt - the contents of the - specified file. - -2> Sends errors to the Get-Process none 2> Errors.txt - specified file. - -2>> Appends errors to Get-Process none 2>> Save-Errors.txt - the contents of the - specified file. - -2>&1 Sends errors (2) and Get-Process none, Powershell 2>&1 - success output (1) - to the success - output stream. - -3> Sends warnings to the Write-Warning "Test!" 3> Warnings.txt - specified file. - -3>> Appends warnings to Write-Warning "Test!" 3>> Save-Warnings.txt - the contents of the - specified file. - -3>&1 Sends warnings (3) and function Test-Warning - success output (1) { Get-Process PowerShell; - to the success Write-Warning "Test!" } - output stream. Test-Warning 3>&1 - -4> Sends verbose output to Import-Module * -Verbose 4> Verbose.txt - the specified file. - -4>> Appends verbose output Import-Module * -Verbose 4>> Save-Verbose.txt - to the contents of the - specified file. - -4>&1 Sends verbose output (4) Import-Module * -Verbose 4>&1 - and success output (1) - to the success output - stream. - -5> Sends debug messages to Write-Debug "Starting" 5> Debug.txt - the specified file. - -5>> Appends debug messages Write-Debug "Saving" 5>> Save-Debug.txt - to the contents of the - specified file. - -5>&1 Sends debug messages (5) function Test-Debug - and success output (1) { Get-Process PowerShell - to the success output Write-Debug "PS" } - stream. Test-Debug 5>&1 - -*> Sends all output types function Test-Output - to the specified file. { Get-Process PowerShell, none - Write-Warning "Test!" -*>> Appends all output types Write-Verbose "Test Verbose" - to the contents of the Write-Debug "Test Debug" } - specified file. - Test-Output *> Test-Output.txt -*>&1 Sends all output types Test-Output *>> Test-Output.txt - (*) to the success output Test-Output *>&1 +2> Sends errors to the Get-Process none 2> Errors.txt + specified file. + +2>> Appends errors to Get-Process none 2>> Save-Errors.txt + the contents of the + specified file. + +2>&1 Sends errors (2) and Get-Process none, Powershell 2>&1 + success output (1) + to the success + output stream. + +3> Sends warnings to the Write-Warning "Test!" 3> Warnings.txt + specified file. + +3>> Appends warnings to Write-Warning "Test!" 3>> Warnings.txt + the contents of the + specified file. + +3>&1 Sends warnings (3) and function Test-Warning + success output (1) { Get-Process PowerShell; + to the success Write-Warning "Test!" } + output stream. Test-Warning 3>&1 + +4> Sends verbose output to Import-Module * -Verbose 4> Verbose.txt + the specified file. + +4>> Appends verbose output Import-Module * -Verbose 4>> Verbose.txt + to the contents of the + specified file. + +4>&1 Sends verbose output (4) Import-Module * -Verbose 4>&1 + and success output (1) + to the success output stream. -``` +5> Sends debug messages to Write-Debug "Starting" 5> Debug.txt + the specified file. + +5>> Appends debug messages Write-Debug "Saving" 5>> Debug.txt + to the contents of the + specified file. + +5>&1 Sends debug messages (5) function Test-Debug + and success output (1) { Get-Process PowerShell + to the success output Write-Debug "PS" } + stream. Test-Debug 5>&1 + +*> Sends all output types function Test-Output + to the specified file. { Get-Process PowerShell, none + Write-Warning "Test!" +*>> Appends all output types Write-Verbose "Test Verbose" + to the contents of the Write-Debug "Test Debug" } + specified file. + Test-Output *> Test-Output.txt +*>&1 Sends all output types Test-Output *>> Test-Output.txt + (*) to the success Test-Output *>&1 + output stream. +``` The syntax of the redirection operators is as follows: - ``` [\] ``` +If the specified file already exists, the redirection operators that do not +append data (> and n>) overwrite the current contents of the file without +warning. However, if the file is a read-only, hidden, or system file, the +redirection fails. The append redirection operators (>> and n>>) do not write +to a read-only file, but they append content to a system or hidden file. -If the specified file already exists, the redirection operators that do not append data (> and n>) overwrite the current contents of the file without warning. However, if the file is a read-only, hidden, or system file, the redirection fails. The append redirection operators (>> and n>>) do not write to a read-only file, but they append content to a system or hidden file. - -To force the redirection of content to a read-only, hidden, or system file, use the Out-File cmdlet with its Force parameter. When you are writing to files, the redirection operators use Unicode encoding. If the file has a different encoding, the output might not be formatted correctly. To redirect content to non-Unicode files, use the Out-File cmdlet with its Encoding parameter. - +To force the redirection of content to a read-only, hidden, or system file, +use the Out-File cmdlet with its Force parameter. When you are writing to +files, the redirection operators use Unicode encoding. If the file has a +different encoding, the output might not be formatted correctly. To redirect +content to non-Unicode files, use the Out-File cmdlet with its Encoding +parameter. ## SEE ALSO @@ -142,4 +152,3 @@ Tee-Object [about_Command_Syntax](about_Command_Syntax.md) [about_Path_Syntax](about_Path_Syntax.md) - diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 00bb519f161..9194ac278b4 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -16,50 +16,132 @@ Describes regular expressions in Windows PowerShell. Windows PowerShell supports the following regular expression characters. -| Format | Logic | Example | -| ------- | ----- | ------- | -| value | Matches exact characters anywhere in the original value. | "book" -match "oo" | -| . | Matches any single character. | "copy" -match "c..y" | -| [value] | Matches at least one of the characters in the brackets. | "big" -match "b[iou]g" | -| [range] | Matches at least one of the characters within the range. The use of a hyphen (-) allows you to specify an adjacent character. | "and" -match "[a-e]nd" | -| [^] | Matches any characters except those in brackets. | "and" -match "[^brt]nd" | -| ^ | Matches the beginning characters. | "book" -match "^bo" | -| $ | Matches the end characters. | "book" -match "ok$" | -| * | Matches any instances of the preceding character. | "baggy" -match "g*" | -| ? | Matches zero or one instance of the preceding character. | "baggy" -match "g?" | -| \ | Matches the character that follows as an escaped character. | "Try$" -match "Try\\$" | - -Windows PowerShell supports the character classes available in -Microsoft .NET Framework regular expressions. - -| Format | Logic | Example | -| -------- | ----- | ------- | -| \p{name} | Matches any character in the named character class specified by {name}. Supported names are Unicode groups and block ranges such as Ll, Nd, Z, IsGreek, and IsBoxDrawing. | "abcd defg" -match "\p{Ll}+" | -| \P{name} | Matches text not included in the groups and block ranges specified in {name}. | 1234 -match "\P{Ll}+" | -| \w | Matches any word character. Equivalent to the Unicode character categories [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. If ECMAScript-compliant behavior is specified with the ECMAScript option, \w is equivalent to [a-zA-Z_0-9]. | "abcd defg" -match "\w+" (this matches abcd) | -| \W | Matches any nonword character. Equivalent to the Unicode categories [^\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. | "abcd defg" -match "\W+" (this matches the space) | -| \s | Matches any white-space character. Equivalent to the Unicode character categories [\f\n\r\t\v\x85\p{Z}]. | "abcd defg" -match "\s+" | -| \S | Matches any non-white-space character. Equivalent to the Unicode character categories [^\f\n\r\t\v\x85\p{Z}]. | "abcd defg" -match "\S+" | -| \d | Matches any decimal digit. Equivalent to \p{Nd} for Unicode and [0-9] for non-Unicode behavior. | 12345 -match "\d+" | -| \D | Matches any nondigit. Equivalent to \P{Nd} for Unicode and [^0-9] for non-Unicode behavior. | "abcd" -match "\D+" | - +``` +Format value +Logic Matches exact characters anywhere in the original value. +Example "book" -match "oo" + +Format . +Logic Matches any single character. +Example "copy" -match "c..y" + +Format [value] +Logic Matches at least one of the characters in the brackets. +Example "big" -match "b[iou]g" + +Format [range] +Logic Matches at least one of the characters within the range. The use + of a hyphen (-) allows you to specify an adjacent character. +Example "and" -match "[a-e]nd" + +Format [^] +Logic Matches any characters except those in brackets. +Example "and" -match "[^brt]nd" + +Format ^ +Logic Matches the beginning characters. +Example "book" -match "^bo" + +Format $ +Logic Matches the end characters. +Example "book" -match "ok$" + +Format * +Logic Matches any instances of the preceding character. +Example "baggy" -match "g*" + +Format ? +Logic Matches zero or one instance of the preceding character. +Example "baggy" -match "g?" + +Format \ +Logic Matches the character that follows as an escaped character. +Example "Try$" -match "Try\\$" +``` + +Windows PowerShell supports the character classes available in Microsoft .NET +Framework regular expressions. + +``` +Format: \p{name} +Logic: Matches any character in the named character class specified by + {name}. Supported names are Unicode groups and block ranges such + as Ll, Nd, Z, IsGreek, and IsBoxDrawing. +Example: "abcd defg" -match "\p{Ll}+" + +Format: \P{name} +Logic: Matches text not included in the groups and block ranges specified + in {name}. +Example: 1234 -match "\P{Ll}+" + +Format: \w +Logic: Matches any word character. Equivalent to the Unicode character + categories [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. If ECMAScript- + compliant behavior is specified with the ECMAScript option, \w is + equivalent to [a-zA-Z_0-9]. +Example: "abcd defg" -match "\w+" (this matches abcd) + +Format: \W +Logic: Matches any nonword character. Equivalent to the Unicode categories + [^\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. +Example: "abcd defg" -match "\W+" (this matches the space) + +Format: \s +Logic: Matches any white-space character. Equivalent to the Unicode + character categories [\f\n\r\t\v\x85\p{Z}]. +Example: "abcd defg" -match "\s+" + +Format: \S +Logic: Matches any non-white-space character. Equivalent to the Unicode + character categories [^\f\n\r\t\v\x85\p{Z}]. +Example: "abcd defg" -match "\S+" + +Format: \d +Logic: Matches any decimal digit. Equivalent to \p{Nd} for Unicode and + [0-9] for non-Unicode behavior. +Example: 12345 -match "\d+" + +Format: \D +Logic: Matches any nondigit. Equivalent to \P{Nd} for Unicode and [^0-9] + for non-Unicode behavior. +Example: "abcd" -match "\D+" +``` Windows PowerShell supports the quantifiers available in .NET Framework regular expressions. The following are some examples of quantifiers. -| Format | Logic | Example | -| ------ | ----- | ------- | -| * | Specifies zero or more matches; for example, \wor (abc). Equivalent to {0,}. | "abc" -match "\w*" | -| + | Matches repeating instances of the preceding characters. | "xyxyxy" -match "xy+" | -| ? | Specifies zero or one matches; for example, \w? or (abc)?. Equivalent to {0,1}. | "abc" -match "\w?" | -| {n} | Specifies exactly n matches; for example, (pizza){2}. | "abc" -match "\w{2}" | -| {n,} | Specifies at least n matches; for example, (abc){2,}. | "abc" -match "\w{2,}" | -| {n,m} | Specifies at least n, but no more than m, matches. | "abc" -match "\w{2,3}" | +``` +Format: * +Logic Specifies zero or more matches; for example, \wor (abc). Equivalent + to {0,}. +Example: "abc" -match "\w*" + +Format: + +Logic: Matches repeating instances of the preceding characters. +Example: "xyxyxy" -match "xy+" + +Format: ? +Logic: Specifies zero or one matches; for example, \w? or (abc)?. + Equivalent to {0,1}. +Example: "abc" -match "\w?" + +Format: {n} +Logic: Specifies exactly n matches; for example, (pizza){2}. +Example: "abc" -match "\w{2}" + +Format: {n,} +Logic: Specifies at least n matches; for example, (abc){2,}. +Example: "abc" -match "\w{2,}" + +Format: {n,m} +Logic: Specifies at least n, but no more than m, matches. +Example: "abc" -match "\w{2,3}" +``` All the comparisons shown in the preceding table evaluate to true. -Notice that the escape character for regular expressions, a backslash (\\), -is different from the escape character for Windows PowerShell. The -escape character for Windows PowerShell is the backtick character (`) (ASCII 96). +Notice that the escape character for regular expressions, a backslash (\\), is +different from the escape character for Windows PowerShell. The escape +character for Windows PowerShell is the backtick character (`) (ASCII 96). For more information, see [Regular Expression Language - Quick Reference](https://go.microsoft.com/fwlink/?LinkId=133231). diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md index 9106db823dd..d7a4d220a0c 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,34 +14,31 @@ Explains how to disconnect from and reconnect to a PSSession ## Long Description -Beginning in Windows PowerShell 3.0, you can disconnect from -a PSSession and reconnect to the PSSession at a later time on -the same computer or a different computer. The session state -is maintained and commands in the PSSession continue to -run while the session is disconnected. +Beginning in Windows PowerShell 3.0, you can disconnect from a PSSession and +reconnect to the PSSession at a later time on the same computer or a different +computer. The session state is maintained and commands in the PSSession +continue to run while the session is disconnected. -The Disconnected Sessions feature is available only when the -computer at the remote end of a connection is running Windows -PowerShell 3.0 or a later version of Windows PowerShell. +The Disconnected Sessions feature is available only when the computer at the +remote end of a connection is running Windows PowerShell 3.0 or a later +version of Windows PowerShell. -The Disconnected Sessions feature allows you to close the session -in which a PSSession was created, and even close Windows PowerShell, -and shut down the computer, without disrupting commands running -in the PSSession. It is especially useful for running commands that -take an extended time to complete, and it provides the time and -device flexibility that IT professionals require. +The Disconnected Sessions feature allows you to close the session in which a +PSSession was created, and even close Windows PowerShell, and shut down the +computer, without disrupting commands running in the PSSession. It is +especially useful for running commands that take an extended time to complete, +and it provides the time and device flexibility that IT professionals require. -NOTE: You cannot disconnect from an interactive session that -is started by using the `Enter-PSSession` cmdlet. +NOTE: You cannot disconnect from an interactive session that is started by +using the `Enter-PSSession` cmdlet. -You can use Disconnected Sessions to manage PSSessions that -were disconnected unintentionally as the result of a computer -or network outage. +You can use Disconnected Sessions to manage PSSessions that were disconnected +unintentionally as the result of a computer or network outage. -In real-world use, the Disconnected Sessions feature allows -you to begin solving a problem, turn your attention to a higher -priority issue, and then resume work on the solution, even on a -different computer in a different location. +In real-world use, the Disconnected Sessions feature allows you to begin +solving a problem, turn your attention to a higher priority issue, and then +resume work on the solution, even on a different computer in a different +location. ## Disconnected Session Cmdlets @@ -50,82 +47,77 @@ The following cmdlets support the Disconnected Sessions feature: * `Connect-PSSession`: Connects to a disconnected PSSession * `Disconnect-PSSession`: Disconnects a PSSession * `Get-PSSession`: Gets PSSessions on the local computer or on remote computers -* `Receive-PSSession`: Gets the results of commands that ran in disconnected sessions -* `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and disconnects immediately +* `Receive-PSSession`: Gets the results of commands that ran in disconnected + sessions +* `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and + disconnects immediately ## How the Disconnected Sessions Feature Works -Beginning in Windows PowerShell 3.0, PSSessions are independent -of the sessions in which they are created. Active PSSession are -maintained on the remote computer or "server side" of the -connection, even if the session in which PSSession was -created is closed and the originating computer is shut down -or disconnected from the network. - -In Windows PowerShell 2.0, the PSSession is deleted from the -remote computer when it is disconnected from the originating -session or the session in which it was created ends. - -When you disconnect a PSSession, the PSSession remains active -and is maintained on the remote computer. The session state -changes from Running to Disconnected. You can reconnect to a -disconnected PSSession from the current session or from a different -session on the same computer, or from a different computer. The -remote computer that maintains the session must be running and +Beginning in Windows PowerShell 3.0, PSSessions are independent of the +sessions in which they are created. Active PSSession are maintained on the +remote computer or "server side" of the connection, even if the session in +which PSSession was created is closed and the originating computer is shut +down or disconnected from the network. + +In Windows PowerShell 2.0, the PSSession is deleted from the remote computer +when it is disconnected from the originating session or the session in which +it was created ends. + +When you disconnect a PSSession, the PSSession remains active and is +maintained on the remote computer. The session state changes from Running to +Disconnected. You can reconnect to a disconnected PSSession from the current +session or from a different session on the same computer, or from a different +computer. The remote computer that maintains the session must be running and be connected to the network. -Commands in a disconnected PSSession continue to run -uninterrupted on the remote computer until the command -completes or the output buffer fills. To prevent a full -output buffer from suspending a command, use the +Commands in a disconnected PSSession continue to run uninterrupted on the +remote computer until the command completes or the output buffer fills. To +prevent a full output buffer from suspending a command, use the **OutputBufferingMode** parameter of the `Disconnect-PSSession`, `New-PSSessionOption`, or `New-PSTransportOption` cmdlets. -Disconnected sessions are maintained in the disconnected -state on the remote computer. They are available for you to -reconnect, until you delete the PSSession, such as by using -the `Remove-PSSession` cmdlet, or until the idle timeout of the -PSSession expires. You can adjust the idle timeout of a PSSession -by using the **IdleTimeoutSec** or **IdleTimeout** parameters of the +Disconnected sessions are maintained in the disconnected state on the remote +computer. They are available for you to reconnect, until you delete the +PSSession, such as by using the `Remove-PSSession` cmdlet, or until the idle +timeout of the PSSession expires. You can adjust the idle timeout of a +PSSession by using the **IdleTimeoutSec** or **IdleTimeout** parameters of the `Disconnect-PSSession`, `New-PSSessionOption`, or `New-PSTransportOption` cmdlets. -Another user can connect to PSSessions that you created, -but only if they can supply the credentials that were used -to create the session, or use the RunAs credentials of -the session configuration. +Another user can connect to PSSessions that you created, but only if they can +supply the credentials that were used to create the session, or use the RunAs +credentials of the session configuration. ## How to Get PSSessions Beginning in Windows PowerShell 3.0, the `Get-PSSession` cmdlet gets -PSSessions on the local computer and remote computers. It can also -get PSSessions that were created in the current session. +PSSessions on the local computer and remote computers. It can also get +PSSessions that were created in the current session. To get PSsessions on the local computer or remote computers, use the **ComputerName** or **ConnectionUri** parameters. Without parameters, `Get-PSSession` gets PSSession that were created in the local session, regardless of where they terminate. -When getting PSSessions, remember to look for them on the computer -on which they are maintained, that is, the remote or "server-side" -computer. +When getting PSSessions, remember to look for them on the computer on which +they are maintained, that is, the remote or "server-side" computer. -For example, if you create a PSSession to the Server01 computer, -get the session from the Server01 computer. If you create a PSSession -from another computer to the local computer, get the session from -the local computer. +For example, if you create a PSSession to the Server01 computer, get the +session from the Server01 computer. If you create a PSSession from another +computer to the local computer, get the session from the local computer. The following command sequence shows how `Get-PSSession` works. -The first command creates a session to the Server01 computer. The -session resides on the Server01 computer. +The first command creates a session to the Server01 computer. The session +resides on the Server01 computer. ```powershell PS C:\> New-PSSession -ComputerName Server01 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` To get the session, use the **ComputerName** parameter of `Get-PSSession` @@ -134,15 +126,15 @@ with a value of Server01. ```powershell PS C:\> Get-PSSession -ComputerName Server01 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` If the value of the **ComputerName** parameter of `Get-PSSession` is localhost, `Get-PSSession` gets PSSessions that terminate at and are -maintained on the local computer. It does not get PSSessions on the -Server01 computer, even if they were started on the local computer. +maintained on the local computer. It does not get PSSessions on the Server01 +computer, even if they were started on the local computer. ```powershell PS C:\> Get-PSSession -ComputerName localhost @@ -156,16 +148,16 @@ that was created in the current session and connects to the Server01 computer. ```powershell PS C:\> Get-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` ## How to Disconnect Sessions -To disconnect a PSSession use the `Disconnect-PSSession` cmdlet. To -identify the PSSession, use the **Session** parameter, or pipe a PSSession -from the `New-PSSession` or `Get-PSSession` cmdlets to `Disconnect-PSSession`. +To disconnect a PSSession use the `Disconnect-PSSession` cmdlet. To identify +the PSSession, use the **Session** parameter, or pipe a PSSession from the +`New-PSSession` or `Get-PSSession` cmdlets to `Disconnect-PSSession`. The following command disconnects the PSSession to the Server01 computer. Notice that the value of the State property is Disconnected and the @@ -174,94 +166,96 @@ Availability is None. ```powershell PS C:\> Get-PSSession -ComputerName Server01 | Disconnect-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Disconnected Microsoft.PowerShell None ``` To create a disconnected session, use the **InDisconnectedSession** parameter -of the `Invoke-Command` cmdlet. It creates a session, starts the command, -and disconnects immediately, before the command can return any output. +of the `Invoke-Command` cmdlet. It creates a session, starts the command, and +disconnects immediately, before the command can return any output. -The following command runs a `Get-WinEvent` command in a disconnected -session on the Server02 remote computer. +The following command runs a `Get-WinEvent` command in a disconnected session +on the Server02 remote computer. ```powershell PS C:\> Invoke-Command -ComputerName Server02 -InDisconnectedSession ` -ScriptBlock { Get-WinEvent -LogName "Windows PowerShell" } -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 4 Session3 Server02 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 4 Session3 Server02 Disconnected Microsoft.PowerShell None ``` ## How to Connect to Disconnected Sessions -You can connect to any available disconnected PSSession from the session -in which you created the PSSession or from other sessions on the local -computer or other computers. +You can connect to any available disconnected PSSession from the session in +which you created the PSSession or from other sessions on the local computer +or other computers. -You can create a PSSession, run commands in the PSSession, disconnect from -the PSSession, close Windows PowerShell, and shut down the computer. Hours -later, you can open a different computer, get the PSSession, connect to it, -and get the results of commands that ran in the PSSession while it was -disconnected. Then you can run more commands in the session. +You can create a PSSession, run commands in the PSSession, disconnect from the +PSSession, close Windows PowerShell, and shut down the computer. Hours later, +you can open a different computer, get the PSSession, connect to it, and get +the results of commands that ran in the PSSession while it was disconnected. +Then you can run more commands in the session. To connect a disconnected PSSession, use the `Connect-PSSession` cmdlet. Use -the **ComputerName** or **ConnectionUri** parameters to identify the PSSession, or -pipe a PSSession from `Get-PSSession` to `Connect-PSSession`. +the **ComputerName** or **ConnectionUri** parameters to identify the +PSSession, or pipe a PSSession from `Get-PSSession` to `Connect-PSSession`. -The following command gets the sessions on the Server02 computer. -The output includes two disconnected sessions, both of which are available. +The following command gets the sessions on the Server02 computer. The output +includes two disconnected sessions, both of which are available. ```powershell PS C:\> Get-PSSession -ComputerName Server02 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 juneb-srv8320 Disconnected Microsoft.PowerShell None - 4 Session3 juneb-srv8320 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 juneb-srv8320 Disconnected Microsoft.PowerShell None + 4 Session3 juneb-srv8320 Disconnected Microsoft.PowerShell None ``` -The following command connects to Session2. The PSSession is now open and available. +The following command connects to Session2. The PSSession is now open and +available. ```powershell PS C:\> Connect-PSSession -ComputerName Server02 -Name Session2 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 juneb-srv8320 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 juneb-srv8320 Opened Microsoft.PowerShell Available ``` ## How to Get the Results -To get the results of commands that ran in a disconnected PSSession, use -the `Receive-PSSession` cmdlet. +To get the results of commands that ran in a disconnected PSSession, use the +`Receive-PSSession` cmdlet. You can use `Receive-PSSession` in addition to, or instead of, using the `Connect-PSSession` cmdlet. If the session is already reconnected, -`Receive-PSSession` gets the results of commands that ran when the session -was disconnected. If the PSSession is still disconnected, `Receive-PSSession` +`Receive-PSSession` gets the results of commands that ran when the session was +disconnected. If the PSSession is still disconnected, `Receive-PSSession` connects to it and then gets the results of commands that ran while it was disconnected. -`Receive-PSSession` can return the results in a job (asynchronously) or to -the host program (synchronously). Use the **OutTarget** parameter to select Job -or Host. Host is the default value. However, if the command that is being +`Receive-PSSession` can return the results in a job (asynchronously) or to the +host program (synchronously). Use the **OutTarget** parameter to select Job or +Host. Host is the default value. However, if the command that is being received was started in the current session as a job, it is returned as a job by default. -The following command uses the `Receive-PSSession` cmdlet to connect to the PSSession -on the Server02 computer and get the results of the `Get-WinEvent` command that -ran in the Session3 session. The command uses the **OutTarget** parameter to get the -results in a job. +The following command uses the `Receive-PSSession` cmdlet to connect to the +PSSession on the Server02 computer and get the results of the `Get-WinEvent` +command that ran in the Session3 session. The command uses the **OutTarget** +parameter to get the results in a job. ```powershell -PS C:\> Receive-PSSession -ComputerName Server02 -Name Session3 -OutTarget Job +PS C:\> Receive-PSSession -ComputerName Server02 -Name Session3 ` + -OutTarget Job -Id Name PSJobTypeName State HasMoreData Location --- ---- ------------- ----- ----------- -------- - 3 Job3 RemoteJob Running True Server02 +Id Name PSJobTypeName State HasMoreData Location +-- ---- ------------- ----- ----------- -------- + 3 Job3 RemoteJob Running True Server02 ``` To get the results of the job, use the `Receive-Job` cmdlet. @@ -281,141 +275,135 @@ TimeCreated Id LevelDisplayName Message PSComputerName ## State and Availability -The State and Availability properties of a disconnected PSSession -tell you whether the session is available for you to reconnect to it. +The State and Availability properties of a disconnected PSSession tell you +whether the session is available for you to reconnect to it. -When a PSSession is connected to the current session, its state is -Opened and its availability is Available. When you disconnect from -the PSSession, the PSSession state is Disconnected and its Availability -is none. +When a PSSession is connected to the current session, its state is Opened and +its availability is Available. When you disconnect from the PSSession, the +PSSession state is Disconnected and its Availability is none. -However, 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. However, it does not mean -that the PSSession is disconnected from all sessions. It might be -connected to a different session. +However, 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. 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, -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. +To determine whether you can connect or reconnect to the PSSession, 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. -The following example is run in two sessions (Windows PowerShell -console windows) on the same computer. Note the changing values of the -State and Availability properties in each session as the PSSession is -disconnected and reconnected. +The following example is run in two sessions (Windows PowerShell console +windows) on the same computer. Note the changing values of the State and +Availability properties in each session as the PSSession is disconnected and +reconnected. ```powershell # Session 1 PS C:\> New-PSSession -ComputerName Server30 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Opened Microsoft.PowerShell Available # Session 2 PS C:\> Get-PSSession -ComputerName Server30 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell Busy +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell Busy # Session 1 -PS C:\> Get-PSSession -ComputerName Server30 -Name Test | Disconnect-PSSession +PS C:\> Get-PSSession -ComputerName Server30 -Name Test | +>> Disconnect-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell None # Session 2 PS C:\> Get-PSSession -ComputerName Server30 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell None # Session 2 PS C:\> Connect-PSSession -ComputerName Server01 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -3 Test Server30 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +3 Test Server30 Opened Microsoft.PowerShell Available # Session 1 PS C:\> Get-PSSession -ComputerName Server30 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell Busy +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell Busy # IDLE TIMEOUT ``` -Disconnected sessions are maintained on the remote computer until -you delete them, such as by using the `Remove-PSSession` cmdlet, or -they time out. The IdleTimeout property of a PSSession determines -how long a disconnected session is maintained before it is deleted. +Disconnected sessions are maintained on the remote computer until you delete +them, such as by using the `Remove-PSSession` cmdlet, or they time out. The +IdleTimeout property of a PSSession determines how long a disconnected session +is maintained before it is deleted. PSSessions are idle when the "heartbeat thread" receives no response. -Disconnecting a session makes it idle and starts the Idle Timeout -clock, even if commands are still running in the disconnected session. -Windows PowerShell considers disconnected sessions to be active, but -idle. - -When creating and disconnecting sessions, verify that the idle -timeout in the PSSession is long enough to maintain the session -for your needs, but not so long that it consumes unnecessary -resources on the remote computer. - -The IdleTimeoutMs property of the session configuration -determines the default idle timeout of sessions that use the -session configuration. You can override the default value, but -the value that you use cannot exceed the MaxIdleTimeoutMs -property of the session configuration. - -To find the value of the IdleTimeoutMs and MaxIdleTimeoutMs -values of a session configuration, use the following command -format. +Disconnecting a session makes it idle and starts the Idle Timeout clock, even +if commands are still running in the disconnected session. Windows PowerShell +considers disconnected sessions to be active, but idle. + +When creating and disconnecting sessions, verify that the idle timeout in the +PSSession is long enough to maintain the session for your needs, but not so +long that it consumes unnecessary resources on the remote computer. + +The IdleTimeoutMs property of the session configuration determines the default +idle timeout of sessions that use the session configuration. You can override +the default value, but the value that you use cannot exceed the +MaxIdleTimeoutMs property of the session configuration. + +To find the value of the IdleTimeoutMs and MaxIdleTimeoutMs values of a +session configuration, use the following command format. ```powershell -Get-PSSessionConfiguration | Format-Table Name, IdleTimeoutMs, MaxIdleTimeoutMs +Get-PSSessionConfiguration | + Format-Table Name, IdleTimeoutMs, MaxIdleTimeoutMs ``` -You can override the default value in the session configuration and -set the idle timeout of a PSSession when you create a PSSession and -when you disconnect. +You can override the default value in the session configuration and set the +idle timeout of a PSSession when you create a PSSession and when you +disconnect. -If you are a member of the Administrators group on the remote computer, -you can also create and change the IdleTimeoutMs and MaxIdleTimeoutMs -properties of session configurations. +If you are a member of the Administrators group on the remote computer, you +can also create and change the IdleTimeoutMs and MaxIdleTimeoutMs properties +of session configurations. ## NOTES: -The idle timeout value of session configurations and session -options is in milliseconds. The idle timeout value of sessions -and session configuration options is in seconds. +The idle timeout value of session configurations and session options is in +milliseconds. The idle timeout value of sessions and session configuration +options is in seconds. -You can set the idle timeout of a PSSession when you create the -PSSession (`New-PSSession`, `Invoke-Command`) and when you disconnect -from it (`Disconnect-PSSession`). However, you cannot change the -IdleTimeout value when you connect to the PSSession -(`Connect-PSSession`) or get results (`Receive-PSSession`). +You can set the idle timeout of a PSSession when you create the PSSession +(`New-PSSession`, `Invoke-Command`) and when you disconnect from it +(`Disconnect-PSSession`). However, you cannot change the IdleTimeout value +when you connect to the PSSession (`Connect-PSSession`) or get results +(`Receive-PSSession`). The `Connect-PSSession` and `Receive-PSSession` cmdlets have a -**SessionOption** parameter that takes a SessionOption object, -such as one returned by the `New-PSSessionOption` cmdlet. However, -the IdleTimeout value in SessionOption object and the IdleTimeout -value in the $PSSessionOption preference variable do not change -the value of the IdleTimeout of the PSSession in a `Connect-PSSession` -or `Receive-PSSession` command. +**SessionOption** parameter that takes a SessionOption object, such as one +returned by the `New-PSSessionOption` cmdlet. However, the IdleTimeout value +in SessionOption object and the IdleTimeout value in the $PSSessionOption +preference variable do not change the value of the IdleTimeout of the +PSSession in a `Connect-PSSession` or `Receive-PSSession` command. * To create a PSSession with a particular idle timeout value, create a $PSSessionOption preference variable. Set the value of the IdleTimeout property to the desired value (in milliseconds). - When you create PSSessions, the values in $PSSessionOption variable - take precedence over the values in the session configuration. + When you create PSSessions, the values in $PSSessionOption variable take + precedence over the values in the session configuration. For example, this command sets an idle timeout of 48 hours. @@ -477,38 +465,35 @@ Set-PSSessionConfiguration -Name Test -TransportOption $o ## Output Buffering Mode -The output buffering mode of a PSSession determines how command -output is managed when the output buffer of the PSSession is full. +The output buffering mode of a PSSession determines how command output is +managed when the output buffer of the PSSession is full. -In a disconnected session, the output buffering mode effectively -determines whether the command continues to run while the session -is disconnected. +In a disconnected session, the output buffering mode effectively determines +whether the command continues to run while the session is disconnected. Valid values: * Block - When the output buffer is full, execution is suspended - until the buffer is clear. + When the output buffer is full, execution is suspended until the buffer is + clear. * Drop - When the output buffer is full, execution continues. - As new output is generated, the oldest output is discarded. + When the output buffer is full, execution continues. As new output is + generated, the oldest output is discarded. -Block, the default value, preserves data, but might interrupt -the command. +Block, the default value, preserves data, but might interrupt the command. -A value of Drop allows the command to complete, although data might -be lost. When using the Drop value, redirect the command output to -a file on disk. This value is recommended for disconnected sessions. +A value of Drop allows the command to complete, although data might be lost. +When using the Drop value, redirect the command output to a file on disk. This +value is recommended for disconnected sessions. -The OutputBufferingMode property of the session configuration -determines the default output buffering mode of sessions that -use the session configuration. +The OutputBufferingMode property of the session configuration determines the +default output buffering mode of sessions that use the session configuration. -To find the value of the OutputBufferingMode of a session -configuration, use the following command formats. +To find the value of the OutputBufferingMode of a session configuration, use +the following command formats. ```powershell (Get-PSSessionConfiguration ).OutputBufferingMode @@ -520,12 +505,12 @@ or Get-PSSessionConfiguration | Format-Table Name, OutputBufferingMode ``` -You can override the default value in the session configuration and set -the output buffering mode of a PSSession when you create a PSSession, -when you disconnect, and when you reconnect. +You can override the default value in the session configuration and set the +output buffering mode of a PSSession when you create a PSSession, when you +disconnect, and when you reconnect. -If you are a member of the Administrators group on the remote computer, -you can also create and change the output buffering mode of session +If you are a member of the Administrators group on the remote computer, you +can also create and change the output buffering mode of session configurations. * To create a PSSession with an output buffering mode of Drop, create @@ -609,63 +594,58 @@ Set-PSSessionConfiguration -Name Test -TransportOption $o ## Disconnecting Loopback Sessions -"Loopback sessions" or "local sessions" are PSSessions that -originate and terminate on the same computer. Like other -PSSessions, active loopback sessions are maintained on the -computer on the remote end of the connection (the local -computer), so you can disconnect from and reconnect to -loopback sessions. +"Loopback sessions" or "local sessions" are PSSessions that originate and +terminate on the same computer. Like other PSSessions, active loopback +sessions are maintained on the computer on the remote end of the connection +(the local computer), so you can disconnect from and reconnect to loopback +sessions. -By default, loopback sessions are created with a network security -token that does not permit commands run in the session to access -other computers. You can reconnect to loopback sessions that have a -network security token from any session on the local computer or a -remote computer. +By default, loopback sessions are created with a network security token that +does not permit commands run in the session to access other computers. You can +reconnect to loopback sessions that have a network security token from any +session on the local computer or a remote computer. However, if you use the **EnableNetworkAccess** parameter of the -`New-PSSession`, `Enter-PSSession`, or `Invoke-Command` cmdlet, the -loopback session is created with an interactive security token. -The interactive token enables commands that run in the loopback -session to get data from other computers. +`New-PSSession`, `Enter-PSSession`, or `Invoke-Command` cmdlet, the loopback +session is created with an interactive security token. The interactive token +enables commands that run in the loopback session to get data from other +computers. -You can disconnect loopback sessions with interactive tokens and -then reconnect to them from the same session or a different session -on the same computer. However, to prevent malicious access, you can -reconnect to loopback sessions with interactive tokens only from the -computer on which they were created. +You can disconnect loopback sessions with interactive tokens and then +reconnect to them from the same session or a different session on the same +computer. However, to prevent malicious access, you can reconnect to loopback +sessions with interactive tokens only from the computer on which they were +created. ## Waiting for Jobs in Disconnected Sessions -The `Wait-Job` cmdlet waits until a job completes and then -returns to the command prompt or the next command. By default, -`Wait-Job` returns if the session in which a job is running is -disconnected. To direct the `Wait-Job` cmdlet to wait until the -session is reconnected (in the Opened state), use the **Force** -parameter. For more information, see [Wait-Job](../Wait-Job.md). +The `Wait-Job` cmdlet waits until a job completes and then returns to the +command prompt or the next command. By default, `Wait-Job` returns if the +session in which a job is running is disconnected. To direct the `Wait-Job` +cmdlet to wait until the session is reconnected (in the Opened state), use the +**Force** parameter. For more information, see [Wait-Job](../Wait-Job.md). ## Robust Sessions and Unintentional Disconnection -Occasionally, a PSSession might be disconnected unintentionally -due to a computer failure or network outage. Windows PowerShell -attempts to recover the PSSession, but its success depends upon -the severity and duration of the cause. - -The state of an unintentionally disconnected PSSession might -be Broken or Closed, but it might also be Disconnected. If -the value of State is Disconnected, you can use the same -techniques to manage the PSSession as you would if the -session were disconnected intentionally. For example, you -can use the `Connect-PSSession` cmdlet to reconnect to the session -and the `Receive-PSSession` cmdlet to get results of commands that -ran while the session was disconnected. - -If you close (exit) the session in which a PSSession was -created while commands are running in the PSSession, Windows -PowerShell maintains the PSSession in the Disconnected state -on the remote computer. If you close (exit) the session in -which a PSSession was created, but no commands are running -in the PSSession, Windows PowerShell does not attempt to -maintain the PSSession. +Occasionally, a PSSession might be disconnected unintentionally due to a +computer failure or network outage. Windows PowerShell attempts to recover the +PSSession, but its success depends upon the severity and duration of the +cause. + +The state of an unintentionally disconnected PSSession might be Broken or +Closed, but it might also be Disconnected. If the value of State is +Disconnected, you can use the same techniques to manage the PSSession as you +would if the session were disconnected intentionally. For example, you can use +the `Connect-PSSession` cmdlet to reconnect to the session and the +`Receive-PSSession` cmdlet to get results of commands that ran while the +session was disconnected. + +If you close (exit) the session in which a PSSession was created while +commands are running in the PSSession, Windows PowerShell maintains the +PSSession in the Disconnected state on the remote computer. If you close +(exit) the session in which a PSSession was created, but no commands are +running in the PSSession, Windows PowerShell does not attempt to maintain the +PSSession. ## See Also diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md index 3c4c6936b01..93fb4c492c5 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,344 +7,512 @@ title: about_Remote_FAQ --- # About Remote FAQ -## about_Remote_FAQ - ## SHORT DESCRIPTION -Contains questions and answers about running remote commands in Windows PowerShell®. +Contains questions and answers about running remote commands in Windows +PowerShell. ## LONG DESCRIPTION -When you work remotely, you type commands in Windows PowerShell on one computer (known as the "local computer"), but the commands run on another computer (known as the "remote computer"). The experience of working remotely should be as much like working directly at the remote computer as possible. - - -``` -Note: To use Windows PowerShell remoting, the remote computer - must be configured for remoting. For more information, see - about_Remote_Requirements. -``` +When you work remotely, you type commands in Windows PowerShell on one +computer (known as the "local computer"), but the commands run on another +computer (known as the "remote computer"). The experience of working remotely +should be as much like working directly at the remote computer as possible. +Note: To use Windows PowerShell remoting, the remote computer must be +configured for remoting. For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). ### MUST BOTH COMPUTERS HAVE WINDOWS POWERSHELL INSTALLED? -Yes. To work remotely, the local and remote computers must have Windows PowerShell, the Microsoft .NET Framework, and the Web Services for Management (WS-Management) protocol. Any files and other resources that are needed to execute a particular command must be on the remote computer. -Computers running Windows PowerShell 3.0 and computers running Windows PowerShell 2.0 can connect to each other remotely and run remote commands. However, some features, such as the ability to disconnect from a session and reconnect to it, work only when both computers are running Windows PowerShell 3.0. +Yes. To work remotely, the local and remote computers must have Windows +PowerShell, the Microsoft .NET Framework, and the Web Services for Management +(WS-Management) protocol. Any files and other resources that are needed to +execute a particular command must be on the remote computer. -You must have permission to connect to the remote computer, permission to run Windows PowerShell, and permission to access data stores (such as files and folders), and the registry on the remote computer. +Computers running Windows PowerShell 3.0 and computers running Windows +PowerShell 2.0 can connect to each other remotely and run remote commands. +However, some features, such as the ability to disconnect from a session and +reconnect to it, work only when both computers are running Windows PowerShell +3.0. -For more information, see about_Remote_Requirements. +You must have permission to connect to the remote computer, permission to run +Windows PowerShell, and permission to access data stores (such as files and +folders), and the registry on the remote computer. +For more information, see [about_Remote_Requirements](about_Remote_Requirements.md). ### HOW DOES REMOTING WORK? -When you submit a remote command, the command is transmitted across the network to the Windows PowerShell engine on the remote computer, and it runs in the Windows PowerShell client on the remote computer. The command results are sent back to the local computer and appear in the Windows PowerShell session on the local computer. -To transmit the commands and receive the output, Windows PowerShell uses the WS-Management protocol. For information about the WS-Management protocol, see "WS-Management Protocol" in the MSDN (Microsoft Developer Network) library at http:\/\/go.microsoft.com\/fwlink\/?LinkId\=144634. +When you submit a remote command, the command is transmitted across the +network to the Windows PowerShell engine on the remote computer, and it runs +in the Windows PowerShell client on the remote computer. The command results +are sent back to the local computer and appear in the Windows PowerShell +session on the local computer. -Beginning in Windows PowerShell 3.0, remote sessions are stored on the remote computer. This enables you to disconnect from the session and reconnect from a different session or a different computer without interrupting the commands or losing state. +To transmit the commands and receive the output, Windows PowerShell uses the +WS-Management protocol. For information about the WS-Management protocol, see +[WS-Management Protocol](http://go.microsoft.com\/fwlink/?LinkId=144634) in +the MSDN library. +Beginning in Windows PowerShell 3.0, remote sessions are stored on the remote +computer. This enables you to disconnect from the session and reconnect from a +different session or a different computer without interrupting the commands or +losing state. ### IS WINDOWS POWERSHELL REMOTING SECURE? -When you connect to a remote computer, the system uses the user name and password credentials on the local computer or the credentials that you supply in the command to log you in to the remote computer. The credentials and the rest of the transmission are encrypted. -To add additional protection, you can configure the remote computer to use Secure Sockets Layer (SSL) instead of HTTP to listen for Windows Remote Management (WinRM) requests. Then, users can use the UseSSL parameters of the Invoke-Command, New-PSSession, and Enter-PSSession cmdlets when establishing a connection. This option uses the more secure HTTPS channel instead of HTTP. +When you connect to a remote computer, the system uses the user name and +password credentials on the local computer or the credentials that you supply +in the command to log you in to the remote computer. The credentials and the +rest of the transmission are encrypted. +To add additional protection, you can configure the remote computer to use +Secure Sockets Layer (SSL) instead of HTTP to listen for Windows Remote +Management (WinRM) requests. Then, users can use the UseSSL parameters of the +Invoke-Command, New-PSSession, and Enter-PSSession cmdlets when establishing a +connection. This option uses the more secure HTTPS channel instead of HTTP. ### DO ALL REMOTE COMMANDS REQUIRE WINDOWS POWERSHELL REMOTING? -No. Several cmdlets have a ComputerName parameter that lets you get objects from the remote computer. - -These cmdlets do not use Windows PowerShell remoting. So, you can use them on any computer that is running Windows PowerShell, even if the computer is not configured for Windows PowerShell remoting or if the computer does not meet the requirements for Windows PowerShell remoting. -These cmdlets include the following cmdlets: +No. Several cmdlets have a ComputerName parameter that lets you get objects +from the remote computer. +These cmdlets do not use Windows PowerShell remoting. So, you can use them on +any computer that is running Windows PowerShell, even if the computer is not +configured for Windows PowerShell remoting or if the computer does not meet +the requirements for Windows PowerShell remoting. -``` -Get-Process -Get-Service -Get-WinEvent -Get-EventLog -Get-WmiObject -Test-Connection -``` +These cmdlets include the following: +- Get-Process +- Get-Service +- Get-WinEvent +- Get-EventLog +- Get-WmiObject +- Test-Connection To find all the cmdlets with a ComputerName parameter, type: - -``` -Get-Help * -Parameter ComputerName -or +```powershell +Get-Help * -Parameter ComputerName +# or Get-Command -ParameterName ComputerName ``` +To determine whether the ComputerName parameter of a particular cmdlet +requires Windows PowerShell remoting, see the parameter description. To +display the parameter description, type: -To determine whether the ComputerName parameter of a particular cmdlet requires Windows PowerShell remoting, see the parameter description. To display the parameter description, type: - - -``` +```ppowershell Get-Help -Parameter ComputerName ``` - For example: - -``` +```powershell Get-Help Get-Process -Parameter Computername ``` - For all other commands, use the Invoke-Command cmdlet. - ### HOW DO I RUN A COMMAND ON A REMOTE COMPUTER? + To run a command on a remote computer, use the Invoke-Command cmdlet. -Enclose your command in braces ( {} ) to make it a script block. Use the ScriptBlock parameter of Invoke-Command to specify the command. +Enclose your command in braces ( {} ) to make it a script block. Use the +ScriptBlock parameter of Invoke-Command to specify the command. -You can use the ComputerName parameter of Invoke-Command to specify a remote computer. Or, you can create a persistent connection to a remote computer (a session) and then use the Session parameter of Invoke-Command to run the command in the session. +You can use the ComputerName parameter of Invoke-Command to specify a remote +computer. Or, you can create a persistent connection to a remote computer (a +session) and then use the Session parameter of Invoke-Command to run the +command in the session. For example, the following commands run a Get-Process command remotely. +```powershell +Invoke-Command -ComputerName Server01, Server02 -ScriptBlock {Get-Process} + +# - OR - -``` -Invoke-Command -ComputerName Server01, Server02 -ScriptBlock {Get-Process} - - - OR - - Invoke-Command -Session $s -ScriptBlock {Get-Process} ``` +To interrupt a remote command, type CTRL\+C. The interruption request is +passed to the remote computer, where it terminates the remote command. -To interrupt a remote command, type CTRL\+C. The interruption request is passed to the remote computer, where it terminates the remote command. - -For more information about remote commands, see about_Remote and the Help topics for the cmdlets that support remoting. - +For more information about remote commands, see about_Remote and the Help +topics for the cmdlets that support remoting. ### CAN I JUST "TELNET INTO" A REMOTE COMPUTER? -You can use the Enter-PSSession cmdlet to start an interactive session with a remote computer. -At the Windows PowerShell prompt, type: +You can use the Enter-PSSession cmdlet to start an interactive session with a +remote computer. +At the Windows PowerShell prompt, type: -``` +```powershell Enter-PSSession ``` - -The command prompt changes to show that you are connected to the remote computer. - +The command prompt changes to show that you are connected to the remote +computer. ``` \C:> ``` - -Now, the commands that you type run on the remote computer just as though you typed them directly on the remote computer. +Now, the commands that you type run on the remote computer just as though you +typed them directly on the remote computer. To end the interactive session, type: - -``` +```powershell Exit-PSSession ``` - -An interactive session is a persistent session that uses the WS-Management protocol. It is not the same as using Telnet, but it provides a similar experience. +An interactive session is a persistent session that uses the WS-Management +protocol. It is not the same as using Telnet, but it provides a similar +experience. For more information, see Enter-PSSession. - ### CAN I CREATE A PERSISTENT CONNECTION? -Yes. You can run remote commands by specifying the name of the remote computer, its NetBIOS name, or its IP address. Or, you can run remote commands by specifying a Windows PowerShell session (PSSession) that is connected to the remote computer. -When you use the ComputerName parameter of Invoke-Command or Enter-PSSession, Windows PowerShell establishes a temporary connection. Windows PowerShell uses the connection to run only the current command, and then it closes the connection. This is a very efficient method for running a single command or several unrelated commands, even on many remote computers. +Yes. You can run remote commands by specifying the name of the remote +computer, its NetBIOS name, or its IP address. Or, you can run remote commands +by specifying a Windows PowerShell session (PSSession) that is connected to +the remote computer. -When you use the New-PSSession cmdlet to create a PSSession, Windows PowerShell establishes a persistent connection for the PSSession. Then, you can run multiple commands in the PSSession, including commands that share data. +When you use the ComputerName parameter of Invoke-Command or Enter-PSSession, +Windows PowerShell establishes a temporary connection. Windows PowerShell uses +the connection to run only the current command, and then it closes the +connection. This is a very efficient method for running a single command or +several unrelated commands, even on many remote computers. -Typically, you create a PSSession to run a series of related commands that share data. Otherwise, the temporary connection created by the ComputerName parameter is sufficient for most commands. +When you use the New-PSSession cmdlet to create a PSSession, Windows +PowerShell establishes a persistent connection for the PSSession. Then, you +can run multiple commands in the PSSession, including commands that share +data. -For more information about sessions, see about_PSSessions. +Typically, you create a PSSession to run a series of related commands that +share data. Otherwise, the temporary connection created by the ComputerName +parameter is sufficient for most commands. +For more information about sessions, see about_PSSessions. ### CAN I RUN COMMANDS ON MORE THAN ONE COMPUTER AT A TIME? -Yes. The ComputerName parameter of the Invoke-Command cmdlet accepts multiple computer names, and the Session parameter accepts multiple PSSessions. -When you run an Invoke-Command command, Windows PowerShell runs the commands on all of the specified computers or in all of the specified PSSessions. +Yes. The ComputerName parameter of the Invoke-Command cmdlet accepts multiple +computer names, and the Session parameter accepts multiple PSSessions. -Windows PowerShell can manage hundreds of concurrent remote connections. However, the number of remote commands that you can send might be limited by the resources of your computer and its capacity to establish and maintain multiple network connections. +When you run an Invoke-Command command, Windows PowerShell runs the commands +on all of the specified computers or in all of the specified PSSessions. -For more information, see the example in the Invoke-Command Help topic. +Windows PowerShell can manage hundreds of concurrent remote connections. +However, the number of remote commands that you can send might be limited by +the resources of your computer and its capacity to establish and maintain +multiple network connections. +For more information, see the example in the Invoke-Command Help topic. ### WHERE ARE MY PROFILES? -Windows PowerShell profiles are not run automatically in remote sessions, so the commands that the profile adds are not present in the session. In addition, the $profile automatic variable is not populated in remote sessions. -To run a profile in a session, use the Invoke-Command cmdlet. +Windows PowerShell profiles are not run automatically in remote sessions, so +the commands that the profile adds are not present in the session. In +addition, the \$profile automatic variable is not populated in remote sessions. -For example, the following command runs the CurrentUserCurrentHost profile from the local computer in the session in $s. +To run a profile in a session, use the `Invoke-Command` cmdlet. +For example, the following command runs the CurrentUserCurrentHost profile +from the local computer in the session in \$s. ``` Invoke-Command -Session $s -FilePath $profile ``` +The following command runs the CurrentUserCurrentHost profile from the remote +computer in the session in $s. Because the $profile variable is not populated, +the command uses the explicit path to the profile. -The following command runs the CurrentUserCurrentHost profile from the remote computer in the session in $s. Because the $profile variable is not populated, the command uses the explicit path to the profile. - - -``` -Invoke-Command -Session $s {. "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1"} +```powershell +Invoke-Command -Session $s { + . "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1" +} ``` +After running this command, the commands that the profile adds to the session +are available in $s. -After running this command, the commands that the profile adds to the session are available in $s. - -You can also use a startup script in a session configuration to run a profile in every remote session that uses the session configuration. - -For more information about Windows PowerShell profiles, see about_Profiles. For more information about session configurations, see Register-PSSessionConfiguration. +You can also use a startup script in a session configuration to run a profile +in every remote session that uses the session configuration. +For more information about Windows PowerShell profiles, see about_Profiles. +For more information about session configurations, see +Register-PSSessionConfiguration. ### HOW DOES THROTTLING WORK ON REMOTE COMMANDS? -To help you manage the resources on your local computer, Windows PowerShell includes a per-command throttling feature that lets you limit the number of concurrent remote connections that are established for each command. -The default is 32 concurrent connections, but you can use the ThrottleLimit parameters of the cmdlets to set a custom throttle limit for particular commands. +To help you manage the resources on your local computer, Windows PowerShell +includes a per-command throttling feature that lets you limit the number of +concurrent remote connections that are established for each command. -When you use the throttling feature, remember that it is applied to each command, not to the entire session or to the computer. If you are running commands concurrently in several sessions or PSSessions, the number of concurrent connections is the sum of the concurrent connections in all the sessions. +The default is 32 concurrent connections, but you can use the **ThrottleLimit** +parameters of the cmdlets to set a custom throttle limit for particular +commands. -To find cmdlets with a ThrottleLimit parameter, type: +When you use the throttling feature, remember that it is applied to each +command, not to the entire session or to the computer. If you are running +commands concurrently in several sessions or PSSessions, the number of +concurrent connections is the sum of the concurrent connections in all the +sessions. +To find cmdlets with a ThrottleLimit parameter, type: ``` -Get-Help * -Parameter ThrottleLimit --or- +Get-Help * -Parameter ThrottleLimit +-or- Get-Command -ParameterName ThrottleLimit ``` - ### IS THE OUTPUT OF REMOTE COMMANDS DIFFERENT FROM LOCAL OUTPUT? -When you use Windows PowerShell locally, you send and receive "live" .NET Framework objects; "live" objects are objects that are associated with actual programs or system components. When you invoke the methods or change the properties of live objects, the changes affect the actual program or component. And, when the properties of a program or component change, the properties of the object that represent them also change. -However, because most live objects cannot be transmitted over the network, Windows PowerShell "serializes" most of the objects sent in remote commands, that is, it converts each object into a series of XML (Constraint Language in XML [CLiXML]) data elements for transmission. +When you use Windows PowerShell locally, you send and receive "live" .NET +Framework objects; "live" objects are objects that are associated with actual +programs or system components. When you invoke the methods or change the +properties of live objects, the changes affect the actual program or +component. And, when the properties of a program or component change, the +properties of the object that represent them also change. -When Windows PowerShell receives a serialized object, it converts the XML into a deserialized object type. The deserialized object is an accurate record of the properties of the program or component at a previous time, but it is no longer "live", that is, it is no longer directly associated with the component. And, the methods are removed because they are no longer effective. +However, because most live objects cannot be transmitted over the network, +Windows PowerShell "serializes" most of the objects sent in remote commands, +that is, it converts each object into a series of XML (Constraint Language in +XML [CLiXML]) data elements for transmission. -Typically, you can use deserialized objects just as you would use live objects, but you must be aware of their limitations. Also, the objects that are returned by the Invoke-Command cmdlet have additional properties that help you to determine the origin of the command. +When Windows PowerShell receives a serialized object, it converts the XML into +a deserialized object type. The deserialized object is an accurate record of +the properties of the program or component at a previous time, but it is no +longer "live", that is, it is no longer directly associated with the +component. And, the methods are removed because they are no longer effective. -Some object types, such as DirectoryInfo objects and GUIDs, are converted back into live objects when they are received. These objects do not need any special handling or formatting. +Typically, you can use deserialized objects just as you would use live +objects, but you must be aware of their limitations. Also, the objects that +are returned by the Invoke-Command cmdlet have additional properties that help +you to determine the origin of the command. -For information about interpreting and formatting remote output, see about_Remote_Output. +Some object types, such as DirectoryInfo objects and GUIDs, are converted back +into live objects when they are received. These objects do not need any +special handling or formatting. +For information about interpreting and formatting remote output, see +[about_Remote_Output](about_Remote_Output.md). ### CAN I RUN BACKGROUND JOBS REMOTELY? -Yes. A Windows PowerShell background job is a Windows PowerShell command that runs asynchronously without interacting with the session. When you start a background job, the command prompt returns immediately, and you can continue to work in the session while the job runs even if it runs for an extended period of time. -You can start a background job even while other commands are running because background jobs always run asynchronously in a temporary session. +Yes. A Windows PowerShell background job is a Windows PowerShell command that +runs asynchronously without interacting with the session. When you start a +background job, the command prompt returns immediately, and you can continue +to work in the session while the job runs even if it runs for an extended +period of time. -You can run background jobs on a local or remote computer. By default, a background job runs on the local computer. However, you can use the AsJob parameter of the Invoke-Command cmdlet to run any remote command as a background job. And, you can use Invoke-Command to run a Start-Job command remotely. +You can start a background job even while other commands are running because +background jobs always run asynchronously in a temporary session. -For more information about background jobs in Windows PowerShell , see about_Jobs and about_Remote_Jobs. +You can run background jobs on a local or remote computer. By default, a +background job runs on the local computer. However, you can use the AsJob +parameter of the Invoke-Command cmdlet to run any remote command as a +background job. And, you can use Invoke-Command to run a Start-Job command +remotely. +For more information about background jobs in Windows PowerShell , see +[about_Jobs(about_Jobs.md)] and [about_Remote_Jobs(about_Remote_Jobs.md)]. ### CAN I RUN WINDOWS PROGRAMS ON A REMOTE COMPUTER? -You can use Windows PowerShell remote commands to run Windows-based programs on remote computers. For example, you can run Shutdown.exe or Ipconfig on a remote computer. -However, you cannot use Windows PowerShell commands to open the user interface for any program on a remote computer. +You can use Windows PowerShell remote commands to run Windows-based programs +on remote computers. For example, you can run Shutdown.exe or Ipconfig on a +remote computer. -When you start a Windows program on a remote computer, the command is not completed, and the Windows PowerShell command prompt does not return, until the program is finished or until you press CTRL\+C to interrupt the command. For example, if you run the IpConfig program on a remote computer, the command prompt does not return until IpConfig is completed. +However, you cannot use Windows PowerShell commands to open the user interface +for any program on a remote computer. -If you use remote commands to start a program that has a user interface, the program process starts, but the user interface does not appear. The Windows PowerShell command is not completed, and the command prompt does not return until you stop the program process or until you press CTRL\+C, which interrupts the command and stops the process. +When you start a Windows program on a remote computer, the command is not +completed, and the Windows PowerShell command prompt does not return, until +the program is finished or until you press CTRL\+C to interrupt the command. +For example, if you run the IpConfig program on a remote computer, the command +prompt does not return until IpConfig is completed. -For example, if you use a Windows PowerShell command to run Notepad on a remote computer, the Notepad process starts on the remote computer, but the Notepad user interface does not appear. To interrupt the command and restore the command prompt, press CTRL\+C. +If you use remote commands to start a program that has a user interface, the +program process starts, but the user interface does not appear. The Windows +PowerShell command is not completed, and the command prompt does not return +until you stop the program process or until you press CTRL\+C, which +interrupts the command and stops the process. +For example, if you use a Windows PowerShell command to run Notepad on a +remote computer, the Notepad process starts on the remote computer, but the +Notepad user interface does not appear. To interrupt the command and restore +the command prompt, press CTRL\+C. ### CAN I LIMIT THE COMMANDS THAT USERS CAN RUN REMOTELY ON MY COMPUTER? -Yes. Every remote session must use one of the session configurations on the remote computer. You can manage the session configurations on your computer (and the permissions to those session configurations) to determine who can run commands remotely on your computer and which commands they can run. - -A session configuration configures the environment for the session. You can define the configuration by using an assembly that implements a new configuration class or by using a script that runs in the session. The configuration can determine the commands that are available in the session. And, the configuration can include settings that protect the computer, such as settings that limit the amount of data that the session can receive remotely in a single object or command. You can also specify a security descriptor that determines the permissions that are required to use the configuration. - -The Enable-PSRemoting cmdlet creates the default session configurations on your computer: Microsoft.PowerShell, Microsoft.PowerShell.Workflow, and Microsoft.PowerShell32 (64-bit operating systems only). Enable-PSRemoting sets the security descriptor for the configuration to allow only members of the Administrators group on your computer to use them. - -You can use the session configuration cmdlets to edit the default session configurations, to create new session configurations, and to change the security descriptors of all the session configurations. -Beginning in Windows PowerShell 3.0, the New-PSSessionConfigurationFile cmdlet lets you create custom session configurations by using a text file. The file includes options for setting the language mode and for specifying the cmdlets and modules that are available in sessions that use the session configuration. - -When users use the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets, they can use the ConfigurationName parameter to indicate the session configuration that is used for the session. And, they can change the default configuration that their sessions use by changing the value of the $PSSessionConfigurationName preference variable in the session. - -For more information about session configurations, see the Help for the session configuration cmdlets. To find the session configuration cmdlets, type: - - -``` +Yes. Every remote session must use one of the session configurations on the +remote computer. You can manage the session configurations on your computer +(and the permissions to those session configurations) to determine who can run +commands remotely on your computer and which commands they can run. + +A session configuration configures the environment for the session. You can +define the configuration by using an assembly that implements a new +configuration class or by using a script that runs in the session. The +configuration can determine the commands that are available in the session. +And, the configuration can include settings that protect the computer, such as +settings that limit the amount of data that the session can receive remotely +in a single object or command. You can also specify a security descriptor that +determines the permissions that are required to use the configuration. + +The Enable-PSRemoting cmdlet creates the default session configurations on +your computer: Microsoft.PowerShell, Microsoft.PowerShell.Workflow, and +Microsoft.PowerShell32 (64-bit operating systems only). Enable-PSRemoting sets +the security descriptor for the configuration to allow only members of the +Administrators group on your computer to use them. + +You can use the session configuration cmdlets to edit the default session +configurations, to create new session configurations, and to change the +security descriptors of all the session configurations. + +Beginning in Windows PowerShell 3.0, the New-PSSessionConfigurationFile cmdlet +lets you create custom session configurations by using a text file. The file +includes options for setting the language mode and for specifying the cmdlets +and modules that are available in sessions that use the session configuration. + +When users use the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets, +they can use the ConfigurationName parameter to indicate the session +configuration that is used for the session. And, they can change the default +configuration that their sessions use by changing the value of the +$PSSessionConfigurationName preference variable in the session. + +For more information about session configurations, see the Help for the +session configuration cmdlets. To find the session configuration cmdlets, +type: + +```powershell Get-Command *PSSessionConfiguration ``` - - ### WHAT ARE FAN-IN AND FAN OUT CONFIGURATIONS? -The most common Windows PowerShell remoting scenario involving multiple computers is the one-to-many configuration, in which one local computer (the administrator's computer) runs Windows PowerShell commands on numerous remote computers. This is known as the "fan-out" scenario. -However, in some enterprises, the configuration is many-to-one, where many client computers connect to a single remote computer that is running Windows PowerShell, such as a file server or a kiosk. This is known as the "fan-in" configuration. +The most common Windows PowerShell remoting scenario involving multiple +computers is the one-to-many configuration, in which one local computer (the +administrator's computer) runs Windows PowerShell commands on numerous remote +computers. This is known as the "fan-out" scenario. -Windows PowerShell remoting supports both fan-out and fan-in configurations. +However, in some enterprises, the configuration is many-to-one, where many +client computers connect to a single remote computer that is running Windows +PowerShell, such as a file server or a kiosk. This is known as the "fan-in" +configuration. -For the fan-out configuration, Windows PowerShell uses the Web Services for Management (WS-Management) protocol and the WinRM service that supports the Microsoft implementation of WS-Management. When a local computer connects to a remote computer, WS-Management establishes a connection and uses a plug-in for Windows PowerShell to start the Windows PowerShell host process (Wsmprovhost.exe) on the remote computer. The user can specify an alternate port, an alternate session configuration, and other features to customize the remote connection. +Windows PowerShell remoting supports both fan-out and fan-in configurations. -To support the "fan-in" configuration, Windows PowerShell uses Internet Information Services (IIS) to host WS-Management, to load the Windows PowerShell plug-in, and to start Windows PowerShell. In this scenario, instead of starting each Windows PowerShell session in a separate process, all Windows PowerShell sessions run in the same host process. +For the fan-out configuration, Windows PowerShell uses the Web Services for +Management (WS-Management) protocol and the WinRM service that supports the +Microsoft implementation of WS-Management. When a local computer connects to a +remote computer, WS-Management establishes a connection and uses a plug-in for +Windows PowerShell to start the Windows PowerShell host process +(Wsmprovhost.exe) on the remote computer. The user can specify an alternate +port, an alternate session configuration, and other features to customize the +remote connection. -IIS hosting and fan-in remote management is not supported in Windows XP or in Windows Server 2003. +To support the "fan-in" configuration, Windows PowerShell uses Internet +Information Services (IIS) to host WS-Management, to load the Windows +PowerShell plug-in, and to start Windows PowerShell. In this scenario, instead +of starting each Windows PowerShell session in a separate process, all Windows +PowerShell sessions run in the same host process. -In a fan-in configuration, the user can specify a connection URI and an HTTP endpoint, including the transport, computer name, port, and application name. IIS forwards all the requests with a specified application name to the application. The default is WS-Management, which can host Windows PowerShell. +IIS hosting and fan-in remote management is not supported in Windows XP or in +Windows Server 2003. -You can also specify an authentication mechanism and prohibit or allow redirection from HTTP and HTTPS endpoints. +In a fan-in configuration, the user can specify a connection URI and an HTTP +endpoint, including the transport, computer name, port, and application name. +IIS forwards all the requests with a specified application name to the +application. The default is WS-Management, which can host Windows PowerShell. +You can also specify an authentication mechanism and prohibit or allow +redirection from HTTP and HTTPS endpoints. ### CAN I TEST REMOTING ON A SINGLE COMPUTER \(NOT IN A DOMAIN\)? -Yes. Windows PowerShell remoting is available even when the local computer is not in a domain. You can use the remoting features to connect to sessions and to create sessions on the same computer. The features work the same as they do when you connect to a remote computer. -To run remote commands on a computer in a workgroup, change the following Windows settings on the computer. +Yes. Windows PowerShell remoting is available even when the local computer is +not in a domain. You can use the remoting features to connect to sessions and +to create sessions on the same computer. The features work the same as they do +when you connect to a remote computer. -Caution: These settings affect all users on the system and they can make the system more vulnerable to a malicious attack. Use caution when making these changes. +To run remote commands on a computer in a workgroup, change the following +Windows settings on the computer. --- Windows XP with SP2: +Caution: These settings affect all users on the system and they can make the +system more vulnerable to a malicious attack. Use caution when making these +changes. -Use Local Security Settings (Secpol.msc) to change the setting of the "Network Access: Sharing and security model for local accounts" policy in Security Settings\Local Policies\Security Options to "Classic". +- Windows XP with SP2: --- Windows Vista, Windows 7, Windows 8: + Use Local Security Settings (Secpol.msc) to change the setting of the + "Network Access: Sharing and security model for local accounts" policy in + Security Settings\Local Policies\Security Options to "Classic". -Create the following registry entry, and then set its value to 1: LocalAccountTokenFilterPolicy in HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System +- Windows Vista, Windows 7, Windows 8: -You can use the following Windows PowerShell command to add this entry: + Create the following registry entry, and then set its value to 1: + LocalAccountTokenFilterPolicy in + HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System -New-ItemProperty ` -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System ` -Name LocalAccountTokenFilterPolicy -propertyType DWord -Value 1 + You can use the following Windows PowerShell command to add this entry: --- Windows Server 2003, Windows Server 2008, Windows Server 2012, Windows Server 2012 R2: + ```powershell + $parameters = @{ + Path='HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System' + Name='LocalAccountTokenFilterPolicy' + propertyType='DWord' + Value=1 + } + New-ItemProperty @parameters + ``` -No changes are needed because the default setting of the "Network Access: Sharing and security model for local accounts" policy is "Classic". Verify the setting in case it has changed. +- Windows Server 2003, Windows Server 2008, Windows Server 2012, Windows + Server 2012 R2: + No changes are needed because the default setting of the "Network Access: + Sharing and security model for local accounts" policy is "Classic". Verify + the setting in case it has changed. ### CAN I RUN REMOTE COMMANDS ON A COMPUTER IN ANOTHER DOMAIN? -Yes. Typically, the commands run without error, although you might need to use the Credential parameter of the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets to provide the credentials of a member of the Administrators group on the remote computer. This is sometimes required even when the current user is a member of the Administrators group on the local and remote computers. -However, if the remote computer is not in a domain that the local computer trusts, the remote computer might not be able to authenticate the user's credentials. +Yes. Typically, the commands run without error, although you might need to use +the **Credential** parameter of the `Invoke-Command`, `New-PSSession`, or +`Enter-PSSession` cmdlets to provide the credentials of a member of the +Administrators group on the remote computer. This is sometimes required even +when the current user is a member of the Administrators group on the local and +remote computers. -To enable authentication, use the following command to add the remote computer to the list of trusted hosts for the local computer in WinRM. Type the command at the Windows PowerShell prompt. +However, if the remote computer is not in a domain that the local computer +trusts, the remote computer might not be able to authenticate the user's +credentials. +To enable authentication, use the following command to add the remote computer +to the list of trusted hosts for the local computer in WinRM. Type the command +at the Windows PowerShell prompt. -``` +```powershell Set-Item WSMan:\localhost\Client\TrustedHosts -Value ``` +For example, to add the Server01 computer to the list of trusted hosts on the +local computer, type the following command at the Windows PowerShell prompt: -For example, to add the Server01 computer to the list of trusted hosts on the local computer, type the following command at the Windows PowerShell prompt: - - -``` +```powershell Set-Item WSMan:\localhost\Client\TrustedHosts -Value Server01 ``` - - ## SEE ALSO [about_Remote](about_Remote.md) @@ -357,7 +525,7 @@ Set-Item WSMan:\localhost\Client\TrustedHosts -Value Server01 [about_Remote_Variables](about_Remote_Variables.md) -Invoke-Command +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[New-PSSession](../New-PSSession.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md index 484b7285a6a..91f9354775f 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,272 +7,338 @@ title: about_Remote_Jobs --- # About Remote Jobs -## about_Remote_Jobs - ## SHORT DESCRIPTION -Describes how to run background jobs on remote computers. +Describes how to run background jobs on remote computers. ## DETAILED DESCRIPTION -A background job is a command that runs asynchronously without interacting with the current session. The command prompt returns immediately, and you can continue to use the session while the job runs. -By default, background jobs run on the local computer. However, you can use several different procedures to run background jobs on remote computers. +A background job is a command that runs asynchronously without interacting +with the current session. The command prompt returns immediately, and you can +continue to use the session while the job runs. -This topic explains how to run a background job on a remote computer. For information about how to run background jobs on a local computer, see about_Jobs. For more information about background jobs, see about_Job_Details. +By default, background jobs run on the local computer. However, you can use +several different procedures to run background jobs on remote computers. +This topic explains how to run a background job on a remote computer. For +information about how to run background jobs on a local computer, see +[about_Jobs](about_Jobs.md). For more information about background jobs, see +[about_Job_Details](about_Job_Details.md). ## REMOTE BACKGROUND JOBS -You can run background jobs on remote computers by using three different methods. --- Start an interactive session with a remote computer, and start a job in the interactive session. The procedures are the same as running a local job, although all actions are performed on the remote computer. +You can run background jobs on remote computers by using three different +methods. --- Run a background job on a remote computer that returns its results to the local computer. Use this method when you want to collect the results of background jobs and maintain them in a central location on the local computer. +- Start an interactive session with a remote computer, and start a job in the + interactive session. The procedures are the same as running a local job, + although all actions are performed on the remote computer. --- Run a background job on a remote computer that maintains its results on the remote computer. Use this method when the job data is more securely maintained on the originating computer. +- Run a background job on a remote computer that returns its results to the + local computer. Use this method when you want to collect the results of + background jobs and maintain them in a central location on the local computer. +- Run a background job on a remote computer that maintains its results on the + remote computer. Use this method when the job data is more securely maintained + on the originating computer. ### START A BACKGROUND JOB IN AN INTERACTIVE SESSION -You can start an interactive session with a remote computer and then start a background job during the interactive session. For more information about interactive sessions, see about_Remote, and see Enter-PSSession. -The procedure for starting a background job in an interactive session is almost identical to the procedure for starting a background job on the local computer. However, all of the operations occur on the remote computer, not the local computer. +You can start an interactive session with a remote computer and then start a +background job during the interactive session. For more information about +interactive sessions, see about_Remote, and see Enter-PSSession. +The procedure for starting a background job in an interactive session is +almost identical to the procedure for starting a background job on the local +computer. However, all of the operations occur on the remote computer, not the +local computer. #### STEP 1: ENTER-PSSESSION -Use the Enter-PSSession cmdlet to start an interactive session with a remote computer. You can use the ComputerName parameter of Enter-PSSession to establish a temporary connection for the interactive session. Or, you can use the Session parameter to run the interactive session in a Windows PowerShell® session (PSSession). -The following command starts an interactive session on the Server01 computer. +Use the Enter-PSSession cmdlet to start an interactive session with a remote +computer. You can use the ComputerName parameter of Enter-PSSession to +establish a temporary connection for the interactive session. Or, you can use +the Session parameter to run the interactive session in a Windows PowerShell +session (PSSession). +The following command starts an interactive session on the Server01 computer. -``` +```powershell C:\PS> Enter-PSSession -computername Server01 ``` - -The command prompt changes to show that you are now connected to the Server01 computer. - +The command prompt changes to show that you are now connected to the Server01 +computer. ``` Server01\C:> ``` - - #### STEP 2: START-JOB -To start a background job in the session, use the Start-Job cmdlet. -The following command runs a background job that gets the events in the Windows PowerShell event log on the Server01 computer. The Start-Job cmdlet returns an object that represents the job. +To start a background job in the session, use the Start-Job cmdlet. -This command saves the job object in the $job variable. +The following command runs a background job that gets the events in the +Windows PowerShell event log on the Server01 computer. The Start-Job cmdlet +returns an object that represents the job. +This command saves the job object in the \$job variable. -``` -Server01\C:> $job = start-job -scriptblock {get-eventlog "Windows PowerShell"} +```powershell +Server01\C:> $job = start-job -scriptblock { + get-eventlog "Windows PowerShell" +} ``` - -While the job runs, you can use the interactive session to run other commands, including other background jobs. However, you must keep the interactive session open until the job is completed. If you end the session, the job is interrupted, and the results are lost. - +While the job runs, you can use the interactive session to run other commands, +including other background jobs. However, you must keep the interactive +session open until the job is completed. If you end the session, the job is +interrupted, and the results are lost. #### STEP 3: GET-JOB -To find out if the job is complete, display the value of the $job variable, or use the Get-Job cmdlet to get the job. The following command uses the Get-Job cmdlet to display the job. +To find out if the job is complete, display the value of the \$job variable, +or use the Get-Job cmdlet to get the job. The following command uses the +Get-Job cmdlet to display the job. -``` -Server01\C:> get-job $job - -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Complete True localhost get-eventlog "Windows PowerShell" -``` - +```powershell +Server01\C:> get-job $job -The Get-Job output shows that job is running on the "localhost" computer because the job was started on and is running on the same computer (in this case, Server01). +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Complete True localhost get-eventlog "Windows... +``` +The Get-Job output shows that job is running on the "localhost" computer +because the job was started on and is running on the same computer (in this +case, Server01). #### STEP 4: RECEIVE-JOB -To get the results of the job, use the Receive-Job cmdlet. You can display the results in the interactive session or save them to a file on the remote computer. The following command gets the results of the job in the $job variable. The command uses the redirection operator (>) to save the results of the job in the PsLog.txt file on the Server01 computer. +To get the results of the job, use the Receive-Job cmdlet. You can display the +results in the interactive session or save them to a file on the remote +computer. The following command gets the results of the job in the $job +variable. The command uses the redirection operator (>) to save the results of +the job in the PsLog.txt file on the Server01 computer. -``` +```powershell Server01\C:> receive-job $job > c:\logs\PsLog.txt ``` - - #### STEP 5: EXIT-PSSESSION -To end the interactive session, use the Exit-PSSession cmdlet. The command prompt changes to show that you are back in the original session on the local computer. +To end the interactive session, use the Exit-PSSession cmdlet. The command +prompt changes to show that you are back in the original session on the local +computer. -``` -Server01\C:> Exit-PSSession +```powershell +Server01\C:> Exit-PSSession C:\PS> ``` - - #### STEP 6: INVOKE-COMMAND: GET-CONTENT -To view the contents of the PsLog.txt file on the Server01 computer at any time, start another interactive session, or run a remote command. This type of command is best run in a PSSession (a persistent connection) in case you want to use several commands to investigate and manage the data in the PsLog.txt file. For more information about PSSessions, see about_PSSessions. -The following commands use the New-PSSession cmdlet to create a PSSession that is connected to the Server01 computer, and they use the Invoke-Command cmdlet to run a Get-Content command in the PSSession to view the contents of the file. +To view the contents of the PsLog.txt file on the Server01 computer at any +time, start another interactive session, or run a remote command. This type of +command is best run in a PSSession (a persistent connection) in case you want +to use several commands to investigate and manage the data in the PsLog.txt +file. For more information about PSSessions, see about_PSSessions. +The following commands use the New-PSSession cmdlet to create a PSSession that +is connected to the Server01 computer, and they use the Invoke-Command cmdlet +to run a Get-Content command in the PSSession to view the contents of the +file. +```powershell +$s = new-pssession -computername Server01 +invoke-command -session $s -scriptblock { + get-content c:\logs\pslog.txt} ``` -C:\PS> $s = new-pssession -computername Server01 -C:\PS> invoke-command -session $s -scriptblock {get-content c:\logs\pslog.txt} -``` - - ### START A REMOTE JOB THAT RETURNS THE RESULTS TO THE LOCAL COMPUTER \(ASJOB\) -To start a background job on a remote computer that returns the command results to the local computer, use the AsJob parameter of a cmdlet such as the Invoke-Command cmdlet. -When you use the AsJob parameter, the job object is actually created on the local computer even though the job runs on the remote computer. When the job is completed, the results are returned to the local computer. +To start a background job on a remote computer that returns the command +results to the local computer, use the AsJob parameter of a cmdlet such as the +Invoke-Command cmdlet. -You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage any job created by any cmdlet. Many of the cmdlets that have AsJob parameters do not use Windows PowerShell remoting, so you can use them even on computers that are not configured for remoting and that do not meet the requirements for remoting. +When you use the AsJob parameter, the job object is actually created on the +local computer even though the job runs on the remote computer. When the job +is completed, the results are returned to the local computer. +You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage +any job created by any cmdlet. Many of the cmdlets that have AsJob parameters +do not use Windows PowerShell remoting, so you can use them even on computers +that are not configured for remoting and that do not meet the requirements for +remoting. #### STEP 1: INVOKE-COMMAND -ASJOB -The following command uses the AsJob parameter of Invoke-Command to start a background job on the Server01 computer. The job runs a Get-Eventlog command that gets the events in the System log. You can use the JobName parameter to assign a display name to the job. +The following command uses the AsJob parameter of Invoke-Command to start a +background job on the Server01 computer. The job runs a Get-Eventlog command +that gets the events in the System log. You can use the JobName parameter to +assign a display name to the job. -``` -invoke-command -computername Server01 -scriptblock {get-eventlog system} -asjob +```powershell +invoke-command -computername Server01 -scriptblock { + get-eventlog system} -asjob ``` - The results of the command resemble the following sample output. - +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Running True Server01 get-eventlog system ``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Running True Server01 get-eventlog system -``` - -When the AsJob parameter is used, Invoke-Command returns the same type of job object that Start-Job returns. You can save the job object in a variable, or you can use a Get-Job command to get the job. - -Note that the value of the Location property shows that the job ran on the Server01 computer. +When the AsJob parameter is used, Invoke-Command returns the same type of job +object that Start-Job returns. You can save the job object in a variable, or +you can use a Get-Job command to get the job. +Note that the value of the Location property shows that the job ran on the +Server01 computer. #### STEP 2: GET-JOB -To manage a job started by using the AsJob parameter of the Invoke-Command cmdlet, use the Job cmdlets. Because the job object that represents the remote job is on the local computer, you do not need to run remote commands to manage the job. -To determine whether the job is complete, use a Get-Job command. The following command gets all of the jobs that were started in the current session. +To manage a job started by using the AsJob parameter of the Invoke-Command +cmdlet, use the Job cmdlets. Because the job object that represents the remote +job is on the local computer, you do not need to run remote commands to manage +the job. +To determine whether the job is complete, use a Get-Job command. The following +command gets all of the jobs that were started in the current session. -``` +```powershell get-job ``` +Because the remote job was started in the current session, a local Get-Job +command gets the job. The State property of the job object shows that the +command was completed successfully. -Because the remote job was started in the current session, a local Get-Job command gets the job. The State property of the job object shows that the command was completed successfully. - - -``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Completed True Server01 get-eventlog system +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Completed True Server01 get-eventlog system ``` - - #### STEP 3: RECEIVE-JOB -To get the results of the job, use the Receive-Job cmdlet. Because the job results are automatically returned to the computer where the job object resides, you can get the results with a local Receive-Job command. -The following command uses the Receive-Job cmdlet to get the results of the job. It uses the session ID to identify the job. This command saves the job results in the $results variable. You can also redirect the results to a file. +To get the results of the job, use the Receive-Job cmdlet. Because the job +results are automatically returned to the computer where the job object +resides, you can get the results with a local Receive-Job command. +The following command uses the Receive-Job cmdlet to get the results of the +job. It uses the session ID to identify the job. This command saves the job +results in the $results variable. You can also redirect the results to a file. -``` +```powershell $results = receive-job -id 1 ``` - - ### START A REMOTE JOB THAT KEEPS THE RESULTS ON THE REMOTE COMPUTER -To start a background job on a remote computer that keeps the command results on the remote computer, use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. You can use this method to run background jobs on multiple computers. -When you run a Start-Job command remotely, the job object is created on the remote computer, and the job results are maintained on the remote computer. From the perspective of the job, all operations are local. You are just running commands remotely to manage a local job on the remote computer. +To start a background job on a remote computer that keeps the command results +on the remote computer, use the Invoke-Command cmdlet to run a Start-Job +command on a remote computer. You can use this method to run background jobs +on multiple computers. +When you run a Start-Job command remotely, the job object is created on the +remote computer, and the job results are maintained on the remote computer. +From the perspective of the job, all operations are local. You are just +running commands remotely to manage a local job on the remote computer. #### STEP 1: INVOKE-COMMAND START-JOB -Use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. -This command requires a PSSession (a persistent connection). If you use the ComputerName parameter of Invoke-Command to establish a temporary connection, the Invoke-Command command is considered to be complete when the job object is returned. As a result, the temporary connection is closed, and the job is canceled. +Use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. -The following command uses the New-PSSession cmdlet to create a PSSession that is connected to the Server01 computer. The command saves the PSSession in the $s variable +This command requires a PSSession (a persistent connection). If you use the +ComputerName parameter of Invoke-Command to establish a temporary connection, +the Invoke-Command command is considered to be complete when the job object is +returned. As a result, the temporary connection is closed, and the job is +canceled. +The following command uses the New-PSSession cmdlet to create a PSSession that +is connected to the Server01 computer. The command saves the PSSession in the +\$s variable. -``` +```powershell $s = new-pssession -computername Server01 ``` +The next command uses the Invoke-Command cmdlet to run a Start-Job command in +the PSSession. The Start-Job command and the Get-Eventlog command are enclosed +in braces. -The next command uses the Invoke-Command cmdlet to run a Start-Job command in the PSSession. The Start-Job command and the Get-Eventlog command are enclosed in braces. - - +```powershell +invoke-command -session $s -scriptblock { + start-job -scriptblock {get-eventlog system}} ``` -invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog system}} -``` - The results resemble the following sample output. - -``` -Id Name State HasMoreData Location Command --- ---- ----- ----------- -------- ------- +```Output +Id Name State HasMoreData Location Command +-- ---- ----- ----------- -------- ------- 2 Job2 Running True Localhost get-eventlog system ``` +When you run a Start-Job command remotely, Invoke-Command returns the same +type of job object that Start-Job returns. You can save the job object in a +variable, or you can use a Get-Job command to get the job. -When you run a Start-Job command remotely, Invoke-Command returns the same type of job object that Start-Job returns. You can save the job object in a variable, or you can use a Get-Job command to get the job. - -Note that the value of the Location property shows that the job ran on the local computer, known as "LocalHost", even though the job ran on the Server01 computer. Because the job object is created on the Server01 computer and the job runs on the same computer, it is considered to be a local background job. - +Note that the value of the Location property shows that the job ran on the +local computer, known as "LocalHost", even though the job ran on the Server01 +computer. Because the job object is created on the Server01 computer and the +job runs on the same computer, it is considered to be a local background job. #### STEP 2: INVOKE-COMMAND GET-JOB -To manage a remote background job, use the Job cmdlets. Because the job object is on the remote computer, you need to run remote commands to get, stop, wait for, or retrieve the job results. -To see if the job is complete, use an Invoke-Command command to run a Get-Job command in the PSSession that is connected to the Server01 computer. +To manage a remote background job, use the Job cmdlets. Because the job object +is on the remote computer, you need to run remote commands to get, stop, wait +for, or retrieve the job results. +To see if the job is complete, use an Invoke-Command command to run a Get-Job +command in the PSSession that is connected to the Server01 computer. -``` +```powershell invoke-command -session $s -scriptblock {get-job} ``` +The command returns a job object. The State property of the job object shows +that the command was completed successfully. -The command returns a job object. The State property of the job object shows that the command was completed successfully. - - +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +2 Job2 Completed True LocalHost get-eventlog system ``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -2 Job2 Completed True LocalHost get-eventlog system -``` - - #### STEP 3: INVOKE-COMMAND RECEIVE-JOB -To get the results of the job, use the Invoke-Command cmdlet to run a Receive-Job command in the PSSession that is connected to the Server01 computer. -The following command uses the Receive-Job cmdlet to get the results of the job. It uses the session ID to identify the job. This command saves the job results in the $results variable. It uses the Keep parameter of Receive-Job to keep the result in the job cache on the remote computer. +To get the results of the job, use the Invoke-Command cmdlet to run a +Receive-Job command in the PSSession that is connected to the Server01 +computer. +The following command uses the Receive-Job cmdlet to get the results of the +job. It uses the session ID to identify the job. This command saves the job +results in the \$results variable. It uses the Keep parameter of Receive-Job +to keep the result in the job cache on the remote computer. +```powershell +$results = invoke-command -session $s -scriptblock { + receive-job -sessionid 2 -keep} ``` -$results = invoke-command -session $s -scriptblock {receive-job -sessionid 2 -keep} -``` - - -You can also redirect the results to a file on the local or remote computer. The following command uses a redirection operator to save the results in a file on the Server01 computer. +You can also redirect the results to a file on the local or remote computer. +The following command uses a redirection operator to save the results in a +file on the Server01 computer. +```powershell +invoke-command -session $s -command { + receive-job -sessionid 2 > c:\logs\pslog.txt} ``` -invoke-command -session $s -command {receive-job -sessionid 2 > c:\logs\pslog.txt} -``` - - ## SEE ALSO @@ -284,21 +350,20 @@ invoke-command -session $s -command {receive-job -sessionid 2 > c:\logs\pslog.tx [about_Remote_Variables](about_Remote_Variables.md) -Invoke-Command - -Start-Job +[Invoke-Command](../Invoke-Command.md) -Get-Job +[Start-Job](../Start-Job.md) -Wait-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Wait-Job](../Wait-Job.md) -Remove-Job +[Stop-Job](../Stop-Job.md) -New-PSSession +[Remove-Job](../Remove-Job.md) -Enter-PSSession +[New-PSSession](../New-PSSession.md) -Exit-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[Exit-PSSession](../Exit-PSSession.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Properties.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Properties.md index 0b9c86c2f69..f9bea619992 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Properties.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Properties.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,278 +7,304 @@ title: about_Properties --- # About Properties -## about_Properties - ## SHORT DESCRIPTION -Describes how to use object properties in Windows PowerShell? +Describes how to use object properties in PowerShell. ## LONG DESCRIPTION -Windows PowerShell uses structured collections of information called objects to represent the items in data stores or the state of the computer. Typically, you work with object that are part of the Microsoft .NET Framework, but you can also create custom objects in Windows PowerShell. -The association between an item and its object is very close. When you change an object, you usually change the item that it represents. For example, when you get a file in Windows PowerShell, you do not get the actual file. Instead, you get a FileInfo object that represents the file. When you change the FileInfo object, the file changes too. +PowerShell uses structured collections of information called objects to +represent the items in data stores or the state of the computer. Typically, +you work with object that are part of the Microsoft .NET Framework, but you +can also create custom objects in PowerShell. -Most objects have properties. Properties are the data that is associated with an object. Different types of object have different properties. For example, a FileInfo object, which represents a file, has an IsReadOnly property that contains $True if the file the read-only attribute and $False if it does not. A DirectoryInfo object, which represents a file system directory, has a Parent property that contains the path to the parent directory. +The association between an item and its object is very close. When you change +an object, you usually change the item that it represents. For example, when +you get a file in PowerShell, you do not get the actual file. Instead, you get +a FileInfo object that represents the file. When you change the FileInfo +object, the file changes too. +Most objects have properties. Properties are the data that is associated with +an object. Different types of object have different properties. For example, a +FileInfo object, which represents a file, has an **IsReadOnly** property that +contains $True if the file the read-only attribute and $False if it does not. +A DirectoryInfo object, which represents a file system directory, has a Parent +property that contains the path to the parent directory. ### OBJECT PROPERTIES -To get the properties of an object, use the Get-Member cmdlet. For example, to get the properties of a FileInfo object, use the Get-ChildItem cmdlet to get the FileInfo object that represents a file. Then, use a pipeline operator (|) to send the FileInfo object to Get-Member. The following command gets the PowerShell.exe file and sends it to Get-Member. The $Pshome automatic variable contains the path of the Windows PowerShell installation directory. +To get the properties of an object, use the `Get-Member` cmdlet. For example, +to get the properties of a **FileInfo** object, use the `Get-ChildItem` cmdlet +to get the FileInfo object that represents a file. Then, use a pipeline +operator (|) to send the **FileInfo** object to `Get-Member`. The +following command gets the PowerShell.exe file and sends it to `Get-Member`. +The \$Pshome automatic variable contains the path of the PowerShell +installation directory. -``` +```powershell Get-ChildItem $pshome\PowerShell.exe | Get-Member ``` +The output of the command lists the members of the **FileInfo** object. +Members include both properties and methods. When you work in PowerShell, you +have access to all the members of the objects. -The output of the command lists the members of the FileInfo object. Members include both properties and methods. When you work in Windows PowerShell, you have access to all the members of the objects. - -To get only the properties of an object and not the methods, use the MemberType parameter of the Get-Member cmdlet with a value of "property", as shown in the following example. - +To get only the properties of an object and not the methods, use the +MemberType parameter of the `Get-Member` cmdlet with a value of "property", as +shown in the following example. -``` +```powershell Get-ChildItem $pshome\PowerShell.exe | Get-Member -MemberType property ``` - - -``` -TypeName: System.IO.FileInfo - -Name MemberType Definition ----- ---------- ---------- -Attributes Property System.IO.FileAttributes Attributes {get;set;} -CreationTime Property System.DateTime CreationTime {get;set;} -CreationTimeUtc Property System.DateTime CreationTimeUtc {get;set;} -Directory Property System.IO.DirectoryInfo Directory {get;} -DirectoryName Property System.String DirectoryName {get;} -Exists Property System.Boolean Exists {get;} -Extension Property System.String Extension {get;} -FullName Property System.String FullName {get;} -IsReadOnly Property System.Boolean IsReadOnly {get;set;} -LastAccessTime Property System.DateTime LastAccessTime {get;set;} -LastAccessTimeUtc Property System.DateTime LastAccessTimeUtc {get;set;} -LastWriteTime Property System.DateTime LastWriteTime {get;set;} -LastWriteTimeUtc Property System.DateTime LastWriteTimeUtc {get;set;} -Length Property System.Int64 Length {get;} +```Output +TypeName: System.IO.FileInfo + +Name MemberType Definition +---- ---------- ---------- +Attributes Property System.IO.FileAttributes Attributes {get;set;} +CreationTime Property System.DateTime CreationTime {get;set;} +CreationTimeUtc Property System.DateTime CreationTimeUtc {get;set;} +Directory Property System.IO.DirectoryInfo Directory {get;} +DirectoryName Property System.String DirectoryName {get;} +Exists Property System.Boolean Exists {get;} +Extension Property System.String Extension {get;} +FullName Property System.String FullName {get;} +IsReadOnly Property System.Boolean IsReadOnly {get;set;} +LastAccessTime Property System.DateTime LastAccessTime {get;set;} +LastAccessTimeUtc Property System.DateTime LastAccessTimeUtc {get;set;} +LastWriteTime Property System.DateTime LastWriteTime {get;set;} +LastWriteTimeUtc Property System.DateTime LastWriteTimeUtc {get;set;} +Length Property System.Int64 Length {get;} Name Property System.String Name {get;} ``` - -After you find the properties, you can use them in your Windows PowerShell commands. - +After you find the properties, you can use them in your PowerShell commands. ## PROPERTY VALUES -Although every object of a specific type has the same properties, the values of those properties describe the particular object. For example, every FileInfo object has a CreationTime property, but the value of that property differs for each file. - -The most common way to get the values of the properties of an object is to use the dot method. Type a reference to the object, such as a variable that contains the object, or a command that gets the object. Then, type a dot (.) followed by the property name. - -For example, the following command displays the value of the CreationTime property of the PowerShell.exe file. The Get-ChildItem command returns a FileInfo object that represents the PowerShell.exe file. The command is enclosed in parentheses to make sure that it is executed before any properties are accessed. The Get-ChildItem command is followed by a dot and the name of the CreationTime property, as follows: - -``` -C:\PS> (Get-ChildItem $pshome\PowerShell.exe).creationtime +Although every object of a specific type has the same properties, the values +of those properties describe the particular object. For example, every +FileInfo object has a CreationTime property, but the value of that property +differs for each file. + +The most common way to get the values of the properties of an object is to use +the dot method. Type a reference to the object, such as a variable that +contains the object, or a command that gets the object. Then, type a dot (.) +followed by the property name. + +For example, the following command displays the value of the CreationTime +property of the PowerShell.exe file. The `Get-ChildItem` command returns a +FileInfo object that represents the PowerShell.exe file. The command is +enclosed in parentheses to make sure that it is executed before any properties +are accessed. The `Get-ChildItem` command is followed by a dot and the name of +the CreationTime property, as follows: + +```powershell +C:\PS> (Get-ChildItem $pshome\PowerShell.exe).creationtime Tuesday, March 18, 2008 12:07:52 AM ``` +You can also save an object in a variable and then get its properties by using +the dot method, as shown in the following example: -You can also save an object in a variable and then get its properties by using the dot method, as shown in the following example: - - -``` -C:\PS> $a = Get-ChildItem $pshome\PowerShell.exe -C:\PS> $a.CreationTime +```powershell +C:\PS> $a = Get-ChildItem $pshome\PowerShell.exe +C:\PS> $a.CreationTime Tuesday, March 18, 2008 12:07:52 AM ``` +You can also use the `Select-Object` and `Format-List` cmdlets to display the +property values of an object. `Select-Object` and `Format-List` each have a +**Property** parameter. You can use the **Property** parameter to specify one +or more properties and their values. Or, you can use the wildcard character +(\*) to represent all the properties. -You can also use the Select-Object and Format-List cmdlets to display the property values of an object. Select-Object and Format-List each have a Property parameter. You can use the Property parameter to specify one or more properties and their values. Or, you can use the wildcard character (\*) to represent all the properties. - -For example, the following command displays the values of all the properties of the PowerShell.exe file. - +For example, the following command displays the values of all the properties +of the PowerShell.exe file. -``` +```powershell C:\PS> Get-ChildItem $pshome\PowerShell.exe | Format-List -property * ``` - - -``` -PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe -PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\system32\WindowsPowerShell\v1.0 -PSChildName : PowerShell.exe -PSDrive : C -PSProvider : Microsoft.PowerShell.Core\FileSystem -PSIsContainer : False -VersionInfo : File: C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe - InternalName: POWERSHELL - OriginalFilename: PowerShell.EXE.MUI - File Version: 6.1.6570.1 (fbl_srv_PowerShell(nigels).070711-0102) - FileDescription: PowerShell.EXE - Product: Microsoft® Windows® Operating System - ProductVersion: 6.1.6570.1 - Debug: False - Patched: False - PreRelease: False - PrivateBuild: True - SpecialBuild: False +```Output +PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\System3 + 2\WindowsPowerShell\v1.0\PowerShell.exe +PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\System3 + 2\WindowsPowerShell\v1.0 +PSChildName : PowerShell.exe +PSDrive : C +PSProvider : Microsoft.PowerShell.Core\FileSystem +PSIsContainer : False +Mode : -a---- +VersionInfo : File: C:\Windows\System32\WindowsPowerShell\ + v1.0\PowerShell.exe + InternalName: POWERSHELL + OriginalFilename: PowerShell.EXE.MUI + FileVersion: 10.0.16299.15 (WinBuild.160101.0800) + FileDescription: Windows PowerShell + Product: Microsoft® Windows® Operating System + ProductVersion: 10.0.16299.15 + Debug: False + Patched: False + PreRelease: False + PrivateBuild: False + SpecialBuild: False Language: English (United States) -``` - - -``` -BaseName : PowerShell -Mode : -a--- -Name : PowerShell.exe -Length : 160256 -DirectoryName : C:\Windows\system32\WindowsPowerShell\v1.0 -Directory : C:\Windows\system32\WindowsPowerShell\v1.0 -IsReadOnly : False -Exists : True -FullName : C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe -Extension : .exe -CreationTime : 3/18/2008 12:07:52 AM -CreationTimeUtc : 3/18/2008 7:07:52 AM -LastAccessTime : 3/19/2008 8:13:58 AM -LastAccessTimeUtc : 3/19/2008 3:13:58 PM -LastWriteTime : 3/18/2008 12:07:52 AM -LastWriteTimeUtc : 3/18/2008 7:07:52 AM +BaseName : PowerShell +Target : {C:\Windows\WinSxS\amd64_microsoft-windows-powershell-ex + e_31bf3856ad364e35_10.0.16299.15_none_8c022aa6735716ae\p + owershell.exe} +LinkType : HardLink +Name : PowerShell.exe +Length : 449024 +DirectoryName : C:\Windows\System32\WindowsPowerShell\v1.0 +Directory : C:\Windows\System32\WindowsPowerShell\v1.0 +IsReadOnly : False +Exists : True +FullName : C:\Windows\System32\WindowsPowerShell\v1.0\PowerShell.ex +Extension : .exe +CreationTime : 9/29/2017 6:43:19 AM +CreationTimeUtc : 9/29/2017 1:43:19 PM +LastAccessTime : 9/29/2017 6:43:19 AM +LastAccessTimeUtc : 9/29/2017 1:43:19 PM +LastWriteTime : 9/29/2017 6:43:19 AM +LastWriteTimeUtc : 9/29/2017 1:43:19 PM Attributes : Archive ``` - - ### STATIC PROPERTIES -You can use the static properties of .NET classes in Windows PowerShell. Static properties are properties of class, unlike standard properties, which are properties of an object. -To get the static properties of an class, use the Static parameter of the Get-Member cmdlet. +You can use the static properties of .NET classes in PowerShell. Static +properties are properties of class, unlike standard properties, which are +properties of an object. -For example, the following command gets the static properties of the System.DateTime class. +To get the static properties of an class, use the Static parameter of the +Get-Member cmdlet. +For example, the following command gets the static properties of the +`System.DateTime` class. -``` +```powershell Get-Date | Get-Member -MemberType Property -Static ``` +```Output +TypeName: System.DateTime - -``` -TypeName: System.DateTime - -Name MemberType Definition ----- ---------- ---------- -MaxValue Property static datetime MaxValue {get;} -MinValue Property static datetime MinValue {get;} -Now Property datetime Now {get;} -Today Property datetime Today {get;} +Name MemberType Definition +---- ---------- ---------- +MaxValue Property static datetime MaxValue {get;} +MinValue Property static datetime MinValue {get;} +Now Property datetime Now {get;} +Today Property datetime Today {get;} UtcNow Property datetime UtcNow {get;} ``` - To get the value of a static property, use the following syntax. - -``` +```powershell []:: ``` +For example, the following command gets the value of the UtcNow static +property of the `System.DateTime` class. -For example, the following command gets the value of the UtcNow static property of the System.DateTime class. - - -``` +```powershell [System.DateTime]::UtcNow ``` - - ### PROPERTIES OF SCALAR OBJECTS AND COLLECTIONS -The properties of one ("scalar") object of a particular type are often different from the properties of a collection of objects of the same type. -For example, every service has as DisplayName property, but a collection of services does not have a DisplayName property. Similarly, all collections have a Count property that tells how many objects are in the collection, but individual objects do not have a Count property. +The properties of one ("scalar") object of a particular type are often +different from the properties of a collection of objects of the same type. -Beginning in Windows PowerShell 3.0, Windows PowerShell tries to prevent scripting errors that result from the differing properties of scalar objects and collections. +For example, every service has as **DisplayName** property, but a collection +of services does not have a **DisplayName** property. Similarly, all +collections have a **Count** property that tells how many objects are in the +collection, but individual objects do not have a **Count** property. -If you submit a collection, but request a property that exists only on single ("scalar") objects, Windows PowerShell returns the value of that property for every object in the collection. +Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that +result from the differing properties of scalar objects and collections. -If you request the Count or Length property of zero objects or of one object, Windows PowerShell returns the correct value. +If you submit a collection, but request a property that exists only on single +("scalar") objects, PowerShell returns the value of that property for every +object in the collection. -If the property exists on the individual objects and on the collection, Windows PowerShell does not alter the result. +If you request the Count or Length property of zero objects or of one object, +PowerShell returns the correct value. -This feature also works on methods of scalar objects and collections. For more information, see about_Methods. +If the property exists on the individual objects and on the collection, +PowerShell does not alter the result. +This feature also works on methods of scalar objects and collections. For more +information, see about_Methods. ### EXAMPLES -For example, each service has a DisplayName property. The following command gets the value of the DisplayName property of the Audiosrv service. +For example, each service has a DisplayName property. The following command +gets the value of the DisplayName property of the Audiosrv service. -``` -PS C:\> (Get-Service Audiosrv).DisplayName +```powershell +PS C:\> (Get-Service Audiosrv).DisplayName Windows Audio ``` +However, a collection or array of services does not have a **DisplayName**. +The following command tries to get the DisplayName property of all services in +PowerShell 2.0. -However, a collection or array of services does not have a DisplayName. The following command tries to get the DisplayName property of all services in Windows PowerShell 2.0. - - -``` -PS C:\> (Get-Service).DisplayName +```powershell +PS C:\> (Get-Service).DisplayName PS C:\> ``` +Beginning in PowerShell 3.0, the same command returns the value of the +**DisplayName** property of every service that `Get-Service` returns. -Beginning in Windows PowerShell 3.0, the same command returns the value of the DisplayName property of every service that Get-Service returns. - - -``` -PS C:\> (Get-Service).DisplayName -Application Experience -Application Layer Gateway Service -Windows All-User Install Agent -Application Identity -Application Information +```powershell +PS C:\> (Get-Service).DisplayName +Application Experience +Application Layer Gateway Service +Windows All-User Install Agent +Application Identity +Application Information ... ``` +Conversely, a collection of two or more services has a **Count** property, +which contains the number of objects in the collection. -Conversely, a collection of two or more services has a Count property, which contains the number of objects in the collection. - - -``` -PS C:\> (Get-Service).Count +```powershell +PS C:\> (Get-Service).Count 176 ``` +Individual services do not have a Count or Length property, as shown in this +command in PowerShell 2.0. -Individual services do not have a Count or Length property, as shown in this command in Windows PowerShell 2.0. - - -``` -PS C:\> (Get-Service Audiosrv).Count +```powershell +PS C:\> (Get-Service Audiosrv).Count PS C:\> ``` +Beginning in PowerShell 3.0, the command returns the correct Count value. -Beginning in Windows PowerShell 3.0, the command returns the correct Count value. - - -``` -PS C:\> (Get-Service Audiosrv).Count +```powershell +PS C:\> (Get-Service Audiosrv).Count 1 ``` - - ## SEE ALSO [about_Methods](about_Methods.md) [about_Objects](about_Objects.md) -Get-Member - -Select-Object +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) -Format-List +[Select-Object](../../Microsoft.PowerShell.Utility/Select-Object.md) +[Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) \ No newline at end of file diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Redirection.md index 87e58a09328..21d289c7f6e 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -1,135 +1,145 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us -keywords: powershell,cmdlet +keywords: PowerShell,cmdlet title: about_Redirection --- # About Redirection -## about_Redirection - ## SHORT DESCRIPTION -Explains how to redirect output from Windows PowerShell?to text files. +Explains how to redirect output from PowerShell to text files. ## LONG DESCRIPTION -By default, Windows PowerShell sends its command output to the Windows PowerShell console. However, you can direct the output to a text file, and you can redirect error output to the regular output stream. -You can use the following methods to redirect output: +By default, PowerShell sends its command output to the PowerShell console. +However, you can direct the output to a text file, and you can redirect error +output to the regular output stream. -- Use the Out-File cmdlet, which sends command output to a text file. Typically, you use the Out-File cmdlet when you need to use its parameters, such as the Encoding, Force, Width, or NoClobber parameters. +You can use the following methods to redirect output: -- Use the Tee-Object cmdlet, which sends command output to a text file and then sends it to the pipeline. +- Use the `Out-File` cmdlet, which sends command output to a text file. + Typically, you use the `Out-File` cmdlet when you need to use its parameters, + such as the **Encoding**, **Force**, **Width**, or **NoClobber** parameters. -- Use the Windows PowerShell redirection operators. +- Use the Tee-Object cmdlet, which sends command output to a text file and + then sends it to the pipeline. +- Use the PowerShell redirection operators. -### WINDOWS POWERSHELL REDIRECTION OPERATORS -The redirection operators enable you to send particular types of output to files and to the success output stream. +### POWERSHELL REDIRECTION OPERATORS -The Windows PowerShell redirection operators use the following characters to represent each output type: +The redirection operators enable you to send particular types of output to +files and to the success output stream. +The PowerShell redirection operators use the following characters to represent +each output type: ``` -* All output -1 Success output -2 Errors -3 Warning messages -4 Verbose output +* All output +1 Success output +2 Errors +3 Warning messages +4 Verbose output 5 Debug messages ``` +NOTE: The All (\*), Warning (3), Verbose (4) and Debug (5) redirection +operators were introduced in PowerShell 3.0. They do not work in earlier +versions of PowerShell. -NOTE: The All (\*), Warning (3), Verbose (4) and Debug (5) redirection operators were introduced in Windows PowerShell 3.0. They do not work in earlier versions of Windows PowerShell. +The PowerShell redirection operators are as follows. -The Windows PowerShell redirection operators are as follows. +``` +Operator Description Example +-------- ---------------------- ------------------------------ +> Sends output to the Get-Process > Process.txt + specified file. +>> Appends the output to dir *.ps1 >> Scripts.txt + the contents of the + specified file. -``` -Operator Description Example --------- ---------------------- ------------------------------ -> Sends output to the Get-Process > Process.txt - specified file. - ->> Appends the output to dir *.ps1 >> Scripts.txt - the contents of the - specified file. - -2> Sends errors to the Get-Process none 2> Errors.txt - specified file. - -2>> Appends errors to Get-Process none 2>> Save-Errors.txt - the contents of the - specified file. - -2>&1 Sends errors (2) and Get-Process none, Powershell 2>&1 - success output (1) - to the success - output stream. - -3> Sends warnings to the Write-Warning "Test!" 3> Warnings.txt - specified file. - -3>> Appends warnings to Write-Warning "Test!" 3>> Save-Warnings.txt - the contents of the - specified file. - -3>&1 Sends warnings (3) and function Test-Warning - success output (1) { Get-Process PowerShell; - to the success Write-Warning "Test!" } - output stream. Test-Warning 3>&1 - -4> Sends verbose output to Import-Module * -Verbose 4> Verbose.txt - the specified file. - -4>> Appends verbose output Import-Module * -Verbose 4>> Save-Verbose.txt - to the contents of the - specified file. - -4>&1 Sends verbose output (4) Import-Module * -Verbose 4>&1 - and success output (1) - to the success output - stream. - -5> Sends debug messages to Write-Debug "Starting" 5> Debug.txt - the specified file. - -5>> Appends debug messages Write-Debug "Saving" 5>> Save-Debug.txt - to the contents of the - specified file. - -5>&1 Sends debug messages (5) function Test-Debug - and success output (1) { Get-Process PowerShell - to the success output Write-Debug "PS" } - stream. Test-Debug 5>&1 - -*> Sends all output types function Test-Output - to the specified file. { Get-Process PowerShell, none - Write-Warning "Test!" -*>> Appends all output types Write-Verbose "Test Verbose" - to the contents of the Write-Debug "Test Debug" } - specified file. - Test-Output *> Test-Output.txt -*>&1 Sends all output types Test-Output *>> Test-Output.txt - (*) to the success output Test-Output *>&1 +2> Sends errors to the Get-Process none 2> Errors.txt + specified file. + +2>> Appends errors to Get-Process none 2>> Save-Errors.txt + the contents of the + specified file. + +2>&1 Sends errors (2) and Get-Process none, Powershell 2>&1 + success output (1) + to the success + output stream. + +3> Sends warnings to the Write-Warning "Test!" 3> Warnings.txt + specified file. + +3>> Appends warnings to Write-Warning "Test!" 3>> Warnings.txt + the contents of the + specified file. + +3>&1 Sends warnings (3) and function Test-Warning + success output (1) { Get-Process PowerShell; + to the success Write-Warning "Test!" } + output stream. Test-Warning 3>&1 + +4> Sends verbose output to Import-Module * -Verbose 4> Verbose.txt + the specified file. + +4>> Appends verbose output Import-Module * -Verbose 4>> Verbose.txt + to the contents of the + specified file. + +4>&1 Sends verbose output (4) Import-Module * -Verbose 4>&1 + and success output (1) + to the success output stream. -``` +5> Sends debug messages to Write-Debug "Starting" 5> Debug.txt + the specified file. + +5>> Appends debug messages Write-Debug "Saving" 5>> Debug.txt + to the contents of the + specified file. + +5>&1 Sends debug messages (5) function Test-Debug + and success output (1) { Get-Process PowerShell + to the success output Write-Debug "PS" } + stream. Test-Debug 5>&1 + +*> Sends all output types function Test-Output + to the specified file. { Get-Process PowerShell, none + Write-Warning "Test!" +*>> Appends all output types Write-Verbose "Test Verbose" + to the contents of the Write-Debug "Test Debug" } + specified file. + Test-Output *> Test-Output.txt +*>&1 Sends all output types Test-Output *>> Test-Output.txt + (*) to the success Test-Output *>&1 + output stream. +``` The syntax of the redirection operators is as follows: - ``` [\] ``` +If the specified file already exists, the redirection operators that do not +append data (> and n>) overwrite the current contents of the file without +warning. However, if the file is a read-only, hidden, or system file, the +redirection fails. The append redirection operators (>> and n>>) do not write +to a read-only file, but they append content to a system or hidden file. -If the specified file already exists, the redirection operators that do not append data (> and n>) overwrite the current contents of the file without warning. However, if the file is a read-only, hidden, or system file, the redirection fails. The append redirection operators (>> and n>>) do not write to a read-only file, but they append content to a system or hidden file. - -To force the redirection of content to a read-only, hidden, or system file, use the Out-File cmdlet with its Force parameter. When you are writing to files, the redirection operators use Unicode encoding. If the file has a different encoding, the output might not be formatted correctly. To redirect content to non-Unicode files, use the Out-File cmdlet with its Encoding parameter. - +To force the redirection of content to a read-only, hidden, or system file, +use the Out-File cmdlet with its Force parameter. When you are writing to +files, the redirection operators use Unicode encoding. If the file has a +different encoding, the output might not be formatted correctly. To redirect +content to non-Unicode files, use the Out-File cmdlet with its Encoding +parameter. ## SEE ALSO @@ -142,4 +152,3 @@ Tee-Object [about_Command_Syntax](about_Command_Syntax.md) [about_Path_Syntax](about_Path_Syntax.md) - diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 00bb519f161..9194ac278b4 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -16,50 +16,132 @@ Describes regular expressions in Windows PowerShell. Windows PowerShell supports the following regular expression characters. -| Format | Logic | Example | -| ------- | ----- | ------- | -| value | Matches exact characters anywhere in the original value. | "book" -match "oo" | -| . | Matches any single character. | "copy" -match "c..y" | -| [value] | Matches at least one of the characters in the brackets. | "big" -match "b[iou]g" | -| [range] | Matches at least one of the characters within the range. The use of a hyphen (-) allows you to specify an adjacent character. | "and" -match "[a-e]nd" | -| [^] | Matches any characters except those in brackets. | "and" -match "[^brt]nd" | -| ^ | Matches the beginning characters. | "book" -match "^bo" | -| $ | Matches the end characters. | "book" -match "ok$" | -| * | Matches any instances of the preceding character. | "baggy" -match "g*" | -| ? | Matches zero or one instance of the preceding character. | "baggy" -match "g?" | -| \ | Matches the character that follows as an escaped character. | "Try$" -match "Try\\$" | - -Windows PowerShell supports the character classes available in -Microsoft .NET Framework regular expressions. - -| Format | Logic | Example | -| -------- | ----- | ------- | -| \p{name} | Matches any character in the named character class specified by {name}. Supported names are Unicode groups and block ranges such as Ll, Nd, Z, IsGreek, and IsBoxDrawing. | "abcd defg" -match "\p{Ll}+" | -| \P{name} | Matches text not included in the groups and block ranges specified in {name}. | 1234 -match "\P{Ll}+" | -| \w | Matches any word character. Equivalent to the Unicode character categories [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. If ECMAScript-compliant behavior is specified with the ECMAScript option, \w is equivalent to [a-zA-Z_0-9]. | "abcd defg" -match "\w+" (this matches abcd) | -| \W | Matches any nonword character. Equivalent to the Unicode categories [^\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. | "abcd defg" -match "\W+" (this matches the space) | -| \s | Matches any white-space character. Equivalent to the Unicode character categories [\f\n\r\t\v\x85\p{Z}]. | "abcd defg" -match "\s+" | -| \S | Matches any non-white-space character. Equivalent to the Unicode character categories [^\f\n\r\t\v\x85\p{Z}]. | "abcd defg" -match "\S+" | -| \d | Matches any decimal digit. Equivalent to \p{Nd} for Unicode and [0-9] for non-Unicode behavior. | 12345 -match "\d+" | -| \D | Matches any nondigit. Equivalent to \P{Nd} for Unicode and [^0-9] for non-Unicode behavior. | "abcd" -match "\D+" | - +``` +Format value +Logic Matches exact characters anywhere in the original value. +Example "book" -match "oo" + +Format . +Logic Matches any single character. +Example "copy" -match "c..y" + +Format [value] +Logic Matches at least one of the characters in the brackets. +Example "big" -match "b[iou]g" + +Format [range] +Logic Matches at least one of the characters within the range. The use + of a hyphen (-) allows you to specify an adjacent character. +Example "and" -match "[a-e]nd" + +Format [^] +Logic Matches any characters except those in brackets. +Example "and" -match "[^brt]nd" + +Format ^ +Logic Matches the beginning characters. +Example "book" -match "^bo" + +Format $ +Logic Matches the end characters. +Example "book" -match "ok$" + +Format * +Logic Matches any instances of the preceding character. +Example "baggy" -match "g*" + +Format ? +Logic Matches zero or one instance of the preceding character. +Example "baggy" -match "g?" + +Format \ +Logic Matches the character that follows as an escaped character. +Example "Try$" -match "Try\\$" +``` + +Windows PowerShell supports the character classes available in Microsoft .NET +Framework regular expressions. + +``` +Format: \p{name} +Logic: Matches any character in the named character class specified by + {name}. Supported names are Unicode groups and block ranges such + as Ll, Nd, Z, IsGreek, and IsBoxDrawing. +Example: "abcd defg" -match "\p{Ll}+" + +Format: \P{name} +Logic: Matches text not included in the groups and block ranges specified + in {name}. +Example: 1234 -match "\P{Ll}+" + +Format: \w +Logic: Matches any word character. Equivalent to the Unicode character + categories [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. If ECMAScript- + compliant behavior is specified with the ECMAScript option, \w is + equivalent to [a-zA-Z_0-9]. +Example: "abcd defg" -match "\w+" (this matches abcd) + +Format: \W +Logic: Matches any nonword character. Equivalent to the Unicode categories + [^\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. +Example: "abcd defg" -match "\W+" (this matches the space) + +Format: \s +Logic: Matches any white-space character. Equivalent to the Unicode + character categories [\f\n\r\t\v\x85\p{Z}]. +Example: "abcd defg" -match "\s+" + +Format: \S +Logic: Matches any non-white-space character. Equivalent to the Unicode + character categories [^\f\n\r\t\v\x85\p{Z}]. +Example: "abcd defg" -match "\S+" + +Format: \d +Logic: Matches any decimal digit. Equivalent to \p{Nd} for Unicode and + [0-9] for non-Unicode behavior. +Example: 12345 -match "\d+" + +Format: \D +Logic: Matches any nondigit. Equivalent to \P{Nd} for Unicode and [^0-9] + for non-Unicode behavior. +Example: "abcd" -match "\D+" +``` Windows PowerShell supports the quantifiers available in .NET Framework regular expressions. The following are some examples of quantifiers. -| Format | Logic | Example | -| ------ | ----- | ------- | -| * | Specifies zero or more matches; for example, \wor (abc). Equivalent to {0,}. | "abc" -match "\w*" | -| + | Matches repeating instances of the preceding characters. | "xyxyxy" -match "xy+" | -| ? | Specifies zero or one matches; for example, \w? or (abc)?. Equivalent to {0,1}. | "abc" -match "\w?" | -| {n} | Specifies exactly n matches; for example, (pizza){2}. | "abc" -match "\w{2}" | -| {n,} | Specifies at least n matches; for example, (abc){2,}. | "abc" -match "\w{2,}" | -| {n,m} | Specifies at least n, but no more than m, matches. | "abc" -match "\w{2,3}" | +``` +Format: * +Logic Specifies zero or more matches; for example, \wor (abc). Equivalent + to {0,}. +Example: "abc" -match "\w*" + +Format: + +Logic: Matches repeating instances of the preceding characters. +Example: "xyxyxy" -match "xy+" + +Format: ? +Logic: Specifies zero or one matches; for example, \w? or (abc)?. + Equivalent to {0,1}. +Example: "abc" -match "\w?" + +Format: {n} +Logic: Specifies exactly n matches; for example, (pizza){2}. +Example: "abc" -match "\w{2}" + +Format: {n,} +Logic: Specifies at least n matches; for example, (abc){2,}. +Example: "abc" -match "\w{2,}" + +Format: {n,m} +Logic: Specifies at least n, but no more than m, matches. +Example: "abc" -match "\w{2,3}" +``` All the comparisons shown in the preceding table evaluate to true. -Notice that the escape character for regular expressions, a backslash (\\), -is different from the escape character for Windows PowerShell. The -escape character for Windows PowerShell is the backtick character (`) (ASCII 96). +Notice that the escape character for regular expressions, a backslash (\\), is +different from the escape character for Windows PowerShell. The escape +character for Windows PowerShell is the backtick character (`) (ASCII 96). For more information, see [Regular Expression Language - Quick Reference](https://go.microsoft.com/fwlink/?LinkId=133231). diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md index 9106db823dd..d7a4d220a0c 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,34 +14,31 @@ Explains how to disconnect from and reconnect to a PSSession ## Long Description -Beginning in Windows PowerShell 3.0, you can disconnect from -a PSSession and reconnect to the PSSession at a later time on -the same computer or a different computer. The session state -is maintained and commands in the PSSession continue to -run while the session is disconnected. +Beginning in Windows PowerShell 3.0, you can disconnect from a PSSession and +reconnect to the PSSession at a later time on the same computer or a different +computer. The session state is maintained and commands in the PSSession +continue to run while the session is disconnected. -The Disconnected Sessions feature is available only when the -computer at the remote end of a connection is running Windows -PowerShell 3.0 or a later version of Windows PowerShell. +The Disconnected Sessions feature is available only when the computer at the +remote end of a connection is running Windows PowerShell 3.0 or a later +version of Windows PowerShell. -The Disconnected Sessions feature allows you to close the session -in which a PSSession was created, and even close Windows PowerShell, -and shut down the computer, without disrupting commands running -in the PSSession. It is especially useful for running commands that -take an extended time to complete, and it provides the time and -device flexibility that IT professionals require. +The Disconnected Sessions feature allows you to close the session in which a +PSSession was created, and even close Windows PowerShell, and shut down the +computer, without disrupting commands running in the PSSession. It is +especially useful for running commands that take an extended time to complete, +and it provides the time and device flexibility that IT professionals require. -NOTE: You cannot disconnect from an interactive session that -is started by using the `Enter-PSSession` cmdlet. +NOTE: You cannot disconnect from an interactive session that is started by +using the `Enter-PSSession` cmdlet. -You can use Disconnected Sessions to manage PSSessions that -were disconnected unintentionally as the result of a computer -or network outage. +You can use Disconnected Sessions to manage PSSessions that were disconnected +unintentionally as the result of a computer or network outage. -In real-world use, the Disconnected Sessions feature allows -you to begin solving a problem, turn your attention to a higher -priority issue, and then resume work on the solution, even on a -different computer in a different location. +In real-world use, the Disconnected Sessions feature allows you to begin +solving a problem, turn your attention to a higher priority issue, and then +resume work on the solution, even on a different computer in a different +location. ## Disconnected Session Cmdlets @@ -50,82 +47,77 @@ The following cmdlets support the Disconnected Sessions feature: * `Connect-PSSession`: Connects to a disconnected PSSession * `Disconnect-PSSession`: Disconnects a PSSession * `Get-PSSession`: Gets PSSessions on the local computer or on remote computers -* `Receive-PSSession`: Gets the results of commands that ran in disconnected sessions -* `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and disconnects immediately +* `Receive-PSSession`: Gets the results of commands that ran in disconnected + sessions +* `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and + disconnects immediately ## How the Disconnected Sessions Feature Works -Beginning in Windows PowerShell 3.0, PSSessions are independent -of the sessions in which they are created. Active PSSession are -maintained on the remote computer or "server side" of the -connection, even if the session in which PSSession was -created is closed and the originating computer is shut down -or disconnected from the network. - -In Windows PowerShell 2.0, the PSSession is deleted from the -remote computer when it is disconnected from the originating -session or the session in which it was created ends. - -When you disconnect a PSSession, the PSSession remains active -and is maintained on the remote computer. The session state -changes from Running to Disconnected. You can reconnect to a -disconnected PSSession from the current session or from a different -session on the same computer, or from a different computer. The -remote computer that maintains the session must be running and +Beginning in Windows PowerShell 3.0, PSSessions are independent of the +sessions in which they are created. Active PSSession are maintained on the +remote computer or "server side" of the connection, even if the session in +which PSSession was created is closed and the originating computer is shut +down or disconnected from the network. + +In Windows PowerShell 2.0, the PSSession is deleted from the remote computer +when it is disconnected from the originating session or the session in which +it was created ends. + +When you disconnect a PSSession, the PSSession remains active and is +maintained on the remote computer. The session state changes from Running to +Disconnected. You can reconnect to a disconnected PSSession from the current +session or from a different session on the same computer, or from a different +computer. The remote computer that maintains the session must be running and be connected to the network. -Commands in a disconnected PSSession continue to run -uninterrupted on the remote computer until the command -completes or the output buffer fills. To prevent a full -output buffer from suspending a command, use the +Commands in a disconnected PSSession continue to run uninterrupted on the +remote computer until the command completes or the output buffer fills. To +prevent a full output buffer from suspending a command, use the **OutputBufferingMode** parameter of the `Disconnect-PSSession`, `New-PSSessionOption`, or `New-PSTransportOption` cmdlets. -Disconnected sessions are maintained in the disconnected -state on the remote computer. They are available for you to -reconnect, until you delete the PSSession, such as by using -the `Remove-PSSession` cmdlet, or until the idle timeout of the -PSSession expires. You can adjust the idle timeout of a PSSession -by using the **IdleTimeoutSec** or **IdleTimeout** parameters of the +Disconnected sessions are maintained in the disconnected state on the remote +computer. They are available for you to reconnect, until you delete the +PSSession, such as by using the `Remove-PSSession` cmdlet, or until the idle +timeout of the PSSession expires. You can adjust the idle timeout of a +PSSession by using the **IdleTimeoutSec** or **IdleTimeout** parameters of the `Disconnect-PSSession`, `New-PSSessionOption`, or `New-PSTransportOption` cmdlets. -Another user can connect to PSSessions that you created, -but only if they can supply the credentials that were used -to create the session, or use the RunAs credentials of -the session configuration. +Another user can connect to PSSessions that you created, but only if they can +supply the credentials that were used to create the session, or use the RunAs +credentials of the session configuration. ## How to Get PSSessions Beginning in Windows PowerShell 3.0, the `Get-PSSession` cmdlet gets -PSSessions on the local computer and remote computers. It can also -get PSSessions that were created in the current session. +PSSessions on the local computer and remote computers. It can also get +PSSessions that were created in the current session. To get PSsessions on the local computer or remote computers, use the **ComputerName** or **ConnectionUri** parameters. Without parameters, `Get-PSSession` gets PSSession that were created in the local session, regardless of where they terminate. -When getting PSSessions, remember to look for them on the computer -on which they are maintained, that is, the remote or "server-side" -computer. +When getting PSSessions, remember to look for them on the computer on which +they are maintained, that is, the remote or "server-side" computer. -For example, if you create a PSSession to the Server01 computer, -get the session from the Server01 computer. If you create a PSSession -from another computer to the local computer, get the session from -the local computer. +For example, if you create a PSSession to the Server01 computer, get the +session from the Server01 computer. If you create a PSSession from another +computer to the local computer, get the session from the local computer. The following command sequence shows how `Get-PSSession` works. -The first command creates a session to the Server01 computer. The -session resides on the Server01 computer. +The first command creates a session to the Server01 computer. The session +resides on the Server01 computer. ```powershell PS C:\> New-PSSession -ComputerName Server01 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` To get the session, use the **ComputerName** parameter of `Get-PSSession` @@ -134,15 +126,15 @@ with a value of Server01. ```powershell PS C:\> Get-PSSession -ComputerName Server01 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` If the value of the **ComputerName** parameter of `Get-PSSession` is localhost, `Get-PSSession` gets PSSessions that terminate at and are -maintained on the local computer. It does not get PSSessions on the -Server01 computer, even if they were started on the local computer. +maintained on the local computer. It does not get PSSessions on the Server01 +computer, even if they were started on the local computer. ```powershell PS C:\> Get-PSSession -ComputerName localhost @@ -156,16 +148,16 @@ that was created in the current session and connects to the Server01 computer. ```powershell PS C:\> Get-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` ## How to Disconnect Sessions -To disconnect a PSSession use the `Disconnect-PSSession` cmdlet. To -identify the PSSession, use the **Session** parameter, or pipe a PSSession -from the `New-PSSession` or `Get-PSSession` cmdlets to `Disconnect-PSSession`. +To disconnect a PSSession use the `Disconnect-PSSession` cmdlet. To identify +the PSSession, use the **Session** parameter, or pipe a PSSession from the +`New-PSSession` or `Get-PSSession` cmdlets to `Disconnect-PSSession`. The following command disconnects the PSSession to the Server01 computer. Notice that the value of the State property is Disconnected and the @@ -174,94 +166,96 @@ Availability is None. ```powershell PS C:\> Get-PSSession -ComputerName Server01 | Disconnect-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Disconnected Microsoft.PowerShell None ``` To create a disconnected session, use the **InDisconnectedSession** parameter -of the `Invoke-Command` cmdlet. It creates a session, starts the command, -and disconnects immediately, before the command can return any output. +of the `Invoke-Command` cmdlet. It creates a session, starts the command, and +disconnects immediately, before the command can return any output. -The following command runs a `Get-WinEvent` command in a disconnected -session on the Server02 remote computer. +The following command runs a `Get-WinEvent` command in a disconnected session +on the Server02 remote computer. ```powershell PS C:\> Invoke-Command -ComputerName Server02 -InDisconnectedSession ` -ScriptBlock { Get-WinEvent -LogName "Windows PowerShell" } -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 4 Session3 Server02 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 4 Session3 Server02 Disconnected Microsoft.PowerShell None ``` ## How to Connect to Disconnected Sessions -You can connect to any available disconnected PSSession from the session -in which you created the PSSession or from other sessions on the local -computer or other computers. +You can connect to any available disconnected PSSession from the session in +which you created the PSSession or from other sessions on the local computer +or other computers. -You can create a PSSession, run commands in the PSSession, disconnect from -the PSSession, close Windows PowerShell, and shut down the computer. Hours -later, you can open a different computer, get the PSSession, connect to it, -and get the results of commands that ran in the PSSession while it was -disconnected. Then you can run more commands in the session. +You can create a PSSession, run commands in the PSSession, disconnect from the +PSSession, close Windows PowerShell, and shut down the computer. Hours later, +you can open a different computer, get the PSSession, connect to it, and get +the results of commands that ran in the PSSession while it was disconnected. +Then you can run more commands in the session. To connect a disconnected PSSession, use the `Connect-PSSession` cmdlet. Use -the **ComputerName** or **ConnectionUri** parameters to identify the PSSession, or -pipe a PSSession from `Get-PSSession` to `Connect-PSSession`. +the **ComputerName** or **ConnectionUri** parameters to identify the +PSSession, or pipe a PSSession from `Get-PSSession` to `Connect-PSSession`. -The following command gets the sessions on the Server02 computer. -The output includes two disconnected sessions, both of which are available. +The following command gets the sessions on the Server02 computer. The output +includes two disconnected sessions, both of which are available. ```powershell PS C:\> Get-PSSession -ComputerName Server02 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 juneb-srv8320 Disconnected Microsoft.PowerShell None - 4 Session3 juneb-srv8320 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 juneb-srv8320 Disconnected Microsoft.PowerShell None + 4 Session3 juneb-srv8320 Disconnected Microsoft.PowerShell None ``` -The following command connects to Session2. The PSSession is now open and available. +The following command connects to Session2. The PSSession is now open and +available. ```powershell PS C:\> Connect-PSSession -ComputerName Server02 -Name Session2 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 juneb-srv8320 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 juneb-srv8320 Opened Microsoft.PowerShell Available ``` ## How to Get the Results -To get the results of commands that ran in a disconnected PSSession, use -the `Receive-PSSession` cmdlet. +To get the results of commands that ran in a disconnected PSSession, use the +`Receive-PSSession` cmdlet. You can use `Receive-PSSession` in addition to, or instead of, using the `Connect-PSSession` cmdlet. If the session is already reconnected, -`Receive-PSSession` gets the results of commands that ran when the session -was disconnected. If the PSSession is still disconnected, `Receive-PSSession` +`Receive-PSSession` gets the results of commands that ran when the session was +disconnected. If the PSSession is still disconnected, `Receive-PSSession` connects to it and then gets the results of commands that ran while it was disconnected. -`Receive-PSSession` can return the results in a job (asynchronously) or to -the host program (synchronously). Use the **OutTarget** parameter to select Job -or Host. Host is the default value. However, if the command that is being +`Receive-PSSession` can return the results in a job (asynchronously) or to the +host program (synchronously). Use the **OutTarget** parameter to select Job or +Host. Host is the default value. However, if the command that is being received was started in the current session as a job, it is returned as a job by default. -The following command uses the `Receive-PSSession` cmdlet to connect to the PSSession -on the Server02 computer and get the results of the `Get-WinEvent` command that -ran in the Session3 session. The command uses the **OutTarget** parameter to get the -results in a job. +The following command uses the `Receive-PSSession` cmdlet to connect to the +PSSession on the Server02 computer and get the results of the `Get-WinEvent` +command that ran in the Session3 session. The command uses the **OutTarget** +parameter to get the results in a job. ```powershell -PS C:\> Receive-PSSession -ComputerName Server02 -Name Session3 -OutTarget Job +PS C:\> Receive-PSSession -ComputerName Server02 -Name Session3 ` + -OutTarget Job -Id Name PSJobTypeName State HasMoreData Location --- ---- ------------- ----- ----------- -------- - 3 Job3 RemoteJob Running True Server02 +Id Name PSJobTypeName State HasMoreData Location +-- ---- ------------- ----- ----------- -------- + 3 Job3 RemoteJob Running True Server02 ``` To get the results of the job, use the `Receive-Job` cmdlet. @@ -281,141 +275,135 @@ TimeCreated Id LevelDisplayName Message PSComputerName ## State and Availability -The State and Availability properties of a disconnected PSSession -tell you whether the session is available for you to reconnect to it. +The State and Availability properties of a disconnected PSSession tell you +whether the session is available for you to reconnect to it. -When a PSSession is connected to the current session, its state is -Opened and its availability is Available. When you disconnect from -the PSSession, the PSSession state is Disconnected and its Availability -is none. +When a PSSession is connected to the current session, its state is Opened and +its availability is Available. When you disconnect from the PSSession, the +PSSession state is Disconnected and its Availability is none. -However, 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. However, it does not mean -that the PSSession is disconnected from all sessions. It might be -connected to a different session. +However, 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. 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, -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. +To determine whether you can connect or reconnect to the PSSession, 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. -The following example is run in two sessions (Windows PowerShell -console windows) on the same computer. Note the changing values of the -State and Availability properties in each session as the PSSession is -disconnected and reconnected. +The following example is run in two sessions (Windows PowerShell console +windows) on the same computer. Note the changing values of the State and +Availability properties in each session as the PSSession is disconnected and +reconnected. ```powershell # Session 1 PS C:\> New-PSSession -ComputerName Server30 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Opened Microsoft.PowerShell Available # Session 2 PS C:\> Get-PSSession -ComputerName Server30 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell Busy +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell Busy # Session 1 -PS C:\> Get-PSSession -ComputerName Server30 -Name Test | Disconnect-PSSession +PS C:\> Get-PSSession -ComputerName Server30 -Name Test | +>> Disconnect-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell None # Session 2 PS C:\> Get-PSSession -ComputerName Server30 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell None # Session 2 PS C:\> Connect-PSSession -ComputerName Server01 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -3 Test Server30 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +3 Test Server30 Opened Microsoft.PowerShell Available # Session 1 PS C:\> Get-PSSession -ComputerName Server30 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell Busy +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell Busy # IDLE TIMEOUT ``` -Disconnected sessions are maintained on the remote computer until -you delete them, such as by using the `Remove-PSSession` cmdlet, or -they time out. The IdleTimeout property of a PSSession determines -how long a disconnected session is maintained before it is deleted. +Disconnected sessions are maintained on the remote computer until you delete +them, such as by using the `Remove-PSSession` cmdlet, or they time out. The +IdleTimeout property of a PSSession determines how long a disconnected session +is maintained before it is deleted. PSSessions are idle when the "heartbeat thread" receives no response. -Disconnecting a session makes it idle and starts the Idle Timeout -clock, even if commands are still running in the disconnected session. -Windows PowerShell considers disconnected sessions to be active, but -idle. - -When creating and disconnecting sessions, verify that the idle -timeout in the PSSession is long enough to maintain the session -for your needs, but not so long that it consumes unnecessary -resources on the remote computer. - -The IdleTimeoutMs property of the session configuration -determines the default idle timeout of sessions that use the -session configuration. You can override the default value, but -the value that you use cannot exceed the MaxIdleTimeoutMs -property of the session configuration. - -To find the value of the IdleTimeoutMs and MaxIdleTimeoutMs -values of a session configuration, use the following command -format. +Disconnecting a session makes it idle and starts the Idle Timeout clock, even +if commands are still running in the disconnected session. Windows PowerShell +considers disconnected sessions to be active, but idle. + +When creating and disconnecting sessions, verify that the idle timeout in the +PSSession is long enough to maintain the session for your needs, but not so +long that it consumes unnecessary resources on the remote computer. + +The IdleTimeoutMs property of the session configuration determines the default +idle timeout of sessions that use the session configuration. You can override +the default value, but the value that you use cannot exceed the +MaxIdleTimeoutMs property of the session configuration. + +To find the value of the IdleTimeoutMs and MaxIdleTimeoutMs values of a +session configuration, use the following command format. ```powershell -Get-PSSessionConfiguration | Format-Table Name, IdleTimeoutMs, MaxIdleTimeoutMs +Get-PSSessionConfiguration | + Format-Table Name, IdleTimeoutMs, MaxIdleTimeoutMs ``` -You can override the default value in the session configuration and -set the idle timeout of a PSSession when you create a PSSession and -when you disconnect. +You can override the default value in the session configuration and set the +idle timeout of a PSSession when you create a PSSession and when you +disconnect. -If you are a member of the Administrators group on the remote computer, -you can also create and change the IdleTimeoutMs and MaxIdleTimeoutMs -properties of session configurations. +If you are a member of the Administrators group on the remote computer, you +can also create and change the IdleTimeoutMs and MaxIdleTimeoutMs properties +of session configurations. ## NOTES: -The idle timeout value of session configurations and session -options is in milliseconds. The idle timeout value of sessions -and session configuration options is in seconds. +The idle timeout value of session configurations and session options is in +milliseconds. The idle timeout value of sessions and session configuration +options is in seconds. -You can set the idle timeout of a PSSession when you create the -PSSession (`New-PSSession`, `Invoke-Command`) and when you disconnect -from it (`Disconnect-PSSession`). However, you cannot change the -IdleTimeout value when you connect to the PSSession -(`Connect-PSSession`) or get results (`Receive-PSSession`). +You can set the idle timeout of a PSSession when you create the PSSession +(`New-PSSession`, `Invoke-Command`) and when you disconnect from it +(`Disconnect-PSSession`). However, you cannot change the IdleTimeout value +when you connect to the PSSession (`Connect-PSSession`) or get results +(`Receive-PSSession`). The `Connect-PSSession` and `Receive-PSSession` cmdlets have a -**SessionOption** parameter that takes a SessionOption object, -such as one returned by the `New-PSSessionOption` cmdlet. However, -the IdleTimeout value in SessionOption object and the IdleTimeout -value in the $PSSessionOption preference variable do not change -the value of the IdleTimeout of the PSSession in a `Connect-PSSession` -or `Receive-PSSession` command. +**SessionOption** parameter that takes a SessionOption object, such as one +returned by the `New-PSSessionOption` cmdlet. However, the IdleTimeout value +in SessionOption object and the IdleTimeout value in the $PSSessionOption +preference variable do not change the value of the IdleTimeout of the +PSSession in a `Connect-PSSession` or `Receive-PSSession` command. * To create a PSSession with a particular idle timeout value, create a $PSSessionOption preference variable. Set the value of the IdleTimeout property to the desired value (in milliseconds). - When you create PSSessions, the values in $PSSessionOption variable - take precedence over the values in the session configuration. + When you create PSSessions, the values in $PSSessionOption variable take + precedence over the values in the session configuration. For example, this command sets an idle timeout of 48 hours. @@ -477,38 +465,35 @@ Set-PSSessionConfiguration -Name Test -TransportOption $o ## Output Buffering Mode -The output buffering mode of a PSSession determines how command -output is managed when the output buffer of the PSSession is full. +The output buffering mode of a PSSession determines how command output is +managed when the output buffer of the PSSession is full. -In a disconnected session, the output buffering mode effectively -determines whether the command continues to run while the session -is disconnected. +In a disconnected session, the output buffering mode effectively determines +whether the command continues to run while the session is disconnected. Valid values: * Block - When the output buffer is full, execution is suspended - until the buffer is clear. + When the output buffer is full, execution is suspended until the buffer is + clear. * Drop - When the output buffer is full, execution continues. - As new output is generated, the oldest output is discarded. + When the output buffer is full, execution continues. As new output is + generated, the oldest output is discarded. -Block, the default value, preserves data, but might interrupt -the command. +Block, the default value, preserves data, but might interrupt the command. -A value of Drop allows the command to complete, although data might -be lost. When using the Drop value, redirect the command output to -a file on disk. This value is recommended for disconnected sessions. +A value of Drop allows the command to complete, although data might be lost. +When using the Drop value, redirect the command output to a file on disk. This +value is recommended for disconnected sessions. -The OutputBufferingMode property of the session configuration -determines the default output buffering mode of sessions that -use the session configuration. +The OutputBufferingMode property of the session configuration determines the +default output buffering mode of sessions that use the session configuration. -To find the value of the OutputBufferingMode of a session -configuration, use the following command formats. +To find the value of the OutputBufferingMode of a session configuration, use +the following command formats. ```powershell (Get-PSSessionConfiguration ).OutputBufferingMode @@ -520,12 +505,12 @@ or Get-PSSessionConfiguration | Format-Table Name, OutputBufferingMode ``` -You can override the default value in the session configuration and set -the output buffering mode of a PSSession when you create a PSSession, -when you disconnect, and when you reconnect. +You can override the default value in the session configuration and set the +output buffering mode of a PSSession when you create a PSSession, when you +disconnect, and when you reconnect. -If you are a member of the Administrators group on the remote computer, -you can also create and change the output buffering mode of session +If you are a member of the Administrators group on the remote computer, you +can also create and change the output buffering mode of session configurations. * To create a PSSession with an output buffering mode of Drop, create @@ -609,63 +594,58 @@ Set-PSSessionConfiguration -Name Test -TransportOption $o ## Disconnecting Loopback Sessions -"Loopback sessions" or "local sessions" are PSSessions that -originate and terminate on the same computer. Like other -PSSessions, active loopback sessions are maintained on the -computer on the remote end of the connection (the local -computer), so you can disconnect from and reconnect to -loopback sessions. +"Loopback sessions" or "local sessions" are PSSessions that originate and +terminate on the same computer. Like other PSSessions, active loopback +sessions are maintained on the computer on the remote end of the connection +(the local computer), so you can disconnect from and reconnect to loopback +sessions. -By default, loopback sessions are created with a network security -token that does not permit commands run in the session to access -other computers. You can reconnect to loopback sessions that have a -network security token from any session on the local computer or a -remote computer. +By default, loopback sessions are created with a network security token that +does not permit commands run in the session to access other computers. You can +reconnect to loopback sessions that have a network security token from any +session on the local computer or a remote computer. However, if you use the **EnableNetworkAccess** parameter of the -`New-PSSession`, `Enter-PSSession`, or `Invoke-Command` cmdlet, the -loopback session is created with an interactive security token. -The interactive token enables commands that run in the loopback -session to get data from other computers. +`New-PSSession`, `Enter-PSSession`, or `Invoke-Command` cmdlet, the loopback +session is created with an interactive security token. The interactive token +enables commands that run in the loopback session to get data from other +computers. -You can disconnect loopback sessions with interactive tokens and -then reconnect to them from the same session or a different session -on the same computer. However, to prevent malicious access, you can -reconnect to loopback sessions with interactive tokens only from the -computer on which they were created. +You can disconnect loopback sessions with interactive tokens and then +reconnect to them from the same session or a different session on the same +computer. However, to prevent malicious access, you can reconnect to loopback +sessions with interactive tokens only from the computer on which they were +created. ## Waiting for Jobs in Disconnected Sessions -The `Wait-Job` cmdlet waits until a job completes and then -returns to the command prompt or the next command. By default, -`Wait-Job` returns if the session in which a job is running is -disconnected. To direct the `Wait-Job` cmdlet to wait until the -session is reconnected (in the Opened state), use the **Force** -parameter. For more information, see [Wait-Job](../Wait-Job.md). +The `Wait-Job` cmdlet waits until a job completes and then returns to the +command prompt or the next command. By default, `Wait-Job` returns if the +session in which a job is running is disconnected. To direct the `Wait-Job` +cmdlet to wait until the session is reconnected (in the Opened state), use the +**Force** parameter. For more information, see [Wait-Job](../Wait-Job.md). ## Robust Sessions and Unintentional Disconnection -Occasionally, a PSSession might be disconnected unintentionally -due to a computer failure or network outage. Windows PowerShell -attempts to recover the PSSession, but its success depends upon -the severity and duration of the cause. - -The state of an unintentionally disconnected PSSession might -be Broken or Closed, but it might also be Disconnected. If -the value of State is Disconnected, you can use the same -techniques to manage the PSSession as you would if the -session were disconnected intentionally. For example, you -can use the `Connect-PSSession` cmdlet to reconnect to the session -and the `Receive-PSSession` cmdlet to get results of commands that -ran while the session was disconnected. - -If you close (exit) the session in which a PSSession was -created while commands are running in the PSSession, Windows -PowerShell maintains the PSSession in the Disconnected state -on the remote computer. If you close (exit) the session in -which a PSSession was created, but no commands are running -in the PSSession, Windows PowerShell does not attempt to -maintain the PSSession. +Occasionally, a PSSession might be disconnected unintentionally due to a +computer failure or network outage. Windows PowerShell attempts to recover the +PSSession, but its success depends upon the severity and duration of the +cause. + +The state of an unintentionally disconnected PSSession might be Broken or +Closed, but it might also be Disconnected. If the value of State is +Disconnected, you can use the same techniques to manage the PSSession as you +would if the session were disconnected intentionally. For example, you can use +the `Connect-PSSession` cmdlet to reconnect to the session and the +`Receive-PSSession` cmdlet to get results of commands that ran while the +session was disconnected. + +If you close (exit) the session in which a PSSession was created while +commands are running in the PSSession, Windows PowerShell maintains the +PSSession in the Disconnected state on the remote computer. If you close +(exit) the session in which a PSSession was created, but no commands are +running in the PSSession, Windows PowerShell does not attempt to maintain the +PSSession. ## See Also diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md index da39d788c10..93fb4c492c5 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,344 +7,512 @@ title: about_Remote_FAQ --- # About Remote FAQ -## about_Remote_FAQ - ## SHORT DESCRIPTION -Contains questions and answers about running remote commands in Windows PowerShell? +Contains questions and answers about running remote commands in Windows +PowerShell. ## LONG DESCRIPTION -When you work remotely, you type commands in Windows PowerShell on one computer (known as the "local computer"), but the commands run on another computer (known as the "remote computer"). The experience of working remotely should be as much like working directly at the remote computer as possible. - - -``` -Note: To use Windows PowerShell remoting, the remote computer - must be configured for remoting. For more information, see - about_Remote_Requirements. -``` +When you work remotely, you type commands in Windows PowerShell on one +computer (known as the "local computer"), but the commands run on another +computer (known as the "remote computer"). The experience of working remotely +should be as much like working directly at the remote computer as possible. +Note: To use Windows PowerShell remoting, the remote computer must be +configured for remoting. For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). ### MUST BOTH COMPUTERS HAVE WINDOWS POWERSHELL INSTALLED? -Yes. To work remotely, the local and remote computers must have Windows PowerShell, the Microsoft .NET Framework, and the Web Services for Management (WS-Management) protocol. Any files and other resources that are needed to execute a particular command must be on the remote computer. -Computers running Windows PowerShell 3.0 and computers running Windows PowerShell 2.0 can connect to each other remotely and run remote commands. However, some features, such as the ability to disconnect from a session and reconnect to it, work only when both computers are running Windows PowerShell 3.0. +Yes. To work remotely, the local and remote computers must have Windows +PowerShell, the Microsoft .NET Framework, and the Web Services for Management +(WS-Management) protocol. Any files and other resources that are needed to +execute a particular command must be on the remote computer. -You must have permission to connect to the remote computer, permission to run Windows PowerShell, and permission to access data stores (such as files and folders), and the registry on the remote computer. +Computers running Windows PowerShell 3.0 and computers running Windows +PowerShell 2.0 can connect to each other remotely and run remote commands. +However, some features, such as the ability to disconnect from a session and +reconnect to it, work only when both computers are running Windows PowerShell +3.0. -For more information, see about_Remote_Requirements. +You must have permission to connect to the remote computer, permission to run +Windows PowerShell, and permission to access data stores (such as files and +folders), and the registry on the remote computer. +For more information, see [about_Remote_Requirements](about_Remote_Requirements.md). ### HOW DOES REMOTING WORK? -When you submit a remote command, the command is transmitted across the network to the Windows PowerShell engine on the remote computer, and it runs in the Windows PowerShell client on the remote computer. The command results are sent back to the local computer and appear in the Windows PowerShell session on the local computer. -To transmit the commands and receive the output, Windows PowerShell uses the WS-Management protocol. For information about the WS-Management protocol, see "WS-Management Protocol" in the MSDN (Microsoft Developer Network) library at http:\/\/go.microsoft.com\/fwlink\/?LinkId\=144634. +When you submit a remote command, the command is transmitted across the +network to the Windows PowerShell engine on the remote computer, and it runs +in the Windows PowerShell client on the remote computer. The command results +are sent back to the local computer and appear in the Windows PowerShell +session on the local computer. -Beginning in Windows PowerShell 3.0, remote sessions are stored on the remote computer. This enables you to disconnect from the session and reconnect from a different session or a different computer without interrupting the commands or losing state. +To transmit the commands and receive the output, Windows PowerShell uses the +WS-Management protocol. For information about the WS-Management protocol, see +[WS-Management Protocol](http://go.microsoft.com\/fwlink/?LinkId=144634) in +the MSDN library. +Beginning in Windows PowerShell 3.0, remote sessions are stored on the remote +computer. This enables you to disconnect from the session and reconnect from a +different session or a different computer without interrupting the commands or +losing state. ### IS WINDOWS POWERSHELL REMOTING SECURE? -When you connect to a remote computer, the system uses the user name and password credentials on the local computer or the credentials that you supply in the command to log you in to the remote computer. The credentials and the rest of the transmission are encrypted. -To add additional protection, you can configure the remote computer to use Secure Sockets Layer (SSL) instead of HTTP to listen for Windows Remote Management (WinRM) requests. Then, users can use the UseSSL parameters of the Invoke-Command, New-PSSession, and Enter-PSSession cmdlets when establishing a connection. This option uses the more secure HTTPS channel instead of HTTP. +When you connect to a remote computer, the system uses the user name and +password credentials on the local computer or the credentials that you supply +in the command to log you in to the remote computer. The credentials and the +rest of the transmission are encrypted. +To add additional protection, you can configure the remote computer to use +Secure Sockets Layer (SSL) instead of HTTP to listen for Windows Remote +Management (WinRM) requests. Then, users can use the UseSSL parameters of the +Invoke-Command, New-PSSession, and Enter-PSSession cmdlets when establishing a +connection. This option uses the more secure HTTPS channel instead of HTTP. ### DO ALL REMOTE COMMANDS REQUIRE WINDOWS POWERSHELL REMOTING? -No. Several cmdlets have a ComputerName parameter that lets you get objects from the remote computer. - -These cmdlets do not use Windows PowerShell remoting. So, you can use them on any computer that is running Windows PowerShell, even if the computer is not configured for Windows PowerShell remoting or if the computer does not meet the requirements for Windows PowerShell remoting. -These cmdlets include the following cmdlets: +No. Several cmdlets have a ComputerName parameter that lets you get objects +from the remote computer. +These cmdlets do not use Windows PowerShell remoting. So, you can use them on +any computer that is running Windows PowerShell, even if the computer is not +configured for Windows PowerShell remoting or if the computer does not meet +the requirements for Windows PowerShell remoting. -``` -Get-Process -Get-Service -Get-WinEvent -Get-EventLog -Get-WmiObject -Test-Connection -``` +These cmdlets include the following: +- Get-Process +- Get-Service +- Get-WinEvent +- Get-EventLog +- Get-WmiObject +- Test-Connection To find all the cmdlets with a ComputerName parameter, type: - -``` -Get-Help * -Parameter ComputerName -or +```powershell +Get-Help * -Parameter ComputerName +# or Get-Command -ParameterName ComputerName ``` +To determine whether the ComputerName parameter of a particular cmdlet +requires Windows PowerShell remoting, see the parameter description. To +display the parameter description, type: -To determine whether the ComputerName parameter of a particular cmdlet requires Windows PowerShell remoting, see the parameter description. To display the parameter description, type: - - -``` +```ppowershell Get-Help -Parameter ComputerName ``` - For example: - -``` +```powershell Get-Help Get-Process -Parameter Computername ``` - For all other commands, use the Invoke-Command cmdlet. - ### HOW DO I RUN A COMMAND ON A REMOTE COMPUTER? + To run a command on a remote computer, use the Invoke-Command cmdlet. -Enclose your command in braces ( {} ) to make it a script block. Use the ScriptBlock parameter of Invoke-Command to specify the command. +Enclose your command in braces ( {} ) to make it a script block. Use the +ScriptBlock parameter of Invoke-Command to specify the command. -You can use the ComputerName parameter of Invoke-Command to specify a remote computer. Or, you can create a persistent connection to a remote computer (a session) and then use the Session parameter of Invoke-Command to run the command in the session. +You can use the ComputerName parameter of Invoke-Command to specify a remote +computer. Or, you can create a persistent connection to a remote computer (a +session) and then use the Session parameter of Invoke-Command to run the +command in the session. For example, the following commands run a Get-Process command remotely. +```powershell +Invoke-Command -ComputerName Server01, Server02 -ScriptBlock {Get-Process} + +# - OR - -``` -Invoke-Command -ComputerName Server01, Server02 -ScriptBlock {Get-Process} - - - OR - - Invoke-Command -Session $s -ScriptBlock {Get-Process} ``` +To interrupt a remote command, type CTRL\+C. The interruption request is +passed to the remote computer, where it terminates the remote command. -To interrupt a remote command, type CTRL\+C. The interruption request is passed to the remote computer, where it terminates the remote command. - -For more information about remote commands, see about_Remote and the Help topics for the cmdlets that support remoting. - +For more information about remote commands, see about_Remote and the Help +topics for the cmdlets that support remoting. ### CAN I JUST "TELNET INTO" A REMOTE COMPUTER? -You can use the Enter-PSSession cmdlet to start an interactive session with a remote computer. -At the Windows PowerShell prompt, type: +You can use the Enter-PSSession cmdlet to start an interactive session with a +remote computer. +At the Windows PowerShell prompt, type: -``` +```powershell Enter-PSSession ``` - -The command prompt changes to show that you are connected to the remote computer. - +The command prompt changes to show that you are connected to the remote +computer. ``` \C:> ``` - -Now, the commands that you type run on the remote computer just as though you typed them directly on the remote computer. +Now, the commands that you type run on the remote computer just as though you +typed them directly on the remote computer. To end the interactive session, type: - -``` +```powershell Exit-PSSession ``` - -An interactive session is a persistent session that uses the WS-Management protocol. It is not the same as using Telnet, but it provides a similar experience. +An interactive session is a persistent session that uses the WS-Management +protocol. It is not the same as using Telnet, but it provides a similar +experience. For more information, see Enter-PSSession. - ### CAN I CREATE A PERSISTENT CONNECTION? -Yes. You can run remote commands by specifying the name of the remote computer, its NetBIOS name, or its IP address. Or, you can run remote commands by specifying a Windows PowerShell session (PSSession) that is connected to the remote computer. -When you use the ComputerName parameter of Invoke-Command or Enter-PSSession, Windows PowerShell establishes a temporary connection. Windows PowerShell uses the connection to run only the current command, and then it closes the connection. This is a very efficient method for running a single command or several unrelated commands, even on many remote computers. +Yes. You can run remote commands by specifying the name of the remote +computer, its NetBIOS name, or its IP address. Or, you can run remote commands +by specifying a Windows PowerShell session (PSSession) that is connected to +the remote computer. -When you use the New-PSSession cmdlet to create a PSSession, Windows PowerShell establishes a persistent connection for the PSSession. Then, you can run multiple commands in the PSSession, including commands that share data. +When you use the ComputerName parameter of Invoke-Command or Enter-PSSession, +Windows PowerShell establishes a temporary connection. Windows PowerShell uses +the connection to run only the current command, and then it closes the +connection. This is a very efficient method for running a single command or +several unrelated commands, even on many remote computers. -Typically, you create a PSSession to run a series of related commands that share data. Otherwise, the temporary connection created by the ComputerName parameter is sufficient for most commands. +When you use the New-PSSession cmdlet to create a PSSession, Windows +PowerShell establishes a persistent connection for the PSSession. Then, you +can run multiple commands in the PSSession, including commands that share +data. -For more information about sessions, see about_PSSessions. +Typically, you create a PSSession to run a series of related commands that +share data. Otherwise, the temporary connection created by the ComputerName +parameter is sufficient for most commands. +For more information about sessions, see about_PSSessions. ### CAN I RUN COMMANDS ON MORE THAN ONE COMPUTER AT A TIME? -Yes. The ComputerName parameter of the Invoke-Command cmdlet accepts multiple computer names, and the Session parameter accepts multiple PSSessions. -When you run an Invoke-Command command, Windows PowerShell runs the commands on all of the specified computers or in all of the specified PSSessions. +Yes. The ComputerName parameter of the Invoke-Command cmdlet accepts multiple +computer names, and the Session parameter accepts multiple PSSessions. -Windows PowerShell can manage hundreds of concurrent remote connections. However, the number of remote commands that you can send might be limited by the resources of your computer and its capacity to establish and maintain multiple network connections. +When you run an Invoke-Command command, Windows PowerShell runs the commands +on all of the specified computers or in all of the specified PSSessions. -For more information, see the example in the Invoke-Command Help topic. +Windows PowerShell can manage hundreds of concurrent remote connections. +However, the number of remote commands that you can send might be limited by +the resources of your computer and its capacity to establish and maintain +multiple network connections. +For more information, see the example in the Invoke-Command Help topic. ### WHERE ARE MY PROFILES? -Windows PowerShell profiles are not run automatically in remote sessions, so the commands that the profile adds are not present in the session. In addition, the $profile automatic variable is not populated in remote sessions. -To run a profile in a session, use the Invoke-Command cmdlet. +Windows PowerShell profiles are not run automatically in remote sessions, so +the commands that the profile adds are not present in the session. In +addition, the \$profile automatic variable is not populated in remote sessions. -For example, the following command runs the CurrentUserCurrentHost profile from the local computer in the session in $s. +To run a profile in a session, use the `Invoke-Command` cmdlet. +For example, the following command runs the CurrentUserCurrentHost profile +from the local computer in the session in \$s. ``` Invoke-Command -Session $s -FilePath $profile ``` +The following command runs the CurrentUserCurrentHost profile from the remote +computer in the session in $s. Because the $profile variable is not populated, +the command uses the explicit path to the profile. -The following command runs the CurrentUserCurrentHost profile from the remote computer in the session in $s. Because the $profile variable is not populated, the command uses the explicit path to the profile. - - -``` -Invoke-Command -Session $s {. "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1"} +```powershell +Invoke-Command -Session $s { + . "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1" +} ``` +After running this command, the commands that the profile adds to the session +are available in $s. -After running this command, the commands that the profile adds to the session are available in $s. - -You can also use a startup script in a session configuration to run a profile in every remote session that uses the session configuration. - -For more information about Windows PowerShell profiles, see about_Profiles. For more information about session configurations, see Register-PSSessionConfiguration. +You can also use a startup script in a session configuration to run a profile +in every remote session that uses the session configuration. +For more information about Windows PowerShell profiles, see about_Profiles. +For more information about session configurations, see +Register-PSSessionConfiguration. ### HOW DOES THROTTLING WORK ON REMOTE COMMANDS? -To help you manage the resources on your local computer, Windows PowerShell includes a per-command throttling feature that lets you limit the number of concurrent remote connections that are established for each command. -The default is 32 concurrent connections, but you can use the ThrottleLimit parameters of the cmdlets to set a custom throttle limit for particular commands. +To help you manage the resources on your local computer, Windows PowerShell +includes a per-command throttling feature that lets you limit the number of +concurrent remote connections that are established for each command. -When you use the throttling feature, remember that it is applied to each command, not to the entire session or to the computer. If you are running commands concurrently in several sessions or PSSessions, the number of concurrent connections is the sum of the concurrent connections in all the sessions. +The default is 32 concurrent connections, but you can use the **ThrottleLimit** +parameters of the cmdlets to set a custom throttle limit for particular +commands. -To find cmdlets with a ThrottleLimit parameter, type: +When you use the throttling feature, remember that it is applied to each +command, not to the entire session or to the computer. If you are running +commands concurrently in several sessions or PSSessions, the number of +concurrent connections is the sum of the concurrent connections in all the +sessions. +To find cmdlets with a ThrottleLimit parameter, type: ``` -Get-Help * -Parameter ThrottleLimit --or- +Get-Help * -Parameter ThrottleLimit +-or- Get-Command -ParameterName ThrottleLimit ``` - ### IS THE OUTPUT OF REMOTE COMMANDS DIFFERENT FROM LOCAL OUTPUT? -When you use Windows PowerShell locally, you send and receive "live" .NET Framework objects; "live" objects are objects that are associated with actual programs or system components. When you invoke the methods or change the properties of live objects, the changes affect the actual program or component. And, when the properties of a program or component change, the properties of the object that represent them also change. -However, because most live objects cannot be transmitted over the network, Windows PowerShell "serializes" most of the objects sent in remote commands, that is, it converts each object into a series of XML (Constraint Language in XML [CLiXML]) data elements for transmission. +When you use Windows PowerShell locally, you send and receive "live" .NET +Framework objects; "live" objects are objects that are associated with actual +programs or system components. When you invoke the methods or change the +properties of live objects, the changes affect the actual program or +component. And, when the properties of a program or component change, the +properties of the object that represent them also change. -When Windows PowerShell receives a serialized object, it converts the XML into a deserialized object type. The deserialized object is an accurate record of the properties of the program or component at a previous time, but it is no longer "live", that is, it is no longer directly associated with the component. And, the methods are removed because they are no longer effective. +However, because most live objects cannot be transmitted over the network, +Windows PowerShell "serializes" most of the objects sent in remote commands, +that is, it converts each object into a series of XML (Constraint Language in +XML [CLiXML]) data elements for transmission. -Typically, you can use deserialized objects just as you would use live objects, but you must be aware of their limitations. Also, the objects that are returned by the Invoke-Command cmdlet have additional properties that help you to determine the origin of the command. +When Windows PowerShell receives a serialized object, it converts the XML into +a deserialized object type. The deserialized object is an accurate record of +the properties of the program or component at a previous time, but it is no +longer "live", that is, it is no longer directly associated with the +component. And, the methods are removed because they are no longer effective. -Some object types, such as DirectoryInfo objects and GUIDs, are converted back into live objects when they are received. These objects do not need any special handling or formatting. +Typically, you can use deserialized objects just as you would use live +objects, but you must be aware of their limitations. Also, the objects that +are returned by the Invoke-Command cmdlet have additional properties that help +you to determine the origin of the command. -For information about interpreting and formatting remote output, see about_Remote_Output. +Some object types, such as DirectoryInfo objects and GUIDs, are converted back +into live objects when they are received. These objects do not need any +special handling or formatting. +For information about interpreting and formatting remote output, see +[about_Remote_Output](about_Remote_Output.md). ### CAN I RUN BACKGROUND JOBS REMOTELY? -Yes. A Windows PowerShell background job is a Windows PowerShell command that runs asynchronously without interacting with the session. When you start a background job, the command prompt returns immediately, and you can continue to work in the session while the job runs even if it runs for an extended period of time. -You can start a background job even while other commands are running because background jobs always run asynchronously in a temporary session. +Yes. A Windows PowerShell background job is a Windows PowerShell command that +runs asynchronously without interacting with the session. When you start a +background job, the command prompt returns immediately, and you can continue +to work in the session while the job runs even if it runs for an extended +period of time. -You can run background jobs on a local or remote computer. By default, a background job runs on the local computer. However, you can use the AsJob parameter of the Invoke-Command cmdlet to run any remote command as a background job. And, you can use Invoke-Command to run a Start-Job command remotely. +You can start a background job even while other commands are running because +background jobs always run asynchronously in a temporary session. -For more information about background jobs in Windows PowerShell , see about_Jobs and about_Remote_Jobs. +You can run background jobs on a local or remote computer. By default, a +background job runs on the local computer. However, you can use the AsJob +parameter of the Invoke-Command cmdlet to run any remote command as a +background job. And, you can use Invoke-Command to run a Start-Job command +remotely. +For more information about background jobs in Windows PowerShell , see +[about_Jobs(about_Jobs.md)] and [about_Remote_Jobs(about_Remote_Jobs.md)]. ### CAN I RUN WINDOWS PROGRAMS ON A REMOTE COMPUTER? -You can use Windows PowerShell remote commands to run Windows-based programs on remote computers. For example, you can run Shutdown.exe or Ipconfig on a remote computer. -However, you cannot use Windows PowerShell commands to open the user interface for any program on a remote computer. +You can use Windows PowerShell remote commands to run Windows-based programs +on remote computers. For example, you can run Shutdown.exe or Ipconfig on a +remote computer. -When you start a Windows program on a remote computer, the command is not completed, and the Windows PowerShell command prompt does not return, until the program is finished or until you press CTRL\+C to interrupt the command. For example, if you run the IpConfig program on a remote computer, the command prompt does not return until IpConfig is completed. +However, you cannot use Windows PowerShell commands to open the user interface +for any program on a remote computer. -If you use remote commands to start a program that has a user interface, the program process starts, but the user interface does not appear. The Windows PowerShell command is not completed, and the command prompt does not return until you stop the program process or until you press CTRL\+C, which interrupts the command and stops the process. +When you start a Windows program on a remote computer, the command is not +completed, and the Windows PowerShell command prompt does not return, until +the program is finished or until you press CTRL\+C to interrupt the command. +For example, if you run the IpConfig program on a remote computer, the command +prompt does not return until IpConfig is completed. -For example, if you use a Windows PowerShell command to run Notepad on a remote computer, the Notepad process starts on the remote computer, but the Notepad user interface does not appear. To interrupt the command and restore the command prompt, press CTRL\+C. +If you use remote commands to start a program that has a user interface, the +program process starts, but the user interface does not appear. The Windows +PowerShell command is not completed, and the command prompt does not return +until you stop the program process or until you press CTRL\+C, which +interrupts the command and stops the process. +For example, if you use a Windows PowerShell command to run Notepad on a +remote computer, the Notepad process starts on the remote computer, but the +Notepad user interface does not appear. To interrupt the command and restore +the command prompt, press CTRL\+C. ### CAN I LIMIT THE COMMANDS THAT USERS CAN RUN REMOTELY ON MY COMPUTER? -Yes. Every remote session must use one of the session configurations on the remote computer. You can manage the session configurations on your computer (and the permissions to those session configurations) to determine who can run commands remotely on your computer and which commands they can run. - -A session configuration configures the environment for the session. You can define the configuration by using an assembly that implements a new configuration class or by using a script that runs in the session. The configuration can determine the commands that are available in the session. And, the configuration can include settings that protect the computer, such as settings that limit the amount of data that the session can receive remotely in a single object or command. You can also specify a security descriptor that determines the permissions that are required to use the configuration. - -The Enable-PSRemoting cmdlet creates the default session configurations on your computer: Microsoft.PowerShell, Microsoft.PowerShell.Workflow, and Microsoft.PowerShell32 (64-bit operating systems only). Enable-PSRemoting sets the security descriptor for the configuration to allow only members of the Administrators group on your computer to use them. - -You can use the session configuration cmdlets to edit the default session configurations, to create new session configurations, and to change the security descriptors of all the session configurations. -Beginning in Windows PowerShell 3.0, the New-PSSessionConfigurationFile cmdlet lets you create custom session configurations by using a text file. The file includes options for setting the language mode and for specifying the cmdlets and modules that are available in sessions that use the session configuration. - -When users use the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets, they can use the ConfigurationName parameter to indicate the session configuration that is used for the session. And, they can change the default configuration that their sessions use by changing the value of the $PSSessionConfigurationName preference variable in the session. - -For more information about session configurations, see the Help for the session configuration cmdlets. To find the session configuration cmdlets, type: - - -``` +Yes. Every remote session must use one of the session configurations on the +remote computer. You can manage the session configurations on your computer +(and the permissions to those session configurations) to determine who can run +commands remotely on your computer and which commands they can run. + +A session configuration configures the environment for the session. You can +define the configuration by using an assembly that implements a new +configuration class or by using a script that runs in the session. The +configuration can determine the commands that are available in the session. +And, the configuration can include settings that protect the computer, such as +settings that limit the amount of data that the session can receive remotely +in a single object or command. You can also specify a security descriptor that +determines the permissions that are required to use the configuration. + +The Enable-PSRemoting cmdlet creates the default session configurations on +your computer: Microsoft.PowerShell, Microsoft.PowerShell.Workflow, and +Microsoft.PowerShell32 (64-bit operating systems only). Enable-PSRemoting sets +the security descriptor for the configuration to allow only members of the +Administrators group on your computer to use them. + +You can use the session configuration cmdlets to edit the default session +configurations, to create new session configurations, and to change the +security descriptors of all the session configurations. + +Beginning in Windows PowerShell 3.0, the New-PSSessionConfigurationFile cmdlet +lets you create custom session configurations by using a text file. The file +includes options for setting the language mode and for specifying the cmdlets +and modules that are available in sessions that use the session configuration. + +When users use the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets, +they can use the ConfigurationName parameter to indicate the session +configuration that is used for the session. And, they can change the default +configuration that their sessions use by changing the value of the +$PSSessionConfigurationName preference variable in the session. + +For more information about session configurations, see the Help for the +session configuration cmdlets. To find the session configuration cmdlets, +type: + +```powershell Get-Command *PSSessionConfiguration ``` - - ### WHAT ARE FAN-IN AND FAN OUT CONFIGURATIONS? -The most common Windows PowerShell remoting scenario involving multiple computers is the one-to-many configuration, in which one local computer (the administrator's computer) runs Windows PowerShell commands on numerous remote computers. This is known as the "fan-out" scenario. -However, in some enterprises, the configuration is many-to-one, where many client computers connect to a single remote computer that is running Windows PowerShell, such as a file server or a kiosk. This is known as the "fan-in" configuration. +The most common Windows PowerShell remoting scenario involving multiple +computers is the one-to-many configuration, in which one local computer (the +administrator's computer) runs Windows PowerShell commands on numerous remote +computers. This is known as the "fan-out" scenario. -Windows PowerShell remoting supports both fan-out and fan-in configurations. +However, in some enterprises, the configuration is many-to-one, where many +client computers connect to a single remote computer that is running Windows +PowerShell, such as a file server or a kiosk. This is known as the "fan-in" +configuration. -For the fan-out configuration, Windows PowerShell uses the Web Services for Management (WS-Management) protocol and the WinRM service that supports the Microsoft implementation of WS-Management. When a local computer connects to a remote computer, WS-Management establishes a connection and uses a plug-in for Windows PowerShell to start the Windows PowerShell host process (Wsmprovhost.exe) on the remote computer. The user can specify an alternate port, an alternate session configuration, and other features to customize the remote connection. +Windows PowerShell remoting supports both fan-out and fan-in configurations. -To support the "fan-in" configuration, Windows PowerShell uses Internet Information Services (IIS) to host WS-Management, to load the Windows PowerShell plug-in, and to start Windows PowerShell. In this scenario, instead of starting each Windows PowerShell session in a separate process, all Windows PowerShell sessions run in the same host process. +For the fan-out configuration, Windows PowerShell uses the Web Services for +Management (WS-Management) protocol and the WinRM service that supports the +Microsoft implementation of WS-Management. When a local computer connects to a +remote computer, WS-Management establishes a connection and uses a plug-in for +Windows PowerShell to start the Windows PowerShell host process +(Wsmprovhost.exe) on the remote computer. The user can specify an alternate +port, an alternate session configuration, and other features to customize the +remote connection. -IIS hosting and fan-in remote management is not supported in Windows XP or in Windows Server 2003. +To support the "fan-in" configuration, Windows PowerShell uses Internet +Information Services (IIS) to host WS-Management, to load the Windows +PowerShell plug-in, and to start Windows PowerShell. In this scenario, instead +of starting each Windows PowerShell session in a separate process, all Windows +PowerShell sessions run in the same host process. -In a fan-in configuration, the user can specify a connection URI and an HTTP endpoint, including the transport, computer name, port, and application name. IIS forwards all the requests with a specified application name to the application. The default is WS-Management, which can host Windows PowerShell. +IIS hosting and fan-in remote management is not supported in Windows XP or in +Windows Server 2003. -You can also specify an authentication mechanism and prohibit or allow redirection from HTTP and HTTPS endpoints. +In a fan-in configuration, the user can specify a connection URI and an HTTP +endpoint, including the transport, computer name, port, and application name. +IIS forwards all the requests with a specified application name to the +application. The default is WS-Management, which can host Windows PowerShell. +You can also specify an authentication mechanism and prohibit or allow +redirection from HTTP and HTTPS endpoints. ### CAN I TEST REMOTING ON A SINGLE COMPUTER \(NOT IN A DOMAIN\)? -Yes. Windows PowerShell remoting is available even when the local computer is not in a domain. You can use the remoting features to connect to sessions and to create sessions on the same computer. The features work the same as they do when you connect to a remote computer. -To run remote commands on a computer in a workgroup, change the following Windows settings on the computer. +Yes. Windows PowerShell remoting is available even when the local computer is +not in a domain. You can use the remoting features to connect to sessions and +to create sessions on the same computer. The features work the same as they do +when you connect to a remote computer. -Caution: These settings affect all users on the system and they can make the system more vulnerable to a malicious attack. Use caution when making these changes. +To run remote commands on a computer in a workgroup, change the following +Windows settings on the computer. --- Windows XP with SP2: +Caution: These settings affect all users on the system and they can make the +system more vulnerable to a malicious attack. Use caution when making these +changes. -Use Local Security Settings (Secpol.msc) to change the setting of the "Network Access: Sharing and security model for local accounts" policy in Security Settings\Local Policies\Security Options to "Classic". +- Windows XP with SP2: --- Windows Vista, Windows 7, Windows 8: + Use Local Security Settings (Secpol.msc) to change the setting of the + "Network Access: Sharing and security model for local accounts" policy in + Security Settings\Local Policies\Security Options to "Classic". -Create the following registry entry, and then set its value to 1: LocalAccountTokenFilterPolicy in HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System +- Windows Vista, Windows 7, Windows 8: -You can use the following Windows PowerShell command to add this entry: + Create the following registry entry, and then set its value to 1: + LocalAccountTokenFilterPolicy in + HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System -New-ItemProperty ` -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System ` -Name LocalAccountTokenFilterPolicy -propertyType DWord -Value 1 + You can use the following Windows PowerShell command to add this entry: --- Windows Server 2003, Windows Server 2008, Windows Server 2012, Windows Server 2012 R2: + ```powershell + $parameters = @{ + Path='HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System' + Name='LocalAccountTokenFilterPolicy' + propertyType='DWord' + Value=1 + } + New-ItemProperty @parameters + ``` -No changes are needed because the default setting of the "Network Access: Sharing and security model for local accounts" policy is "Classic". Verify the setting in case it has changed. +- Windows Server 2003, Windows Server 2008, Windows Server 2012, Windows + Server 2012 R2: + No changes are needed because the default setting of the "Network Access: + Sharing and security model for local accounts" policy is "Classic". Verify + the setting in case it has changed. ### CAN I RUN REMOTE COMMANDS ON A COMPUTER IN ANOTHER DOMAIN? -Yes. Typically, the commands run without error, although you might need to use the Credential parameter of the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets to provide the credentials of a member of the Administrators group on the remote computer. This is sometimes required even when the current user is a member of the Administrators group on the local and remote computers. -However, if the remote computer is not in a domain that the local computer trusts, the remote computer might not be able to authenticate the user's credentials. +Yes. Typically, the commands run without error, although you might need to use +the **Credential** parameter of the `Invoke-Command`, `New-PSSession`, or +`Enter-PSSession` cmdlets to provide the credentials of a member of the +Administrators group on the remote computer. This is sometimes required even +when the current user is a member of the Administrators group on the local and +remote computers. -To enable authentication, use the following command to add the remote computer to the list of trusted hosts for the local computer in WinRM. Type the command at the Windows PowerShell prompt. +However, if the remote computer is not in a domain that the local computer +trusts, the remote computer might not be able to authenticate the user's +credentials. +To enable authentication, use the following command to add the remote computer +to the list of trusted hosts for the local computer in WinRM. Type the command +at the Windows PowerShell prompt. -``` +```powershell Set-Item WSMan:\localhost\Client\TrustedHosts -Value ``` +For example, to add the Server01 computer to the list of trusted hosts on the +local computer, type the following command at the Windows PowerShell prompt: -For example, to add the Server01 computer to the list of trusted hosts on the local computer, type the following command at the Windows PowerShell prompt: - - -``` +```powershell Set-Item WSMan:\localhost\Client\TrustedHosts -Value Server01 ``` - - ## SEE ALSO [about_Remote](about_Remote.md) @@ -357,7 +525,7 @@ Set-Item WSMan:\localhost\Client\TrustedHosts -Value Server01 [about_Remote_Variables](about_Remote_Variables.md) -Invoke-Command +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[New-PSSession](../New-PSSession.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md index d388c378a9a..91f9354775f 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,272 +7,338 @@ title: about_Remote_Jobs --- # About Remote Jobs -## about_Remote_Jobs - ## SHORT DESCRIPTION -Describes how to run background jobs on remote computers. +Describes how to run background jobs on remote computers. ## DETAILED DESCRIPTION -A background job is a command that runs asynchronously without interacting with the current session. The command prompt returns immediately, and you can continue to use the session while the job runs. -By default, background jobs run on the local computer. However, you can use several different procedures to run background jobs on remote computers. +A background job is a command that runs asynchronously without interacting +with the current session. The command prompt returns immediately, and you can +continue to use the session while the job runs. -This topic explains how to run a background job on a remote computer. For information about how to run background jobs on a local computer, see about_Jobs. For more information about background jobs, see about_Job_Details. +By default, background jobs run on the local computer. However, you can use +several different procedures to run background jobs on remote computers. +This topic explains how to run a background job on a remote computer. For +information about how to run background jobs on a local computer, see +[about_Jobs](about_Jobs.md). For more information about background jobs, see +[about_Job_Details](about_Job_Details.md). ## REMOTE BACKGROUND JOBS -You can run background jobs on remote computers by using three different methods. --- Start an interactive session with a remote computer, and start a job in the interactive session. The procedures are the same as running a local job, although all actions are performed on the remote computer. +You can run background jobs on remote computers by using three different +methods. --- Run a background job on a remote computer that returns its results to the local computer. Use this method when you want to collect the results of background jobs and maintain them in a central location on the local computer. +- Start an interactive session with a remote computer, and start a job in the + interactive session. The procedures are the same as running a local job, + although all actions are performed on the remote computer. --- Run a background job on a remote computer that maintains its results on the remote computer. Use this method when the job data is more securely maintained on the originating computer. +- Run a background job on a remote computer that returns its results to the + local computer. Use this method when you want to collect the results of + background jobs and maintain them in a central location on the local computer. +- Run a background job on a remote computer that maintains its results on the + remote computer. Use this method when the job data is more securely maintained + on the originating computer. ### START A BACKGROUND JOB IN AN INTERACTIVE SESSION -You can start an interactive session with a remote computer and then start a background job during the interactive session. For more information about interactive sessions, see about_Remote, and see Enter-PSSession. -The procedure for starting a background job in an interactive session is almost identical to the procedure for starting a background job on the local computer. However, all of the operations occur on the remote computer, not the local computer. +You can start an interactive session with a remote computer and then start a +background job during the interactive session. For more information about +interactive sessions, see about_Remote, and see Enter-PSSession. +The procedure for starting a background job in an interactive session is +almost identical to the procedure for starting a background job on the local +computer. However, all of the operations occur on the remote computer, not the +local computer. #### STEP 1: ENTER-PSSESSION -Use the Enter-PSSession cmdlet to start an interactive session with a remote computer. You can use the ComputerName parameter of Enter-PSSession to establish a temporary connection for the interactive session. Or, you can use the Session parameter to run the interactive session in a Windows PowerShell?session (PSSession). -The following command starts an interactive session on the Server01 computer. +Use the Enter-PSSession cmdlet to start an interactive session with a remote +computer. You can use the ComputerName parameter of Enter-PSSession to +establish a temporary connection for the interactive session. Or, you can use +the Session parameter to run the interactive session in a Windows PowerShell +session (PSSession). +The following command starts an interactive session on the Server01 computer. -``` +```powershell C:\PS> Enter-PSSession -computername Server01 ``` - -The command prompt changes to show that you are now connected to the Server01 computer. - +The command prompt changes to show that you are now connected to the Server01 +computer. ``` Server01\C:> ``` - - #### STEP 2: START-JOB -To start a background job in the session, use the Start-Job cmdlet. -The following command runs a background job that gets the events in the Windows PowerShell event log on the Server01 computer. The Start-Job cmdlet returns an object that represents the job. +To start a background job in the session, use the Start-Job cmdlet. -This command saves the job object in the $job variable. +The following command runs a background job that gets the events in the +Windows PowerShell event log on the Server01 computer. The Start-Job cmdlet +returns an object that represents the job. +This command saves the job object in the \$job variable. -``` -Server01\C:> $job = start-job -scriptblock {get-eventlog "Windows PowerShell"} +```powershell +Server01\C:> $job = start-job -scriptblock { + get-eventlog "Windows PowerShell" +} ``` - -While the job runs, you can use the interactive session to run other commands, including other background jobs. However, you must keep the interactive session open until the job is completed. If you end the session, the job is interrupted, and the results are lost. - +While the job runs, you can use the interactive session to run other commands, +including other background jobs. However, you must keep the interactive +session open until the job is completed. If you end the session, the job is +interrupted, and the results are lost. #### STEP 3: GET-JOB -To find out if the job is complete, display the value of the $job variable, or use the Get-Job cmdlet to get the job. The following command uses the Get-Job cmdlet to display the job. +To find out if the job is complete, display the value of the \$job variable, +or use the Get-Job cmdlet to get the job. The following command uses the +Get-Job cmdlet to display the job. -``` -Server01\C:> get-job $job - -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Complete True localhost get-eventlog "Windows PowerShell" -``` - +```powershell +Server01\C:> get-job $job -The Get-Job output shows that job is running on the "localhost" computer because the job was started on and is running on the same computer (in this case, Server01). +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Complete True localhost get-eventlog "Windows... +``` +The Get-Job output shows that job is running on the "localhost" computer +because the job was started on and is running on the same computer (in this +case, Server01). #### STEP 4: RECEIVE-JOB -To get the results of the job, use the Receive-Job cmdlet. You can display the results in the interactive session or save them to a file on the remote computer. The following command gets the results of the job in the $job variable. The command uses the redirection operator (>) to save the results of the job in the PsLog.txt file on the Server01 computer. +To get the results of the job, use the Receive-Job cmdlet. You can display the +results in the interactive session or save them to a file on the remote +computer. The following command gets the results of the job in the $job +variable. The command uses the redirection operator (>) to save the results of +the job in the PsLog.txt file on the Server01 computer. -``` +```powershell Server01\C:> receive-job $job > c:\logs\PsLog.txt ``` - - #### STEP 5: EXIT-PSSESSION -To end the interactive session, use the Exit-PSSession cmdlet. The command prompt changes to show that you are back in the original session on the local computer. +To end the interactive session, use the Exit-PSSession cmdlet. The command +prompt changes to show that you are back in the original session on the local +computer. -``` -Server01\C:> Exit-PSSession +```powershell +Server01\C:> Exit-PSSession C:\PS> ``` - - #### STEP 6: INVOKE-COMMAND: GET-CONTENT -To view the contents of the PsLog.txt file on the Server01 computer at any time, start another interactive session, or run a remote command. This type of command is best run in a PSSession (a persistent connection) in case you want to use several commands to investigate and manage the data in the PsLog.txt file. For more information about PSSessions, see about_PSSessions. -The following commands use the New-PSSession cmdlet to create a PSSession that is connected to the Server01 computer, and they use the Invoke-Command cmdlet to run a Get-Content command in the PSSession to view the contents of the file. +To view the contents of the PsLog.txt file on the Server01 computer at any +time, start another interactive session, or run a remote command. This type of +command is best run in a PSSession (a persistent connection) in case you want +to use several commands to investigate and manage the data in the PsLog.txt +file. For more information about PSSessions, see about_PSSessions. +The following commands use the New-PSSession cmdlet to create a PSSession that +is connected to the Server01 computer, and they use the Invoke-Command cmdlet +to run a Get-Content command in the PSSession to view the contents of the +file. +```powershell +$s = new-pssession -computername Server01 +invoke-command -session $s -scriptblock { + get-content c:\logs\pslog.txt} ``` -C:\PS> $s = new-pssession -computername Server01 -C:\PS> invoke-command -session $s -scriptblock {get-content c:\logs\pslog.txt} -``` - - ### START A REMOTE JOB THAT RETURNS THE RESULTS TO THE LOCAL COMPUTER \(ASJOB\) -To start a background job on a remote computer that returns the command results to the local computer, use the AsJob parameter of a cmdlet such as the Invoke-Command cmdlet. -When you use the AsJob parameter, the job object is actually created on the local computer even though the job runs on the remote computer. When the job is completed, the results are returned to the local computer. +To start a background job on a remote computer that returns the command +results to the local computer, use the AsJob parameter of a cmdlet such as the +Invoke-Command cmdlet. -You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage any job created by any cmdlet. Many of the cmdlets that have AsJob parameters do not use Windows PowerShell remoting, so you can use them even on computers that are not configured for remoting and that do not meet the requirements for remoting. +When you use the AsJob parameter, the job object is actually created on the +local computer even though the job runs on the remote computer. When the job +is completed, the results are returned to the local computer. +You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage +any job created by any cmdlet. Many of the cmdlets that have AsJob parameters +do not use Windows PowerShell remoting, so you can use them even on computers +that are not configured for remoting and that do not meet the requirements for +remoting. #### STEP 1: INVOKE-COMMAND -ASJOB -The following command uses the AsJob parameter of Invoke-Command to start a background job on the Server01 computer. The job runs a Get-Eventlog command that gets the events in the System log. You can use the JobName parameter to assign a display name to the job. +The following command uses the AsJob parameter of Invoke-Command to start a +background job on the Server01 computer. The job runs a Get-Eventlog command +that gets the events in the System log. You can use the JobName parameter to +assign a display name to the job. -``` -invoke-command -computername Server01 -scriptblock {get-eventlog system} -asjob +```powershell +invoke-command -computername Server01 -scriptblock { + get-eventlog system} -asjob ``` - The results of the command resemble the following sample output. - +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Running True Server01 get-eventlog system ``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Running True Server01 get-eventlog system -``` - -When the AsJob parameter is used, Invoke-Command returns the same type of job object that Start-Job returns. You can save the job object in a variable, or you can use a Get-Job command to get the job. - -Note that the value of the Location property shows that the job ran on the Server01 computer. +When the AsJob parameter is used, Invoke-Command returns the same type of job +object that Start-Job returns. You can save the job object in a variable, or +you can use a Get-Job command to get the job. +Note that the value of the Location property shows that the job ran on the +Server01 computer. #### STEP 2: GET-JOB -To manage a job started by using the AsJob parameter of the Invoke-Command cmdlet, use the Job cmdlets. Because the job object that represents the remote job is on the local computer, you do not need to run remote commands to manage the job. -To determine whether the job is complete, use a Get-Job command. The following command gets all of the jobs that were started in the current session. +To manage a job started by using the AsJob parameter of the Invoke-Command +cmdlet, use the Job cmdlets. Because the job object that represents the remote +job is on the local computer, you do not need to run remote commands to manage +the job. +To determine whether the job is complete, use a Get-Job command. The following +command gets all of the jobs that were started in the current session. -``` +```powershell get-job ``` +Because the remote job was started in the current session, a local Get-Job +command gets the job. The State property of the job object shows that the +command was completed successfully. -Because the remote job was started in the current session, a local Get-Job command gets the job. The State property of the job object shows that the command was completed successfully. - - -``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Completed True Server01 get-eventlog system +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Completed True Server01 get-eventlog system ``` - - #### STEP 3: RECEIVE-JOB -To get the results of the job, use the Receive-Job cmdlet. Because the job results are automatically returned to the computer where the job object resides, you can get the results with a local Receive-Job command. -The following command uses the Receive-Job cmdlet to get the results of the job. It uses the session ID to identify the job. This command saves the job results in the $results variable. You can also redirect the results to a file. +To get the results of the job, use the Receive-Job cmdlet. Because the job +results are automatically returned to the computer where the job object +resides, you can get the results with a local Receive-Job command. +The following command uses the Receive-Job cmdlet to get the results of the +job. It uses the session ID to identify the job. This command saves the job +results in the $results variable. You can also redirect the results to a file. -``` +```powershell $results = receive-job -id 1 ``` - - ### START A REMOTE JOB THAT KEEPS THE RESULTS ON THE REMOTE COMPUTER -To start a background job on a remote computer that keeps the command results on the remote computer, use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. You can use this method to run background jobs on multiple computers. -When you run a Start-Job command remotely, the job object is created on the remote computer, and the job results are maintained on the remote computer. From the perspective of the job, all operations are local. You are just running commands remotely to manage a local job on the remote computer. +To start a background job on a remote computer that keeps the command results +on the remote computer, use the Invoke-Command cmdlet to run a Start-Job +command on a remote computer. You can use this method to run background jobs +on multiple computers. +When you run a Start-Job command remotely, the job object is created on the +remote computer, and the job results are maintained on the remote computer. +From the perspective of the job, all operations are local. You are just +running commands remotely to manage a local job on the remote computer. #### STEP 1: INVOKE-COMMAND START-JOB -Use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. -This command requires a PSSession (a persistent connection). If you use the ComputerName parameter of Invoke-Command to establish a temporary connection, the Invoke-Command command is considered to be complete when the job object is returned. As a result, the temporary connection is closed, and the job is canceled. +Use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. -The following command uses the New-PSSession cmdlet to create a PSSession that is connected to the Server01 computer. The command saves the PSSession in the $s variable +This command requires a PSSession (a persistent connection). If you use the +ComputerName parameter of Invoke-Command to establish a temporary connection, +the Invoke-Command command is considered to be complete when the job object is +returned. As a result, the temporary connection is closed, and the job is +canceled. +The following command uses the New-PSSession cmdlet to create a PSSession that +is connected to the Server01 computer. The command saves the PSSession in the +\$s variable. -``` +```powershell $s = new-pssession -computername Server01 ``` +The next command uses the Invoke-Command cmdlet to run a Start-Job command in +the PSSession. The Start-Job command and the Get-Eventlog command are enclosed +in braces. -The next command uses the Invoke-Command cmdlet to run a Start-Job command in the PSSession. The Start-Job command and the Get-Eventlog command are enclosed in braces. - - +```powershell +invoke-command -session $s -scriptblock { + start-job -scriptblock {get-eventlog system}} ``` -invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog system}} -``` - The results resemble the following sample output. - -``` -Id Name State HasMoreData Location Command --- ---- ----- ----------- -------- ------- +```Output +Id Name State HasMoreData Location Command +-- ---- ----- ----------- -------- ------- 2 Job2 Running True Localhost get-eventlog system ``` +When you run a Start-Job command remotely, Invoke-Command returns the same +type of job object that Start-Job returns. You can save the job object in a +variable, or you can use a Get-Job command to get the job. -When you run a Start-Job command remotely, Invoke-Command returns the same type of job object that Start-Job returns. You can save the job object in a variable, or you can use a Get-Job command to get the job. - -Note that the value of the Location property shows that the job ran on the local computer, known as "LocalHost", even though the job ran on the Server01 computer. Because the job object is created on the Server01 computer and the job runs on the same computer, it is considered to be a local background job. - +Note that the value of the Location property shows that the job ran on the +local computer, known as "LocalHost", even though the job ran on the Server01 +computer. Because the job object is created on the Server01 computer and the +job runs on the same computer, it is considered to be a local background job. #### STEP 2: INVOKE-COMMAND GET-JOB -To manage a remote background job, use the Job cmdlets. Because the job object is on the remote computer, you need to run remote commands to get, stop, wait for, or retrieve the job results. -To see if the job is complete, use an Invoke-Command command to run a Get-Job command in the PSSession that is connected to the Server01 computer. +To manage a remote background job, use the Job cmdlets. Because the job object +is on the remote computer, you need to run remote commands to get, stop, wait +for, or retrieve the job results. +To see if the job is complete, use an Invoke-Command command to run a Get-Job +command in the PSSession that is connected to the Server01 computer. -``` +```powershell invoke-command -session $s -scriptblock {get-job} ``` +The command returns a job object. The State property of the job object shows +that the command was completed successfully. -The command returns a job object. The State property of the job object shows that the command was completed successfully. - - +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +2 Job2 Completed True LocalHost get-eventlog system ``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -2 Job2 Completed True LocalHost get-eventlog system -``` - - #### STEP 3: INVOKE-COMMAND RECEIVE-JOB -To get the results of the job, use the Invoke-Command cmdlet to run a Receive-Job command in the PSSession that is connected to the Server01 computer. -The following command uses the Receive-Job cmdlet to get the results of the job. It uses the session ID to identify the job. This command saves the job results in the $results variable. It uses the Keep parameter of Receive-Job to keep the result in the job cache on the remote computer. +To get the results of the job, use the Invoke-Command cmdlet to run a +Receive-Job command in the PSSession that is connected to the Server01 +computer. +The following command uses the Receive-Job cmdlet to get the results of the +job. It uses the session ID to identify the job. This command saves the job +results in the \$results variable. It uses the Keep parameter of Receive-Job +to keep the result in the job cache on the remote computer. +```powershell +$results = invoke-command -session $s -scriptblock { + receive-job -sessionid 2 -keep} ``` -$results = invoke-command -session $s -scriptblock {receive-job -sessionid 2 -keep} -``` - - -You can also redirect the results to a file on the local or remote computer. The following command uses a redirection operator to save the results in a file on the Server01 computer. +You can also redirect the results to a file on the local or remote computer. +The following command uses a redirection operator to save the results in a +file on the Server01 computer. +```powershell +invoke-command -session $s -command { + receive-job -sessionid 2 > c:\logs\pslog.txt} ``` -invoke-command -session $s -command {receive-job -sessionid 2 > c:\logs\pslog.txt} -``` - - ## SEE ALSO @@ -284,21 +350,20 @@ invoke-command -session $s -command {receive-job -sessionid 2 > c:\logs\pslog.tx [about_Remote_Variables](about_Remote_Variables.md) -Invoke-Command - -Start-Job +[Invoke-Command](../Invoke-Command.md) -Get-Job +[Start-Job](../Start-Job.md) -Wait-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Wait-Job](../Wait-Job.md) -Remove-Job +[Stop-Job](../Stop-Job.md) -New-PSSession +[Remove-Job](../Remove-Job.md) -Enter-PSSession +[New-PSSession](../New-PSSession.md) -Exit-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[Exit-PSSession](../Exit-PSSession.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Properties.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Properties.md index 2cdbdf69230..f9bea619992 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Properties.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Properties.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,278 +7,304 @@ title: about_Properties --- # About Properties -## about_Properties - ## SHORT DESCRIPTION -Describes how to use object properties in Windows PowerShell. +Describes how to use object properties in PowerShell. ## LONG DESCRIPTION -Windows PowerShell uses structured collections of information called objects to represent the items in data stores or the state of the computer. Typically, you work with object that are part of the Microsoft .NET Framework, but you can also create custom objects in Windows PowerShell. -The association between an item and its object is very close. When you change an object, you usually change the item that it represents. For example, when you get a file in Windows PowerShell, you do not get the actual file. Instead, you get a FileInfo object that represents the file. When you change the FileInfo object, the file changes too. +PowerShell uses structured collections of information called objects to +represent the items in data stores or the state of the computer. Typically, +you work with object that are part of the Microsoft .NET Framework, but you +can also create custom objects in PowerShell. -Most objects have properties. Properties are the data that is associated with an object. Different types of object have different properties. For example, a FileInfo object, which represents a file, has an IsReadOnly property that contains $True if the file the read-only attribute and $False if it does not. A DirectoryInfo object, which represents a file system directory, has a Parent property that contains the path to the parent directory. +The association between an item and its object is very close. When you change +an object, you usually change the item that it represents. For example, when +you get a file in PowerShell, you do not get the actual file. Instead, you get +a FileInfo object that represents the file. When you change the FileInfo +object, the file changes too. +Most objects have properties. Properties are the data that is associated with +an object. Different types of object have different properties. For example, a +FileInfo object, which represents a file, has an **IsReadOnly** property that +contains $True if the file the read-only attribute and $False if it does not. +A DirectoryInfo object, which represents a file system directory, has a Parent +property that contains the path to the parent directory. ### OBJECT PROPERTIES -To get the properties of an object, use the Get-Member cmdlet. For example, to get the properties of a FileInfo object, use the Get-ChildItem cmdlet to get the FileInfo object that represents a file. Then, use a pipeline operator (|) to send the FileInfo object to Get-Member. The following command gets the PowerShell.exe file and sends it to Get-Member. The $Pshome automatic variable contains the path of the Windows PowerShell installation directory. +To get the properties of an object, use the `Get-Member` cmdlet. For example, +to get the properties of a **FileInfo** object, use the `Get-ChildItem` cmdlet +to get the FileInfo object that represents a file. Then, use a pipeline +operator (|) to send the **FileInfo** object to `Get-Member`. The +following command gets the PowerShell.exe file and sends it to `Get-Member`. +The \$Pshome automatic variable contains the path of the PowerShell +installation directory. -``` +```powershell Get-ChildItem $pshome\PowerShell.exe | Get-Member ``` +The output of the command lists the members of the **FileInfo** object. +Members include both properties and methods. When you work in PowerShell, you +have access to all the members of the objects. -The output of the command lists the members of the FileInfo object. Members include both properties and methods. When you work in Windows PowerShell, you have access to all the members of the objects. - -To get only the properties of an object and not the methods, use the MemberType parameter of the Get-Member cmdlet with a value of "property", as shown in the following example. - +To get only the properties of an object and not the methods, use the +MemberType parameter of the `Get-Member` cmdlet with a value of "property", as +shown in the following example. -``` +```powershell Get-ChildItem $pshome\PowerShell.exe | Get-Member -MemberType property ``` - - -``` -TypeName: System.IO.FileInfo - -Name MemberType Definition ----- ---------- ---------- -Attributes Property System.IO.FileAttributes Attributes {get;set;} -CreationTime Property System.DateTime CreationTime {get;set;} -CreationTimeUtc Property System.DateTime CreationTimeUtc {get;set;} -Directory Property System.IO.DirectoryInfo Directory {get;} -DirectoryName Property System.String DirectoryName {get;} -Exists Property System.Boolean Exists {get;} -Extension Property System.String Extension {get;} -FullName Property System.String FullName {get;} -IsReadOnly Property System.Boolean IsReadOnly {get;set;} -LastAccessTime Property System.DateTime LastAccessTime {get;set;} -LastAccessTimeUtc Property System.DateTime LastAccessTimeUtc {get;set;} -LastWriteTime Property System.DateTime LastWriteTime {get;set;} -LastWriteTimeUtc Property System.DateTime LastWriteTimeUtc {get;set;} -Length Property System.Int64 Length {get;} +```Output +TypeName: System.IO.FileInfo + +Name MemberType Definition +---- ---------- ---------- +Attributes Property System.IO.FileAttributes Attributes {get;set;} +CreationTime Property System.DateTime CreationTime {get;set;} +CreationTimeUtc Property System.DateTime CreationTimeUtc {get;set;} +Directory Property System.IO.DirectoryInfo Directory {get;} +DirectoryName Property System.String DirectoryName {get;} +Exists Property System.Boolean Exists {get;} +Extension Property System.String Extension {get;} +FullName Property System.String FullName {get;} +IsReadOnly Property System.Boolean IsReadOnly {get;set;} +LastAccessTime Property System.DateTime LastAccessTime {get;set;} +LastAccessTimeUtc Property System.DateTime LastAccessTimeUtc {get;set;} +LastWriteTime Property System.DateTime LastWriteTime {get;set;} +LastWriteTimeUtc Property System.DateTime LastWriteTimeUtc {get;set;} +Length Property System.Int64 Length {get;} Name Property System.String Name {get;} ``` - -After you find the properties, you can use them in your Windows PowerShell commands. - +After you find the properties, you can use them in your PowerShell commands. ## PROPERTY VALUES -Although every object of a specific type has the same properties, the values of those properties describe the particular object. For example, every FileInfo object has a CreationTime property, but the value of that property differs for each file. - -The most common way to get the values of the properties of an object is to use the dot method. Type a reference to the object, such as a variable that contains the object, or a command that gets the object. Then, type a dot (.) followed by the property name. - -For example, the following command displays the value of the CreationTime property of the PowerShell.exe file. The Get-ChildItem command returns a FileInfo object that represents the PowerShell.exe file. The command is enclosed in parentheses to make sure that it is executed before any properties are accessed. The Get-ChildItem command is followed by a dot and the name of the CreationTime property, as follows: - -``` -C:\PS> (Get-ChildItem $pshome\PowerShell.exe).creationtime +Although every object of a specific type has the same properties, the values +of those properties describe the particular object. For example, every +FileInfo object has a CreationTime property, but the value of that property +differs for each file. + +The most common way to get the values of the properties of an object is to use +the dot method. Type a reference to the object, such as a variable that +contains the object, or a command that gets the object. Then, type a dot (.) +followed by the property name. + +For example, the following command displays the value of the CreationTime +property of the PowerShell.exe file. The `Get-ChildItem` command returns a +FileInfo object that represents the PowerShell.exe file. The command is +enclosed in parentheses to make sure that it is executed before any properties +are accessed. The `Get-ChildItem` command is followed by a dot and the name of +the CreationTime property, as follows: + +```powershell +C:\PS> (Get-ChildItem $pshome\PowerShell.exe).creationtime Tuesday, March 18, 2008 12:07:52 AM ``` +You can also save an object in a variable and then get its properties by using +the dot method, as shown in the following example: -You can also save an object in a variable and then get its properties by using the dot method, as shown in the following example: - - -``` -C:\PS> $a = Get-ChildItem $pshome\PowerShell.exe -C:\PS> $a.CreationTime +```powershell +C:\PS> $a = Get-ChildItem $pshome\PowerShell.exe +C:\PS> $a.CreationTime Tuesday, March 18, 2008 12:07:52 AM ``` +You can also use the `Select-Object` and `Format-List` cmdlets to display the +property values of an object. `Select-Object` and `Format-List` each have a +**Property** parameter. You can use the **Property** parameter to specify one +or more properties and their values. Or, you can use the wildcard character +(\*) to represent all the properties. -You can also use the Select-Object and Format-List cmdlets to display the property values of an object. Select-Object and Format-List each have a Property parameter. You can use the Property parameter to specify one or more properties and their values. Or, you can use the wildcard character (\*) to represent all the properties. - -For example, the following command displays the values of all the properties of the PowerShell.exe file. - +For example, the following command displays the values of all the properties +of the PowerShell.exe file. -``` +```powershell C:\PS> Get-ChildItem $pshome\PowerShell.exe | Format-List -property * ``` - - -``` -PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe -PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\system32\WindowsPowerShell\v1.0 -PSChildName : PowerShell.exe -PSDrive : C -PSProvider : Microsoft.PowerShell.Core\FileSystem -PSIsContainer : False -VersionInfo : File: C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe - InternalName: POWERSHELL - OriginalFilename: PowerShell.EXE.MUI - File Version: 6.1.6570.1 (fbl_srv_PowerShell(nigels).070711-0102) - FileDescription: PowerShell.EXE - Product: Microsoft® Windows® Operating System - ProductVersion: 6.1.6570.1 - Debug: False - Patched: False - PreRelease: False - PrivateBuild: True - SpecialBuild: False +```Output +PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\System3 + 2\WindowsPowerShell\v1.0\PowerShell.exe +PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\System3 + 2\WindowsPowerShell\v1.0 +PSChildName : PowerShell.exe +PSDrive : C +PSProvider : Microsoft.PowerShell.Core\FileSystem +PSIsContainer : False +Mode : -a---- +VersionInfo : File: C:\Windows\System32\WindowsPowerShell\ + v1.0\PowerShell.exe + InternalName: POWERSHELL + OriginalFilename: PowerShell.EXE.MUI + FileVersion: 10.0.16299.15 (WinBuild.160101.0800) + FileDescription: Windows PowerShell + Product: Microsoft® Windows® Operating System + ProductVersion: 10.0.16299.15 + Debug: False + Patched: False + PreRelease: False + PrivateBuild: False + SpecialBuild: False Language: English (United States) -``` - - -``` -BaseName : PowerShell -Mode : -a--- -Name : PowerShell.exe -Length : 160256 -DirectoryName : C:\Windows\system32\WindowsPowerShell\v1.0 -Directory : C:\Windows\system32\WindowsPowerShell\v1.0 -IsReadOnly : False -Exists : True -FullName : C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe -Extension : .exe -CreationTime : 3/18/2008 12:07:52 AM -CreationTimeUtc : 3/18/2008 7:07:52 AM -LastAccessTime : 3/19/2008 8:13:58 AM -LastAccessTimeUtc : 3/19/2008 3:13:58 PM -LastWriteTime : 3/18/2008 12:07:52 AM -LastWriteTimeUtc : 3/18/2008 7:07:52 AM +BaseName : PowerShell +Target : {C:\Windows\WinSxS\amd64_microsoft-windows-powershell-ex + e_31bf3856ad364e35_10.0.16299.15_none_8c022aa6735716ae\p + owershell.exe} +LinkType : HardLink +Name : PowerShell.exe +Length : 449024 +DirectoryName : C:\Windows\System32\WindowsPowerShell\v1.0 +Directory : C:\Windows\System32\WindowsPowerShell\v1.0 +IsReadOnly : False +Exists : True +FullName : C:\Windows\System32\WindowsPowerShell\v1.0\PowerShell.ex +Extension : .exe +CreationTime : 9/29/2017 6:43:19 AM +CreationTimeUtc : 9/29/2017 1:43:19 PM +LastAccessTime : 9/29/2017 6:43:19 AM +LastAccessTimeUtc : 9/29/2017 1:43:19 PM +LastWriteTime : 9/29/2017 6:43:19 AM +LastWriteTimeUtc : 9/29/2017 1:43:19 PM Attributes : Archive ``` - - ### STATIC PROPERTIES -You can use the static properties of .NET classes in Windows PowerShell. Static properties are properties of class, unlike standard properties, which are properties of an object. -To get the static properties of an class, use the Static parameter of the Get-Member cmdlet. +You can use the static properties of .NET classes in PowerShell. Static +properties are properties of class, unlike standard properties, which are +properties of an object. -For example, the following command gets the static properties of the System.DateTime class. +To get the static properties of an class, use the Static parameter of the +Get-Member cmdlet. +For example, the following command gets the static properties of the +`System.DateTime` class. -``` +```powershell Get-Date | Get-Member -MemberType Property -Static ``` +```Output +TypeName: System.DateTime - -``` -TypeName: System.DateTime - -Name MemberType Definition ----- ---------- ---------- -MaxValue Property static datetime MaxValue {get;} -MinValue Property static datetime MinValue {get;} -Now Property datetime Now {get;} -Today Property datetime Today {get;} +Name MemberType Definition +---- ---------- ---------- +MaxValue Property static datetime MaxValue {get;} +MinValue Property static datetime MinValue {get;} +Now Property datetime Now {get;} +Today Property datetime Today {get;} UtcNow Property datetime UtcNow {get;} ``` - To get the value of a static property, use the following syntax. - -``` +```powershell []:: ``` +For example, the following command gets the value of the UtcNow static +property of the `System.DateTime` class. -For example, the following command gets the value of the UtcNow static property of the System.DateTime class. - - -``` +```powershell [System.DateTime]::UtcNow ``` - - ### PROPERTIES OF SCALAR OBJECTS AND COLLECTIONS -The properties of one ("scalar") object of a particular type are often different from the properties of a collection of objects of the same type. -For example, every service has as DisplayName property, but a collection of services does not have a DisplayName property. Similarly, all collections have a Count property that tells how many objects are in the collection, but individual objects do not have a Count property. +The properties of one ("scalar") object of a particular type are often +different from the properties of a collection of objects of the same type. -Beginning in Windows PowerShell 3.0, Windows PowerShell tries to prevent scripting errors that result from the differing properties of scalar objects and collections. +For example, every service has as **DisplayName** property, but a collection +of services does not have a **DisplayName** property. Similarly, all +collections have a **Count** property that tells how many objects are in the +collection, but individual objects do not have a **Count** property. -If you submit a collection, but request a property that exists only on single ("scalar") objects, Windows PowerShell returns the value of that property for every object in the collection. +Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that +result from the differing properties of scalar objects and collections. -If you request the Count or Length property of zero objects or of one object, Windows PowerShell returns the correct value. +If you submit a collection, but request a property that exists only on single +("scalar") objects, PowerShell returns the value of that property for every +object in the collection. -If the property exists on the individual objects and on the collection, Windows PowerShell does not alter the result. +If you request the Count or Length property of zero objects or of one object, +PowerShell returns the correct value. -This feature also works on methods of scalar objects and collections. For more information, see about_Methods. +If the property exists on the individual objects and on the collection, +PowerShell does not alter the result. +This feature also works on methods of scalar objects and collections. For more +information, see about_Methods. ### EXAMPLES -For example, each service has a DisplayName property. The following command gets the value of the DisplayName property of the Audiosrv service. +For example, each service has a DisplayName property. The following command +gets the value of the DisplayName property of the Audiosrv service. -``` -PS C:\> (Get-Service Audiosrv).DisplayName +```powershell +PS C:\> (Get-Service Audiosrv).DisplayName Windows Audio ``` +However, a collection or array of services does not have a **DisplayName**. +The following command tries to get the DisplayName property of all services in +PowerShell 2.0. -However, a collection or array of services does not have a DisplayName. The following command tries to get the DisplayName property of all services in Windows PowerShell 2.0. - - -``` -PS C:\> (Get-Service).DisplayName +```powershell +PS C:\> (Get-Service).DisplayName PS C:\> ``` +Beginning in PowerShell 3.0, the same command returns the value of the +**DisplayName** property of every service that `Get-Service` returns. -Beginning in Windows PowerShell 3.0, the same command returns the value of the DisplayName property of every service that Get-Service returns. - - -``` -PS C:\> (Get-Service).DisplayName -Application Experience -Application Layer Gateway Service -Windows All-User Install Agent -Application Identity -Application Information +```powershell +PS C:\> (Get-Service).DisplayName +Application Experience +Application Layer Gateway Service +Windows All-User Install Agent +Application Identity +Application Information ... ``` +Conversely, a collection of two or more services has a **Count** property, +which contains the number of objects in the collection. -Conversely, a collection of two or more services has a Count property, which contains the number of objects in the collection. - - -``` -PS C:\> (Get-Service).Count +```powershell +PS C:\> (Get-Service).Count 176 ``` +Individual services do not have a Count or Length property, as shown in this +command in PowerShell 2.0. -Individual services do not have a Count or Length property, as shown in this command in Windows PowerShell 2.0. - - -``` -PS C:\> (Get-Service Audiosrv).Count +```powershell +PS C:\> (Get-Service Audiosrv).Count PS C:\> ``` +Beginning in PowerShell 3.0, the command returns the correct Count value. -Beginning in Windows PowerShell 3.0, the command returns the correct Count value. - - -``` -PS C:\> (Get-Service Audiosrv).Count +```powershell +PS C:\> (Get-Service Audiosrv).Count 1 ``` - - ## SEE ALSO [about_Methods](about_Methods.md) [about_Objects](about_Objects.md) -Get-Member - -Select-Object +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) -Format-List +[Select-Object](../../Microsoft.PowerShell.Utility/Select-Object.md) +[Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) \ No newline at end of file diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md index cd527f93dbd..21d289c7f6e 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -1,135 +1,145 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us -keywords: powershell,cmdlet +keywords: PowerShell,cmdlet title: about_Redirection --- # About Redirection -## about_Redirection - ## SHORT DESCRIPTION -Explains how to redirect output from Windows PowerShell to text files. +Explains how to redirect output from PowerShell to text files. ## LONG DESCRIPTION -By default, Windows PowerShell sends its command output to the Windows PowerShell console. However, you can direct the output to a text file, and you can redirect error output to the regular output stream. -You can use the following methods to redirect output: +By default, PowerShell sends its command output to the PowerShell console. +However, you can direct the output to a text file, and you can redirect error +output to the regular output stream. -- Use the Out-File cmdlet, which sends command output to a text file. Typically, you use the Out-File cmdlet when you need to use its parameters, such as the Encoding, Force, Width, or NoClobber parameters. +You can use the following methods to redirect output: -- Use the Tee-Object cmdlet, which sends command output to a text file and then sends it to the pipeline. +- Use the `Out-File` cmdlet, which sends command output to a text file. + Typically, you use the `Out-File` cmdlet when you need to use its parameters, + such as the **Encoding**, **Force**, **Width**, or **NoClobber** parameters. -- Use the Windows PowerShell redirection operators. +- Use the Tee-Object cmdlet, which sends command output to a text file and + then sends it to the pipeline. +- Use the PowerShell redirection operators. -### WINDOWS POWERSHELL REDIRECTION OPERATORS -The redirection operators enable you to send particular types of output to files and to the success output stream. +### POWERSHELL REDIRECTION OPERATORS -The Windows PowerShell redirection operators use the following characters to represent each output type: +The redirection operators enable you to send particular types of output to +files and to the success output stream. +The PowerShell redirection operators use the following characters to represent +each output type: ``` -* All output -1 Success output -2 Errors -3 Warning messages -4 Verbose output +* All output +1 Success output +2 Errors +3 Warning messages +4 Verbose output 5 Debug messages ``` +NOTE: The All (\*), Warning (3), Verbose (4) and Debug (5) redirection +operators were introduced in PowerShell 3.0. They do not work in earlier +versions of PowerShell. -NOTE: The All (\*), Warning (3), Verbose (4) and Debug (5) redirection operators were introduced in Windows PowerShell 3.0. They do not work in earlier versions of Windows PowerShell. +The PowerShell redirection operators are as follows. -The Windows PowerShell redirection operators are as follows. +``` +Operator Description Example +-------- ---------------------- ------------------------------ +> Sends output to the Get-Process > Process.txt + specified file. +>> Appends the output to dir *.ps1 >> Scripts.txt + the contents of the + specified file. -``` -Operator Description Example --------- ---------------------- ------------------------------ -> Sends output to the Get-Process > Process.txt - specified file. - ->> Appends the output to dir *.ps1 >> Scripts.txt - the contents of the - specified file. - -2> Sends errors to the Get-Process none 2> Errors.txt - specified file. - -2>> Appends errors to Get-Process none 2>> Save-Errors.txt - the contents of the - specified file. - -2>&1 Sends errors (2) and Get-Process none, Powershell 2>&1 - success output (1) - to the success - output stream. - -3> Sends warnings to the Write-Warning "Test!" 3> Warnings.txt - specified file. - -3>> Appends warnings to Write-Warning "Test!" 3>> Save-Warnings.txt - the contents of the - specified file. - -3>&1 Sends warnings (3) and function Test-Warning - success output (1) { Get-Process PowerShell; - to the success Write-Warning "Test!" } - output stream. Test-Warning 3>&1 - -4> Sends verbose output to Import-Module * -Verbose 4> Verbose.txt - the specified file. - -4>> Appends verbose output Import-Module * -Verbose 4>> Save-Verbose.txt - to the contents of the - specified file. - -4>&1 Sends verbose output (4) Import-Module * -Verbose 4>&1 - and success output (1) - to the success output - stream. - -5> Sends debug messages to Write-Debug "Starting" 5> Debug.txt - the specified file. - -5>> Appends debug messages Write-Debug "Saving" 5>> Save-Debug.txt - to the contents of the - specified file. - -5>&1 Sends debug messages (5) function Test-Debug - and success output (1) { Get-Process PowerShell - to the success output Write-Debug "PS" } - stream. Test-Debug 5>&1 - -*> Sends all output types function Test-Output - to the specified file. { Get-Process PowerShell, none - Write-Warning "Test!" -*>> Appends all output types Write-Verbose "Test Verbose" - to the contents of the Write-Debug "Test Debug" } - specified file. - Test-Output *> Test-Output.txt -*>&1 Sends all output types Test-Output *>> Test-Output.txt - (*) to the success output Test-Output *>&1 +2> Sends errors to the Get-Process none 2> Errors.txt + specified file. + +2>> Appends errors to Get-Process none 2>> Save-Errors.txt + the contents of the + specified file. + +2>&1 Sends errors (2) and Get-Process none, Powershell 2>&1 + success output (1) + to the success + output stream. + +3> Sends warnings to the Write-Warning "Test!" 3> Warnings.txt + specified file. + +3>> Appends warnings to Write-Warning "Test!" 3>> Warnings.txt + the contents of the + specified file. + +3>&1 Sends warnings (3) and function Test-Warning + success output (1) { Get-Process PowerShell; + to the success Write-Warning "Test!" } + output stream. Test-Warning 3>&1 + +4> Sends verbose output to Import-Module * -Verbose 4> Verbose.txt + the specified file. + +4>> Appends verbose output Import-Module * -Verbose 4>> Verbose.txt + to the contents of the + specified file. + +4>&1 Sends verbose output (4) Import-Module * -Verbose 4>&1 + and success output (1) + to the success output stream. -``` +5> Sends debug messages to Write-Debug "Starting" 5> Debug.txt + the specified file. + +5>> Appends debug messages Write-Debug "Saving" 5>> Debug.txt + to the contents of the + specified file. + +5>&1 Sends debug messages (5) function Test-Debug + and success output (1) { Get-Process PowerShell + to the success output Write-Debug "PS" } + stream. Test-Debug 5>&1 + +*> Sends all output types function Test-Output + to the specified file. { Get-Process PowerShell, none + Write-Warning "Test!" +*>> Appends all output types Write-Verbose "Test Verbose" + to the contents of the Write-Debug "Test Debug" } + specified file. + Test-Output *> Test-Output.txt +*>&1 Sends all output types Test-Output *>> Test-Output.txt + (*) to the success Test-Output *>&1 + output stream. +``` The syntax of the redirection operators is as follows: - ``` [\] ``` +If the specified file already exists, the redirection operators that do not +append data (> and n>) overwrite the current contents of the file without +warning. However, if the file is a read-only, hidden, or system file, the +redirection fails. The append redirection operators (>> and n>>) do not write +to a read-only file, but they append content to a system or hidden file. -If the specified file already exists, the redirection operators that do not append data (> and n>) overwrite the current contents of the file without warning. However, if the file is a read-only, hidden, or system file, the redirection fails. The append redirection operators (>> and n>>) do not write to a read-only file, but they append content to a system or hidden file. - -To force the redirection of content to a read-only, hidden, or system file, use the Out-File cmdlet with its Force parameter. When you are writing to files, the redirection operators use Unicode encoding. If the file has a different encoding, the output might not be formatted correctly. To redirect content to non-Unicode files, use the Out-File cmdlet with its Encoding parameter. - +To force the redirection of content to a read-only, hidden, or system file, +use the Out-File cmdlet with its Force parameter. When you are writing to +files, the redirection operators use Unicode encoding. If the file has a +different encoding, the output might not be formatted correctly. To redirect +content to non-Unicode files, use the Out-File cmdlet with its Encoding +parameter. ## SEE ALSO @@ -142,4 +152,3 @@ Tee-Object [about_Command_Syntax](about_Command_Syntax.md) [about_Path_Syntax](about_Path_Syntax.md) - diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 00bb519f161..9194ac278b4 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -16,50 +16,132 @@ Describes regular expressions in Windows PowerShell. Windows PowerShell supports the following regular expression characters. -| Format | Logic | Example | -| ------- | ----- | ------- | -| value | Matches exact characters anywhere in the original value. | "book" -match "oo" | -| . | Matches any single character. | "copy" -match "c..y" | -| [value] | Matches at least one of the characters in the brackets. | "big" -match "b[iou]g" | -| [range] | Matches at least one of the characters within the range. The use of a hyphen (-) allows you to specify an adjacent character. | "and" -match "[a-e]nd" | -| [^] | Matches any characters except those in brackets. | "and" -match "[^brt]nd" | -| ^ | Matches the beginning characters. | "book" -match "^bo" | -| $ | Matches the end characters. | "book" -match "ok$" | -| * | Matches any instances of the preceding character. | "baggy" -match "g*" | -| ? | Matches zero or one instance of the preceding character. | "baggy" -match "g?" | -| \ | Matches the character that follows as an escaped character. | "Try$" -match "Try\\$" | - -Windows PowerShell supports the character classes available in -Microsoft .NET Framework regular expressions. - -| Format | Logic | Example | -| -------- | ----- | ------- | -| \p{name} | Matches any character in the named character class specified by {name}. Supported names are Unicode groups and block ranges such as Ll, Nd, Z, IsGreek, and IsBoxDrawing. | "abcd defg" -match "\p{Ll}+" | -| \P{name} | Matches text not included in the groups and block ranges specified in {name}. | 1234 -match "\P{Ll}+" | -| \w | Matches any word character. Equivalent to the Unicode character categories [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. If ECMAScript-compliant behavior is specified with the ECMAScript option, \w is equivalent to [a-zA-Z_0-9]. | "abcd defg" -match "\w+" (this matches abcd) | -| \W | Matches any nonword character. Equivalent to the Unicode categories [^\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. | "abcd defg" -match "\W+" (this matches the space) | -| \s | Matches any white-space character. Equivalent to the Unicode character categories [\f\n\r\t\v\x85\p{Z}]. | "abcd defg" -match "\s+" | -| \S | Matches any non-white-space character. Equivalent to the Unicode character categories [^\f\n\r\t\v\x85\p{Z}]. | "abcd defg" -match "\S+" | -| \d | Matches any decimal digit. Equivalent to \p{Nd} for Unicode and [0-9] for non-Unicode behavior. | 12345 -match "\d+" | -| \D | Matches any nondigit. Equivalent to \P{Nd} for Unicode and [^0-9] for non-Unicode behavior. | "abcd" -match "\D+" | - +``` +Format value +Logic Matches exact characters anywhere in the original value. +Example "book" -match "oo" + +Format . +Logic Matches any single character. +Example "copy" -match "c..y" + +Format [value] +Logic Matches at least one of the characters in the brackets. +Example "big" -match "b[iou]g" + +Format [range] +Logic Matches at least one of the characters within the range. The use + of a hyphen (-) allows you to specify an adjacent character. +Example "and" -match "[a-e]nd" + +Format [^] +Logic Matches any characters except those in brackets. +Example "and" -match "[^brt]nd" + +Format ^ +Logic Matches the beginning characters. +Example "book" -match "^bo" + +Format $ +Logic Matches the end characters. +Example "book" -match "ok$" + +Format * +Logic Matches any instances of the preceding character. +Example "baggy" -match "g*" + +Format ? +Logic Matches zero or one instance of the preceding character. +Example "baggy" -match "g?" + +Format \ +Logic Matches the character that follows as an escaped character. +Example "Try$" -match "Try\\$" +``` + +Windows PowerShell supports the character classes available in Microsoft .NET +Framework regular expressions. + +``` +Format: \p{name} +Logic: Matches any character in the named character class specified by + {name}. Supported names are Unicode groups and block ranges such + as Ll, Nd, Z, IsGreek, and IsBoxDrawing. +Example: "abcd defg" -match "\p{Ll}+" + +Format: \P{name} +Logic: Matches text not included in the groups and block ranges specified + in {name}. +Example: 1234 -match "\P{Ll}+" + +Format: \w +Logic: Matches any word character. Equivalent to the Unicode character + categories [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. If ECMAScript- + compliant behavior is specified with the ECMAScript option, \w is + equivalent to [a-zA-Z_0-9]. +Example: "abcd defg" -match "\w+" (this matches abcd) + +Format: \W +Logic: Matches any nonword character. Equivalent to the Unicode categories + [^\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. +Example: "abcd defg" -match "\W+" (this matches the space) + +Format: \s +Logic: Matches any white-space character. Equivalent to the Unicode + character categories [\f\n\r\t\v\x85\p{Z}]. +Example: "abcd defg" -match "\s+" + +Format: \S +Logic: Matches any non-white-space character. Equivalent to the Unicode + character categories [^\f\n\r\t\v\x85\p{Z}]. +Example: "abcd defg" -match "\S+" + +Format: \d +Logic: Matches any decimal digit. Equivalent to \p{Nd} for Unicode and + [0-9] for non-Unicode behavior. +Example: 12345 -match "\d+" + +Format: \D +Logic: Matches any nondigit. Equivalent to \P{Nd} for Unicode and [^0-9] + for non-Unicode behavior. +Example: "abcd" -match "\D+" +``` Windows PowerShell supports the quantifiers available in .NET Framework regular expressions. The following are some examples of quantifiers. -| Format | Logic | Example | -| ------ | ----- | ------- | -| * | Specifies zero or more matches; for example, \wor (abc). Equivalent to {0,}. | "abc" -match "\w*" | -| + | Matches repeating instances of the preceding characters. | "xyxyxy" -match "xy+" | -| ? | Specifies zero or one matches; for example, \w? or (abc)?. Equivalent to {0,1}. | "abc" -match "\w?" | -| {n} | Specifies exactly n matches; for example, (pizza){2}. | "abc" -match "\w{2}" | -| {n,} | Specifies at least n matches; for example, (abc){2,}. | "abc" -match "\w{2,}" | -| {n,m} | Specifies at least n, but no more than m, matches. | "abc" -match "\w{2,3}" | +``` +Format: * +Logic Specifies zero or more matches; for example, \wor (abc). Equivalent + to {0,}. +Example: "abc" -match "\w*" + +Format: + +Logic: Matches repeating instances of the preceding characters. +Example: "xyxyxy" -match "xy+" + +Format: ? +Logic: Specifies zero or one matches; for example, \w? or (abc)?. + Equivalent to {0,1}. +Example: "abc" -match "\w?" + +Format: {n} +Logic: Specifies exactly n matches; for example, (pizza){2}. +Example: "abc" -match "\w{2}" + +Format: {n,} +Logic: Specifies at least n matches; for example, (abc){2,}. +Example: "abc" -match "\w{2,}" + +Format: {n,m} +Logic: Specifies at least n, but no more than m, matches. +Example: "abc" -match "\w{2,3}" +``` All the comparisons shown in the preceding table evaluate to true. -Notice that the escape character for regular expressions, a backslash (\\), -is different from the escape character for Windows PowerShell. The -escape character for Windows PowerShell is the backtick character (`) (ASCII 96). +Notice that the escape character for regular expressions, a backslash (\\), is +different from the escape character for Windows PowerShell. The escape +character for Windows PowerShell is the backtick character (`) (ASCII 96). For more information, see [Regular Expression Language - Quick Reference](https://go.microsoft.com/fwlink/?LinkId=133231). diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md index 9106db823dd..d7a4d220a0c 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,34 +14,31 @@ Explains how to disconnect from and reconnect to a PSSession ## Long Description -Beginning in Windows PowerShell 3.0, you can disconnect from -a PSSession and reconnect to the PSSession at a later time on -the same computer or a different computer. The session state -is maintained and commands in the PSSession continue to -run while the session is disconnected. +Beginning in Windows PowerShell 3.0, you can disconnect from a PSSession and +reconnect to the PSSession at a later time on the same computer or a different +computer. The session state is maintained and commands in the PSSession +continue to run while the session is disconnected. -The Disconnected Sessions feature is available only when the -computer at the remote end of a connection is running Windows -PowerShell 3.0 or a later version of Windows PowerShell. +The Disconnected Sessions feature is available only when the computer at the +remote end of a connection is running Windows PowerShell 3.0 or a later +version of Windows PowerShell. -The Disconnected Sessions feature allows you to close the session -in which a PSSession was created, and even close Windows PowerShell, -and shut down the computer, without disrupting commands running -in the PSSession. It is especially useful for running commands that -take an extended time to complete, and it provides the time and -device flexibility that IT professionals require. +The Disconnected Sessions feature allows you to close the session in which a +PSSession was created, and even close Windows PowerShell, and shut down the +computer, without disrupting commands running in the PSSession. It is +especially useful for running commands that take an extended time to complete, +and it provides the time and device flexibility that IT professionals require. -NOTE: You cannot disconnect from an interactive session that -is started by using the `Enter-PSSession` cmdlet. +NOTE: You cannot disconnect from an interactive session that is started by +using the `Enter-PSSession` cmdlet. -You can use Disconnected Sessions to manage PSSessions that -were disconnected unintentionally as the result of a computer -or network outage. +You can use Disconnected Sessions to manage PSSessions that were disconnected +unintentionally as the result of a computer or network outage. -In real-world use, the Disconnected Sessions feature allows -you to begin solving a problem, turn your attention to a higher -priority issue, and then resume work on the solution, even on a -different computer in a different location. +In real-world use, the Disconnected Sessions feature allows you to begin +solving a problem, turn your attention to a higher priority issue, and then +resume work on the solution, even on a different computer in a different +location. ## Disconnected Session Cmdlets @@ -50,82 +47,77 @@ The following cmdlets support the Disconnected Sessions feature: * `Connect-PSSession`: Connects to a disconnected PSSession * `Disconnect-PSSession`: Disconnects a PSSession * `Get-PSSession`: Gets PSSessions on the local computer or on remote computers -* `Receive-PSSession`: Gets the results of commands that ran in disconnected sessions -* `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and disconnects immediately +* `Receive-PSSession`: Gets the results of commands that ran in disconnected + sessions +* `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and + disconnects immediately ## How the Disconnected Sessions Feature Works -Beginning in Windows PowerShell 3.0, PSSessions are independent -of the sessions in which they are created. Active PSSession are -maintained on the remote computer or "server side" of the -connection, even if the session in which PSSession was -created is closed and the originating computer is shut down -or disconnected from the network. - -In Windows PowerShell 2.0, the PSSession is deleted from the -remote computer when it is disconnected from the originating -session or the session in which it was created ends. - -When you disconnect a PSSession, the PSSession remains active -and is maintained on the remote computer. The session state -changes from Running to Disconnected. You can reconnect to a -disconnected PSSession from the current session or from a different -session on the same computer, or from a different computer. The -remote computer that maintains the session must be running and +Beginning in Windows PowerShell 3.0, PSSessions are independent of the +sessions in which they are created. Active PSSession are maintained on the +remote computer or "server side" of the connection, even if the session in +which PSSession was created is closed and the originating computer is shut +down or disconnected from the network. + +In Windows PowerShell 2.0, the PSSession is deleted from the remote computer +when it is disconnected from the originating session or the session in which +it was created ends. + +When you disconnect a PSSession, the PSSession remains active and is +maintained on the remote computer. The session state changes from Running to +Disconnected. You can reconnect to a disconnected PSSession from the current +session or from a different session on the same computer, or from a different +computer. The remote computer that maintains the session must be running and be connected to the network. -Commands in a disconnected PSSession continue to run -uninterrupted on the remote computer until the command -completes or the output buffer fills. To prevent a full -output buffer from suspending a command, use the +Commands in a disconnected PSSession continue to run uninterrupted on the +remote computer until the command completes or the output buffer fills. To +prevent a full output buffer from suspending a command, use the **OutputBufferingMode** parameter of the `Disconnect-PSSession`, `New-PSSessionOption`, or `New-PSTransportOption` cmdlets. -Disconnected sessions are maintained in the disconnected -state on the remote computer. They are available for you to -reconnect, until you delete the PSSession, such as by using -the `Remove-PSSession` cmdlet, or until the idle timeout of the -PSSession expires. You can adjust the idle timeout of a PSSession -by using the **IdleTimeoutSec** or **IdleTimeout** parameters of the +Disconnected sessions are maintained in the disconnected state on the remote +computer. They are available for you to reconnect, until you delete the +PSSession, such as by using the `Remove-PSSession` cmdlet, or until the idle +timeout of the PSSession expires. You can adjust the idle timeout of a +PSSession by using the **IdleTimeoutSec** or **IdleTimeout** parameters of the `Disconnect-PSSession`, `New-PSSessionOption`, or `New-PSTransportOption` cmdlets. -Another user can connect to PSSessions that you created, -but only if they can supply the credentials that were used -to create the session, or use the RunAs credentials of -the session configuration. +Another user can connect to PSSessions that you created, but only if they can +supply the credentials that were used to create the session, or use the RunAs +credentials of the session configuration. ## How to Get PSSessions Beginning in Windows PowerShell 3.0, the `Get-PSSession` cmdlet gets -PSSessions on the local computer and remote computers. It can also -get PSSessions that were created in the current session. +PSSessions on the local computer and remote computers. It can also get +PSSessions that were created in the current session. To get PSsessions on the local computer or remote computers, use the **ComputerName** or **ConnectionUri** parameters. Without parameters, `Get-PSSession` gets PSSession that were created in the local session, regardless of where they terminate. -When getting PSSessions, remember to look for them on the computer -on which they are maintained, that is, the remote or "server-side" -computer. +When getting PSSessions, remember to look for them on the computer on which +they are maintained, that is, the remote or "server-side" computer. -For example, if you create a PSSession to the Server01 computer, -get the session from the Server01 computer. If you create a PSSession -from another computer to the local computer, get the session from -the local computer. +For example, if you create a PSSession to the Server01 computer, get the +session from the Server01 computer. If you create a PSSession from another +computer to the local computer, get the session from the local computer. The following command sequence shows how `Get-PSSession` works. -The first command creates a session to the Server01 computer. The -session resides on the Server01 computer. +The first command creates a session to the Server01 computer. The session +resides on the Server01 computer. ```powershell PS C:\> New-PSSession -ComputerName Server01 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` To get the session, use the **ComputerName** parameter of `Get-PSSession` @@ -134,15 +126,15 @@ with a value of Server01. ```powershell PS C:\> Get-PSSession -ComputerName Server01 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` If the value of the **ComputerName** parameter of `Get-PSSession` is localhost, `Get-PSSession` gets PSSessions that terminate at and are -maintained on the local computer. It does not get PSSessions on the -Server01 computer, even if they were started on the local computer. +maintained on the local computer. It does not get PSSessions on the Server01 +computer, even if they were started on the local computer. ```powershell PS C:\> Get-PSSession -ComputerName localhost @@ -156,16 +148,16 @@ that was created in the current session and connects to the Server01 computer. ```powershell PS C:\> Get-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` ## How to Disconnect Sessions -To disconnect a PSSession use the `Disconnect-PSSession` cmdlet. To -identify the PSSession, use the **Session** parameter, or pipe a PSSession -from the `New-PSSession` or `Get-PSSession` cmdlets to `Disconnect-PSSession`. +To disconnect a PSSession use the `Disconnect-PSSession` cmdlet. To identify +the PSSession, use the **Session** parameter, or pipe a PSSession from the +`New-PSSession` or `Get-PSSession` cmdlets to `Disconnect-PSSession`. The following command disconnects the PSSession to the Server01 computer. Notice that the value of the State property is Disconnected and the @@ -174,94 +166,96 @@ Availability is None. ```powershell PS C:\> Get-PSSession -ComputerName Server01 | Disconnect-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Disconnected Microsoft.PowerShell None ``` To create a disconnected session, use the **InDisconnectedSession** parameter -of the `Invoke-Command` cmdlet. It creates a session, starts the command, -and disconnects immediately, before the command can return any output. +of the `Invoke-Command` cmdlet. It creates a session, starts the command, and +disconnects immediately, before the command can return any output. -The following command runs a `Get-WinEvent` command in a disconnected -session on the Server02 remote computer. +The following command runs a `Get-WinEvent` command in a disconnected session +on the Server02 remote computer. ```powershell PS C:\> Invoke-Command -ComputerName Server02 -InDisconnectedSession ` -ScriptBlock { Get-WinEvent -LogName "Windows PowerShell" } -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 4 Session3 Server02 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 4 Session3 Server02 Disconnected Microsoft.PowerShell None ``` ## How to Connect to Disconnected Sessions -You can connect to any available disconnected PSSession from the session -in which you created the PSSession or from other sessions on the local -computer or other computers. +You can connect to any available disconnected PSSession from the session in +which you created the PSSession or from other sessions on the local computer +or other computers. -You can create a PSSession, run commands in the PSSession, disconnect from -the PSSession, close Windows PowerShell, and shut down the computer. Hours -later, you can open a different computer, get the PSSession, connect to it, -and get the results of commands that ran in the PSSession while it was -disconnected. Then you can run more commands in the session. +You can create a PSSession, run commands in the PSSession, disconnect from the +PSSession, close Windows PowerShell, and shut down the computer. Hours later, +you can open a different computer, get the PSSession, connect to it, and get +the results of commands that ran in the PSSession while it was disconnected. +Then you can run more commands in the session. To connect a disconnected PSSession, use the `Connect-PSSession` cmdlet. Use -the **ComputerName** or **ConnectionUri** parameters to identify the PSSession, or -pipe a PSSession from `Get-PSSession` to `Connect-PSSession`. +the **ComputerName** or **ConnectionUri** parameters to identify the +PSSession, or pipe a PSSession from `Get-PSSession` to `Connect-PSSession`. -The following command gets the sessions on the Server02 computer. -The output includes two disconnected sessions, both of which are available. +The following command gets the sessions on the Server02 computer. The output +includes two disconnected sessions, both of which are available. ```powershell PS C:\> Get-PSSession -ComputerName Server02 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 juneb-srv8320 Disconnected Microsoft.PowerShell None - 4 Session3 juneb-srv8320 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 juneb-srv8320 Disconnected Microsoft.PowerShell None + 4 Session3 juneb-srv8320 Disconnected Microsoft.PowerShell None ``` -The following command connects to Session2. The PSSession is now open and available. +The following command connects to Session2. The PSSession is now open and +available. ```powershell PS C:\> Connect-PSSession -ComputerName Server02 -Name Session2 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 juneb-srv8320 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 juneb-srv8320 Opened Microsoft.PowerShell Available ``` ## How to Get the Results -To get the results of commands that ran in a disconnected PSSession, use -the `Receive-PSSession` cmdlet. +To get the results of commands that ran in a disconnected PSSession, use the +`Receive-PSSession` cmdlet. You can use `Receive-PSSession` in addition to, or instead of, using the `Connect-PSSession` cmdlet. If the session is already reconnected, -`Receive-PSSession` gets the results of commands that ran when the session -was disconnected. If the PSSession is still disconnected, `Receive-PSSession` +`Receive-PSSession` gets the results of commands that ran when the session was +disconnected. If the PSSession is still disconnected, `Receive-PSSession` connects to it and then gets the results of commands that ran while it was disconnected. -`Receive-PSSession` can return the results in a job (asynchronously) or to -the host program (synchronously). Use the **OutTarget** parameter to select Job -or Host. Host is the default value. However, if the command that is being +`Receive-PSSession` can return the results in a job (asynchronously) or to the +host program (synchronously). Use the **OutTarget** parameter to select Job or +Host. Host is the default value. However, if the command that is being received was started in the current session as a job, it is returned as a job by default. -The following command uses the `Receive-PSSession` cmdlet to connect to the PSSession -on the Server02 computer and get the results of the `Get-WinEvent` command that -ran in the Session3 session. The command uses the **OutTarget** parameter to get the -results in a job. +The following command uses the `Receive-PSSession` cmdlet to connect to the +PSSession on the Server02 computer and get the results of the `Get-WinEvent` +command that ran in the Session3 session. The command uses the **OutTarget** +parameter to get the results in a job. ```powershell -PS C:\> Receive-PSSession -ComputerName Server02 -Name Session3 -OutTarget Job +PS C:\> Receive-PSSession -ComputerName Server02 -Name Session3 ` + -OutTarget Job -Id Name PSJobTypeName State HasMoreData Location --- ---- ------------- ----- ----------- -------- - 3 Job3 RemoteJob Running True Server02 +Id Name PSJobTypeName State HasMoreData Location +-- ---- ------------- ----- ----------- -------- + 3 Job3 RemoteJob Running True Server02 ``` To get the results of the job, use the `Receive-Job` cmdlet. @@ -281,141 +275,135 @@ TimeCreated Id LevelDisplayName Message PSComputerName ## State and Availability -The State and Availability properties of a disconnected PSSession -tell you whether the session is available for you to reconnect to it. +The State and Availability properties of a disconnected PSSession tell you +whether the session is available for you to reconnect to it. -When a PSSession is connected to the current session, its state is -Opened and its availability is Available. When you disconnect from -the PSSession, the PSSession state is Disconnected and its Availability -is none. +When a PSSession is connected to the current session, its state is Opened and +its availability is Available. When you disconnect from the PSSession, the +PSSession state is Disconnected and its Availability is none. -However, 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. However, it does not mean -that the PSSession is disconnected from all sessions. It might be -connected to a different session. +However, 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. 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, -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. +To determine whether you can connect or reconnect to the PSSession, 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. -The following example is run in two sessions (Windows PowerShell -console windows) on the same computer. Note the changing values of the -State and Availability properties in each session as the PSSession is -disconnected and reconnected. +The following example is run in two sessions (Windows PowerShell console +windows) on the same computer. Note the changing values of the State and +Availability properties in each session as the PSSession is disconnected and +reconnected. ```powershell # Session 1 PS C:\> New-PSSession -ComputerName Server30 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Opened Microsoft.PowerShell Available # Session 2 PS C:\> Get-PSSession -ComputerName Server30 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell Busy +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell Busy # Session 1 -PS C:\> Get-PSSession -ComputerName Server30 -Name Test | Disconnect-PSSession +PS C:\> Get-PSSession -ComputerName Server30 -Name Test | +>> Disconnect-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell None # Session 2 PS C:\> Get-PSSession -ComputerName Server30 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell None # Session 2 PS C:\> Connect-PSSession -ComputerName Server01 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -3 Test Server30 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +3 Test Server30 Opened Microsoft.PowerShell Available # Session 1 PS C:\> Get-PSSession -ComputerName Server30 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell Busy +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell Busy # IDLE TIMEOUT ``` -Disconnected sessions are maintained on the remote computer until -you delete them, such as by using the `Remove-PSSession` cmdlet, or -they time out. The IdleTimeout property of a PSSession determines -how long a disconnected session is maintained before it is deleted. +Disconnected sessions are maintained on the remote computer until you delete +them, such as by using the `Remove-PSSession` cmdlet, or they time out. The +IdleTimeout property of a PSSession determines how long a disconnected session +is maintained before it is deleted. PSSessions are idle when the "heartbeat thread" receives no response. -Disconnecting a session makes it idle and starts the Idle Timeout -clock, even if commands are still running in the disconnected session. -Windows PowerShell considers disconnected sessions to be active, but -idle. - -When creating and disconnecting sessions, verify that the idle -timeout in the PSSession is long enough to maintain the session -for your needs, but not so long that it consumes unnecessary -resources on the remote computer. - -The IdleTimeoutMs property of the session configuration -determines the default idle timeout of sessions that use the -session configuration. You can override the default value, but -the value that you use cannot exceed the MaxIdleTimeoutMs -property of the session configuration. - -To find the value of the IdleTimeoutMs and MaxIdleTimeoutMs -values of a session configuration, use the following command -format. +Disconnecting a session makes it idle and starts the Idle Timeout clock, even +if commands are still running in the disconnected session. Windows PowerShell +considers disconnected sessions to be active, but idle. + +When creating and disconnecting sessions, verify that the idle timeout in the +PSSession is long enough to maintain the session for your needs, but not so +long that it consumes unnecessary resources on the remote computer. + +The IdleTimeoutMs property of the session configuration determines the default +idle timeout of sessions that use the session configuration. You can override +the default value, but the value that you use cannot exceed the +MaxIdleTimeoutMs property of the session configuration. + +To find the value of the IdleTimeoutMs and MaxIdleTimeoutMs values of a +session configuration, use the following command format. ```powershell -Get-PSSessionConfiguration | Format-Table Name, IdleTimeoutMs, MaxIdleTimeoutMs +Get-PSSessionConfiguration | + Format-Table Name, IdleTimeoutMs, MaxIdleTimeoutMs ``` -You can override the default value in the session configuration and -set the idle timeout of a PSSession when you create a PSSession and -when you disconnect. +You can override the default value in the session configuration and set the +idle timeout of a PSSession when you create a PSSession and when you +disconnect. -If you are a member of the Administrators group on the remote computer, -you can also create and change the IdleTimeoutMs and MaxIdleTimeoutMs -properties of session configurations. +If you are a member of the Administrators group on the remote computer, you +can also create and change the IdleTimeoutMs and MaxIdleTimeoutMs properties +of session configurations. ## NOTES: -The idle timeout value of session configurations and session -options is in milliseconds. The idle timeout value of sessions -and session configuration options is in seconds. +The idle timeout value of session configurations and session options is in +milliseconds. The idle timeout value of sessions and session configuration +options is in seconds. -You can set the idle timeout of a PSSession when you create the -PSSession (`New-PSSession`, `Invoke-Command`) and when you disconnect -from it (`Disconnect-PSSession`). However, you cannot change the -IdleTimeout value when you connect to the PSSession -(`Connect-PSSession`) or get results (`Receive-PSSession`). +You can set the idle timeout of a PSSession when you create the PSSession +(`New-PSSession`, `Invoke-Command`) and when you disconnect from it +(`Disconnect-PSSession`). However, you cannot change the IdleTimeout value +when you connect to the PSSession (`Connect-PSSession`) or get results +(`Receive-PSSession`). The `Connect-PSSession` and `Receive-PSSession` cmdlets have a -**SessionOption** parameter that takes a SessionOption object, -such as one returned by the `New-PSSessionOption` cmdlet. However, -the IdleTimeout value in SessionOption object and the IdleTimeout -value in the $PSSessionOption preference variable do not change -the value of the IdleTimeout of the PSSession in a `Connect-PSSession` -or `Receive-PSSession` command. +**SessionOption** parameter that takes a SessionOption object, such as one +returned by the `New-PSSessionOption` cmdlet. However, the IdleTimeout value +in SessionOption object and the IdleTimeout value in the $PSSessionOption +preference variable do not change the value of the IdleTimeout of the +PSSession in a `Connect-PSSession` or `Receive-PSSession` command. * To create a PSSession with a particular idle timeout value, create a $PSSessionOption preference variable. Set the value of the IdleTimeout property to the desired value (in milliseconds). - When you create PSSessions, the values in $PSSessionOption variable - take precedence over the values in the session configuration. + When you create PSSessions, the values in $PSSessionOption variable take + precedence over the values in the session configuration. For example, this command sets an idle timeout of 48 hours. @@ -477,38 +465,35 @@ Set-PSSessionConfiguration -Name Test -TransportOption $o ## Output Buffering Mode -The output buffering mode of a PSSession determines how command -output is managed when the output buffer of the PSSession is full. +The output buffering mode of a PSSession determines how command output is +managed when the output buffer of the PSSession is full. -In a disconnected session, the output buffering mode effectively -determines whether the command continues to run while the session -is disconnected. +In a disconnected session, the output buffering mode effectively determines +whether the command continues to run while the session is disconnected. Valid values: * Block - When the output buffer is full, execution is suspended - until the buffer is clear. + When the output buffer is full, execution is suspended until the buffer is + clear. * Drop - When the output buffer is full, execution continues. - As new output is generated, the oldest output is discarded. + When the output buffer is full, execution continues. As new output is + generated, the oldest output is discarded. -Block, the default value, preserves data, but might interrupt -the command. +Block, the default value, preserves data, but might interrupt the command. -A value of Drop allows the command to complete, although data might -be lost. When using the Drop value, redirect the command output to -a file on disk. This value is recommended for disconnected sessions. +A value of Drop allows the command to complete, although data might be lost. +When using the Drop value, redirect the command output to a file on disk. This +value is recommended for disconnected sessions. -The OutputBufferingMode property of the session configuration -determines the default output buffering mode of sessions that -use the session configuration. +The OutputBufferingMode property of the session configuration determines the +default output buffering mode of sessions that use the session configuration. -To find the value of the OutputBufferingMode of a session -configuration, use the following command formats. +To find the value of the OutputBufferingMode of a session configuration, use +the following command formats. ```powershell (Get-PSSessionConfiguration ).OutputBufferingMode @@ -520,12 +505,12 @@ or Get-PSSessionConfiguration | Format-Table Name, OutputBufferingMode ``` -You can override the default value in the session configuration and set -the output buffering mode of a PSSession when you create a PSSession, -when you disconnect, and when you reconnect. +You can override the default value in the session configuration and set the +output buffering mode of a PSSession when you create a PSSession, when you +disconnect, and when you reconnect. -If you are a member of the Administrators group on the remote computer, -you can also create and change the output buffering mode of session +If you are a member of the Administrators group on the remote computer, you +can also create and change the output buffering mode of session configurations. * To create a PSSession with an output buffering mode of Drop, create @@ -609,63 +594,58 @@ Set-PSSessionConfiguration -Name Test -TransportOption $o ## Disconnecting Loopback Sessions -"Loopback sessions" or "local sessions" are PSSessions that -originate and terminate on the same computer. Like other -PSSessions, active loopback sessions are maintained on the -computer on the remote end of the connection (the local -computer), so you can disconnect from and reconnect to -loopback sessions. +"Loopback sessions" or "local sessions" are PSSessions that originate and +terminate on the same computer. Like other PSSessions, active loopback +sessions are maintained on the computer on the remote end of the connection +(the local computer), so you can disconnect from and reconnect to loopback +sessions. -By default, loopback sessions are created with a network security -token that does not permit commands run in the session to access -other computers. You can reconnect to loopback sessions that have a -network security token from any session on the local computer or a -remote computer. +By default, loopback sessions are created with a network security token that +does not permit commands run in the session to access other computers. You can +reconnect to loopback sessions that have a network security token from any +session on the local computer or a remote computer. However, if you use the **EnableNetworkAccess** parameter of the -`New-PSSession`, `Enter-PSSession`, or `Invoke-Command` cmdlet, the -loopback session is created with an interactive security token. -The interactive token enables commands that run in the loopback -session to get data from other computers. +`New-PSSession`, `Enter-PSSession`, or `Invoke-Command` cmdlet, the loopback +session is created with an interactive security token. The interactive token +enables commands that run in the loopback session to get data from other +computers. -You can disconnect loopback sessions with interactive tokens and -then reconnect to them from the same session or a different session -on the same computer. However, to prevent malicious access, you can -reconnect to loopback sessions with interactive tokens only from the -computer on which they were created. +You can disconnect loopback sessions with interactive tokens and then +reconnect to them from the same session or a different session on the same +computer. However, to prevent malicious access, you can reconnect to loopback +sessions with interactive tokens only from the computer on which they were +created. ## Waiting for Jobs in Disconnected Sessions -The `Wait-Job` cmdlet waits until a job completes and then -returns to the command prompt or the next command. By default, -`Wait-Job` returns if the session in which a job is running is -disconnected. To direct the `Wait-Job` cmdlet to wait until the -session is reconnected (in the Opened state), use the **Force** -parameter. For more information, see [Wait-Job](../Wait-Job.md). +The `Wait-Job` cmdlet waits until a job completes and then returns to the +command prompt or the next command. By default, `Wait-Job` returns if the +session in which a job is running is disconnected. To direct the `Wait-Job` +cmdlet to wait until the session is reconnected (in the Opened state), use the +**Force** parameter. For more information, see [Wait-Job](../Wait-Job.md). ## Robust Sessions and Unintentional Disconnection -Occasionally, a PSSession might be disconnected unintentionally -due to a computer failure or network outage. Windows PowerShell -attempts to recover the PSSession, but its success depends upon -the severity and duration of the cause. - -The state of an unintentionally disconnected PSSession might -be Broken or Closed, but it might also be Disconnected. If -the value of State is Disconnected, you can use the same -techniques to manage the PSSession as you would if the -session were disconnected intentionally. For example, you -can use the `Connect-PSSession` cmdlet to reconnect to the session -and the `Receive-PSSession` cmdlet to get results of commands that -ran while the session was disconnected. - -If you close (exit) the session in which a PSSession was -created while commands are running in the PSSession, Windows -PowerShell maintains the PSSession in the Disconnected state -on the remote computer. If you close (exit) the session in -which a PSSession was created, but no commands are running -in the PSSession, Windows PowerShell does not attempt to -maintain the PSSession. +Occasionally, a PSSession might be disconnected unintentionally due to a +computer failure or network outage. Windows PowerShell attempts to recover the +PSSession, but its success depends upon the severity and duration of the +cause. + +The state of an unintentionally disconnected PSSession might be Broken or +Closed, but it might also be Disconnected. If the value of State is +Disconnected, you can use the same techniques to manage the PSSession as you +would if the session were disconnected intentionally. For example, you can use +the `Connect-PSSession` cmdlet to reconnect to the session and the +`Receive-PSSession` cmdlet to get results of commands that ran while the +session was disconnected. + +If you close (exit) the session in which a PSSession was created while +commands are running in the PSSession, Windows PowerShell maintains the +PSSession in the Disconnected state on the remote computer. If you close +(exit) the session in which a PSSession was created, but no commands are +running in the PSSession, Windows PowerShell does not attempt to maintain the +PSSession. ## See Also diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md index d8b2c92b2d3..93fb4c492c5 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,344 +7,512 @@ title: about_Remote_FAQ --- # About Remote FAQ -## about_Remote_FAQ - ## SHORT DESCRIPTION -Contains questions and answers about running remote commands in Windows PowerShell. +Contains questions and answers about running remote commands in Windows +PowerShell. ## LONG DESCRIPTION -When you work remotely, you type commands in Windows PowerShell on one computer (known as the "local computer"), but the commands run on another computer (known as the "remote computer"). The experience of working remotely should be as much like working directly at the remote computer as possible. - - -``` -Note: To use Windows PowerShell remoting, the remote computer - must be configured for remoting. For more information, see - about_Remote_Requirements. -``` +When you work remotely, you type commands in Windows PowerShell on one +computer (known as the "local computer"), but the commands run on another +computer (known as the "remote computer"). The experience of working remotely +should be as much like working directly at the remote computer as possible. +Note: To use Windows PowerShell remoting, the remote computer must be +configured for remoting. For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). ### MUST BOTH COMPUTERS HAVE WINDOWS POWERSHELL INSTALLED? -Yes. To work remotely, the local and remote computers must have Windows PowerShell, the Microsoft .NET Framework, and the Web Services for Management (WS-Management) protocol. Any files and other resources that are needed to execute a particular command must be on the remote computer. -Computers running Windows PowerShell 3.0 and computers running Windows PowerShell 2.0 can connect to each other remotely and run remote commands. However, some features, such as the ability to disconnect from a session and reconnect to it, work only when both computers are running Windows PowerShell 3.0. +Yes. To work remotely, the local and remote computers must have Windows +PowerShell, the Microsoft .NET Framework, and the Web Services for Management +(WS-Management) protocol. Any files and other resources that are needed to +execute a particular command must be on the remote computer. -You must have permission to connect to the remote computer, permission to run Windows PowerShell, and permission to access data stores (such as files and folders), and the registry on the remote computer. +Computers running Windows PowerShell 3.0 and computers running Windows +PowerShell 2.0 can connect to each other remotely and run remote commands. +However, some features, such as the ability to disconnect from a session and +reconnect to it, work only when both computers are running Windows PowerShell +3.0. -For more information, see about_Remote_Requirements. +You must have permission to connect to the remote computer, permission to run +Windows PowerShell, and permission to access data stores (such as files and +folders), and the registry on the remote computer. +For more information, see [about_Remote_Requirements](about_Remote_Requirements.md). ### HOW DOES REMOTING WORK? -When you submit a remote command, the command is transmitted across the network to the Windows PowerShell engine on the remote computer, and it runs in the Windows PowerShell client on the remote computer. The command results are sent back to the local computer and appear in the Windows PowerShell session on the local computer. -To transmit the commands and receive the output, Windows PowerShell uses the WS-Management protocol. For information about the WS-Management protocol, see "WS-Management Protocol" in the MSDN (Microsoft Developer Network) library at http:\/\/go.microsoft.com\/fwlink\/?LinkId\=144634. +When you submit a remote command, the command is transmitted across the +network to the Windows PowerShell engine on the remote computer, and it runs +in the Windows PowerShell client on the remote computer. The command results +are sent back to the local computer and appear in the Windows PowerShell +session on the local computer. -Beginning in Windows PowerShell 3.0, remote sessions are stored on the remote computer. This enables you to disconnect from the session and reconnect from a different session or a different computer without interrupting the commands or losing state. +To transmit the commands and receive the output, Windows PowerShell uses the +WS-Management protocol. For information about the WS-Management protocol, see +[WS-Management Protocol](http://go.microsoft.com\/fwlink/?LinkId=144634) in +the MSDN library. +Beginning in Windows PowerShell 3.0, remote sessions are stored on the remote +computer. This enables you to disconnect from the session and reconnect from a +different session or a different computer without interrupting the commands or +losing state. ### IS WINDOWS POWERSHELL REMOTING SECURE? -When you connect to a remote computer, the system uses the user name and password credentials on the local computer or the credentials that you supply in the command to log you in to the remote computer. The credentials and the rest of the transmission are encrypted. -To add additional protection, you can configure the remote computer to use Secure Sockets Layer (SSL) instead of HTTP to listen for Windows Remote Management (WinRM) requests. Then, users can use the UseSSL parameters of the Invoke-Command, New-PSSession, and Enter-PSSession cmdlets when establishing a connection. This option uses the more secure HTTPS channel instead of HTTP. +When you connect to a remote computer, the system uses the user name and +password credentials on the local computer or the credentials that you supply +in the command to log you in to the remote computer. The credentials and the +rest of the transmission are encrypted. +To add additional protection, you can configure the remote computer to use +Secure Sockets Layer (SSL) instead of HTTP to listen for Windows Remote +Management (WinRM) requests. Then, users can use the UseSSL parameters of the +Invoke-Command, New-PSSession, and Enter-PSSession cmdlets when establishing a +connection. This option uses the more secure HTTPS channel instead of HTTP. ### DO ALL REMOTE COMMANDS REQUIRE WINDOWS POWERSHELL REMOTING? -No. Several cmdlets have a ComputerName parameter that lets you get objects from the remote computer. - -These cmdlets do not use Windows PowerShell remoting. So, you can use them on any computer that is running Windows PowerShell, even if the computer is not configured for Windows PowerShell remoting or if the computer does not meet the requirements for Windows PowerShell remoting. -These cmdlets include the following cmdlets: +No. Several cmdlets have a ComputerName parameter that lets you get objects +from the remote computer. +These cmdlets do not use Windows PowerShell remoting. So, you can use them on +any computer that is running Windows PowerShell, even if the computer is not +configured for Windows PowerShell remoting or if the computer does not meet +the requirements for Windows PowerShell remoting. -``` -Get-Process -Get-Service -Get-WinEvent -Get-EventLog -Get-WmiObject -Test-Connection -``` +These cmdlets include the following: +- Get-Process +- Get-Service +- Get-WinEvent +- Get-EventLog +- Get-WmiObject +- Test-Connection To find all the cmdlets with a ComputerName parameter, type: - -``` -Get-Help * -Parameter ComputerName -or +```powershell +Get-Help * -Parameter ComputerName +# or Get-Command -ParameterName ComputerName ``` +To determine whether the ComputerName parameter of a particular cmdlet +requires Windows PowerShell remoting, see the parameter description. To +display the parameter description, type: -To determine whether the ComputerName parameter of a particular cmdlet requires Windows PowerShell remoting, see the parameter description. To display the parameter description, type: - - -``` +```ppowershell Get-Help -Parameter ComputerName ``` - For example: - -``` +```powershell Get-Help Get-Process -Parameter Computername ``` - For all other commands, use the Invoke-Command cmdlet. - ### HOW DO I RUN A COMMAND ON A REMOTE COMPUTER? + To run a command on a remote computer, use the Invoke-Command cmdlet. -Enclose your command in braces ( {} ) to make it a script block. Use the ScriptBlock parameter of Invoke-Command to specify the command. +Enclose your command in braces ( {} ) to make it a script block. Use the +ScriptBlock parameter of Invoke-Command to specify the command. -You can use the ComputerName parameter of Invoke-Command to specify a remote computer. Or, you can create a persistent connection to a remote computer (a session) and then use the Session parameter of Invoke-Command to run the command in the session. +You can use the ComputerName parameter of Invoke-Command to specify a remote +computer. Or, you can create a persistent connection to a remote computer (a +session) and then use the Session parameter of Invoke-Command to run the +command in the session. For example, the following commands run a Get-Process command remotely. +```powershell +Invoke-Command -ComputerName Server01, Server02 -ScriptBlock {Get-Process} + +# - OR - -``` -Invoke-Command -ComputerName Server01, Server02 -ScriptBlock {Get-Process} - - - OR - - Invoke-Command -Session $s -ScriptBlock {Get-Process} ``` +To interrupt a remote command, type CTRL\+C. The interruption request is +passed to the remote computer, where it terminates the remote command. -To interrupt a remote command, type CTRL\+C. The interruption request is passed to the remote computer, where it terminates the remote command. - -For more information about remote commands, see about_Remote and the Help topics for the cmdlets that support remoting. - +For more information about remote commands, see about_Remote and the Help +topics for the cmdlets that support remoting. ### CAN I JUST "TELNET INTO" A REMOTE COMPUTER? -You can use the Enter-PSSession cmdlet to start an interactive session with a remote computer. -At the Windows PowerShell prompt, type: +You can use the Enter-PSSession cmdlet to start an interactive session with a +remote computer. +At the Windows PowerShell prompt, type: -``` +```powershell Enter-PSSession ``` - -The command prompt changes to show that you are connected to the remote computer. - +The command prompt changes to show that you are connected to the remote +computer. ``` \C:> ``` - -Now, the commands that you type run on the remote computer just as though you typed them directly on the remote computer. +Now, the commands that you type run on the remote computer just as though you +typed them directly on the remote computer. To end the interactive session, type: - -``` +```powershell Exit-PSSession ``` - -An interactive session is a persistent session that uses the WS-Management protocol. It is not the same as using Telnet, but it provides a similar experience. +An interactive session is a persistent session that uses the WS-Management +protocol. It is not the same as using Telnet, but it provides a similar +experience. For more information, see Enter-PSSession. - ### CAN I CREATE A PERSISTENT CONNECTION? -Yes. You can run remote commands by specifying the name of the remote computer, its NetBIOS name, or its IP address. Or, you can run remote commands by specifying a Windows PowerShell session (PSSession) that is connected to the remote computer. -When you use the ComputerName parameter of Invoke-Command or Enter-PSSession, Windows PowerShell establishes a temporary connection. Windows PowerShell uses the connection to run only the current command, and then it closes the connection. This is a very efficient method for running a single command or several unrelated commands, even on many remote computers. +Yes. You can run remote commands by specifying the name of the remote +computer, its NetBIOS name, or its IP address. Or, you can run remote commands +by specifying a Windows PowerShell session (PSSession) that is connected to +the remote computer. -When you use the New-PSSession cmdlet to create a PSSession, Windows PowerShell establishes a persistent connection for the PSSession. Then, you can run multiple commands in the PSSession, including commands that share data. +When you use the ComputerName parameter of Invoke-Command or Enter-PSSession, +Windows PowerShell establishes a temporary connection. Windows PowerShell uses +the connection to run only the current command, and then it closes the +connection. This is a very efficient method for running a single command or +several unrelated commands, even on many remote computers. -Typically, you create a PSSession to run a series of related commands that share data. Otherwise, the temporary connection created by the ComputerName parameter is sufficient for most commands. +When you use the New-PSSession cmdlet to create a PSSession, Windows +PowerShell establishes a persistent connection for the PSSession. Then, you +can run multiple commands in the PSSession, including commands that share +data. -For more information about sessions, see about_PSSessions. +Typically, you create a PSSession to run a series of related commands that +share data. Otherwise, the temporary connection created by the ComputerName +parameter is sufficient for most commands. +For more information about sessions, see about_PSSessions. ### CAN I RUN COMMANDS ON MORE THAN ONE COMPUTER AT A TIME? -Yes. The ComputerName parameter of the Invoke-Command cmdlet accepts multiple computer names, and the Session parameter accepts multiple PSSessions. -When you run an Invoke-Command command, Windows PowerShell runs the commands on all of the specified computers or in all of the specified PSSessions. +Yes. The ComputerName parameter of the Invoke-Command cmdlet accepts multiple +computer names, and the Session parameter accepts multiple PSSessions. -Windows PowerShell can manage hundreds of concurrent remote connections. However, the number of remote commands that you can send might be limited by the resources of your computer and its capacity to establish and maintain multiple network connections. +When you run an Invoke-Command command, Windows PowerShell runs the commands +on all of the specified computers or in all of the specified PSSessions. -For more information, see the example in the Invoke-Command Help topic. +Windows PowerShell can manage hundreds of concurrent remote connections. +However, the number of remote commands that you can send might be limited by +the resources of your computer and its capacity to establish and maintain +multiple network connections. +For more information, see the example in the Invoke-Command Help topic. ### WHERE ARE MY PROFILES? -Windows PowerShell profiles are not run automatically in remote sessions, so the commands that the profile adds are not present in the session. In addition, the $profile automatic variable is not populated in remote sessions. -To run a profile in a session, use the Invoke-Command cmdlet. +Windows PowerShell profiles are not run automatically in remote sessions, so +the commands that the profile adds are not present in the session. In +addition, the \$profile automatic variable is not populated in remote sessions. -For example, the following command runs the CurrentUserCurrentHost profile from the local computer in the session in $s. +To run a profile in a session, use the `Invoke-Command` cmdlet. +For example, the following command runs the CurrentUserCurrentHost profile +from the local computer in the session in \$s. ``` Invoke-Command -Session $s -FilePath $profile ``` +The following command runs the CurrentUserCurrentHost profile from the remote +computer in the session in $s. Because the $profile variable is not populated, +the command uses the explicit path to the profile. -The following command runs the CurrentUserCurrentHost profile from the remote computer in the session in $s. Because the $profile variable is not populated, the command uses the explicit path to the profile. - - -``` -Invoke-Command -Session $s {. "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1"} +```powershell +Invoke-Command -Session $s { + . "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1" +} ``` +After running this command, the commands that the profile adds to the session +are available in $s. -After running this command, the commands that the profile adds to the session are available in $s. - -You can also use a startup script in a session configuration to run a profile in every remote session that uses the session configuration. - -For more information about Windows PowerShell profiles, see about_Profiles. For more information about session configurations, see Register-PSSessionConfiguration. +You can also use a startup script in a session configuration to run a profile +in every remote session that uses the session configuration. +For more information about Windows PowerShell profiles, see about_Profiles. +For more information about session configurations, see +Register-PSSessionConfiguration. ### HOW DOES THROTTLING WORK ON REMOTE COMMANDS? -To help you manage the resources on your local computer, Windows PowerShell includes a per-command throttling feature that lets you limit the number of concurrent remote connections that are established for each command. -The default is 32 concurrent connections, but you can use the ThrottleLimit parameters of the cmdlets to set a custom throttle limit for particular commands. +To help you manage the resources on your local computer, Windows PowerShell +includes a per-command throttling feature that lets you limit the number of +concurrent remote connections that are established for each command. -When you use the throttling feature, remember that it is applied to each command, not to the entire session or to the computer. If you are running commands concurrently in several sessions or PSSessions, the number of concurrent connections is the sum of the concurrent connections in all the sessions. +The default is 32 concurrent connections, but you can use the **ThrottleLimit** +parameters of the cmdlets to set a custom throttle limit for particular +commands. -To find cmdlets with a ThrottleLimit parameter, type: +When you use the throttling feature, remember that it is applied to each +command, not to the entire session or to the computer. If you are running +commands concurrently in several sessions or PSSessions, the number of +concurrent connections is the sum of the concurrent connections in all the +sessions. +To find cmdlets with a ThrottleLimit parameter, type: ``` -Get-Help * -Parameter ThrottleLimit --or- +Get-Help * -Parameter ThrottleLimit +-or- Get-Command -ParameterName ThrottleLimit ``` - ### IS THE OUTPUT OF REMOTE COMMANDS DIFFERENT FROM LOCAL OUTPUT? -When you use Windows PowerShell locally, you send and receive "live" .NET Framework objects; "live" objects are objects that are associated with actual programs or system components. When you invoke the methods or change the properties of live objects, the changes affect the actual program or component. And, when the properties of a program or component change, the properties of the object that represent them also change. -However, because most live objects cannot be transmitted over the network, Windows PowerShell "serializes" most of the objects sent in remote commands, that is, it converts each object into a series of XML (Constraint Language in XML [CLiXML]) data elements for transmission. +When you use Windows PowerShell locally, you send and receive "live" .NET +Framework objects; "live" objects are objects that are associated with actual +programs or system components. When you invoke the methods or change the +properties of live objects, the changes affect the actual program or +component. And, when the properties of a program or component change, the +properties of the object that represent them also change. -When Windows PowerShell receives a serialized object, it converts the XML into a deserialized object type. The deserialized object is an accurate record of the properties of the program or component at a previous time, but it is no longer "live", that is, it is no longer directly associated with the component. And, the methods are removed because they are no longer effective. +However, because most live objects cannot be transmitted over the network, +Windows PowerShell "serializes" most of the objects sent in remote commands, +that is, it converts each object into a series of XML (Constraint Language in +XML [CLiXML]) data elements for transmission. -Typically, you can use deserialized objects just as you would use live objects, but you must be aware of their limitations. Also, the objects that are returned by the Invoke-Command cmdlet have additional properties that help you to determine the origin of the command. +When Windows PowerShell receives a serialized object, it converts the XML into +a deserialized object type. The deserialized object is an accurate record of +the properties of the program or component at a previous time, but it is no +longer "live", that is, it is no longer directly associated with the +component. And, the methods are removed because they are no longer effective. -Some object types, such as DirectoryInfo objects and GUIDs, are converted back into live objects when they are received. These objects do not need any special handling or formatting. +Typically, you can use deserialized objects just as you would use live +objects, but you must be aware of their limitations. Also, the objects that +are returned by the Invoke-Command cmdlet have additional properties that help +you to determine the origin of the command. -For information about interpreting and formatting remote output, see about_Remote_Output. +Some object types, such as DirectoryInfo objects and GUIDs, are converted back +into live objects when they are received. These objects do not need any +special handling or formatting. +For information about interpreting and formatting remote output, see +[about_Remote_Output](about_Remote_Output.md). ### CAN I RUN BACKGROUND JOBS REMOTELY? -Yes. A Windows PowerShell background job is a Windows PowerShell command that runs asynchronously without interacting with the session. When you start a background job, the command prompt returns immediately, and you can continue to work in the session while the job runs even if it runs for an extended period of time. -You can start a background job even while other commands are running because background jobs always run asynchronously in a temporary session. +Yes. A Windows PowerShell background job is a Windows PowerShell command that +runs asynchronously without interacting with the session. When you start a +background job, the command prompt returns immediately, and you can continue +to work in the session while the job runs even if it runs for an extended +period of time. -You can run background jobs on a local or remote computer. By default, a background job runs on the local computer. However, you can use the AsJob parameter of the Invoke-Command cmdlet to run any remote command as a background job. And, you can use Invoke-Command to run a Start-Job command remotely. +You can start a background job even while other commands are running because +background jobs always run asynchronously in a temporary session. -For more information about background jobs in Windows PowerShell , see about_Jobs and about_Remote_Jobs. +You can run background jobs on a local or remote computer. By default, a +background job runs on the local computer. However, you can use the AsJob +parameter of the Invoke-Command cmdlet to run any remote command as a +background job. And, you can use Invoke-Command to run a Start-Job command +remotely. +For more information about background jobs in Windows PowerShell , see +[about_Jobs(about_Jobs.md)] and [about_Remote_Jobs(about_Remote_Jobs.md)]. ### CAN I RUN WINDOWS PROGRAMS ON A REMOTE COMPUTER? -You can use Windows PowerShell remote commands to run Windows-based programs on remote computers. For example, you can run Shutdown.exe or Ipconfig on a remote computer. -However, you cannot use Windows PowerShell commands to open the user interface for any program on a remote computer. +You can use Windows PowerShell remote commands to run Windows-based programs +on remote computers. For example, you can run Shutdown.exe or Ipconfig on a +remote computer. -When you start a Windows program on a remote computer, the command is not completed, and the Windows PowerShell command prompt does not return, until the program is finished or until you press CTRL\+C to interrupt the command. For example, if you run the IpConfig program on a remote computer, the command prompt does not return until IpConfig is completed. +However, you cannot use Windows PowerShell commands to open the user interface +for any program on a remote computer. -If you use remote commands to start a program that has a user interface, the program process starts, but the user interface does not appear. The Windows PowerShell command is not completed, and the command prompt does not return until you stop the program process or until you press CTRL\+C, which interrupts the command and stops the process. +When you start a Windows program on a remote computer, the command is not +completed, and the Windows PowerShell command prompt does not return, until +the program is finished or until you press CTRL\+C to interrupt the command. +For example, if you run the IpConfig program on a remote computer, the command +prompt does not return until IpConfig is completed. -For example, if you use a Windows PowerShell command to run Notepad on a remote computer, the Notepad process starts on the remote computer, but the Notepad user interface does not appear. To interrupt the command and restore the command prompt, press CTRL\+C. +If you use remote commands to start a program that has a user interface, the +program process starts, but the user interface does not appear. The Windows +PowerShell command is not completed, and the command prompt does not return +until you stop the program process or until you press CTRL\+C, which +interrupts the command and stops the process. +For example, if you use a Windows PowerShell command to run Notepad on a +remote computer, the Notepad process starts on the remote computer, but the +Notepad user interface does not appear. To interrupt the command and restore +the command prompt, press CTRL\+C. ### CAN I LIMIT THE COMMANDS THAT USERS CAN RUN REMOTELY ON MY COMPUTER? -Yes. Every remote session must use one of the session configurations on the remote computer. You can manage the session configurations on your computer (and the permissions to those session configurations) to determine who can run commands remotely on your computer and which commands they can run. - -A session configuration configures the environment for the session. You can define the configuration by using an assembly that implements a new configuration class or by using a script that runs in the session. The configuration can determine the commands that are available in the session. And, the configuration can include settings that protect the computer, such as settings that limit the amount of data that the session can receive remotely in a single object or command. You can also specify a security descriptor that determines the permissions that are required to use the configuration. - -The Enable-PSRemoting cmdlet creates the default session configurations on your computer: Microsoft.PowerShell, Microsoft.PowerShell.Workflow, and Microsoft.PowerShell32 (64-bit operating systems only). Enable-PSRemoting sets the security descriptor for the configuration to allow only members of the Administrators group on your computer to use them. - -You can use the session configuration cmdlets to edit the default session configurations, to create new session configurations, and to change the security descriptors of all the session configurations. -Beginning in Windows PowerShell 3.0, the New-PSSessionConfigurationFile cmdlet lets you create custom session configurations by using a text file. The file includes options for setting the language mode and for specifying the cmdlets and modules that are available in sessions that use the session configuration. - -When users use the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets, they can use the ConfigurationName parameter to indicate the session configuration that is used for the session. And, they can change the default configuration that their sessions use by changing the value of the $PSSessionConfigurationName preference variable in the session. - -For more information about session configurations, see the Help for the session configuration cmdlets. To find the session configuration cmdlets, type: - - -``` +Yes. Every remote session must use one of the session configurations on the +remote computer. You can manage the session configurations on your computer +(and the permissions to those session configurations) to determine who can run +commands remotely on your computer and which commands they can run. + +A session configuration configures the environment for the session. You can +define the configuration by using an assembly that implements a new +configuration class or by using a script that runs in the session. The +configuration can determine the commands that are available in the session. +And, the configuration can include settings that protect the computer, such as +settings that limit the amount of data that the session can receive remotely +in a single object or command. You can also specify a security descriptor that +determines the permissions that are required to use the configuration. + +The Enable-PSRemoting cmdlet creates the default session configurations on +your computer: Microsoft.PowerShell, Microsoft.PowerShell.Workflow, and +Microsoft.PowerShell32 (64-bit operating systems only). Enable-PSRemoting sets +the security descriptor for the configuration to allow only members of the +Administrators group on your computer to use them. + +You can use the session configuration cmdlets to edit the default session +configurations, to create new session configurations, and to change the +security descriptors of all the session configurations. + +Beginning in Windows PowerShell 3.0, the New-PSSessionConfigurationFile cmdlet +lets you create custom session configurations by using a text file. The file +includes options for setting the language mode and for specifying the cmdlets +and modules that are available in sessions that use the session configuration. + +When users use the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets, +they can use the ConfigurationName parameter to indicate the session +configuration that is used for the session. And, they can change the default +configuration that their sessions use by changing the value of the +$PSSessionConfigurationName preference variable in the session. + +For more information about session configurations, see the Help for the +session configuration cmdlets. To find the session configuration cmdlets, +type: + +```powershell Get-Command *PSSessionConfiguration ``` - - ### WHAT ARE FAN-IN AND FAN OUT CONFIGURATIONS? -The most common Windows PowerShell remoting scenario involving multiple computers is the one-to-many configuration, in which one local computer (the administrator's computer) runs Windows PowerShell commands on numerous remote computers. This is known as the "fan-out" scenario. -However, in some enterprises, the configuration is many-to-one, where many client computers connect to a single remote computer that is running Windows PowerShell, such as a file server or a kiosk. This is known as the "fan-in" configuration. +The most common Windows PowerShell remoting scenario involving multiple +computers is the one-to-many configuration, in which one local computer (the +administrator's computer) runs Windows PowerShell commands on numerous remote +computers. This is known as the "fan-out" scenario. -Windows PowerShell remoting supports both fan-out and fan-in configurations. +However, in some enterprises, the configuration is many-to-one, where many +client computers connect to a single remote computer that is running Windows +PowerShell, such as a file server or a kiosk. This is known as the "fan-in" +configuration. -For the fan-out configuration, Windows PowerShell uses the Web Services for Management (WS-Management) protocol and the WinRM service that supports the Microsoft implementation of WS-Management. When a local computer connects to a remote computer, WS-Management establishes a connection and uses a plug-in for Windows PowerShell to start the Windows PowerShell host process (Wsmprovhost.exe) on the remote computer. The user can specify an alternate port, an alternate session configuration, and other features to customize the remote connection. +Windows PowerShell remoting supports both fan-out and fan-in configurations. -To support the "fan-in" configuration, Windows PowerShell uses Internet Information Services (IIS) to host WS-Management, to load the Windows PowerShell plug-in, and to start Windows PowerShell. In this scenario, instead of starting each Windows PowerShell session in a separate process, all Windows PowerShell sessions run in the same host process. +For the fan-out configuration, Windows PowerShell uses the Web Services for +Management (WS-Management) protocol and the WinRM service that supports the +Microsoft implementation of WS-Management. When a local computer connects to a +remote computer, WS-Management establishes a connection and uses a plug-in for +Windows PowerShell to start the Windows PowerShell host process +(Wsmprovhost.exe) on the remote computer. The user can specify an alternate +port, an alternate session configuration, and other features to customize the +remote connection. -IIS hosting and fan-in remote management is not supported in Windows XP or in Windows Server 2003. +To support the "fan-in" configuration, Windows PowerShell uses Internet +Information Services (IIS) to host WS-Management, to load the Windows +PowerShell plug-in, and to start Windows PowerShell. In this scenario, instead +of starting each Windows PowerShell session in a separate process, all Windows +PowerShell sessions run in the same host process. -In a fan-in configuration, the user can specify a connection URI and an HTTP endpoint, including the transport, computer name, port, and application name. IIS forwards all the requests with a specified application name to the application. The default is WS-Management, which can host Windows PowerShell. +IIS hosting and fan-in remote management is not supported in Windows XP or in +Windows Server 2003. -You can also specify an authentication mechanism and prohibit or allow redirection from HTTP and HTTPS endpoints. +In a fan-in configuration, the user can specify a connection URI and an HTTP +endpoint, including the transport, computer name, port, and application name. +IIS forwards all the requests with a specified application name to the +application. The default is WS-Management, which can host Windows PowerShell. +You can also specify an authentication mechanism and prohibit or allow +redirection from HTTP and HTTPS endpoints. ### CAN I TEST REMOTING ON A SINGLE COMPUTER \(NOT IN A DOMAIN\)? -Yes. Windows PowerShell remoting is available even when the local computer is not in a domain. You can use the remoting features to connect to sessions and to create sessions on the same computer. The features work the same as they do when you connect to a remote computer. -To run remote commands on a computer in a workgroup, change the following Windows settings on the computer. +Yes. Windows PowerShell remoting is available even when the local computer is +not in a domain. You can use the remoting features to connect to sessions and +to create sessions on the same computer. The features work the same as they do +when you connect to a remote computer. -Caution: These settings affect all users on the system and they can make the system more vulnerable to a malicious attack. Use caution when making these changes. +To run remote commands on a computer in a workgroup, change the following +Windows settings on the computer. --- Windows XP with SP2: +Caution: These settings affect all users on the system and they can make the +system more vulnerable to a malicious attack. Use caution when making these +changes. -Use Local Security Settings (Secpol.msc) to change the setting of the "Network Access: Sharing and security model for local accounts" policy in Security Settings\Local Policies\Security Options to "Classic". +- Windows XP with SP2: --- Windows Vista, Windows 7, Windows 8: + Use Local Security Settings (Secpol.msc) to change the setting of the + "Network Access: Sharing and security model for local accounts" policy in + Security Settings\Local Policies\Security Options to "Classic". -Create the following registry entry, and then set its value to 1: LocalAccountTokenFilterPolicy in HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System +- Windows Vista, Windows 7, Windows 8: -You can use the following Windows PowerShell command to add this entry: + Create the following registry entry, and then set its value to 1: + LocalAccountTokenFilterPolicy in + HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System -New-ItemProperty ` -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System ` -Name LocalAccountTokenFilterPolicy -propertyType DWord -Value 1 + You can use the following Windows PowerShell command to add this entry: --- Windows Server 2003, Windows Server 2008, Windows Server 2012, Windows Server 2012 R2: + ```powershell + $parameters = @{ + Path='HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System' + Name='LocalAccountTokenFilterPolicy' + propertyType='DWord' + Value=1 + } + New-ItemProperty @parameters + ``` -No changes are needed because the default setting of the "Network Access: Sharing and security model for local accounts" policy is "Classic". Verify the setting in case it has changed. +- Windows Server 2003, Windows Server 2008, Windows Server 2012, Windows + Server 2012 R2: + No changes are needed because the default setting of the "Network Access: + Sharing and security model for local accounts" policy is "Classic". Verify + the setting in case it has changed. ### CAN I RUN REMOTE COMMANDS ON A COMPUTER IN ANOTHER DOMAIN? -Yes. Typically, the commands run without error, although you might need to use the Credential parameter of the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets to provide the credentials of a member of the Administrators group on the remote computer. This is sometimes required even when the current user is a member of the Administrators group on the local and remote computers. -However, if the remote computer is not in a domain that the local computer trusts, the remote computer might not be able to authenticate the user's credentials. +Yes. Typically, the commands run without error, although you might need to use +the **Credential** parameter of the `Invoke-Command`, `New-PSSession`, or +`Enter-PSSession` cmdlets to provide the credentials of a member of the +Administrators group on the remote computer. This is sometimes required even +when the current user is a member of the Administrators group on the local and +remote computers. -To enable authentication, use the following command to add the remote computer to the list of trusted hosts for the local computer in WinRM. Type the command at the Windows PowerShell prompt. +However, if the remote computer is not in a domain that the local computer +trusts, the remote computer might not be able to authenticate the user's +credentials. +To enable authentication, use the following command to add the remote computer +to the list of trusted hosts for the local computer in WinRM. Type the command +at the Windows PowerShell prompt. -``` +```powershell Set-Item WSMan:\localhost\Client\TrustedHosts -Value ``` +For example, to add the Server01 computer to the list of trusted hosts on the +local computer, type the following command at the Windows PowerShell prompt: -For example, to add the Server01 computer to the list of trusted hosts on the local computer, type the following command at the Windows PowerShell prompt: - - -``` +```powershell Set-Item WSMan:\localhost\Client\TrustedHosts -Value Server01 ``` - - ## SEE ALSO [about_Remote](about_Remote.md) @@ -357,7 +525,7 @@ Set-Item WSMan:\localhost\Client\TrustedHosts -Value Server01 [about_Remote_Variables](about_Remote_Variables.md) -Invoke-Command +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[New-PSSession](../New-PSSession.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md index ea1d750215a..91f9354775f 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,272 +7,338 @@ title: about_Remote_Jobs --- # About Remote Jobs -## about_Remote_Jobs - ## SHORT DESCRIPTION -Describes how to run background jobs on remote computers. +Describes how to run background jobs on remote computers. ## DETAILED DESCRIPTION -A background job is a command that runs asynchronously without interacting with the current session. The command prompt returns immediately, and you can continue to use the session while the job runs. -By default, background jobs run on the local computer. However, you can use several different procedures to run background jobs on remote computers. +A background job is a command that runs asynchronously without interacting +with the current session. The command prompt returns immediately, and you can +continue to use the session while the job runs. -This topic explains how to run a background job on a remote computer. For information about how to run background jobs on a local computer, see about_Jobs. For more information about background jobs, see about_Job_Details. +By default, background jobs run on the local computer. However, you can use +several different procedures to run background jobs on remote computers. +This topic explains how to run a background job on a remote computer. For +information about how to run background jobs on a local computer, see +[about_Jobs](about_Jobs.md). For more information about background jobs, see +[about_Job_Details](about_Job_Details.md). ## REMOTE BACKGROUND JOBS -You can run background jobs on remote computers by using three different methods. --- Start an interactive session with a remote computer, and start a job in the interactive session. The procedures are the same as running a local job, although all actions are performed on the remote computer. +You can run background jobs on remote computers by using three different +methods. --- Run a background job on a remote computer that returns its results to the local computer. Use this method when you want to collect the results of background jobs and maintain them in a central location on the local computer. +- Start an interactive session with a remote computer, and start a job in the + interactive session. The procedures are the same as running a local job, + although all actions are performed on the remote computer. --- Run a background job on a remote computer that maintains its results on the remote computer. Use this method when the job data is more securely maintained on the originating computer. +- Run a background job on a remote computer that returns its results to the + local computer. Use this method when you want to collect the results of + background jobs and maintain them in a central location on the local computer. +- Run a background job on a remote computer that maintains its results on the + remote computer. Use this method when the job data is more securely maintained + on the originating computer. ### START A BACKGROUND JOB IN AN INTERACTIVE SESSION -You can start an interactive session with a remote computer and then start a background job during the interactive session. For more information about interactive sessions, see about_Remote, and see Enter-PSSession. -The procedure for starting a background job in an interactive session is almost identical to the procedure for starting a background job on the local computer. However, all of the operations occur on the remote computer, not the local computer. +You can start an interactive session with a remote computer and then start a +background job during the interactive session. For more information about +interactive sessions, see about_Remote, and see Enter-PSSession. +The procedure for starting a background job in an interactive session is +almost identical to the procedure for starting a background job on the local +computer. However, all of the operations occur on the remote computer, not the +local computer. #### STEP 1: ENTER-PSSESSION -Use the Enter-PSSession cmdlet to start an interactive session with a remote computer. You can use the ComputerName parameter of Enter-PSSession to establish a temporary connection for the interactive session. Or, you can use the Session parameter to run the interactive session in a Windows PowerShell session (PSSession). -The following command starts an interactive session on the Server01 computer. +Use the Enter-PSSession cmdlet to start an interactive session with a remote +computer. You can use the ComputerName parameter of Enter-PSSession to +establish a temporary connection for the interactive session. Or, you can use +the Session parameter to run the interactive session in a Windows PowerShell +session (PSSession). +The following command starts an interactive session on the Server01 computer. -``` +```powershell C:\PS> Enter-PSSession -computername Server01 ``` - -The command prompt changes to show that you are now connected to the Server01 computer. - +The command prompt changes to show that you are now connected to the Server01 +computer. ``` Server01\C:> ``` - - #### STEP 2: START-JOB -To start a background job in the session, use the Start-Job cmdlet. -The following command runs a background job that gets the events in the Windows PowerShell event log on the Server01 computer. The Start-Job cmdlet returns an object that represents the job. +To start a background job in the session, use the Start-Job cmdlet. -This command saves the job object in the $job variable. +The following command runs a background job that gets the events in the +Windows PowerShell event log on the Server01 computer. The Start-Job cmdlet +returns an object that represents the job. +This command saves the job object in the \$job variable. -``` -Server01\C:> $job = start-job -scriptblock {get-eventlog "Windows PowerShell"} +```powershell +Server01\C:> $job = start-job -scriptblock { + get-eventlog "Windows PowerShell" +} ``` - -While the job runs, you can use the interactive session to run other commands, including other background jobs. However, you must keep the interactive session open until the job is completed. If you end the session, the job is interrupted, and the results are lost. - +While the job runs, you can use the interactive session to run other commands, +including other background jobs. However, you must keep the interactive +session open until the job is completed. If you end the session, the job is +interrupted, and the results are lost. #### STEP 3: GET-JOB -To find out if the job is complete, display the value of the $job variable, or use the Get-Job cmdlet to get the job. The following command uses the Get-Job cmdlet to display the job. +To find out if the job is complete, display the value of the \$job variable, +or use the Get-Job cmdlet to get the job. The following command uses the +Get-Job cmdlet to display the job. -``` -Server01\C:> get-job $job - -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Complete True localhost get-eventlog "Windows PowerShell" -``` - +```powershell +Server01\C:> get-job $job -The Get-Job output shows that job is running on the "localhost" computer because the job was started on and is running on the same computer (in this case, Server01). +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Complete True localhost get-eventlog "Windows... +``` +The Get-Job output shows that job is running on the "localhost" computer +because the job was started on and is running on the same computer (in this +case, Server01). #### STEP 4: RECEIVE-JOB -To get the results of the job, use the Receive-Job cmdlet. You can display the results in the interactive session or save them to a file on the remote computer. The following command gets the results of the job in the $job variable. The command uses the redirection operator (>) to save the results of the job in the PsLog.txt file on the Server01 computer. +To get the results of the job, use the Receive-Job cmdlet. You can display the +results in the interactive session or save them to a file on the remote +computer. The following command gets the results of the job in the $job +variable. The command uses the redirection operator (>) to save the results of +the job in the PsLog.txt file on the Server01 computer. -``` +```powershell Server01\C:> receive-job $job > c:\logs\PsLog.txt ``` - - #### STEP 5: EXIT-PSSESSION -To end the interactive session, use the Exit-PSSession cmdlet. The command prompt changes to show that you are back in the original session on the local computer. +To end the interactive session, use the Exit-PSSession cmdlet. The command +prompt changes to show that you are back in the original session on the local +computer. -``` -Server01\C:> Exit-PSSession +```powershell +Server01\C:> Exit-PSSession C:\PS> ``` - - #### STEP 6: INVOKE-COMMAND: GET-CONTENT -To view the contents of the PsLog.txt file on the Server01 computer at any time, start another interactive session, or run a remote command. This type of command is best run in a PSSession (a persistent connection) in case you want to use several commands to investigate and manage the data in the PsLog.txt file. For more information about PSSessions, see about_PSSessions. -The following commands use the New-PSSession cmdlet to create a PSSession that is connected to the Server01 computer, and they use the Invoke-Command cmdlet to run a Get-Content command in the PSSession to view the contents of the file. +To view the contents of the PsLog.txt file on the Server01 computer at any +time, start another interactive session, or run a remote command. This type of +command is best run in a PSSession (a persistent connection) in case you want +to use several commands to investigate and manage the data in the PsLog.txt +file. For more information about PSSessions, see about_PSSessions. +The following commands use the New-PSSession cmdlet to create a PSSession that +is connected to the Server01 computer, and they use the Invoke-Command cmdlet +to run a Get-Content command in the PSSession to view the contents of the +file. +```powershell +$s = new-pssession -computername Server01 +invoke-command -session $s -scriptblock { + get-content c:\logs\pslog.txt} ``` -C:\PS> $s = new-pssession -computername Server01 -C:\PS> invoke-command -session $s -scriptblock {get-content c:\logs\pslog.txt} -``` - - ### START A REMOTE JOB THAT RETURNS THE RESULTS TO THE LOCAL COMPUTER \(ASJOB\) -To start a background job on a remote computer that returns the command results to the local computer, use the AsJob parameter of a cmdlet such as the Invoke-Command cmdlet. -When you use the AsJob parameter, the job object is actually created on the local computer even though the job runs on the remote computer. When the job is completed, the results are returned to the local computer. +To start a background job on a remote computer that returns the command +results to the local computer, use the AsJob parameter of a cmdlet such as the +Invoke-Command cmdlet. -You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage any job created by any cmdlet. Many of the cmdlets that have AsJob parameters do not use Windows PowerShell remoting, so you can use them even on computers that are not configured for remoting and that do not meet the requirements for remoting. +When you use the AsJob parameter, the job object is actually created on the +local computer even though the job runs on the remote computer. When the job +is completed, the results are returned to the local computer. +You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage +any job created by any cmdlet. Many of the cmdlets that have AsJob parameters +do not use Windows PowerShell remoting, so you can use them even on computers +that are not configured for remoting and that do not meet the requirements for +remoting. #### STEP 1: INVOKE-COMMAND -ASJOB -The following command uses the AsJob parameter of Invoke-Command to start a background job on the Server01 computer. The job runs a Get-Eventlog command that gets the events in the System log. You can use the JobName parameter to assign a display name to the job. +The following command uses the AsJob parameter of Invoke-Command to start a +background job on the Server01 computer. The job runs a Get-Eventlog command +that gets the events in the System log. You can use the JobName parameter to +assign a display name to the job. -``` -invoke-command -computername Server01 -scriptblock {get-eventlog system} -asjob +```powershell +invoke-command -computername Server01 -scriptblock { + get-eventlog system} -asjob ``` - The results of the command resemble the following sample output. - +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Running True Server01 get-eventlog system ``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Running True Server01 get-eventlog system -``` - -When the AsJob parameter is used, Invoke-Command returns the same type of job object that Start-Job returns. You can save the job object in a variable, or you can use a Get-Job command to get the job. - -Note that the value of the Location property shows that the job ran on the Server01 computer. +When the AsJob parameter is used, Invoke-Command returns the same type of job +object that Start-Job returns. You can save the job object in a variable, or +you can use a Get-Job command to get the job. +Note that the value of the Location property shows that the job ran on the +Server01 computer. #### STEP 2: GET-JOB -To manage a job started by using the AsJob parameter of the Invoke-Command cmdlet, use the Job cmdlets. Because the job object that represents the remote job is on the local computer, you do not need to run remote commands to manage the job. -To determine whether the job is complete, use a Get-Job command. The following command gets all of the jobs that were started in the current session. +To manage a job started by using the AsJob parameter of the Invoke-Command +cmdlet, use the Job cmdlets. Because the job object that represents the remote +job is on the local computer, you do not need to run remote commands to manage +the job. +To determine whether the job is complete, use a Get-Job command. The following +command gets all of the jobs that were started in the current session. -``` +```powershell get-job ``` +Because the remote job was started in the current session, a local Get-Job +command gets the job. The State property of the job object shows that the +command was completed successfully. -Because the remote job was started in the current session, a local Get-Job command gets the job. The State property of the job object shows that the command was completed successfully. - - -``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Completed True Server01 get-eventlog system +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Completed True Server01 get-eventlog system ``` - - #### STEP 3: RECEIVE-JOB -To get the results of the job, use the Receive-Job cmdlet. Because the job results are automatically returned to the computer where the job object resides, you can get the results with a local Receive-Job command. -The following command uses the Receive-Job cmdlet to get the results of the job. It uses the session ID to identify the job. This command saves the job results in the $results variable. You can also redirect the results to a file. +To get the results of the job, use the Receive-Job cmdlet. Because the job +results are automatically returned to the computer where the job object +resides, you can get the results with a local Receive-Job command. +The following command uses the Receive-Job cmdlet to get the results of the +job. It uses the session ID to identify the job. This command saves the job +results in the $results variable. You can also redirect the results to a file. -``` +```powershell $results = receive-job -id 1 ``` - - ### START A REMOTE JOB THAT KEEPS THE RESULTS ON THE REMOTE COMPUTER -To start a background job on a remote computer that keeps the command results on the remote computer, use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. You can use this method to run background jobs on multiple computers. -When you run a Start-Job command remotely, the job object is created on the remote computer, and the job results are maintained on the remote computer. From the perspective of the job, all operations are local. You are just running commands remotely to manage a local job on the remote computer. +To start a background job on a remote computer that keeps the command results +on the remote computer, use the Invoke-Command cmdlet to run a Start-Job +command on a remote computer. You can use this method to run background jobs +on multiple computers. +When you run a Start-Job command remotely, the job object is created on the +remote computer, and the job results are maintained on the remote computer. +From the perspective of the job, all operations are local. You are just +running commands remotely to manage a local job on the remote computer. #### STEP 1: INVOKE-COMMAND START-JOB -Use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. -This command requires a PSSession (a persistent connection). If you use the ComputerName parameter of Invoke-Command to establish a temporary connection, the Invoke-Command command is considered to be complete when the job object is returned. As a result, the temporary connection is closed, and the job is canceled. +Use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. -The following command uses the New-PSSession cmdlet to create a PSSession that is connected to the Server01 computer. The command saves the PSSession in the $s variable +This command requires a PSSession (a persistent connection). If you use the +ComputerName parameter of Invoke-Command to establish a temporary connection, +the Invoke-Command command is considered to be complete when the job object is +returned. As a result, the temporary connection is closed, and the job is +canceled. +The following command uses the New-PSSession cmdlet to create a PSSession that +is connected to the Server01 computer. The command saves the PSSession in the +\$s variable. -``` +```powershell $s = new-pssession -computername Server01 ``` +The next command uses the Invoke-Command cmdlet to run a Start-Job command in +the PSSession. The Start-Job command and the Get-Eventlog command are enclosed +in braces. -The next command uses the Invoke-Command cmdlet to run a Start-Job command in the PSSession. The Start-Job command and the Get-Eventlog command are enclosed in braces. - - +```powershell +invoke-command -session $s -scriptblock { + start-job -scriptblock {get-eventlog system}} ``` -invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog system}} -``` - The results resemble the following sample output. - -``` -Id Name State HasMoreData Location Command --- ---- ----- ----------- -------- ------- +```Output +Id Name State HasMoreData Location Command +-- ---- ----- ----------- -------- ------- 2 Job2 Running True Localhost get-eventlog system ``` +When you run a Start-Job command remotely, Invoke-Command returns the same +type of job object that Start-Job returns. You can save the job object in a +variable, or you can use a Get-Job command to get the job. -When you run a Start-Job command remotely, Invoke-Command returns the same type of job object that Start-Job returns. You can save the job object in a variable, or you can use a Get-Job command to get the job. - -Note that the value of the Location property shows that the job ran on the local computer, known as "LocalHost", even though the job ran on the Server01 computer. Because the job object is created on the Server01 computer and the job runs on the same computer, it is considered to be a local background job. - +Note that the value of the Location property shows that the job ran on the +local computer, known as "LocalHost", even though the job ran on the Server01 +computer. Because the job object is created on the Server01 computer and the +job runs on the same computer, it is considered to be a local background job. #### STEP 2: INVOKE-COMMAND GET-JOB -To manage a remote background job, use the Job cmdlets. Because the job object is on the remote computer, you need to run remote commands to get, stop, wait for, or retrieve the job results. -To see if the job is complete, use an Invoke-Command command to run a Get-Job command in the PSSession that is connected to the Server01 computer. +To manage a remote background job, use the Job cmdlets. Because the job object +is on the remote computer, you need to run remote commands to get, stop, wait +for, or retrieve the job results. +To see if the job is complete, use an Invoke-Command command to run a Get-Job +command in the PSSession that is connected to the Server01 computer. -``` +```powershell invoke-command -session $s -scriptblock {get-job} ``` +The command returns a job object. The State property of the job object shows +that the command was completed successfully. -The command returns a job object. The State property of the job object shows that the command was completed successfully. - - +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +2 Job2 Completed True LocalHost get-eventlog system ``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -2 Job2 Completed True LocalHost get-eventlog system -``` - - #### STEP 3: INVOKE-COMMAND RECEIVE-JOB -To get the results of the job, use the Invoke-Command cmdlet to run a Receive-Job command in the PSSession that is connected to the Server01 computer. -The following command uses the Receive-Job cmdlet to get the results of the job. It uses the session ID to identify the job. This command saves the job results in the $results variable. It uses the Keep parameter of Receive-Job to keep the result in the job cache on the remote computer. +To get the results of the job, use the Invoke-Command cmdlet to run a +Receive-Job command in the PSSession that is connected to the Server01 +computer. +The following command uses the Receive-Job cmdlet to get the results of the +job. It uses the session ID to identify the job. This command saves the job +results in the \$results variable. It uses the Keep parameter of Receive-Job +to keep the result in the job cache on the remote computer. +```powershell +$results = invoke-command -session $s -scriptblock { + receive-job -sessionid 2 -keep} ``` -$results = invoke-command -session $s -scriptblock {receive-job -sessionid 2 -keep} -``` - - -You can also redirect the results to a file on the local or remote computer. The following command uses a redirection operator to save the results in a file on the Server01 computer. +You can also redirect the results to a file on the local or remote computer. +The following command uses a redirection operator to save the results in a +file on the Server01 computer. +```powershell +invoke-command -session $s -command { + receive-job -sessionid 2 > c:\logs\pslog.txt} ``` -invoke-command -session $s -command {receive-job -sessionid 2 > c:\logs\pslog.txt} -``` - - ## SEE ALSO @@ -284,21 +350,20 @@ invoke-command -session $s -command {receive-job -sessionid 2 > c:\logs\pslog.tx [about_Remote_Variables](about_Remote_Variables.md) -Invoke-Command - -Start-Job +[Invoke-Command](../Invoke-Command.md) -Get-Job +[Start-Job](../Start-Job.md) -Wait-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Wait-Job](../Wait-Job.md) -Remove-Job +[Stop-Job](../Stop-Job.md) -New-PSSession +[Remove-Job](../Remove-Job.md) -Enter-PSSession +[New-PSSession](../New-PSSession.md) -Exit-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[Exit-PSSession](../Exit-PSSession.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Properties.md b/reference/6/Microsoft.PowerShell.Core/About/about_Properties.md index 2cdbdf69230..f9bea619992 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Properties.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Properties.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,278 +7,304 @@ title: about_Properties --- # About Properties -## about_Properties - ## SHORT DESCRIPTION -Describes how to use object properties in Windows PowerShell. +Describes how to use object properties in PowerShell. ## LONG DESCRIPTION -Windows PowerShell uses structured collections of information called objects to represent the items in data stores or the state of the computer. Typically, you work with object that are part of the Microsoft .NET Framework, but you can also create custom objects in Windows PowerShell. -The association between an item and its object is very close. When you change an object, you usually change the item that it represents. For example, when you get a file in Windows PowerShell, you do not get the actual file. Instead, you get a FileInfo object that represents the file. When you change the FileInfo object, the file changes too. +PowerShell uses structured collections of information called objects to +represent the items in data stores or the state of the computer. Typically, +you work with object that are part of the Microsoft .NET Framework, but you +can also create custom objects in PowerShell. -Most objects have properties. Properties are the data that is associated with an object. Different types of object have different properties. For example, a FileInfo object, which represents a file, has an IsReadOnly property that contains $True if the file the read-only attribute and $False if it does not. A DirectoryInfo object, which represents a file system directory, has a Parent property that contains the path to the parent directory. +The association between an item and its object is very close. When you change +an object, you usually change the item that it represents. For example, when +you get a file in PowerShell, you do not get the actual file. Instead, you get +a FileInfo object that represents the file. When you change the FileInfo +object, the file changes too. +Most objects have properties. Properties are the data that is associated with +an object. Different types of object have different properties. For example, a +FileInfo object, which represents a file, has an **IsReadOnly** property that +contains $True if the file the read-only attribute and $False if it does not. +A DirectoryInfo object, which represents a file system directory, has a Parent +property that contains the path to the parent directory. ### OBJECT PROPERTIES -To get the properties of an object, use the Get-Member cmdlet. For example, to get the properties of a FileInfo object, use the Get-ChildItem cmdlet to get the FileInfo object that represents a file. Then, use a pipeline operator (|) to send the FileInfo object to Get-Member. The following command gets the PowerShell.exe file and sends it to Get-Member. The $Pshome automatic variable contains the path of the Windows PowerShell installation directory. +To get the properties of an object, use the `Get-Member` cmdlet. For example, +to get the properties of a **FileInfo** object, use the `Get-ChildItem` cmdlet +to get the FileInfo object that represents a file. Then, use a pipeline +operator (|) to send the **FileInfo** object to `Get-Member`. The +following command gets the PowerShell.exe file and sends it to `Get-Member`. +The \$Pshome automatic variable contains the path of the PowerShell +installation directory. -``` +```powershell Get-ChildItem $pshome\PowerShell.exe | Get-Member ``` +The output of the command lists the members of the **FileInfo** object. +Members include both properties and methods. When you work in PowerShell, you +have access to all the members of the objects. -The output of the command lists the members of the FileInfo object. Members include both properties and methods. When you work in Windows PowerShell, you have access to all the members of the objects. - -To get only the properties of an object and not the methods, use the MemberType parameter of the Get-Member cmdlet with a value of "property", as shown in the following example. - +To get only the properties of an object and not the methods, use the +MemberType parameter of the `Get-Member` cmdlet with a value of "property", as +shown in the following example. -``` +```powershell Get-ChildItem $pshome\PowerShell.exe | Get-Member -MemberType property ``` - - -``` -TypeName: System.IO.FileInfo - -Name MemberType Definition ----- ---------- ---------- -Attributes Property System.IO.FileAttributes Attributes {get;set;} -CreationTime Property System.DateTime CreationTime {get;set;} -CreationTimeUtc Property System.DateTime CreationTimeUtc {get;set;} -Directory Property System.IO.DirectoryInfo Directory {get;} -DirectoryName Property System.String DirectoryName {get;} -Exists Property System.Boolean Exists {get;} -Extension Property System.String Extension {get;} -FullName Property System.String FullName {get;} -IsReadOnly Property System.Boolean IsReadOnly {get;set;} -LastAccessTime Property System.DateTime LastAccessTime {get;set;} -LastAccessTimeUtc Property System.DateTime LastAccessTimeUtc {get;set;} -LastWriteTime Property System.DateTime LastWriteTime {get;set;} -LastWriteTimeUtc Property System.DateTime LastWriteTimeUtc {get;set;} -Length Property System.Int64 Length {get;} +```Output +TypeName: System.IO.FileInfo + +Name MemberType Definition +---- ---------- ---------- +Attributes Property System.IO.FileAttributes Attributes {get;set;} +CreationTime Property System.DateTime CreationTime {get;set;} +CreationTimeUtc Property System.DateTime CreationTimeUtc {get;set;} +Directory Property System.IO.DirectoryInfo Directory {get;} +DirectoryName Property System.String DirectoryName {get;} +Exists Property System.Boolean Exists {get;} +Extension Property System.String Extension {get;} +FullName Property System.String FullName {get;} +IsReadOnly Property System.Boolean IsReadOnly {get;set;} +LastAccessTime Property System.DateTime LastAccessTime {get;set;} +LastAccessTimeUtc Property System.DateTime LastAccessTimeUtc {get;set;} +LastWriteTime Property System.DateTime LastWriteTime {get;set;} +LastWriteTimeUtc Property System.DateTime LastWriteTimeUtc {get;set;} +Length Property System.Int64 Length {get;} Name Property System.String Name {get;} ``` - -After you find the properties, you can use them in your Windows PowerShell commands. - +After you find the properties, you can use them in your PowerShell commands. ## PROPERTY VALUES -Although every object of a specific type has the same properties, the values of those properties describe the particular object. For example, every FileInfo object has a CreationTime property, but the value of that property differs for each file. - -The most common way to get the values of the properties of an object is to use the dot method. Type a reference to the object, such as a variable that contains the object, or a command that gets the object. Then, type a dot (.) followed by the property name. - -For example, the following command displays the value of the CreationTime property of the PowerShell.exe file. The Get-ChildItem command returns a FileInfo object that represents the PowerShell.exe file. The command is enclosed in parentheses to make sure that it is executed before any properties are accessed. The Get-ChildItem command is followed by a dot and the name of the CreationTime property, as follows: - -``` -C:\PS> (Get-ChildItem $pshome\PowerShell.exe).creationtime +Although every object of a specific type has the same properties, the values +of those properties describe the particular object. For example, every +FileInfo object has a CreationTime property, but the value of that property +differs for each file. + +The most common way to get the values of the properties of an object is to use +the dot method. Type a reference to the object, such as a variable that +contains the object, or a command that gets the object. Then, type a dot (.) +followed by the property name. + +For example, the following command displays the value of the CreationTime +property of the PowerShell.exe file. The `Get-ChildItem` command returns a +FileInfo object that represents the PowerShell.exe file. The command is +enclosed in parentheses to make sure that it is executed before any properties +are accessed. The `Get-ChildItem` command is followed by a dot and the name of +the CreationTime property, as follows: + +```powershell +C:\PS> (Get-ChildItem $pshome\PowerShell.exe).creationtime Tuesday, March 18, 2008 12:07:52 AM ``` +You can also save an object in a variable and then get its properties by using +the dot method, as shown in the following example: -You can also save an object in a variable and then get its properties by using the dot method, as shown in the following example: - - -``` -C:\PS> $a = Get-ChildItem $pshome\PowerShell.exe -C:\PS> $a.CreationTime +```powershell +C:\PS> $a = Get-ChildItem $pshome\PowerShell.exe +C:\PS> $a.CreationTime Tuesday, March 18, 2008 12:07:52 AM ``` +You can also use the `Select-Object` and `Format-List` cmdlets to display the +property values of an object. `Select-Object` and `Format-List` each have a +**Property** parameter. You can use the **Property** parameter to specify one +or more properties and their values. Or, you can use the wildcard character +(\*) to represent all the properties. -You can also use the Select-Object and Format-List cmdlets to display the property values of an object. Select-Object and Format-List each have a Property parameter. You can use the Property parameter to specify one or more properties and their values. Or, you can use the wildcard character (\*) to represent all the properties. - -For example, the following command displays the values of all the properties of the PowerShell.exe file. - +For example, the following command displays the values of all the properties +of the PowerShell.exe file. -``` +```powershell C:\PS> Get-ChildItem $pshome\PowerShell.exe | Format-List -property * ``` - - -``` -PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe -PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\system32\WindowsPowerShell\v1.0 -PSChildName : PowerShell.exe -PSDrive : C -PSProvider : Microsoft.PowerShell.Core\FileSystem -PSIsContainer : False -VersionInfo : File: C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe - InternalName: POWERSHELL - OriginalFilename: PowerShell.EXE.MUI - File Version: 6.1.6570.1 (fbl_srv_PowerShell(nigels).070711-0102) - FileDescription: PowerShell.EXE - Product: Microsoft® Windows® Operating System - ProductVersion: 6.1.6570.1 - Debug: False - Patched: False - PreRelease: False - PrivateBuild: True - SpecialBuild: False +```Output +PSPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\System3 + 2\WindowsPowerShell\v1.0\PowerShell.exe +PSParentPath : Microsoft.PowerShell.Core\FileSystem::C:\Windows\System3 + 2\WindowsPowerShell\v1.0 +PSChildName : PowerShell.exe +PSDrive : C +PSProvider : Microsoft.PowerShell.Core\FileSystem +PSIsContainer : False +Mode : -a---- +VersionInfo : File: C:\Windows\System32\WindowsPowerShell\ + v1.0\PowerShell.exe + InternalName: POWERSHELL + OriginalFilename: PowerShell.EXE.MUI + FileVersion: 10.0.16299.15 (WinBuild.160101.0800) + FileDescription: Windows PowerShell + Product: Microsoft® Windows® Operating System + ProductVersion: 10.0.16299.15 + Debug: False + Patched: False + PreRelease: False + PrivateBuild: False + SpecialBuild: False Language: English (United States) -``` - - -``` -BaseName : PowerShell -Mode : -a--- -Name : PowerShell.exe -Length : 160256 -DirectoryName : C:\Windows\system32\WindowsPowerShell\v1.0 -Directory : C:\Windows\system32\WindowsPowerShell\v1.0 -IsReadOnly : False -Exists : True -FullName : C:\Windows\system32\WindowsPowerShell\v1.0\PowerShell.exe -Extension : .exe -CreationTime : 3/18/2008 12:07:52 AM -CreationTimeUtc : 3/18/2008 7:07:52 AM -LastAccessTime : 3/19/2008 8:13:58 AM -LastAccessTimeUtc : 3/19/2008 3:13:58 PM -LastWriteTime : 3/18/2008 12:07:52 AM -LastWriteTimeUtc : 3/18/2008 7:07:52 AM +BaseName : PowerShell +Target : {C:\Windows\WinSxS\amd64_microsoft-windows-powershell-ex + e_31bf3856ad364e35_10.0.16299.15_none_8c022aa6735716ae\p + owershell.exe} +LinkType : HardLink +Name : PowerShell.exe +Length : 449024 +DirectoryName : C:\Windows\System32\WindowsPowerShell\v1.0 +Directory : C:\Windows\System32\WindowsPowerShell\v1.0 +IsReadOnly : False +Exists : True +FullName : C:\Windows\System32\WindowsPowerShell\v1.0\PowerShell.ex +Extension : .exe +CreationTime : 9/29/2017 6:43:19 AM +CreationTimeUtc : 9/29/2017 1:43:19 PM +LastAccessTime : 9/29/2017 6:43:19 AM +LastAccessTimeUtc : 9/29/2017 1:43:19 PM +LastWriteTime : 9/29/2017 6:43:19 AM +LastWriteTimeUtc : 9/29/2017 1:43:19 PM Attributes : Archive ``` - - ### STATIC PROPERTIES -You can use the static properties of .NET classes in Windows PowerShell. Static properties are properties of class, unlike standard properties, which are properties of an object. -To get the static properties of an class, use the Static parameter of the Get-Member cmdlet. +You can use the static properties of .NET classes in PowerShell. Static +properties are properties of class, unlike standard properties, which are +properties of an object. -For example, the following command gets the static properties of the System.DateTime class. +To get the static properties of an class, use the Static parameter of the +Get-Member cmdlet. +For example, the following command gets the static properties of the +`System.DateTime` class. -``` +```powershell Get-Date | Get-Member -MemberType Property -Static ``` +```Output +TypeName: System.DateTime - -``` -TypeName: System.DateTime - -Name MemberType Definition ----- ---------- ---------- -MaxValue Property static datetime MaxValue {get;} -MinValue Property static datetime MinValue {get;} -Now Property datetime Now {get;} -Today Property datetime Today {get;} +Name MemberType Definition +---- ---------- ---------- +MaxValue Property static datetime MaxValue {get;} +MinValue Property static datetime MinValue {get;} +Now Property datetime Now {get;} +Today Property datetime Today {get;} UtcNow Property datetime UtcNow {get;} ``` - To get the value of a static property, use the following syntax. - -``` +```powershell []:: ``` +For example, the following command gets the value of the UtcNow static +property of the `System.DateTime` class. -For example, the following command gets the value of the UtcNow static property of the System.DateTime class. - - -``` +```powershell [System.DateTime]::UtcNow ``` - - ### PROPERTIES OF SCALAR OBJECTS AND COLLECTIONS -The properties of one ("scalar") object of a particular type are often different from the properties of a collection of objects of the same type. -For example, every service has as DisplayName property, but a collection of services does not have a DisplayName property. Similarly, all collections have a Count property that tells how many objects are in the collection, but individual objects do not have a Count property. +The properties of one ("scalar") object of a particular type are often +different from the properties of a collection of objects of the same type. -Beginning in Windows PowerShell 3.0, Windows PowerShell tries to prevent scripting errors that result from the differing properties of scalar objects and collections. +For example, every service has as **DisplayName** property, but a collection +of services does not have a **DisplayName** property. Similarly, all +collections have a **Count** property that tells how many objects are in the +collection, but individual objects do not have a **Count** property. -If you submit a collection, but request a property that exists only on single ("scalar") objects, Windows PowerShell returns the value of that property for every object in the collection. +Beginning in PowerShell 3.0, PowerShell tries to prevent scripting errors that +result from the differing properties of scalar objects and collections. -If you request the Count or Length property of zero objects or of one object, Windows PowerShell returns the correct value. +If you submit a collection, but request a property that exists only on single +("scalar") objects, PowerShell returns the value of that property for every +object in the collection. -If the property exists on the individual objects and on the collection, Windows PowerShell does not alter the result. +If you request the Count or Length property of zero objects or of one object, +PowerShell returns the correct value. -This feature also works on methods of scalar objects and collections. For more information, see about_Methods. +If the property exists on the individual objects and on the collection, +PowerShell does not alter the result. +This feature also works on methods of scalar objects and collections. For more +information, see about_Methods. ### EXAMPLES -For example, each service has a DisplayName property. The following command gets the value of the DisplayName property of the Audiosrv service. +For example, each service has a DisplayName property. The following command +gets the value of the DisplayName property of the Audiosrv service. -``` -PS C:\> (Get-Service Audiosrv).DisplayName +```powershell +PS C:\> (Get-Service Audiosrv).DisplayName Windows Audio ``` +However, a collection or array of services does not have a **DisplayName**. +The following command tries to get the DisplayName property of all services in +PowerShell 2.0. -However, a collection or array of services does not have a DisplayName. The following command tries to get the DisplayName property of all services in Windows PowerShell 2.0. - - -``` -PS C:\> (Get-Service).DisplayName +```powershell +PS C:\> (Get-Service).DisplayName PS C:\> ``` +Beginning in PowerShell 3.0, the same command returns the value of the +**DisplayName** property of every service that `Get-Service` returns. -Beginning in Windows PowerShell 3.0, the same command returns the value of the DisplayName property of every service that Get-Service returns. - - -``` -PS C:\> (Get-Service).DisplayName -Application Experience -Application Layer Gateway Service -Windows All-User Install Agent -Application Identity -Application Information +```powershell +PS C:\> (Get-Service).DisplayName +Application Experience +Application Layer Gateway Service +Windows All-User Install Agent +Application Identity +Application Information ... ``` +Conversely, a collection of two or more services has a **Count** property, +which contains the number of objects in the collection. -Conversely, a collection of two or more services has a Count property, which contains the number of objects in the collection. - - -``` -PS C:\> (Get-Service).Count +```powershell +PS C:\> (Get-Service).Count 176 ``` +Individual services do not have a Count or Length property, as shown in this +command in PowerShell 2.0. -Individual services do not have a Count or Length property, as shown in this command in Windows PowerShell 2.0. - - -``` -PS C:\> (Get-Service Audiosrv).Count +```powershell +PS C:\> (Get-Service Audiosrv).Count PS C:\> ``` +Beginning in PowerShell 3.0, the command returns the correct Count value. -Beginning in Windows PowerShell 3.0, the command returns the correct Count value. - - -``` -PS C:\> (Get-Service Audiosrv).Count +```powershell +PS C:\> (Get-Service Audiosrv).Count 1 ``` - - ## SEE ALSO [about_Methods](about_Methods.md) [about_Objects](about_Objects.md) -Get-Member - -Select-Object +[Get-Member](../../Microsoft.PowerShell.Utility/Get-Member.md) -Format-List +[Select-Object](../../Microsoft.PowerShell.Utility/Select-Object.md) +[Format-List](../../Microsoft.PowerShell.Utility/Format-List.md) \ No newline at end of file diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/6/Microsoft.PowerShell.Core/About/about_Redirection.md index cd527f93dbd..21d289c7f6e 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -1,135 +1,145 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us -keywords: powershell,cmdlet +keywords: PowerShell,cmdlet title: about_Redirection --- # About Redirection -## about_Redirection - ## SHORT DESCRIPTION -Explains how to redirect output from Windows PowerShell to text files. +Explains how to redirect output from PowerShell to text files. ## LONG DESCRIPTION -By default, Windows PowerShell sends its command output to the Windows PowerShell console. However, you can direct the output to a text file, and you can redirect error output to the regular output stream. -You can use the following methods to redirect output: +By default, PowerShell sends its command output to the PowerShell console. +However, you can direct the output to a text file, and you can redirect error +output to the regular output stream. -- Use the Out-File cmdlet, which sends command output to a text file. Typically, you use the Out-File cmdlet when you need to use its parameters, such as the Encoding, Force, Width, or NoClobber parameters. +You can use the following methods to redirect output: -- Use the Tee-Object cmdlet, which sends command output to a text file and then sends it to the pipeline. +- Use the `Out-File` cmdlet, which sends command output to a text file. + Typically, you use the `Out-File` cmdlet when you need to use its parameters, + such as the **Encoding**, **Force**, **Width**, or **NoClobber** parameters. -- Use the Windows PowerShell redirection operators. +- Use the Tee-Object cmdlet, which sends command output to a text file and + then sends it to the pipeline. +- Use the PowerShell redirection operators. -### WINDOWS POWERSHELL REDIRECTION OPERATORS -The redirection operators enable you to send particular types of output to files and to the success output stream. +### POWERSHELL REDIRECTION OPERATORS -The Windows PowerShell redirection operators use the following characters to represent each output type: +The redirection operators enable you to send particular types of output to +files and to the success output stream. +The PowerShell redirection operators use the following characters to represent +each output type: ``` -* All output -1 Success output -2 Errors -3 Warning messages -4 Verbose output +* All output +1 Success output +2 Errors +3 Warning messages +4 Verbose output 5 Debug messages ``` +NOTE: The All (\*), Warning (3), Verbose (4) and Debug (5) redirection +operators were introduced in PowerShell 3.0. They do not work in earlier +versions of PowerShell. -NOTE: The All (\*), Warning (3), Verbose (4) and Debug (5) redirection operators were introduced in Windows PowerShell 3.0. They do not work in earlier versions of Windows PowerShell. +The PowerShell redirection operators are as follows. -The Windows PowerShell redirection operators are as follows. +``` +Operator Description Example +-------- ---------------------- ------------------------------ +> Sends output to the Get-Process > Process.txt + specified file. +>> Appends the output to dir *.ps1 >> Scripts.txt + the contents of the + specified file. -``` -Operator Description Example --------- ---------------------- ------------------------------ -> Sends output to the Get-Process > Process.txt - specified file. - ->> Appends the output to dir *.ps1 >> Scripts.txt - the contents of the - specified file. - -2> Sends errors to the Get-Process none 2> Errors.txt - specified file. - -2>> Appends errors to Get-Process none 2>> Save-Errors.txt - the contents of the - specified file. - -2>&1 Sends errors (2) and Get-Process none, Powershell 2>&1 - success output (1) - to the success - output stream. - -3> Sends warnings to the Write-Warning "Test!" 3> Warnings.txt - specified file. - -3>> Appends warnings to Write-Warning "Test!" 3>> Save-Warnings.txt - the contents of the - specified file. - -3>&1 Sends warnings (3) and function Test-Warning - success output (1) { Get-Process PowerShell; - to the success Write-Warning "Test!" } - output stream. Test-Warning 3>&1 - -4> Sends verbose output to Import-Module * -Verbose 4> Verbose.txt - the specified file. - -4>> Appends verbose output Import-Module * -Verbose 4>> Save-Verbose.txt - to the contents of the - specified file. - -4>&1 Sends verbose output (4) Import-Module * -Verbose 4>&1 - and success output (1) - to the success output - stream. - -5> Sends debug messages to Write-Debug "Starting" 5> Debug.txt - the specified file. - -5>> Appends debug messages Write-Debug "Saving" 5>> Save-Debug.txt - to the contents of the - specified file. - -5>&1 Sends debug messages (5) function Test-Debug - and success output (1) { Get-Process PowerShell - to the success output Write-Debug "PS" } - stream. Test-Debug 5>&1 - -*> Sends all output types function Test-Output - to the specified file. { Get-Process PowerShell, none - Write-Warning "Test!" -*>> Appends all output types Write-Verbose "Test Verbose" - to the contents of the Write-Debug "Test Debug" } - specified file. - Test-Output *> Test-Output.txt -*>&1 Sends all output types Test-Output *>> Test-Output.txt - (*) to the success output Test-Output *>&1 +2> Sends errors to the Get-Process none 2> Errors.txt + specified file. + +2>> Appends errors to Get-Process none 2>> Save-Errors.txt + the contents of the + specified file. + +2>&1 Sends errors (2) and Get-Process none, Powershell 2>&1 + success output (1) + to the success + output stream. + +3> Sends warnings to the Write-Warning "Test!" 3> Warnings.txt + specified file. + +3>> Appends warnings to Write-Warning "Test!" 3>> Warnings.txt + the contents of the + specified file. + +3>&1 Sends warnings (3) and function Test-Warning + success output (1) { Get-Process PowerShell; + to the success Write-Warning "Test!" } + output stream. Test-Warning 3>&1 + +4> Sends verbose output to Import-Module * -Verbose 4> Verbose.txt + the specified file. + +4>> Appends verbose output Import-Module * -Verbose 4>> Verbose.txt + to the contents of the + specified file. + +4>&1 Sends verbose output (4) Import-Module * -Verbose 4>&1 + and success output (1) + to the success output stream. -``` +5> Sends debug messages to Write-Debug "Starting" 5> Debug.txt + the specified file. + +5>> Appends debug messages Write-Debug "Saving" 5>> Debug.txt + to the contents of the + specified file. + +5>&1 Sends debug messages (5) function Test-Debug + and success output (1) { Get-Process PowerShell + to the success output Write-Debug "PS" } + stream. Test-Debug 5>&1 + +*> Sends all output types function Test-Output + to the specified file. { Get-Process PowerShell, none + Write-Warning "Test!" +*>> Appends all output types Write-Verbose "Test Verbose" + to the contents of the Write-Debug "Test Debug" } + specified file. + Test-Output *> Test-Output.txt +*>&1 Sends all output types Test-Output *>> Test-Output.txt + (*) to the success Test-Output *>&1 + output stream. +``` The syntax of the redirection operators is as follows: - ``` [\] ``` +If the specified file already exists, the redirection operators that do not +append data (> and n>) overwrite the current contents of the file without +warning. However, if the file is a read-only, hidden, or system file, the +redirection fails. The append redirection operators (>> and n>>) do not write +to a read-only file, but they append content to a system or hidden file. -If the specified file already exists, the redirection operators that do not append data (> and n>) overwrite the current contents of the file without warning. However, if the file is a read-only, hidden, or system file, the redirection fails. The append redirection operators (>> and n>>) do not write to a read-only file, but they append content to a system or hidden file. - -To force the redirection of content to a read-only, hidden, or system file, use the Out-File cmdlet with its Force parameter. When you are writing to files, the redirection operators use Unicode encoding. If the file has a different encoding, the output might not be formatted correctly. To redirect content to non-Unicode files, use the Out-File cmdlet with its Encoding parameter. - +To force the redirection of content to a read-only, hidden, or system file, +use the Out-File cmdlet with its Force parameter. When you are writing to +files, the redirection operators use Unicode encoding. If the file has a +different encoding, the output might not be formatted correctly. To redirect +content to non-Unicode files, use the Out-File cmdlet with its Encoding +parameter. ## SEE ALSO @@ -142,4 +152,3 @@ Tee-Object [about_Command_Syntax](about_Command_Syntax.md) [about_Path_Syntax](about_Path_Syntax.md) - diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md b/reference/6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md index 00bb519f161..9194ac278b4 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Regular_Expressions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -16,50 +16,132 @@ Describes regular expressions in Windows PowerShell. Windows PowerShell supports the following regular expression characters. -| Format | Logic | Example | -| ------- | ----- | ------- | -| value | Matches exact characters anywhere in the original value. | "book" -match "oo" | -| . | Matches any single character. | "copy" -match "c..y" | -| [value] | Matches at least one of the characters in the brackets. | "big" -match "b[iou]g" | -| [range] | Matches at least one of the characters within the range. The use of a hyphen (-) allows you to specify an adjacent character. | "and" -match "[a-e]nd" | -| [^] | Matches any characters except those in brackets. | "and" -match "[^brt]nd" | -| ^ | Matches the beginning characters. | "book" -match "^bo" | -| $ | Matches the end characters. | "book" -match "ok$" | -| * | Matches any instances of the preceding character. | "baggy" -match "g*" | -| ? | Matches zero or one instance of the preceding character. | "baggy" -match "g?" | -| \ | Matches the character that follows as an escaped character. | "Try$" -match "Try\\$" | - -Windows PowerShell supports the character classes available in -Microsoft .NET Framework regular expressions. - -| Format | Logic | Example | -| -------- | ----- | ------- | -| \p{name} | Matches any character in the named character class specified by {name}. Supported names are Unicode groups and block ranges such as Ll, Nd, Z, IsGreek, and IsBoxDrawing. | "abcd defg" -match "\p{Ll}+" | -| \P{name} | Matches text not included in the groups and block ranges specified in {name}. | 1234 -match "\P{Ll}+" | -| \w | Matches any word character. Equivalent to the Unicode character categories [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. If ECMAScript-compliant behavior is specified with the ECMAScript option, \w is equivalent to [a-zA-Z_0-9]. | "abcd defg" -match "\w+" (this matches abcd) | -| \W | Matches any nonword character. Equivalent to the Unicode categories [^\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. | "abcd defg" -match "\W+" (this matches the space) | -| \s | Matches any white-space character. Equivalent to the Unicode character categories [\f\n\r\t\v\x85\p{Z}]. | "abcd defg" -match "\s+" | -| \S | Matches any non-white-space character. Equivalent to the Unicode character categories [^\f\n\r\t\v\x85\p{Z}]. | "abcd defg" -match "\S+" | -| \d | Matches any decimal digit. Equivalent to \p{Nd} for Unicode and [0-9] for non-Unicode behavior. | 12345 -match "\d+" | -| \D | Matches any nondigit. Equivalent to \P{Nd} for Unicode and [^0-9] for non-Unicode behavior. | "abcd" -match "\D+" | - +``` +Format value +Logic Matches exact characters anywhere in the original value. +Example "book" -match "oo" + +Format . +Logic Matches any single character. +Example "copy" -match "c..y" + +Format [value] +Logic Matches at least one of the characters in the brackets. +Example "big" -match "b[iou]g" + +Format [range] +Logic Matches at least one of the characters within the range. The use + of a hyphen (-) allows you to specify an adjacent character. +Example "and" -match "[a-e]nd" + +Format [^] +Logic Matches any characters except those in brackets. +Example "and" -match "[^brt]nd" + +Format ^ +Logic Matches the beginning characters. +Example "book" -match "^bo" + +Format $ +Logic Matches the end characters. +Example "book" -match "ok$" + +Format * +Logic Matches any instances of the preceding character. +Example "baggy" -match "g*" + +Format ? +Logic Matches zero or one instance of the preceding character. +Example "baggy" -match "g?" + +Format \ +Logic Matches the character that follows as an escaped character. +Example "Try$" -match "Try\\$" +``` + +Windows PowerShell supports the character classes available in Microsoft .NET +Framework regular expressions. + +``` +Format: \p{name} +Logic: Matches any character in the named character class specified by + {name}. Supported names are Unicode groups and block ranges such + as Ll, Nd, Z, IsGreek, and IsBoxDrawing. +Example: "abcd defg" -match "\p{Ll}+" + +Format: \P{name} +Logic: Matches text not included in the groups and block ranges specified + in {name}. +Example: 1234 -match "\P{Ll}+" + +Format: \w +Logic: Matches any word character. Equivalent to the Unicode character + categories [\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. If ECMAScript- + compliant behavior is specified with the ECMAScript option, \w is + equivalent to [a-zA-Z_0-9]. +Example: "abcd defg" -match "\w+" (this matches abcd) + +Format: \W +Logic: Matches any nonword character. Equivalent to the Unicode categories + [^\p{Ll}\p{Lu}\p{Lt}\p{Lo}\p{Nd}\p{Pc}]. +Example: "abcd defg" -match "\W+" (this matches the space) + +Format: \s +Logic: Matches any white-space character. Equivalent to the Unicode + character categories [\f\n\r\t\v\x85\p{Z}]. +Example: "abcd defg" -match "\s+" + +Format: \S +Logic: Matches any non-white-space character. Equivalent to the Unicode + character categories [^\f\n\r\t\v\x85\p{Z}]. +Example: "abcd defg" -match "\S+" + +Format: \d +Logic: Matches any decimal digit. Equivalent to \p{Nd} for Unicode and + [0-9] for non-Unicode behavior. +Example: 12345 -match "\d+" + +Format: \D +Logic: Matches any nondigit. Equivalent to \P{Nd} for Unicode and [^0-9] + for non-Unicode behavior. +Example: "abcd" -match "\D+" +``` Windows PowerShell supports the quantifiers available in .NET Framework regular expressions. The following are some examples of quantifiers. -| Format | Logic | Example | -| ------ | ----- | ------- | -| * | Specifies zero or more matches; for example, \wor (abc). Equivalent to {0,}. | "abc" -match "\w*" | -| + | Matches repeating instances of the preceding characters. | "xyxyxy" -match "xy+" | -| ? | Specifies zero or one matches; for example, \w? or (abc)?. Equivalent to {0,1}. | "abc" -match "\w?" | -| {n} | Specifies exactly n matches; for example, (pizza){2}. | "abc" -match "\w{2}" | -| {n,} | Specifies at least n matches; for example, (abc){2,}. | "abc" -match "\w{2,}" | -| {n,m} | Specifies at least n, but no more than m, matches. | "abc" -match "\w{2,3}" | +``` +Format: * +Logic Specifies zero or more matches; for example, \wor (abc). Equivalent + to {0,}. +Example: "abc" -match "\w*" + +Format: + +Logic: Matches repeating instances of the preceding characters. +Example: "xyxyxy" -match "xy+" + +Format: ? +Logic: Specifies zero or one matches; for example, \w? or (abc)?. + Equivalent to {0,1}. +Example: "abc" -match "\w?" + +Format: {n} +Logic: Specifies exactly n matches; for example, (pizza){2}. +Example: "abc" -match "\w{2}" + +Format: {n,} +Logic: Specifies at least n matches; for example, (abc){2,}. +Example: "abc" -match "\w{2,}" + +Format: {n,m} +Logic: Specifies at least n, but no more than m, matches. +Example: "abc" -match "\w{2,3}" +``` All the comparisons shown in the preceding table evaluate to true. -Notice that the escape character for regular expressions, a backslash (\\), -is different from the escape character for Windows PowerShell. The -escape character for Windows PowerShell is the backtick character (`) (ASCII 96). +Notice that the escape character for regular expressions, a backslash (\\), is +different from the escape character for Windows PowerShell. The escape +character for Windows PowerShell is the backtick character (`) (ASCII 96). For more information, see [Regular Expression Language - Quick Reference](https://go.microsoft.com/fwlink/?LinkId=133231). diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md index 9106db823dd..d7a4d220a0c 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Disconnected_Sessions.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -14,34 +14,31 @@ Explains how to disconnect from and reconnect to a PSSession ## Long Description -Beginning in Windows PowerShell 3.0, you can disconnect from -a PSSession and reconnect to the PSSession at a later time on -the same computer or a different computer. The session state -is maintained and commands in the PSSession continue to -run while the session is disconnected. +Beginning in Windows PowerShell 3.0, you can disconnect from a PSSession and +reconnect to the PSSession at a later time on the same computer or a different +computer. The session state is maintained and commands in the PSSession +continue to run while the session is disconnected. -The Disconnected Sessions feature is available only when the -computer at the remote end of a connection is running Windows -PowerShell 3.0 or a later version of Windows PowerShell. +The Disconnected Sessions feature is available only when the computer at the +remote end of a connection is running Windows PowerShell 3.0 or a later +version of Windows PowerShell. -The Disconnected Sessions feature allows you to close the session -in which a PSSession was created, and even close Windows PowerShell, -and shut down the computer, without disrupting commands running -in the PSSession. It is especially useful for running commands that -take an extended time to complete, and it provides the time and -device flexibility that IT professionals require. +The Disconnected Sessions feature allows you to close the session in which a +PSSession was created, and even close Windows PowerShell, and shut down the +computer, without disrupting commands running in the PSSession. It is +especially useful for running commands that take an extended time to complete, +and it provides the time and device flexibility that IT professionals require. -NOTE: You cannot disconnect from an interactive session that -is started by using the `Enter-PSSession` cmdlet. +NOTE: You cannot disconnect from an interactive session that is started by +using the `Enter-PSSession` cmdlet. -You can use Disconnected Sessions to manage PSSessions that -were disconnected unintentionally as the result of a computer -or network outage. +You can use Disconnected Sessions to manage PSSessions that were disconnected +unintentionally as the result of a computer or network outage. -In real-world use, the Disconnected Sessions feature allows -you to begin solving a problem, turn your attention to a higher -priority issue, and then resume work on the solution, even on a -different computer in a different location. +In real-world use, the Disconnected Sessions feature allows you to begin +solving a problem, turn your attention to a higher priority issue, and then +resume work on the solution, even on a different computer in a different +location. ## Disconnected Session Cmdlets @@ -50,82 +47,77 @@ The following cmdlets support the Disconnected Sessions feature: * `Connect-PSSession`: Connects to a disconnected PSSession * `Disconnect-PSSession`: Disconnects a PSSession * `Get-PSSession`: Gets PSSessions on the local computer or on remote computers -* `Receive-PSSession`: Gets the results of commands that ran in disconnected sessions -* `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and disconnects immediately +* `Receive-PSSession`: Gets the results of commands that ran in disconnected + sessions +* `Invoke-Command`: **InDisconnectedSession** parameter creates a PSSession and + disconnects immediately ## How the Disconnected Sessions Feature Works -Beginning in Windows PowerShell 3.0, PSSessions are independent -of the sessions in which they are created. Active PSSession are -maintained on the remote computer or "server side" of the -connection, even if the session in which PSSession was -created is closed and the originating computer is shut down -or disconnected from the network. - -In Windows PowerShell 2.0, the PSSession is deleted from the -remote computer when it is disconnected from the originating -session or the session in which it was created ends. - -When you disconnect a PSSession, the PSSession remains active -and is maintained on the remote computer. The session state -changes from Running to Disconnected. You can reconnect to a -disconnected PSSession from the current session or from a different -session on the same computer, or from a different computer. The -remote computer that maintains the session must be running and +Beginning in Windows PowerShell 3.0, PSSessions are independent of the +sessions in which they are created. Active PSSession are maintained on the +remote computer or "server side" of the connection, even if the session in +which PSSession was created is closed and the originating computer is shut +down or disconnected from the network. + +In Windows PowerShell 2.0, the PSSession is deleted from the remote computer +when it is disconnected from the originating session or the session in which +it was created ends. + +When you disconnect a PSSession, the PSSession remains active and is +maintained on the remote computer. The session state changes from Running to +Disconnected. You can reconnect to a disconnected PSSession from the current +session or from a different session on the same computer, or from a different +computer. The remote computer that maintains the session must be running and be connected to the network. -Commands in a disconnected PSSession continue to run -uninterrupted on the remote computer until the command -completes or the output buffer fills. To prevent a full -output buffer from suspending a command, use the +Commands in a disconnected PSSession continue to run uninterrupted on the +remote computer until the command completes or the output buffer fills. To +prevent a full output buffer from suspending a command, use the **OutputBufferingMode** parameter of the `Disconnect-PSSession`, `New-PSSessionOption`, or `New-PSTransportOption` cmdlets. -Disconnected sessions are maintained in the disconnected -state on the remote computer. They are available for you to -reconnect, until you delete the PSSession, such as by using -the `Remove-PSSession` cmdlet, or until the idle timeout of the -PSSession expires. You can adjust the idle timeout of a PSSession -by using the **IdleTimeoutSec** or **IdleTimeout** parameters of the +Disconnected sessions are maintained in the disconnected state on the remote +computer. They are available for you to reconnect, until you delete the +PSSession, such as by using the `Remove-PSSession` cmdlet, or until the idle +timeout of the PSSession expires. You can adjust the idle timeout of a +PSSession by using the **IdleTimeoutSec** or **IdleTimeout** parameters of the `Disconnect-PSSession`, `New-PSSessionOption`, or `New-PSTransportOption` cmdlets. -Another user can connect to PSSessions that you created, -but only if they can supply the credentials that were used -to create the session, or use the RunAs credentials of -the session configuration. +Another user can connect to PSSessions that you created, but only if they can +supply the credentials that were used to create the session, or use the RunAs +credentials of the session configuration. ## How to Get PSSessions Beginning in Windows PowerShell 3.0, the `Get-PSSession` cmdlet gets -PSSessions on the local computer and remote computers. It can also -get PSSessions that were created in the current session. +PSSessions on the local computer and remote computers. It can also get +PSSessions that were created in the current session. To get PSsessions on the local computer or remote computers, use the **ComputerName** or **ConnectionUri** parameters. Without parameters, `Get-PSSession` gets PSSession that were created in the local session, regardless of where they terminate. -When getting PSSessions, remember to look for them on the computer -on which they are maintained, that is, the remote or "server-side" -computer. +When getting PSSessions, remember to look for them on the computer on which +they are maintained, that is, the remote or "server-side" computer. -For example, if you create a PSSession to the Server01 computer, -get the session from the Server01 computer. If you create a PSSession -from another computer to the local computer, get the session from -the local computer. +For example, if you create a PSSession to the Server01 computer, get the +session from the Server01 computer. If you create a PSSession from another +computer to the local computer, get the session from the local computer. The following command sequence shows how `Get-PSSession` works. -The first command creates a session to the Server01 computer. The -session resides on the Server01 computer. +The first command creates a session to the Server01 computer. The session +resides on the Server01 computer. ```powershell PS C:\> New-PSSession -ComputerName Server01 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` To get the session, use the **ComputerName** parameter of `Get-PSSession` @@ -134,15 +126,15 @@ with a value of Server01. ```powershell PS C:\> Get-PSSession -ComputerName Server01 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` If the value of the **ComputerName** parameter of `Get-PSSession` is localhost, `Get-PSSession` gets PSSessions that terminate at and are -maintained on the local computer. It does not get PSSessions on the -Server01 computer, even if they were started on the local computer. +maintained on the local computer. It does not get PSSessions on the Server01 +computer, even if they were started on the local computer. ```powershell PS C:\> Get-PSSession -ComputerName localhost @@ -156,16 +148,16 @@ that was created in the current session and connects to the Server01 computer. ```powershell PS C:\> Get-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Opened Microsoft.PowerShell Available ``` ## How to Disconnect Sessions -To disconnect a PSSession use the `Disconnect-PSSession` cmdlet. To -identify the PSSession, use the **Session** parameter, or pipe a PSSession -from the `New-PSSession` or `Get-PSSession` cmdlets to `Disconnect-PSSession`. +To disconnect a PSSession use the `Disconnect-PSSession` cmdlet. To identify +the PSSession, use the **Session** parameter, or pipe a PSSession from the +`New-PSSession` or `Get-PSSession` cmdlets to `Disconnect-PSSession`. The following command disconnects the PSSession to the Server01 computer. Notice that the value of the State property is Disconnected and the @@ -174,94 +166,96 @@ Availability is None. ```powershell PS C:\> Get-PSSession -ComputerName Server01 | Disconnect-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 Server01 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 Server01 Disconnected Microsoft.PowerShell None ``` To create a disconnected session, use the **InDisconnectedSession** parameter -of the `Invoke-Command` cmdlet. It creates a session, starts the command, -and disconnects immediately, before the command can return any output. +of the `Invoke-Command` cmdlet. It creates a session, starts the command, and +disconnects immediately, before the command can return any output. -The following command runs a `Get-WinEvent` command in a disconnected -session on the Server02 remote computer. +The following command runs a `Get-WinEvent` command in a disconnected session +on the Server02 remote computer. ```powershell PS C:\> Invoke-Command -ComputerName Server02 -InDisconnectedSession ` -ScriptBlock { Get-WinEvent -LogName "Windows PowerShell" } -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 4 Session3 Server02 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 4 Session3 Server02 Disconnected Microsoft.PowerShell None ``` ## How to Connect to Disconnected Sessions -You can connect to any available disconnected PSSession from the session -in which you created the PSSession or from other sessions on the local -computer or other computers. +You can connect to any available disconnected PSSession from the session in +which you created the PSSession or from other sessions on the local computer +or other computers. -You can create a PSSession, run commands in the PSSession, disconnect from -the PSSession, close Windows PowerShell, and shut down the computer. Hours -later, you can open a different computer, get the PSSession, connect to it, -and get the results of commands that ran in the PSSession while it was -disconnected. Then you can run more commands in the session. +You can create a PSSession, run commands in the PSSession, disconnect from the +PSSession, close Windows PowerShell, and shut down the computer. Hours later, +you can open a different computer, get the PSSession, connect to it, and get +the results of commands that ran in the PSSession while it was disconnected. +Then you can run more commands in the session. To connect a disconnected PSSession, use the `Connect-PSSession` cmdlet. Use -the **ComputerName** or **ConnectionUri** parameters to identify the PSSession, or -pipe a PSSession from `Get-PSSession` to `Connect-PSSession`. +the **ComputerName** or **ConnectionUri** parameters to identify the +PSSession, or pipe a PSSession from `Get-PSSession` to `Connect-PSSession`. -The following command gets the sessions on the Server02 computer. -The output includes two disconnected sessions, both of which are available. +The following command gets the sessions on the Server02 computer. The output +includes two disconnected sessions, both of which are available. ```powershell PS C:\> Get-PSSession -ComputerName Server02 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 juneb-srv8320 Disconnected Microsoft.PowerShell None - 4 Session3 juneb-srv8320 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 juneb-srv8320 Disconnected Microsoft.PowerShell None + 4 Session3 juneb-srv8320 Disconnected Microsoft.PowerShell None ``` -The following command connects to Session2. The PSSession is now open and available. +The following command connects to Session2. The PSSession is now open and +available. ```powershell PS C:\> Connect-PSSession -ComputerName Server02 -Name Session2 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ - 2 Session2 juneb-srv8320 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ + 2 Session2 juneb-srv8320 Opened Microsoft.PowerShell Available ``` ## How to Get the Results -To get the results of commands that ran in a disconnected PSSession, use -the `Receive-PSSession` cmdlet. +To get the results of commands that ran in a disconnected PSSession, use the +`Receive-PSSession` cmdlet. You can use `Receive-PSSession` in addition to, or instead of, using the `Connect-PSSession` cmdlet. If the session is already reconnected, -`Receive-PSSession` gets the results of commands that ran when the session -was disconnected. If the PSSession is still disconnected, `Receive-PSSession` +`Receive-PSSession` gets the results of commands that ran when the session was +disconnected. If the PSSession is still disconnected, `Receive-PSSession` connects to it and then gets the results of commands that ran while it was disconnected. -`Receive-PSSession` can return the results in a job (asynchronously) or to -the host program (synchronously). Use the **OutTarget** parameter to select Job -or Host. Host is the default value. However, if the command that is being +`Receive-PSSession` can return the results in a job (asynchronously) or to the +host program (synchronously). Use the **OutTarget** parameter to select Job or +Host. Host is the default value. However, if the command that is being received was started in the current session as a job, it is returned as a job by default. -The following command uses the `Receive-PSSession` cmdlet to connect to the PSSession -on the Server02 computer and get the results of the `Get-WinEvent` command that -ran in the Session3 session. The command uses the **OutTarget** parameter to get the -results in a job. +The following command uses the `Receive-PSSession` cmdlet to connect to the +PSSession on the Server02 computer and get the results of the `Get-WinEvent` +command that ran in the Session3 session. The command uses the **OutTarget** +parameter to get the results in a job. ```powershell -PS C:\> Receive-PSSession -ComputerName Server02 -Name Session3 -OutTarget Job +PS C:\> Receive-PSSession -ComputerName Server02 -Name Session3 ` + -OutTarget Job -Id Name PSJobTypeName State HasMoreData Location --- ---- ------------- ----- ----------- -------- - 3 Job3 RemoteJob Running True Server02 +Id Name PSJobTypeName State HasMoreData Location +-- ---- ------------- ----- ----------- -------- + 3 Job3 RemoteJob Running True Server02 ``` To get the results of the job, use the `Receive-Job` cmdlet. @@ -281,141 +275,135 @@ TimeCreated Id LevelDisplayName Message PSComputerName ## State and Availability -The State and Availability properties of a disconnected PSSession -tell you whether the session is available for you to reconnect to it. +The State and Availability properties of a disconnected PSSession tell you +whether the session is available for you to reconnect to it. -When a PSSession is connected to the current session, its state is -Opened and its availability is Available. When you disconnect from -the PSSession, the PSSession state is Disconnected and its Availability -is none. +When a PSSession is connected to the current session, its state is Opened and +its availability is Available. When you disconnect from the PSSession, the +PSSession state is Disconnected and its Availability is none. -However, 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. However, it does not mean -that the PSSession is disconnected from all sessions. It might be -connected to a different session. +However, 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. 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, -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. +To determine whether you can connect or reconnect to the PSSession, 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. -The following example is run in two sessions (Windows PowerShell -console windows) on the same computer. Note the changing values of the -State and Availability properties in each session as the PSSession is -disconnected and reconnected. +The following example is run in two sessions (Windows PowerShell console +windows) on the same computer. Note the changing values of the State and +Availability properties in each session as the PSSession is disconnected and +reconnected. ```powershell # Session 1 PS C:\> New-PSSession -ComputerName Server30 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Opened Microsoft.PowerShell Available # Session 2 PS C:\> Get-PSSession -ComputerName Server30 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell Busy +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell Busy # Session 1 -PS C:\> Get-PSSession -ComputerName Server30 -Name Test | Disconnect-PSSession +PS C:\> Get-PSSession -ComputerName Server30 -Name Test | +>> Disconnect-PSSession -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell None # Session 2 PS C:\> Get-PSSession -ComputerName Server30 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell None +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell None # Session 2 PS C:\> Connect-PSSession -ComputerName Server01 -Name Test -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -3 Test Server30 Opened Microsoft.PowerShell Available +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +3 Test Server30 Opened Microsoft.PowerShell Available # Session 1 PS C:\> Get-PSSession -ComputerName Server30 -Id Name ComputerName State ConfigurationName Availability --- ---- ------------ ----- ----------------- ------------ -1 Test Server30 Disconnected Microsoft.PowerShell Busy +Id Name ComputerName State ConfigurationName Availability +-- ---- ------------ ----- ----------------- ------------ +1 Test Server30 Disconnected Microsoft.PowerShell Busy # IDLE TIMEOUT ``` -Disconnected sessions are maintained on the remote computer until -you delete them, such as by using the `Remove-PSSession` cmdlet, or -they time out. The IdleTimeout property of a PSSession determines -how long a disconnected session is maintained before it is deleted. +Disconnected sessions are maintained on the remote computer until you delete +them, such as by using the `Remove-PSSession` cmdlet, or they time out. The +IdleTimeout property of a PSSession determines how long a disconnected session +is maintained before it is deleted. PSSessions are idle when the "heartbeat thread" receives no response. -Disconnecting a session makes it idle and starts the Idle Timeout -clock, even if commands are still running in the disconnected session. -Windows PowerShell considers disconnected sessions to be active, but -idle. - -When creating and disconnecting sessions, verify that the idle -timeout in the PSSession is long enough to maintain the session -for your needs, but not so long that it consumes unnecessary -resources on the remote computer. - -The IdleTimeoutMs property of the session configuration -determines the default idle timeout of sessions that use the -session configuration. You can override the default value, but -the value that you use cannot exceed the MaxIdleTimeoutMs -property of the session configuration. - -To find the value of the IdleTimeoutMs and MaxIdleTimeoutMs -values of a session configuration, use the following command -format. +Disconnecting a session makes it idle and starts the Idle Timeout clock, even +if commands are still running in the disconnected session. Windows PowerShell +considers disconnected sessions to be active, but idle. + +When creating and disconnecting sessions, verify that the idle timeout in the +PSSession is long enough to maintain the session for your needs, but not so +long that it consumes unnecessary resources on the remote computer. + +The IdleTimeoutMs property of the session configuration determines the default +idle timeout of sessions that use the session configuration. You can override +the default value, but the value that you use cannot exceed the +MaxIdleTimeoutMs property of the session configuration. + +To find the value of the IdleTimeoutMs and MaxIdleTimeoutMs values of a +session configuration, use the following command format. ```powershell -Get-PSSessionConfiguration | Format-Table Name, IdleTimeoutMs, MaxIdleTimeoutMs +Get-PSSessionConfiguration | + Format-Table Name, IdleTimeoutMs, MaxIdleTimeoutMs ``` -You can override the default value in the session configuration and -set the idle timeout of a PSSession when you create a PSSession and -when you disconnect. +You can override the default value in the session configuration and set the +idle timeout of a PSSession when you create a PSSession and when you +disconnect. -If you are a member of the Administrators group on the remote computer, -you can also create and change the IdleTimeoutMs and MaxIdleTimeoutMs -properties of session configurations. +If you are a member of the Administrators group on the remote computer, you +can also create and change the IdleTimeoutMs and MaxIdleTimeoutMs properties +of session configurations. ## NOTES: -The idle timeout value of session configurations and session -options is in milliseconds. The idle timeout value of sessions -and session configuration options is in seconds. +The idle timeout value of session configurations and session options is in +milliseconds. The idle timeout value of sessions and session configuration +options is in seconds. -You can set the idle timeout of a PSSession when you create the -PSSession (`New-PSSession`, `Invoke-Command`) and when you disconnect -from it (`Disconnect-PSSession`). However, you cannot change the -IdleTimeout value when you connect to the PSSession -(`Connect-PSSession`) or get results (`Receive-PSSession`). +You can set the idle timeout of a PSSession when you create the PSSession +(`New-PSSession`, `Invoke-Command`) and when you disconnect from it +(`Disconnect-PSSession`). However, you cannot change the IdleTimeout value +when you connect to the PSSession (`Connect-PSSession`) or get results +(`Receive-PSSession`). The `Connect-PSSession` and `Receive-PSSession` cmdlets have a -**SessionOption** parameter that takes a SessionOption object, -such as one returned by the `New-PSSessionOption` cmdlet. However, -the IdleTimeout value in SessionOption object and the IdleTimeout -value in the $PSSessionOption preference variable do not change -the value of the IdleTimeout of the PSSession in a `Connect-PSSession` -or `Receive-PSSession` command. +**SessionOption** parameter that takes a SessionOption object, such as one +returned by the `New-PSSessionOption` cmdlet. However, the IdleTimeout value +in SessionOption object and the IdleTimeout value in the $PSSessionOption +preference variable do not change the value of the IdleTimeout of the +PSSession in a `Connect-PSSession` or `Receive-PSSession` command. * To create a PSSession with a particular idle timeout value, create a $PSSessionOption preference variable. Set the value of the IdleTimeout property to the desired value (in milliseconds). - When you create PSSessions, the values in $PSSessionOption variable - take precedence over the values in the session configuration. + When you create PSSessions, the values in $PSSessionOption variable take + precedence over the values in the session configuration. For example, this command sets an idle timeout of 48 hours. @@ -477,38 +465,35 @@ Set-PSSessionConfiguration -Name Test -TransportOption $o ## Output Buffering Mode -The output buffering mode of a PSSession determines how command -output is managed when the output buffer of the PSSession is full. +The output buffering mode of a PSSession determines how command output is +managed when the output buffer of the PSSession is full. -In a disconnected session, the output buffering mode effectively -determines whether the command continues to run while the session -is disconnected. +In a disconnected session, the output buffering mode effectively determines +whether the command continues to run while the session is disconnected. Valid values: * Block - When the output buffer is full, execution is suspended - until the buffer is clear. + When the output buffer is full, execution is suspended until the buffer is + clear. * Drop - When the output buffer is full, execution continues. - As new output is generated, the oldest output is discarded. + When the output buffer is full, execution continues. As new output is + generated, the oldest output is discarded. -Block, the default value, preserves data, but might interrupt -the command. +Block, the default value, preserves data, but might interrupt the command. -A value of Drop allows the command to complete, although data might -be lost. When using the Drop value, redirect the command output to -a file on disk. This value is recommended for disconnected sessions. +A value of Drop allows the command to complete, although data might be lost. +When using the Drop value, redirect the command output to a file on disk. This +value is recommended for disconnected sessions. -The OutputBufferingMode property of the session configuration -determines the default output buffering mode of sessions that -use the session configuration. +The OutputBufferingMode property of the session configuration determines the +default output buffering mode of sessions that use the session configuration. -To find the value of the OutputBufferingMode of a session -configuration, use the following command formats. +To find the value of the OutputBufferingMode of a session configuration, use +the following command formats. ```powershell (Get-PSSessionConfiguration ).OutputBufferingMode @@ -520,12 +505,12 @@ or Get-PSSessionConfiguration | Format-Table Name, OutputBufferingMode ``` -You can override the default value in the session configuration and set -the output buffering mode of a PSSession when you create a PSSession, -when you disconnect, and when you reconnect. +You can override the default value in the session configuration and set the +output buffering mode of a PSSession when you create a PSSession, when you +disconnect, and when you reconnect. -If you are a member of the Administrators group on the remote computer, -you can also create and change the output buffering mode of session +If you are a member of the Administrators group on the remote computer, you +can also create and change the output buffering mode of session configurations. * To create a PSSession with an output buffering mode of Drop, create @@ -609,63 +594,58 @@ Set-PSSessionConfiguration -Name Test -TransportOption $o ## Disconnecting Loopback Sessions -"Loopback sessions" or "local sessions" are PSSessions that -originate and terminate on the same computer. Like other -PSSessions, active loopback sessions are maintained on the -computer on the remote end of the connection (the local -computer), so you can disconnect from and reconnect to -loopback sessions. +"Loopback sessions" or "local sessions" are PSSessions that originate and +terminate on the same computer. Like other PSSessions, active loopback +sessions are maintained on the computer on the remote end of the connection +(the local computer), so you can disconnect from and reconnect to loopback +sessions. -By default, loopback sessions are created with a network security -token that does not permit commands run in the session to access -other computers. You can reconnect to loopback sessions that have a -network security token from any session on the local computer or a -remote computer. +By default, loopback sessions are created with a network security token that +does not permit commands run in the session to access other computers. You can +reconnect to loopback sessions that have a network security token from any +session on the local computer or a remote computer. However, if you use the **EnableNetworkAccess** parameter of the -`New-PSSession`, `Enter-PSSession`, or `Invoke-Command` cmdlet, the -loopback session is created with an interactive security token. -The interactive token enables commands that run in the loopback -session to get data from other computers. +`New-PSSession`, `Enter-PSSession`, or `Invoke-Command` cmdlet, the loopback +session is created with an interactive security token. The interactive token +enables commands that run in the loopback session to get data from other +computers. -You can disconnect loopback sessions with interactive tokens and -then reconnect to them from the same session or a different session -on the same computer. However, to prevent malicious access, you can -reconnect to loopback sessions with interactive tokens only from the -computer on which they were created. +You can disconnect loopback sessions with interactive tokens and then +reconnect to them from the same session or a different session on the same +computer. However, to prevent malicious access, you can reconnect to loopback +sessions with interactive tokens only from the computer on which they were +created. ## Waiting for Jobs in Disconnected Sessions -The `Wait-Job` cmdlet waits until a job completes and then -returns to the command prompt or the next command. By default, -`Wait-Job` returns if the session in which a job is running is -disconnected. To direct the `Wait-Job` cmdlet to wait until the -session is reconnected (in the Opened state), use the **Force** -parameter. For more information, see [Wait-Job](../Wait-Job.md). +The `Wait-Job` cmdlet waits until a job completes and then returns to the +command prompt or the next command. By default, `Wait-Job` returns if the +session in which a job is running is disconnected. To direct the `Wait-Job` +cmdlet to wait until the session is reconnected (in the Opened state), use the +**Force** parameter. For more information, see [Wait-Job](../Wait-Job.md). ## Robust Sessions and Unintentional Disconnection -Occasionally, a PSSession might be disconnected unintentionally -due to a computer failure or network outage. Windows PowerShell -attempts to recover the PSSession, but its success depends upon -the severity and duration of the cause. - -The state of an unintentionally disconnected PSSession might -be Broken or Closed, but it might also be Disconnected. If -the value of State is Disconnected, you can use the same -techniques to manage the PSSession as you would if the -session were disconnected intentionally. For example, you -can use the `Connect-PSSession` cmdlet to reconnect to the session -and the `Receive-PSSession` cmdlet to get results of commands that -ran while the session was disconnected. - -If you close (exit) the session in which a PSSession was -created while commands are running in the PSSession, Windows -PowerShell maintains the PSSession in the Disconnected state -on the remote computer. If you close (exit) the session in -which a PSSession was created, but no commands are running -in the PSSession, Windows PowerShell does not attempt to -maintain the PSSession. +Occasionally, a PSSession might be disconnected unintentionally due to a +computer failure or network outage. Windows PowerShell attempts to recover the +PSSession, but its success depends upon the severity and duration of the +cause. + +The state of an unintentionally disconnected PSSession might be Broken or +Closed, but it might also be Disconnected. If the value of State is +Disconnected, you can use the same techniques to manage the PSSession as you +would if the session were disconnected intentionally. For example, you can use +the `Connect-PSSession` cmdlet to reconnect to the session and the +`Receive-PSSession` cmdlet to get results of commands that ran while the +session was disconnected. + +If you close (exit) the session in which a PSSession was created while +commands are running in the PSSession, Windows PowerShell maintains the +PSSession in the Disconnected state on the remote computer. If you close +(exit) the session in which a PSSession was created, but no commands are +running in the PSSession, Windows PowerShell does not attempt to maintain the +PSSession. ## See Also diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md index d8b2c92b2d3..93fb4c492c5 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_FAQ.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,344 +7,512 @@ title: about_Remote_FAQ --- # About Remote FAQ -## about_Remote_FAQ - ## SHORT DESCRIPTION -Contains questions and answers about running remote commands in Windows PowerShell. +Contains questions and answers about running remote commands in Windows +PowerShell. ## LONG DESCRIPTION -When you work remotely, you type commands in Windows PowerShell on one computer (known as the "local computer"), but the commands run on another computer (known as the "remote computer"). The experience of working remotely should be as much like working directly at the remote computer as possible. - - -``` -Note: To use Windows PowerShell remoting, the remote computer - must be configured for remoting. For more information, see - about_Remote_Requirements. -``` +When you work remotely, you type commands in Windows PowerShell on one +computer (known as the "local computer"), but the commands run on another +computer (known as the "remote computer"). The experience of working remotely +should be as much like working directly at the remote computer as possible. +Note: To use Windows PowerShell remoting, the remote computer must be +configured for remoting. For more information, see +[about_Remote_Requirements](about_Remote_Requirements.md). ### MUST BOTH COMPUTERS HAVE WINDOWS POWERSHELL INSTALLED? -Yes. To work remotely, the local and remote computers must have Windows PowerShell, the Microsoft .NET Framework, and the Web Services for Management (WS-Management) protocol. Any files and other resources that are needed to execute a particular command must be on the remote computer. -Computers running Windows PowerShell 3.0 and computers running Windows PowerShell 2.0 can connect to each other remotely and run remote commands. However, some features, such as the ability to disconnect from a session and reconnect to it, work only when both computers are running Windows PowerShell 3.0. +Yes. To work remotely, the local and remote computers must have Windows +PowerShell, the Microsoft .NET Framework, and the Web Services for Management +(WS-Management) protocol. Any files and other resources that are needed to +execute a particular command must be on the remote computer. -You must have permission to connect to the remote computer, permission to run Windows PowerShell, and permission to access data stores (such as files and folders), and the registry on the remote computer. +Computers running Windows PowerShell 3.0 and computers running Windows +PowerShell 2.0 can connect to each other remotely and run remote commands. +However, some features, such as the ability to disconnect from a session and +reconnect to it, work only when both computers are running Windows PowerShell +3.0. -For more information, see about_Remote_Requirements. +You must have permission to connect to the remote computer, permission to run +Windows PowerShell, and permission to access data stores (such as files and +folders), and the registry on the remote computer. +For more information, see [about_Remote_Requirements](about_Remote_Requirements.md). ### HOW DOES REMOTING WORK? -When you submit a remote command, the command is transmitted across the network to the Windows PowerShell engine on the remote computer, and it runs in the Windows PowerShell client on the remote computer. The command results are sent back to the local computer and appear in the Windows PowerShell session on the local computer. -To transmit the commands and receive the output, Windows PowerShell uses the WS-Management protocol. For information about the WS-Management protocol, see "WS-Management Protocol" in the MSDN (Microsoft Developer Network) library at http:\/\/go.microsoft.com\/fwlink\/?LinkId\=144634. +When you submit a remote command, the command is transmitted across the +network to the Windows PowerShell engine on the remote computer, and it runs +in the Windows PowerShell client on the remote computer. The command results +are sent back to the local computer and appear in the Windows PowerShell +session on the local computer. -Beginning in Windows PowerShell 3.0, remote sessions are stored on the remote computer. This enables you to disconnect from the session and reconnect from a different session or a different computer without interrupting the commands or losing state. +To transmit the commands and receive the output, Windows PowerShell uses the +WS-Management protocol. For information about the WS-Management protocol, see +[WS-Management Protocol](http://go.microsoft.com\/fwlink/?LinkId=144634) in +the MSDN library. +Beginning in Windows PowerShell 3.0, remote sessions are stored on the remote +computer. This enables you to disconnect from the session and reconnect from a +different session or a different computer without interrupting the commands or +losing state. ### IS WINDOWS POWERSHELL REMOTING SECURE? -When you connect to a remote computer, the system uses the user name and password credentials on the local computer or the credentials that you supply in the command to log you in to the remote computer. The credentials and the rest of the transmission are encrypted. -To add additional protection, you can configure the remote computer to use Secure Sockets Layer (SSL) instead of HTTP to listen for Windows Remote Management (WinRM) requests. Then, users can use the UseSSL parameters of the Invoke-Command, New-PSSession, and Enter-PSSession cmdlets when establishing a connection. This option uses the more secure HTTPS channel instead of HTTP. +When you connect to a remote computer, the system uses the user name and +password credentials on the local computer or the credentials that you supply +in the command to log you in to the remote computer. The credentials and the +rest of the transmission are encrypted. +To add additional protection, you can configure the remote computer to use +Secure Sockets Layer (SSL) instead of HTTP to listen for Windows Remote +Management (WinRM) requests. Then, users can use the UseSSL parameters of the +Invoke-Command, New-PSSession, and Enter-PSSession cmdlets when establishing a +connection. This option uses the more secure HTTPS channel instead of HTTP. ### DO ALL REMOTE COMMANDS REQUIRE WINDOWS POWERSHELL REMOTING? -No. Several cmdlets have a ComputerName parameter that lets you get objects from the remote computer. - -These cmdlets do not use Windows PowerShell remoting. So, you can use them on any computer that is running Windows PowerShell, even if the computer is not configured for Windows PowerShell remoting or if the computer does not meet the requirements for Windows PowerShell remoting. -These cmdlets include the following cmdlets: +No. Several cmdlets have a ComputerName parameter that lets you get objects +from the remote computer. +These cmdlets do not use Windows PowerShell remoting. So, you can use them on +any computer that is running Windows PowerShell, even if the computer is not +configured for Windows PowerShell remoting or if the computer does not meet +the requirements for Windows PowerShell remoting. -``` -Get-Process -Get-Service -Get-WinEvent -Get-EventLog -Get-WmiObject -Test-Connection -``` +These cmdlets include the following: +- Get-Process +- Get-Service +- Get-WinEvent +- Get-EventLog +- Get-WmiObject +- Test-Connection To find all the cmdlets with a ComputerName parameter, type: - -``` -Get-Help * -Parameter ComputerName -or +```powershell +Get-Help * -Parameter ComputerName +# or Get-Command -ParameterName ComputerName ``` +To determine whether the ComputerName parameter of a particular cmdlet +requires Windows PowerShell remoting, see the parameter description. To +display the parameter description, type: -To determine whether the ComputerName parameter of a particular cmdlet requires Windows PowerShell remoting, see the parameter description. To display the parameter description, type: - - -``` +```ppowershell Get-Help -Parameter ComputerName ``` - For example: - -``` +```powershell Get-Help Get-Process -Parameter Computername ``` - For all other commands, use the Invoke-Command cmdlet. - ### HOW DO I RUN A COMMAND ON A REMOTE COMPUTER? + To run a command on a remote computer, use the Invoke-Command cmdlet. -Enclose your command in braces ( {} ) to make it a script block. Use the ScriptBlock parameter of Invoke-Command to specify the command. +Enclose your command in braces ( {} ) to make it a script block. Use the +ScriptBlock parameter of Invoke-Command to specify the command. -You can use the ComputerName parameter of Invoke-Command to specify a remote computer. Or, you can create a persistent connection to a remote computer (a session) and then use the Session parameter of Invoke-Command to run the command in the session. +You can use the ComputerName parameter of Invoke-Command to specify a remote +computer. Or, you can create a persistent connection to a remote computer (a +session) and then use the Session parameter of Invoke-Command to run the +command in the session. For example, the following commands run a Get-Process command remotely. +```powershell +Invoke-Command -ComputerName Server01, Server02 -ScriptBlock {Get-Process} + +# - OR - -``` -Invoke-Command -ComputerName Server01, Server02 -ScriptBlock {Get-Process} - - - OR - - Invoke-Command -Session $s -ScriptBlock {Get-Process} ``` +To interrupt a remote command, type CTRL\+C. The interruption request is +passed to the remote computer, where it terminates the remote command. -To interrupt a remote command, type CTRL\+C. The interruption request is passed to the remote computer, where it terminates the remote command. - -For more information about remote commands, see about_Remote and the Help topics for the cmdlets that support remoting. - +For more information about remote commands, see about_Remote and the Help +topics for the cmdlets that support remoting. ### CAN I JUST "TELNET INTO" A REMOTE COMPUTER? -You can use the Enter-PSSession cmdlet to start an interactive session with a remote computer. -At the Windows PowerShell prompt, type: +You can use the Enter-PSSession cmdlet to start an interactive session with a +remote computer. +At the Windows PowerShell prompt, type: -``` +```powershell Enter-PSSession ``` - -The command prompt changes to show that you are connected to the remote computer. - +The command prompt changes to show that you are connected to the remote +computer. ``` \C:> ``` - -Now, the commands that you type run on the remote computer just as though you typed them directly on the remote computer. +Now, the commands that you type run on the remote computer just as though you +typed them directly on the remote computer. To end the interactive session, type: - -``` +```powershell Exit-PSSession ``` - -An interactive session is a persistent session that uses the WS-Management protocol. It is not the same as using Telnet, but it provides a similar experience. +An interactive session is a persistent session that uses the WS-Management +protocol. It is not the same as using Telnet, but it provides a similar +experience. For more information, see Enter-PSSession. - ### CAN I CREATE A PERSISTENT CONNECTION? -Yes. You can run remote commands by specifying the name of the remote computer, its NetBIOS name, or its IP address. Or, you can run remote commands by specifying a Windows PowerShell session (PSSession) that is connected to the remote computer. -When you use the ComputerName parameter of Invoke-Command or Enter-PSSession, Windows PowerShell establishes a temporary connection. Windows PowerShell uses the connection to run only the current command, and then it closes the connection. This is a very efficient method for running a single command or several unrelated commands, even on many remote computers. +Yes. You can run remote commands by specifying the name of the remote +computer, its NetBIOS name, or its IP address. Or, you can run remote commands +by specifying a Windows PowerShell session (PSSession) that is connected to +the remote computer. -When you use the New-PSSession cmdlet to create a PSSession, Windows PowerShell establishes a persistent connection for the PSSession. Then, you can run multiple commands in the PSSession, including commands that share data. +When you use the ComputerName parameter of Invoke-Command or Enter-PSSession, +Windows PowerShell establishes a temporary connection. Windows PowerShell uses +the connection to run only the current command, and then it closes the +connection. This is a very efficient method for running a single command or +several unrelated commands, even on many remote computers. -Typically, you create a PSSession to run a series of related commands that share data. Otherwise, the temporary connection created by the ComputerName parameter is sufficient for most commands. +When you use the New-PSSession cmdlet to create a PSSession, Windows +PowerShell establishes a persistent connection for the PSSession. Then, you +can run multiple commands in the PSSession, including commands that share +data. -For more information about sessions, see about_PSSessions. +Typically, you create a PSSession to run a series of related commands that +share data. Otherwise, the temporary connection created by the ComputerName +parameter is sufficient for most commands. +For more information about sessions, see about_PSSessions. ### CAN I RUN COMMANDS ON MORE THAN ONE COMPUTER AT A TIME? -Yes. The ComputerName parameter of the Invoke-Command cmdlet accepts multiple computer names, and the Session parameter accepts multiple PSSessions. -When you run an Invoke-Command command, Windows PowerShell runs the commands on all of the specified computers or in all of the specified PSSessions. +Yes. The ComputerName parameter of the Invoke-Command cmdlet accepts multiple +computer names, and the Session parameter accepts multiple PSSessions. -Windows PowerShell can manage hundreds of concurrent remote connections. However, the number of remote commands that you can send might be limited by the resources of your computer and its capacity to establish and maintain multiple network connections. +When you run an Invoke-Command command, Windows PowerShell runs the commands +on all of the specified computers or in all of the specified PSSessions. -For more information, see the example in the Invoke-Command Help topic. +Windows PowerShell can manage hundreds of concurrent remote connections. +However, the number of remote commands that you can send might be limited by +the resources of your computer and its capacity to establish and maintain +multiple network connections. +For more information, see the example in the Invoke-Command Help topic. ### WHERE ARE MY PROFILES? -Windows PowerShell profiles are not run automatically in remote sessions, so the commands that the profile adds are not present in the session. In addition, the $profile automatic variable is not populated in remote sessions. -To run a profile in a session, use the Invoke-Command cmdlet. +Windows PowerShell profiles are not run automatically in remote sessions, so +the commands that the profile adds are not present in the session. In +addition, the \$profile automatic variable is not populated in remote sessions. -For example, the following command runs the CurrentUserCurrentHost profile from the local computer in the session in $s. +To run a profile in a session, use the `Invoke-Command` cmdlet. +For example, the following command runs the CurrentUserCurrentHost profile +from the local computer in the session in \$s. ``` Invoke-Command -Session $s -FilePath $profile ``` +The following command runs the CurrentUserCurrentHost profile from the remote +computer in the session in $s. Because the $profile variable is not populated, +the command uses the explicit path to the profile. -The following command runs the CurrentUserCurrentHost profile from the remote computer in the session in $s. Because the $profile variable is not populated, the command uses the explicit path to the profile. - - -``` -Invoke-Command -Session $s {. "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1"} +```powershell +Invoke-Command -Session $s { + . "$home\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1" +} ``` +After running this command, the commands that the profile adds to the session +are available in $s. -After running this command, the commands that the profile adds to the session are available in $s. - -You can also use a startup script in a session configuration to run a profile in every remote session that uses the session configuration. - -For more information about Windows PowerShell profiles, see about_Profiles. For more information about session configurations, see Register-PSSessionConfiguration. +You can also use a startup script in a session configuration to run a profile +in every remote session that uses the session configuration. +For more information about Windows PowerShell profiles, see about_Profiles. +For more information about session configurations, see +Register-PSSessionConfiguration. ### HOW DOES THROTTLING WORK ON REMOTE COMMANDS? -To help you manage the resources on your local computer, Windows PowerShell includes a per-command throttling feature that lets you limit the number of concurrent remote connections that are established for each command. -The default is 32 concurrent connections, but you can use the ThrottleLimit parameters of the cmdlets to set a custom throttle limit for particular commands. +To help you manage the resources on your local computer, Windows PowerShell +includes a per-command throttling feature that lets you limit the number of +concurrent remote connections that are established for each command. -When you use the throttling feature, remember that it is applied to each command, not to the entire session or to the computer. If you are running commands concurrently in several sessions or PSSessions, the number of concurrent connections is the sum of the concurrent connections in all the sessions. +The default is 32 concurrent connections, but you can use the **ThrottleLimit** +parameters of the cmdlets to set a custom throttle limit for particular +commands. -To find cmdlets with a ThrottleLimit parameter, type: +When you use the throttling feature, remember that it is applied to each +command, not to the entire session or to the computer. If you are running +commands concurrently in several sessions or PSSessions, the number of +concurrent connections is the sum of the concurrent connections in all the +sessions. +To find cmdlets with a ThrottleLimit parameter, type: ``` -Get-Help * -Parameter ThrottleLimit --or- +Get-Help * -Parameter ThrottleLimit +-or- Get-Command -ParameterName ThrottleLimit ``` - ### IS THE OUTPUT OF REMOTE COMMANDS DIFFERENT FROM LOCAL OUTPUT? -When you use Windows PowerShell locally, you send and receive "live" .NET Framework objects; "live" objects are objects that are associated with actual programs or system components. When you invoke the methods or change the properties of live objects, the changes affect the actual program or component. And, when the properties of a program or component change, the properties of the object that represent them also change. -However, because most live objects cannot be transmitted over the network, Windows PowerShell "serializes" most of the objects sent in remote commands, that is, it converts each object into a series of XML (Constraint Language in XML [CLiXML]) data elements for transmission. +When you use Windows PowerShell locally, you send and receive "live" .NET +Framework objects; "live" objects are objects that are associated with actual +programs or system components. When you invoke the methods or change the +properties of live objects, the changes affect the actual program or +component. And, when the properties of a program or component change, the +properties of the object that represent them also change. -When Windows PowerShell receives a serialized object, it converts the XML into a deserialized object type. The deserialized object is an accurate record of the properties of the program or component at a previous time, but it is no longer "live", that is, it is no longer directly associated with the component. And, the methods are removed because they are no longer effective. +However, because most live objects cannot be transmitted over the network, +Windows PowerShell "serializes" most of the objects sent in remote commands, +that is, it converts each object into a series of XML (Constraint Language in +XML [CLiXML]) data elements for transmission. -Typically, you can use deserialized objects just as you would use live objects, but you must be aware of their limitations. Also, the objects that are returned by the Invoke-Command cmdlet have additional properties that help you to determine the origin of the command. +When Windows PowerShell receives a serialized object, it converts the XML into +a deserialized object type. The deserialized object is an accurate record of +the properties of the program or component at a previous time, but it is no +longer "live", that is, it is no longer directly associated with the +component. And, the methods are removed because they are no longer effective. -Some object types, such as DirectoryInfo objects and GUIDs, are converted back into live objects when they are received. These objects do not need any special handling or formatting. +Typically, you can use deserialized objects just as you would use live +objects, but you must be aware of their limitations. Also, the objects that +are returned by the Invoke-Command cmdlet have additional properties that help +you to determine the origin of the command. -For information about interpreting and formatting remote output, see about_Remote_Output. +Some object types, such as DirectoryInfo objects and GUIDs, are converted back +into live objects when they are received. These objects do not need any +special handling or formatting. +For information about interpreting and formatting remote output, see +[about_Remote_Output](about_Remote_Output.md). ### CAN I RUN BACKGROUND JOBS REMOTELY? -Yes. A Windows PowerShell background job is a Windows PowerShell command that runs asynchronously without interacting with the session. When you start a background job, the command prompt returns immediately, and you can continue to work in the session while the job runs even if it runs for an extended period of time. -You can start a background job even while other commands are running because background jobs always run asynchronously in a temporary session. +Yes. A Windows PowerShell background job is a Windows PowerShell command that +runs asynchronously without interacting with the session. When you start a +background job, the command prompt returns immediately, and you can continue +to work in the session while the job runs even if it runs for an extended +period of time. -You can run background jobs on a local or remote computer. By default, a background job runs on the local computer. However, you can use the AsJob parameter of the Invoke-Command cmdlet to run any remote command as a background job. And, you can use Invoke-Command to run a Start-Job command remotely. +You can start a background job even while other commands are running because +background jobs always run asynchronously in a temporary session. -For more information about background jobs in Windows PowerShell , see about_Jobs and about_Remote_Jobs. +You can run background jobs on a local or remote computer. By default, a +background job runs on the local computer. However, you can use the AsJob +parameter of the Invoke-Command cmdlet to run any remote command as a +background job. And, you can use Invoke-Command to run a Start-Job command +remotely. +For more information about background jobs in Windows PowerShell , see +[about_Jobs(about_Jobs.md)] and [about_Remote_Jobs(about_Remote_Jobs.md)]. ### CAN I RUN WINDOWS PROGRAMS ON A REMOTE COMPUTER? -You can use Windows PowerShell remote commands to run Windows-based programs on remote computers. For example, you can run Shutdown.exe or Ipconfig on a remote computer. -However, you cannot use Windows PowerShell commands to open the user interface for any program on a remote computer. +You can use Windows PowerShell remote commands to run Windows-based programs +on remote computers. For example, you can run Shutdown.exe or Ipconfig on a +remote computer. -When you start a Windows program on a remote computer, the command is not completed, and the Windows PowerShell command prompt does not return, until the program is finished or until you press CTRL\+C to interrupt the command. For example, if you run the IpConfig program on a remote computer, the command prompt does not return until IpConfig is completed. +However, you cannot use Windows PowerShell commands to open the user interface +for any program on a remote computer. -If you use remote commands to start a program that has a user interface, the program process starts, but the user interface does not appear. The Windows PowerShell command is not completed, and the command prompt does not return until you stop the program process or until you press CTRL\+C, which interrupts the command and stops the process. +When you start a Windows program on a remote computer, the command is not +completed, and the Windows PowerShell command prompt does not return, until +the program is finished or until you press CTRL\+C to interrupt the command. +For example, if you run the IpConfig program on a remote computer, the command +prompt does not return until IpConfig is completed. -For example, if you use a Windows PowerShell command to run Notepad on a remote computer, the Notepad process starts on the remote computer, but the Notepad user interface does not appear. To interrupt the command and restore the command prompt, press CTRL\+C. +If you use remote commands to start a program that has a user interface, the +program process starts, but the user interface does not appear. The Windows +PowerShell command is not completed, and the command prompt does not return +until you stop the program process or until you press CTRL\+C, which +interrupts the command and stops the process. +For example, if you use a Windows PowerShell command to run Notepad on a +remote computer, the Notepad process starts on the remote computer, but the +Notepad user interface does not appear. To interrupt the command and restore +the command prompt, press CTRL\+C. ### CAN I LIMIT THE COMMANDS THAT USERS CAN RUN REMOTELY ON MY COMPUTER? -Yes. Every remote session must use one of the session configurations on the remote computer. You can manage the session configurations on your computer (and the permissions to those session configurations) to determine who can run commands remotely on your computer and which commands they can run. - -A session configuration configures the environment for the session. You can define the configuration by using an assembly that implements a new configuration class or by using a script that runs in the session. The configuration can determine the commands that are available in the session. And, the configuration can include settings that protect the computer, such as settings that limit the amount of data that the session can receive remotely in a single object or command. You can also specify a security descriptor that determines the permissions that are required to use the configuration. - -The Enable-PSRemoting cmdlet creates the default session configurations on your computer: Microsoft.PowerShell, Microsoft.PowerShell.Workflow, and Microsoft.PowerShell32 (64-bit operating systems only). Enable-PSRemoting sets the security descriptor for the configuration to allow only members of the Administrators group on your computer to use them. - -You can use the session configuration cmdlets to edit the default session configurations, to create new session configurations, and to change the security descriptors of all the session configurations. -Beginning in Windows PowerShell 3.0, the New-PSSessionConfigurationFile cmdlet lets you create custom session configurations by using a text file. The file includes options for setting the language mode and for specifying the cmdlets and modules that are available in sessions that use the session configuration. - -When users use the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets, they can use the ConfigurationName parameter to indicate the session configuration that is used for the session. And, they can change the default configuration that their sessions use by changing the value of the $PSSessionConfigurationName preference variable in the session. - -For more information about session configurations, see the Help for the session configuration cmdlets. To find the session configuration cmdlets, type: - - -``` +Yes. Every remote session must use one of the session configurations on the +remote computer. You can manage the session configurations on your computer +(and the permissions to those session configurations) to determine who can run +commands remotely on your computer and which commands they can run. + +A session configuration configures the environment for the session. You can +define the configuration by using an assembly that implements a new +configuration class or by using a script that runs in the session. The +configuration can determine the commands that are available in the session. +And, the configuration can include settings that protect the computer, such as +settings that limit the amount of data that the session can receive remotely +in a single object or command. You can also specify a security descriptor that +determines the permissions that are required to use the configuration. + +The Enable-PSRemoting cmdlet creates the default session configurations on +your computer: Microsoft.PowerShell, Microsoft.PowerShell.Workflow, and +Microsoft.PowerShell32 (64-bit operating systems only). Enable-PSRemoting sets +the security descriptor for the configuration to allow only members of the +Administrators group on your computer to use them. + +You can use the session configuration cmdlets to edit the default session +configurations, to create new session configurations, and to change the +security descriptors of all the session configurations. + +Beginning in Windows PowerShell 3.0, the New-PSSessionConfigurationFile cmdlet +lets you create custom session configurations by using a text file. The file +includes options for setting the language mode and for specifying the cmdlets +and modules that are available in sessions that use the session configuration. + +When users use the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets, +they can use the ConfigurationName parameter to indicate the session +configuration that is used for the session. And, they can change the default +configuration that their sessions use by changing the value of the +$PSSessionConfigurationName preference variable in the session. + +For more information about session configurations, see the Help for the +session configuration cmdlets. To find the session configuration cmdlets, +type: + +```powershell Get-Command *PSSessionConfiguration ``` - - ### WHAT ARE FAN-IN AND FAN OUT CONFIGURATIONS? -The most common Windows PowerShell remoting scenario involving multiple computers is the one-to-many configuration, in which one local computer (the administrator's computer) runs Windows PowerShell commands on numerous remote computers. This is known as the "fan-out" scenario. -However, in some enterprises, the configuration is many-to-one, where many client computers connect to a single remote computer that is running Windows PowerShell, such as a file server or a kiosk. This is known as the "fan-in" configuration. +The most common Windows PowerShell remoting scenario involving multiple +computers is the one-to-many configuration, in which one local computer (the +administrator's computer) runs Windows PowerShell commands on numerous remote +computers. This is known as the "fan-out" scenario. -Windows PowerShell remoting supports both fan-out and fan-in configurations. +However, in some enterprises, the configuration is many-to-one, where many +client computers connect to a single remote computer that is running Windows +PowerShell, such as a file server or a kiosk. This is known as the "fan-in" +configuration. -For the fan-out configuration, Windows PowerShell uses the Web Services for Management (WS-Management) protocol and the WinRM service that supports the Microsoft implementation of WS-Management. When a local computer connects to a remote computer, WS-Management establishes a connection and uses a plug-in for Windows PowerShell to start the Windows PowerShell host process (Wsmprovhost.exe) on the remote computer. The user can specify an alternate port, an alternate session configuration, and other features to customize the remote connection. +Windows PowerShell remoting supports both fan-out and fan-in configurations. -To support the "fan-in" configuration, Windows PowerShell uses Internet Information Services (IIS) to host WS-Management, to load the Windows PowerShell plug-in, and to start Windows PowerShell. In this scenario, instead of starting each Windows PowerShell session in a separate process, all Windows PowerShell sessions run in the same host process. +For the fan-out configuration, Windows PowerShell uses the Web Services for +Management (WS-Management) protocol and the WinRM service that supports the +Microsoft implementation of WS-Management. When a local computer connects to a +remote computer, WS-Management establishes a connection and uses a plug-in for +Windows PowerShell to start the Windows PowerShell host process +(Wsmprovhost.exe) on the remote computer. The user can specify an alternate +port, an alternate session configuration, and other features to customize the +remote connection. -IIS hosting and fan-in remote management is not supported in Windows XP or in Windows Server 2003. +To support the "fan-in" configuration, Windows PowerShell uses Internet +Information Services (IIS) to host WS-Management, to load the Windows +PowerShell plug-in, and to start Windows PowerShell. In this scenario, instead +of starting each Windows PowerShell session in a separate process, all Windows +PowerShell sessions run in the same host process. -In a fan-in configuration, the user can specify a connection URI and an HTTP endpoint, including the transport, computer name, port, and application name. IIS forwards all the requests with a specified application name to the application. The default is WS-Management, which can host Windows PowerShell. +IIS hosting and fan-in remote management is not supported in Windows XP or in +Windows Server 2003. -You can also specify an authentication mechanism and prohibit or allow redirection from HTTP and HTTPS endpoints. +In a fan-in configuration, the user can specify a connection URI and an HTTP +endpoint, including the transport, computer name, port, and application name. +IIS forwards all the requests with a specified application name to the +application. The default is WS-Management, which can host Windows PowerShell. +You can also specify an authentication mechanism and prohibit or allow +redirection from HTTP and HTTPS endpoints. ### CAN I TEST REMOTING ON A SINGLE COMPUTER \(NOT IN A DOMAIN\)? -Yes. Windows PowerShell remoting is available even when the local computer is not in a domain. You can use the remoting features to connect to sessions and to create sessions on the same computer. The features work the same as they do when you connect to a remote computer. -To run remote commands on a computer in a workgroup, change the following Windows settings on the computer. +Yes. Windows PowerShell remoting is available even when the local computer is +not in a domain. You can use the remoting features to connect to sessions and +to create sessions on the same computer. The features work the same as they do +when you connect to a remote computer. -Caution: These settings affect all users on the system and they can make the system more vulnerable to a malicious attack. Use caution when making these changes. +To run remote commands on a computer in a workgroup, change the following +Windows settings on the computer. --- Windows XP with SP2: +Caution: These settings affect all users on the system and they can make the +system more vulnerable to a malicious attack. Use caution when making these +changes. -Use Local Security Settings (Secpol.msc) to change the setting of the "Network Access: Sharing and security model for local accounts" policy in Security Settings\Local Policies\Security Options to "Classic". +- Windows XP with SP2: --- Windows Vista, Windows 7, Windows 8: + Use Local Security Settings (Secpol.msc) to change the setting of the + "Network Access: Sharing and security model for local accounts" policy in + Security Settings\Local Policies\Security Options to "Classic". -Create the following registry entry, and then set its value to 1: LocalAccountTokenFilterPolicy in HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System +- Windows Vista, Windows 7, Windows 8: -You can use the following Windows PowerShell command to add this entry: + Create the following registry entry, and then set its value to 1: + LocalAccountTokenFilterPolicy in + HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System -New-ItemProperty ` -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System ` -Name LocalAccountTokenFilterPolicy -propertyType DWord -Value 1 + You can use the following Windows PowerShell command to add this entry: --- Windows Server 2003, Windows Server 2008, Windows Server 2012, Windows Server 2012 R2: + ```powershell + $parameters = @{ + Path='HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System' + Name='LocalAccountTokenFilterPolicy' + propertyType='DWord' + Value=1 + } + New-ItemProperty @parameters + ``` -No changes are needed because the default setting of the "Network Access: Sharing and security model for local accounts" policy is "Classic". Verify the setting in case it has changed. +- Windows Server 2003, Windows Server 2008, Windows Server 2012, Windows + Server 2012 R2: + No changes are needed because the default setting of the "Network Access: + Sharing and security model for local accounts" policy is "Classic". Verify + the setting in case it has changed. ### CAN I RUN REMOTE COMMANDS ON A COMPUTER IN ANOTHER DOMAIN? -Yes. Typically, the commands run without error, although you might need to use the Credential parameter of the Invoke-Command, New-PSSession, or Enter-PSSession cmdlets to provide the credentials of a member of the Administrators group on the remote computer. This is sometimes required even when the current user is a member of the Administrators group on the local and remote computers. -However, if the remote computer is not in a domain that the local computer trusts, the remote computer might not be able to authenticate the user's credentials. +Yes. Typically, the commands run without error, although you might need to use +the **Credential** parameter of the `Invoke-Command`, `New-PSSession`, or +`Enter-PSSession` cmdlets to provide the credentials of a member of the +Administrators group on the remote computer. This is sometimes required even +when the current user is a member of the Administrators group on the local and +remote computers. -To enable authentication, use the following command to add the remote computer to the list of trusted hosts for the local computer in WinRM. Type the command at the Windows PowerShell prompt. +However, if the remote computer is not in a domain that the local computer +trusts, the remote computer might not be able to authenticate the user's +credentials. +To enable authentication, use the following command to add the remote computer +to the list of trusted hosts for the local computer in WinRM. Type the command +at the Windows PowerShell prompt. -``` +```powershell Set-Item WSMan:\localhost\Client\TrustedHosts -Value ``` +For example, to add the Server01 computer to the list of trusted hosts on the +local computer, type the following command at the Windows PowerShell prompt: -For example, to add the Server01 computer to the list of trusted hosts on the local computer, type the following command at the Windows PowerShell prompt: - - -``` +```powershell Set-Item WSMan:\localhost\Client\TrustedHosts -Value Server01 ``` - - ## SEE ALSO [about_Remote](about_Remote.md) @@ -357,7 +525,7 @@ Set-Item WSMan:\localhost\Client\TrustedHosts -Value Server01 [about_Remote_Variables](about_Remote_Variables.md) -Invoke-Command +[Invoke-Command](../Invoke-Command.md) -New-PSSession +[New-PSSession](../New-PSSession.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md index ea1d750215a..91f9354775f 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Remote_Jobs.md @@ -1,5 +1,5 @@ --- -ms.date: 2017-06-09 +ms.date: 2017-12-01 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,272 +7,338 @@ title: about_Remote_Jobs --- # About Remote Jobs -## about_Remote_Jobs - ## SHORT DESCRIPTION -Describes how to run background jobs on remote computers. +Describes how to run background jobs on remote computers. ## DETAILED DESCRIPTION -A background job is a command that runs asynchronously without interacting with the current session. The command prompt returns immediately, and you can continue to use the session while the job runs. -By default, background jobs run on the local computer. However, you can use several different procedures to run background jobs on remote computers. +A background job is a command that runs asynchronously without interacting +with the current session. The command prompt returns immediately, and you can +continue to use the session while the job runs. -This topic explains how to run a background job on a remote computer. For information about how to run background jobs on a local computer, see about_Jobs. For more information about background jobs, see about_Job_Details. +By default, background jobs run on the local computer. However, you can use +several different procedures to run background jobs on remote computers. +This topic explains how to run a background job on a remote computer. For +information about how to run background jobs on a local computer, see +[about_Jobs](about_Jobs.md). For more information about background jobs, see +[about_Job_Details](about_Job_Details.md). ## REMOTE BACKGROUND JOBS -You can run background jobs on remote computers by using three different methods. --- Start an interactive session with a remote computer, and start a job in the interactive session. The procedures are the same as running a local job, although all actions are performed on the remote computer. +You can run background jobs on remote computers by using three different +methods. --- Run a background job on a remote computer that returns its results to the local computer. Use this method when you want to collect the results of background jobs and maintain them in a central location on the local computer. +- Start an interactive session with a remote computer, and start a job in the + interactive session. The procedures are the same as running a local job, + although all actions are performed on the remote computer. --- Run a background job on a remote computer that maintains its results on the remote computer. Use this method when the job data is more securely maintained on the originating computer. +- Run a background job on a remote computer that returns its results to the + local computer. Use this method when you want to collect the results of + background jobs and maintain them in a central location on the local computer. +- Run a background job on a remote computer that maintains its results on the + remote computer. Use this method when the job data is more securely maintained + on the originating computer. ### START A BACKGROUND JOB IN AN INTERACTIVE SESSION -You can start an interactive session with a remote computer and then start a background job during the interactive session. For more information about interactive sessions, see about_Remote, and see Enter-PSSession. -The procedure for starting a background job in an interactive session is almost identical to the procedure for starting a background job on the local computer. However, all of the operations occur on the remote computer, not the local computer. +You can start an interactive session with a remote computer and then start a +background job during the interactive session. For more information about +interactive sessions, see about_Remote, and see Enter-PSSession. +The procedure for starting a background job in an interactive session is +almost identical to the procedure for starting a background job on the local +computer. However, all of the operations occur on the remote computer, not the +local computer. #### STEP 1: ENTER-PSSESSION -Use the Enter-PSSession cmdlet to start an interactive session with a remote computer. You can use the ComputerName parameter of Enter-PSSession to establish a temporary connection for the interactive session. Or, you can use the Session parameter to run the interactive session in a Windows PowerShell session (PSSession). -The following command starts an interactive session on the Server01 computer. +Use the Enter-PSSession cmdlet to start an interactive session with a remote +computer. You can use the ComputerName parameter of Enter-PSSession to +establish a temporary connection for the interactive session. Or, you can use +the Session parameter to run the interactive session in a Windows PowerShell +session (PSSession). +The following command starts an interactive session on the Server01 computer. -``` +```powershell C:\PS> Enter-PSSession -computername Server01 ``` - -The command prompt changes to show that you are now connected to the Server01 computer. - +The command prompt changes to show that you are now connected to the Server01 +computer. ``` Server01\C:> ``` - - #### STEP 2: START-JOB -To start a background job in the session, use the Start-Job cmdlet. -The following command runs a background job that gets the events in the Windows PowerShell event log on the Server01 computer. The Start-Job cmdlet returns an object that represents the job. +To start a background job in the session, use the Start-Job cmdlet. -This command saves the job object in the $job variable. +The following command runs a background job that gets the events in the +Windows PowerShell event log on the Server01 computer. The Start-Job cmdlet +returns an object that represents the job. +This command saves the job object in the \$job variable. -``` -Server01\C:> $job = start-job -scriptblock {get-eventlog "Windows PowerShell"} +```powershell +Server01\C:> $job = start-job -scriptblock { + get-eventlog "Windows PowerShell" +} ``` - -While the job runs, you can use the interactive session to run other commands, including other background jobs. However, you must keep the interactive session open until the job is completed. If you end the session, the job is interrupted, and the results are lost. - +While the job runs, you can use the interactive session to run other commands, +including other background jobs. However, you must keep the interactive +session open until the job is completed. If you end the session, the job is +interrupted, and the results are lost. #### STEP 3: GET-JOB -To find out if the job is complete, display the value of the $job variable, or use the Get-Job cmdlet to get the job. The following command uses the Get-Job cmdlet to display the job. +To find out if the job is complete, display the value of the \$job variable, +or use the Get-Job cmdlet to get the job. The following command uses the +Get-Job cmdlet to display the job. -``` -Server01\C:> get-job $job - -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Complete True localhost get-eventlog "Windows PowerShell" -``` - +```powershell +Server01\C:> get-job $job -The Get-Job output shows that job is running on the "localhost" computer because the job was started on and is running on the same computer (in this case, Server01). +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Complete True localhost get-eventlog "Windows... +``` +The Get-Job output shows that job is running on the "localhost" computer +because the job was started on and is running on the same computer (in this +case, Server01). #### STEP 4: RECEIVE-JOB -To get the results of the job, use the Receive-Job cmdlet. You can display the results in the interactive session or save them to a file on the remote computer. The following command gets the results of the job in the $job variable. The command uses the redirection operator (>) to save the results of the job in the PsLog.txt file on the Server01 computer. +To get the results of the job, use the Receive-Job cmdlet. You can display the +results in the interactive session or save them to a file on the remote +computer. The following command gets the results of the job in the $job +variable. The command uses the redirection operator (>) to save the results of +the job in the PsLog.txt file on the Server01 computer. -``` +```powershell Server01\C:> receive-job $job > c:\logs\PsLog.txt ``` - - #### STEP 5: EXIT-PSSESSION -To end the interactive session, use the Exit-PSSession cmdlet. The command prompt changes to show that you are back in the original session on the local computer. +To end the interactive session, use the Exit-PSSession cmdlet. The command +prompt changes to show that you are back in the original session on the local +computer. -``` -Server01\C:> Exit-PSSession +```powershell +Server01\C:> Exit-PSSession C:\PS> ``` - - #### STEP 6: INVOKE-COMMAND: GET-CONTENT -To view the contents of the PsLog.txt file on the Server01 computer at any time, start another interactive session, or run a remote command. This type of command is best run in a PSSession (a persistent connection) in case you want to use several commands to investigate and manage the data in the PsLog.txt file. For more information about PSSessions, see about_PSSessions. -The following commands use the New-PSSession cmdlet to create a PSSession that is connected to the Server01 computer, and they use the Invoke-Command cmdlet to run a Get-Content command in the PSSession to view the contents of the file. +To view the contents of the PsLog.txt file on the Server01 computer at any +time, start another interactive session, or run a remote command. This type of +command is best run in a PSSession (a persistent connection) in case you want +to use several commands to investigate and manage the data in the PsLog.txt +file. For more information about PSSessions, see about_PSSessions. +The following commands use the New-PSSession cmdlet to create a PSSession that +is connected to the Server01 computer, and they use the Invoke-Command cmdlet +to run a Get-Content command in the PSSession to view the contents of the +file. +```powershell +$s = new-pssession -computername Server01 +invoke-command -session $s -scriptblock { + get-content c:\logs\pslog.txt} ``` -C:\PS> $s = new-pssession -computername Server01 -C:\PS> invoke-command -session $s -scriptblock {get-content c:\logs\pslog.txt} -``` - - ### START A REMOTE JOB THAT RETURNS THE RESULTS TO THE LOCAL COMPUTER \(ASJOB\) -To start a background job on a remote computer that returns the command results to the local computer, use the AsJob parameter of a cmdlet such as the Invoke-Command cmdlet. -When you use the AsJob parameter, the job object is actually created on the local computer even though the job runs on the remote computer. When the job is completed, the results are returned to the local computer. +To start a background job on a remote computer that returns the command +results to the local computer, use the AsJob parameter of a cmdlet such as the +Invoke-Command cmdlet. -You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage any job created by any cmdlet. Many of the cmdlets that have AsJob parameters do not use Windows PowerShell remoting, so you can use them even on computers that are not configured for remoting and that do not meet the requirements for remoting. +When you use the AsJob parameter, the job object is actually created on the +local computer even though the job runs on the remote computer. When the job +is completed, the results are returned to the local computer. +You can use the cmdlets that contain the Job noun (the Job cmdlets) to manage +any job created by any cmdlet. Many of the cmdlets that have AsJob parameters +do not use Windows PowerShell remoting, so you can use them even on computers +that are not configured for remoting and that do not meet the requirements for +remoting. #### STEP 1: INVOKE-COMMAND -ASJOB -The following command uses the AsJob parameter of Invoke-Command to start a background job on the Server01 computer. The job runs a Get-Eventlog command that gets the events in the System log. You can use the JobName parameter to assign a display name to the job. +The following command uses the AsJob parameter of Invoke-Command to start a +background job on the Server01 computer. The job runs a Get-Eventlog command +that gets the events in the System log. You can use the JobName parameter to +assign a display name to the job. -``` -invoke-command -computername Server01 -scriptblock {get-eventlog system} -asjob +```powershell +invoke-command -computername Server01 -scriptblock { + get-eventlog system} -asjob ``` - The results of the command resemble the following sample output. - +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Running True Server01 get-eventlog system ``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Running True Server01 get-eventlog system -``` - -When the AsJob parameter is used, Invoke-Command returns the same type of job object that Start-Job returns. You can save the job object in a variable, or you can use a Get-Job command to get the job. - -Note that the value of the Location property shows that the job ran on the Server01 computer. +When the AsJob parameter is used, Invoke-Command returns the same type of job +object that Start-Job returns. You can save the job object in a variable, or +you can use a Get-Job command to get the job. +Note that the value of the Location property shows that the job ran on the +Server01 computer. #### STEP 2: GET-JOB -To manage a job started by using the AsJob parameter of the Invoke-Command cmdlet, use the Job cmdlets. Because the job object that represents the remote job is on the local computer, you do not need to run remote commands to manage the job. -To determine whether the job is complete, use a Get-Job command. The following command gets all of the jobs that were started in the current session. +To manage a job started by using the AsJob parameter of the Invoke-Command +cmdlet, use the Job cmdlets. Because the job object that represents the remote +job is on the local computer, you do not need to run remote commands to manage +the job. +To determine whether the job is complete, use a Get-Job command. The following +command gets all of the jobs that were started in the current session. -``` +```powershell get-job ``` +Because the remote job was started in the current session, a local Get-Job +command gets the job. The State property of the job object shows that the +command was completed successfully. -Because the remote job was started in the current session, a local Get-Job command gets the job. The State property of the job object shows that the command was completed successfully. - - -``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -1 Job1 Completed True Server01 get-eventlog system +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +1 Job1 Completed True Server01 get-eventlog system ``` - - #### STEP 3: RECEIVE-JOB -To get the results of the job, use the Receive-Job cmdlet. Because the job results are automatically returned to the computer where the job object resides, you can get the results with a local Receive-Job command. -The following command uses the Receive-Job cmdlet to get the results of the job. It uses the session ID to identify the job. This command saves the job results in the $results variable. You can also redirect the results to a file. +To get the results of the job, use the Receive-Job cmdlet. Because the job +results are automatically returned to the computer where the job object +resides, you can get the results with a local Receive-Job command. +The following command uses the Receive-Job cmdlet to get the results of the +job. It uses the session ID to identify the job. This command saves the job +results in the $results variable. You can also redirect the results to a file. -``` +```powershell $results = receive-job -id 1 ``` - - ### START A REMOTE JOB THAT KEEPS THE RESULTS ON THE REMOTE COMPUTER -To start a background job on a remote computer that keeps the command results on the remote computer, use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. You can use this method to run background jobs on multiple computers. -When you run a Start-Job command remotely, the job object is created on the remote computer, and the job results are maintained on the remote computer. From the perspective of the job, all operations are local. You are just running commands remotely to manage a local job on the remote computer. +To start a background job on a remote computer that keeps the command results +on the remote computer, use the Invoke-Command cmdlet to run a Start-Job +command on a remote computer. You can use this method to run background jobs +on multiple computers. +When you run a Start-Job command remotely, the job object is created on the +remote computer, and the job results are maintained on the remote computer. +From the perspective of the job, all operations are local. You are just +running commands remotely to manage a local job on the remote computer. #### STEP 1: INVOKE-COMMAND START-JOB -Use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. -This command requires a PSSession (a persistent connection). If you use the ComputerName parameter of Invoke-Command to establish a temporary connection, the Invoke-Command command is considered to be complete when the job object is returned. As a result, the temporary connection is closed, and the job is canceled. +Use the Invoke-Command cmdlet to run a Start-Job command on a remote computer. -The following command uses the New-PSSession cmdlet to create a PSSession that is connected to the Server01 computer. The command saves the PSSession in the $s variable +This command requires a PSSession (a persistent connection). If you use the +ComputerName parameter of Invoke-Command to establish a temporary connection, +the Invoke-Command command is considered to be complete when the job object is +returned. As a result, the temporary connection is closed, and the job is +canceled. +The following command uses the New-PSSession cmdlet to create a PSSession that +is connected to the Server01 computer. The command saves the PSSession in the +\$s variable. -``` +```powershell $s = new-pssession -computername Server01 ``` +The next command uses the Invoke-Command cmdlet to run a Start-Job command in +the PSSession. The Start-Job command and the Get-Eventlog command are enclosed +in braces. -The next command uses the Invoke-Command cmdlet to run a Start-Job command in the PSSession. The Start-Job command and the Get-Eventlog command are enclosed in braces. - - +```powershell +invoke-command -session $s -scriptblock { + start-job -scriptblock {get-eventlog system}} ``` -invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog system}} -``` - The results resemble the following sample output. - -``` -Id Name State HasMoreData Location Command --- ---- ----- ----------- -------- ------- +```Output +Id Name State HasMoreData Location Command +-- ---- ----- ----------- -------- ------- 2 Job2 Running True Localhost get-eventlog system ``` +When you run a Start-Job command remotely, Invoke-Command returns the same +type of job object that Start-Job returns. You can save the job object in a +variable, or you can use a Get-Job command to get the job. -When you run a Start-Job command remotely, Invoke-Command returns the same type of job object that Start-Job returns. You can save the job object in a variable, or you can use a Get-Job command to get the job. - -Note that the value of the Location property shows that the job ran on the local computer, known as "LocalHost", even though the job ran on the Server01 computer. Because the job object is created on the Server01 computer and the job runs on the same computer, it is considered to be a local background job. - +Note that the value of the Location property shows that the job ran on the +local computer, known as "LocalHost", even though the job ran on the Server01 +computer. Because the job object is created on the Server01 computer and the +job runs on the same computer, it is considered to be a local background job. #### STEP 2: INVOKE-COMMAND GET-JOB -To manage a remote background job, use the Job cmdlets. Because the job object is on the remote computer, you need to run remote commands to get, stop, wait for, or retrieve the job results. -To see if the job is complete, use an Invoke-Command command to run a Get-Job command in the PSSession that is connected to the Server01 computer. +To manage a remote background job, use the Job cmdlets. Because the job object +is on the remote computer, you need to run remote commands to get, stop, wait +for, or retrieve the job results. +To see if the job is complete, use an Invoke-Command command to run a Get-Job +command in the PSSession that is connected to the Server01 computer. -``` +```powershell invoke-command -session $s -scriptblock {get-job} ``` +The command returns a job object. The State property of the job object shows +that the command was completed successfully. -The command returns a job object. The State property of the job object shows that the command was completed successfully. - - +```Output +SessionId Name State HasMoreData Location Command +--------- ---- ----- ----------- -------- ------- +2 Job2 Completed True LocalHost get-eventlog system ``` -SessionId Name State HasMoreData Location Command ---------- ---- ----- ----------- -------- ------- -2 Job2 Completed True LocalHost get-eventlog system -``` - - #### STEP 3: INVOKE-COMMAND RECEIVE-JOB -To get the results of the job, use the Invoke-Command cmdlet to run a Receive-Job command in the PSSession that is connected to the Server01 computer. -The following command uses the Receive-Job cmdlet to get the results of the job. It uses the session ID to identify the job. This command saves the job results in the $results variable. It uses the Keep parameter of Receive-Job to keep the result in the job cache on the remote computer. +To get the results of the job, use the Invoke-Command cmdlet to run a +Receive-Job command in the PSSession that is connected to the Server01 +computer. +The following command uses the Receive-Job cmdlet to get the results of the +job. It uses the session ID to identify the job. This command saves the job +results in the \$results variable. It uses the Keep parameter of Receive-Job +to keep the result in the job cache on the remote computer. +```powershell +$results = invoke-command -session $s -scriptblock { + receive-job -sessionid 2 -keep} ``` -$results = invoke-command -session $s -scriptblock {receive-job -sessionid 2 -keep} -``` - - -You can also redirect the results to a file on the local or remote computer. The following command uses a redirection operator to save the results in a file on the Server01 computer. +You can also redirect the results to a file on the local or remote computer. +The following command uses a redirection operator to save the results in a +file on the Server01 computer. +```powershell +invoke-command -session $s -command { + receive-job -sessionid 2 > c:\logs\pslog.txt} ``` -invoke-command -session $s -command {receive-job -sessionid 2 > c:\logs\pslog.txt} -``` - - ## SEE ALSO @@ -284,21 +350,20 @@ invoke-command -session $s -command {receive-job -sessionid 2 > c:\logs\pslog.tx [about_Remote_Variables](about_Remote_Variables.md) -Invoke-Command - -Start-Job +[Invoke-Command](../Invoke-Command.md) -Get-Job +[Start-Job](../Start-Job.md) -Wait-Job +[Get-Job](../Get-Job.md) -Stop-Job +[Wait-Job](../Wait-Job.md) -Remove-Job +[Stop-Job](../Stop-Job.md) -New-PSSession +[Remove-Job](../Remove-Job.md) -Enter-PSSession +[New-PSSession](../New-PSSession.md) -Exit-PSSession +[Enter-PSSession](../Enter-PSSession.md) +[Exit-PSSession](../Exit-PSSession.md)