Enter-PSHostProcess

  • Referência
Módulo:
Microsoft.PowerShell.Core

Conecta-se e entra em uma sessão interativa com um processo local.

Syntax

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 é suportado em plataformas que não sejam do 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 estiver interagindo com uma sessão remota em um processo especificado, você pode enumerar espaços de execução em execução e, em seguida, selecionar um espaço de execução para depurar executando um ou Debug-RunspaceEnable-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 no qual o processo é encontrado ou deve ser o usuário que está executando o script que iniciou o processo.

Depois de selecionar um espaço de execução para depurar, uma sessão de depuração remota é aberta para o espaço de execução se ele estiver atualmente executando um comando ou for interrompido no depurador. Em seguida, você pode depurar o script de espaço de execução 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 pare 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 cmdlet é habilitado em um computador remoto especificado, para que você possa anexar a um processo local em uma sessão remota do Enter-PSHostProcess PowerShell.

Exemplos

Exemplo Parte 1: Iniciar a depuração de um espaço de execução dentro do processo ISE do PowerShell

Neste exemplo, você executa Enter-PSHostProcess de dentro do console do PowerShell para entrar no processo ISE do PowerShell. Na sessão interativa resultante, você pode encontrar um espaço de execução que deseja depurar executando e, em Get-Runspaceseguida, depurar o espaço de execução.

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 parte 2: Depurar um espaço de execução específico

Em seguida, depure o ID 4 do espaço de execução, que está executando o script de longa execução de outro usuário. Na lista retornada de , observe que o estado do espaço de execução é Aberto e a disponibilidade está ocupada, o que significa que o espaço de Get-Runspaceexecução ainda está executando o script de longa execução. Os objetos 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 espaço de execução executando o Debug-Runspace cmdlet.

Exemplo 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

Especifica um nome de domínio de aplicativo ao qual se conectar se omitido, usa DefaultAppDomain. Use Get-PSHostProcessInfo para exibir os nomes de domínio do aplicativo.

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

-CustomPipeName

Obtém ou define o nome do pipe nomeado personalizado ao qual se conectar. Isto é geralmente usado em conjunto com pwsh -CustomPipeName.

Esse parâmetro foi introduzido no PowerShell 6.2.

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

-HostProcessInfo

Especifica um objeto PSHostProcessInfo que pode ser conectado ao PowerShell. Use Get-PSHostProcessInfo para obter o objeto.

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

-Id

Especifica um processo pela ID do processo. Para obter uma ID de processo, execute o Get-Process cmdlet.

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

-Name

Especifica um processo pelo nome do processo. Para obter um nome de processo, execute o Get-Process cmdlet. Você também pode obter nomes de processo na caixa de diálogo Propriedades de um processo no Gerenciador de Tarefas.

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

-Process

Especifica um processo pelo objeto de processo. A maneira mais simples de usar esse parâmetro é salvar os resultados de um Get-Process comando que retorna o processo que você deseja inserir em uma variável e, em seguida, especificar a variável como o valor desse parâmetro.

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

Entradas

Process

Notas

Enter-PSHostProcess não pode 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 ISE do PowerShell que esteja sendo executada ao mesmo tempo que a sessão na qual você está executando Enter-PSHostProcesso .

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 sobre SSH não oferecia suporte a sessões remotas de segundo salto. Esse recurso foi limitado a sessões usando o WinRM. O PowerShell 7.1 permite Enter-PSSession e Enter-PSHostProcess funciona a partir de qualquer sessão remota interativa.