< Back
Start-RSJob
Post
NAME Start-RSJob
SYNOPSIS
Starts a background job using runspaces.
SYNTAX
Start-RSJob [-ScriptBlock] <ScriptBlock> [-InputObject <Object>] [-Name <Object>] [-Batch <String>] [-ArgumentList
<Array>] [-Throttle <Int32>] [-ModulesToImport <String[]>] [-PSSnapinsToImport <String[]>] [-FunctionsToImport
<String[]>] [-FunctionFilesToImport <String[]>] [-VariablesToImport <String[]>] [<CommonParameters>]
Start-RSJob [[-FilePath] <String>] [-InputObject <Object>] [-Name <Object>] [-Batch <String>] [-ArgumentList
<Array>] [-Throttle <Int32>] [-ModulesToImport <String[]>] [-PSSnapinsToImport <String[]>] [-FunctionsToImport
<String[]>] [-FunctionFilesToImport <String[]>] [-VariablesToImport <String[]>] [<CommonParameters>]
DESCRIPTION
This will run a command in the background, leaving your console available to perform other tasks. This uses
runspaces in runspacepools which allows for throttling of running jobs. As the jobs are finished, they will
automatically
dispose of each runspace and allow other runspace jobs in queue to begin based on the throttling of the
runspacepool.
This is available on PowerShell V3 and above. By doing this, you can use the $Using: variable to take variables
in the local scope and apply those directly into the scriptblock of the background runspace job.
PARAMETERS
-ScriptBlock <ScriptBlock>
The scriptblock that holds all of the commands which will be run in the background runspace. You must specify
at least one Parameter in the Param() to account for the item that is being piped into Start-Job.
Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FilePath <String>
This is the path to a file containing code that will be run in the background runspace job.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-InputObject <Object>
The object being piped into Start-RSJob or applied via the parameter.
Required? false
Position? named
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false
-Name <Object>
The name of a background runspace job
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Batch <String>
Name of the batch of RSJobs that will be run
Required? false
Position? named
Default value $([guid]::NewGuid().ToString())
Accept pipeline input? false
Accept wildcard characters? false
-ArgumentList <Array>
List of values that will be applied at the end of the argument list in the Param() statement.
Required? false
Position? named
Default value @()
Accept pipeline input? false
Accept wildcard characters? false
-Throttle <Int32>
Number of concurrent running runspace jobs which are allowed at a time.
Required? false
Position? named
Default value 5
Accept pipeline input? false
Accept wildcard characters? false
-ModulesToImport <String[]>
A collection of modules that will be imported into the background runspace job.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-PSSnapinsToImport <String[]>
A collection of PSSnapins that will be imported into the background runspace job.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FunctionsToImport <String[]>
A collection of functions that will be imported for use with a background runspace job.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FunctionFilesToImport <String[]>
A collection of files containing custom functions that will be imported into the background runspace job.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-VariablesToImport <String[]>
A collection of variables that will be imported for use with a background runspace job.
If used, $using:variable not expanded !
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
RSJob
NOTES
Name: Start-RSJob
Author: Boe Prox/Max Kozlov
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Get-ChildItem -Directory | Start-RSjob -Name {$_.Name} -ScriptBlock {
Param($Directory)
Write-Verbose $_
$Sum = (Get-ChildItem $Directory.FullName -Recurse -Force -ErrorAction SilentlyContinue |
Measure-Object -Property Length -Sum).Sum
[pscustomobject]@{
Name = $Directory.Name
SizeMB = ([math]::round(($Sum/1MB),2))
}
}
Id Name State HasMoreData HasErrors Command
-- ---- ----- ----------- --------- -------
13 Contacts Running False False ...
14 Desktop Running False False ...
15 Documents Running False False ...
16 Downloads Running False False ...
17 Favorites Running False False ...
18 Links Running False False ...
19 Music Running False False ...
20 OneDrive Running False False ...
21 Pictures Running False False ...
22 Saved Games Running False False ...
23 Searches Running False False ...
24 Videos Running False False ...
Get-RSJob | Receive-RSJob
Name SizeMB
---- ------
Contacts 0
Desktop 7.24
Documents 83.99
Downloads 10259.6
Favorites 0
Links 0
Music 16691.89
OneDrive 1485.24
Pictures 1734.91
Saved Games 0
Searches 0
Videos 17.19
Description
-----------
Starts a background runspace job that looks at the total size of each folder. Using Get-RSJob | Recieve-RSJob shows
the results when the State is Completed.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>$Test = 'test'
$Something = 1..10
1..5|start-rsjob -Name {$_} -ScriptBlock {
Param($Object) [pscustomobject]@{
Result=($Object*2)
Test=$Using:Test
Something=$Using:Something
}
}
Id Name State HasMoreData HasErrors Command
-- ---- ----- ----------- --------- -------
76 1 Completed True False ...
77 2 Running False False ...
78 3 Running False False ...
79 4 Completed False False ...
80 5 Completed False False ...
Get-RSjob | Receive-RSJob
Result Test Something
------ ---- ---------
2 test {1, 2, 3, 4...}
4 test {1, 2, 3, 4...}
6 test {1, 2, 3, 4...}
8 test {1, 2, 3, 4...}
10 test {1, 2, 3, 4...}
Description
-----------
Shows an example of the $Using: variable being used in the scriptblock.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>$Test = 42
$AnotherTest = 7
$String = 'SomeString'
$ProcName = 'powershell_ise'
$ScriptBlock = {
Param($y,$z)
[pscustomobject] @{
Test = $y
Proc = (Get-Process -Name $Using:ProcName)
String = $Using:String
AnotherTest = ($z+$_)
PipedObject = $_
}
}
1..5|Start-RSJob $ScriptBlock -ArgumentList $test, $anothertest
Description
-----------
Shows an example of the $Using: variable being used in the scriptblock as well as $_ and multiple -ArgumentList
parameters.
RELATED LINKS
SYNOPSIS
Starts a background job using runspaces.
SYNTAX
Start-RSJob [-ScriptBlock] <ScriptBlock> [-InputObject <Object>] [-Name <Object>] [-Batch <String>] [-ArgumentList
<Array>] [-Throttle <Int32>] [-ModulesToImport <String[]>] [-PSSnapinsToImport <String[]>] [-FunctionsToImport
<String[]>] [-FunctionFilesToImport <String[]>] [-VariablesToImport <String[]>] [<CommonParameters>]
Start-RSJob [[-FilePath] <String>] [-InputObject <Object>] [-Name <Object>] [-Batch <String>] [-ArgumentList
<Array>] [-Throttle <Int32>] [-ModulesToImport <String[]>] [-PSSnapinsToImport <String[]>] [-FunctionsToImport
<String[]>] [-FunctionFilesToImport <String[]>] [-VariablesToImport <String[]>] [<CommonParameters>]
DESCRIPTION
This will run a command in the background, leaving your console available to perform other tasks. This uses
runspaces in runspacepools which allows for throttling of running jobs. As the jobs are finished, they will
automatically
dispose of each runspace and allow other runspace jobs in queue to begin based on the throttling of the
runspacepool.
This is available on PowerShell V3 and above. By doing this, you can use the $Using: variable to take variables
in the local scope and apply those directly into the scriptblock of the background runspace job.
PARAMETERS
-ScriptBlock <ScriptBlock>
The scriptblock that holds all of the commands which will be run in the background runspace. You must specify
at least one Parameter in the Param() to account for the item that is being piped into Start-Job.
Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FilePath <String>
This is the path to a file containing code that will be run in the background runspace job.
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-InputObject <Object>
The object being piped into Start-RSJob or applied via the parameter.
Required? false
Position? named
Default value
Accept pipeline input? true (ByValue, ByPropertyName)
Accept wildcard characters? false
-Name <Object>
The name of a background runspace job
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Batch <String>
Name of the batch of RSJobs that will be run
Required? false
Position? named
Default value $([guid]::NewGuid().ToString())
Accept pipeline input? false
Accept wildcard characters? false
-ArgumentList <Array>
List of values that will be applied at the end of the argument list in the Param() statement.
Required? false
Position? named
Default value @()
Accept pipeline input? false
Accept wildcard characters? false
-Throttle <Int32>
Number of concurrent running runspace jobs which are allowed at a time.
Required? false
Position? named
Default value 5
Accept pipeline input? false
Accept wildcard characters? false
-ModulesToImport <String[]>
A collection of modules that will be imported into the background runspace job.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-PSSnapinsToImport <String[]>
A collection of PSSnapins that will be imported into the background runspace job.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FunctionsToImport <String[]>
A collection of functions that will be imported for use with a background runspace job.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-FunctionFilesToImport <String[]>
A collection of files containing custom functions that will be imported into the background runspace job.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-VariablesToImport <String[]>
A collection of variables that will be imported for use with a background runspace job.
If used, $using:variable not expanded !
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
RSJob
NOTES
Name: Start-RSJob
Author: Boe Prox/Max Kozlov
-------------------------- EXAMPLE 1 --------------------------
PS C:\\>Get-ChildItem -Directory | Start-RSjob -Name {$_.Name} -ScriptBlock {
Param($Directory)
Write-Verbose $_
$Sum = (Get-ChildItem $Directory.FullName -Recurse -Force -ErrorAction SilentlyContinue |
Measure-Object -Property Length -Sum).Sum
[pscustomobject]@{
Name = $Directory.Name
SizeMB = ([math]::round(($Sum/1MB),2))
}
}
Id Name State HasMoreData HasErrors Command
-- ---- ----- ----------- --------- -------
13 Contacts Running False False ...
14 Desktop Running False False ...
15 Documents Running False False ...
16 Downloads Running False False ...
17 Favorites Running False False ...
18 Links Running False False ...
19 Music Running False False ...
20 OneDrive Running False False ...
21 Pictures Running False False ...
22 Saved Games Running False False ...
23 Searches Running False False ...
24 Videos Running False False ...
Get-RSJob | Receive-RSJob
Name SizeMB
---- ------
Contacts 0
Desktop 7.24
Documents 83.99
Downloads 10259.6
Favorites 0
Links 0
Music 16691.89
OneDrive 1485.24
Pictures 1734.91
Saved Games 0
Searches 0
Videos 17.19
Description
-----------
Starts a background runspace job that looks at the total size of each folder. Using Get-RSJob | Recieve-RSJob shows
the results when the State is Completed.
-------------------------- EXAMPLE 2 --------------------------
PS C:\\>$Test = 'test'
$Something = 1..10
1..5|start-rsjob -Name {$_} -ScriptBlock {
Param($Object) [pscustomobject]@{
Result=($Object*2)
Test=$Using:Test
Something=$Using:Something
}
}
Id Name State HasMoreData HasErrors Command
-- ---- ----- ----------- --------- -------
76 1 Completed True False ...
77 2 Running False False ...
78 3 Running False False ...
79 4 Completed False False ...
80 5 Completed False False ...
Get-RSjob | Receive-RSJob
Result Test Something
------ ---- ---------
2 test {1, 2, 3, 4...}
4 test {1, 2, 3, 4...}
6 test {1, 2, 3, 4...}
8 test {1, 2, 3, 4...}
10 test {1, 2, 3, 4...}
Description
-----------
Shows an example of the $Using: variable being used in the scriptblock.
-------------------------- EXAMPLE 3 --------------------------
PS C:\\>$Test = 42
$AnotherTest = 7
$String = 'SomeString'
$ProcName = 'powershell_ise'
$ScriptBlock = {
Param($y,$z)
[pscustomobject] @{
Test = $y
Proc = (Get-Process -Name $Using:ProcName)
String = $Using:String
AnotherTest = ($z+$_)
PipedObject = $_
}
}
1..5|Start-RSJob $ScriptBlock -ArgumentList $test, $anothertest
Description
-----------
Shows an example of the $Using: variable being used in the scriptblock as well as $_ and multiple -ArgumentList
parameters.
RELATED LINKS