Skip to content

Fixes #10346 - Document new TerminateOrphanedConsoleApps switch #10355

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 3 commits into from
Aug 21, 2023
Merged

Fixes #10346 - Document new TerminateOrphanedConsoleApps switch #10355

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b4122c0
Document new TerminateOrphanedConsoleApps switch
sdwheeler Aug 20, 2023
506c19c
Apply suggestions from code review
sdwheeler Aug 21, 2023
c632cba
Feedback changes
sdwheeler Aug 21, 2023
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
24 changes: 16 additions & 8 deletions reference/7.4/PSReadLine/Get-PSReadLineOption.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
external help file: Microsoft.PowerShell.PSReadLine2.dll-Help.xml
Locale: en-US
Module Name: PSReadLine
ms.date: 12/13/2022
ms.date: 08/20/2023
online version: https://learn.microsoft.com/powershell/module/psreadline/get-psreadlineoption?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Get-PSReadLineOption
Expand Down Expand Up @@ -46,33 +46,41 @@ HistorySearchCursorMovesToEnd : False
MaximumHistoryCount : 4096
ContinuationPrompt : >>
ExtraPromptLineCount : 0
PromptText : {> }
PromptText : >
BellStyle : Audible
DingDuration : 50
DingTone : 1221
CommandsToValidateScriptBlockArguments : {ForEach-Object, %, Invoke-Command, icm...}
CommandsToValidateScriptBlockArguments : {ForEach-Object, %, Invoke-Command, icm…}
CommandValidationHandler :
CompletionQueryItems : 100
MaximumKillRingCount : 10
ShowToolTips : True
ViModeIndicator : None
WordDelimiters : ;:,.[]{}()/\|^&*-=+'"---
WordDelimiters : ;:,.[]{}()/\|!?^&*-=+'"–—―
AnsiEscapeTimeout : 100
PredictionSource : HistoryAndPlugin
PredictionViewStyle : InlineView
TerminateOrphanedConsoleApps : False
CommandColor : "`e[93m"
CommentColor : "`e[32m"
ContinuationPromptColor : "`e[97m"
DefaultTokenColor : "`e[97m"
ContinuationPromptColor : "`e[37m"
DefaultTokenColor : "`e[37m"
EmphasisColor : "`e[96m"
ErrorColor : "`e[91m"
InlinePredictionColor : "`e[97;2;3m"
KeywordColor : "`e[92m"
MemberColor : "`e[97m"
ListPredictionColor : "`e[33m"
ListPredictionSelectedColor : "`e[48;5;238m"
ListPredictionTooltipColor : "`e[97;2;3m"
MemberColor : "`e[37m"
NumberColor : "`e[97m"
OperatorColor : "`e[90m"
ParameterColor : "`e[90m"
SelectionColor : "`e[30;107m"
SelectionColor : "`e[30;47m"
StringColor : "`e[36m"
TypeColor : "`e[37m"
VariableColor : "`e[92m"

```

This command returns the list of available PSReadLine options and their current values.
Expand Down
54 changes: 42 additions & 12 deletions reference/7.4/PSReadLine/Set-PSReadLineOption.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
external help file: Microsoft.PowerShell.PSReadLine2.dll-Help.xml
Locale: en-US
Module Name: PSReadLine
ms.date: 07/19/2023
ms.date: 08/20/2023
online version: https://learn.microsoft.com/powershell/module/psreadline/set-psreadlineoption?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Set-PSReadLineOption
Expand All @@ -25,7 +25,8 @@ Set-PSReadLineOption [-EditMode <EditMode>] [-ContinuationPrompt <String>] [-His
[-HistorySearchCaseSensitive] [-HistorySaveStyle <HistorySaveStyle>] [-HistorySavePath <String>]
[-AnsiEscapeTimeout <Int32>] [-PromptText <String[]>] [-ViModeIndicator <ViModeStyle>]
[-ViModeChangeHandler <ScriptBlock>] [-PredictionSource <PredictionSource>]
[-PredictionViewStyle <PredictionViewStyle>] [-Colors <Hashtable>] [<CommonParameters>]
[-PredictionViewStyle <PredictionViewStyle>] [-Colors <Hashtable>] [-TerminateOrphanedConsoleApps]
[<CommonParameters>]
```

## DESCRIPTION
Expand Down Expand Up @@ -208,8 +209,8 @@ Specifies a **ScriptBlock** that controls which commands get added to **PSReadLi

The **ScriptBlock** receives the command line as input.

The **ScripBlock** should return a member of the **AddToHistoryOption** enum, the string name of
one of those members, or a boolean value. The list below describes the possible values and their
The **ScripBlock** should return a member of the **AddToHistoryOption** enum, the string name of one
of those members, or a boolean value. The list below describes the possible values and their
effects.

- `MemoryAndFile` - Add the command to the history file and the current session.
Expand All @@ -236,8 +237,8 @@ This option is specific to Windows when input is redirected, for example, when r
or `screen`.

With redirected input on Windows, many keys are sent as a sequence of characters starting with the
escape character. It's impossible to distinguish between a single escape character followed by
more characters and a valid escape sequence.
escape character. It's impossible to distinguish between a single escape character followed by more
characters and a valid escape sequence.

The assumption is that the terminal can send the characters faster than a user types. **PSReadLine**
waits for this timeout before concluding that it has received a complete escape sequence.
Expand Down Expand Up @@ -283,7 +284,8 @@ Accept wildcard characters: False
The **Colors** parameter specifies various colors used by **PSReadLine**.

The argument is a hash table where the keys specify which element and the values specify the color.
For more information, see [about_Hash_Tables](/powershell/module/microsoft.powershell.core/about/about_hash_tables).
For more information, see
[about_Hash_Tables](/powershell/module/microsoft.powershell.core/about/about_hash_tables).

Colors can be either a value from **ConsoleColor**, for example `[ConsoleColor]::Red`, or a valid
ANSI escape sequence. Valid escape sequences depend on your terminal. In PowerShell 5.0, an example
Expand All @@ -302,7 +304,8 @@ Two color settings were added to support customization of the `ListView` in PSRe
- Foreground, background, or both
- Inverse, bold

For more information about ANSI color codes, see [ANSI escape code](https://wikipedia.org/wiki/ANSI_escape_code#Colors_) in Wikipedia.
For more information about ANSI color codes, see the Wikipedia article
[ANSI escape code](https://wikipedia.org/wiki/ANSI_escape_code#Colors_).

The valid keys include:

Expand Down Expand Up @@ -727,10 +730,9 @@ When displaying possible completions, tooltips are shown in the list of completi
This option is enabled by default. This option wasn't enabled by default in prior versions of
**PSReadLine**. To disable, set this option to `$False`.

By default, the **ShowToolTips** property of the global **PSConsoleReadLineOptions**
object is set to `True`. Using this **SwitchParameter** sets the property value to `True`. To change
the property value, you must specify the value of the **SwitchParameter** as follows:
`-ShowToolTips:$False`.
By default, the **ShowToolTips** property of the global **PSConsoleReadLineOptions** object is set
to `True`. Using this **SwitchParameter** sets the property value to `True`. To change the property
value, you must specify the value of the **SwitchParameter** as follows: `-ShowToolTips:$False`.

Using the following command, you can set the property value directly:

Expand All @@ -748,6 +750,34 @@ Accept pipeline input: False
Accept wildcard characters: False
```

### -TerminateOrphanedConsoleApps

This parameter sets the **TerminateOrphanedConsoleApps** option to `$true`.

On Windows, when you press <kbd>Ctrl</kbd>+<kbd>c</kbd> to terminate a process, each process
attached to a console receives a terminate signal, as opposed to just the active shell. Sometimes,
when a shell has launched some large tree of child processes, (imagine a build system, for example)
some processes may exit, leaving multiple processes concurrently trying to consume console input.

When setting the **TerminateOrphanedConsoleApps** option to `$true`, PSReadLine records the list of
processes that are currently attached to the console. Afterwards, whenever PSReadLine runs, it will
get a new list of processes attached to the console, and terminate those that aren't in the original
list.

This parameter and option were added in PSReadLine 2.3.2-beta2.

```yaml
Type: System.Management.Automation.SwitchParameter
Parameter Sets: (All)
Aliases:

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

### -ViModeChangeHandler

When the **ViModeIndicator** is set to `Script`, the script block provided will be invoked every
Expand Down