Stop-AlTask
SYNOPSIS
Requests the cancellation of one or more running App Layering tasks or subtasks.
SYNTAX
Default (Default)
Stop-AlTask [-Force] [[-InputObject] <PSObject>] [-ConnectionId <Guid>] [<CommonParameters>]
<!--NeedCopy-->
ByTask
Stop-AlTask [-Force] [[-InputObject] <PSObject>] -WorkTicketId <Int64> [-ConnectionId <Guid>]
[<CommonParameters>]
<!--NeedCopy-->
BySubTask
Stop-AlTask [-Force] [[-InputObject] <PSObject>] -WorkItemId <Int64> [-ConnectionId <Guid>]
[<CommonParameters>]
<!--NeedCopy-->
DESCRIPTION
The Stop-AlTask cmdlet sends a request to the connected App Layering Appliance to cancel one or more ongoing tasks or specific subtasks.
Use this command to interrupt operations initiated by cmdlets like Start-AlIpsExport or Start-AlIpsPrepare that are no longer needed, are stuck, or were started in error.
Cancellation is typically requested gracefully, allowing the task to attempt cleanup if possible. The task may take some time to fully stop and reach a ‘Canceled’ state after this command is run.
You can specify the target task(s) or subtask(s) to cancel in several ways:
Using the pipeline (-InputObject parameter):
- Pipe the output object(s) directly from the relevant ‘Start-Al*’ command (e.g.,
$task | Stop-AlTask). - Pipe one or more Task IDs directly (e.g.,
123, 456 | Stop-AlTask). - Pipe a custom object or hashtable containing a ‘TaskId’ or ‘SubTaskId’ property (TaskId/SubTaskId value can be a single ID or an array of IDs).
Using specific parameters:
- Use the
-WorkTicketId(alias-TaskId) parameter to cancel a single, specific task by its ID. - Use the
-WorkItemId(alias-SubTaskId) parameter to cancel a single, specific subtask by its ID.
The -Force parameter attempts a more immediate cancellation request.
However, using -Force on a task that is already in the process of cancelling, may prevent the task from properly cleaning up associated resources.
Use this switch with caution.
EXAMPLES
Example 1
PS C:\> Stop-AlTask -TaskId 1114 -Force
<!--NeedCopy-->
This command forcefully requests the cancellation of the App Layering task with the ID 1114.
Example 2
PS C:\> Stop-AlTask -SubTaskId 224
<!--NeedCopy-->
This command requests the cancellation of the specific App Layering subtask with the ID 224.
Example 3
PS C:\> 1114, 629 | Stop-AlTask
PS C:\> @(1114, 629) | Stop-AlTask
<!--NeedCopy-->
Both of these commands request the cancellation of two App Layering tasks, with IDs 1114 and 629, by piping the IDs directly to the cmdlet.
Example 4
PS C:\> $exportTask = Start-AlIpsExport -ConnectorConfigId "063A0697-ACDF-43BB-969B-AA69F1419757" -SourceDisk "[DatastoreName] VMFolder/disk.vmdk" -OutputDiskName "MyExportedDisk"
PS C:\> $exportTask | Stop-AlTask -Force
<!--NeedCopy-->
This example first starts an export task and stores the resulting task object in the $exportTask variable.
The second command then pipes this task object to Stop-AlTask with the -Force switch to forcefully request the cancellation of that specific export operation.
Example 5
PS C:\> @{"TaskId" = @(1114, 629)} | Stop-AlTask
<!--NeedCopy-->
This command requests the cancellation of tasks 1114 and 629 by piping a hashtable containing a TaskId key whose value is an array of the task IDs.
Example 6
PS C:\> New-Object PSObject -Property @{TaskId = @(1114, "629")} | Stop-AlTask
<!--NeedCopy-->
Similar to the previous example, this command cancels tasks 1114 and 629 by piping a custom PSObject that has a TaskId property containing an array of the IDs.
Example 7
PS C:\> New-Object PSObject -Property @{SubTaskId = 224} | Stop-AlTask
<!--NeedCopy-->
This command cancels subtask 224 by piping a custom PSObject that has a SubTaskId property with the subtask’s ID.
PARAMETERS
-ConnectionId
Specifies the connection to the App Layering Appliance to use for this operation.
This is the GUID returned by Connect-AlAppliance.
If omitted, the command uses the current connection automatically if it’s the only one active. When multiple sessions are active, the GUID of the most recently used connection is used.
Type: Guid
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-Force
Forces the cancellation request. By default, Stop-AlTask sends a standard cancellation request allowing for potential cleanup. Using -Force attempts a more immediate stop signal. Caution: Forcing cancellation on a task already attempting to cancel, may prevent proper resource cleanup associated with the task.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-InputObject
Accepts input via the pipeline to specify the task(s) or subtask(s) to process. This parameter offers flexibility in how targets are provided. It can process:
- Task objects output by ‘Start-Al*’ cmdlets (automatically extracts the
TaskId). - Single Task IDs (System.Int64).
- Arrays of Task IDs (System.Int64[]).
- Hashtables or PSCustomObjects containing a ‘TaskId’ key/property (value can be a single Int64 ID or an array of Int64 IDs).
- Hashtables or PSCustomObjects containing a ‘SubTaskId’ key/property (value should be a single Int64 ID or an array of Int64 IDs).
Refer to the examples section for detailed usage patterns. Cannot be used with -WorkTicketId or -WorkItemId.
Type: PSObject
Parameter Sets: (All)
Aliases:
Required: False
Position: 0
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False
<!--NeedCopy-->
-WorkItemId
Specifies the unique identifier (WorkItemId or SubTaskId) of a single App Layering subtask to process. This parameter cannot be used with -InputObject or -WorkTicketId.
Type: Int64
Parameter Sets: BySubTask
Aliases: SubTaskId
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
-WorkTicketId
Specifies the unique identifier (WorkTicketId or TaskId) of a single App Layering task to process. This parameter cannot be used with -InputObject or -WorkItemId.
Type: Int64
Parameter Sets: ByTask
Aliases: TaskId
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
<!--NeedCopy-->
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
System.Management.Automation.PSObject
OUTPUTS
[Int64[]] (Array)
Returns the TaskIds of the tasks for which cancellation was initiated. These objects can be piped to Wait-AlTask to await the cancellation to complete.
Type: Int64