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

Description

O cmdlet Enter-PSHostProcess se conecta e entra em uma sessão interativa com um processo local.

Em vez de criar um novo processo para hospedar o Windows PowerShell e executar uma sessão remota, a sessão remota e interativa é executada em um processo existente que já está executando o Windows 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 Windows 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 Windows 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 Windows PowerShell.

Exemplos

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

In this example, you run **Enter-PSHostProcess** from within the Windows PowerShell console to enter the Windows PowerShell ISE process. In the resulting interactive session, you can find a runspace that you want to debug by running Get-Runspace, and then debug the runspace.
PS C:\> Enter-PSHostProcess -Name powershell_ise
[Process:1520]: PS C:\Test\Documents>

Next, get available runspaces within the process you have entered.
PS C:\> [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

The runspace objects returned by **Get-Runspace** also have a NoteProperty called **ScriptStackTrace** of the running command stack, if available.Next, debug runspace ID 4, that is running another user's long-running script. From the list returned from **Get-Runspace**, note that the runspace state is **Opened**, and **Availability** is **Busy**, meaning that the runspace is still running the long-running script.
PS C:\> [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>

Start an interactive debugging session with this runspace by running the Debug-Runspace cmdlet.
PS C:\> [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:\> >

After you are finished debugging, allow the script to continue running without the debugger attached by running the **exit** debugger command. Alternatively, you can quit the debugger with the **q** or **Stop** commands.
PS C:\> [Process:346]: [RSDBG: 3]: PS C:\> > exit
[Process:1520]: PS C:\>

When you are finished working in the process, exit the process by running the Exit-PSHostProcess cmdlet. This returns you to the PS C:\> prompt.
PS C:\> [Process:1520]: PS C:\>  Exit-PSHostProcess
PS C:\>

Parâmetros

-AppDomainName

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

-HostProcessInfo

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 Windows PowerShell na qual você está executando o comando. No entanto, você pode inserir o processo de outra sessão do Windows PowerShell ou uma sessão ISE do Windows 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 hospedam o Windows PowerShell. Ou seja, eles carregaram o mecanismo do Windows PowerShell.

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