Start-RSJob

SYNOPSIS

Starts a background job using runspaces.

SYNTAX

ScriptBlock (Default)

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>]

ScriptPath

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.

EXAMPLES

EXAMPLE 1

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

$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

$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.

PARAMETERS

-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.

Type: System.Management.Automation.ScriptBlock
Parameter Sets: ScriptBlock
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-FilePath

This is the path to a file containing code that will be run in the background runspace job.

Type: System.String
Parameter Sets: ScriptPath
Aliases:

Required: False
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-InputObject

The object being piped into Start-RSJob or applied via the parameter.

Type: System.Object
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False

-Name

The name of a background runspace job

Type: System.Object
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Batch

Name of the batch of RSJobs that will be run

Type: System.String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: $([guid]::NewGuid().ToString())
Accept pipeline input: False
Accept wildcard characters: False

-ArgumentList

List of values that will be applied at the end of the argument list in the Param() statement.

Type: System.Array
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-Throttle

Number of concurrent running runspace jobs which are allowed at a time.

Type: System.Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: 5
Accept pipeline input: False
Accept wildcard characters: False

-ModulesToImport

A collection of modules that will be imported into the background runspace job.

Type: System.String[]
Parameter Sets: (All)
Aliases: ModulesToLoad

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-PSSnapinsToImport

A collection of PSSnapins that will be imported into the background runspace job.

Type: System.String[]
Parameter Sets: (All)
Aliases: PSSnapinsToLoad

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-FunctionsToImport

A collection of functions that will be imported for use with a background runspace job.

Type: System.String[]
Parameter Sets: (All)
Aliases: FunctionsToLoad

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-FunctionFilesToImport

A collection of files containing custom functions that will be imported into the background runspace job.

Type: System.String[]
Parameter Sets: (All)
Aliases: FunctionFilesToLoad

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-VariablesToImport

A collection of variables that will be imported for use with a background runspace job. If used, $using:variable not expanded !

Type: System.String[]
Parameter Sets: (All)
Aliases: VariablesToLoad

Required: False
Position: Named
Default value: None
Accept pipeline input: False
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.

INPUTS

OUTPUTS

RSJob

NOTES

Name: Start-RSJob Author: Boe Prox/Max Kozlov

RELATED LINKS