Enter-PSHostProcess
Conecta-se a 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 tem suporte em plataformas que não são 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. Ao interagir 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-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 foi 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, a sessão interativa com o processo, executando sair duas vezes ou interrompa a execução do script executando o comando sair 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 dentro do processo do ISE do PowerShell
Neste exemplo, você executa Enter-PSHostProcess de dentro do console do PowerShell para inserir o 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 NoneExemplo de parte 2: Depurar um runspace específico
Em seguida, depure a ID do runspace 4, que está executando o script de execução longa de outro usuário. Na lista retornada de Get-Runspace, observe que o estado do runspace é Aberto e a Disponibilidade está Ocupada, o que significa que o runspace ainda está executando o script de execução prolongada. 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 sair do depurador. 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 você 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 do 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. Isso 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
Observações
Enter-PSHostProcess não é possível inserir o 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 em execução ao mesmo tempo que a sessão na qual você está executando Enter-PSHostProcesso .
Enter-PSHostProcess pode inserir apenas os processos que hospedam 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.