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.

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.

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

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