PSReadLine V2 shiping in latest RS5 build breaks profiles

[doctordns]

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.

1. 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.
2. 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

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

Set-PSReadlineOption -TokenKind Parameter -ForegroundColor Cyan

2. Upgrade the computer to 17728.1000 (or probably later) (ie RS5 preview).

3. Logon as the same user that did step 1, run PowerShell and observe the earlier error.

4. Google/Bing for Set-PSReadLine and notice the URLs. They point to the page that shows the -TokenKind parameter does exist as noted above.

[lzybkr]

The breaking change is noted in the release notes here. That file is apparently not included in RS5, but is included in the version I publish to the gallery, see here.

Some form of breaking change was necessary to support VT escape sequences when specifying colors. Escape sequences provide much better support for accessibility - you have access to 24 bit colors instead of the 16 colors previously supported.

Based on some analysis of profiles on GitHub, I deemed the breaking change fairly low impact with an easy fix after discovering the change. I have no plans to support the V1 way.

Note that a (again, very minor) breaking change is a good thing in that it should point people to the improved color support which they presumably want because they are using the non-default options.

[doctordns]

I have no problems with the changes. But my system was updated by the last RS5 preview broke my $profile and Google was little help as it pointed to the old version. The OS upgrade made no mention. As a user, I should not have to chase up source repos to find this stuff. This is sloppy IMHO.

ALSO, the docs at docs.Microsoft.com are not up to date.

[lzybkr]

I'm sorry about breaking your profile and I'm sorry it was harder to discover the fix than you expected.

Naturally it takes time for changes like this to be sufficiently documented and for search engines to rank the newer documentation more highly, such is the life of an early adopter.

Hopefully the offline help (Get-Help Set-PSReadLineOption) is sufficient, but I'm not sure if that was updated for RS5 (again my published version has useful help on the change).

I don't have any control over what goes into RS5 or how docs are updated. From my point of view, I'm not sure what else I could have done.

[doctordns]

Don't worry about my profile. I can fix it. And I did. And I like the new functionality/

The point I have been trying to make is that there is an issue for those of us who upgrade to later versions of Win10. I am in the vanguard and found this issue early. There is loads of time to 'fix' it before RS5 hits the streets. I

This is a breaking issue. It breaks profiles that adjust PSreadline. It is not documented in the OS release notes. Yes, it is documented in the modules repo, but as an IT Pro, should I really need to search out repos before upgrading?

So there is work to be done here. PSreadline 2.0 is great and I am pleased with the improvements. The upgrade, however, WAS a surprise. And again, I am NOT blaming the PSReadlIne folks - this is a complex issue around how Win10 takes new versions of modules that are not backward compatible. The doc strategy, in this case, is sub-optimal.

So maybe the PSReadline team (ie you) could not have done more, MSFT as a whole can. I had hoped that by reporting this we could find a solution. It looks like I was wrong. My apologies for wasting your time.

[chawyehsu]

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!

[lzybkr]

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.

[doctordns]

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]

@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.

[Whale-fall]

Don't worry about my profile. I can fix it. And I did. And I like the new functionality/

The point I have been trying to make is that there is an issue for those of us who upgrade to later versions of Win10. I am in the vanguard and found this issue early. There is loads of time to 'fix' it before RS5 hits the streets. I

This is a breaking issue. It breaks profiles that adjust PSreadline. It is not documented in the OS release notes. Yes, it is documented in the modules repo, but as an IT Pro, should I really need to search out repos before upgrading?

So there is work to be done here. PSreadline 2.0 is great and I am pleased with the improvements. The upgrade, however, WAS a surprise. And again, I am NOT blaming the PSReadlIne folks - this is a complex issue around how Win10 takes new versions of modules that are not backward compatible. The doc strategy, in this case, is sub-optimal.

So maybe the PSReadline team (ie you) could not have done more, MSFT as a whole can. I had hoped that by reporting this we could find a solution. It looks like I was wrong. My apologies for wasting your time.

i am sorry to comment here but i really need a help to fix my profile.what can i do to deal with the issue as you point.

[lzybkr]

@Whale-fall - Did you see the examples in the docs in this repo or this comment?

[doctordns]

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

[Whale-fall]

Thank you all and it really did work!
However, I will still be bothered when I type this command as Set-PSReadlineOption -TokenKind Parameter -ForegroundColor Cyan. Hope you guys can fix it.