PSReadLine: PSReadLine V2 shiping in latest RS5 build breaks profiles

The latest RS5 Windows preview build(s) include an update to PSReadline. I understand this update was taken to resolve a compatability issue. Good stuff, but V2 changes how tokens are colorised.

If you set token colorisation (as I do to enable the tokens to be visible with the utterly crap projectors I get stuck with, or for accessibility easons) via $profile, this update produces the following error entering PowerShell:

Set-PSReadLineOption : A parameter cannot be found that matches parameter name 'TokenKind'.
At C:\Users\tfl.COOKHAM.000\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1:68 char:22
+ Set-PSReadlineOption -TokenKind Parameter -ForegroundColor Cyan
+                      ~~~~~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Set-PSReadLineOption], ParameterBindingException
    + FullyQualifiedErrorId : NamedParameterNotFound,Microsoft.PowerShell.SetPSReadLineOption

This can be fixed - but the documentation over on docs.microsoft.com is utterly wrong in this case. If you to docs.microsoft.com for the cmdlet, you go to: https://docs.microsoft.com/en-us/powershell/module/psreadline/Set-PSReadlineOption?view=powershell-5.1.

This page shows the old documentation for v 1.2 and makes no mention of 2.0 or the breaking change. The official documentation does not help discover the fix (and at the point of writing, blogsphere has not commented on this).

tl;dr - an OS upgrade breaks profiles and the fix is hard to discover.

This is not so much an issue today (although a fix would be nice), but is going to be one in the autumn as RS5 rolls out.

This is the first time I can recall where a RS version update takes a new base PowerShell module that contains a breaking (albeit minor) issue - code that worked is now not working purely due to the OS upgrade. There seems to be no mechanism to document different versions of the cmdlet on docs.microsoft.com (unrelated to different PowerShell versions.

I am not clear on an obvious solution but there are at least options.

Have the page on docs.microsoft.com specifically call out the two versions of the cmdlet and explain the change. Also have some examples showing how to update the profile to resolve the error message.
Create a way of versioning modules/cmdlets within a version of PowerShell on the docs.microsoft.com platform. That way I could look at PowerShell 5.1 help then seach for details of the PSReadline v2 module. That would be some dev work for the docs team and i suspect not high enough priority to get it in place before RS5 builds hit the slow lane. It still might be a nice idea for the future.

Environment data

PS version: 5.1.17728.1000 PSReadline version: 2.0.0-beta2 os: 10.0.17728.1000 (WinBuild.160101.0800) PS file version: 10.0.17728.1000 (WinBuild.160101.0800)

Steps to reproduce or exception report

Take a Windows 10 system, using RS4 and Setup a user profile with the line:

Set-PSReadlineOption -TokenKind Parameter -ForegroundColor Cyan

Upgrade the computer to 17728.1000 (or probably later) (ie RS5 preview).
Logon as the same user that did step 1, run PowerShell and observe the earlier error.
Google/Bing for Set-PSReadLine and notice the URLs. They point to the page that shows the -TokenKind parameter does exist as noted above.

About this issue

Original URL
State: closed
Created 6 years ago
Comments: 19 (4 by maintainers)

Commits related to this issue

Adding others tokens using the -Colors to avoid error after update Windows the issue is documented https://github.com/lzybkr/PSReadLine/issues/738 — committed to ViniciusSouza/poshfiles by ViniciusSouza 5 years ago

Most upvoted comments

@lzybkr I know this repo has the up to date stuff for PSReadline. But really - should IT pros need to hunt down documentation in GitHub for standard windows modules? WHY isn’t this change reflected in Docs.Microsoft.Com. These days - IT Pros wanting to know why their previously working scripts now break are going to use their search engine and this is likely to point to docs.microsoft.com. Doing so points to a version of PSReadLIne that is innacruate for 1809. I totally agree that the new version is an improvement and am all for it being incorporated. But the discovery is poor and the fact that the upgrade to 1809 breaks scripts that work should be documented but wasn’t. Microsoft as a whole could do better here. IMHO.

doctordns on Oct 7, 2018

First - I suspect that this is not the last we’ll hear of this issue. The 1809 version of Windows ships with a new version of PSReadline. This is NOT documented as the breaking change it can be (it broke all my labs and lab setup). This could have been handled better, but no one seems to care much when this issue was first raised. I attempted to get a change made, but the PSReadLine folks did not show any interest - it was the OS team’s issue. ANYWAY,

This is easy to fix. You call the NEW Set-PSReadLineOption with a hash table of colours to change, like this:

Set-PSReadLineOption -Colors @{Comment = "Green";Error='yellow'}

You can use the Get-PSReadLIneOption cmdlet to return the current settings. The hash table key is the name of the colour shown, minus the text ‘color’. So Type=‘colour’ to set the TypeColor, or Nummber='color; to set the colour for numbers.

A rather poor, non-obvious and hard to discover implementation but such is life.

doctordns on Oct 6, 2018

The docs in this repo are always current - see here.

Set-PSReadlineOption -ResetTokenColors is no longer easy - you’ll have to implement it yourself by calling Get-PSReadLineOption first and saving the properties you want to restore.

lzybkr on Oct 5, 2018

I’m sorry to add comment here, but I want a help about changing and resetting the token color in PSReadLine 2, I notice that in this issue, the error is related to tokenbind.

Here is the code I use in PSReadLine 1:

$options = Get-PSReadlineOption

# Token Foreground                                # base16 colors
$options.CommandForegroundColor   = "DarkBlue"    # base0D
$options.CommentForegroundColor   = "Yellow"      # base03
$options.KeywordForegroundColor   = "DarkMagenta" # base0E
$options.MemberForegroundColor    = "DarkBlue"    # base0D
$options.NumberForegroundColor    = "Red"         # base09
$options.OperatorForegroundColor  = "DarkCyan"    # base0C
$options.ParameterForegroundColor = "Red"         # base09
$options.StringForegroundColor    = "DarkGreen"   # base0B
$options.TypeForegroundColor      = "DarkYellow"  # base0A
$options.VariableForegroundColor  = "DarkRed"     # base08

And reset:

# Reset
Set-PSReadlineOption -ResetTokenColors

How can I improve it to be compatible with PSReadLine 2? The doc is not updated yet, and I can’t find example code. Thanks!

chawyehsu on Oct 5, 2018

It would be a really nice gesture if the error message said “we changed the syntax” rather than “you used the wrong syntax”, and also if it could point out more clearly the precise change and the proper workaround.

I know Microsoft can’t learn from others, but the way some popular platforms do this is they issue a warning in the first roll-out and give people a couple of releases before the breaking change is finally rolled out.

tripleee on Nov 27, 2019

Glad it works. As for your concern, If you use a cmdlet and use incorrect syntax, you get errors. If you use the V1.x syntax of PSReadLine, under 1809 it WILL fail. You can only fix that by uninstalling the newer module and finding and installing the old one.

My analogy is using a horse whip on a horseless carriage. It has no effect since cars and horses are different objects. You are using a new version of PSReadline that has a different syntax. You COULD create your own function (set-mypsreadlineoption) that allows you to use the old syntax and converts it to the new syntax. Personally, I just updated my scripts and moved on.

doctordns on Oct 14, 2018

@Whale-fall I’ve written a blog article: see https://tfl09.blogspot.com/2018/08/psreadline-v2-can-break-powershell.html

doctordns on Oct 8, 2018