diff --git a/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md b/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md index f473b4fcdbab..f76fd14c7ac7 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md +++ b/reference/3.0/Microsoft.PowerShell.Core/Start-Job.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 08/09/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -7,11 +7,11 @@ online version: https://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. +Starts a PowerShell background job. ## SYNTAX @@ -26,7 +26,8 @@ Start-Job [-Name ] [-ScriptBlock] [-Credential [[-DefinitionPath] ] [[-Type] ] [] +Start-Job [-DefinitionName] [[-DefinitionPath] ] [[-Type] ] + [] ``` ### LiteralFilePathComputerName @@ -47,144 +48,172 @@ Start-Job [-Name ] [-Credential ] [-FilePath] ## DESCRIPTION -The **Start-Job** cmdlet starts a Windows PowerShell background job on the local computer. +The `Start-Job` cmdlet starts a PowerShell background job on the local computer. -A Windows PowerShell background job runs a command "in the background" without interacting with the current session. -When you start a background job, a job object is returned immediately, even if the job takes an extended time to complete. -You can continue to work in the session without interruption while the job runs. +A PowerShell background job runs a command without interacting with the current session. When you +start a background job, a job object returns immediately, even if the job takes an extended time to +finish. You can continue to work in the session without interruption while the job runs. -The job object contains useful information about the job, but it does not contain the job results. -When the job completes, use the Receive-Job cmdlet to get the results of the job. -For more information about background jobs, see [about_Jobs](./About/about_Jobs.md). +The job object contains useful information about the job, but it doesn't contain the job results. +When the job finishes, use the `Receive-Job` cmdlet to get the results of the job. For more +information about background jobs, see [about_Jobs](./About/about_Jobs.md). -To run a background job on a remote computer, use the AsJob parameter that is available on many cmdlets, or use the Invoke-Command cmdlet to run a **Start-Job** command on the remote computer. -For more information, see [about_Remote_Jobs](./About/about_Remote_Jobs.md). +To run a background job on a remote computer, use the **AsJob** parameter that is available on many +cmdlets, or use the `Invoke-Command` cmdlet to run a `Start-Job` command on the remote computer. For +more information, see [about_Remote_Jobs](./About/about_Remote_Jobs.md). -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. +Starting in PowerShell 3.0, `Start-Job` can start instances of custom job types, such as scheduled +jobs. For information about how to use `Start-Job` to start jobs with custom types, see the help +documents for the job type feature. ## EXAMPLES -### Example 1 +### Example 1: Start a background job +This example starts a job that runs in the background on the local computer. + +```powershell +Start-Job -ScriptBlock {Get-Process} ``` -PS> start-job -scriptblock {get-process} -Id Name State HasMoreData Location Command ---- ---- ----- ----------- -------- ------- -1 Job1 Running True localhost get-process +```Output +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Running True localhost Get-Process ``` -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. +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Process` as a background job. The job +information is displayed and PowerShell returns to a prompt while the job runs in the background. -### Example 2 +### Example 2: Start a job using Invoke-Command -``` -PS> $jobWRM = invoke-command -computerName (get-content servers.txt) -scriptblock {get-service winrm} -jobname WinRM -throttlelimit 16 -AsJob +This example runs a job on multiple computers. The job is stored in a variable and is executed by +using the variable name on the PowerShell command line. + +```powershell +$jobWRM = Invoke-Command -ComputerName (Get-Content -Path C:\Servers.txt) -ScriptBlock { + Get-Service -Name 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. -Because the command is running on a server with substantial network traffic, the command uses the ThrottleLimit parameter of Invoke-Command to limit the number of concurrent commands to 16. +A job that uses `Invoke-Command` is created and stored in the `$jobWRM` variable. `Invoke-Command` +uses the **ComputerName** parameter to specify the computers where the job runs. `Get-Content` gets +the server names from the `C:\Servers.txt` file. -The command uses the ComputerName parameter to specify the computers on which the job runs. -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 **ScriptBlock** parameter specifies a command that `Get-Service` gets the **WinRM** service. The +**JobName** parameter specifies a friendly name for the job, **WinRM**. The **ThrottleLimit** +parameter limits the number of concurrent commands to 16. The **AsJob** parameter starts a +background job that runs the command on the servers. -The command uses the ScriptBlock parameter to specify the command and the JobName parameter to specify a friendly name for the job. +### Example 3: Get job information -### Example 3 +This example gets information about a job and displays the results of a completed job that was run +on the local computer. +```powershell +$j = Start-Job -ScriptBlock { Get-WinEvent -Log System } -Credential Domain01\User01 +$j | Select-Object -Property * ``` -PS> $j = start-job -scriptblock {get-eventlog -log system} -credential domain01\user01 -PS> $j | format-list -property * +```Output +State : Completed HasMoreData : True StatusMessage : Location : localhost -Command : get-eventlog -log system -JobStateInfo : Running +Command : Get-WinEvent -Log System +JobStateInfo : Completed Finished : System.Threading.ManualResetEvent -InstanceId : 2d9d775f-63e0-4d48-b4bc-c05d0e177f34 -Id : 1 -Name : Job1 -ChildJobs : {Job2} +InstanceId : 27ce3fd9-40ed-488a-99e5-679cd91b9dd3 +Id : 18 +Name : Job18 +ChildJobs : {Job19} +PSBeginTime : 8/8/2019 14:41:57 +PSEndTime : 8/8/2019 14:42:07 +PSJobTypeName : BackgroundJob Output : {} Error : {} Progress : {} Verbose : {} Debug : {} Warning : {} -StateChanged : - -PS> $j.JobStateInfo.state -Completed -PS> $results = receive-job -job $j -PS> $results - -Index Time Type Source EventID Message ------ ---- ---- ------ ------- ------- -84366 Feb 18 19:20 Information Service Control M... 7036 The description... -84365 Feb 18 19:16 Information Service Control M... 7036 The description... -84364 Feb 18 19:10 Information Service Control M... 7036 The description... -... +Information : {} ``` -These commands manage a background job that gets all of the events from the System log in Event Viewer. -The job runs on the local computer. +`Start-Job` uses the **ScriptBlock** parameter to run a command that specifies `Get-WinEvent` to get +the **System** log. The **Credential** parameter specifies a domain user account with permission to +run the job on the computer. The job object is stored in the `$j` variable. -The first command uses the **Start-Job** cmdlet to start the job. -It uses the Credential parameter to specify the user account of a user who has permission to run the job on the computer. -Then it saves the job object that **Start-Job** returns in the $j variable. +The object in the `$j` variable is sent down the pipeline to `Select-Object`. The **Property** +parameter specifies an asterisk (`*`) to display all the job object's properties. -At this point, you can resume your other work while the job completes. +### Example 4: Run a script as a background job -The second command uses a pipeline operator (|) to pass 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. +In this example, a script on the local computer is run as a background job. -The third command displays the value of the JobStateInfo property. -This contains the status of the job. +```powershell +Start-Job -FilePath C:\Scripts\Sample.ps1 +``` -The fourth command uses the Receive-Job cmdlet to get the results of the job. -It stores the results in the $results variable. +`Start-Job` uses the **FilePath** parameter to specify a script file that's stored on the local +computer. -The final command displays the contents of the $results variable. +### Example 5: Get a process using a background job -### Example 4 +This example uses a background job to get a specified process by name. -``` -PS> start-job -filepath c:\scripts\sample.ps1 +```powershell +Start-Job -Name PShellJob -ScriptBlock { Get-Process -Name PowerShell } ``` -This command runs the Sample.ps1 script as a background job. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **PShellJob**. The +**ScriptBlock** parameter specifies `Get-Process` to get processes with the name **PowerShell**. -### Example 5 +### Example 6: Collect and save data by using a background job +This example starts a job that collects a large amount of map data and then saves it in a `.tif` +file. + +```powershell +Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock { + Get-Map -Name * | Set-Content -Path D:\Maps.tif } -RunAs32 ``` -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. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **GetMappingFiles**. The +**InitializationScript** parameter runs a script block that imports the **MapFunctions** module. The +**ScriptBlock** parameter runs `Get-Map` and `Set-Content` saves the data in the location specified +by the **Path** parameter. The **RunAs32** parameter runs the process as 32-bit, even on a 64-bit +operating system. + +### Example 7: Pass input to a background job -### Example 6 +This example uses the `$input` automatic variable to process an input object. Use `Receive-Job` to +view the job's output. +```powershell +Start-Job -ScriptBlock { Get-Content $input } -InputObject "C:\Servers.txt" +Receive-Job -Name Job45 -Keep ``` -PS> start-job -name GetMappingFiles -initializationScript {import-module MapFunctions} -scriptblock {Get-Map -name * | set-content D:\Maps.tif} -runAs32 + +```Output +Server01 +Server02 +Server03 +Server04 ``` -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. +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Content` with the `$input` automatic +variable. The `$input` variable gets objects from the **InputObject** parameter. `Receive-Job` uses +the **Name** parameter to specify the job and outputs the results. The **Keep** parameter saves the +job output so it can be viewed again during the PowerShell session. ## PARAMETERS ### -ArgumentList -Specifies the arguments (parameter values) for the script that is specified by the **FilePath** parameter. +Specifies an array of arguments, or 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. +Because all the values that follow the **ArgumentList** parameter name are interpreted as being +values of **ArgumentList**, specify this parameter as the last parameter in the command. ```yaml Type: Object[] @@ -200,22 +229,38 @@ 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**. +Specifies the mechanism that is used to authenticate user credentials. -CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of Windows. +The acceptable values for this parameter are as follows: -For more information about the values of this parameter, see [AuthenticationMechanism Enumeration](/dotnet/api/system.management.automation.runspaces.authenticationmechanism) in the MSDN library. +- Default +- Basic +- Credssp +- Digest +- Kerberos +- Negotiate +- NegotiateWithImplicitCredential -CAUTION: Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. -This mechanism increases the security risk of the remote operation. -If the remote computer is compromised, the credentials that are passed to it can be used to control the network session. +The default value is Default. + +CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions +of the Windows operating system. + +For more information about the values of this parameter, see +[AuthenticationMechanism](/dotnet/api/system.management.automation.runspaces.authenticationmechanism). + +> [!CAUTION] +> Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are +> passed to a remote computer to be authenticated, is designed for commands that require +> authentication on more than one resource, such as accessing a remote network share. This mechanism +> increases the security risk of the remote operation. If the remote computer is compromised, the +> credentials that are passed to it can be used to control the network session. ```yaml Type: AuthenticationMechanism Parameter Sets: ComputerName, LiteralFilePathComputerName, FilePathComputerName Aliases: +Accepted values: Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos Required: False Position: Named @@ -226,10 +271,11 @@ Accept wildcard characters: False ### -Credential -Specifies a user account that has permission to perform this action. -The default is the current user. +Specifies a user account that has permission to perform this action. If the **Credential** parameter +isn't specified, the command uses the current user's credentials. -Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one from the Get-Credential cmdlet. +Type a user name, such as **User01** or **Domain01\User01**, or enter a **PSCredential** object, +such as one from the `Get-Credential` cmdlet. ```yaml Type: PSCredential @@ -243,13 +289,63 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -DefinitionName + +Specifies the definition name of the job that this cmdlet starts. Use this parameter to start custom +job types that have a definition name, such as scheduled jobs. + +When you use `Start-Job` to start an instance of a scheduled job, the job starts immediately, +regardless of job triggers or job options. The resulting job instance is a scheduled job, but it +isn't saved to disk like triggered scheduled jobs. You can't use the **ArgumentList** parameter of +`Start-Job` to provide values for parameters of scripts that run in a scheduled job. For more +information, see [about_Scheduled_Jobs](../PSScheduledJob/About/about_Scheduled_Jobs.md). + +This parameter was introduced in PowerShell 3.0. + +```yaml +Type: String +Parameter Sets: DefinitionName +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DefinitionPath + +Specifies path of the definition for the job that this cmdlet starts. Enter the definition path. The +concatenation of the values of the **DefinitionPath** and **DefinitionName** parameters is the fully +qualified path of the job definition. Use this parameter to start custom job types that have a +definition path, such as scheduled jobs. + +For scheduled jobs, the value of the **DefinitionPath** parameter is +`$home\AppData\Local\Windows\PowerShell\ScheduledJob`. + +This parameter was introduced in PowerShell 3.0. + +```yaml +Type: String +Parameter Sets: DefinitionName +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +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. +Specifies a local script that `Start-Job` runs as a background job. Enter the path and file name of +the script or use the pipeline to send a script path to `Start-Job`. The script must be on the local +computer or in a folder that the local computer can access. -When you use this parameter, Windows PowerShell converts the contents of the specified script file to a script block and runs the script block as a background job. +When you use this parameter, PowerShell converts the contents of the specified script file to a +script block and runs the script block as a background job. ```yaml Type: String @@ -257,7 +353,7 @@ Parameter Sets: FilePathComputerName Aliases: Required: True -Position: 1 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -265,11 +361,11 @@ Accept wildcard characters: False ### -InitializationScript -Specifies commands that run before the job starts. -Enclose the commands in braces ( { } ) to create a script block. +Specifies commands that run before the job starts. To create a script block, enclose the commands in +curly braces (`{}`). -Use this parameter to prepare the session in which the job runs. -For example, you can use it to add functions, snap-ins, and modules to the session. +Use this parameter to prepare the session in which the job runs. For example, you can use it to add +functions, snap-ins, and modules to the session. ```yaml Type: ScriptBlock @@ -277,7 +373,7 @@ Parameter Sets: ComputerName, LiteralFilePathComputerName, FilePathComputerName Aliases: Required: False -Position: 2 +Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -285,10 +381,11 @@ 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. +Specifies input to the command. Enter a variable that contains the objects, or type a command or +expression that generates the objects. -In the value of the **ScriptBlock** parameter, use the $input automatic variable to represent the input objects. +In the value of the **ScriptBlock** parameter, use the `$input` automatic variable to represent the +input objects. ```yaml Type: PSObject @@ -304,13 +401,13 @@ Accept wildcard characters: False ### -LiteralPath -Runs the specified local script as a background job. -Enter the path to a script on the local computer. +Specifies a local script that this cmdlet runs as a background job. Enter the path of a script on +the local computer. -Unlike the **FilePath** parameter, the value of **LiteralPath** is used exactly as it is typed. -No characters are interpreted as wildcards. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +`Start-Job` uses the value of the **LiteralPath** parameter exactly as it's typed. No characters are +interpreted as wildcard characters. If the path includes escape characters, enclose it in single +quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape +sequences. ```yaml Type: String @@ -326,10 +423,11 @@ 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. +Specifies a friendly name for the new job. You can use the name to identify the job to other job +cmdlets, such as the `Stop-Job` cmdlet. -The default friendly name is Job#, where "#" is an ordinal number that is incremented for each job. +The default friendly name is `Job#`, where `#` is an ordinal number that is incremented for each +job. ```yaml Type: String @@ -338,17 +436,17 @@ Aliases: Required: False Position: Named -Default value: Job +Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -PSVersion -Runs the job with the specified version of Windows PowerShell. -Valid values are 2.0 and 3.0. +Specifies a version. `Start-Job` runs the job with the version of PowerShell. The acceptable values +for this parameter are: `2.0` and `3.0`. -This parameter is introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: Version @@ -357,17 +455,19 @@ Aliases: Required: False Position: Named -Default value: 3.0 +Default value: None Accept pipeline input: False 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. +Indicates that `Start-Job` runs the job in a 32-bit process. **RunAs32** forces the job to run in a +32-bit process, even on a 64-bit operating system. -NOTE: On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the **Start-Job** command includes the **RunAs32** parameter, you cannot use the **Credential** parameter to specify the credentials of another user. +On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the `Start-Job` command includes +the **RunAs32** parameter, you can't use the **Credential** parameter to specify the credentials of +another user. ```yaml Type: SwitchParameter @@ -383,9 +483,9 @@ 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. +Specifies the commands to run in the background job. To create a script block, enclose the commands +in curly braces (`{}`). Use the `$input` automatic variable to access the value of the +**InputObject** parameter. This parameter is required. ```yaml Type: ScriptBlock @@ -393,54 +493,7 @@ Parameter Sets: ComputerName Aliases: Command Required: True -Position: 1 -Default value: None -Accept pipeline input: False -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. - -When you use **Start-Job** to start an instance of a scheduled job, the job starts immediately, regardless of job triggers or job options. -The resulting job instance is a scheduled job, but it is not saved to disk like triggered scheduled jobs. -Also, you cannot use the **ArgumentList** parameter of **Start-Job** to provide values for parameters of scripts that run in a scheduled job. -For more information, see [about_Scheduled_Jobs](../PSScheduledJob/About/about_Scheduled_Jobs.md). - -This parameter is introduced in Windows PowerShell 3.0. - -```yaml -Type: String -Parameter Sets: DefinitionName -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -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. -Use this parameter to start custom job types that have a definition path, such as scheduled jobs. - -For scheduled jobs, the value of the **DefinitionPath** parameter is "$home\AppData\Local\Windows\PowerShell\ScheduledJob". - -This parameter is introduced in Windows PowerShell 3.0. - -```yaml -Type: String -Parameter Sets: DefinitionName -Aliases: - -Required: False -Position: 2 +Position: 0 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -448,11 +501,11 @@ 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. +Specifies the custom type for jobs started by `Start-Job`. Enter a custom job type name, such as +PSScheduledJob for scheduled jobs or PSWorkflowJob for workflows jobs. This parameter isn't valid +for standard background jobs. -This parameter is introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -460,7 +513,7 @@ Parameter Sets: DefinitionName Aliases: Required: False -Position: 3 +Position: 2 Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -468,29 +521,37 @@ 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](./About/about_CommonParameters.md). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://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**. +You can use the pipeline to send an object with the **Name** property to the **Name** parameter. For +example, you can pipeline 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. +`Start-Job` returns a **PSRemotingJob** 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 in 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 in the remote session. ## RELATED LINKS +[about_Jobs](./About/about_Jobs.md) + +[about_Job_Details](./About/about_Job_Details.md) + +[about_Remote_Jobs](./About/about_Remote_Jobs.md) + [Get-Job](Get-Job.md) [Invoke-Command](Invoke-Command.md) @@ -501,16 +562,8 @@ For example, you can pipe a FileInfo object from Get-ChildItem to **Start-Job**. [Resume-Job](Resume-Job.md) -[Start-Job](Start-Job.md) - [Stop-Job](Stop-Job.md) [Suspend-Job](Suspend-Job.md) [Wait-Job](Wait-Job.md) - -[about_Job_Details](About/about_Job_Details.md) - -[about_Remote_Jobs](About/about_Remote_Jobs.md) - -[about_Jobs](About/about_Jobs.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/Start-Job.md b/reference/4.0/Microsoft.PowerShell.Core/Start-Job.md index e594dc10e669..70c90018c785 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/Start-Job.md +++ b/reference/4.0/Microsoft.PowerShell.Core/Start-Job.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 08/09/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,11 +11,12 @@ title: Start-Job # Start-Job ## SYNOPSIS -Starts a Windows PowerShell background job. +Starts a PowerShell background job. ## SYNTAX ### ComputerName (Default) + ``` Start-Job [-Name ] [-ScriptBlock] [-Credential ] [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -23,11 +24,14 @@ Start-Job [-Name ] [-ScriptBlock] [-Credential [[-DefinitionPath] ] [[-Type] ] [] +Start-Job [-DefinitionName] [[-DefinitionPath] ] [[-Type] ] + [] ``` ### FilePathComputerName + ``` Start-Job [-Name ] [-Credential ] [-FilePath] [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -35,6 +39,7 @@ Start-Job [-Name ] [-Credential ] [-FilePath] ``` ### LiteralFilePathComputerName + ``` Start-Job [-Name ] [-Credential ] -LiteralPath [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -42,148 +47,173 @@ Start-Job [-Name ] [-Credential ] -LiteralPath ``` ## 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. -When you start a background job, a job object is returned immediately, even if the job takes an extended time to complete. -You can continue to work in the session without interruption while the job runs. +The `Start-Job` cmdlet starts a PowerShell background job on the local computer. -The job object contains useful information about the job, but it does not contain the job results. -When the job completes, use the Receive-Job cmdlet to get the results of the job. -For more information about background jobs, see about_Jobs. +A PowerShell background job runs a command without interacting with the current session. When you +start a background job, a job object returns immediately, even if the job takes an extended time to +finish. You can continue to work in the session without interruption while the job runs. -To run a background job on a remote computer, use the AsJob parameter that is available on many cmdlets, or use the Invoke-Command cmdlet to run a **Start-Job** command on the remote computer. -For more information, see about_Remote_Jobs. +The job object contains useful information about the job, but it doesn't contain the job results. +When the job finishes, use the `Receive-Job` cmdlet to get the results of the job. For more +information about background jobs, see [about_Jobs](./About/about_Jobs.md). -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. +To run a background job on a remote computer, use the **AsJob** parameter that is available on many +cmdlets, or use the `Invoke-Command` cmdlet to run a `Start-Job` command on the remote computer. For +more information, see [about_Remote_Jobs](./About/about_Remote_Jobs.md). + +Starting in PowerShell 3.0, `Start-Job` can start instances of custom job types, such as scheduled +jobs. For information about how to use `Start-Job` to start jobs with custom types, see the help +documents for the job type feature. ## EXAMPLES -### Example 1 +### Example 1: Start a background job + +This example starts a job that runs in the background on the local computer. + +```powershell +Start-Job -ScriptBlock {Get-Process} ``` -PS C:\> start-job -scriptblock {get-process} -Id Name State HasMoreData Location Command ---- ---- ----- ----------- -------- ------- -1 Job1 Running True localhost get-process +```Output +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Running True localhost Get-Process ``` -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. +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Process` as a background job. The job +information is displayed and PowerShell returns to a prompt 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 +### Example 2: Start a job using Invoke-Command + +This example runs a job on multiple computers. The job is stored in a variable and is executed by +using the variable name on the PowerShell command line. + +```powershell +$jobWRM = Invoke-Command -ComputerName (Get-Content -Path C:\Servers.txt) -ScriptBlock { + Get-Service -Name 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. -Because the command is running on a server with substantial network traffic, the command uses the ThrottleLimit parameter of Invoke-Command to limit the number of concurrent commands to 16. +A job that uses `Invoke-Command` is created and stored in the `$jobWRM` variable. `Invoke-Command` +uses the **ComputerName** parameter to specify the computers where the job runs. `Get-Content` gets +the server names from the `C:\Servers.txt` file. -The command uses the ComputerName parameter to specify the computers on which the job runs. -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 **ScriptBlock** parameter specifies a command that `Get-Service` gets the **WinRM** service. The +**JobName** parameter specifies a friendly name for the job, **WinRM**. The **ThrottleLimit** +parameter limits the number of concurrent commands to 16. The **AsJob** parameter starts a +background job that runs the command on the servers. -The command uses the ScriptBlock parameter to specify the command and the JobName parameter to specify a friendly name for the job. +### Example 3: Get job information -### Example 3 +This example gets information about a job and displays the results of a completed job that was run +on the local computer. + +```powershell +$j = Start-Job -ScriptBlock { Get-WinEvent -Log System } -Credential Domain01\User01 +$j | Select-Object -Property * ``` -PS C:\> $j = start-job -scriptblock {get-eventlog -log system} -credential domain01\user01 -PS C:\> $j | format-list -property * +```Output +State : Completed HasMoreData : True StatusMessage : Location : localhost -Command : get-eventlog -log system -JobStateInfo : Running +Command : Get-WinEvent -Log System +JobStateInfo : Completed Finished : System.Threading.ManualResetEvent -InstanceId : 2d9d775f-63e0-4d48-b4bc-c05d0e177f34 -Id : 1 -Name : Job1 -ChildJobs : {Job2} +InstanceId : 27ce3fd9-40ed-488a-99e5-679cd91b9dd3 +Id : 18 +Name : Job18 +ChildJobs : {Job19} +PSBeginTime : 8/8/2019 14:41:57 +PSEndTime : 8/8/2019 14:42:07 +PSJobTypeName : BackgroundJob Output : {} Error : {} Progress : {} Verbose : {} Debug : {} Warning : {} -StateChanged : - -PS C:\> $j.JobStateInfo.state -Completed -PS C:\> $results = receive-job -job $j -PS C:\> $results - -Index Time Type Source EventID Message ------ ---- ---- ------ ------- ------- -84366 Feb 18 19:20 Information Service Control M... 7036 The description... -84365 Feb 18 19:16 Information Service Control M... 7036 The description... -84364 Feb 18 19:10 Information Service Control M... 7036 The description... -... +Information : {} ``` -These commands manage a background job that gets all of the events from the System log in Event Viewer. -The job runs on the local computer. +`Start-Job` uses the **ScriptBlock** parameter to run a command that specifies `Get-WinEvent` to get +the **System** log. The **Credential** parameter specifies a domain user account with permission to +run the job on the computer. The job object is stored in the `$j` variable. -The first command uses the **Start-Job** cmdlet to start the job. -It uses the Credential parameter to specify the user account of a user who has permission to run the job on the computer. -Then it saves the job object that **Start-Job** returns in the $j variable. +The object in the `$j` variable is sent down the pipeline to `Select-Object`. The **Property** +parameter specifies an asterisk (`*`) to display all the job object's properties. -At this point, you can resume your other work while the job completes. +### Example 4: Run a script as a background job -The second command uses a pipeline operator (|) to pass 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. +In this example, a script on the local computer is run as a background job. -The third command displays the value of the JobStateInfo property. -This contains the status of the job. +```powershell +Start-Job -FilePath C:\Scripts\Sample.ps1 +``` -The fourth command uses the Receive-Job cmdlet to get the results of the job. -It stores the results in the $results variable. +`Start-Job` uses the **FilePath** parameter to specify a script file that's stored on the local +computer. -The final command displays the contents of the $results variable. +### Example 5: Get a process using a background job -### Example 4 -``` -PS C:\> start-job -filepath c:\scripts\sample.ps1 +This example uses a background job to get a specified process by name. + +```powershell +Start-Job -Name PShellJob -ScriptBlock { Get-Process -Name PowerShell } ``` -This command runs the Sample.ps1 script as a background job. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **PShellJob**. The +**ScriptBlock** parameter specifies `Get-Process` to get processes with the name **PowerShell**. -### Example 5 -``` -PS C:\> start-job -name WinRm -scriptblock {get-process winrm} -``` +### Example 6: Collect and save data by using a background job -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. +This example starts a job that collects a large amount of map data and then saves it in a `.tif` +file. -### Example 6 -``` -PS C:\> start-job -name GetMappingFiles -initializationScript {import-module MapFunctions} -scriptblock {Get-Map -name * | set-content D:\Maps.tif} -runAs32 +```powershell +Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock { + Get-Map -Name * | Set-Content -Path 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. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **GetMappingFiles**. The +**InitializationScript** parameter runs a script block that imports the **MapFunctions** module. The +**ScriptBlock** parameter runs `Get-Map` and `Set-Content` saves the data in the location specified +by the **Path** parameter. The **RunAs32** parameter runs the process as 32-bit, even on a 64-bit +operating system. ### Example 7: Pass input to a background job +This example uses the `$input` automatic variable to process an input object. Use `Receive-Job` to +view the job's output. + +```powershell +Start-Job -ScriptBlock { Get-Content $input } -InputObject "C:\Servers.txt" +Receive-Job -Name Job45 -Keep ``` -PS C:\> Start-Job -ScriptBlock {Write-Output $Input} -InputObject 'Hello, world!' + +```Output +Server01 +Server02 +Server03 +Server04 ``` -This command starts a job that simply accesses and outputs its input. -The command uses the *InputObject* parameter to pass input to the job. -Input to a job is accessed via the $Input automatic variable. -The $_ automatic variable (alias $PSItem) is not populated. +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Content` with the `$input` automatic +variable. The `$input` variable gets objects from the **InputObject** parameter. `Receive-Job` uses +the **Name** parameter to specify the job and outputs the results. The **Keep** parameter saves the +job output so it can be viewed again during the PowerShell session. ## 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. +Specifies an array of arguments, or parameter values, for the script that is specified by the +**FilePath** parameter. + +Because all the values that follow the **ArgumentList** parameter name are interpreted as being +values of **ArgumentList**, specify this parameter as the last parameter in the command. ```yaml Type: Object[] @@ -198,17 +228,33 @@ 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**. -CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of Windows. +Specifies the mechanism that is used to authenticate user credentials. + +The acceptable values for this parameter are as follows: + +- Default +- Basic +- Credssp +- Digest +- Kerberos +- Negotiate +- NegotiateWithImplicitCredential + +The default value is Default. -For more information about the values of this parameter, see [AuthenticationMechanism Enumeration](https://msdn.microsoft.com/library/system.management.automation.runspaces.authenticationmechanism) in the MSDN library. +CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions +of the Windows operating system. -CAUTION: Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. -This mechanism increases the security risk of the remote operation. -If the remote computer is compromised, the credentials that are passed to it can be used to control the network session. +For more information about the values of this parameter, see +[AuthenticationMechanism](/dotnet/api/system.management.automation.runspaces.authenticationmechanism). + +> [!CAUTION] +> Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are +> passed to a remote computer to be authenticated, is designed for commands that require +> authentication on more than one resource, such as accessing a remote network share. This mechanism +> increases the security risk of the remote operation. If the remote computer is compromised, the +> credentials that are passed to it can be used to control the network session. ```yaml Type: AuthenticationMechanism @@ -224,10 +270,12 @@ Accept wildcard characters: False ``` ### -Credential -Specifies a user account that has permission to perform this action. -The default is the current user. -Type a user name, such as "User01" or "Domain01\User01", or enter a PSCredential object, such as one from the Get-Credential cmdlet. +Specifies a user account that has permission to perform this action. If the **Credential** parameter +isn't specified, the command uses the current user's credentials. + +Type a user name, such as **User01** or **Domain01\User01**, or enter a **PSCredential** object, +such as one from the `Get-Credential` cmdlet. ```yaml Type: PSCredential @@ -242,15 +290,17 @@ 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. -When you use **Start-Job** to start an instance of a scheduled job, the job starts immediately, regardless of job triggers or job options. -The resulting job instance is a scheduled job, but it is not saved to disk like triggered scheduled jobs. -Also, you cannot use the **ArgumentList** parameter of **Start-Job** to provide values for parameters of scripts that run in a scheduled job. -For more information, see about_Scheduled_Jobs. +Specifies the definition name of the job that this cmdlet starts. Use this parameter to start custom +job types that have a definition name, such as scheduled jobs. -This parameter is introduced in Windows PowerShell 3.0. +When you use `Start-Job` to start an instance of a scheduled job, the job starts immediately, +regardless of job triggers or job options. The resulting job instance is a scheduled job, but it +isn't saved to disk like triggered scheduled jobs. You can't use the **ArgumentList** parameter of +`Start-Job` to provide values for parameters of scripts that run in a scheduled job. For more +information, see [about_Scheduled_Jobs](../PSScheduledJob/About/about_Scheduled_Jobs.md). + +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -265,14 +315,16 @@ 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. -Use this parameter to start custom job types that have a definition path, such as scheduled jobs. -For scheduled jobs, the value of the **DefinitionPath** parameter is "$home\AppData\Local\Windows\PowerShell\ScheduledJob". +Specifies path of the definition for the job that this cmdlet starts. Enter the definition path. The +concatenation of the values of the **DefinitionPath** and **DefinitionName** parameters is the fully +qualified path of the job definition. Use this parameter to start custom job types that have a +definition path, such as scheduled jobs. + +For scheduled jobs, the value of the **DefinitionPath** parameter is +`$home\AppData\Local\Windows\PowerShell\ScheduledJob`. -This parameter is introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -287,11 +339,13 @@ 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. -When you use this parameter, Windows PowerShell converts the contents of the specified script file to a script block and runs the script block as a background job. +Specifies a local script that `Start-Job` runs as a background job. Enter the path and file name of +the script or use the pipeline to send a script path to `Start-Job`. The script must be on the local +computer or in a folder that the local computer can access. + +When you use this parameter, PowerShell converts the contents of the specified script file to a +script block and runs the script block as a background job. ```yaml Type: String @@ -306,11 +360,12 @@ Accept wildcard characters: False ``` ### -InitializationScript -Specifies commands that run before the job starts. -Enclose the commands in braces ( { } ) to create a script block. -Use this parameter to prepare the session in which the job runs. -For example, you can use it to add functions, snap-ins, and modules to the session. +Specifies commands that run before the job starts. To create a script block, enclose the commands in +curly braces (`{}`). + +Use this parameter to prepare the session in which the job runs. For example, you can use it to add +functions, snap-ins, and modules to the session. ```yaml Type: ScriptBlock @@ -325,10 +380,12 @@ 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. -In the value of the **ScriptBlock** parameter, use the $input automatic variable to represent the input objects. +Specifies input to the command. Enter a variable that contains the objects, or type a command or +expression that generates the objects. + +In the value of the **ScriptBlock** parameter, use the `$input` automatic variable to represent the +input objects. ```yaml Type: PSObject @@ -343,13 +400,14 @@ Accept wildcard characters: False ``` ### -LiteralPath -Runs the specified local script as a background job. -Enter the path to a script on the local computer. -Unlike the **FilePath** parameter, the value of **LiteralPath** is used exactly as it is typed. -No characters are interpreted as wildcards. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Specifies a local script that this cmdlet runs as a background job. Enter the path of a script on +the local computer. + +`Start-Job` uses the value of the **LiteralPath** parameter exactly as it's typed. No characters are +interpreted as wildcard characters. If the path includes escape characters, enclose it in single +quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape +sequences. ```yaml Type: String @@ -364,10 +422,12 @@ 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. -The default friendly name is Job#, where "#" is an ordinal number that is incremented for each job. +Specifies a friendly name for the new job. You can use the name to identify the job to other job +cmdlets, such as the `Stop-Job` cmdlet. + +The default friendly name is `Job#`, where `#` is an ordinal number that is incremented for each +job. ```yaml Type: String @@ -376,16 +436,17 @@ Aliases: Required: False Position: Named -Default value: Job +Default value: None Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` ### -PSVersion -Runs the job with the specified version of Windows PowerShell. -Valid values are 2.0 and 3.0. -This parameter is introduced in Windows PowerShell 3.0. +Specifies a version. `Start-Job` runs the job with the version of PowerShell. The acceptable values +for this parameter are: `2.0` and `3.0`. + +This parameter was introduced in PowerShell 3.0. ```yaml Type: Version @@ -394,16 +455,19 @@ Aliases: Required: False Position: Named -Default value: 3.0 +Default value: None Accept pipeline input: False 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. -NOTE: On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the **Start-Job** command includes the **RunAs32** parameter, you cannot use the **Credential** parameter to specify the credentials of another user. +Indicates that `Start-Job` runs the job in a 32-bit process. **RunAs32** forces the job to run in a +32-bit process, even on a 64-bit operating system. + +On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the `Start-Job` command includes +the **RunAs32** parameter, you can't use the **Credential** parameter to specify the credentials of +another user. ```yaml Type: SwitchParameter @@ -418,10 +482,10 @@ Accept wildcard characters: False ``` ### -ScriptBlock -Specifies the commands to run in the background job. -Enclose the commands in braces ( { } ) to create a script block. -Use the $Input automatic variable to access the value of the *InputObject* parameter. -This parameter is required. + +Specifies the commands to run in the background job. To create a script block, enclose the commands +in curly braces (`{}`). Use the `$input` automatic variable to access the value of the +**InputObject** parameter. This parameter is required. ```yaml Type: ScriptBlock @@ -436,11 +500,12 @@ 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. -This parameter is introduced in Windows PowerShell 3.0. +Specifies the custom type for jobs started by `Start-Job`. Enter a custom job type name, such as +PSScheduledJob for scheduled jobs or PSWorkflowJob for workflows jobs. This parameter isn't valid +for standard background jobs. + +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -455,26 +520,38 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://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**. + +You can use the pipeline to send an object with the **Name** property to the **Name** parameter. For +example, you can pipeline 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. + +`Start-Job` returns a **PSRemotingJob** 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 in 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 in the remote session. ## RELATED LINKS +[about_Jobs](./About/about_Jobs.md) + +[about_Job_Details](./About/about_Job_Details.md) + +[about_Remote_Jobs](./About/about_Remote_Jobs.md) + [Get-Job](Get-Job.md) [Invoke-Command](Invoke-Command.md) @@ -485,16 +562,8 @@ For example, you can pipe a FileInfo object from Get-ChildItem to **Start-Job**. [Resume-Job](Resume-Job.md) -[Start-Job](Start-Job.md) - [Stop-Job](Stop-Job.md) [Suspend-Job](Suspend-Job.md) [Wait-Job](Wait-Job.md) - -[about_Job_Details](About/about_Job_Details.md) - -[about_Remote_Jobs](About/about_Remote_Jobs.md) - -[about_Jobs](About/about_Jobs.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/Start-Job.md b/reference/5.0/Microsoft.PowerShell.Core/Start-Job.md index c1e0a2138109..c80cfd5aab99 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/Start-Job.md +++ b/reference/5.0/Microsoft.PowerShell.Core/Start-Job.md @@ -1,5 +1,5 @@ --- -ms.date: 06/09/2017 +ms.date: 08/09/2019 schema: 2.0.0 locale: en-us keywords: powershell,cmdlet @@ -11,11 +11,12 @@ title: Start-Job # Start-Job ## SYNOPSIS -Starts a Windows PowerShell background job. +Starts a PowerShell background job. ## SYNTAX ### ComputerName (Default) + ``` Start-Job [-Name ] [-ScriptBlock] [-Credential ] [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -23,11 +24,14 @@ Start-Job [-Name ] [-ScriptBlock] [-Credential [[-DefinitionPath] ] [[-Type] ] [] +Start-Job [-DefinitionName] [[-DefinitionPath] ] [[-Type] ] + [] ``` ### FilePathComputerName + ``` Start-Job [-Name ] [-Credential ] [-FilePath] [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -35,6 +39,7 @@ Start-Job [-Name ] [-Credential ] [-FilePath] ``` ### LiteralFilePathComputerName + ``` Start-Job [-Name ] [-Credential ] -LiteralPath [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -42,167 +47,197 @@ Start-Job [-Name ] [-Credential ] -LiteralPath ``` ### FilePathVMId + ``` Start-Job [-VMGuid] [] ``` ### VMId + ``` Start-Job [-VMGuid] [] ``` ### FilePathVMName + ``` Start-Job -VMName [] ``` ### VMName + ``` Start-Job -VMName [] ``` ## DESCRIPTION -The **Start-Job** cmdlet starts a Windows PowerShell background job on the local computer. -A Windows PowerShell background job runs a command without interacting with the current session. -When you start a background job, a job object returns immediately, even if the job takes an extended time to finish. -You can continue to work in the session without interruption while the job runs. +The `Start-Job` cmdlet starts a PowerShell background job on the local computer. -The job object contains useful information about the job, but it does not contain the job results. -When the job finishes, use the Receive-Job cmdlet to get the results of the job. -For more information about background jobs, see about_Jobs. +A PowerShell background job runs a command without interacting with the current session. When you +start a background job, a job object returns immediately, even if the job takes an extended time to +finish. You can continue to work in the session without interruption while the job runs. -To run a background job on a remote computer, use the *AsJob* parameter that is available on many cmdlets, or use the Invoke-Command cmdlet to run a **Start-Job** command on the remote computer. -For more information, see about_Remote_Jobs. +The job object contains useful information about the job, but it doesn't contain the job results. +When the job finishes, use the `Receive-Job` cmdlet to get the results of the job. For more +information about background jobs, see [about_Jobs](./About/about_Jobs.md). -Starting in Windows PowerShell 3.0, **Start-Job** can start instances of custom job types, such as scheduled jobs. -For information about how to use **Start-Job** to start jobs with custom types, see the help topics for the job type feature. +To run a background job on a remote computer, use the **AsJob** parameter that is available on many +cmdlets, or use the `Invoke-Command` cmdlet to run a `Start-Job` command on the remote computer. For +more information, see [about_Remote_Jobs](./About/about_Remote_Jobs.md). + +Starting in PowerShell 3.0, `Start-Job` can start instances of custom job types, such as scheduled +jobs. For information about how to use `Start-Job` to start jobs with custom types, see the help +documents for the job type feature. ## EXAMPLES ### Example 1: Start a background job + +This example starts a job that runs in the background on the local computer. + +```powershell +Start-Job -ScriptBlock {Get-Process} ``` -PS C:\> Start-Job -ScriptBlock {Get-Process} -Id Name State HasMoreData Location Command ---- ---- ----- ----------- -------- ------- -1 Job1 Running True localhost get-process + +```Output +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Running True localhost Get-Process ``` -This command starts a background job that runs a Get-Process command. -The command returns a job object that has information about the job. -The command prompt returns immediately so that you can work in the session while the job runs in the background. +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Process` as a background job. The job +information is displayed and PowerShell returns to a prompt while the job runs in the background. -### Example 2: Start a job by using Invoke-Command -``` -PS C:\> $jobWRM = Invoke-Command -ComputerName (Get-Content servers.txt) -ScriptBlock {Get-Service winrm} -JobName "WinRM" -ThrottleLimit 16 -AsJob +### Example 2: Start a job using Invoke-Command + +This example runs a job on multiple computers. The job is stored in a variable and is executed by +using the variable name on the PowerShell command line. + +```powershell +$jobWRM = Invoke-Command -ComputerName (Get-Content -Path C:\Servers.txt) -ScriptBlock { + Get-Service -Name 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 command on many computers. -Because the command is running on a server that has significant network traffic, the command uses the *ThrottleLimit* parameter of **Invoke-Command** to limit the number of concurrent commands to 16. +A job that uses `Invoke-Command` is created and stored in the `$jobWRM` variable. `Invoke-Command` +uses the **ComputerName** parameter to specify the computers where the job runs. `Get-Content` gets +the server names from the `C:\Servers.txt` file. -The command uses the *ComputerName* parameter to specify the computers on which the job runs. -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 **ScriptBlock** parameter specifies a command that `Get-Service` gets the **WinRM** service. The +**JobName** parameter specifies a friendly name for the job, **WinRM**. The **ThrottleLimit** +parameter limits the number of concurrent commands to 16. The **AsJob** parameter starts a +background job that runs the command on the servers. -The command uses the *ScriptBlock* parameter to specify the command and the *JobName* parameter to specify a friendly name for the job. +### Example 3: Get job information -### Example 3: Get events from the System log on the local computer +This example gets information about a job and displays the results of a completed job that was run +on the local computer. + +```powershell +$j = Start-Job -ScriptBlock { Get-WinEvent -Log System } -Credential Domain01\User01 +$j | Select-Object -Property * ``` -PS C:\> $j = Start-Job -ScriptBlock {Get-EventLog -Log system} -Credential domain01\user01 -PS C:\> $j | Format-List -Property * +```Output +State : Completed HasMoreData : True StatusMessage : Location : localhost -Command : get-eventlog -log system -JobStateInfo : Running +Command : Get-WinEvent -Log System +JobStateInfo : Completed Finished : System.Threading.ManualResetEvent -InstanceId : 2d9d775f-63e0-4d48-b4bc-c05d0e177f34 -Id : 1 -Name : Job1 -ChildJobs : {Job2} +InstanceId : 27ce3fd9-40ed-488a-99e5-679cd91b9dd3 +Id : 18 +Name : Job18 +ChildJobs : {Job19} +PSBeginTime : 8/8/2019 14:41:57 +PSEndTime : 8/8/2019 14:42:07 +PSJobTypeName : BackgroundJob Output : {} Error : {} Progress : {} Verbose : {} Debug : {} Warning : {} -StateChanged : - -PS C:\> $j.JobStateInfo.state -Completed -PS C:\> $results = Receive-Job -Job $j -PS C:\> $results - -Index Time Type Source EventID Message ------ ---- ---- ------ ------- ------- -84366 Feb 18 19:20 Information Service Control M... 7036 The description... -84365 Feb 18 19:16 Information Service Control M... 7036 The description... -84364 Feb 18 19:10 Information Service Control M... 7036 The description... -... +Information : {} ``` -These commands manage a background job that gets all of the events from the System log in Event Viewer. -The job runs on the local computer. - -The first command uses the **Start-Job** cmdlet to start the job. -It uses the *Credential* parameter to specify the user account of a user who has permission to run the job on the computer. -Then it stores the job object that **Start-Job** returns in the $j variable. +`Start-Job` uses the **ScriptBlock** parameter to run a command that specifies `Get-WinEvent` to get +the **System** log. The **Credential** parameter specifies a domain user account with permission to +run the job on the computer. The job object is stored in the `$j` variable. -At this point, you can resume your other work while the job finishes. +The object in the `$j` variable is sent down the pipeline to `Select-Object`. The **Property** +parameter specifies an asterisk (`*`) to display all the job object's properties. -The second command uses a pipeline operator (|) to pass 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. +### Example 4: Run a script as a background job -The third command displays the value of the **JobStateInfo** property. -This contains the status of the job. +In this example, a script on the local computer is run as a background job. -The fourth command uses the **Receive-Job** cmdlet to get the results of the job. -It stores the results in the $results variable. +```powershell +Start-Job -FilePath C:\Scripts\Sample.ps1 +``` -The final command displays the contents of the $results variable. +`Start-Job` uses the **FilePath** parameter to specify a script file that's stored on the local +computer. -### Example 4: Run a script as a background job -``` -PS C:\> Start-Job -FilePath "c:\scripts\sample.ps1" -``` +### Example 5: Get a process using a background job -This command runs the Sample.ps1 script as a background job. +This example uses a background job to get a specified process by name. -### Example 5: Get a process by name by using a background job -``` -PS C:\> Start-Job -Name "WinRm" -ScriptBlock {Get-Process winrm} +```powershell +Start-Job -Name PShellJob -ScriptBlock { Get-Process -Name PowerShell } ``` -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. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **PShellJob**. The +**ScriptBlock** parameter specifies `Get-Process` to get processes with the name **PowerShell**. ### Example 6: Collect and save data by using a background job -``` -PS C:\> Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock {Get-Map -Name * | Set-Content D:\Maps.tif} -RunAs32 + +This example starts a job that collects a large amount of map data and then saves it in a `.tif` +file. + +```powershell +Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock { + Get-Map -Name * | Set-Content -Path D:\Maps.tif } -RunAs32 ``` -This command starts a job that collects lots of data, and then 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. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **GetMappingFiles**. The +**InitializationScript** parameter runs a script block that imports the **MapFunctions** module. The +**ScriptBlock** parameter runs `Get-Map` and `Set-Content` saves the data in the location specified +by the **Path** parameter. The **RunAs32** parameter runs the process as 32-bit, even on a 64-bit +operating system. ### Example 7: Pass input to a background job +This example uses the `$input` automatic variable to process an input object. Use `Receive-Job` to +view the job's output. + +```powershell +Start-Job -ScriptBlock { Get-Content $input } -InputObject "C:\Servers.txt" +Receive-Job -Name Job45 -Keep ``` -PS C:\> Start-Job -ScriptBlock {Write-Output $Input} -InputObject 'Hello, world!' + +```Output +Server01 +Server02 +Server03 +Server04 ``` -This command starts a job that simply accesses and outputs its input. -The command uses the *InputObject* parameter to pass input to the job. -Input to a job is accessed via the $Input automatic variable. -The $_ automatic variable (alias $PSItem) is not populated. +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Content` with the `$input` automatic +variable. The `$input` variable gets objects from the **InputObject** parameter. `Receive-Job` uses +the **Name** parameter to specify the job and outputs the results. The **Keep** parameter saves the +job output so it can be viewed again during the PowerShell session. ## PARAMETERS ### -ArgumentList -Specifies an array of arguments, or 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*, specify this parameter as the last parameter in the command. +Specifies an array of arguments, or parameter values, for the script that is specified by the +**FilePath** parameter. + +Because all the values that follow the **ArgumentList** parameter name are interpreted as being +values of **ArgumentList**, specify this parameter as the last parameter in the command. ```yaml Type: Object[] @@ -217,8 +252,10 @@ Accept wildcard characters: False ``` ### -Authentication + Specifies the mechanism that is used to authenticate user credentials. -The acceptable values for this parameter are: + +The acceptable values for this parameter are as follows: - Default - Basic @@ -230,13 +267,18 @@ The acceptable values for this parameter are: The default value is Default. -CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of the Windows operating system. +CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions +of the Windows operating system. -For more information about the values of this parameter, see [AuthenticationMechanism Enumeration](https://msdn.microsoft.com/library/system.management.automation.runspaces.authenticationmechanism) in the MSDN library. +For more information about the values of this parameter, see +[AuthenticationMechanism](/dotnet/api/system.management.automation.runspaces.authenticationmechanism). -Caution: Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. -This mechanism increases the security risk of the remote operation. -If the remote computer is compromised, the credentials that are passed to it can be used to control the network session. +> [!CAUTION] +> Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are +> passed to a remote computer to be authenticated, is designed for commands that require +> authentication on more than one resource, such as accessing a remote network share. This mechanism +> increases the security risk of the remote operation. If the remote computer is compromised, the +> credentials that are passed to it can be used to control the network session. ```yaml Type: AuthenticationMechanism @@ -246,16 +288,18 @@ Accepted values: Default, Basic, Negotiate, NegotiateWithImplicitCredential, Cre Required: False Position: Named -Default value: None +Default value: Default Accept pipeline input: False Accept wildcard characters: False ``` ### -Credential -Specifies a user account that has permission to perform this action. -The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one from the Get-Credential cmdlet. +Specifies a user account that has permission to perform this action. If the **Credential** parameter +isn't specified, the command uses the current user's credentials. + +Type a user name, such as **User01** or **Domain01\User01**, or enter a **PSCredential** object, +such as one from the `Get-Credential` cmdlet. ```yaml Type: PSCredential @@ -264,21 +308,23 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: False Accept wildcard characters: False ``` ### -DefinitionName -Specifies the definition name of the job that this cmdlet starts. -Use this parameter to start custom job types that have a definition name, such as scheduled jobs. -When you use **Start-Job** to start an instance of a scheduled job, the job starts immediately, regardless of job triggers or job options. -The resulting job instance is a scheduled job, but it is not saved to disk like triggered scheduled jobs. -Also, you cannot use the *ArgumentList* parameter of **Start-Job** to provide values for parameters of scripts that run in a scheduled job. -For more information, see about_Scheduled_Jobs. +Specifies the definition name of the job that this cmdlet starts. Use this parameter to start custom +job types that have a definition name, such as scheduled jobs. -This parameter was introduced in Windows PowerShell 3.0. +When you use `Start-Job` to start an instance of a scheduled job, the job starts immediately, +regardless of job triggers or job options. The resulting job instance is a scheduled job, but it +isn't saved to disk like triggered scheduled jobs. You can't use the **ArgumentList** parameter of +`Start-Job` to provide values for parameters of scripts that run in a scheduled job. For more +information, see [about_Scheduled_Jobs](../PSScheduledJob/About/about_Scheduled_Jobs.md). + +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -293,14 +339,16 @@ Accept wildcard characters: False ``` ### -DefinitionPath -Specifies path of the definition for the job that this cmdlet starts. -Enter the definition path. -The concatenation of the values of the *DefinitionPath* and *DefinitionName* parameters is the fully qualified path of the job definition. -Use this parameter to start custom job types that have a definition path, such as scheduled jobs. -For scheduled jobs, the value of the *DefinitionPath* parameter is `$home\AppData\Local\Windows\PowerShell\ScheduledJob`. +Specifies path of the definition for the job that this cmdlet starts. Enter the definition path. The +concatenation of the values of the **DefinitionPath** and **DefinitionName** parameters is the fully +qualified path of the job definition. Use this parameter to start custom job types that have a +definition path, such as scheduled jobs. + +For scheduled jobs, the value of the **DefinitionPath** parameter is +`$home\AppData\Local\Windows\PowerShell\ScheduledJob`. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -315,11 +363,13 @@ Accept wildcard characters: False ``` ### -FilePath -Specifies a local script that this cmdlet runs as a background job. -Enter the path and file name of the script or pipe a script path to **Start-Job**. -The script must be on the local computer or in a folder that the local computer can access. -When you use this parameter, Windows PowerShell converts the contents of the specified script file to a script block and runs the script block as a background job. +Specifies a local script that `Start-Job` runs as a background job. Enter the path and file name of +the script or use the pipeline to send a script path to `Start-Job`. The script must be on the local +computer or in a folder that the local computer can access. + +When you use this parameter, PowerShell converts the contents of the specified script file to a +script block and runs the script block as a background job. ```yaml Type: String @@ -334,11 +384,12 @@ Accept wildcard characters: False ``` ### -InitializationScript -Specifies commands that run before the job starts. -Enclose the commands in braces ( { } ) to create a script block. -Use this parameter to prepare the session in which the job runs. -For example, you can use it to add functions, snap-ins, and modules to the session. +Specifies commands that run before the job starts. To create a script block, enclose the commands in +curly braces (`{}`). + +Use this parameter to prepare the session in which the job runs. For example, you can use it to add +functions, snap-ins, and modules to the session. ```yaml Type: ScriptBlock @@ -353,10 +404,12 @@ 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. -In the value of the *ScriptBlock* parameter, use the $Input automatic variable to represent the input objects. +Specifies input to the command. Enter a variable that contains the objects, or type a command or +expression that generates the objects. + +In the value of the **ScriptBlock** parameter, use the `$input` automatic variable to represent the +input objects. ```yaml Type: PSObject @@ -371,13 +424,14 @@ Accept wildcard characters: False ``` ### -LiteralPath -Specifies a local script that this cmdlet runs as a background job. -Enter the path of a script on the local computer. -Unlike the *FilePath* parameter, this cmdlet uses the value of the *LiteralPath* parameter exactly as it is typed. -No characters are interpreted as wildcard characters. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Specifies a local script that this cmdlet runs as a background job. Enter the path of a script on +the local computer. + +`Start-Job` uses the value of the **LiteralPath** parameter exactly as it's typed. No characters are +interpreted as wildcard characters. If the path includes escape characters, enclose it in single +quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape +sequences. ```yaml Type: String @@ -392,10 +446,12 @@ 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 the Stop-Job cmdlet. -The default friendly name is Job#, where # is an ordinal number that is incremented for each job. +Specifies a friendly name for the new job. You can use the name to identify the job to other job +cmdlets, such as the `Stop-Job` cmdlet. + +The default friendly name is `Job#`, where `#` is an ordinal number that is incremented for each +job. ```yaml Type: String @@ -410,11 +466,11 @@ Accept wildcard characters: False ``` ### -PSVersion -Specifies a version. -This cmdlet runs the job with the version of Windows PowerShell. -The acceptable values for this parameter are: 2.0 and 3.0. -This parameter was introduced in Windows PowerShell 3.0. +Specifies a version. `Start-Job` runs the job with the version of PowerShell. The acceptable values +for this parameter are: `2.0` and `3.0`. + +This parameter was introduced in PowerShell 3.0. ```yaml Type: Version @@ -429,10 +485,13 @@ Accept wildcard characters: False ``` ### -RunAs32 -Indicates that this cmdlet 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. -On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the **Start-Job** command includes the *RunAs32* parameter, you cannot use the *Credential* parameter to specify the credentials of another user. +Indicates that `Start-Job` runs the job in a 32-bit process. **RunAs32** forces the job to run in a +32-bit process, even on a 64-bit operating system. + +On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the `Start-Job` command includes +the **RunAs32** parameter, you can't use the **Credential** parameter to specify the credentials of +another user. ```yaml Type: SwitchParameter @@ -441,16 +500,16 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -ScriptBlock -Specifies the commands to run in the background job. -Enclose the commands in braces ( { } ) to create a script block. -Use the $Input automatic variable to access the value of the *InputObject* parameter. -This parameter is required. + +Specifies the commands to run in the background job. To create a script block, enclose the commands +in curly braces (`{}`). Use the `$input` automatic variable to access the value of the +**InputObject** parameter. This parameter is required. ```yaml Type: ScriptBlock @@ -465,11 +524,12 @@ Accept wildcard characters: False ``` ### -Type -Specifies the custom type for jobs that this cmdlet starts. -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. -This parameter was introduced in Windows PowerShell 3.0. +Specifies the custom type for jobs started by `Start-Job`. Enter a custom job type name, such as +PSScheduledJob for scheduled jobs or PSWorkflowJob for workflows jobs. This parameter isn't valid +for standard background jobs. + +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -484,26 +544,38 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.String -You can pipe an object that has the **Name** property to the *Name* parameter. -For example, you can pipe a **FileInfo** object from Get-ChildItem to **Start-Job**. + +You can use the pipeline to send an object with the **Name** property to the **Name** parameter. For +example, you can pipeline a **FileInfo** object from `Get-ChildItem` to `Start-Job`. ## OUTPUTS ### System.Management.Automation.PSRemotingJob -This cmdlet returns an object that represents the job that it started. + +`Start-Job` returns a **PSRemotingJob** object that represents the job that it started. ## NOTES -* To run in the background, **Start-Job** runs in its own session in 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 in the remote session. -* +To run in the background, `Start-Job` runs in its own session in 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 in the remote session. ## RELATED LINKS +[about_Jobs](./About/about_Jobs.md) + +[about_Job_Details](./About/about_Job_Details.md) + +[about_Remote_Jobs](./About/about_Remote_Jobs.md) + [Get-Job](Get-Job.md) [Invoke-Command](Invoke-Command.md) @@ -519,9 +591,3 @@ This cmdlet returns an object that represents the job that it started. [Suspend-Job](Suspend-Job.md) [Wait-Job](Wait-Job.md) - -[about_Job_Details](About/about_Job_Details.md) - -[about_Remote_Jobs](About/about_Remote_Jobs.md) - -[about_Jobs](About/about_Jobs.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/Start-Job.md b/reference/5.1/Microsoft.PowerShell.Core/Start-Job.md index 984c6140d7c7..f923e9cccdb3 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Start-Job.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Start-Job.md @@ -3,7 +3,7 @@ external help file: System.Management.Automation.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Core -ms.date: 06/09/2017 +ms.date: 08/09/2019 online version: https://go.microsoft.com/fwlink/?linkid=821518 schema: 2.0.0 title: Start-Job @@ -12,11 +12,12 @@ title: Start-Job # Start-Job ## SYNOPSIS -Starts a Windows PowerShell background job. +Starts a PowerShell background job. ## SYNTAX ### ComputerName (Default) + ``` Start-Job [-Name ] [-ScriptBlock] [-Credential ] [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -24,11 +25,14 @@ Start-Job [-Name ] [-ScriptBlock] [-Credential [[-DefinitionPath] ] [[-Type] ] [] +Start-Job [-DefinitionName] [[-DefinitionPath] ] [[-Type] ] + [] ``` ### FilePathComputerName + ``` Start-Job [-Name ] [-Credential ] [-FilePath] [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -36,6 +40,7 @@ Start-Job [-Name ] [-Credential ] [-FilePath] ``` ### LiteralFilePathComputerName + ``` Start-Job [-Name ] [-Credential ] -LiteralPath [-Authentication ] [[-InitializationScript] ] [-RunAs32] @@ -43,147 +48,173 @@ Start-Job [-Name ] [-Credential ] -LiteralPath ``` ## DESCRIPTION -The **Start-Job** cmdlet starts a Windows PowerShell background job on the local computer. -A Windows PowerShell background job runs a command without interacting with the current session. -When you start a background job, a job object returns immediately, even if the job takes an extended time to finish. -You can continue to work in the session without interruption while the job runs. +The `Start-Job` cmdlet starts a PowerShell background job on the local computer. -The job object contains useful information about the job, but it does not contain the job results. -When the job finishes, use the Receive-Job cmdlet to get the results of the job. -For more information about background jobs, see about_Jobs. +A PowerShell background job runs a command without interacting with the current session. When you +start a background job, a job object returns immediately, even if the job takes an extended time to +finish. You can continue to work in the session without interruption while the job runs. -To run a background job on a remote computer, use the *AsJob* parameter that is available on many cmdlets, or use the Invoke-Command cmdlet to run a **Start-Job** command on the remote computer. -For more information, see about_Remote_Jobs. +The job object contains useful information about the job, but it doesn't contain the job results. +When the job finishes, use the `Receive-Job` cmdlet to get the results of the job. For more +information about background jobs, see [about_Jobs](./About/about_Jobs.md). -Starting in Windows PowerShell 3.0, **Start-Job** can start instances of custom job types, such as scheduled jobs. -For information about how to use **Start-Job** to start jobs with custom types, see the help topics for the job type feature. +To run a background job on a remote computer, use the **AsJob** parameter that is available on many +cmdlets, or use the `Invoke-Command` cmdlet to run a `Start-Job` command on the remote computer. For +more information, see [about_Remote_Jobs](./About/about_Remote_Jobs.md). + +Starting in PowerShell 3.0, `Start-Job` can start instances of custom job types, such as scheduled +jobs. For information about how to use `Start-Job` to start jobs with custom types, see the help +documents for the job type feature. ## EXAMPLES ### Example 1: Start a background job + +This example starts a job that runs in the background on the local computer. + +```powershell +Start-Job -ScriptBlock {Get-Process} ``` -PS C:\> Start-Job -ScriptBlock {Get-Process} -Id Name State HasMoreData Location Command ---- ---- ----- ----------- -------- ------- -1 Job1 Running True localhost get-process + +```Output +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Running True localhost Get-Process ``` -This command starts a background job that runs a Get-Process command. -The command returns a job object that has information about the job. -The command prompt returns immediately so that you can work in the session while the job runs in the background. +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Process` as a background job. The job +information is displayed and PowerShell returns to a prompt while the job runs in the background. -### Example 2: Start a job by using Invoke-Command -``` -PS C:\> $jobWRM = Invoke-Command -ComputerName (Get-Content servers.txt) -ScriptBlock {Get-Service winrm} -JobName "WinRM" -ThrottleLimit 16 -AsJob +### Example 2: Start a job using Invoke-Command + +This example runs a job on multiple computers. The job is stored in a variable and is executed by +using the variable name on the PowerShell command line. + +```powershell +$jobWRM = Invoke-Command -ComputerName (Get-Content -Path C:\Servers.txt) -ScriptBlock { + Get-Service -Name 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 command on many computers. -Because the command is running on a server that has significant network traffic, the command uses the *ThrottleLimit* parameter of **Invoke-Command** to limit the number of concurrent commands to 16. +A job that uses `Invoke-Command` is created and stored in the `$jobWRM` variable. `Invoke-Command` +uses the **ComputerName** parameter to specify the computers where the job runs. `Get-Content` gets +the server names from the `C:\Servers.txt` file. + +The **ScriptBlock** parameter specifies a command that `Get-Service` gets the **WinRM** service. The +**JobName** parameter specifies a friendly name for the job, **WinRM**. The **ThrottleLimit** +parameter limits the number of concurrent commands to 16. The **AsJob** parameter starts a +background job that runs the command on the servers. -The command uses the *ComputerName* parameter to specify the computers on which the job runs. -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. +### Example 3: Get job information -The command uses the *ScriptBlock* parameter to specify the command and the *JobName* parameter to specify a friendly name for the job. +This example gets information about a job and displays the results of a completed job that was run +on the local computer. -### Example 3: Get events from the System log on the local computer +```powershell +$j = Start-Job -ScriptBlock { Get-WinEvent -Log System } -Credential Domain01\User01 +$j | Select-Object -Property * ``` -PS C:\> $j = Start-Job -ScriptBlock {Get-EventLog -Log system} -Credential domain01\user01 -PS C:\> $j | Format-List -Property * +```Output +State : Completed HasMoreData : True StatusMessage : Location : localhost -Command : get-eventlog -log system -JobStateInfo : Running +Command : Get-WinEvent -Log System +JobStateInfo : Completed Finished : System.Threading.ManualResetEvent -InstanceId : 2d9d775f-63e0-4d48-b4bc-c05d0e177f34 -Id : 1 -Name : Job1 -ChildJobs : {Job2} +InstanceId : 27ce3fd9-40ed-488a-99e5-679cd91b9dd3 +Id : 18 +Name : Job18 +ChildJobs : {Job19} +PSBeginTime : 8/8/2019 14:41:57 +PSEndTime : 8/8/2019 14:42:07 +PSJobTypeName : BackgroundJob Output : {} Error : {} Progress : {} Verbose : {} Debug : {} Warning : {} -StateChanged : - -PS C:\> $j.JobStateInfo.state -Completed -PS C:\> $results = Receive-Job -Job $j -PS C:\> $results - -Index Time Type Source EventID Message ------ ---- ---- ------ ------- ------- -84366 Feb 18 19:20 Information Service Control M... 7036 The description... -84365 Feb 18 19:16 Information Service Control M... 7036 The description... -84364 Feb 18 19:10 Information Service Control M... 7036 The description... -... +Information : {} ``` -These commands manage a background job that gets all of the events from the System log in Event Viewer. -The job runs on the local computer. - -The first command uses the **Start-Job** cmdlet to start the job. -It uses the *Credential* parameter to specify the user account of a user who has permission to run the job on the computer. -Then it stores the job object that **Start-Job** returns in the $j variable. +`Start-Job` uses the **ScriptBlock** parameter to run a command that specifies `Get-WinEvent` to get +the **System** log. The **Credential** parameter specifies a domain user account with permission to +run the job on the computer. The job object is stored in the `$j` variable. -At this point, you can resume your other work while the job finishes. +The object in the `$j` variable is sent down the pipeline to `Select-Object`. The **Property** +parameter specifies an asterisk (`*`) to display all the job object's properties. -The second command uses a pipeline operator (|) to pass 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. +### Example 4: Run a script as a background job -The third command displays the value of the **JobStateInfo** property. -This contains the status of the job. +In this example, a script on the local computer is run as a background job. -The fourth command uses the **Receive-Job** cmdlet to get the results of the job. -It stores the results in the $results variable. +```powershell +Start-Job -FilePath C:\Scripts\Sample.ps1 +``` -The final command displays the contents of the $results variable. +`Start-Job` uses the **FilePath** parameter to specify a script file that's stored on the local +computer. -### Example 4: Run a script as a background job -``` -PS C:\> Start-Job -FilePath "c:\scripts\sample.ps1" -``` +### Example 5: Get a process using a background job -This command runs the Sample.ps1 script as a background job. +This example uses a background job to get a specified process by name. -### Example 5: Get a process by name by using a background job -``` -PS C:\> Start-Job -Name "WinRm" -ScriptBlock {Get-Process winrm} +```powershell +Start-Job -Name PShellJob -ScriptBlock { Get-Process -Name PowerShell } ``` -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. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **PShellJob**. The +**ScriptBlock** parameter specifies `Get-Process` to get processes with the name **PowerShell**. ### Example 6: Collect and save data by using a background job -``` -PS C:\> Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock {Get-Map -Name * | Set-Content D:\Maps.tif} -RunAs32 + +This example starts a job that collects a large amount of map data and then saves it in a `.tif` +file. + +```powershell +Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock { + Get-Map -Name * | Set-Content -Path D:\Maps.tif } -RunAs32 ``` -This command starts a job that collects lots of data, and then 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. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **GetMappingFiles**. The +**InitializationScript** parameter runs a script block that imports the **MapFunctions** module. The +**ScriptBlock** parameter runs `Get-Map` and `Set-Content` saves the data in the location specified +by the **Path** parameter. The **RunAs32** parameter runs the process as 32-bit, even on a 64-bit +operating system. ### Example 7: Pass input to a background job +This example uses the `$input` automatic variable to process an input object. Use `Receive-Job` to +view the job's output. + +```powershell +Start-Job -ScriptBlock { Get-Content $input } -InputObject "C:\Servers.txt" +Receive-Job -Name Job45 -Keep ``` -PS C:\> Start-Job -ScriptBlock {Write-Output $Input} -InputObject 'Hello, world!' + +```Output +Server01 +Server02 +Server03 +Server04 ``` -This command starts a job that simply accesses and outputs its input. -The command uses the *InputObject* parameter to pass input to the job. -Input to a job is accessed via the $Input automatic variable. -The $_ automatic variable (alias $PSItem) is not populated. +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Content` with the `$input` automatic +variable. The `$input` variable gets objects from the **InputObject** parameter. `Receive-Job` uses +the **Name** parameter to specify the job and outputs the results. The **Keep** parameter saves the +job output so it can be viewed again during the PowerShell session. ## PARAMETERS ### -ArgumentList -Specifies an array of arguments, or 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*, specify this parameter as the last parameter in the command. +Specifies an array of arguments, or parameter values, for the script that is specified by the +**FilePath** parameter. + +Because all the values that follow the **ArgumentList** parameter name are interpreted as being +values of **ArgumentList**, specify this parameter as the last parameter in the command. ```yaml Type: Object[] @@ -198,8 +229,10 @@ Accept wildcard characters: False ``` ### -Authentication + Specifies the mechanism that is used to authenticate user credentials. -The acceptable values for this parameter are: + +The acceptable values for this parameter are as follows: - Default - Basic @@ -211,13 +244,18 @@ The acceptable values for this parameter are: The default value is Default. -CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of the Windows operating system. +CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions +of the Windows operating system. -For more information about the values of this parameter, see [AuthenticationMechanism Enumeration](https://msdn.microsoft.com/library/system.management.automation.runspaces.authenticationmechanism) in the MSDN library. +For more information about the values of this parameter, see +[AuthenticationMechanism](/dotnet/api/system.management.automation.runspaces.authenticationmechanism). -Caution: Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. -This mechanism increases the security risk of the remote operation. -If the remote computer is compromised, the credentials that are passed to it can be used to control the network session. +> [!CAUTION] +> Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are +> passed to a remote computer to be authenticated, is designed for commands that require +> authentication on more than one resource, such as accessing a remote network share. This mechanism +> increases the security risk of the remote operation. If the remote computer is compromised, the +> credentials that are passed to it can be used to control the network session. ```yaml Type: AuthenticationMechanism @@ -227,16 +265,18 @@ Accepted values: Default, Basic, Negotiate, NegotiateWithImplicitCredential, Cre Required: False Position: Named -Default value: None +Default value: Default Accept pipeline input: False Accept wildcard characters: False ``` ### -Credential -Specifies a user account that has permission to perform this action. -The default is the current user. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one from the Get-Credential cmdlet. +Specifies a user account that has permission to perform this action. If the **Credential** parameter +isn't specified, the command uses the current user's credentials. + +Type a user name, such as **User01** or **Domain01\User01**, or enter a **PSCredential** object, +such as one from the `Get-Credential` cmdlet. ```yaml Type: PSCredential @@ -245,21 +285,23 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: False Accept wildcard characters: False ``` ### -DefinitionName -Specifies the definition name of the job that this cmdlet starts. -Use this parameter to start custom job types that have a definition name, such as scheduled jobs. -When you use **Start-Job** to start an instance of a scheduled job, the job starts immediately, regardless of job triggers or job options. -The resulting job instance is a scheduled job, but it is not saved to disk like triggered scheduled jobs. -Also, you cannot use the *ArgumentList* parameter of **Start-Job** to provide values for parameters of scripts that run in a scheduled job. -For more information, see about_Scheduled_Jobs. +Specifies the definition name of the job that this cmdlet starts. Use this parameter to start custom +job types that have a definition name, such as scheduled jobs. + +When you use `Start-Job` to start an instance of a scheduled job, the job starts immediately, +regardless of job triggers or job options. The resulting job instance is a scheduled job, but it +isn't saved to disk like triggered scheduled jobs. You can't use the **ArgumentList** parameter of +`Start-Job` to provide values for parameters of scripts that run in a scheduled job. For more +information, see [about_Scheduled_Jobs](../PSScheduledJob/About/about_Scheduled_Jobs.md). -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -274,14 +316,16 @@ Accept wildcard characters: False ``` ### -DefinitionPath -Specifies path of the definition for the job that this cmdlet starts. -Enter the definition path. -The concatenation of the values of the *DefinitionPath* and *DefinitionName* parameters is the fully qualified path of the job definition. -Use this parameter to start custom job types that have a definition path, such as scheduled jobs. -For scheduled jobs, the value of the *DefinitionPath* parameter is `$home\AppData\Local\Windows\PowerShell\ScheduledJob`. +Specifies path of the definition for the job that this cmdlet starts. Enter the definition path. The +concatenation of the values of the **DefinitionPath** and **DefinitionName** parameters is the fully +qualified path of the job definition. Use this parameter to start custom job types that have a +definition path, such as scheduled jobs. -This parameter was introduced in Windows PowerShell 3.0. +For scheduled jobs, the value of the **DefinitionPath** parameter is +`$home\AppData\Local\Windows\PowerShell\ScheduledJob`. + +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -296,11 +340,13 @@ Accept wildcard characters: False ``` ### -FilePath -Specifies a local script that this cmdlet runs as a background job. -Enter the path and file name of the script or pipe a script path to **Start-Job**. -The script must be on the local computer or in a folder that the local computer can access. -When you use this parameter, Windows PowerShell converts the contents of the specified script file to a script block and runs the script block as a background job. +Specifies a local script that `Start-Job` runs as a background job. Enter the path and file name of +the script or use the pipeline to send a script path to `Start-Job`. The script must be on the local +computer or in a folder that the local computer can access. + +When you use this parameter, PowerShell converts the contents of the specified script file to a +script block and runs the script block as a background job. ```yaml Type: String @@ -315,11 +361,12 @@ Accept wildcard characters: False ``` ### -InitializationScript -Specifies commands that run before the job starts. -Enclose the commands in braces ( { } ) to create a script block. -Use this parameter to prepare the session in which the job runs. -For example, you can use it to add functions, snap-ins, and modules to the session. +Specifies commands that run before the job starts. To create a script block, enclose the commands in +curly braces (`{}`). + +Use this parameter to prepare the session in which the job runs. For example, you can use it to add +functions, snap-ins, and modules to the session. ```yaml Type: ScriptBlock @@ -334,10 +381,12 @@ 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. -In the value of the *ScriptBlock* parameter, use the $Input automatic variable to represent the input objects. +Specifies input to the command. Enter a variable that contains the objects, or type a command or +expression that generates the objects. + +In the value of the **ScriptBlock** parameter, use the `$input` automatic variable to represent the +input objects. ```yaml Type: PSObject @@ -352,13 +401,14 @@ Accept wildcard characters: False ``` ### -LiteralPath -Specifies a local script that this cmdlet runs as a background job. -Enter the path of a script on the local computer. -Unlike the *FilePath* parameter, this cmdlet uses the value of the *LiteralPath* parameter exactly as it is typed. -No characters are interpreted as wildcard characters. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences. +Specifies a local script that this cmdlet runs as a background job. Enter the path of a script on +the local computer. + +`Start-Job` uses the value of the **LiteralPath** parameter exactly as it's typed. No characters are +interpreted as wildcard characters. If the path includes escape characters, enclose it in single +quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape +sequences. ```yaml Type: String @@ -373,14 +423,16 @@ 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 the Stop-Job cmdlet. -The default friendly name is Job#, where # is an ordinal number that is incremented for each job. +Specifies a friendly name for the new job. You can use the name to identify the job to other job +cmdlets, such as the `Stop-Job` cmdlet. + +The default friendly name is `Job#`, where `#` is an ordinal number that is incremented for each +job. ```yaml Type: String -Parameter Sets: ComputerName, FilePathComputerName, LiteralFilePathComputerName +Parameter Sets: ComputerName, LiteralFilePathComputerName, FilePathComputerName Aliases: Required: False @@ -391,11 +443,11 @@ Accept wildcard characters: False ``` ### -PSVersion -Specifies a version. -This cmdlet runs the job with the version of Windows PowerShell. -The acceptable values for this parameter are: 2.0 and 3.0. -This parameter was introduced in Windows PowerShell 3.0. +Specifies a version. `Start-Job` runs the job with the version of PowerShell. The acceptable values +for this parameter are: `2.0` and `3.0`. + +This parameter was introduced in PowerShell 3.0. ```yaml Type: Version @@ -410,10 +462,13 @@ Accept wildcard characters: False ``` ### -RunAs32 -Indicates that this cmdlet 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. -On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the **Start-Job** command includes the *RunAs32* parameter, you cannot use the *Credential* parameter to specify the credentials of another user. +Indicates that `Start-Job` runs the job in a 32-bit process. **RunAs32** forces the job to run in a +32-bit process, even on a 64-bit operating system. + +On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the `Start-Job` command includes +the **RunAs32** parameter, you can't use the **Credential** parameter to specify the credentials of +another user. ```yaml Type: SwitchParameter @@ -422,16 +477,16 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -ScriptBlock -Specifies the commands to run in the background job. -Enclose the commands in braces ( { } ) to create a script block. -Use the $Input automatic variable to access the value of the *InputObject* parameter. -This parameter is required. + +Specifies the commands to run in the background job. To create a script block, enclose the commands +in curly braces (`{}`). Use the `$input` automatic variable to access the value of the +**InputObject** parameter. This parameter is required. ```yaml Type: ScriptBlock @@ -446,11 +501,12 @@ Accept wildcard characters: False ``` ### -Type -Specifies the custom type for jobs that this cmdlet starts. -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. -This parameter was introduced in Windows PowerShell 3.0. +Specifies the custom type for jobs started by `Start-Job`. Enter a custom job type name, such as +PSScheduledJob for scheduled jobs or PSWorkflowJob for workflows jobs. This parameter isn't valid +for standard background jobs. + +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -465,26 +521,38 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.String -You can pipe an object that has the **Name** property to the *Name* parameter. -For example, you can pipe a **FileInfo** object from Get-ChildItem to **Start-Job**. + +You can use the pipeline to send an object with the **Name** property to the **Name** parameter. For +example, you can pipeline a **FileInfo** object from `Get-ChildItem` to `Start-Job`. ## OUTPUTS ### System.Management.Automation.PSRemotingJob -This cmdlet returns an object that represents the job that it started. + +`Start-Job` returns a **PSRemotingJob** object that represents the job that it started. ## NOTES -* To run in the background, **Start-Job** runs in its own session in 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 in the remote session. -* +To run in the background, `Start-Job` runs in its own session in 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 in the remote session. ## RELATED LINKS +[about_Jobs](./About/about_Jobs.md) + +[about_Job_Details](./About/about_Job_Details.md) + +[about_Remote_Jobs](./About/about_Remote_Jobs.md) + [Get-Job](Get-Job.md) [Invoke-Command](Invoke-Command.md) diff --git a/reference/6/Microsoft.PowerShell.Core/Start-Job.md b/reference/6/Microsoft.PowerShell.Core/Start-Job.md index 7fdde29aba0b..52d39bdbea52 100644 --- a/reference/6/Microsoft.PowerShell.Core/Start-Job.md +++ b/reference/6/Microsoft.PowerShell.Core/Start-Job.md @@ -3,11 +3,12 @@ external help file: System.Management.Automation.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Core -ms.date: 06/09/2017 +ms.date: 08/09/2019 online version: https://go.microsoft.com/fwlink/?linkid=2096181 schema: 2.0.0 title: Start-Job --- + # Start-Job ## SYNOPSIS @@ -26,7 +27,8 @@ Start-Job [-Name ] [-ScriptBlock] [-Credential [[-DefinitionPath] ] [[-Type] ] [] +Start-Job [-DefinitionName] [[-DefinitionPath] ] [[-Type] ] + [] ``` ### FilePathComputerName @@ -47,182 +49,183 @@ Start-Job [-Name ] [-Credential ] -LiteralPath ## DESCRIPTION -The **Start-Job** cmdlet starts a PowerShell background job on the local computer. +The `Start-Job` cmdlet starts a PowerShell background job on the local computer. -A PowerShell background job runs a command without interacting with the current session. -When you start a background job, a job object returns immediately, even if the job takes an extended time to finish. -You can continue to work in the session without interruption while the job runs. +A PowerShell background job runs a command without interacting with the current session. When you +start a background job, a job object returns immediately, even if the job takes an extended time to +finish. You can continue to work in the session without interruption while the job runs. -The job object contains useful information about the job, but it does not contain the job results. -When the job finishes, use the Receive-Job cmdlet to get the results of the job. -For more information about background jobs, see about_Jobs. +The job object contains useful information about the job, but it doesn't contain the job results. +When the job finishes, use the `Receive-Job` cmdlet to get the results of the job. For more +information about background jobs, see [about_Jobs](./About/about_Jobs.md). -To run a background job on a remote computer, use the *AsJob* parameter that is available on many cmdlets, -or use the Invoke-Command cmdlet to run a **Start-Job** command on the remote computer. -For more information, see about_Remote_Jobs. +To run a background job on a remote computer, use the **AsJob** parameter that is available on many +cmdlets, or use the `Invoke-Command` cmdlet to run a `Start-Job` command on the remote computer. For +more information, see [about_Remote_Jobs](./About/about_Remote_Jobs.md). -Starting in Windows PowerShell 3.0, **Start-Job** can start instances of custom job types, such as scheduled jobs. -For information about how to use **Start-Job** to start jobs with custom types, see the help topics for the job type feature. +Starting in PowerShell 3.0, `Start-Job` can start instances of custom job types, such as scheduled +jobs. For information about how to use `Start-Job` to start jobs with custom types, see the help +documents for the job type feature. > [!NOTE] -> Creating an out-of-process background job with **Start-Job** is not supported -> in the scenario where PowerShell is being hosted in other applications, -> such as the PowerShell Azure Functions. +> Creating an out-of-process background job with `Start-Job` is not supported in the scenario where +> PowerShell is being hosted in other applications, such as the PowerShell Azure Functions. > -> This is by design because **Start-Job** depends on the `pwsh` executable to be available under `$PSHOME` -> to start an out-of-process background job, -> but when an application is hosting PowerShell, -> it's directly using the PowerShell NuGet SDK packages and won't have `pwsh` shipped along. +> This is by design because `Start-Job` depends on the `pwsh` executable to be available under +> `$PSHOME` to start an out-of-process background job, but when an application is hosting +> PowerShell, it's directly using the PowerShell NuGet SDK packages and won't have `pwsh` shipped +> along. > -> The substitute in that scenario is **Start-ThreadJob** from the module **ThreadJob**. +> The substitute in that scenario is `Start-ThreadJob` from the module **ThreadJob**. ## EXAMPLES ### Example 1: Start a background job +This example starts a job that runs in the background on the local computer. + ```powershell Start-Job -ScriptBlock {Get-Process} ``` ```Output -Id Name State HasMoreData Location Command ---- ---- ----- ----------- -------- ------- -1 Job1 Running True localhost get-process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Running True localhost Get-Process ``` -This command starts a background job that runs a Get-Process command. -The command returns a job object that has information about the job. -The command prompt returns immediately so that you can work in the session while the job runs in the background. +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Process` as a background job. The job +information is displayed and PowerShell returns to a prompt while the job runs in the background. + +### Example 2: Start a job using Invoke-Command -### Example 2: Start a job by using Invoke-Command +This example runs a job on multiple computers. The job is stored in a variable and is executed by +using the variable name on the PowerShell command line. ```powershell -$jobWRM = Invoke-Command -ComputerName (Get-Content servers.txt) -ScriptBlock {Get-Service winrm} -JobName "WinRM" -ThrottleLimit 16 -AsJob +$jobWRM = Invoke-Command -ComputerName (Get-Content -Path C:\Servers.txt) -ScriptBlock { + Get-Service -Name 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 command on many computers. -Because the command is running on a server that has significant network traffic, the command uses the *ThrottleLimit* parameter of **Invoke-Command** to limit the number of concurrent commands to 16. +A job that uses `Invoke-Command` is created and stored in the `$jobWRM` variable. `Invoke-Command` +uses the **ComputerName** parameter to specify the computers where the job runs. `Get-Content` gets +the server names from the `C:\Servers.txt` file. -The command uses the *ComputerName* parameter to specify the computers on which the job runs. -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 **ScriptBlock** parameter specifies a command that `Get-Service` gets the **WinRM** service. The +**JobName** parameter specifies a friendly name for the job, **WinRM**. The **ThrottleLimit** +parameter limits the number of concurrent commands to 16. The **AsJob** parameter starts a +background job that runs the command on the servers. -The command uses the *ScriptBlock* parameter to specify the command and the *JobName* parameter to specify a friendly name for the job. +### Example 3: Get job information -### Example 3: Get events from the System log on the local computer +This example gets information about a job and displays the results of a completed job that was run +on the local computer. ```powershell -$j = Start-Job -ScriptBlock {Get-EventLog -Log system} -Credential domain01\user01 -$j | Format-List -Property * +$j = Start-Job -ScriptBlock { Get-WinEvent -Log System } -Credential Domain01\User01 +$j | Select-Object -Property * ``` ```Output +State : Completed HasMoreData : True StatusMessage : Location : localhost -Command : get-eventlog -log system -JobStateInfo : Running +Command : Get-WinEvent -Log System +JobStateInfo : Completed Finished : System.Threading.ManualResetEvent -InstanceId : 2d9d775f-63e0-4d48-b4bc-c05d0e177f34 -Id : 1 -Name : Job1 -ChildJobs : {Job2} +InstanceId : 27ce3fd9-40ed-488a-99e5-679cd91b9dd3 +Id : 18 +Name : Job18 +ChildJobs : {Job19} +PSBeginTime : 8/8/2019 14:41:57 +PSEndTime : 8/8/2019 14:42:07 +PSJobTypeName : BackgroundJob Output : {} Error : {} Progress : {} Verbose : {} Debug : {} Warning : {} -StateChanged : -``` - -```powershell -$j.JobStateInfo.state +Information : {} ``` -```Output -Completed -``` - -```powershell -$results = Receive-Job -Job $j -$results -``` - -```Output -Index Time Type Source EventID Message ------ ---- ---- ------ ------- ------- -84366 Feb 18 19:20 Information Service Control M... 7036 The description... -84365 Feb 18 19:16 Information Service Control M... 7036 The description... -84364 Feb 18 19:10 Information Service Control M... 7036 The description... -... -``` - -These commands manage a background job that gets all of the events from the System log in Event Viewer. -The job runs on the local computer. - -The first command uses the **Start-Job** cmdlet to start the job. -It uses the *Credential* parameter to specify the user account of a user who has permission to run the job on the computer. -Then it stores the job object that **Start-Job** returns in the $j variable. - -At this point, you can resume your other work while the job finishes. - -The second command uses a pipeline operator (|) to pass 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 third command displays the value of the **JobStateInfo** property. -This contains the status of the job. +`Start-Job` uses the **ScriptBlock** parameter to run a command that specifies `Get-WinEvent` to get +the **System** log. The **Credential** parameter specifies a domain user account with permission to +run the job on the computer. The job object is stored in the `$j` variable. -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. +The object in the `$j` variable is sent down the pipeline to `Select-Object`. The **Property** +parameter specifies an asterisk (`*`) to display all the job object's properties. ### Example 4: Run a script as a background job +In this example, a script on the local computer is run as a background job. + ```powershell -Start-Job -FilePath "c:\scripts\sample.ps1" +Start-Job -FilePath C:\Scripts\Sample.ps1 ``` -This command runs the Sample.ps1 script as a background job. +`Start-Job` uses the **FilePath** parameter to specify a script file that's stored on the local +computer. + +### Example 5: Get a process using a background job -### Example 5: Get a process by name by using a background job +This example uses a background job to get a specified process by name. ```powershell -Start-Job -Name "WinRm" -ScriptBlock {Get-Process winrm} +Start-Job -Name PShellJob -ScriptBlock { Get-Process -Name PowerShell } ``` -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. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **PShellJob**. The +**ScriptBlock** parameter specifies `Get-Process` to get processes with the name **PowerShell**. ### Example 6: Collect and save data by using a background job +This example starts a job that collects a large amount of map data and then saves it in a `.tif` +file. + ```powershell -Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock {Get-Map -Name * | Set-Content D:\Maps.tif} -RunAs32 +Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock { + Get-Map -Name * | Set-Content -Path D:\Maps.tif } -RunAs32 ``` -This command starts a job that collects lots of data, and then 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. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **GetMappingFiles**. The +**InitializationScript** parameter runs a script block that imports the **MapFunctions** module. The +**ScriptBlock** parameter runs `Get-Map` and `Set-Content` saves the data in the location specified +by the **Path** parameter. The **RunAs32** parameter runs the process as 32-bit, even on a 64-bit +operating system. ### Example 7: Pass input to a background job +This example uses the `$input` automatic variable to process an input object. Use `Receive-Job` to +view the job's output. + ```powershell -Start-Job -ScriptBlock {Write-Output $Input} -InputObject 'Hello, world!' +Start-Job -ScriptBlock { Get-Content $input } -InputObject "C:\Servers.txt" +Receive-Job -Name Job45 -Keep ``` -This command starts a job that simply accesses and outputs its input. -The command uses the *InputObject* parameter to pass input to the job. -Input to a job is accessed via the $Input automatic variable. -The $_ automatic variable (alias $PSItem) is not populated. +```Output +Server01 +Server02 +Server03 +Server04 +``` + +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Content` with the `$input` automatic +variable. The `$input` variable gets objects from the **InputObject** parameter. `Receive-Job` uses +the **Name** parameter to specify the job and outputs the results. The **Keep** parameter saves the +job output so it can be viewed again during the PowerShell session. ## PARAMETERS ### -ArgumentList -Specifies an array of arguments, or parameter values, for the script that is specified by the *FilePath* parameter. +Specifies an array of arguments, or 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*, specify this parameter as the last parameter in the command. +Because all the values that follow the **ArgumentList** parameter name are interpreted as being +values of **ArgumentList**, specify this parameter as the last parameter in the command. ```yaml Type: Object[] @@ -239,7 +242,8 @@ Accept wildcard characters: False ### -Authentication Specifies the mechanism that is used to authenticate user credentials. -The acceptable values for this parameter are: + +The acceptable values for this parameter are as follows: - Default - Basic @@ -251,13 +255,18 @@ The acceptable values for this parameter are: The default value is Default. -CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of the Windows operating system. +CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions +of the Windows operating system. -For more information about the values of this parameter, see [AuthenticationMechanism Enumeration](https://msdn.microsoft.com/library/system.management.automation.runspaces.authenticationmechanism) in the MSDN library. +For more information about the values of this parameter, see +[AuthenticationMechanism](/dotnet/api/system.management.automation.runspaces.authenticationmechanism). -Caution: Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. -This mechanism increases the security risk of the remote operation. -If the remote computer is compromised, the credentials that are passed to it can be used to control the network session. +> [!CAUTION] +> Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are +> passed to a remote computer to be authenticated, is designed for commands that require +> authentication on more than one resource, such as accessing a remote network share. This mechanism +> increases the security risk of the remote operation. If the remote computer is compromised, the +> credentials that are passed to it can be used to control the network session. ```yaml Type: AuthenticationMechanism @@ -267,17 +276,18 @@ Accepted values: Default, Basic, Negotiate, NegotiateWithImplicitCredential, Cre Required: False Position: Named -Default value: None +Default value: Default Accept pipeline input: False Accept wildcard characters: False ``` ### -Credential -Specifies a user account that has permission to perform this action. -The default is the current user. +Specifies a user account that has permission to perform this action. If the **Credential** parameter +isn't specified, the command uses the current user's credentials. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one from the Get-Credential cmdlet. +Type a user name, such as **User01** or **Domain01\User01**, or enter a **PSCredential** object, +such as one from the `Get-Credential` cmdlet. ```yaml Type: PSCredential @@ -286,22 +296,22 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: False Accept wildcard characters: False ``` ### -DefinitionName -Specifies the definition name of the job that this cmdlet starts. -Use this parameter to start custom job types that have a definition name, such as scheduled jobs. +Specifies the definition name of the job that this cmdlet starts. Use this parameter to start custom +job types that have a definition name, such as scheduled jobs. -When you use **Start-Job** to start an instance of a scheduled job, the job starts immediately, regardless of job triggers or job options. -The resulting job instance is a scheduled job, but it is not saved to disk like triggered scheduled jobs. -Also, you cannot use the *ArgumentList* parameter of **Start-Job** to provide values for parameters of scripts that run in a scheduled job. -For more information, see about_Scheduled_Jobs. +When you use `Start-Job` to start an instance of a scheduled job, the job starts immediately, +regardless of job triggers or job options. The resulting job instance is a scheduled job, but it +isn't saved to disk like triggered scheduled jobs. You can't use the **ArgumentList** parameter of +`Start-Job` to provide values for parameters of scripts that run in a scheduled job. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -317,14 +327,15 @@ Accept wildcard characters: False ### -DefinitionPath -Specifies path of the definition for the job that this cmdlet starts. -Enter the definition path. -The concatenation of the values of the *DefinitionPath* and *DefinitionName* parameters is the fully qualified path of the job definition. -Use this parameter to start custom job types that have a definition path, such as scheduled jobs. +Specifies path of the definition for the job that this cmdlet starts. Enter the definition path. The +concatenation of the values of the **DefinitionPath** and **DefinitionName** parameters is the fully +qualified path of the job definition. Use this parameter to start custom job types that have a +definition path, such as scheduled jobs. -For scheduled jobs, the value of the *DefinitionPath* parameter is `$home\AppData\Local\Windows\PowerShell\ScheduledJob`. +For scheduled jobs, the value of the **DefinitionPath** parameter is +`$home\AppData\Local\Windows\PowerShell\ScheduledJob`. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -340,11 +351,12 @@ Accept wildcard characters: False ### -FilePath -Specifies a local script that this cmdlet runs as a background job. -Enter the path and file name of the script or pipe a script path to **Start-Job**. -The script must be on the local computer or in a folder that the local computer can access. +Specifies a local script that `Start-Job` runs as a background job. Enter the path and file name of +the script or use the pipeline to send a script path to `Start-Job`. The script must be on the local +computer or in a folder that the local computer can access. -When you use this parameter, PowerShell converts the contents of the specified script file to a script block and runs the script block as a background job. +When you use this parameter, PowerShell converts the contents of the specified script file to a +script block and runs the script block as a background job. ```yaml Type: String @@ -360,11 +372,11 @@ Accept wildcard characters: False ### -InitializationScript -Specifies commands that run before the job starts. -Enclose the commands in braces ( { } ) to create a script block. +Specifies commands that run before the job starts. To create a script block, enclose the commands in +curly braces (`{}`). -Use this parameter to prepare the session in which the job runs. -For example, you can use it to add functions, snap-ins, and modules to the session. +Use this parameter to prepare the session in which the job runs. For example, you can use it to add +functions, snap-ins, and modules to the session. ```yaml Type: ScriptBlock @@ -380,10 +392,11 @@ 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. +Specifies input to the command. Enter a variable that contains the objects, or type a command or +expression that generates the objects. -In the value of the *ScriptBlock* parameter, use the $Input automatic variable to represent the input objects. +In the value of the **ScriptBlock** parameter, use the `$input` automatic variable to represent the +input objects. ```yaml Type: PSObject @@ -399,13 +412,13 @@ Accept wildcard characters: False ### -LiteralPath -Specifies a local script that this cmdlet runs as a background job. -Enter the path of a script on the local computer. +Specifies a local script that this cmdlet runs as a background job. Enter the path of a script on +the local computer. -Unlike the *FilePath* parameter, this cmdlet uses the value of the *LiteralPath* parameter exactly as it is typed. -No characters are interpreted as wildcard characters. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell PowerShell not to interpret any characters as escape sequences. +`Start-Job` uses the value of the **LiteralPath** parameter exactly as it's typed. No characters are +interpreted as wildcard characters. If the path includes escape characters, enclose it in single +quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape +sequences. ```yaml Type: String @@ -421,10 +434,11 @@ 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 the Stop-Job cmdlet. +Specifies a friendly name for the new job. You can use the name to identify the job to other job +cmdlets, such as the `Stop-Job` cmdlet. -The default friendly name is Job#, where # is an ordinal number that is incremented for each job. +The default friendly name is `Job#`, where `#` is an ordinal number that is incremented for each +job. ```yaml Type: String @@ -440,11 +454,10 @@ Accept wildcard characters: False ### -PSVersion -Specifies a version. -This cmdlet runs the job with the version of PowerShell. -The acceptable values for this parameter are: 2.0 and 3.0. +Specifies a version. `Start-Job` runs the job with the version of PowerShell. The acceptable values +for this parameter are: `2.0` and `3.0`. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: Version @@ -460,10 +473,12 @@ Accept wildcard characters: False ### -RunAs32 -Indicates that this cmdlet 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. +Indicates that `Start-Job` runs the job in a 32-bit process. **RunAs32** forces the job to run in a +32-bit process, even on a 64-bit operating system. -On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the **Start-Job** command includes the *RunAs32* parameter, you cannot use the *Credential* parameter to specify the credentials of another user. +On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the `Start-Job` command includes +the **RunAs32** parameter, you can't use the **Credential** parameter to specify the credentials of +another user. ```yaml Type: SwitchParameter @@ -472,17 +487,16 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -ScriptBlock -Specifies the commands to run in the background job. -Enclose the commands in braces ( { } ) to create a script block. -Use the $Input automatic variable to access the value of the *InputObject* parameter. -This parameter is required. +Specifies the commands to run in the background job. To create a script block, enclose the commands +in curly braces (`{}`). Use the `$input` automatic variable to access the value of the +**InputObject** parameter. This parameter is required. ```yaml Type: ScriptBlock @@ -498,11 +512,11 @@ Accept wildcard characters: False ### -Type -Specifies the custom type for jobs that this cmdlet starts. -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. +Specifies the custom type for jobs started by `Start-Job`. Enter a custom job type name, such as +PSScheduledJob for scheduled jobs or PSWorkflowJob for workflows jobs. This parameter isn't valid +for standard background jobs. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -518,29 +532,37 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.String -You can pipe an object that has the **Name** property to the *Name* parameter. -For example, you can pipe a **FileInfo** object from Get-ChildItem to **Start-Job**. +You can use the pipeline to send an object with the **Name** property to the **Name** parameter. For +example, you can pipeline a **FileInfo** object from `Get-ChildItem` to `Start-Job`. ## OUTPUTS ### System.Management.Automation.PSRemotingJob -This cmdlet returns an object that represents the job that it started. +`Start-Job` returns a **PSRemotingJob** object that represents the job that it started. ## NOTES -* To run in the background, **Start-Job** runs in its own session in 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 in the remote session. - -* +To run in the background, `Start-Job` runs in its own session in 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 in the remote session. ## RELATED LINKS +[about_Jobs](./About/about_Jobs.md) + +[about_Job_Details](./About/about_Job_Details.md) + +[about_Remote_Jobs](./About/about_Remote_Jobs.md) + [Get-Job](Get-Job.md) [Invoke-Command](Invoke-Command.md) @@ -549,6 +571,10 @@ This cmdlet returns an object that represents the job that it started. [Remove-Job](Remove-Job.md) +[Resume-Job](Resume-Job.md) + [Stop-Job](Stop-Job.md) +[Suspend-Job](Suspend-Job.md) + [Wait-Job](Wait-Job.md) diff --git a/reference/7/Microsoft.PowerShell.Core/Start-Job.md b/reference/7/Microsoft.PowerShell.Core/Start-Job.md index 57cdca83a5f7..155f67f2e65a 100644 --- a/reference/7/Microsoft.PowerShell.Core/Start-Job.md +++ b/reference/7/Microsoft.PowerShell.Core/Start-Job.md @@ -3,11 +3,12 @@ external help file: System.Management.Automation.dll-Help.xml keywords: powershell,cmdlet locale: en-us Module Name: Microsoft.PowerShell.Core -ms.date: 06/09/2017 +ms.date: 08/09/2019 online version: https://go.microsoft.com/fwlink/?linkid=2096796 schema: 2.0.0 title: Start-Job --- + # Start-Job ## SYNOPSIS @@ -26,7 +27,8 @@ Start-Job [-Name ] [-ScriptBlock] [-Credential [[-DefinitionPath] ] [[-Type] ] [] +Start-Job [-DefinitionName] [[-DefinitionPath] ] [[-Type] ] + [] ``` ### FilePathComputerName @@ -47,182 +49,182 @@ Start-Job [-Name ] [-Credential ] -LiteralPath ## DESCRIPTION -The **Start-Job** cmdlet starts a PowerShell background job on the local computer. +The `Start-Job` cmdlet starts a PowerShell background job on the local computer. -A PowerShell background job runs a command without interacting with the current session. -When you start a background job, a job object returns immediately, even if the job takes an extended time to finish. -You can continue to work in the session without interruption while the job runs. +A PowerShell background job runs a command without interacting with the current session. When you +start a background job, a job object returns immediately, even if the job takes an extended time to +finish. You can continue to work in the session without interruption while the job runs. -The job object contains useful information about the job, but it does not contain the job results. -When the job finishes, use the Receive-Job cmdlet to get the results of the job. -For more information about background jobs, see about_Jobs. +The job object contains useful information about the job, but it doesn't contain the job results. +When the job finishes, use the `Receive-Job` cmdlet to get the results of the job. For more +information about background jobs, see [about_Jobs](./About/about_Jobs.md). -To run a background job on a remote computer, use the *AsJob* parameter that is available on many cmdlets, -or use the Invoke-Command cmdlet to run a **Start-Job** command on the remote computer. -For more information, see about_Remote_Jobs. +To run a background job on a remote computer, use the **AsJob** parameter that is available on many +cmdlets, or use the `Invoke-Command` cmdlet to run a `Start-Job` command on the remote computer. For +more information, see [about_Remote_Jobs](./About/about_Remote_Jobs.md). -Starting in Windows PowerShell 3.0, **Start-Job** can start instances of custom job types, such as scheduled jobs. -For information about how to use **Start-Job** to start jobs with custom types, see the help topics for the job type feature. +Starting in PowerShell 3.0, `Start-Job` can start instances of custom job types, such as scheduled +jobs. For information about how to use `Start-Job` to start jobs with custom types, see the help +documents for the job type feature. > [!NOTE] -> Creating an out-of-process background job with **Start-Job** is not supported -> in the scenario where PowerShell is being hosted in other applications, -> such as the PowerShell Azure Functions. +> Creating an out-of-process background job with `Start-Job` is not supported in the scenario where +> PowerShell is being hosted in other applications, such as the PowerShell Azure Functions. > -> This is by design because **Start-Job** depends on the `pwsh` executable to be available under `$PSHOME` -> to start an out-of-process background job, -> but when an application is hosting PowerShell, -> it's directly using the PowerShell NuGet SDK packages and won't have `pwsh` shipped along. +> This is by design because `Start-Job` depends on the `pwsh` executable to be available under +> `$PSHOME` to start an out-of-process background job, but when an application is hosting +> PowerShell, it's directly using the PowerShell NuGet SDK packages and won't have `pwsh` shipped +> along. > -> The substitute in that scenario is **Start-ThreadJob** from the module **ThreadJob**. +> The substitute in that scenario is `Start-ThreadJob` from the module **ThreadJob**. ## EXAMPLES ### Example 1: Start a background job +This example starts a job that runs in the background on the local computer. + ```powershell Start-Job -ScriptBlock {Get-Process} ``` ```Output -Id Name State HasMoreData Location Command ---- ---- ----- ----------- -------- ------- -1 Job1 Running True localhost get-process +Id Name PSJobTypeName State HasMoreData Location Command +-- ---- ------------- ----- ----------- -------- ------- +1 Job1 BackgroundJob Running True localhost Get-Process ``` -This command starts a background job that runs a Get-Process command. -The command returns a job object that has information about the job. -The command prompt returns immediately so that you can work in the session while the job runs in the background. +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Process` as a background job. The job +information is displayed and PowerShell returns to a prompt while the job runs in the background. + +### Example 2: Start a job using Invoke-Command -### Example 2: Start a job by using Invoke-Command +This example runs a job on multiple computers. The job is stored in a variable and is executed by +using the variable name on the PowerShell command line. ```powershell -$jobWRM = Invoke-Command -ComputerName (Get-Content servers.txt) -ScriptBlock {Get-Service winrm} -JobName "WinRM" -ThrottleLimit 16 -AsJob +$jobWRM = Invoke-Command -ComputerName (Get-Content -Path C:\Servers.txt) -ScriptBlock { + Get-Service -Name 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 command on many computers. -Because the command is running on a server that has significant network traffic, the command uses the *ThrottleLimit* parameter of **Invoke-Command** to limit the number of concurrent commands to 16. +A job that uses `Invoke-Command` is created and stored in the `$jobWRM` variable. `Invoke-Command` +uses the **ComputerName** parameter to specify the computers where the job runs. `Get-Content` gets +the server names from the `C:\Servers.txt` file. -The command uses the *ComputerName* parameter to specify the computers on which the job runs. -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 **ScriptBlock** parameter specifies a command that `Get-Service` gets the **WinRM** service. The +**JobName** parameter specifies a friendly name for the job, **WinRM**. The **ThrottleLimit** +parameter limits the number of concurrent commands to 16. The **AsJob** parameter starts a +background job that runs the command on the servers. -The command uses the *ScriptBlock* parameter to specify the command and the *JobName* parameter to specify a friendly name for the job. +### Example 3: Get job information -### Example 3: Get events from the System log on the local computer +This example gets information about a job and displays the results of a completed job that was run +on the local computer. ```powershell -$j = Start-Job -ScriptBlock {Get-EventLog -Log system} -Credential domain01\user01 -$j | Format-List -Property * +$j = Start-Job -ScriptBlock { Get-WinEvent -Log System } -Credential Domain01\User01 +$j | Select-Object -Property * ``` ```Output +State : Completed HasMoreData : True StatusMessage : Location : localhost -Command : get-eventlog -log system -JobStateInfo : Running +Command : Get-WinEvent -Log System +JobStateInfo : Completed Finished : System.Threading.ManualResetEvent -InstanceId : 2d9d775f-63e0-4d48-b4bc-c05d0e177f34 -Id : 1 -Name : Job1 -ChildJobs : {Job2} +InstanceId : 27ce3fd9-40ed-488a-99e5-679cd91b9dd3 +Id : 18 +Name : Job18 +ChildJobs : {Job19} +PSBeginTime : 8/8/2019 14:41:57 +PSEndTime : 8/8/2019 14:42:07 +PSJobTypeName : BackgroundJob Output : {} Error : {} Progress : {} Verbose : {} Debug : {} Warning : {} -StateChanged : -``` - -```powershell -$j.JobStateInfo.state +Information : {} ``` -```Output -Completed -``` - -```powershell -$results = Receive-Job -Job $j -$results -``` - -```Output -Index Time Type Source EventID Message ------ ---- ---- ------ ------- ------- -84366 Feb 18 19:20 Information Service Control M... 7036 The description... -84365 Feb 18 19:16 Information Service Control M... 7036 The description... -84364 Feb 18 19:10 Information Service Control M... 7036 The description... -... -``` - -These commands manage a background job that gets all of the events from the System log in Event Viewer. -The job runs on the local computer. - -The first command uses the **Start-Job** cmdlet to start the job. -It uses the *Credential* parameter to specify the user account of a user who has permission to run the job on the computer. -Then it stores the job object that **Start-Job** returns in the $j variable. - -At this point, you can resume your other work while the job finishes. - -The second command uses a pipeline operator (|) to pass 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 third command displays the value of the **JobStateInfo** property. -This contains the status of the job. +`Start-Job` uses the **ScriptBlock** parameter to run a command that specifies `Get-WinEvent` to get +the **System** log. The **Credential** parameter specifies a domain user account with permission to +run the job on the computer. The job object is stored in the `$j` variable. -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. +The object in the `$j` variable is sent down the pipeline to `Select-Object`. The **Property** +parameter specifies an asterisk (`*`) to display all the job object's properties. ### Example 4: Run a script as a background job +In this example, a script on the local computer is run as a background job. + ```powershell -Start-Job -FilePath "c:\scripts\sample.ps1" +Start-Job -FilePath C:\Scripts\Sample.ps1 ``` -This command runs the Sample.ps1 script as a background job. +`Start-Job` uses the **FilePath** parameter to specify a script file that's stored on the local +computer. + +### Example 5: Get a process using a background job -### Example 5: Get a process by name by using a background job +This example uses a background job to get a specified process by name. ```powershell -Start-Job -Name "WinRm" -ScriptBlock {Get-Process winrm} +Start-Job -Name PShellJob -ScriptBlock { Get-Process -Name PowerShell } ``` -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. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **PShellJob**. The +**ScriptBlock** parameter specifies `Get-Process` to get processes with the name **PowerShell**. ### Example 6: Collect and save data by using a background job +This example starts a job that collects a large amount of map data and then saves it in a `.tif` +file. + ```powershell -Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock {Get-Map -Name * | Set-Content D:\Maps.tif} -RunAs32 +Start-Job -Name GetMappingFiles -InitializationScript {Import-Module MapFunctions} -ScriptBlock { + Get-Map -Name * | Set-Content -Path D:\Maps.tif } ``` -This command starts a job that collects lots of data, and then 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. +`Start-Job` uses the **Name** parameter to specify a friendly job name, **GetMappingFiles**. The +**InitializationScript** parameter runs a script block that imports the **MapFunctions** module. The +**ScriptBlock** parameter runs `Get-Map` and `Set-Content` saves the data in the location specified +by the **Path** parameter. ### Example 7: Pass input to a background job +This example uses the `$input` automatic variable to process an input object. Use `Receive-Job` to +view the job's output. + ```powershell -Start-Job -ScriptBlock {Write-Output $Input} -InputObject 'Hello, world!' +Start-Job -ScriptBlock { Get-Content $input } -InputObject "C:\Servers.txt" +Receive-Job -Name Job45 -Keep ``` -This command starts a job that simply accesses and outputs its input. -The command uses the *InputObject* parameter to pass input to the job. -Input to a job is accessed via the $Input automatic variable. -The $_ automatic variable (alias $PSItem) is not populated. +```Output +Server01 +Server02 +Server03 +Server04 +``` + +`Start-Job` uses the **ScriptBlock** parameter to run `Get-Content` with the `$input` automatic +variable. The `$input` variable gets objects from the **InputObject** parameter. `Receive-Job` uses +the **Name** parameter to specify the job and outputs the results. The **Keep** parameter saves the +job output so it can be viewed again during the PowerShell session. ## PARAMETERS ### -ArgumentList -Specifies an array of arguments, or parameter values, for the script that is specified by the *FilePath* parameter. +Specifies an array of arguments, or 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*, specify this parameter as the last parameter in the command. +Because all the values that follow the **ArgumentList** parameter name are interpreted as being +values of **ArgumentList**, specify this parameter as the last parameter in the command. ```yaml Type: Object[] @@ -239,7 +241,8 @@ Accept wildcard characters: False ### -Authentication Specifies the mechanism that is used to authenticate user credentials. -The acceptable values for this parameter are: + +The acceptable values for this parameter are as follows: - Default - Basic @@ -251,13 +254,18 @@ The acceptable values for this parameter are: The default value is Default. -CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions of the Windows operating system. +CredSSP authentication is available only in Windows Vista, Windows Server 2008, and later versions +of the Windows operating system. -For more information about the values of this parameter, see [AuthenticationMechanism Enumeration](https://msdn.microsoft.com/library/system.management.automation.runspaces.authenticationmechanism) in the MSDN library. +For more information about the values of this parameter, see +[AuthenticationMechanism](/dotnet/api/system.management.automation.runspaces.authenticationmechanism). -Caution: Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are passed to a remote computer to be authenticated, is designed for commands that require authentication on more than one resource, such as accessing a remote network share. -This mechanism increases the security risk of the remote operation. -If the remote computer is compromised, the credentials that are passed to it can be used to control the network session. +> [!CAUTION] +> Credential Security Support Provider (CredSSP) authentication, in which the user's credentials are +> passed to a remote computer to be authenticated, is designed for commands that require +> authentication on more than one resource, such as accessing a remote network share. This mechanism +> increases the security risk of the remote operation. If the remote computer is compromised, the +> credentials that are passed to it can be used to control the network session. ```yaml Type: AuthenticationMechanism @@ -267,17 +275,18 @@ Accepted values: Default, Basic, Negotiate, NegotiateWithImplicitCredential, Cre Required: False Position: Named -Default value: None +Default value: Default Accept pipeline input: False Accept wildcard characters: False ``` ### -Credential -Specifies a user account that has permission to perform this action. -The default is the current user. +Specifies a user account that has permission to perform this action. If the **Credential** parameter +isn't specified, the command uses the current user's credentials. -Type a user name, such as User01 or Domain01\User01, or enter a **PSCredential** object, such as one from the Get-Credential cmdlet. +Type a user name, such as **User01** or **Domain01\User01**, or enter a **PSCredential** object, +such as one from the `Get-Credential` cmdlet. ```yaml Type: PSCredential @@ -286,22 +295,22 @@ Aliases: Required: False Position: Named -Default value: None +Default value: Current user Accept pipeline input: False Accept wildcard characters: False ``` ### -DefinitionName -Specifies the definition name of the job that this cmdlet starts. -Use this parameter to start custom job types that have a definition name, such as scheduled jobs. +Specifies the definition name of the job that this cmdlet starts. Use this parameter to start custom +job types that have a definition name, such as scheduled jobs. -When you use **Start-Job** to start an instance of a scheduled job, the job starts immediately, regardless of job triggers or job options. -The resulting job instance is a scheduled job, but it is not saved to disk like triggered scheduled jobs. -Also, you cannot use the *ArgumentList* parameter of **Start-Job** to provide values for parameters of scripts that run in a scheduled job. -For more information, see about_Scheduled_Jobs. +When you use `Start-Job` to start an instance of a scheduled job, the job starts immediately, +regardless of job triggers or job options. The resulting job instance is a scheduled job, but it +isn't saved to disk like triggered scheduled jobs. You can't use the **ArgumentList** parameter of +`Start-Job` to provide values for parameters of scripts that run in a scheduled job. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -317,14 +326,15 @@ Accept wildcard characters: False ### -DefinitionPath -Specifies path of the definition for the job that this cmdlet starts. -Enter the definition path. -The concatenation of the values of the *DefinitionPath* and *DefinitionName* parameters is the fully qualified path of the job definition. -Use this parameter to start custom job types that have a definition path, such as scheduled jobs. +Specifies path of the definition for the job that this cmdlet starts. Enter the definition path. The +concatenation of the values of the **DefinitionPath** and **DefinitionName** parameters is the fully +qualified path of the job definition. Use this parameter to start custom job types that have a +definition path, such as scheduled jobs. -For scheduled jobs, the value of the *DefinitionPath* parameter is `$home\AppData\Local\Windows\PowerShell\ScheduledJob`. +For scheduled jobs, the value of the **DefinitionPath** parameter is +`$home\AppData\Local\Windows\PowerShell\ScheduledJob`. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -340,11 +350,12 @@ Accept wildcard characters: False ### -FilePath -Specifies a local script that this cmdlet runs as a background job. -Enter the path and file name of the script or pipe a script path to **Start-Job**. -The script must be on the local computer or in a folder that the local computer can access. +Specifies a local script that `Start-Job` runs as a background job. Enter the path and file name of +the script or use the pipeline to send a script path to `Start-Job`. The script must be on the local +computer or in a folder that the local computer can access. -When you use this parameter, PowerShell converts the contents of the specified script file to a script block and runs the script block as a background job. +When you use this parameter, PowerShell converts the contents of the specified script file to a +script block and runs the script block as a background job. ```yaml Type: String @@ -360,11 +371,11 @@ Accept wildcard characters: False ### -InitializationScript -Specifies commands that run before the job starts. -Enclose the commands in braces ( { } ) to create a script block. +Specifies commands that run before the job starts. To create a script block, enclose the commands in +curly braces (`{}`). -Use this parameter to prepare the session in which the job runs. -For example, you can use it to add functions, snap-ins, and modules to the session. +Use this parameter to prepare the session in which the job runs. For example, you can use it to add +functions, snap-ins, and modules to the session. ```yaml Type: ScriptBlock @@ -380,10 +391,11 @@ 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. +Specifies input to the command. Enter a variable that contains the objects, or type a command or +expression that generates the objects. -In the value of the *ScriptBlock* parameter, use the $Input automatic variable to represent the input objects. +In the value of the **ScriptBlock** parameter, use the `$input` automatic variable to represent the +input objects. ```yaml Type: PSObject @@ -399,13 +411,13 @@ Accept wildcard characters: False ### -LiteralPath -Specifies a local script that this cmdlet runs as a background job. -Enter the path of a script on the local computer. +Specifies a local script that this cmdlet runs as a background job. Enter the path of a script on +the local computer. -Unlike the *FilePath* parameter, this cmdlet uses the value of the *LiteralPath* parameter exactly as it is typed. -No characters are interpreted as wildcard characters. -If the path includes escape characters, enclose it in single quotation marks. -Single quotation marks tell PowerShell not to interpret any characters as escape sequences. +`Start-Job` uses the value of the **LiteralPath** parameter exactly as it's typed. No characters are +interpreted as wildcard characters. If the path includes escape characters, enclose it in single +quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape +sequences. ```yaml Type: String @@ -421,10 +433,11 @@ 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 the Stop-Job cmdlet. +Specifies a friendly name for the new job. You can use the name to identify the job to other job +cmdlets, such as the `Stop-Job` cmdlet. -The default friendly name is Job#, where # is an ordinal number that is incremented for each job. +The default friendly name is `Job#`, where `#` is an ordinal number that is incremented for each +job. ```yaml Type: String @@ -440,11 +453,10 @@ Accept wildcard characters: False ### -PSVersion -Specifies a version. -This cmdlet runs the job with the version of PowerShell. -The acceptable values for this parameter are: 2.0 and 3.0. +Specifies a version. `Start-Job` runs the job with the version of PowerShell. The acceptable values +for this parameter are: `2.0` and `3.0`. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: Version @@ -460,10 +472,17 @@ Accept wildcard characters: False ### -RunAs32 -Indicates that this cmdlet 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. +Beginning with PowerShell 7, the **RunAs32** parameter doesn't work on 64-bit PowerShell (`pwsh`). +If **RunAs32** is specified in 64-bit PowerShell, `Start-Job` throws a terminating exception error. +To start a 32-bit PowerShell (`pwsh`) process with **RunAs32**, you need to have the 32-bit +PowerShell installed. + +In 32-bit PowerShell, **RunAs32** forces the job to run in a 32-bit process, even on a 64-bit +operating system. -On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the **Start-Job** command includes the *RunAs32* parameter, you cannot use the *Credential* parameter to specify the credentials of another user. +On 64-bit versions of Windows 7 and Windows Server 2008 R2, when the `Start-Job` command includes +the **RunAs32** parameter, you can't use the **Credential** parameter to specify the credentials of +another user. ```yaml Type: SwitchParameter @@ -472,17 +491,16 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -ScriptBlock -Specifies the commands to run in the background job. -Enclose the commands in braces ( { } ) to create a script block. -Use the $Input automatic variable to access the value of the *InputObject* parameter. -This parameter is required. +Specifies the commands to run in the background job. To create a script block, enclose the commands +in curly braces (`{}`). Use the `$input` automatic variable to access the value of the +**InputObject** parameter. This parameter is required. ```yaml Type: ScriptBlock @@ -498,11 +516,11 @@ Accept wildcard characters: False ### -Type -Specifies the custom type for jobs that this cmdlet starts. -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. +Specifies the custom type for jobs started by `Start-Job`. Enter a custom job type name, such as +PSScheduledJob for scheduled jobs or PSWorkflowJob for workflows jobs. This parameter isn't valid +for standard background jobs. -This parameter was introduced in Windows PowerShell 3.0. +This parameter was introduced in PowerShell 3.0. ```yaml Type: String @@ -518,29 +536,37 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS ### System.String -You can pipe an object that has the **Name** property to the *Name* parameter. -For example, you can pipe a **FileInfo** object from Get-ChildItem to **Start-Job**. +You can use the pipeline to send an object with the **Name** property to the **Name** parameter. For +example, you can pipeline a **FileInfo** object from `Get-ChildItem` to `Start-Job`. ## OUTPUTS ### System.Management.Automation.PSRemotingJob -This cmdlet returns an object that represents the job that it started. +`Start-Job` returns a **PSRemotingJob** object that represents the job that it started. ## NOTES -* To run in the background, **Start-Job** runs in its own session in 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 in the remote session. - -* +To run in the background, `Start-Job` runs in its own session in 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 in the remote session. ## RELATED LINKS +[about_Jobs](./About/about_Jobs.md) + +[about_Job_Details](./About/about_Job_Details.md) + +[about_Remote_Jobs](./About/about_Remote_Jobs.md) + [Get-Job](Get-Job.md) [Invoke-Command](Invoke-Command.md) @@ -549,6 +575,10 @@ This cmdlet returns an object that represents the job that it started. [Remove-Job](Remove-Job.md) +[Resume-Job](Resume-Job.md) + [Stop-Job](Stop-Job.md) +[Suspend-Job](Suspend-Job.md) + [Wait-Job](Wait-Job.md)