Enter-PSHostProcess

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

Connecter s pour entrer dans une session interactive avec un processus 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

L’applet Enter-PSHostProcess de commande 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 l’un ou Enable-RunspaceDebugl’autre Debug-Runspace des instances d’exécution.

Le processus que vous souhaitez entrer doit héberger PowerShell (System.Management.Automation.dll). Vous devez être membre du groupe Administration istrators 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 Enter-PSHostProcess de commande est activée sur un ordinateur distant spécifié afin de pouvoir 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, puis déboguer l’espace d’exécution Get-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          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’état d’exécution est ouvert et que la 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 une noteProperty appelée 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 runspace en exécutant l’applet de Debug-Runspace commande.

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 Exit-PSHostProcess de commande. Vous êtes alors renvoyé à l’invite 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. Permet Get-PSHostProcessInfo d’afficher les noms de domaine d’application.

Type:String
Position:1
Default value:DefaultAppDomain
Required:False
Accept pipeline input:False
Accept wildcard characters: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
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-HostProcessInfo

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

Type:PSHostProcessInfo
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Id

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

Type:Int32
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Name

Spécifie un processus par le nom du processus. Pour obtenir un nom de processus, exécutez l’applet de Get-Process commande. 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
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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 qui retourne le Get-Process processus que vous souhaitez entrer dans une variable, puis à spécifier la variable comme valeur de ce paramètre.

Type:Process
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters: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 à partir 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 à distance de deuxième saut. Cette fonctionnalité était limitée aux sessions qui utilisaient WinRM. PowerShell 7.1 permet à Enter-PSSession et Enter-PSHostProcess de fonctionner dans n’importe quelle session à distance interactive.