Enter-PSHostProcess

Sintaxe

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

Description

O Enter-PSHostProcess cmdlet se conecta e entra em uma sessão interativa com um processo local. A partir do PowerShell 6.2, esse cmdlet tem suporte em plataformas não Windows.

Em vez de criar um novo processo para hospedar o PowerShell e executar uma sessão remota, a sessão remota e interativa é executada em um processo existente que já está executando o PowerShell. Quando você está interagindo com uma sessão remota em um processo especificado, você pode enumerar runspaces em execução e, em seguida, selecionar um runspace para depurar executando ou Debug-Runspace Enable-RunspaceDebug.

O processo que você deseja inserir deve estar hospedando o PowerShell (System.Management.Automation.dll). Você deve ser membro do grupo Administradores no computador em que o processo é encontrado ou deve ser o usuário que está executando o script que iniciou o processo.

Depois de selecionar um runspace para depurar, uma sessão de depuração remota será aberta para o runspace se ele estiver executando um comando no momento ou estiver parado no depurador. Em seguida, você pode depurar o script de runspace da mesma forma que depuraria outros scripts de sessão remota.

Desanexe de uma sessão de depuração e, em seguida, da sessão interativa com o processo, executando exit duas vezes ou interrompa a execução do script executando o comando quit do depurador existente.

Se você especificar um processo usando o parâmetro Name e houver apenas um processo encontrado com o nome especificado, o processo será inserido. Se mais de um processo com o nome especificado for encontrado, o PowerShell retornará um erro e listará todos os processos encontrados com o nome especificado.

Para dar suporte à anexação a processos em computadores remotos, o Enter-PSHostProcess cmdlet é habilitado em um computador remoto especificado, para que você possa anexar a um processo local em uma sessão remota do PowerShell.

Exemplos

Exemplo Parte 1: Iniciar a depuração de um runspace no processo do ISE do PowerShell

Neste exemplo, você executa Enter-PSHostProcess de dentro do console do PowerShell para entrar no processo do ISE do PowerShell. Na sessão interativa resultante, você pode encontrar um runspace que deseja depurar executando Get-Runspacee, em seguida, depurar o 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

Exemplo de parte 2: Depurar um runspace específico

Em seguida, depure a ID 4 do runspace, que está executando o script de execução longa de outro usuário. Na lista retornada de , observe que o estado do Get-Runspacerunspace é Aberto e a Disponibilidade é Ocupado, o que significa que o runspace ainda está executando o script de execução longa. Os objetos de runspace retornados por Get-Runspace também têm uma NoteProperty chamada ScriptStackTrace da pilha de comandos em execução, se disponível.

[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:\>

Inicie uma sessão de depuração interativa com esse runspace executando o Debug-Runspace cmdlet.

Exemplo de parte 3: Concluir a sessão de depuração e sair

Depois de concluir a depuração, permita que o script continue em execução sem o depurador anexado executando o comando exit debugger. Como alternativa, você pode sair do depurador com os comandos q ou Stop.

Quando terminar de trabalhar no processo, saia do processo executando o Exit-PSHostProcess cmdlet. Isso retorna ao PS C:\> prompt.

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

Parâmetros

-AppDomainName

-CustomPipeName

-HostProcessInfo

-Id

-Name

-Process

Entradas

Process

Observações

Enter-PSHostProcess não é possível entrar no processo da sessão do PowerShell na qual você está executando o comando. No entanto, você pode inserir o processo de outra sessão do PowerShell ou uma sessão do ISE do PowerShell que esteja sendo executada ao mesmo tempo que a sessão na qual você está executando Enter-PSHostProcess.

Enter-PSHostProcess pode inserir apenas os processos que estão hospedando o PowerShell. Ou seja, eles carregaram o mecanismo do PowerShell.

Para sair de um processo de dentro do processo, digite exit e pressione Enter.

Antes do PowerShell 7.1, a comunicação remota por SSH não dava suporte a sessões remotas de segundo salto. Essa funcionalidade estava limitada a sessões que usavam o WinRM. O PowerShell 7.1 permite que Enter-PSSession e Enter-PSHostProcess funcionem em qualquer sessão remota interativa.

Links Relacionados

• Exit-PSHostProcess
• Get-PSHostProcessInfo