Enter-PSHostProcess

  • 参考
模块:
Microsoft.PowerShell.Core

连接到并进入与本地进程的交互会话。

语法

Enter-PSHostProcess
     [-Id] <Int32>
     [[-AppDomainName] <String>]
     [<CommonParameters>]
Enter-PSHostProcess
     [-Process] <Process>
     [[-AppDomainName] <String>]
     [<CommonParameters>]
Enter-PSHostProcess
     [-Name] <String>
     [[-AppDomainName] <String>]
     [<CommonParameters>]
Enter-PSHostProcess
     [-HostProcessInfo] <PSHostProcessInfo>
     [[-AppDomainName] <String>]
     [<CommonParameters>]
Enter-PSHostProcess
     -CustomPipeName <String>
     [<CommonParameters>]

说明

Enter-PSHostProcess cmdlet 连接到本地进程并进入交互式会话。 从 PowerShell 6.2 开始，此 cmdlet 在非 Windows 平台上受支持。

远程交互会话在已运行 PowerShell 的现有进程中运行，而不是创建一个新进程来托管 PowerShell 并运行远程会话。 与指定进程上的远程会话交互时，可以枚举正在运行的运行空间，然后选择一个运行空间，通过运行 Debug-Runspace 或 Enable-RunspaceDebug 对其进行调试。

你想要进入的进程必须能够托管 PowerShell (System.Management.Automation.dll)。 而你必须是发现该进程的计算机上“管理员”组的成员，或必须是运行启动进程的脚本的用户。

选择要调试的运行空间后，无论该运行空间当前是正在运行某个命令还是在调试器中已停止运行，都将为该运行空间打开一个远程调试会话。 你可以在其中按照调试其他远程会话脚本的相同方式调试该运行空间脚本。

运行两次 exit，先后离开调试会话和进程的交互会话，或通过运行现有调试器 Quit 命令停止脚本执行。

如果使用 Name 参数指定进程，并且只找到一个具有指定名称的进程，则进入该进程。 如果找到多个具有指定名称的进程，则 PowerShell 将返回错误，并列出所有找到的具有指定名称的进程。

若要支持连接到远程计算机上的进程，则在指定的远程计算机中启用 Enter-PSHostProcess cmdlet，以便你可以连接到远程 PowerShell 会话中的本地进程。

示例

示例第 1 部分：开始在 PowerShell ISE 进程中调试运行空间

在此示例中，从 PowerShell 控制台中运行 Enter-PSHostProcess 以进入 PowerShell ISE 进程。 在生成的交互式会话中，可以通过运行 Get-Runspace 找到要调试的运行空间，然后调试运行空间。

PS C:\> Enter-PSHostProcess -Name powershell_ise
[Process:1520]: PS C:\>  Get-Runspace
Id    Name          InstanceId                               State           Availability
--    -------       -----------                              ------          -------------
1     Runspace1     2d91211d-9cce-42f0-ab0e-71ac258b32b5     Opened          Available
2     Runspace2     a3855043-cb16-424a-a616-685360c3763b     Opened          RemoteDebug
3     MyLocalRS     2236dbd8-2105-4dec-a15a-a27d0bfaacb5     Opened          LocalDebug
4     MyRunspace    771356e9-8c44-4b70-9de5-dd17cb41e48e     Opened          Busy
5     Runspace8     3e517382-a97a-49ba-9c3c-fd21f6664288     Broken          None

示例第 2 部分：调试特定的运行空间

接下来，调试运行空间 ID 4，即运行其他用户的长时间运行的脚本。 在从 Get-Runspace 返回的列表中，请注意，运行空间“State”为 Opened，“Availability”为 Busy，这意味着运行空间仍在运行长时间运行的脚本。 Get-Runspace 返回的运行空间对象还具有正在运行的命令堆栈的名为 ScriptStackTrace 的 NoteProperty（如果可用）。

[Process:1520]: PS C:\>  (Get-Runspace -Id 4).ScriptStackTrace
Command                    Arguments                           Location
-------                    ---------                           --------
MyModuleWorkflowF1         {}                                  TestNoFile3.psm1: line 6
WFTest1                    {}                                  TestNoFile2.ps1: line 14
TestNoFile2.ps1            {}                                  TestNoFile2.ps1: line 22
<ScriptBlock>              {}                                  <No file>

[Process: 1520]: PS C:\>  Debug-Runspace -Id 4
Hit Line breakpoint on 'C:\TestWFVar1.ps1:83'

At C:\TestWFVar1.ps1:83 char:1
+ $scriptVar = "Script Variable"
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[Process: 1520]: [RSDBG: 4]: PS C:\>

通过运行 Debug-Runspace cmdlet 启动与此运行空间的交互式调试会话。

示例第 3 部分：完成调试会话并退出

完成调试后，通过运行“退出调试程序”命令，允许脚本继续运行，而无需附加调试程序。 或者，可以使用 q 或 Stop 命令退出调试程序。

完成进程中的工作后，请运行 Exit-PSHostProcess cmdlet 退出进程。 这会返回到 PS C:\> 提示符。

[Process:346]: [RSDBG: 3]: PS C:\> exit
[Process:1520]: PS C:\>
[Process:1520]: PS C:\>  Exit-PSHostProcess
PS C:\>

参数

-AppDomainName

指定要连接到的应用程序域名，如果省略，则使用 DefaultAppDomain。 使用 Get-PSHostProcessInfo 显示应用程序域名。

Type:String
Position:1
Default value:DefaultAppDomain
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CustomPipeName

获取或设置要连接到的自定义命名管道名称。 这通常与 pwsh -CustomPipeName 结合使用。

此参数是在 PowerShell 6.2 中引入的。

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

-HostProcessInfo

指定可以使用 PowerShell 连接到的 PSHostProcessInfo 对象。 使用 Get-PSHostProcessInfo 获取对象。

Type:PSHostProcessInfo
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Id

按进程 ID 指定进程。 若要获取进程 ID，请运行 Get-Process cmdlet。

Type:Int32
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Name

按进程名称指定进程。 若要获取进程名称，请运行 Get-Process cmdlet。 还可以在“任务管理器”中通过进程的“属性”对话框获取进程名称。

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Process

按进程对象指定进程。 使用此参数最简单的方法是，保存 Get-Process 命令（此命令可返回要通过某个变量进入的进程）的结果，然后将该变量指定为此参数的值。

Type:Process
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

输入

Process

备注

Enter-PSHostProcess 无法进入在其中运行命令的 Windows PowerShell 会话的进程。 但是，可以进入另一个 PowerShell 会话的进程，或与运行 Enter-PSHostProcess 的会话同时运行的 Windows PowerShell ISE 会话。

Enter-PSHostProcess 只能进入托管 PowerShell 的进程。 也就是说，它们已加载 PowerShell 引擎。

若要从进程内退出进程，请键入 exit，然后按 Enter。

在 PowerShell 7.1 之前，通过 SSH 进行远程处理不支持第二个跃点的远程会话。 此功能仅限于使用 WinRM 的会话。 PowerShell 7.1 允许 Enter-PSSession 和 Enter-PSHostProcess 在任何交互式远程会话中工作。