Partilhar via

Enter-PSHostProcess

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

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

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 cmdlet Enter-PSHostProcess 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 você estiver interagindo com uma sessão remota em um processo especificado, poderá enumerar espaços de execução em execução e, em seguida, selecionar um espaço de execução para depurar executando Debug-Runspace ou 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 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 Enter-PSHostProcess é 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 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 Get-Runspacee, em seguida, 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 do Get-Runspace, observe que o de Estado de do espaço de execução é Aberto e de Disponibilidade está ocupado, o que significa que o espaço de execução ainda está executando o script de longa execução. Os objetos de espaço de execução retornados por Get-Runspace também têm um NoteProperty chamado 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 cmdlet Debug-Runspace.

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 cmdlet Exit-PSHostProcess. Isso retorna ao prompt PS C:\>.

[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.

Tipo:String
Position:1
Default value:DefaultAppDomain
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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.

Tipo:String
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-HostProcessInfo

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

Tipo:PSHostProcessInfo
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Id

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

Tipo:Int32
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Name

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

Tipo:String
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Process

Especifica um processo pelo objeto de processo. A maneira mais simples de usar esse parâmetro é salvar os resultados de um comando Get-Process 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.

Tipo:Process
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais: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-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 saire 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 que Enter-PSSession e Enter-PSHostProcess trabalhem a partir de qualquer sessão remota interativa.