Reference: background tasks¶
Run slow PowerShell work (file scans, hashing, web requests, Get-WinEvent queries) without
freezing the window. How-to: Background tasks.
Rules¶
- The
-ScriptBlockruns in a new, isolated runspace: none of the caller's variables, functions or imported modules exist there (import what it needs inside the block). Its text is re-parsed in that runspace, so a closure's captured variables do not travel either. - Pass inputs with
-ArgumentListas plain data. NativeHTMLKit objects (application, window, document, node, bitmap, request, task, subscription) are refused anywhere inside the arguments (checked 8 levels deep) because they belong to the owning runspace. - The task's output becomes the result.
-OnCompletedand-OnFailedrun later on the owning runspace, while it pumps events (Wait-NativeHTMLKitor any waiting command), never inside another callback, and never afterClose-NativeHTMLKit. Update the UI there. - At most 8 unfinished tasks per application and 32 per process. A worker whose cancellation was requested still occupies its slot until its thread really ends.
-TimeoutMillisecondsandStop-NativeHTMLKitTaskonly request cancellation (PowerShellBeginStop). Interruptible commands such asStart-Sleepstop; a worker blocked in .NET or native code may keep running. Its eventual result is discarded.
Start-NativeHTMLKitTask¶
Alias: Start-NHKTask
Starts the scriptblock in an isolated runspace and returns a task handle.
Start-NativeHTMLKitTask [-Application] <Object> [-ScriptBlock] <scriptblock> [[-ArgumentList] <Object[]>] [[-OnCompleted] <scriptblock>] [[-OnFailed] <scriptblock>] [[-TimeoutMilliseconds] <int>] [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application that owns the task and runs its callbacks. |
-ScriptBlock |
scriptblock |
yes | - | Work to run. Receives the -ArgumentList values as positional arguments. |
-ArgumentList |
object[] |
no | @() |
Plain-data arguments. Pass one array argument as @(, $array). |
-OnCompleted |
scriptblock |
no | - | Runs on the owning runspace after success; receives the task output as one array (param($result); $result[0] is the first output object). |
-OnFailed |
scriptblock |
no | - | Runs on the owning runspace after a terminating error, a timeout (System.TimeoutException) or a stop (System.OperationCanceledException); receives the exception. Without it, a failure is written as a warning. |
-TimeoutMilliseconds |
int |
no | 0 |
Deadline after which cancellation is requested and the task fails with TimeoutException; 0 means no deadline. Range 0 to 3600000. |
Returns NativeHTMLKit.Task (property Id; use the cmdlets below to inspect it).
Errors a refused argument (A NativeHTMLKit.Window belongs to the owning runspace...); the task
limit (NativeHTMLKit background task limit (8 per application) reached...).
Non-terminating errors written by the worker (Write-Error) do not fail the task; they are
available as Errors from Receive-NativeHTMLKitTask. Exceptions thrown by -OnCompleted or
-OnFailed are isolated like event callbacks (stderr message, CallbackFailures counter).
$null = Start-NativeHTMLKitTask -Application $app -ArgumentList @($computer) -TimeoutMilliseconds 30000 -ScriptBlock {
param([string]$Name)
Get-CimInstance -ClassName Win32_Service -ComputerName $Name | Select-Object Name, State, StartMode
} -OnCompleted {
param($services)
Show-Services $services # runs on the UI runspace
} -OnFailed {
param($failure)
Set-NativeHTMLKitDocumentText -Document $doc -Element status -Text ('Query failed: ' + $failure.Message)
}
Receive-NativeHTMLKitTask¶
Alias: Receive-NHKTask
Reports a task's state and, with -Wait, pumps host messages until it completes. Calling it also
delivers any due completion callbacks (when not called from inside a callback).
Receive-NativeHTMLKitTask [-Task] <Object> [[-TimeoutMilliseconds] <int>] [-Wait] [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Task |
NativeHTMLKit.Task |
yes | - | The task. |
-Wait |
switch |
no | off | Wait (pumping events) until the task completes. |
-TimeoutMilliseconds |
int |
no | -1 |
With -Wait: give up after this time with System.TimeoutException (the task is not cancelled); -1 waits indefinitely. Range -1 to 2147483647. |
Returns @{ Id; Completed; Result; Failure; Errors; CancellationPending }.
CancellationPending is $true while a stopped or timed-out worker is still running.
Stop-NativeHTMLKitTask¶
Alias: Stop-NHKTask
Requests cancellation. The task is marked completed with an OperationCanceledException, which
-OnFailed receives; does nothing for a completed task.
Stop-NativeHTMLKitTask [-Task] <Object> [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Task |
NativeHTMLKit.Task |
yes | - | The task. |
Source: nativehtmlkit-powershell/docs/reference/tasks.md ยท edit the page there.