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>]
Enter-PSHostProcess
     -CustomPipeName <String>
     [<CommonParameters>]

Description

L’applet de commande Enter-PSHostProcess se connecte et entre dans une session interactive avec un processus local. À compter de PowerShell 6.2, cette applet de commande est prise en charge sur les plateformes autres que Windows.

Au lieu de créer un processus pour héberger PowerShell et exécuter une session à distance, la session interactive distante est exécutée dans un processus existant qui exécute déjà 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 à déboguer en exécutant Debug-Runspace ou Enable-RunspaceDebug.

Le processus que vous souhaitez entrer doit héberger 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, 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é, afin que vous puissiez vous attacher à un processus local au sein d’une session PowerShell distante.

Exemples

Exemple de partie 1 : Démarrer le débogage d’un espace d’exécution dans le processus PowerShell ISE

Dans cet exemple, vous exécutez Enter-PSHostProcess à partir de la console PowerShell pour entrer le processus PowerShell ISE. Dans la session interactive résultante, vous pouvez trouver un espace d’exécution que vous souhaitez déboguer en exécutant Get-Runspace, puis déboguer l’espace d’exécution.

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

Exemple de partie 2 : Déboguer un runspace spécifique

Ensuite, déboguez l’ID d’instance d’exécution 4, qui exécute le script long d’un autre utilisateur. Dans la liste retournée par Get-Runspace, notez que l'd’état d’exécution est ouvert et que disponibilité est occupé, ce qui signifie que l’espace d’exécution exécute toujours le script de longue durée. Les objets runspace retournés par Get-Runspace ont également un NoteProperty appelé ScriptStackTrace de la pile de commandes en cours d’exécution, le cas échéant.

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

Démarrez une session de débogage interactive avec cet espace d’exécution en exécutant l’applet de commande Debug-Runspace.

Exemple de partie 3 : Terminer la session de débogage et quitter

Une fois le débogage terminé, autorisez le script à continuer à s’exécuter sans le débogueur attaché en exécutant la commande de débogueur de sortie. Vous pouvez également quitter le débogueur avec les commandes q ou Arrêter.

Lorsque vous avez terminé de travailler dans le processus, quittez le processus en exécutant l’applet de commande Exit-PSHostProcess. Cette opération vous renvoie à l’invite de PS C:\>.

[Process:346]: [RSDBG: 3]: PS C:\> exit
[Process:1520]: PS C:\>
[Process:1520]: PS C:\>  Exit-PSHostProcess
PS C:\>

Paramètres

-AppDomainName

Spécifie un nom de domaine d’application auquel se connecter s’il est omis, utilise DefaultAppDomain. Utilisez Get-PSHostProcessInfo pour afficher les noms de domaine d’application.

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

-CustomPipeName

Obtient ou définit le nom de canal nommé personnalisé auquel se connecter. Cela est généralement utilisé conjointement avec pwsh -CustomPipeName.

Ce paramètre a été introduit dans PowerShell 6.2.

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

-HostProcessInfo

Spécifie un objet PSHostProcessInfo qui peut être connecté à PowerShell. Utilisez Get-PSHostProcessInfo pour obtenir l’objet.

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 PowerShell dans laquelle vous exécutez la commande. Toutefois, vous pouvez entrer le processus d’une autre session PowerShell ou d’une session 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 PowerShell. Autrement dit, ils ont chargé le moteur PowerShell.

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

Avant PowerShell 7.1, la communication à distance via SSH ne prenait pas en charge les sessions distantes du deuxième tronçon. Cette fonctionnalité était limitée aux sessions utilisant WinRM. PowerShell 7.1 permet Enter-PSSession et Enter-PSHostProcess de fonctionner à partir de n’importe quelle session distante interactive.