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

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

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

3. 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:

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

[doctordns]

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.

[tripleee]

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.

[msftrncs]

The error message is created by PowerShell, and so PSReadLine (or any cmdlet author) cannot control the error message, with out practically providing the backwards support for the obsolete syntax. That is a lot of extra work, with little gain, that is usually duplicated by documentation.

One of the reasons this particular thread (among others) has affected people so much, is the fact that a non-stable-released utility is being distributed with released software, making it difficult for online documentation to keep up, since its geared towards stable-release versions.

This is where PowerShell's offline help comes in so importantly. It was delivered with the non-stable-released utility, so no online help was needed, but in todays age, everyone just turns to online help instead of offline.

Also to be mentioned, PowerShell is specifically responsible for the discoverability of every cmdlets's options, through the afore mentioned offline help, and also, via functions that PSReadLine compliments, such as tab completion menu. It however, is the responsibility of cmdlet authors to implement their cmdlets in a manner compatible with this self-discovery, and that is technically a requirement in order to be called a cmdlet.

[doctordns]

A wild idea, but could the experimental feature PSCommandNotFoundSuggestion be updated to provide some further clues. Right now, if a cmdlet is not found, that EF can provide suggestions. Could that be excended to look at errors in the Set-PSReadLineOption and catch the error that occurs when the old syntax is used generating a specific error, and then offering a pointer to the new syntax.

[msftrncs]

That's a possibility, but it would be up to https://github.com/PowerShell/PowerShell. The current feature is implemented using heuristics, and those heuristics would probably work as well for both parameter names and parameter values.

[Dustii77]

Newbie PowerShell user reporting. It's frustrating when both Microsoft's docs page and the Set-PSReadLineOption get-help documentation are giving incorrect information. I really need to go to a GitHub comment section for answers to this problem? (Thanks @doctordns). This issue was brought up in 2018 for crying out loud.

[doctordns]

This has been an issue ever since PSReadLIne was first adopted. PSReadline is a great solution but the integration with the rest of PowerShell is frankly poor and the result is a mess that many users trip over.

I have raised issues on this - but no one seems to want to resolve the issue - both the PSReadline and PowerShell teams point to the other it seems. FWIW: You are not the only person to hit this, and until the issue is properly resolved, you will not be the last.

A properly implemented and well-documented solution is desirable.