Skip to content

Enter-PSHostProcess available on non-Windows platforms in PS 6.2 #5055

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 4, 2019
Merged

Enter-PSHostProcess available on non-Windows platforms in PS 6.2 #5055

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a9fed6c
changes in PS62
davidsmatlak Nov 4, 2019
49e8914
Merge branch 'staging' of https://github.com/MicrosoftDocs/PowerShell…
davidsmatlak Nov 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 66 additions & 33 deletions reference/6/Microsoft.PowerShell.Core/Enter-PSHostProcess.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,12 @@ external help file: System.Management.Automation.dll-Help.xml
keywords: powershell,cmdlet
locale: en-us
Module Name: Microsoft.PowerShell.Core
ms.date: 03/22/2019
ms.date: 11/04/2019
online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/enter-pshostprocess?view=powershell-6&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Enter-PSHostProcess
---

# Enter-PSHostProcess

## SYNOPSIS
Expand Down Expand Up @@ -36,7 +37,8 @@ Enter-PSHostProcess [-Name] <String> [[-AppDomainName] <String>] [<CommonParamet
### PSHostProcessInfoParameterSet

```
Enter-PSHostProcess [-HostProcessInfo] <PSHostProcessInfo> [[-AppDomainName] <String>] [<CommonParameters>]
Enter-PSHostProcess [-HostProcessInfo] <PSHostProcessInfo> [[-AppDomainName] <String>]
[<CommonParameters>]
```

### PipeNameParameterSet
Expand All @@ -47,30 +49,42 @@ Enter-PSHostProcess -CustomPipeName <String> [<CommonParameters>]

## DESCRIPTION

The **Enter-PSHostProcess** cmdlet connects to and enters into an interactive session with a local process.
The `Enter-PSHostProcess` cmdlet connects to and enters into an interactive session with a local
process. Beginning in PowerShell 6.2, this cmdlet is supported on non-Windows platforms.

Instead of creating a new process to host PowerShell and run a remote session, the remote, interactive session is run in an existing process that is already running PowerShell.
When you are interacting with a remote session on a specified process, you can enumerate running runspaces, and then select a runspace to debug by running either Debug-Runspace or Enable-RunspaceDebug.
Instead of creating a new process to host PowerShell and run a remote session, the remote,
interactive session is run in an existing process that is already running PowerShell. When you are
interacting with a remote session on a specified process, you can enumerate running runspaces, and
then select a runspace to debug by running either `Debug-Runspace` or `Enable-RunspaceDebug`.

The process that you want to enter must be hosting PowerShell (System.Management.Automation.dll).
You must be either a member of the Administrators group on the computer on which the process is found, or you must be the user who is running the script that started the process.
You must be either a member of the Administrators group on the computer on which the process is
found, or you must be the user who is running the script that started the process.

After you have selected a runspace to debug, a remote debug session is opened for the runspace if it is either currently running a command or is stopped in the debugger.
You can then debug the runspace script in the same way you would debug other remote session scripts.
After you have selected a runspace to debug, a remote debug session is opened for the runspace if it
is either currently running a command or is stopped in the debugger. You can then debug the runspace
script in the same way you would debug other remote session scripts.

Detach from a debugging session, and then the interactive session with the process, by running exit twice, or stop script execution by running the existing debugger quit command.
Detach from a debugging session, and then the interactive session with the process, by running exit
twice, or stop script execution by running the existing debugger quit command.

If you specify a process by using the *Name* parameter, and there is only one process found with the specified name, the process is entered.
If more than one process with the specified name is found, PowerShell returns an error, and lists all processes found with the specified name.
If you specify a process by using the **Name** parameter, and there is only one process found with
the specified name, the process is entered. If more than one process with the specified name is
found, PowerShell returns an error, and lists all processes found with the specified name.

To support attaching to processes on remote computers, the **Enter-PSHostProcess** cmdlet is enabled in a specified remote computer, so that you can attach to a local process within a remote PowerShell session.
To support attaching to processes on remote computers, the `Enter-PSHostProcess` cmdlet is enabled
in a specified remote computer, so that you can attach to a local process within a remote PowerShell
session.

## EXAMPLES

### Example 1: Start debugging a runspace within the Windows PowerShell ISE process
### Example 1: Start debugging a runspace within the PowerShell ISE process

In this example, you run `Enter-PSHostProcess` from within the PowerShell console to enter the
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.

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

Expand All @@ -84,7 +98,12 @@ Id Name InstanceId State Ava
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.
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
------- --------- --------
Expand All @@ -94,6 +113,7 @@ TestNoFile2.ps1 {} TestNoFile2.ps1:
<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'

Expand All @@ -103,11 +123,16 @@ At C:\TestWFVar1.ps1:83 char:1

[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.
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.
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:\>
```
Expand All @@ -116,20 +141,26 @@ PS C:\>

### -AppDomainName

Specifies an application domain name to connect to if omitted, uses **DefaultAppDomain**. Use
`Get-PSHostProcessInfo` to display the application domain names.

```yaml
Type: String
Parameter Sets: ProcessIdParameterSet, ProcessParameterSet, ProcessNameParameterSet, PSHostProcessInfoParameterSet
Aliases:

Required: False
Position: 1
Default value: None
Default value: DefaultAppDomain
Accept pipeline input: False
Accept wildcard characters: False
```

### -HostProcessInfo

Specifies a **PSHostProcessInfo** object that can be connected to with PowerShell. Use
`Get-PSHostProcessInfo` to get the object.

```yaml
Type: PSHostProcessInfo
Parameter Sets: PSHostProcessInfoParameterSet
Expand All @@ -144,8 +175,7 @@ Accept wildcard characters: False

### -Id

Specifies a process by the process ID.
To get a process ID, run the Get-Process cmdlet.
Specifies a process by the process ID. To get a process ID, run the `Get-Process` cmdlet.

```yaml
Type: Int32
Expand All @@ -161,9 +191,8 @@ Accept wildcard characters: False

### -Name

Specifies a process by the process name.
To get a process name, run the Get-Process cmdlet.
You can also get process names from the Properties dialog box of a process in Task Manager.
Specifies a process by the process name. To get a process name, run the `Get-Process` cmdlet. You
can also get process names from the Properties dialog box of a process in Task Manager.

```yaml
Type: String
Expand All @@ -179,8 +208,9 @@ Accept wildcard characters: False

### -Process

Specifies a process by the process object.
The simplest way to use this parameter is to save the results of a **Get-Process** command that returns process that you want to enter in a variable, and then specify the variable as the value of this parameter.
Specifies a process by the process object. The simplest way to use this parameter is to save the
results of a `Get-Process` command that returns process that you want to enter in a variable, and
then specify the variable as the value of this parameter.

```yaml
Type: Process
Expand All @@ -196,8 +226,7 @@ Accept wildcard characters: False

### -CustomPipeName

Gets or sets the custom named pipe name to connect to.
This is usually used in conjunction with
Gets or sets the custom named pipe name to connect to. This is usually used in conjunction with
`pwsh -CustomPipeName`.

This parameter was introduced in PowerShell 6.2.
Expand All @@ -217,8 +246,8 @@ Accept wildcard characters: False
### CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable,
-Verbose, -WarningAction, and -WarningVariable. For more information, see
-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
-WarningAction, and -WarningVariable. For more information, see
[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).

## INPUTS
Expand All @@ -229,14 +258,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable

## NOTES

* **Enter-PSHostProcess** cannot enter the process of the PowerShell session in which you are running the command. You can, however, enter the process of another PowerShell session, or a Windows PowerShell ISE session that is running at the same time as the session in which you are running **Enter-PSHostProcess**.
`Enter-PSHostProcess` cannot enter the process of the PowerShell session in which you are running
the command. You can, however, enter the process of another PowerShell session, or a PowerShell ISE
session that is running at the same time as the session in which you are running
`Enter-PSHostProcess`.

**Enter-PSHostProcess** can enter only those processes that are hosting PowerShell.
That is, they have loaded the PowerShell engine.
`Enter-PSHostProcess` can enter only those processes that are hosting PowerShell. That is, they have
loaded the PowerShell engine.

To exit a process from within the process, type exit, and then press Enter.
To exit a process from within the process, type **exit**, and then press <kbd>Enter</kbd>.

## RELATED LINKS

[Exit-PSHostProcess](Exit-PSHostProcess.md)

[Get-PSHostProcessInfo](Get-PSHostProcessInfo.md)
Loading