Partager via

Enter-PSHostProcess

  • Référence
Module:
Microsoft.PowerShell.Core

Se connecte et entre dans une session interactive avec un processus local.

Syntaxe

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

L’applet de commande Enter-PSHostProcess se connecte et entre dans une session interactive avec un processus local.

Au lieu de créer un processus pour héberger Windows PowerShell et exécuter une session à distance, la session interactive distante est exécutée dans un processus existant qui exécute déjà Windows PowerShell. Lorsque vous interagissez avec une session distante sur un processus spécifié, vous pouvez énumérer les instances d’exécution en cours d’exécution, puis sélectionner un espace d’exécution pour déboguer en exécutant Debug-Runspace ou Enable-RunspaceDebug.

Le processus que vous souhaitez entrer doit héberger Windows PowerShell (System.Management.Automation.dll). Vous devez être membre du groupe Administrateurs sur l’ordinateur sur lequel le processus est trouvé, ou vous devez être l’utilisateur qui exécute le script qui a démarré le processus.

Une fois que vous avez sélectionné un espace d’exécution pour déboguer, une session de débogage à distance est ouverte pour l’espace d’exécution s’il exécute actuellement une commande ou s’il est arrêté dans le débogueur. Vous pouvez ensuite déboguer le script d’exécution de la même façon que vous déboguez d’autres scripts de session distante.

Détachez-vous d’une session de débogage, puis de la session interactive avec le processus, en exécutant la sortie deux fois ou en arrêtant l’exécution du script en exécutant la commande de débogueur existante.

Si vous spécifiez un processus à l’aide du paramètre Name et qu’il n’y a qu’un seul processus trouvé avec le nom spécifié, le processus est entré. Si plusieurs processus portant le nom spécifié sont trouvés, Windows PowerShell retourne une erreur et répertorie tous les processus trouvés avec le nom spécifié.

Pour prendre en charge l’attachement à des processus sur des ordinateurs distants, l’applet de commande Enter-PSHostProcess est activée sur un ordinateur distant spécifié, de sorte que vous puissiez vous attacher à un processus local au sein d’une session Windows PowerShell distante.

Exemples

Exemple 1 : Démarrer le débogage d’un runspace dans le processus Windows PowerShell ISE

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

Paramètres

-AppDomainName

Type:String
Position:1
Valeur par défaut:None
Obligatoire:False
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-HostProcessInfo

Type:PSHostProcessInfo
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

-Id

Spécifie un processus par l’ID de processus. Pour obtenir un ID de processus, exécutez l’applet de commande Get-Process.

Type:Int32
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Name

Spécifie un processus par le nom du processus. Pour obtenir un nom de processus, exécutez l’applet de commande Get-Process. Vous pouvez également obtenir des noms de processus à partir de la boîte de dialogue Propriétés d’un processus dans le Gestionnaire des tâches.

Type:String
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:False
Accepter les caractères génériques:False

-Process

Spécifie un processus par l’objet de processus. La façon la plus simple d’utiliser ce paramètre consiste à enregistrer les résultats d’une commande Get-Process qui retourne le processus que vous souhaitez entrer dans une variable, puis à spécifier la variable comme valeur de ce paramètre.

Type:Process
Position:0
Valeur par défaut:None
Obligatoire:True
Accepter l'entrée de pipeline:True
Accepter les caractères génériques:False

Entrées

Process

Notes

  • Enter-PSHostProcess ne peut pas entrer le processus de la session Windows PowerShell dans laquelle vous exécutez la commande. Toutefois, vous pouvez entrer le processus d’une autre session Windows PowerShell ou d’une session Windows PowerShell ISE qui s’exécute en même temps que la session dans laquelle vous exécutez Enter-PSHostProcess.

    Enter-PSHostProcess ne peut entrer que les processus qui hébergent Windows PowerShell. Autrement dit, ils ont chargé le moteur Windows PowerShell.

    Pour quitter un processus à partir du processus, tapez quitter, puis appuyez sur Entrée.