diff --git a/reference/3.0/Microsoft.PowerShell.Core/Out-Default.md b/reference/3.0/Microsoft.PowerShell.Core/Out-Default.md index a244ab732a16..b53fe4379ad7 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Out-Default.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Out-Default.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113362 external help file: System.Management.Automation.dll-Help.xml title: Out-Default --- - # Out-Default + ## SYNOPSIS + Sends the output to the default formatter and to the default output cmdlet. + ## SYNTAX ``` @@ -18,12 +20,15 @@ Out-Default [-InputObject ] [] ``` ## DESCRIPTION + The **Out-Default** cmdlet sends output to the default formatter and the default output cmdlet. This cmdlet has no effect on the formatting or output of Windows PowerShell commands. It is a placeholder that lets you write your own **Out-Default** function or cmdlet. + ## EXAMPLES ### 1: + ``` ``` @@ -31,6 +36,7 @@ It is a placeholder that lets you write your own **Out-Default** function or cmd ## PARAMETERS ### -InputObject + Accepts input to the cmdlet. ```yaml @@ -46,7 +52,9 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ## OUTPUTS diff --git a/reference/3.0/Microsoft.PowerShell.Core/Out-Host.md b/reference/3.0/Microsoft.PowerShell.Core/Out-Host.md index b54781ecdfdc..49ff5bff04dc 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Out-Host.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Out-Host.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113365 external help file: System.Management.Automation.dll-Help.xml title: Out-Host --- - # Out-Host + ## SYNOPSIS + Sends output to the command line. + ## SYNTAX ``` @@ -18,14 +20,17 @@ Out-Host [-Paging] [-InputObject ] [] ``` ## DESCRIPTION + The **Out-Host** cmdlet sends output to the Windows PowerShell host for display. The host displays the output at the command line. Because **Out-Host** is the default, you do not need to specify it unless you want to use its parameters to change the display. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Get-Process | Out-Host -Paging +PS> Get-Process | Out-Host -Paging ``` This command displays the processes on the system one page at a time. @@ -35,18 +40,22 @@ The **Paging** parameter displays one page of data at a time. The same command format is used for the Help function that is built into Windows PowerShell. That function gets data from the Get-Help cmdlet and then uses the **Paging** parameter of **Out-Host** to display the data one page at a time by using this command format: `Get-Help $Args\[0\] | Out-Host -Paging`. + ### Example 2 + ``` -PS C:\> $a = Get-History -PS C:\> Out-Host -InputObject $a +PS> $a = Get-History +PS> Out-Host -InputObject $a ``` These commands display the session history at the command line. The first command uses the Get-History cmdlet to get the session history, and then it stores the history in the $a variable. The second command uses **Out-Host** to display the content of the $a variable, and it uses the **InputObject** parameter to specify the variable to **Out-Host**. + ## PARAMETERS ### -InputObject + Specifies the objects that are written to the console. Enter a variable that contains the objects, or type a command or expression that gets the objects. @@ -63,6 +72,7 @@ Accept wildcard characters: False ``` ### -Paging + Displays one page of output at a time, and waits for user input before displaying the remaining pages, much like the traditional "more" command. By default, all of the output is displayed on a single page. The page size is determined by the characteristics of the host. @@ -80,22 +90,30 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.PSObject + You can pipe any object to **Out-Host**. + ## OUTPUTS ### None + **Out-Host** does not generate any output. However, the host might display the objects that **Out-Host** sends to it. + ## NOTES -* The cmdlets that contain the Out verb (the Out cmdlets) do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. -* The Out cmdlets do not have parameters for names or file paths. To send data to an Out cmdlet, use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. For help, see the examples. -* **Out-Host** sends data, but it does not emit any output objects. If you pipe the output of **Out-Host** to the Get-Member cmdlet, **Get-Member** reports that no objects have been specified. -* +- The cmdlets that contain the Out verb (the Out cmdlets) do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. +- The Out cmdlets do not have parameters for names or file paths. To send data to an Out cmdlet, use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. For help, see the examples. +- **Out-Host** sends data, but it does not emit any output objects. If you pipe the output of **Out-Host** to the Get-Member cmdlet, **Get-Member** reports that no objects have been specified. + +- + ## RELATED LINKS [Clear-Host](Functions/Clear-Host.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Out-Null.md b/reference/3.0/Microsoft.PowerShell.Core/Out-Null.md index 2a7d2838ef67..48f3f734ba15 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Out-Null.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Out-Null.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113366 external help file: System.Management.Automation.dll-Help.xml title: Out-Null --- - # Out-Null + ## SYNOPSIS + Hides the output instead of sending it down the pipeline or displaying it. + ## SYNTAX ``` @@ -18,21 +20,26 @@ Out-Null [-InputObject ] [] ``` ## DESCRIPTION + The **Out-Null** cmdlet sends its output to NULL, in effect, removing it from the pipeline and preventing the output to be displayed at the screen. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Get-ChildItem | Out-Null +PS> Get-ChildItem | Out-Null ``` This command gets items in the current location/directory, but its output is not passed through the pipeline nor displayed at the command line. This is useful for hiding output that you do not need. + ## PARAMETERS ### -InputObject + Specifies the object to be sent to NULL (removed from pipeline). Enter a variable that contains the objects, or type a command or expression that gets the objects. @@ -49,22 +56,30 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.PSObject + You can pipe any object to **Out-Null**. + ## OUTPUTS ### None + **Out-Null** does not generate any output. + ## NOTES -* The cmdlets that contain the Out verb (the Out cmdlets) do not have parameters for names or file paths. To send data to an Out cmdlet, use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. For more information, see the examples. -* +- The cmdlets that contain the Out verb (the Out cmdlets) do not have parameters for names or file paths. To send data to an Out cmdlet, use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet. For more information, see the examples. + +- **Out-Null** does not return any output objects. If you pipe the output of **Out-Null** to the Get-Member cmdlet, **Get-Member** reports that no objects have been specified. + ## RELATED LINKS [Out-Default](Out-Default.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md b/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md index eb78f029b3f4..b64418827072 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Receive-Job.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,49 +7,58 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113372 external help file: System.Management.Automation.dll-Help.xml title: Receive-Job --- - # Receive-Job + ## SYNOPSIS + Gets the results of the Windows PowerShell background jobs in the current session. + ## SYNTAX ### Location (Default) + ``` Receive-Job [-Job] [[-Location] ] [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [] ``` ### ComputerName + ``` Receive-Job [-Job] [[-ComputerName] ] [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [] ``` ### Session + ``` Receive-Job [-Job] [[-Session] ] [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [] ``` ### NameParameterSet + ``` Receive-Job [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [-Name] [] ``` ### InstanceIdParameterSet + ``` Receive-Job [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [-InstanceId] [] ``` ### SessionIdParameterSet + ``` Receive-Job [-Keep] [-NoRecurse] [-Force] [-Wait] [-AutoRemoveJob] [-WriteEvents] [-WriteJobInResults] [-Id] [] ``` ## DESCRIPTION + The **Receive-Job** cmdlet gets the results of Windows PowerShell background jobs, such as those started by using the Start-Job cmdlet or the **AsJob** parameter of any cmdlet. You can get the results of all jobs or identify jobs by their name, ID, instance ID, computer name, location, or session, or by submitting a job object. @@ -68,12 +77,14 @@ To delete the job results, run the **Receive-Job** command again (without the ** Beginning in Windows PowerShell 3.0, **Receive-Job** also gets the results of custom job types, such as workflow jobs and instances of scheduled jobs. To enable **Receive-Job** to get the results a custom job type, import the module that supports the custom job type into the session before running a **Receive-Job** command, either by using the Import-Module cmdlet or by using or getting a cmdlet in the module. For information about a particular custom job type, see the documentation of the custom job type feature. + ## EXAMPLES ### Example 1 + ``` -PS C:\> $job = Start-Job -ScriptBlock {Get-Process} -PS C:\> Receive-Job -Job $job +PS> $job = Start-Job -ScriptBlock {Get-Process} +PS> Receive-Job -Job $job ``` These commands use the **Job** parameter of **Receive-Job** to get the results of a particular job. @@ -83,24 +94,28 @@ The command uses the assignment operator (=) to save the resulting job object in The second command uses the **Receive-Job** cmdlet to get the results of the job. It uses the **Job** parameter to specify the job. + ### Example 2 + ``` -PS C:\> $job = Start-Job -ScriptBlock {Get-Process} -PS C:\> $job | Receive-Job +PS> $job = Start-Job -ScriptBlock {Get-Process} +PS> $job | Receive-Job ``` This example is the same as Example 2, except that the command uses a pipeline operator (|) to send the job object to **Receive-Job**. As a result, the command does not need a **Job** parameter to specify the job. + ### Example 3 + ``` The first command uses the Invoke-Command cmdlet to start a background job that runs a Get-Service command on three remote computers. The command uses the **AsJob** parameter to run the command as a background job. The command saves the resulting job object in the $j variable.When you use the **AsJob** parameter of **Invoke-Command** to start a job, the job object is created on the local computer, even though the job runs on the remote computers. As a result, you use local commands to manage the job.Also, when you use **AsJob**, Windows PowerShell returns one job object that contains a child job for each job that was started. In this case, the job object contains three child jobs, one for each job on each remote computer. -PS C:\> +PS> -PS C:\> $j = Invoke-Command -ComputerName Server01, Server02, Server03 -ScriptBlock {Get-Service} -AsJob +PS> $j = Invoke-Command -ComputerName Server01, Server02, Server03 -ScriptBlock {Get-Service} -AsJob The second command uses the dot method to display the value of the **ChildJobs** property of the job object in $j. The display shows that the command created three child jobs, one for the job on each remote computer. -PS C:\> $j.ChildJobs +PS> $j.ChildJobs Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- @@ -109,7 +124,7 @@ Id Name State HasMoreData Location Command 4 Job4 Completed True Server03 Get-Service The third command uses the **Receive-Job** cmdlet to get the results of the Job3 child job that ran on the Server02 computer. It uses the Name parameter to specify the name of the child job and the Keep parameter to save the job results even after they are received. -PS C:\> Receive-Job -Name Job3 -Keep +PS> Receive-Job -Name Job3 -Keep Status Name DisplayName PSComputerName ------ ----------- ----------- -------------- @@ -120,16 +135,18 @@ Running AppMgmt Application Management Server02 ``` These commands get the results of one of several background jobs run on remote computers. + ### Example 4 + ``` The first command uses the New-PSSession cmdlet to create three user-managed sessions ("PSSessions), one on each of the servers specified in the command. It saves the sessions in the $s variable. -PS C:\> $s = new-pssession -computername Server01, Server02, Server03 +PS> $s = new-pssession -computername Server01, Server02, Server03 The second command uses the Invoke-Command cmdlet to run a Start-Job command in each of the PSSessions in the $s variable. The job runs a Get-Eventlog command that gets the events in the System log. The command saves the results in the $j variable.Because the command used Invoke-Command to run the Start-Job command, the command actually started three independent jobs on each of the three computers. As a result, the command returned three job objects representing three jobs run locally on three different computers. -PS C:\> $j = invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog -logname system}} +PS> $j = invoke-command -session $s -scriptblock {start-job -scriptblock {get-eventlog -logname system}} The third command displays the three job objects in $j. -PS C:\> $j +PS> $j Id Name State HasMoreData Location Command -- ---- ----- ----------- -------- ------- @@ -139,13 +156,15 @@ Id Name State HasMoreData Location Command The fourth command uses Invoke-Command to run a **Receive-Job** command in each of the sessions in $s and save the results in the $Results variable.Because $j is a local variable, the script block uses the **Using** scope modifier to identify the $j variable. For more information about the **Using** scope modifier, see about_Remote_Variables (http://go.microsoft.com/fwlink/?LinkID=252653). -PS C:\> $results = Invoke-Command -Session $s -ScriptBlock {Receive-Job -Job $Using:j} +PS> $results = Invoke-Command -Session $s -ScriptBlock {Receive-Job -Job $Using:j} ``` This example shows how to get the results of background jobs run on three remote computers. + ## PARAMETERS ### -ComputerName + Gets the results of jobs that were run on the specified computers. Enter the computer names. Wildcards are supported. @@ -168,6 +187,7 @@ Accept wildcard characters: True ``` ### -Id + Gets the results of jobs with the specified IDs. The default is all jobs in the current session. @@ -189,6 +209,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Gets the results of jobs with the specified instance IDs. The default is all jobs in the current session. @@ -208,6 +229,7 @@ Accept wildcard characters: False ``` ### -Job + Specifies the job for which results are being retrieved. This parameter is required in a **Receive-Job** command. Enter a variable that contains the job or a command that gets the job. @@ -226,6 +248,7 @@ Accept wildcard characters: False ``` ### -Keep + Saves the job results in the system, even after you have received them. By default, the job results are deleted when they are retrieved. @@ -244,6 +267,7 @@ Accept wildcard characters: False ``` ### -Location + Gets only the results of jobs with the specified location. The default is all jobs in the current session. @@ -260,6 +284,7 @@ Accept wildcard characters: False ``` ### -Name + Gets the results of jobs with the specified friendly name. Wildcards are supported. The default is all jobs in the current session. @@ -277,6 +302,7 @@ Accept wildcard characters: True ``` ### -NoRecurse + Gets results only from the specified job. By default, **Receive-Job** also gets the results of all child jobs of the specified job. @@ -293,6 +319,7 @@ Accept wildcard characters: False ``` ### -Session + Gets the results of jobs that were run in the specified Windows Powershell session (PSSession). Enter a variable that contains the PSSession or a command that gets the PSSession, such as a Get-PSSession command. The default is all jobs in the current session. @@ -310,6 +337,7 @@ Accept wildcard characters: False ``` ### -Wait + Suppresses the command prompt until all job results are received. By default, **Receive-Job** immediately returns the available results. @@ -331,6 +359,7 @@ Accept wildcard characters: False ``` ### -AutoRemoveJob + Deletes the job after returning the job results. If the job has more results, the job is still deleted, but **Receive-Job** displays a message. @@ -354,6 +383,7 @@ Accept wildcard characters: False ``` ### -WriteEvents + Reports changes in the job state while waiting for the job to complete. This parameter is valid only when the **Wait** parameter is used in the command and the **Keep** parameter is omitted. @@ -373,6 +403,7 @@ Accept wildcard characters: False ``` ### -WriteJobInResults + Returns the job object followed by the results. This parameter is valid only when the **Wait** parameter is used in the command and the **Keep** parameter is omitted. @@ -392,6 +423,7 @@ Accept wildcard characters: False ``` ### -Force + Continues waiting if jobs are in the **Suspended** or **Disconnected** state. By default, the **Wait** parameter of **Receive-Job** returns (terminates the wait) when jobs are in one of the following states: Completed, Failed, Stopped, Suspended, or Disconnected. @@ -412,15 +444,21 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.Job + You can pipe job objects to **Receive-Job**. + ## OUTPUTS ### PSObject + **Receive-Job** returns the results of the commands in the job. + ## NOTES ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Core/Receive-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Receive-PSSession.md index 4aff204fb219..465c7fef28ad 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Receive-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Receive-PSSession.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,25 +7,30 @@ online version: http://go.microsoft.com/fwlink/?LinkID=217037 external help file: System.Management.Automation.dll-Help.xml title: Receive-PSSession --- - # Receive-PSSession + ## SYNOPSIS + Gets results of commands in disconnected sessions + ## SYNTAX ### Session (Default) + ``` Receive-PSSession [-Session] [-OutTarget ] [-JobName ] [-WhatIf] [-Confirm] [] ``` ### Id + ``` Receive-PSSession [-Id] [-OutTarget ] [-JobName ] [-WhatIf] [-Confirm] [] ``` ### ComputerSessionName + ``` Receive-PSSession [-ComputerName] [-ApplicationName ] [-ConfigurationName ] [-Name] [-OutTarget ] [-JobName ] [-Credential ] @@ -34,6 +39,7 @@ Receive-PSSession [-ComputerName] [-ApplicationName ] [-Configu ``` ### ComputerInstanceId + ``` Receive-PSSession [-ComputerName] [-ApplicationName ] [-ConfigurationName ] -InstanceId [-OutTarget ] [-JobName ] [-Credential ] @@ -42,6 +48,7 @@ Receive-PSSession [-ComputerName] [-ApplicationName ] [-Configu ``` ### ConnectionUriSessionName + ``` Receive-PSSession [-ConfigurationName ] [-ConnectionUri] [-AllowRedirection] [-Name] [-OutTarget ] [-JobName ] [-Credential ] @@ -50,6 +57,7 @@ Receive-PSSession [-ConfigurationName ] [-ConnectionUri] [-AllowRe ``` ### ConnectionUriInstanceId + ``` Receive-PSSession [-ConfigurationName ] [-ConnectionUri] [-AllowRedirection] -InstanceId [-OutTarget ] [-JobName ] [-Credential ] @@ -58,18 +66,21 @@ Receive-PSSession [-ConfigurationName ] [-ConnectionUri] [-AllowRe ``` ### InstanceId + ``` Receive-PSSession -InstanceId [-OutTarget ] [-JobName ] [-WhatIf] [-Confirm] [] ``` ### SessionName + ``` Receive-PSSession [-Name] [-OutTarget ] [-JobName ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Receive-PSSession** cmdlet gets the results of commands running in Windows PowerShell sessions ("PSSession") that were disconnected. If the session is currently connected, **Receive-PSSession** gets the results of commands that were running when the session was disconnected. If the session is still disconnected, **Receive-PSSession** connects to the session, resumes any commands that were suspended, and gets the results of commands running in the session. @@ -84,27 +95,33 @@ If you use the **Receive-PSSession** cmdlet to connect to a session in which no For more information about the Disconnected Sessions feature, see about_Remote_Disconnected_Sessions. This cmdlet is introduced in Windows PowerShell 3.0. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Receive-PSSession -ComputerName Server01 -Name ITTask +PS> Receive-PSSession -ComputerName Server01 -Name ITTask ``` This command uses the **Receive-PSSession** cmdlet to connect to the ITTask session on the Server01 computer and get the results of commands that were running in the session. Because the command does not use the **OutTarget** parameter, the results appear at the command line. + ### Example 2 + ``` -PS C:\> Get-PSSession -ComputerName Server01, Server02 | Receive-PSSession +PS> Get-PSSession -ComputerName Server01, Server02 | Receive-PSSession ``` This command gets the results of all commands running in all disconnected sessions on the Server01 and Server02 computers. If any session was not disconnected or is not running commands, **Receive-PSSession** does not connect to the session and does not return any output or errors. + ### Example 3 + ``` -PS C:\> Receive-PSSession -ComputerName Server01 -Name ITTask -OutTarget Job -JobName ITTaskJob01 -Credential Domain01\Admin01 +PS> Receive-PSSession -ComputerName Server01 -Name ITTask -OutTarget Job -JobName ITTaskJob01 -Credential Domain01\Admin01 Id Name State HasMoreData Location -- ---- ----- ----------- -------- 16 ITTaskJob01 Running True Server01 @@ -119,18 +136,20 @@ The command uses the **Credential** parameter to run the **Receive-PSSession** c The output shows that **Receive-PSSession** returned the results as a job in the current session. To get the job results, use a Receive-Job command + ### Example 4 + ``` The first command uses the New-PSSession cmdlet to create a session on the Server01 computer. The command saves the session in the $s variable.The second command gets the session in the $s variable. Notice that the **State** is **Opened** and the **Availability** is **Available**. These values indicate that you are connected to the session and can run commands in the session. -PS C:\> $s = New-PSSession -ComputerName Server01 -Name AD -ConfigurationName ADEndpoint -PS C:\> $s +PS> $s = New-PSSession -ComputerName Server01 -Name AD -ConfigurationName ADEndpoint +PS> $s Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 8 AD Server01 Opened ADEndpoint Available The third command uses the Invoke-Command cmdlet to run a script in the session in the $s variable.The script begins to run and return data, but a network outage occurs that interrupts the session. The user has to exit the session and restart the local computer. -PS C:\> Invoke-Command -Session $s -FilePath \\Server12\Scripts\SharedScripts\New-ADResolve.ps1 +PS> Invoke-Command -Session $s -FilePath \\Server12\Scripts\SharedScripts\New-ADResolve.ps1 Running "New-ADResolve.ps1" ….exit # Network outage @@ -138,7 +157,7 @@ PS C:\> Invoke-Command -Session $s -FilePath \\Server12\Scripts\SharedScripts\Ne # Network access is not re-established within 4 minutes When the computer restarts, the user starts Windows PowerShell and runs a Get-PSSession command to get sessions on the Server01 computer. The output shows that the AD session still exists on the Server01 computer. The **State** indicates that it is disconnected and the **Availability** value, **None**, indicates that it is not connected to any client sessions. -PS C:\> Get-PSSession -ComputerName Server01 +PS> Get-PSSession -ComputerName Server01 Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ @@ -147,13 +166,13 @@ PS C:\> Get-PSSession -ComputerName Server01 The fifth command uses the **Receive-PSSession** cmdlet to reconnect to the AD session and get the results of the script that ran in the session. The command uses the **OutTarget** parameter to request the results in a job named "ADJob".The command returns a job object. The output indicates that the script is still running. -PS C:\> Receive-PSSession -ComputerName Server01 -Name AD -OutTarget Job -JobName AD +PS> Receive-PSSession -ComputerName Server01 -Name AD -OutTarget Job -JobName AD Job Id Name State HasMoreData Location -- ---- ----- ----------- -------- 16 ADJob Running True Server01 The sixth command uses the Get-PSSession cmdlet to check the job state. The output confirms that, in addition to resuming script execution and getting the script results, the **Receive-PSSession** cmdlet reconnected to the AD session, which is now open and available for commands. -PS C:\> Get-PSSession -ComputerName Server01 +PS> Get-PSSession -ComputerName Server01 Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 Backup Server01 Disconnected Microsoft.PowerShell Busy @@ -162,16 +181,18 @@ Id Name ComputerName State ConfigurationName Availability This example uses the **Receive-PSSession** cmdlet to get the results of a job after a network outage disrupts a session connection. Windows PowerShell automatically attempts to reconnect the session once each second for the next four minutes and abandons the effort only if all attempts in the four-minute interval fail. + ### Example 5 + ``` The first command uses the Invoke-Command cmdlet to run a script on the three remote computers. Because the scripts gathers and summarize data from multiple databases, it often takes the script an extended time to complete. The command uses the **InDisconnectedSession** parameter, which starts the scripts and then immediately disconnects the sessions.The command uses the **SessionOption** parameter to extend the **IdleTimeout** value of the disconnected session. Disconnected sessions are considered to be idle from the moment they are disconnected, so it's important to set the idle timeout for a long enough period that the commands can complete and you can reconnect to the session, if necessary. You can set the IdleTimeout only when you create the PSSession and change it only when you disconnect from it. You cannot change the **IdleTimeout** value when connecting to a PSSession or receiving its results.After running the command, the user exits Windows PowerShell and closes the computer . -PS C:\> Invoke-Command -InDisconnectedSession -ComputerName Server01, Server02, Server30 -FilePath \\Server12\Scripts\SharedScripts\Get-BugStatus.ps1 -Name BugStatus -SessionOption @{IdleTimeout = 86400000} -ConfigurationName ITTasks# Exit +PS> Invoke-Command -InDisconnectedSession -ComputerName Server01, Server02, Server30 -FilePath \\Server12\Scripts\SharedScripts\Get-BugStatus.ps1 -Name BugStatus -SessionOption @{IdleTimeout = 86400000} -ConfigurationName ITTasks# Exit # Start Windows PowerShell on a different computer. On the next day, the user resumes Windows and starts Windows PowerShell. The second command uses the Get-PSSession cmdlet to get the sessions in which the scripts were running. The command identifies the sessions by the computer name, session name, and the name of the session configuration and saves the sessions in the $s variable.The third command displays the value of the $s variable. The output shows that the sessions are disconnected, but not busy, as expected. -PS C:\> $s = Get-PSSession -ComputerName Server01, Server02, Server30 -Name BugStatus - PS C:\> $s +PS> $s = Get-PSSession -ComputerName Server01, Server02, Server30 -Name BugStatus + PS> $s Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 ITTask Server01 Disconnected ITTasks None @@ -180,8 +201,8 @@ Id Name ComputerName State ConfigurationName Availability The fourth command uses the **Receive-PSSession** cmdlet to connect to the sessions in the $s variable and get their results. The command saves the results in the $Results variable..Another display of the $s variable shows that the sessions are connected and available for commands. -PS C:\> $Results = Receive-PSSession -Session $s -PS C:\> $s +PS> $Results = Receive-PSSession -Session $s +PS> $s Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 ITTask Server01 Opened ITTasks Available @@ -190,7 +211,7 @@ PS C:\> $s The fifth command displays the script results in the $Results variable. If any of the results are unexpected, the user can run commands in the sessions to investigate. -PS C:\> $Results +PS> $Results Bug Report - Domain 01 ---------------------- ComputerName BugCount LastUpdated @@ -201,49 +222,52 @@ Server01 121 Friday, December 30, 2011 5:03:34 PMâ This example uses the **Receive-PSSession** cmdlet to reconnect to sessions that were intentionally disconnected and get the results of jobs that were running in the sessions. ### Example 6 + ``` The first command uses the New-PSSession cmdlet to create the Test session on the Server01 computer. The command saves the session in the $s variable. -PS C:\> $s = New-PSSession -ComputerName Server01 -Name Test +PS> $s = New-PSSession -ComputerName Server01 -Name Test The second command uses the Invoke-Command cmdlet to run a command in the session in the $s variable. The command uses the **AsJob** parameter to run the command as a job and to create the job object in the current session. The command returns a job object, which is saved in the $j variable.The third command displays the job object in the $j variable. -PS C:\> $j = Invoke-Command -Session $s { 1..1500 | Foreach-Object {"Return $_"; sleep 30}} -AsJob +PS> $j = Invoke-Command -Session $s { 1..1500 | Foreach-Object {"Return $_"; sleep 30}} -AsJob -PS C:\> $j +PS> $j Id Name State HasMoreData Location -- ---- ----- ----------- -------- 16 Job1 Running True Server01 The fourth command disconnects the session in the $s variable. -PS C:\> $s | Disconnect-PSSession +PS> $s | Disconnect-PSSession Id Name ComputerName State ConfigurationName Availability -- ---- ------------ ----- ----------------- ------------ 1 Test Server01 Disconnected Microsoft.PowerShell None The fifth command shows the effect of disconnecting on the job object in the $j variable. The job state is now Disconnected. -PS C:\> $j +PS> $j Id Name State HasMoreData Location -- ---- ----- ----------- -------- 16 Job1 Disconnected True Server01 The sixth command runs a Receive-Job command on the job in the $j variable. The output shows that the job began to return output before the session (and the job) were disconnected. -PS C:\> Receive-Job $j -Keep +PS> Receive-Job $j -Keep Return 1Return 2 The seventh command is run in the same client session. The command uses the Connect-PSSession cmdlet to reconnect to the Test session on the Server01 computer and saves the session in the $s2 variable. -PS C:\> $s2 = Connect-PSSession -ComputerName Server01 -Name Test +PS> $s2 = Connect-PSSession -ComputerName Server01 -Name Test The eighth command uses the **Receive-PSSession** cmdlet to get the results of the job that was running in the session. Because the command is run in the same session, **Receive-PSSession** returns the results as a job by default and reuses the same job object. The command saves the job in the $j2 variable.The ninth command uses the **Receive-Job** cmdlet to get the results of the job in the $j variable. -PS C:\> $j2 = Receive-PSSession -ComputerName Server01 -Name Test +PS> $j2 = Receive-PSSession -ComputerName Server01 -Name Test -PS C:\> Receive-Job $j +PS> Receive-Job $j Return 3 Return 4… ``` This example shows what happens to a job that is running in a disconnected session. + ## PARAMETERS ### -Authentication + Specifies the mechanism that is used to authenticate the user's credentials in the command to reconnect to the disconnected session. Valid values are **Default**, **Basic**, **Credssp**, **Digest**, **Kerberos**, **Negotiate**, and **NegotiateWithImplicitCredential**. The default value is **Default**. @@ -267,6 +291,7 @@ Accept wildcard characters: False ``` ### -CertificateThumbprint + Specifies the digital public key certificate (X509) of a user account that has permission to connect to the disconnected session. Enter the certificate thumbprint of the certificate. @@ -288,6 +313,7 @@ Accept wildcard characters: False ``` ### -ComputerName + Specifies the computer on which the disconnected session is stored. Sessions are stored on the computer that is at the "server-side" or receiving end of a connection. The default is the local computer. @@ -309,6 +335,7 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to connect to the disconnected session. The default is the current user. @@ -329,6 +356,7 @@ Accept wildcard characters: False ``` ### -Id + Specifies the ID of the disconnected session. The ID parameter works only when the disconnected session was previously connected to the current session. @@ -347,6 +375,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Specifies the instance ID of the disconnected session. The instance ID is a GUID that uniquely identifies a PSSession on a local or remote computer. @@ -378,6 +407,7 @@ Accept wildcard characters: False ``` ### -JobName + Specifies a friendly name for the job that **Receive-PSSession** returns. **Receive-PSSession** returns a job when the value of the **OutTarget** parameter is **Job** or the job that is running in the disconnected session was started in the current session. @@ -402,6 +432,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the friendly name of the disconnected session. ```yaml @@ -429,6 +460,7 @@ Accept wildcard characters: False ``` ### -OutTarget + Determines how the session results are returned. Valid values are: @@ -456,6 +488,7 @@ Accept wildcard characters: False ``` ### -Port + Specifies the network port on the remote computer that is used to reconnect to the session. To connect to a remote computer, the remote computer must be listening on the port that the connection uses. The default ports are 5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS). @@ -484,6 +517,7 @@ Accept wildcard characters: False ``` ### -Session + Specifies the disconnected session. Enter a variable that contains the PSSession or a command that creates or gets the PSSession, such as a Get-PSSession command. @@ -500,6 +534,7 @@ Accept wildcard characters: False ``` ### -UseSSL + Uses the Secure Sockets Layer (SSL) protocol to connect to the disconnected session. By default, SSL is not used. @@ -521,6 +556,7 @@ Accept wildcard characters: False ``` ### -AllowRedirection + Allows redirection of this connection to an alternate Uniform Resource Identifier (URI). When you use the **ConnectionURI** parameter, the remote destination can return an instruction to redirect to a different URI. @@ -543,6 +579,7 @@ Accept wildcard characters: False ``` ### -ApplicationName + Connects only to sessions that use the specified application. Enter the application name segment of the connection URI. @@ -565,6 +602,7 @@ Accept wildcard characters: False ``` ### -ConfigurationName + Connects only to sessions that use the specified session configuration. Enter a configuration name or the fully qualified resource URI for a session configuration. @@ -589,6 +627,7 @@ Accept wildcard characters: False ``` ### -ConnectionUri + Specifies a Uniform Resource Identifier (URI) that defines the connection endpoint that is used to reconnect to the disconnected session. The URI must be fully qualified. @@ -621,6 +660,7 @@ Accept wildcard characters: False ``` ### -SessionOption + Sets advanced options for the session. Enter a **SessionOption** object, such as one that you create by using the New-PSSessionOption cmdlet, or a hash table in which the keys are session option names and the values are session option values. @@ -647,6 +687,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -662,6 +703,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -678,35 +720,48 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.Runspaces.PSSession + You can pipe session objects, such as those returned by the Get-PSSession cmdlet to Receive-PSSession. + ### System.Int32 + You can pipe session IDs to Receive-PSSession. + ### System.Guid + You can pipe the instance IDs of sessions to Receive-PSSession. + ### System.String + You can pipe session names to Receive-PSSession. + ## OUTPUTS ### System.Management.Automation.Job or PSObject + **Receive-PSSession** gets the results of commands that ran in the disconnected session, if any. If the value or default value of the **OutTarget** parameter is **Job**, **Receive-PSSession** returns a job object. Otherwise, it returns objects that represent that command results. + ## NOTES -* **Receive-PSSession** gets results only from sessions that were disconnected. Only sessions that are connected to (terminate at) computers running Windows PowerShell 3.0 or later can be disconnected and reconnected. -* If the commands that were running in the disconnected session did not generate results or if the results were already returned to another session, **Receive-PSSession** does not generate any output. -* The output buffering mode of a session determines how commands in the session manage output when the session is disconnected. When the value of the **OutputBufferingMode** option of the session is **Drop** and the output buffer is full, the command begins to delete output. Receive-PSSession cannot recover this output. For more information about the output buffering mode option, see the help topics for the New-PSSessionOption and New-PSTransportOption cmdlets. -* You cannot change the idle timeout value of a PSSession when you connect to the PSSession or receive results. The **SessionOption** parameter of **Receive-PSSession** takes a **SessionOption** object that has an **IdleTimeout** value. However, the **IdleTimeout** value of the **SessionOption** object and the **IdleTimeout** value of the **$PSSessionOption** variable are ignored when connecting to a PSSession or receiving results. + +- **Receive-PSSession** gets results only from sessions that were disconnected. Only sessions that are connected to (terminate at) computers running Windows PowerShell 3.0 or later can be disconnected and reconnected. +- If the commands that were running in the disconnected session did not generate results or if the results were already returned to another session, **Receive-PSSession** does not generate any output. +- The output buffering mode of a session determines how commands in the session manage output when the session is disconnected. When the value of the **OutputBufferingMode** option of the session is **Drop** and the output buffer is full, the command begins to delete output. Receive-PSSession cannot recover this output. For more information about the output buffering mode option, see the help topics for the New-PSSessionOption and New-PSTransportOption cmdlets. +- You cannot change the idle timeout value of a PSSession when you connect to the PSSession or receive results. The **SessionOption** parameter of **Receive-PSSession** takes a **SessionOption** object that has an **IdleTimeout** value. However, the **IdleTimeout** value of the **SessionOption** object and the **IdleTimeout** value of the **$PSSessionOption** variable are ignored when connecting to a PSSession or receiving results. You can set and change the idle timeout of a PSSession when you create the PSSession (by using the New-PSSession or Invoke-Command cmdlets) and when you disconnect from the PSSession. The **IdleTimeout** property of a PSSession is critical to disconnected sessions, because it determines how long a disconnected session is maintained on the remote computer. Disconnected sessions are considered to be idle from the moment that they are disconnected, even if commands are running in the disconnected session. -* If you start a start a job in a remote session by using the **AsJob** parameter of the Invoke-Command cmdlet, the job object is created in the current session, even though the job runs in the remote session. If you disconnect the remote session, the job object in the current session is now disconnected from the job. The job object still contains any results that were returned to it, but it does not receive new results from the job in the disconnected session. +- If you start a start a job in a remote session by using the **AsJob** parameter of the Invoke-Command cmdlet, the job object is created in the current session, even though the job runs in the remote session. If you disconnect the remote session, the job object in the current session is now disconnected from the job. The job object still contains any results that were returned to it, but it does not receive new results from the job in the disconnected session. If a different client connects to the session that contains the running job, the results that were delivered to the original job object in the original session are not available in the newly connected session. Only results that were not delivered to the original job object are available in the reconnected session. @@ -721,8 +776,8 @@ In this case, the job object is created in the remote session. You cannot use the **Receive-PSSession** cmdlet to get the job results. Instead, use the **Connect-PSSession** cmdlet to connect to the session and then use the **Invoke-Command** cmdlet to run a Receive-Job command in the session. -* When a session that contains a running job is disconnected and then reconnected, the original job object is reused only if the job is disconnected and reconnected to the same session, and the command to reconnect does not specify a new job name. If the session is reconnected to a different client session or a new job name is specified, Windows PowerShell creates a new job object for the new session. -* When you disconnect a PSSession, the session state is **Disconnected** and the availability is **None**. +- When a session that contains a running job is disconnected and then reconnected, the original job object is reused only if the job is disconnected and reconnected to the same session, and the command to reconnect does not specify a new job name. If the session is reconnected to a different client session or a new job name is specified, Windows PowerShell creates a new job object for the new session. +- When you disconnect a PSSession, the session state is **Disconnected** and the availability is **None**. The value of the **State** property is relative to the current session. Therefore, a value of **Disconnected** means that the PSSession is not connected to the current session. diff --git a/reference/3.0/Microsoft.PowerShell.Core/Register-PSSessionConfiguration.md b/reference/3.0/Microsoft.PowerShell.Core/Register-PSSessionConfiguration.md index 2b1618e0acb0..5c9781c27116 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Register-PSSessionConfiguration.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Register-PSSessionConfiguration.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=144306 external help file: System.Management.Automation.dll-Help.xml title: Register-PSSessionConfiguration --- - # Register-PSSessionConfiguration + ## SYNOPSIS + Creates and registers a new session configuration. + ## SYNTAX ### NameParameterSet (Default) + ``` Register-PSSessionConfiguration [-ProcessorArchitecture ] [-SessionType ] [-Name] [-ApplicationBase ] [-RunAsCredential ] @@ -26,6 +29,7 @@ Register-PSSessionConfiguration [-ProcessorArchitecture ] [-SessionType ``` ### AssemblyNameParameterSet + ``` Register-PSSessionConfiguration [-ProcessorArchitecture ] [-Name] [-AssemblyName] [-ApplicationBase ] [-ConfigurationTypeName] [-RunAsCredential ] @@ -38,6 +42,7 @@ Register-PSSessionConfiguration [-ProcessorArchitecture ] [-Name] ] [-Name] [-RunAsCredential ] [-ThreadApartmentState ] [-ThreadOptions ] @@ -48,6 +53,7 @@ Register-PSSessionConfiguration [-ProcessorArchitecture ] [-Name] Register-PSSessionConfiguration -Name NewShell -ApplicationBase c:\MyShells\ -AssemblyName MyShell.dll -ConfigurationTypeName MyClass +PS> Register-PSSessionConfiguration -Name NewShell -ApplicationBase c:\MyShells\ -AssemblyName MyShell.dll -ConfigurationTypeName MyClass ``` This command registers the NewShell session configuration. @@ -75,9 +83,11 @@ It uses the **AssemblyName** and **ApplicationBase** parameters to specify the l It also uses the **ConfigurationTypeName** parameter to specify a new class that further configures the session. To use this configuration, type "new-pssession -configurationname newshell". + ### Example 2 + ``` -PS C:\> Register-PSSessionConfiguration -name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 +PS> Register-PSSessionConfiguration -name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 ``` This command registers the MaintenanceShell configuration on the local computer. @@ -86,10 +96,12 @@ The command uses the **StartupScript** parameter to specify the Maintenance.ps1 When a user uses a New-PSSession command and selects the MaintenanceShell configuration, the Maintenance.ps1 script runs in the new session. The script can configure the session, including importing modules, adding Windows PowerShell snap-ins, and setting the execution policy for the session. If the script generates any errors, including non-terminating errors, the **New-PSSession** command fails. + ### Example 3 + ``` -PS C:\> $sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)" -PS C:\> Register-PSSessionConfiguration -name AdminShell -SecurityDescriptorSDDL $sddl -MaximumReceivedObjectSizeMB 20 -StartupScript C:\scripts\AdminShell.ps1 +PS> $sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)" +PS> Register-PSSessionConfiguration -name AdminShell -SecurityDescriptorSDDL $sddl -MaximumReceivedObjectSizeMB 20 -StartupScript C:\scripts\AdminShell.ps1 ``` This example registers the AdminShell session configuration. @@ -102,13 +114,15 @@ It also uses the **StartupScript** parameter to specify a script that configures As an alternative to using the **SecurityDescriptorSDDL** parameter, you can use the **ShowSecurityDescriptorUI** parameter, which displays a property sheet that you can use to set permissions for the session configuration. When you click "OK" in the property sheet, the tool generates an SDDL for the session configuration. + ### Example 4 + ``` The first command uses the **Register-PSSessionConfiguration** cmdlet to register the MaintenanceShell configuration. It saves the object that the cmdlet returns in the $s variable. -PS C:\> $s = Register-PSSessionConfiguration -name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 +PS> $s = Register-PSSessionConfiguration -name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 The second command displays the contents of the $s variable. -PS C:\> $s +PS> $s WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin Name Type Keys @@ -117,13 +131,13 @@ MaintenanceShell Container {Name=MaintenanceShell} The third command uses the **GetType** method and its **FullName** property to display the type name of the object that **Register-PSSessionConfiguration** returns. -PS C:\> $s.GetType().FullName +PS> $s.GetType().FullName TypeName: Microsoft.WSMan.Management.WSManConfigContainerElement The fourth command uses the Format-List cmdlet to display all the properties of the object that Register-PSSessionConfiguration returns in a list. The **PSPath** property shows that the object is stored in a directory of the WSMan: drive. -PS C:\> $s | Format-List -Property * +PS> $s | Format-List -Property * PSPath : Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell PSParentPath : Microsoft.WSMan.Management\WSMan::localhost\Plugin @@ -137,7 +151,7 @@ TypeNameOfElement : Container The fifth command uses the Get-ChildItem cmdlet to display the items in the WSMan:\LocalHost\PlugIn path. These include the new MaintenanceShell configuration and the two default configurations that come with Windows PowerShell. -PS C:\> dir WSMan:\LocalHost\Plugin +PS> dir WSMan:\LocalHost\Plugin Name Type Keys ---- ---- ---- @@ -148,9 +162,11 @@ microsoft.powershell32 Container {Name=microsoft.powershell32} This example shows that a Register-PSSessionConfiguration command returns a WSManConfigContainerElement. It also shows how to find the container elements in the WSMan: drive. + ### Example 5 + ``` -PS C:\> Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1 +PS> Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1 # Add-Profile.ps1 . c:\users\admin01\documents\windowspowershell\profile.ps1 @@ -164,22 +180,24 @@ The script contains a single command that uses dot sourcing to run the user's ** For more information about profiles, see about_Profiles. For more information about dot sourcing, see about_Scopes. + ### Example 6 + ``` The first pair of commands use the **New-PSSessionConfigurationFile** cmdlet to create two session configuration files. The first command creates a no-Language file. The second command creates a restricted-language file. Other than the value of the **LanguageMode** parameter, the session configuration files are equivalent. -PS C:\> New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage -PS C:\> New-PSSessionConfigurationFile -Path .\RestrictedLanguage.pssc -LanguageMode Restricted +PS> New-PSSessionConfigurationFile -Path .\NoLanguage.pssc -LanguageMode NoLanguage +PS> New-PSSessionConfigurationFile -Path .\RestrictedLanguage.pssc -LanguageMode Restricted The second pair of commands use the configuration files to create session configurations on the local computer. -PS C:\> Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force -PS C:\> Register-PSSessionConfiguration -Path .\RestrictedLanguage.pssc -Name RestrictedLanguage -Force +PS> Register-PSSessionConfiguration -Path .\NoLanguage.pssc -Name NoLanguage -Force +PS> Register-PSSessionConfiguration -Path .\RestrictedLanguage.pssc -Name RestrictedLanguage -Force The third pair of command creates two sessions, each of which uses one of the session configurations that was created in the previous command pair. -PS C:\> $NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage -PS C:\> $RestrictedLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage +PS> $NoLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName NoLanguage +PS> $RestrictedLanguage = New-PSSession -ComputerName Srv01 -ConfigurationName RestrictedLanguage The seventh command uses the Invoke-Command cmdlet to run an If statement in the no-Language session. The command fails, because the language elements in the command are not permitted in a no-language session. -PS C:\> Invoke-Command -Session $NoLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } +PS> Invoke-Command -Session $NoLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } The syntax is not supported by this runspace. This might be because it is in no-language mode. + CategoryInfo : ParserError: (if ((Get-Date) ...") {"Before"} :String) [], ParseException + FullyQualifiedErrorId : ScriptsNotAllowed @@ -187,7 +205,7 @@ The syntax is not supported by this runspace. This might be because it is in no- The eighth command uses the **Invoke-Command** cmdlet to run the same If statement in the restricted-language session. Because these language elements are permitted in the restricted-language session, the command succeeds. -PS C:\> Invoke-Command -Session $RestrictedLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } +PS> Invoke-Command -Session $RestrictedLanguage {if ((Get-Date) -lt "1January2014") {"Before"} else {"After"} } Before ``` @@ -196,9 +214,11 @@ The example shows the effect of using the **LanguageMode** parameter of **New-PS To run the commands in this example, start Windows PowerShell with the "Run as administrator" option. This option is required to run the Register-PSSessionConfiguration cmdlet . + ## PARAMETERS ### -AccessMode + Enables and disables the session configuration and determines whether it can be used for remote or local sessions on the computer. **Remote** is the default. @@ -226,6 +246,7 @@ Accept wildcard characters: False ``` ### -ApplicationBase + Specifies the path to the assembly file (*.dll) that is specified in the value of the **AssemblyName** parameter. Use this parameter when the value of the **AssemblyName** parameter does not include a path. The default is the current directory. @@ -243,6 +264,7 @@ Accept wildcard characters: False ``` ### -AssemblyName + Specifies the name of an assembly file (*.dll) in which the configuration type is defined. You can specify the path to the .dll in this parameter or in the value of the **ApplicationBase** parameter. @@ -261,6 +283,7 @@ Accept wildcard characters: False ``` ### -ConfigurationTypeName + Specifies the fully qualified name of the Microsoft .NET Framework type that is used for this configuration. The type that you specify must implement the **System.Management.Automation.Remoting.PSSessionConfiguration** class. @@ -283,6 +306,7 @@ Accept wildcard characters: False ``` ### -Force + Suppresses all users prompts and restarts the WinRM service without prompting. Restarting the service makes the configuration change effective. @@ -301,6 +325,7 @@ Accept wildcard characters: False ``` ### -MaximumReceivedDataSizePerCommandMB + Limits the amount of data that can be sent to this computer in any single remote command. Enter the data size in megabytes (MB). The default is 50 MB. @@ -320,6 +345,7 @@ Accept wildcard characters: False ``` ### -MaximumReceivedObjectSizeMB + Limits the amount of data that can be sent to this computer in any single object. Enter the data size in megabytes (MB). The default is 10 MB. @@ -339,6 +365,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies a name for the session configuration. This parameter is required. @@ -355,6 +382,7 @@ Accept wildcard characters: False ``` ### -NoServiceRestart + Does not restart the WinRM service, and suppresses the prompt to restart the service. By default, when you enter a **Register-PSSessionConfiguration** command, you are prompted to restart the WinRM service to make the new session configuration effective. @@ -376,6 +404,7 @@ Accept wildcard characters: False ``` ### -Path + Specifies the path and file name of a session configuration file (.pssc), such as one created by the New-PSSessionConfigurationFile cmdlet. If you omit the path, the default is the current directory. @@ -394,6 +423,7 @@ Accept wildcard characters: False ``` ### -ProcessorArchitecture + Determines whether a 32-bit or 64-bit version of the Windows PowerShell process is started in sessions that use this session configuration. Valid values are x86 (32-bit) and AMD64 (64-bit). The default value is determined by the processor architecture of the computer that hosts the session configuration. @@ -414,6 +444,7 @@ Accept wildcard characters: False ``` ### -PSVersion + Specifies the version of Windows PowerShell in sessions that use this session configuration. The value of this parameter takes precedence over the value of the **PowerShellVersion** key in the session configuration file. @@ -433,6 +464,7 @@ Accept wildcard characters: False ``` ### -RunAsCredential + Runs commands in the session with the permissions of the specified user. By default, commands run with the permissions of the current user. @@ -451,6 +483,7 @@ Accept wildcard characters: False ``` ### -SecurityDescriptorSddl + Specifies a Security Descriptor Definition Language (SDDL) string for the configuration. This string determines the permissions that are required to use the new session configuration. @@ -477,6 +510,7 @@ Accept wildcard characters: False ``` ### -SessionType + Specifies the type of session that is created by using the session configuration. The default value is **Default**. Valid values are: @@ -502,6 +536,7 @@ Accept wildcard characters: False ``` ### -SessionTypeOption + Sets type-specific options for the session configuration. Enter a session type options object, such as the **PSWorkflowExecutionOption** object that the New-PSWorkflowExecutionOption cmdlet returns. @@ -524,6 +559,7 @@ Accept wildcard characters: False ``` ### -ShowSecurityDescriptorUI + Displays a property sheet that helps you to create the SDDL for the session configuration. The property sheet appears after you enter the **Register-PSSessionConfiguration** command and then restart the WinRM service. @@ -544,6 +580,7 @@ Accept wildcard characters: False ``` ### -StartupScript + Specifies the fully qualified path to a Windows PowerShell script. The specified script runs in the new session that uses the session configuration. @@ -563,6 +600,7 @@ Accept wildcard characters: False ``` ### -ThreadApartmentState + Determines the apartment state of the threads in the session. Valid values are **STA**, **MTA**, and **Unknown**. **Unknown** is the default. @@ -580,6 +618,7 @@ Accept wildcard characters: False ``` ### -ThreadOptions + Defines how threads are created and used when a command is executed in the session. Valid values are **Default**, **ReuseThread**, **UseCurrentThread**, and **UseNewThread**. **UseCurrentThread** is the default. @@ -599,6 +638,7 @@ Accept wildcard characters: False ``` ### -TransportOption + This parameter is introduced in Windows PowerShell 3.0. ```yaml @@ -614,6 +654,7 @@ Accept wildcard characters: False ``` ### -UseSharedProcess + Use only one process to host all sessions that are started by the same user and use the same session configuration. By default, each session is hosted in its own process. @@ -632,6 +673,7 @@ Accept wildcard characters: False ``` ### -ModulesToImport + Specifies the modules and snap-ins that are automatically imported into sessions that use the session configuration. By default, only the **Microsoft.PowerShell.Core** snap-in is imported into sessions, but unless the cmdlets are excluded, users can use the Import-Module and Add-PSSnapin cmdlets to add modules and snap-ins to the session. @@ -654,6 +696,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -669,6 +712,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -685,21 +729,27 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### Microsoft.WSMan.Management.WSManConfigContainerElement ## NOTES -* To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, start Windows PowerShell with the "Run as administrator" option. + +- To run this cmdlet on Windows Vista, Windows Server 2008, and later versions of Windows, start Windows PowerShell with the "Run as administrator" option. This cmdlet generates XML that represents a Web Services for Management (WS-Management) plug-in configuration and sends the XML to WS-Management, which registers the plug-in on the local computer ("new-item wsman:\localhost\plugin"). -* The properties of a session configuration object vary with the options set for the session configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties. +- The properties of a session configuration object vary with the options set for the session configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties. + ## RELATED LINKS [Disable-PSSessionConfiguration](Disable-PSSessionConfiguration.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Remove-Job.md b/reference/3.0/Microsoft.PowerShell.Core/Remove-Job.md index 5d2e97792f5e..ded8983e5af4 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Remove-Job.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Remove-Job.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,48 +7,58 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113377 external help file: System.Management.Automation.dll-Help.xml title: Remove-Job --- - # Remove-Job + ## SYNOPSIS + Deletes a Windows PowerShell background job. + ## SYNTAX ### SessionIdParameterSet (Default) + ``` Remove-Job [-Force] [-Id] [-WhatIf] [-Confirm] [] ``` ### JobParameterSet + ``` Remove-Job [-Job] [-Force] [-WhatIf] [-Confirm] [] ``` ### NameParameterSet + ``` Remove-Job [-Force] [-Name] [-WhatIf] [-Confirm] [] ``` ### InstanceIdParameterSet + ``` Remove-Job [-Force] [-InstanceId] [-WhatIf] [-Confirm] [] ``` ### FilterParameterSet + ``` Remove-Job [-Force] [-Filter] [-WhatIf] [-Confirm] [] ``` ### StateParameterSet + ``` Remove-Job [-State] [-WhatIf] [-Confirm] [] ``` ### CommandParameterSet + ``` Remove-Job [-Command ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Remove-Job** cmdlet deletes Windows PowerShell background jobs that were started by using the Start-Job or the **AsJob** parameter of any cmdlet. You can use this cmdlet to delete all jobs or delete selected jobs based on their name, ID, instance ID, command, or state, or by passing a job object to **Remove-Job**. @@ -62,12 +72,14 @@ If you try to delete a running job, the command fails. You can use the **Force** parameter of **Remove-Job** to delete a running job. If you do not delete a background job, the job remains in the global job cache until you close the session in which the job was created. + ## EXAMPLES ### Example 1 + ``` -PS C:\> $batch = Get-Job -Name BatchJob -PS C:\> $batch | Remove-Job +PS> $batch = Get-Job -Name BatchJob +PS> $batch | Remove-Job ``` These commands delete a background job named BatchJob from the current session. @@ -75,30 +87,38 @@ The first command uses the Get-Job cmdlet to get an object representing the job, The second command uses a pipeline operator (|) to send the job to the Remove-Job cmdlet. This command is equivalent to using the **Job** parameter of **Remove-Job**, for example, "remove-job -job $batch". + ### Example 2 + ``` -PS C:\> Get-job | Remove-Job +PS> Get-job | Remove-Job ``` This command deletes all of the jobs in the current session. + ### Example 3 + ``` -PS C:\> Remove-Job -State NotStarted +PS> Remove-Job -State NotStarted ``` This command deletes all jobs from the current session that have not yet been started. + ### Example 4 + ``` -PS C:\> Remove-Job -Name *batch -Force +PS> Remove-Job -Name *batch -Force ``` This command deletes all jobs with friendly names that end with "batch" from the current session, including jobs that are running. It uses the **Name** parameter of **Remove-Job** to specify a job name pattern, and it uses the **Force** parameter to ensure that all jobs are removed, even those that might be in progress. + ### Example 5 + ``` -PS C:\> $j = Invoke-Command -ComputerName Server01 -ScriptBlock {Get-Process} -AsJob -PS C:\> $j | Remove-Job +PS> $j = Invoke-Command -ComputerName Server01 -ScriptBlock {Get-Process} -AsJob +PS> $j | Remove-Job ``` This example shows how to use the **Remove-Job** cmdlet to remove a job that was started on a remote computer by using the **AsJob** parameter of the Invoke-Command cmdlet. @@ -113,27 +133,31 @@ The second command uses the **Remove-Job** cmdlet to remove the job. It uses a pipeline operator (|) to send the job in $j to **Remove-Job**. Note that this is a local command. A remote command is not required to remove a job that was started by using the **AsJob** parameter. + ### Example 6 + ``` The first command uses the New-PSSession cmdlet to create a PSSession (a persistent connection) to the Server01 computer. A persistent connection is required when running a Start-Job command remotely. The command saves the PSSession in the $s variable. -PS C:\> $s = New-PSSession -ComputerName Server01 +PS> $s = New-PSSession -ComputerName Server01 The second command uses the **Invoke-Command** cmdlet to run a **Start-Job** command in the PSSession in $s. The job runs a **Get-Process** command. It uses the **Name** parameter of **Start-Job** to specify a friendly name for the job. -PS C:\> Invoke-Command -Session $s -ScriptBlock {Start-Job -ScriptBlock {Get-Process} -Name MyJob} +PS> Invoke-Command -Session $s -ScriptBlock {Start-Job -ScriptBlock {Get-Process} -Name MyJob} The third command uses the **Invoke-Command** cmdlet to run a **Remove-Job** command in the PSSession in $s. The command uses the **Name** parameter of Remove-Job to identify the job to be deleted. -PS C:\> Invoke-Command -Session $s -ScriptBlock {Remove-Job -Name MyJob} +PS> Invoke-Command -Session $s -ScriptBlock {Remove-Job -Name MyJob} ``` This example shows how to remove a job that was started by using Invoke-Command to run a Start-Job command. In this case, the job object is created on the remote computer and you use remote commands to manage the job. + ### Example 7 + ``` The first command uses the Start-Job cmdlet to start a background job. The command saves the resulting job object in the $j variable. -PS C:\> $j = Start-Job -ScriptBlock {Get-Process Powershell} +PS> $j = Start-Job -ScriptBlock {Get-Process Powershell} The second command uses a pipeline operator (|) to send the job object in $j to the Format-List cmdlet. The **Format-List** command uses the **Property** parameter with a value of * (all) to display all of the properties of the job object in a list.The job object display shows the values of the **ID** and **InstanceID** properties, along with the other properties of the object. -PS C:\> $j | Format-List -Property * +PS> $j | Format-List -Property * HasMoreData : False StatusMessage : @@ -154,13 +178,15 @@ Warning : {} StateChanged : The third command uses a **Remove-Job** command to remove the job from the current session. To generate the command, you can copy and paste the **InstanceID** value from the object display.To copy a value in the Windows PowerShell console, use the mouse to select the value, and then press Enter to copy it. To paste a value, right-click. -PS C:\> Remove-Job -InstanceID dce2ee73-f8c9-483e-bdd7-a549d8687eed +PS> Remove-Job -InstanceID dce2ee73-f8c9-483e-bdd7-a549d8687eed ``` This example shows how to remove a job based on its instance ID. + ## PARAMETERS ### -Command + Deletes jobs that include the specified words in the command. ```yaml @@ -176,6 +202,7 @@ Accept wildcard characters: False ``` ### -Filter + Deletes jobs that satisfy all of the conditions established in the associated hash table. Enter a hash table where the keys are job properties and the values are job property values. @@ -198,6 +225,7 @@ Accept wildcard characters: False ``` ### -Force + Deletes the job even if the status is "Running". Without the **Force** parameter, **Remove-Job** does not delete running jobs. @@ -214,6 +242,7 @@ Accept wildcard characters: False ``` ### -Id + Deletes background jobs with the specified IDs. The ID is an integer that uniquely identifies the job within the current session. @@ -234,6 +263,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Deletes jobs with the specified instance IDs. An instance ID is a GUID that uniquely identifies the job on the computer. @@ -252,6 +282,7 @@ Accept wildcard characters: False ``` ### -Job + Specifies the jobs to be deleted. Enter a variable that contains the jobs or a command that gets the jobs. You can also use a pipeline operator to submit jobs to the **Remove-Job** cmdlet. @@ -269,6 +300,7 @@ Accept wildcard characters: False ``` ### -Name + Deletes only the jobs with the specified friendly names. Wildcards are permitted. @@ -287,6 +319,7 @@ Accept wildcard characters: False ``` ### -State + Deletes only jobs with the specified status. Valid values are Valid values are NotStarted, Running, Completed, Failed, Stopped, Blocked, Disconnected, Suspending, Stopping, and Suspended. To delete jobs with a state of Running, use the **Force** parameter. @@ -304,6 +337,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -319,6 +353,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -335,15 +370,21 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.Job + You can pipe a job object to Remove-Job. + ## OUTPUTS ### None + This cmdlet does not generate any output. + ## NOTES ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Core/Remove-Module.md b/reference/3.0/Microsoft.PowerShell.Core/Remove-Module.md index e52ec11202cc..7c59646e776e 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Remove-Module.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Remove-Module.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,46 +7,57 @@ online version: http://go.microsoft.com/fwlink/?LinkID=141556 external help file: System.Management.Automation.dll-Help.xml title: Remove-Module --- - # Remove-Module + ## SYNOPSIS + Removes modules from the current session. + ## SYNTAX ### name + ``` Remove-Module [-Name] [-Force] [-WhatIf] [-Confirm] [] ``` ### ModuleInfo + ``` Remove-Module [-ModuleInfo] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Remove-Module** cmdlet removes the members of a module, such as cmdlets and functions, from the current session. If the module includes an assembly (.dll), all members that are implemented by the assembly are removed, but the assembly is not unloaded. This cmdlet does not uninstall the module or delete it from the computer. It affects only the current Windows PowerShell session. + ## EXAMPLES ### Example 1 + ``` -PS C:\> Remove-Module -Name BitsTransfer +PS> Remove-Module -Name BitsTransfer ``` This command removes the BitsTransfer module from the current session. + ### Example 2 + ``` -PS C:\> Get-Module | Remove-Module +PS> Get-Module | Remove-Module ``` This command removes all modules from the current session. + ### Example 3 + ``` -PS C:\> "FileTransfer", "PSDiagnostics" | Remove-Module -Verbose +PS> "FileTransfer", "PSDiagnostics" | Remove-Module -Verbose VERBOSE: Performing operation "Remove-Module" on Target "filetransfer (Path: 'C:\Windows\system32\WindowsPowerShell\v1.0\Modules\filetransfer\filetransfer.psd1')". VERBOSE: Performing operation "Remove-Module" on Target "Microsoft.BackgroundIntelligentTransfer.Management (Path: 'C:\Windows\assembly\GAC_MSIL\Microsoft.BackgroundIntelligentTransfer.Management\1.0.0.0__31bf3856ad364e35\Microsoft.BackgroundIntelligentTransfe r.Management.dll')". @@ -72,16 +83,20 @@ It uses the **Verbose** common parameter to get detailed information about the m The Verbose messages show the items that are removed. The messages differ because the BitsTransfer module includes an assembly that implements its cmdlets and a nested module with its own assembly. The PSDiagnostics module includes a module script file (.psm1) that exports functions. + ### Example 4 + ``` -PS C:\> $a = Get-Module BitsTransfer -PS C:\> Remove-Module -ModuleInfo $a +PS> $a = Get-Module BitsTransfer +PS> Remove-Module -ModuleInfo $a ``` This command uses the ModuleInfo parameter to remove the BitsTransfer module. + ## PARAMETERS ### -Force + Removes read-only modules. By default, **Remove-Module** removes only read-write modules. @@ -100,6 +115,7 @@ Accept wildcard characters: False ``` ### -ModuleInfo + Specifies the module objects to remove. Enter a variable that contains a module object (PSModuleInfo) or a command that gets a module object, such as a Get-Module command. You can also pipe module objects to **Remove-Module**. @@ -117,6 +133,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the names of modules to remove. Wildcards are permitted. You can also pipe name strings to **Remove-Module**. @@ -134,6 +151,7 @@ Accept wildcard characters: True ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -149,6 +167,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -165,15 +184,21 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.String, System.Management.Automation.PSModuleInfo + You can pipe module names (strings) and module objects to **Remove-Module**. + ## OUTPUTS ### None + Remove-Module does not generate any output. + ## NOTES ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSession.md b/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSession.md index 2af91bdbe2f1..4dd2eacc335a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSession.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSession.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,38 +7,46 @@ online version: http://go.microsoft.com/fwlink/?LinkID=135250 external help file: System.Management.Automation.dll-Help.xml title: Remove-PSSession --- - # Remove-PSSession + ## SYNOPSIS + Closes one or more Windows PowerShell sessions (PSSessions). + ## SYNTAX ### Id (Default) + ``` Remove-PSSession [-Id] [-WhatIf] [-Confirm] [] ``` ### Session + ``` Remove-PSSession [-Session] [-WhatIf] [-Confirm] [] ``` ### InstanceId + ``` Remove-PSSession -InstanceId [-WhatIf] [-Confirm] [] ``` ### Name + ``` Remove-PSSession -Name [-WhatIf] [-Confirm] [] ``` ### ComputerName + ``` Remove-PSSession [-ComputerName] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The Remove-PSSession cmdlet closes Windows PowerShell sessions (PSSessions) in the current session. It stops any commands that are running in the PSSessions, ends the PSSession, and releases the resources that the PSSession was using. If the PSSession is connected to a remote computer, Remove-PSSession also closes the connection between the local and remote computers. @@ -46,47 +54,57 @@ If the PSSession is connected to a remote computer, Remove-PSSession also closes To remove a PSSession, enter the Name, ComputerName, ID, or InstanceID of the session. If you have saved the PSSession in a variable, the session object remains in the variable, but the state of the PSSession is "Closed." + ## EXAMPLES ### Example 1 + ``` -PS C:\> remove-pssession -id 1, 2 +PS> remove-pssession -id 1, 2 ``` This command removes the PSSessions that have IDs 1 and 2. + ### Example 2 + ``` -PS C:\> get-pssession | remove-pssession +PS> get-pssession | remove-pssession - or - -PS C:\> remove-pssession -session (get-pssession) +PS> remove-pssession -session (get-pssession) - or - -PS C:\> $s = get-pssession -PS C:\> remove-pssession -session $s +PS> $s = get-pssession +PS> remove-pssession -session $s ``` These commands remove all of the PSSessions in the current session. Although the three command formats look different, they have the same effect. + ### Example 3 + ``` -PS C:\> $r = get-pssession -computername Serv* +PS> $r = get-pssession -computername Serv* $r | remove-pssession ``` These commands close the PSSessions that are connected to computers that have names that begin with "Serv". + ### Example 4 + ``` -PS C:\> get-pssession | where {$_.port -eq 90} | remove-pssession +PS> get-pssession | where {$_.port -eq 90} | remove-pssession ``` This command closes the PSSessions that are connected to port 90. You can use this command format to identify PSSessions by properties other than ComputerName, Name, InstanceID, and ID. + ### Example 5 + ``` -PS C:\> get-pssession | ft computername, instanceID -auto +PS> get-pssession | ft computername, instanceID -auto ComputerName InstanceId ------------ ---------------- @@ -96,7 +114,7 @@ Server02 4699cdbc-61d5-4e0d-b916-84f82ebede1f Server03 4e5a3245-4c63-43e4-88d0-a7798bfc2414 TX-TEST-01 fc4e9dfa-f246-452d-9fa3-1adbdd64ae85 -PS C:\> remove-pssession -InstanceID fc4e9dfa-f246-452d-9fa3-1adbdd64ae85 +PS> remove-pssession -InstanceID fc4e9dfa-f246-452d-9fa3-1adbdd64ae85 ``` These commands show how to close a PSSession based on its instance ID (RemoteRunspaceID). @@ -108,16 +126,20 @@ The AutoSize parameter ("auto") compresses the columns for display. From the resulting display, the administrator can identify the PSSession to be closed, and copy and paste the InstanceID of that PSSession into the second command. The second command uses the Remove-PSSession cmdlet to remove the PSSession with the specified instance ID. + ### Example 6 + ``` -PS C:\> function EndPSS { get-pssession | remove-pssession } +PS> function EndPSS { get-pssession | remove-pssession } ``` This function deletes all of the PSSessions in the current session. After you add this function to your Windows Powershell profile, to delete all sessions, just type "endpss". + ## PARAMETERS ### -ComputerName + Closes the PSSessions that are connected to the specified computers. Wildcards are permitted. @@ -137,6 +159,7 @@ Accept wildcard characters: True ``` ### -Id + Closes the PSSessions with the specified IDs. Type one or more IDs (separated by commas) or use the range operator (..) to specify a range of IDs @@ -157,6 +180,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Closes the PSSessions with the specified instance IDs. The instance ID is a GUID that uniquely identifies a PSSession in the current session. @@ -178,6 +202,7 @@ Accept wildcard characters: False ``` ### -Name + Closes the PSSessions with the specified friendly names. Wildcards are permitted. @@ -196,6 +221,7 @@ Accept wildcard characters: True ``` ### -Session + Specifies the session objects of the PSSessions to close. Enter a variable that contains the PSSessions or a command that creates or gets the PSSessions, such as a New-PSSession or Get-PSSession command. You can also pipe one or more session objects to Remove-PSSession. @@ -213,6 +239,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -228,6 +255,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -244,17 +272,24 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.Runspaces.PSSession + You can pipe a session object to Remove-PSSession. + ## OUTPUTS ### None + Remove-PSSession does not return any objects. + ## NOTES -* The ID parameter is mandatory. You cannot type "remove-pssession" without parameters. To delete all the PSSessions in the current session, type "get-pssession | remove-pssession". + +- The ID parameter is mandatory. You cannot type "remove-pssession" without parameters. To delete all the PSSessions in the current session, type "get-pssession | remove-pssession". A PSSession uses a persistent connection to a remote computer. Create a PSSession to run a series of commands that share data. @@ -263,7 +298,8 @@ For more information, see about_PSSessions. PSSessions are specific to the current session. When you end a session, the PSSessions that you created in that session are forcibly closed. -* +- + ## RELATED LINKS [Connect-PSSession](Connect-PSSession.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSnapin.md b/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSnapin.md index f46b56d76723..0e08950c634a 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSnapin.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Remove-PSSnapin.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,10 +7,12 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113378 external help file: System.Management.Automation.dll-Help.xml title: Remove-PSSnapin --- - # Remove-PSSnapin + ## SYNOPSIS + Removes Windows PowerShell snap-ins from the current session. + ## SYNTAX ``` @@ -18,22 +20,27 @@ Remove-PSSnapin [-Name] [-PassThru] [-WhatIf] [-Confirm] [ remove-pssnapin -name Microsoft.Exchange +PS> remove-pssnapin -name Microsoft.Exchange ``` This command removes the Microsoft.Exchange snap-in from the current session. When the command is complete, the cmdlets and providers that the snap-in supported are not available in the session. + ### Example 2 + ``` -PS C:\> get-PSSnapIn smp* | remove-PSSnapIn +PS> get-PSSnapIn smp* | remove-PSSnapIn ``` This command removes the Windows PowerShell snap-ins that have names beginning with "smp" from the current session. @@ -43,16 +50,20 @@ The pipeline operator (|) sends the results to the Remove-PSSnapin cmdlet, which The providers and cmdlets that this snap-in supports are no longer available in the session. When you pipe objects to Remove-PSSnapin, the names of the objects are associated with the Name parameter, which accepts objects from the pipeline that have a Name property. + ### Example 3 + ``` -PS C:\> remove-pssnapin -name *event* +PS> remove-pssnapin -name *event* ``` This command removes all Windows PowerShell snap-ins that have names that include "event". This command specifies the "Name" parameter name, but the parameter name can be omitted because it is optional. + ## PARAMETERS ### -Name + Specifies the names of Windows PowerShell snap-ins to remove from the current session. The parameter name ("Name") is optional, and wildcard characters (*) are permitted in the value. @@ -69,6 +80,7 @@ Accept wildcard characters: True ``` ### -PassThru + Returns an object representing the snap-in. By default, this cmdlet does not generate any output. @@ -85,6 +97,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -100,6 +113,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -116,18 +130,25 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.PSSnapInInfo + You can pipe a snap-in object to Remove-PSSnapin. + ## OUTPUTS ### None or System.Management.Automation.PSSnapInInfo + By default, Remove-PsSnapin does not generate any output. However, if you use the PassThru parameter, it generates a System.Management.Automation.PSSnapInInfo object representing the snap-in. + ## NOTES -* You can also refer to Remove-PSSnapin by its built-in alias, "rsnp". For more information, see about_Aliases. + +- You can also refer to Remove-PSSnapin by its built-in alias, "rsnp". For more information, see about_Aliases. Remove-PSSnapin does not check the version of Windows PowerShell before removing a snap-in from the session. If a snap-in cannot be removed, a warning appears and the command fails. @@ -136,7 +157,8 @@ If a snap-in cannot be removed, a warning appears and the command fails. If you have added an Add-PSSnapin command to your Windows PowerShell profile, you should delete the command to remove the snap-in from future sessions. For instructions, see about_Profiles. -* +- + ## RELATED LINKS [Add-PSSnapin](Add-PSSnapin.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Resume-Job.md b/reference/3.0/Microsoft.PowerShell.Core/Resume-Job.md index 08b071dff396..de930e0b6579 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Resume-Job.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Resume-Job.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,43 +7,52 @@ online version: http://go.microsoft.com/fwlink/?LinkID=210611 external help file: System.Management.Automation.dll-Help.xml title: Resume-Job --- - # Resume-Job + ## SYNOPSIS + Restarts a suspended job + ## SYNTAX ### SessionIdParameterSet (Default) + ``` Resume-Job [-Wait] [-Id] [-WhatIf] [-Confirm] [] ``` ### JobParameterSet + ``` Resume-Job [-Job] [-Wait] [-WhatIf] [-Confirm] [] ``` ### NameParameterSet + ``` Resume-Job [-Wait] [-Name] [-WhatIf] [-Confirm] [] ``` ### InstanceIdParameterSet + ``` Resume-Job [-Wait] [-InstanceId] [-WhatIf] [-Confirm] [] ``` ### StateParameterSet + ``` Resume-Job [-Wait] [-State] [-WhatIf] [-Confirm] [] ``` ### FilterParameterSet + ``` Resume-Job [-Wait] [-Filter] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION + The **Resume-Job** cmdlet resumes a workflow job that was suspended, such as by using the Suspend-Job cmdlet or the about_Suspend-Workflow activity. When a workflow job is resumed, the job engine reconstructs the state, metadata, and output from saved resources, such as checkpoints, so the job is restarted without any loss of state or data. The job state is changed from **Suspended** to **Running**. @@ -64,38 +73,46 @@ To determine whether a particular custom job type supports the **Resume-Job** cm NOTE: Before using a Job cmdlet on a custom job type, import the module that supports the custom job type, either by using the Import-Module cmdlet or getting or using a cmdlet in the module. This cmdlet is introduced in Windows PowerShell 3.0. + ## EXAMPLES ### Example 1: Resume a job by ID + ``` The first command uses the **Get-Job** cmdlet to get the job. The output shows that the job is a suspended workflow job. -PS C:\> Get-Job EventJob +PS> Get-Job EventJob Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 4 EventJob PSWorkflowJob Suspended True Server01 \\Script\Share\Event.ps1 The second command uses the **Id** parameter of the **Resume-Job** cmdlet to resume the job with an **Id** value of 4. -PS C:\> Resume-Job -Id 4 +PS> Resume-Job -Id 4 ``` The commands in this example verify that the job is a suspended workflow job and then resume the job. + ### Example 2: Resume a job by name + ``` -PS C:\> Resume-Job -Name WorkflowJob, InventoryWorkflow, WFTest* +PS> Resume-Job -Name WorkflowJob, InventoryWorkflow, WFTest* ``` This command uses the **Name** parameter to resume several workflow jobs on the local computer. + ### Example 3: Use custom property values + ``` -PS C:\> Resume-Job -Filter @{CustomID="T091291"} -State Suspended +PS> Resume-Job -Filter @{CustomID="T091291"} -State Suspended ``` This command uses the value of a custom property to identify the workflow job to resume. It uses the **Filter** parameter to identify the workflow job by its **CustomID** property. It also uses the **State** parameter to verify that the workflow job is suspended, before it tries to resume it. + ### Example 4: Resume all suspended jobs on a remote computer + ``` -PS C:\> Invoke-Command -ComputerName Srv01 -ScriptBlock {Get-Job -State Suspended | Resume-Job} +PS> Invoke-Command -ComputerName Srv01 -ScriptBlock {Get-Job -State Suspended | Resume-Job} ``` This command resumes all suspended jobs on the Srv01 remote computer. @@ -103,14 +120,18 @@ This command resumes all suspended jobs on the Srv01 remote computer. The command uses the Invoke-Command cmdlet to run a command on the Srv01 computer. The remote command uses the **State** parameter of the Get-Job cmdlet to get all suspended jobs on the computer. A pipeline operator (|) sends the suspended jobs to the **Resume-Job** cmdlet, which resumes them. + ### Example 5: Wait for jobs to resume + ``` -PS C:\> Resume-Job -Name WorkflowJob, InventoryWorkflow, WFTest* -Wait +PS> Resume-Job -Name WorkflowJob, InventoryWorkflow, WFTest* -Wait ``` This command uses the **Wait** parameter to direct Resume-Job to return only after all specified jobs are resumed. The **Wait** parameter is especially useful in scripts that assume that jobs are resumed before the script continues. + ### Example 6: Resume a Workflow that Suspends Itself + ``` This code sample shows the **Suspend-Workflow** activity in a workflow. #SampleWorkflow @@ -122,7 +143,7 @@ Workflow Test-Suspend } The following command runs the Test-Suspend workflow on the Server01 computer.When you run the workflow, the workflow runs the Get-Date activity and saves the result in the $a variable. Then it runs the **Suspend-Workflow** activity. In response, it takes a checkpoint, suspends the workflow, and returns a workflow job object. **Suspend-Workflow** returns a workflow job object even if the workflow is not explicitly run as a job. -PS C:\> Test-Suspend -PSComputerName Server01 +PS> Test-Suspend -PSComputerName Server01 Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -130,7 +151,7 @@ Id Name PSJobTypeName State HasMoreData Location 8 Job8 PSWorkflowJob Suspended True Server01 Test-Suspend The following command resumes the Test-Suspend workflow in Job8. It uses the **Wait** parameter to hold the command prompt until the job is resumed. -PS C:\> Resume-Job -Name Job8 -Wait +PS> Resume-Job -Name Job8 -Wait Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- @@ -138,7 +159,7 @@ Id Name PSJobTypeName State HasMoreData Location 8 Job8 PSWorkflowJob Running True Server01 Test-Suspend This command uses the **Receive-Job** cmdlet to get the results of the Test-Suspend workflow. The final command in the workflow returns a TimeSpan object that represents the elapsed time between the current date and time and the date and time that was saved in the $a variable before the workflow was suspended. -PS C:\> Receive-Job -Name Job8 +PS> Receive-Job -Name Job8 Days : 0 Hours : 0 @@ -169,9 +190,11 @@ This activity suspends a workflow from within a workflow. It is valid only in workflows. For information about the Suspend-Workflow, see about_Suspend-Workflow. + ## PARAMETERS ### -Filter + Resumes only jobs that satisfy all of the conditions established in the associated hash table. Enter a hash table where the keys are job properties and the values are job property values. @@ -188,6 +211,7 @@ Accept wildcard characters: False ``` ### -Id + Resumes the jobs with the specified IDs. The ID is an integer that uniquely identifies the job within the current session. @@ -208,6 +232,7 @@ Accept wildcard characters: False ``` ### -InstanceId + Resumes jobs with the specified instance IDs. The default is all jobs. @@ -227,6 +252,7 @@ Accept wildcard characters: False ``` ### -Job + Specifies the jobs to be resumed. Enter a variable that contains the jobs or a command that gets the jobs. You can also pipe jobs to the **Resume-Job** cmdlet. @@ -244,6 +270,7 @@ Accept wildcard characters: False ``` ### -Name + Resumes jobs with the specified friendly names. Enter one or more job names. Wildcards are supported. @@ -261,6 +288,7 @@ Accept wildcard characters: False ``` ### -State + Resumes only those jobs in the specified state. Valid values are NotStarted, Running, Completed, Failed, Stopped, Blocked, Suspended, Disconnected, Suspending, and Stopping, but **Resume-Job** resumes only jobs in the **Suspended** state. @@ -279,6 +307,7 @@ Accept wildcard characters: False ``` ### -Wait + Suspends the command prompt until all specified jobs are resumed. By default, Resume-Job returns immediately. @@ -295,6 +324,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -310,6 +340,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -326,23 +357,31 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.Job + You can pipe all types of jobs to **Resume-Job**. However, if **Resume-Job** gets a job of an unsupported type, it throws a terminating error. + ## OUTPUTS ### None or System.Management.Automation.Job + If you use the **PassThru** parameter, **Resume-Job** returns the jobs that it tried to resume. Otherwise, this cmdlet does not generate any output. + ## NOTES -* **Resume-Job** can only resume jobs that are suspended. If you submit a job in a different state, **Resume-Job** runs the resume operation on the job, but generates a warning to notify you that the job could not be resumed. To suppress the warning, use the **WarningAction** common parameter with a value of **SilentlyContinue**. -* If a job is not of a type that supports resuming, such as a workflow job (PSWorkflowJob), **Resume-Job** throws a terminating error. -* The mechanism and location for saving a suspended job might vary depending on the job type. For example, suspended workflow jobs are saved in a flat file store by default, but can also be saved in a SQL database. -* When you resume a job, the job state changes from **Suspended** to **Running**. To find the jobs that are running, including those that were resumed by this cmdlet, use the **State** parameter of the Get-Job cmdlet to get jobs in the **Running** state. -* Some job types have options or properties that prevent Windows PowerShell from suspending the job. If attempts to suspend the job fail, verify that the job options and properties allow suspending. + +- **Resume-Job** can only resume jobs that are suspended. If you submit a job in a different state, **Resume-Job** runs the resume operation on the job, but generates a warning to notify you that the job could not be resumed. To suppress the warning, use the **WarningAction** common parameter with a value of **SilentlyContinue**. +- If a job is not of a type that supports resuming, such as a workflow job (PSWorkflowJob), **Resume-Job** throws a terminating error. +- The mechanism and location for saving a suspended job might vary depending on the job type. For example, suspended workflow jobs are saved in a flat file store by default, but can also be saved in a SQL database. +- When you resume a job, the job state changes from **Suspended** to **Running**. To find the jobs that are running, including those that were resumed by this cmdlet, use the **State** parameter of the Get-Job cmdlet to get jobs in the **Running** state. +- Some job types have options or properties that prevent Windows PowerShell from suspending the job. If attempts to suspend the job fail, verify that the job options and properties allow suspending. + ## RELATED LINKS [Get-Job](Get-Job.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Save-Help.md b/reference/3.0/Microsoft.PowerShell.Core/Save-Help.md index 31877db158cf..c6b117418895 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Save-Help.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Save-Help.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,25 +7,30 @@ online version: http://go.microsoft.com/fwlink/?LinkID=210612 external help file: System.Management.Automation.dll-Help.xml title: Save-Help --- - # Save-Help + ## SYNOPSIS + Downloads and saves the newest help files to a file system directory. + ## SYNTAX ### Path (Default) + ``` Save-Help [-DestinationPath] [[-Module] ] [[-UICulture] ] [-Credential ] [-UseDefaultCredentials] [-Force] [] ``` ### LiteralPath + ``` Save-Help -LiteralPath [[-Module] ] [[-UICulture] ] [-Credential ] [-UseDefaultCredentials] [-Force] [] ``` ## DESCRIPTION + The **Save-Help** cmdlet downloads the newest help files for Windows PowerShell modules and saves them to a directory that you specify. This feature allows you to update the help files on computers that do not have access to the Internet and makes it easier to update the help files on multiple computers. @@ -46,18 +51,22 @@ To save the help files for modules in the Windows PowerShell installation direct You must be a member of the Administrators group on the computer to download the help files for these modules. This cmdlet is introduced in Windows PowerShell 3.0. + ## EXAMPLES ### Example 1: Save help for all modules + ``` -PS C:\> Save-Help -DestinationPath \\Server01\FileShare01 +PS> Save-Help -DestinationPath \\Server01\FileShare01 ``` This command downloads the newest help files for all modules in the UI culture set for Windows on the local computer. It saves the help files in the \\\\Server01\Fileshare01 directory. + ### Example 2: Save help for a module on the computer + ``` -PS C:\> Save-Help -Module ServerManager -DestinationPath \\Server01\FileShare01 -Credential Domain01/Admin01 +PS> Save-Help -Module ServerManager -DestinationPath \\Server01\FileShare01 -Credential Domain01/Admin01 ``` This command downloads the newest help files for the ServerManager module and saves them in the \\\\Server01\Fileshare01 directory. @@ -65,9 +74,11 @@ This command downloads the newest help files for the ServerManager module and sa When a module is installed on the computer, you can type the module name as the value of the **Module** parameter, even if the module is not imported into the current session. The command uses the **Credential** parameter to supply the credentials of a user who has permission to write to the file share. + ### Example 3: Save help for a module on a different computer + ``` -PS C:\> Invoke-Command -ComputerName Server02 {Get-Module -Name CustomSQL -ListAvailable} | Save-Help -DestinationPath \\Server01\FileShare01 -Credential Domain01\Admin01 +PS> Invoke-Command -ComputerName Server02 {Get-Module -Name CustomSQL -ListAvailable} | Save-Help -DestinationPath \\Server01\FileShare01 -Credential Domain01\Admin01 ``` These commands download the newest help files for the CustomSQL module and save them in the \\\\Server01\Fileshare01 directory. @@ -75,18 +86,22 @@ These commands download the newest help files for the CustomSQL module and save Because the CustomSQL module is not installed on the computer, the sequence includes an **Invoke-Command** command that gets the module object for the CustomSQL module from the Server02 computer and then pipes the module object to the **Save-Help** cmdlet. When a module is not installed on the computer, **Save-Help** needs the module object, which includes information about the location of the newest help files. + ### Example 4: Save help for a module in multiple languages + ``` -PS C:\> Save-Help -Module Microsoft.PowerShell* -UICulture de-DE, en-US, fr-FR, ja-JP -DestinationPath D:\Help +PS> Save-Help -Module Microsoft.PowerShell* -UICulture de-DE, en-US, fr-FR, ja-JP -DestinationPath D:\Help ``` This command saves help for the Windows PowerShell Core modules in four different UI cultures. The language packs for these locales do not need to be installed on the computer. **Save-Help** can download help files for modules in different UI cultures only when the module owner makes the translated files available on the Internet. + ### Example 5: Save help more than once each day + ``` -PS C:\> Save-Help -Force -DestinationPath \\Server3\AdminShare\Help +PS> Save-Help -Force -DestinationPath \\Server3\AdminShare\Help ``` This command saves help for all modules that are installed on the computer. @@ -96,9 +111,11 @@ The **Force** parameter also overrides the 1 GB restriction and circumvents vers The command uses the **Save-Help** cmdlet to download and save the help files to the specified directory. The **Force** parameter is required when you need to run a **Save-Help** command more than once each day. + ## PARAMETERS ### -Credential + Runs the command with credentials of a user who has permission to access the file system location specified by the **DestinationPath** parameter. This parameter is valid only when the **DestinationPath** or **LiteralPath** parameter is used in the command. @@ -118,6 +135,7 @@ Accept wildcard characters: False ``` ### -DestinationPath + Specifies the path to the directory in which the help files are saved. Enter the path to a directory. Do not specify a file name or file name extension. @@ -135,6 +153,7 @@ Accept wildcard characters: False ``` ### -Force + Overrides the once-per-day limitation, circumvents version checking, and downloads files that exceed the 1 GB limit Without this parameter, only one **Save-Help** command for each module is permitted in each 24-hour period, downloads are limited to 1 GB of uncompressed content per module and help files for a module are installed only when they are newer than the files on the computer. @@ -156,6 +175,7 @@ Accept wildcard characters: False ``` ### -LiteralPath + Specifies a path to the destination directory. Unlike the value of the **DestinationPath** parameter, the value of the **LiteralPath** parameter is used exactly as it is typed. No characters are interpreted as wildcards. @@ -175,6 +195,7 @@ Accept wildcard characters: False ``` ### -Module + Downloads help for the specified modules. Enter one or more module names or name patters in a comma-separated list or in a file with one module name on each line. Wildcards are permitted. @@ -207,6 +228,7 @@ Accept wildcard characters: True ``` ### -UICulture + Gets updated help files for the specified UI culture. Enter one or more language codes, such as "es-ES", a variable that contains culture objects, or a command that gets culture objects, such as a Get-Culture or Get-UICulture command. @@ -228,6 +250,7 @@ Accept wildcard characters: False ``` ### -UseDefaultCredentials + Runs the command, including the web download, with the credentials of the current user. By default, the command runs without explicit credentials. @@ -246,24 +269,32 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.Management.Automation.PSModuleInfo + You can pipe a module object from the Get-Module cmdlet to the **Module** parameter of **Save-Help**. + ## OUTPUTS ### None + **Save-Help** does not generate any output. + ## NOTES -* To save help for modules in the $pshome\Modules directory, start Windows PowerShell with the "Run as administrator" option. Only members of the Administrators group on the computer can download help for the for modules in the $pshome\Modules directory. -* The saved help for each module consists of one help information (HelpInfo XML) file and one cabinet (.cab) file for the help files each UI culture. You do not need to extract the help files from the cabinet file. The Update-Help cmdlet extracts the help files, validates the XML, and then installs the help files and the help information file in a language-specific subdirectory of the module directory. -* The **Save-Help** cmdlet can save help for modules that are not installed on the computer. However, because help files are installed in the module directory, the Update-Help cmdlet can install updated help file only for modules that are installed on the computer. -* If **Save-Help** cannot find updated help files for a module, or cannot find updated help files in the specified language, it continues silently without displaying an error message. To see which files were saved by the command, use the **Verbose** parameter. -* Modules are the smallest unit of updatable help. You cannot save help for a particular cmdlet; only for all cmdlets in module. To find the module that contains a particular cmdlet, use the **ModuleName** property of the Get-Command cmdlet, for example, `(Get-Command \).ModuleName` -* **Save-Help** supports all modules and the Windows PowerShell Core snap-ins. It does not support any other snap-ins. -* The Update-Help and **Save-Help** cmdlets use the following ports to download help files: Port 80 for HTTP and port 443 for HTTPS. -* The **Update-Help** and **Save-Help** cmdlets are not supported on Windows Preinstallation Environment (Windows PE). + +- To save help for modules in the $pshome\Modules directory, start Windows PowerShell with the "Run as administrator" option. Only members of the Administrators group on the computer can download help for the for modules in the $pshome\Modules directory. +- The saved help for each module consists of one help information (HelpInfo XML) file and one cabinet (.cab) file for the help files each UI culture. You do not need to extract the help files from the cabinet file. The Update-Help cmdlet extracts the help files, validates the XML, and then installs the help files and the help information file in a language-specific subdirectory of the module directory. +- The **Save-Help** cmdlet can save help for modules that are not installed on the computer. However, because help files are installed in the module directory, the Update-Help cmdlet can install updated help file only for modules that are installed on the computer. +- If **Save-Help** cannot find updated help files for a module, or cannot find updated help files in the specified language, it continues silently without displaying an error message. To see which files were saved by the command, use the **Verbose** parameter. +- Modules are the smallest unit of updatable help. You cannot save help for a particular cmdlet; only for all cmdlets in module. To find the module that contains a particular cmdlet, use the **ModuleName** property of the Get-Command cmdlet, for example, `(Get-Command \).ModuleName` +- **Save-Help** supports all modules and the Windows PowerShell Core snap-ins. It does not support any other snap-ins. +- The Update-Help and **Save-Help** cmdlets use the following ports to download help files: Port 80 for HTTP and port 443 for HTTPS. +- The **Update-Help** and **Save-Help** cmdlets are not supported on Windows Preinstallation Environment (Windows PE). + ## RELATED LINKS [Updatable Help Status Table (http://go.microsoft.com/fwlink/?LinkID=270007)](http://go.microsoft.com/fwlink/?LinkID=270007) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Set-PSDebug.md b/reference/3.0/Microsoft.PowerShell.Core/Set-PSDebug.md index 6d0e2513f729..db61f67624a9 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Set-PSDebug.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Set-PSDebug.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,33 +7,40 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113398 external help file: System.Management.Automation.dll-Help.xml title: Set-PSDebug --- - # Set-PSDebug + ## SYNOPSIS + Turns script debugging features on and off, sets the trace level, and toggles strict mode. + ## SYNTAX ### on + ``` Set-PSDebug [-Trace ] [-Step] [-Strict] [] ``` ### off + ``` Set-PSDebug [-Off] [] ``` ## DESCRIPTION + The Set-PSDebug cmdlet turns script debugging features on and off, sets the trace level, and toggles strict mode. When the Trace parameter is set to 1, each line of script is traced as it is executed. When the parameter is set to 2, variable assignments, function calls, and script calls are also traced. If the Step parameter is specified, you are prompted before each line of the script is executed. + ## EXAMPLES ### Example 1 + ``` -PS C:\> set-psdebug -trace 2; foreach ($i in 1..3) {$i} +PS> set-psdebug -trace 2; foreach ($i in 1..3) {$i} DEBUG: 1+ Set-PsDebug -trace 2; foreach ($i in 1..3) {$i} DEBUG: 1+ Set-PsDebug -trace 2; foreach ($i in 1..3) {$i} @@ -45,9 +52,11 @@ DEBUG: 1+ Set-PsDebug -trace 2; foreach ($i in 1..3) {$i} ``` This command sets the trace level to 2, and then runs a script that displays the numbers 1, 2, and 3. + ### Example 2 + ``` -PS C:\> set-psdebug -step; foreach ($i in 1..3) {$i} +PS> set-psdebug -step; foreach ($i in 1..3) {$i} DEBUG: 1+ Set-PsDebug -step; foreach ($i in 1..3) {$i} Continue with this operation? @@ -63,27 +72,33 @@ DEBUG: 1+ Set-PsDebug -step; foreach ($i in 1..3) {$i} This command turns on stepping and then runs a script that displays the numbers 1, 2, and 3. + ### Example 3 + ``` -PS C:\> set-psdebug -off; foreach ($i in 1..3) {$i} +PS> set-psdebug -off; foreach ($i in 1..3) {$i} 1 2 3 ``` This command turns off all debugging features, and then runs a script that displays the numbers 1, 2, and 3. + ### Example 4 + ``` -PS C:\> set-psdebug -strict; $NewVar +PS> set-psdebug -strict; $NewVar The variable $NewVar cannot be retrieved because it has not been set yet. At line:1 char:28 + Set-PsDebug -strict;$NewVar <<<< ``` This command puts the interpreter in strict mode, and attempts to access a variable that has not yet been set. + ## PARAMETERS ### -Off + Turns off all script debugging features. Note: A "set-strictmode -off" command disables the verification set by a "set-psdebug -strict" command. @@ -102,6 +117,7 @@ Accept wildcard characters: False ``` ### -Step + Turns on script stepping. Before each line is run, the user is prompted to stop, continue, or enter a new interpreter level to inspect the state of the script. @@ -120,6 +136,7 @@ Accept wildcard characters: False ``` ### -Strict + Specifies that the interpreter should throw an exception if a variable is referenced before a value is assigned to the variable. Note: A "set-strictmode -off" command disables the verification set by a "set-psdebug -strict" command. @@ -138,6 +155,7 @@ Accept wildcard characters: False ``` ### -Trace + Specifies the trace level: 0 - Turn script tracing off @@ -159,15 +177,21 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### None + This cmdlet does not return any output. + ## NOTES ## RELATED LINKS diff --git a/reference/3.0/Microsoft.PowerShell.Core/Set-PSSessionConfiguration.md b/reference/3.0/Microsoft.PowerShell.Core/Set-PSSessionConfiguration.md index 1120a10e2108..deec20b051e2 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Set-PSSessionConfiguration.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Set-PSSessionConfiguration.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=144307 external help file: System.Management.Automation.dll-Help.xml title: Set-PSSessionConfiguration --- - # Set-PSSessionConfiguration + ## SYNOPSIS + Changes the properties of a registered session configuration. + ## SYNTAX ### NameParameterSet (Default) + ``` Set-PSSessionConfiguration [-Name] [-ApplicationBase ] [-RunAsCredential ] [-ThreadApartmentState ] [-ThreadOptions ] @@ -25,6 +28,7 @@ Set-PSSessionConfiguration [-Name] [-ApplicationBase ] [-RunAsC ``` ### AssemblyNameParameterSet + ``` Set-PSSessionConfiguration [-Name] [-AssemblyName] [-ApplicationBase ] [-ConfigurationTypeName] [-RunAsCredential ] [-ThreadApartmentState ] @@ -36,6 +40,7 @@ Set-PSSessionConfiguration [-Name] [-AssemblyName] [-Applicati ``` ### SessionConfigurationFile + ``` Set-PSSessionConfiguration [-Name] [-RunAsCredential ] [-ThreadApartmentState ] [-ThreadOptions ] @@ -46,6 +51,7 @@ Set-PSSessionConfiguration [-Name] [-RunAsCredential ] ``` ## DESCRIPTION + The **Set-PSSessionConfiguration** cmdlet changes the properties of the session configurations on the local computer. Use the **Name** parameter to identify the session configuration that you want to change. @@ -66,31 +72,37 @@ For more information about session configurations, see about_Session_Configurati To see the properties of a session configuration, use the **Get-PSSessionConfiguration** cmdlet or the WSMan Provider. For more information about the WSMan Provider, type "Get-Help WSMan". + ## EXAMPLES ### Example 1 + ``` -PS C:\> Set-PSSessionConfiguration -Name MaintenanceShell -ThreadApartmentState STA +PS> Set-PSSessionConfiguration -Name MaintenanceShell -ThreadApartmentState STA ``` This command changes the thread apartment state in the MaintenanceShell configuration to STA. The change is effective when you restart the WinRM service. + ### Example 2 + ``` The first command uses the Register-PSSessionConfiguration cmdlet to create the AdminShell configuration. -PS C:\> Register-PSSessionConfiguration -name AdminShell -AssemblyName C:\Shells\AdminShell.dll -ConfigurationType AdminClass +PS> Register-PSSessionConfiguration -name AdminShell -AssemblyName C:\Shells\AdminShell.dll -ConfigurationType AdminClass The second command uses the **Set-PSSessionConfiguration** cmdlet to add the AdminConfig.ps1 script to the configuration. The change is effective when you restart WinRM. -PS C:\> Set-PSSessionConfiguration -Name AdminShell -StartupScript AdminConfig.ps1 +PS> Set-PSSessionConfiguration -Name AdminShell -StartupScript AdminConfig.ps1 The third command removes the AdminConfig.ps1 script from the configuration. It uses the **Set-PSSessionConfiguration** cmdlet with a value of $null for the **StartupScript** parameter. -PS C:\> Set-PSSessionConfiguration -Name AdminShell -StartupScript $null +PS> Set-PSSessionConfiguration -Name AdminShell -StartupScript $null ``` This example shows how to create and then change a session configuration. + ### Example 3 + ``` -PS C:\> Set-PSSessionConfiguration -name IncObj -MaximumReceivedObjectSizeMB 20 +PS> Set-PSSessionConfiguration -name IncObj -MaximumReceivedObjectSizeMB 20 WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\IncObj\InitializationParameters ParamName ParamValue @@ -109,10 +121,12 @@ The **Set-PSSessionConfiguration** command returns a **Microsoft.WSMan.Managemen It also prompts you to restart the WinRM service. The **Set-PSSessionConfiguration** change is not effective until the WinRM service is restarted. + ### Example 4 + ``` The first command uses the **Set-PSSessionConfiguration** cmdlet to change the startup script in the MaintenanceShell session configuration to Maintenance.ps1. The output of this command shows the change and prompts you to restart the WinRM service. The response is "y" (yes). -PS C:\> Set-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 +PS> Set-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1 WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell\InitializationParameters ParamName ParamValue @@ -126,7 +140,7 @@ the command "restart-service winrm"? The second command uses the Get-PSSessionConfiguration cmdlet to get the MaintenanceShell session configuration. The command uses a pipeline operator (|) to send the results of the command to the Format-List cmdlet, which displays all of the properties of the session configuration object in a list. -PS C:\> Get-PSSessionConfiguration MaintenanceShell | Format-List -Property * +PS> Get-PSSessionConfiguration MaintenanceShell | Format-List -Property * xmlns : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration Name : MaintenanceShell Filename : %windir%\system32\pwrshplugin.dll @@ -142,7 +156,7 @@ Capability : {Shell} Permission : The third command uses the WSMan provider to view the initialization parameters for the MaintenanceShell configuration. The command uses the Get-ChildItem cmdlet (alias = dir) to get the child items in the **InitializationParameters** node for the MaintenanceShell plug-in.For more information about the WSMan provider, type "get-help wsman". -PS C:\> dir WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters +PS> dir WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters ParamName ParamValue --------- ---------- PSVersion 2.0 @@ -150,9 +164,11 @@ startupscript c:\ps-test\Maintenance.ps1 ``` This example shows different ways of viewing the results of a **Set-PSSessionConfiguration** command. + ## PARAMETERS ### -ApplicationBase + Specifies the path to the assembly file (*.dll) that is specified in the value of the **AssemblyName** parameter. ```yaml @@ -168,6 +184,7 @@ Accept wildcard characters: False ``` ### -AssemblyName + Creates a session configuration based on a class that is defined in an assembly. Enter the path (optional) and file name of an assembly (a .dll file) that defines a session configuration. @@ -186,6 +203,7 @@ Accept wildcard characters: False ``` ### -ConfigurationTypeName + Specifies the type of the session configuration that is defined in the assembly in the **AssemblyName** parameter. The type that you specify must implement the System.Management.Automation.Remoting.PSSessionConfiguration class. @@ -204,6 +222,7 @@ Accept wildcard characters: False ``` ### -Force + Suppresses all user prompts, and restarts the WinRM service without prompting. Restarting the service makes the configuration change effective. @@ -222,6 +241,7 @@ Accept wildcard characters: False ``` ### -MaximumReceivedDataSizePerCommandMB + Changes the limit on the amount of data that can be sent to this computer in any single remote command. Enter the data size in megabytes (MB). The default is 50 MB. @@ -241,6 +261,7 @@ Accept wildcard characters: False ``` ### -MaximumReceivedObjectSizeMB + Changes the limits on the amount of data that can be sent to this computer in any single object. Enter the data size in megabytes (MB). The default is 10 MB. @@ -260,6 +281,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the session configuration that you want to change. You cannot use this parameter to change the name of the session configuration. @@ -277,6 +299,7 @@ Accept wildcard characters: False ``` ### -NoServiceRestart + Does not restart the WinRM service, and suppresses the prompt to restart the service. By default, when you enter a Set-PSSessionConfiguration command, you are prompted to restart the WinRM service to make the new session configuration effective. @@ -298,6 +321,7 @@ Accept wildcard characters: False ``` ### -PSVersion + Specifies the version of Windows PowerShell in sessions that use this session configuration. The value of this parameter takes precedence over the value of the **PowerShellVersion** key in the session configuration file. @@ -317,6 +341,7 @@ Accept wildcard characters: False ``` ### -RunAsCredential + Runs commands in the session with the permissions of the specified user. By default, commands run with the permissions of the current user. @@ -335,6 +360,7 @@ Accept wildcard characters: False ``` ### -SecurityDescriptorSddl + Specifies a different Security Descriptor Definition Language (SDDL) string for the configuration. This string determines the permissions that are required to use the new session configuration. @@ -359,6 +385,7 @@ Accept wildcard characters: False ``` ### -ShowSecurityDescriptorUI + Displays a property sheet that helps you to create a new SDDL for the session configuration. The property sheet appears after you enter the Set-PSSessionConfiguration command and then restart the WinRM service. @@ -379,6 +406,7 @@ Accept wildcard characters: False ``` ### -StartupScript + Adds or changes the startup script for the configuration. Enter the fully qualified path to a Windows PowerShell script. The specified script runs in the new session that uses the session configuration. @@ -401,6 +429,7 @@ Accept wildcard characters: False ``` ### -ThreadApartmentState + Changes the apartment state setting for the threads in the session. Valid values are STA, MTA and Unknown. Unknown is the default. @@ -418,6 +447,7 @@ Accept wildcard characters: False ``` ### -ThreadOptions + Changes the thread options setting in the configuration. This setting defines how threads are created and used when a command is executed in the session. Valid values are **Default**, **ReuseThread**, **UseCurrentThread**, and **UseNewThread**. @@ -438,6 +468,7 @@ Accept wildcard characters: False ``` ### -UseSharedProcess + Use only one process to host all sessions that are started by the same user and use the same session configuration. By default, each session is hosted in its own process. @@ -456,6 +487,7 @@ Accept wildcard characters: False ``` ### -AccessMode + Enables and disables the session configuration and determines whether it can be used for remote or local sessions on the computer. **Remote** is the default. @@ -483,6 +515,7 @@ Accept wildcard characters: False ``` ### -SessionTypeOption + Sets type-specific options for the session configuration. Enter a session type options object, such as the **PSWorkflowExecutionOption** object that the New-PSWorkflowExecutionOption cmdlet returns. @@ -505,6 +538,7 @@ Accept wildcard characters: False ``` ### -TransportOption + Sets transport options for the session configuration. Enter a transport options object, such as the **WSManConfigurationOption** object that the New-PSTransportOption cmdlet returns. @@ -527,6 +561,7 @@ Accept wildcard characters: False ``` ### -Path + Adds or replaces a session configuration file (.pssc), such as one created by the New-PSSessionConfigurationFile cmdlet. If you omit the path, the default is the current directory. @@ -547,6 +582,7 @@ Accept wildcard characters: False ``` ### -ModulesToImport + Specifies the modules and snap-ins that are automatically imported into sessions that use the session configuration. Enter the module and snap-in names. @@ -572,6 +608,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -587,6 +624,7 @@ Accept wildcard characters: False ``` ### -WhatIf + Shows what would happen if the cmdlet runs. The cmdlet is not run. @@ -603,21 +641,27 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### Microsoft.WSMan.Management.WSManConfigLeafElement ## NOTES -* To run this cmdlet, start Windows PowerShell with the "Run as administrator" option. -* The **Set-PSSessionConfiguration** cmdlet does not change the configuration name and the WSMan provider does not support the Rename-Item cmdlet. To change the name of a session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the configuration and then use the Register-PSSessionConfiguration cmdlet to create and register a new session configuration. -* You can use the **Set-PSSessionConfiguration** cmdlet to change the default Microsoft.PowerShell and Microsoft.PowerShell32 session configurations. They are not protected. To revert to the original version of a default session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the default session configuration and then use the Enable-PSRemoting cmdlet to restore it. -* The properties of a session configuration object vary with the options set for the session configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties. -* You can use commands in the WSMan: drive to change the properties of session configurations. However, you cannot use the WSMan: drive in Windows PowerShell 2.0 to change session configuration properties that are introduced in Windows PowerShell 3.0, such as **OutputBufferingMode**. Windows PowerShell 2.0 commands do not generate an error, but they are ineffective. To change properties introduced in Windows PowerShell 3.0, use the WSMan: drive in Windows PowerShell 3.0. + +- To run this cmdlet, start Windows PowerShell with the "Run as administrator" option. +- The **Set-PSSessionConfiguration** cmdlet does not change the configuration name and the WSMan provider does not support the Rename-Item cmdlet. To change the name of a session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the configuration and then use the Register-PSSessionConfiguration cmdlet to create and register a new session configuration. +- You can use the **Set-PSSessionConfiguration** cmdlet to change the default Microsoft.PowerShell and Microsoft.PowerShell32 session configurations. They are not protected. To revert to the original version of a default session configuration, use the Unregister-PSSessionConfiguration cmdlet to delete the default session configuration and then use the Enable-PSRemoting cmdlet to restore it. +- The properties of a session configuration object vary with the options set for the session configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties. +- You can use commands in the WSMan: drive to change the properties of session configurations. However, you cannot use the WSMan: drive in Windows PowerShell 2.0 to change session configuration properties that are introduced in Windows PowerShell 3.0, such as **OutputBufferingMode**. Windows PowerShell 2.0 commands do not generate an error, but they are ineffective. To change properties introduced in Windows PowerShell 3.0, use the WSMan: drive in Windows PowerShell 3.0. + ## RELATED LINKS [Disable-PSSessionConfiguration](Disable-PSSessionConfiguration.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Set-StrictMode.md b/reference/3.0/Microsoft.PowerShell.Core/Set-StrictMode.md index 225f1022f915..997177f45f3d 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Set-StrictMode.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Set-StrictMode.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,23 +7,28 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113450 external help file: System.Management.Automation.dll-Help.xml title: Set-StrictMode --- - # Set-StrictMode + ## SYNOPSIS + Establishes and enforces coding rules in expressions, scripts, and script blocks. + ## SYNTAX ### Version (Default) + ``` Set-StrictMode -Version [] ``` ### Off + ``` Set-StrictMode [-Off] [] ``` ## DESCRIPTION + The Set-StrictMode cmdlet configures strict mode for the current scope (and all child scopes) and turns it on and off. When strict mode is on, Windows PowerShell generates a terminating error when the content of an expression, script, or script block violates basic best-practice coding rules. @@ -34,12 +39,14 @@ Unlike the Set-PSDebug cmdlet, Set-StrictMode affects only the current scope and When Set-StrictMode is off, uninitialized variables (Version 1) are assumed to have a value of 0 (zero) or $null, depending on type. References to non-existent properties return $null, and the results of function syntax that is not valid vary with the error. Unnamed variables are not permitted. + ## EXAMPLES ### Example 1 + ``` -PS C:\> set-strictmode -version 1.0 -PS C:\> $a -gt 5 +PS> set-strictmode -version 1.0 +PS> $a -gt 5 False The variable $a cannot be retrieved because it has not been set yet. At line:1 char:3 @@ -52,19 +59,21 @@ This command turns strict mode on and sets it to version 1.0. As a result, attempts to reference variables that are not initialized will fail. The sample output shows the effect of version 1.0 strict mode. + ### Example 2 + ``` -PS C:\> # set-strictmode -version 2.0 +PS> # set-strictmode -version 2.0 # Strict mode is off by default. -PS C:\> function add ($a, $b) {$a + $b} -PS C:\> add 3 4 +PS> function add ($a, $b) {$a + $b} +PS> add 3 4 7 -PS C:\> add(3,4) +PS> add(3,4) 3 4 -PS C:\> set-strictmode -version 2.0 -PS C:\> add(3,4) +PS> set-strictmode -version 2.0 +PS> add(3,4) The function or command was called like a method. Parameters should be separated by spaces, as described in 'Get-Help about_Parameter.' At line:1 char:4 @@ -72,13 +81,13 @@ At line:1 char:4 + CategoryInfo : InvalidOperation: (:) [], RuntimeException + FullyQualifiedErrorId : StrictModeFunctionCallWithParens -PS C:\> set-strictmode -off -PS C:\> $string = "This is a string." -PS C:\> $string.Month -PS C:\> -PS C:\> set-strictmode -version 2.0 -PS C:\> $string = "This is a string." -PS C:\> $string.Month +PS> set-strictmode -off +PS> $string = "This is a string." +PS> $string.Month +PS> +PS> set-strictmode -version 2.0 +PS> $string = "This is a string." +PS> $string.Month Property 'month' cannot be found on this object; make sure it exists. At line:1 char:9 @@ -97,9 +106,11 @@ With version 2.0 strict mode, it is correctly interpreted as faulty syntax for s Without version 2.0, the reference to the non-existent Month property of a string returns only null. With version 2.0, it is interpreted correctly as a reference error. + ## PARAMETERS ### -Off + Turns strict mode off. This parameter also turns off "Set-PSDebug -Strict". @@ -116,6 +127,7 @@ Accept wildcard characters: False ``` ### -Version + Specifies the conditions that cause an error in strict mode. This parameter is required. @@ -150,19 +162,27 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### None + You cannot pipe input to this cmdlet. + ## OUTPUTS ### None + This cmdlet does not return any output. + ## NOTES -* Set-StrictMode is similar to the Strict parameter of Set-PSDebug. "Set-Strictmode -version 1" is equivalent to "Set-PSDebug -strict", except that Set-PSDebug is effective in all scopes. Set-StrictMode is effective only in the scope in which it is set and in its child scopes. For more information about scopes in Windows PowerShell, see about_Scopes. -* +- Set-StrictMode is similar to the Strict parameter of Set-PSDebug. "Set-Strictmode -version 1" is equivalent to "Set-PSDebug -strict", except that Set-PSDebug is effective in all scopes. Set-StrictMode is effective only in the scope in which it is set and in its child scopes. For more information about scopes in Windows PowerShell, see about_Scopes. + +- + ## RELATED LINKS [Set-PSDebug](Set-PSDebug.md) diff --git a/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md b/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md index 337ef4ff4986..89fece00add3 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md @@ -1,4 +1,4 @@ ---- +--- ms.date: 06/09/2017 schema: 2.0.0 locale: en-us @@ -7,13 +7,16 @@ online version: http://go.microsoft.com/fwlink/?LinkID=113405 external help file: System.Management.Automation.dll-Help.xml title: Start-Job --- - # Start-Job + ## SYNOPSIS + Starts a Windows PowerShell background job. + ## SYNTAX ### ComputerName (Default) + ``` Start-Job [-Name ] [-ScriptBlock] [-Credential ] [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -21,11 +24,13 @@ Start-Job [-Name ] [-ScriptBlock] [-Credential [[-DefinitionPath] ] [[-Type] ] [] ``` ### LiteralFilePathComputerName + ``` Start-Job [-Name ] [-Credential ] -LiteralPath [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -33,6 +38,7 @@ Start-Job [-Name ] [-Credential ] -LiteralPath ``` ### FilePathComputerName + ``` Start-Job [-Name ] [-Credential ] [-FilePath] [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -40,6 +46,7 @@ Start-Job [-Name ] [-Credential ] [-FilePath] ``` ## DESCRIPTION + The **Start-Job** cmdlet starts a Windows PowerShell background job on the local computer. A Windows PowerShell background job runs a command "in the background" without interacting with the current session. @@ -55,11 +62,13 @@ For more information, see about_Remote_Jobs. Beginning in Windows PowerShell 3.0, **Start-Job** can start instances of custom job types, such as scheduled jobs. For information about using **Start-Job** to start jobs with custom types, see the help topics for the job type feature. + ## EXAMPLES ### Example 1 + ``` -PS C:\> start-job -scriptblock {get-process} +PS> start-job -scriptblock {get-process} Id Name State HasMoreData Location Command --- ---- ----- ----------- -------- ------- @@ -69,9 +78,11 @@ Id Name State HasMoreData Location Command This command starts a background job that runs a Get-Process command. The command returns a job object with information about the job. The command prompt returns immediately so that you can work in the session while the job runs in the background. + ### Example 2 + ``` -PS C:\> $jobWRM = invoke-command -computerName (get-content servers.txt) -scriptblock {get-service winrm} -jobname WinRM -throttlelimit 16 -AsJob +PS> $jobWRM = invoke-command -computerName (get-content servers.txt) -scriptblock {get-service winrm} -jobname WinRM -throttlelimit 16 -AsJob ``` This command uses the Invoke-Command cmdlet and its AsJob parameter to start a background job that runs a "get-service winrm" command on numerous computers. @@ -81,10 +92,12 @@ The command uses the ComputerName parameter to specify the computers on which th The value of the ComputerName parameter is a Get-Content command that gets the text in the Servers.txt file, a file of computer names in a domain. The command uses the ScriptBlock parameter to specify the command and the JobName parameter to specify a friendly name for the job. + ### Example 3 + ``` -PS C:\> $j = start-job -scriptblock {get-eventlog -log system} -credential domain01\user01 -PS C:\> $j | format-list -property * +PS> $j = start-job -scriptblock {get-eventlog -log system} -credential domain01\user01 +PS> $j | format-list -property * HasMoreData : True StatusMessage : @@ -104,10 +117,10 @@ Debug : {} Warning : {} StateChanged : -PS C:\> $j.JobStateInfo.state +PS> $j.JobStateInfo.state Completed -PS C:\> $results = receive-job -job $j -PS C:\> $results +PS> $results = receive-job -job $j +PS> $results Index Time Type Source EventID Message ----- ---- ---- ------ ------- ------- @@ -136,31 +149,39 @@ The fourth command uses the Receive-Job cmdlet to get the results of the job. It stores the results in the $results variable. The final command displays the contents of the $results variable. + ### Example 4 + ``` -PS C:\> start-job -filepath c:\scripts\sample.ps1 +PS> start-job -filepath c:\scripts\sample.ps1 ``` This command runs the Sample.ps1 script as a background job. + ### Example 5 + ``` -PS C:\> start-job -name WinRm -scriptblock {get-process winrm} +PS> start-job -name WinRm -scriptblock {get-process winrm} ``` This command runs a background job that gets the WinRM process on the local computer. The command uses the ScriptBlock parameter to specify the command that runs in the background job. It uses the Name parameter to specify a friendly name for the new job. + ### Example 6 + ``` -PS C:\> start-job -name GetMappingFiles -initializationScript {import-module MapFunctions} -scriptblock {Get-Map -name * | set-content D:\Maps.tif} -runAs32 +PS> start-job -name GetMappingFiles -initializationScript {import-module MapFunctions} -scriptblock {Get-Map -name * | set-content D:\Maps.tif} -runAs32 ``` This command starts a job that collects a large amount of data and saves it in a .tif file. The command uses the InitializationScript parameter to run a script block that imports a required module. It also uses the RunAs32 parameter to run the job in a 32-bit process even if the computer has a 64-bit operating system. + ## PARAMETERS ### -ArgumentList + Specifies the arguments (parameter values) for the script that is specified by the **FilePath** parameter. Because all of the values that follow the ArgumentList parameter name are interpreted as being values of ArgumentList, the ArgumentList parameter should be the last parameter in the command. @@ -178,6 +199,7 @@ Accept wildcard characters: False ``` ### -Authentication + Specifies the mechanism that is used to authenticate the user's credentials. Valid values are **Default**, **Basic**, **Credssp**, **Digest**, **Kerberos**, **Negotiate**, and **NegotiateWithImplicitCredential**. The default value is **Default**. @@ -203,6 +225,7 @@ Accept wildcard characters: False ``` ### -Credential + Specifies a user account that has permission to perform this action. The default is the current user. @@ -221,6 +244,7 @@ Accept wildcard characters: False ``` ### -FilePath + Runs the specified local script as a background job. Enter the path and file name of the script or pipe a script path to **Start-Job**. The script must reside on the local computer or in a directory that the local computer can access. @@ -240,6 +264,7 @@ Accept wildcard characters: False ``` ### -InitializationScript + Specifies commands that run before the job starts. Enclose the commands in braces ( { } ) to create a script block. @@ -259,6 +284,7 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies input to the command. Enter a variable that contains the objects, or type a command or expression that generates the objects. @@ -277,6 +303,7 @@ Accept wildcard characters: False ``` ### -LiteralPath + Runs the specified local script as a background job. Enter the path to a script on the local computer. @@ -298,6 +325,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies a friendly name for the new job. You can use the name to identify the job to other job cmdlets, such as Stop-Job. @@ -316,6 +344,7 @@ Accept wildcard characters: False ``` ### -PSVersion + Runs the job with the specified version of Windows PowerShell. Valid values are 2.0 and 3.0. @@ -334,6 +363,7 @@ Accept wildcard characters: False ``` ### -RunAs32 + Runs the job in a 32-bit process. Use this parameter to force the job to run in a 32-bit process on a 64-bit operating system. @@ -352,6 +382,7 @@ Accept wildcard characters: False ``` ### -ScriptBlock + Specifies the commands to run in the background job. Enclose the commands in braces ( { } ) to create a script block. This parameter is required. @@ -369,6 +400,7 @@ Accept wildcard characters: False ``` ### -DefinitionName + Starts the job with the specified job definition name. Use this parameter to start custom job types that have a definition name, such as scheduled jobs. @@ -392,6 +424,7 @@ Accept wildcard characters: False ``` ### -DefinitionPath + Starts the job at the specified path location. Enter the definition path. The concatenation of the values of the **DefinitionPath** and **DefinitionName** parameters should be the fully-qualified path to the job definition. @@ -414,6 +447,7 @@ Accept wildcard characters: False ``` ### -Type + Starts only jobs of the specified custom type. Enter a custom job type name, such as PSScheduledJob for scheduled jobs or PSWorkflowJob for workflows jobs. This parameter is not valid for standard background jobs. @@ -433,20 +467,28 @@ Accept wildcard characters: False ``` ### CommonParameters + This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + ## INPUTS ### System.String + You can pipe an object with the Name property to the Name parameter. For example, you can pipe a FileInfo object from Get-ChildItem to **Start-Job**. + ## OUTPUTS ### System.Management.Automation.PSRemotingJob + **Start-Job** returns an object that represents the job that it started. + ## NOTES -* To run in the background, **Start-Job** runs in its own session within the current session. When you use the Invoke-Command cmdlet to run a **Start-Job** command in a session on a remote computer, **Start-Job** runs in a session within the remote session. -* +- To run in the background, **Start-Job** runs in its own session within the current session. When you use the Invoke-Command cmdlet to run a **Start-Job** command in a session on a remote computer, **Start-Job** runs in a session within the remote session. + +- + ## RELATED LINKS [Get-Job](Get-Job.md)