Share via

Enter-PSHostProcess

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

Se connecte à et entre 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 nouveau processus pour héberger PowerShell et exécuter une session à distance, la session interactive à distance 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 runspaces en cours d’exécution, puis sélectionner un runspace à 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 runspace à déboguer, une session de débogage à distance est ouverte pour l’runspace s’il exécute actuellement une commande ou s’il est arrêté dans le débogueur. Vous pouvez ensuite déboguer le script Runspace de la même manière que vous débogueriez 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 quitter deux fois, ou arrêtez l’exécution du script en exécutant la commande de départ du débogueur existante.

Si vous spécifiez un processus à l’aide du paramètre Name et qu’il n’existe qu’un seul processus 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 dans un ordinateur distant spécifié, de sorte que vous pouvez vous attacher à un processus local au sein d’une session PowerShell distante.

Exemples

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

Dans cet exemple, vous exécutez Enter-PSHostProcess à partir de la console PowerShell pour entrer dans le processus PowerShell ISE. Dans la session interactive résultante, vous pouvez trouver un runspace 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’espace d’exécution 4, qui exécute le script de longue durée d’un autre utilisateur. Dans la liste retournée à partir de Get-Runspace, notez que l’état de l’espace d’exécution est Ouvert et 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 ont également une propriété NoteProperty appelée ScriptStackTrace de la pile de commandes en cours d’exécution, si disponible.

[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 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 sortie du débogueur. 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 Exit-PSHostProcess commande. Cela vous renvoie à 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 en cas d’omission, utilise DefaultAppDomain. Utilisez Get-PSHostProcessInfo pour afficher les noms de domaine de l’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. Il 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 auquel il est possible de se connecter avec PowerShell. Utilisez Get-PSHostProcessInfo pour 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 process. Le moyen le plus simple d’utiliser ce paramètre consiste à enregistrer les résultats d’une Get-Process commande 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
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

Entrées

Process

Notes

Enter-PSHostProcess impossible d’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 peut entrer uniquement les processus qui hébergent PowerShell. Autrement dit, ils ont chargé le moteur PowerShell.

Pour quitter un processus à partir du processus, tapez exit, 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.