Udostępnij za pośrednictwem

Enter-PSHostProcess

  • Odwołanie
Moduł:
Microsoft.PowerShell.Core

Nawiązuje połączenie z sesją interaktywną i wchodzi w nią za pomocą procesu lokalnego.

Składnia

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>]

Opis

Polecenie cmdlet Enter-PSHostProcess nawiązuje połączenie i wprowadza w interakcyjnej sesji z procesem lokalnym. Począwszy od programu PowerShell 6.2, to polecenie cmdlet jest obsługiwane na platformach innych niż Windows.

Zamiast tworzyć nowy proces hostowania programu PowerShell i uruchamiania sesji zdalnej, sesja interaktywna jest uruchamiana w istniejącym procesie, który jest już uruchomiony w programie PowerShell. Podczas interakcji z sesją zdalną w określonym procesie można wyliczyć uruchomione przestrzenie uruchomieniowe, a następnie wybrać przestrzeń uruchamiania do debugowania, uruchamiając Debug-Runspace lub Enable-RunspaceDebug.

Proces, który chcesz wprowadzić, musi hostować program PowerShell (System.Management.Automation.dll). Musisz być członkiem grupy Administratorzy na komputerze, na którym znajduje się proces, lub użytkownik, który uruchamia skrypt, który uruchomił proces.

Po wybraniu obszaru uruchamiania do debugowania zostanie otwarta sesja zdalnego debugowania dla obszaru uruchomieniowego, jeśli jest aktualnie uruchomiona polecenie lub jest zatrzymana w debugerze. Następnie można debugować skrypt runspace w taki sam sposób, jak w przypadku debugowania innych skryptów sesji zdalnej.

Odłącz się od sesji debugowania, a następnie interakcyjnej sesji z procesem, uruchamiając dwukrotnie wyjście lub zatrzymaj wykonywanie skryptu, uruchamiając istniejące polecenie zakończenia debugera.

Jeśli określisz proces przy użyciu parametru Nazwa i zostanie znaleziony tylko jeden proces o określonej nazwie, proces zostanie wprowadzony. Jeśli zostanie znaleziony więcej niż jeden proces o określonej nazwie, program PowerShell zwróci błąd i wyświetli listę wszystkich procesów znalezionych z określoną nazwą.

Aby obsługiwać dołączanie do procesów na komputerach zdalnych, polecenie cmdlet Enter-PSHostProcess jest włączone na określonym komputerze zdalnym, dzięki czemu można dołączyć do procesu lokalnego w ramach zdalnej sesji programu PowerShell.

Przykłady

Przykładowa część 1. Rozpoczęcie debugowania przestrzeni uruchomieniowej w procesie środowiska POWERShell ISE

W tym przykładzie uruchomisz Enter-PSHostProcess z poziomu konsoli programu PowerShell, aby wprowadzić proces ŚRODOWISKA ISE programu PowerShell. W wynikowej sesji interaktywnej możesz znaleźć przestrzeń uruchomieniową, którą chcesz debugować, uruchamiając Get-Runspace, a następnie debugując przestrzeń uruchamiania.

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

Przykładowa część 2. Debugowanie określonej przestrzeni uruchomieniowej

Następnie debuguj identyfikator runspace ID 4, który uruchamia długotrwały skrypt innego użytkownika. Z listy zwróconej z Get-Runspacezwróć uwagę, że stan obszaru uruchamiania jest otwarty, a dostępność jest zajęta, co oznacza, że przestrzeń uruchamiania nadal działa długotrwały skrypt. Obiekty runspace zwrócone przez Get-Runspace mają również NoteProperty o nazwie ScriptStackTrace uruchomionego stosu poleceń, jeśli jest dostępny.

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

Uruchom interaktywną sesję debugowania z tą przestrzenią uruchamiania, uruchamiając polecenie cmdlet Debug-Runspace.

Przykładowa część 3. Zakończenie sesji debugowania i zakończenie

Po zakończeniu debugowania zezwól skryptowi na kontynuowanie działania bez dołączonego debugera, uruchamiając polecenie exit debugger. Alternatywnie możesz zamknąć debuger za pomocą poleceń q lub Stop.

Po zakończeniu pracy w procesie zakończ proces, uruchamiając polecenie cmdlet Exit-PSHostProcess. Spowoduje to zwrócenie monitu PS C:\>.

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

Parametry

-AppDomainName

Określa nazwę domeny aplikacji do nawiązania połączenia w przypadku pominięcia, używa DefaultAppDomain. Użyj Get-PSHostProcessInfo, aby wyświetlić nazwy domen aplikacji.

Typ:String
Position:1
Domyślna wartość:DefaultAppDomain
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-CustomPipeName

Pobiera lub ustawia niestandardową nazwę nazwanego potoku w celu nawiązania połączenia. Jest to zwykle używane w połączeniu z pwsh -CustomPipeName.

Ten parametr został wprowadzony w programie PowerShell 6.2.

Typ:String
Position:Named
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-HostProcessInfo

Określa obiekt PSHostProcessInfo, z którymi można nawiązać połączenie za pomocą programu PowerShell. Użyj Get-PSHostProcessInfo, aby pobrać obiekt.

Typ:PSHostProcessInfo
Position:0
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:True
Akceptowanie symboli wieloznacznych:False

-Id

Określa proces według identyfikatora procesu. Aby uzyskać identyfikator procesu, uruchom polecenie cmdlet Get-Process.

Typ:Int32
Position:0
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-Name

Określa proces według nazwy procesu. Aby uzyskać nazwę procesu, uruchom polecenie cmdlet Get-Process. Nazwy procesów można również pobrać z okna dialogowego Właściwości procesu w Menedżerze zadań.

Typ:String
Position:0
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-Process

Określa proces przez obiekt procesu. Najprostszym sposobem użycia tego parametru jest zapisanie wyników polecenia Get-Process, które zwraca proces, który ma zostać wprowadzony w zmiennej, a następnie określ zmienną jako wartość tego parametru.

Typ:Process
Position:0
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:True
Akceptowanie symboli wieloznacznych:False

Dane wejściowe

Process

Uwagi

Enter-PSHostProcess nie może wprowadzić procesu sesji programu PowerShell, w której uruchamiasz polecenie. Można jednak wprowadzić proces innej sesji programu PowerShell lub sesji programu PowerShell ISE uruchomionej w tym samym czasie co sesja, w której jest uruchomiona Enter-PSHostProcess.

Enter-PSHostProcess może wprowadzać tylko te procesy, które hostują program PowerShell. Oznacza to, że załadowali aparat programu PowerShell.

Aby zakończyć proces z poziomu procesu, wpisz zakończ, a następnie naciśnij Enter.

Przed programem PowerShell 7.1 komunikacja zdalna za pośrednictwem protokołu SSH nie obsługiwała sesji zdalnych drugiego przeskoku. Ta funkcja była ograniczona do sesji przy użyciu usługi WinRM. Program PowerShell 7.1 umożliwia Enter-PSSession i Enter-PSHostProcess pracę z poziomu dowolnej interaktywnej sesji zdalnej.