functions/runspace/Stop-PSFRunspace.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
function Stop-PSFRunspace
{
<#
 .SYNOPSIS
  Stops a runspace that was registered to the PSFramework
  
 .DESCRIPTION
  Stops a runspace that was registered to the PSFramework
  Will not cause errors if the runspace is already halted.
   
  Runspaces may not automatically terminate immediately when calling this function.
  Depending on the implementation of the scriptblock, this may in fact take a little time.
  If the scriptblock hasn't finished and terminated the runspace in a seemingly time, it will be killed by the system.
  This timeout is by default 30 seconds, but can be altered by using the Configuration System.
  For example, this line will increase the timeout to 60 seconds:
  Set-PSFConfig -FullName PSFramework.Runspace.StopTimeout -Value 60
  
 .PARAMETER Name
  The name of the registered runspace to stop
  
 .PARAMETER Runspace
  The runspace to stop. Returned by Get-PSFRunspace
  
 .PARAMETER EnableException
  This parameters disables user-friendly warnings and enables the throwing of exceptions.
  This is less user friendly, but allows catching exceptions in calling scripts.
  
 .PARAMETER Confirm
  If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
  
 .PARAMETER WhatIf
  If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
  
 .EXAMPLE
  PS C:\> Stop-PSFRunspace -Name 'mymodule.maintenance'
   
  Stops the runspace registered under the name 'mymodule.maintenance'
  
 .NOTES
  Additional information about the function.
#>

    [CmdletBinding(SupportsShouldProcess = $true)]
    Param (
        [Parameter(ValueFromPipeline = $true)]
        [string[]]
        $Name,
        
        [Parameter(ValueFromPipeline = $true)]
        [PSFramework.Runspace.RunspaceContainer[]]
        $Runspace,
        
        [switch]
        $EnableException
    )
    
    process
    {
        foreach ($item in $Name)
        {
            # Ignore all output from Get-PSFRunspace - it'll be handled by the second loop
            if ($item -eq "psframework.runspace.runspacecontainer") { continue }
            
            if ([PSFramework.Runspace.RunspaceHost]::Runspaces.ContainsKey($item.ToLower()))
            {
                if ($PSCmdlet.ShouldProcess($item, "Stopping Runspace"))
                {
                    try
                    {
                        Write-PSFMessage -Level Verbose -Message "Stopping runspace: <c='em'>$($item.ToLower())</c>" -Target $item.ToLower() -Tag "runspace", "stop"
                        [PSFramework.Runspace.RunspaceHost]::Runspaces[$item.ToLower()].Stop()
                    }
                    catch
                    {
                        Stop-PSFFunction -Message "Failed to stop runspace: <c='em'>$($item.ToLower())</c>" -EnableException $EnableException -Tag "fail", "argument", "runspace", "stop" -Target $item.ToLower() -Continue -ErrorRecord $_
                    }
                }
            }
            else
            {
                Stop-PSFFunction -Message "Failed to stop runspace: <c='em'>$($item.ToLower())</c> | No runspace registered under this name!" -EnableException $EnableException -Category InvalidArgument -Tag "fail", "argument", "runspace", "stop" -Target $item.ToLower() -Continue
            }
        }
        
        foreach ($item in $Runspace)
        {
            if ($PSCmdlet.ShouldProcess($item.Name, "Stopping Runspace"))
            {
                try
                {
                    Write-PSFMessage -Level Verbose -Message "Stopping runspace: <c='em'>$($item.Name.ToLower())</c>" -Target $item -Tag "runspace", "stop"
                    $item.Stop()
                }
                catch
                {
                    Stop-PSFFunction -Message "Failed to stop runspace: <c='em'>$($item.Name.ToLower())</c>" -EnableException $EnableException -Tag "fail", "argument", "runspace", "stop" -Target $item -Continue -ErrorRecord $_
                }
            }
        }
    }
}