Powershell: Improving PS Core upgrade/acquisition from the Windows PowerShell prompt

[NickCraver]

This is a feedback/suggestion issue following some Twitter conversations about the notice presented every time a PowerShell prompt is opened on Windows. I hope this is helpful. A ton of awesome work has gone into PS Core and I'm not trying to rag on that at all. My only goal is to improve the acquisition experience for users - if we can't ship in-box then we should lower the bar as much as possible to increase adoption as much as possible.

Here's what a user sees when launching (in Windows slow/fast ring builds):

I want to call out a few specific inconsistencies and built-in assumptions of the process that follows here not as criticisms of massive effort involved, but simply advising on gaps that should get love for broader adoption and fewer user issues. Here's what a user goes through:

Current Process

1. User launches the default Windows terminal (PowerShell)
   
   
   
   • Pointing out that _it's the default_ specifically here - this is for all non-tech users that ever need to enter a command prompt for any reason.
   
   
2. "Try the new cross-platform PowerShell https://aka.ms/pscore6"
   
   
   
   • Prompt goes to Installing various versions of PowerShell (note: not specifically PS Core 6)
   
   
   • As a user, I'm likely to have immediate questions: do I need .NET Core? Makes sense I guess, it says "PowerShell Core".
   
   
   • Overall, the doc says nothing about why - what am I doing here? Is this an upgrade? Only for .NET Core and such usages, other? It only covers how to install. The user is given no context about this change.
   
   
   • This doc also has links for both legacy and PS Core versions, more confusing _unless you already know the difference_.
   
   
3. Click to Windows: "Installing PowerShell Core on Windows"
   
   
   
   • "Install the Windows Management Framework (WMF)" - This is phrased like I need to install that version for those OSes, what about others?
     
     
     
     
     
     • Proposed clarifications:
     
     
     
     • "(For Windows versions prior to Windows 10) Install the Universal C Runtime. It is available via direct download or Windows Update. Fully patched (including optional packages), supported systems will already have this installed."
     
     
     
     • "(Windows 7 and Windows Server 2008 R2 only) Install the Windows Management Framework (WMF) 4.0 or newer. For more information about WMF, see WMF Overview."
     
     
     
   
   
   • Note: We came here from the Windows terminal, why did we go through the last ("Installing various versions of PowerShell") document? It seems like we could link directly to Windows-specific instructions.
   
   
4. Go to releases: https://github.com/PowerShell/PowerShell/releases
5. User has to scroll to find what the latest stable release is in a sea of previews (that'll always be the case).
   
   
   
   • This assumes the user even knows what a stable release is. I think it's safe to assume some decent percentage of users will simply download the top/first release which may or may not be latest, stable, etc. Importantly: this page is ordered by release date only.
   
   
   • (Quick fix) IMO This should at least link to the latest release directly: https://github.com/PowerShell/PowerShell/releases/latest
     
     
     
     
     
     • ...or make it some direct aka.ms link, which would be better for automating installs and such anyway, e.g. aka.ms/pscore6-windows-latest (more below)
     
     
     
   
   
6. User needs to pick the right download.
   
   
   
   • Note: we're currently presenting a user with 23 downloads options (as of 6.2.3 - it increases to 28 in 7.x)
   
   
   • For any non-technical user, this is generally going to involve flipping back to the last page to follow the paragraph of instructions needed here on finding the right file.
   
   
7. User installs PS Core
   
   
   
   • I'm intentionally not covering that in this issue and only talking about the installer acquisition here as I think there's plenty to talk about getting users to this point
   
   

Overall Thoughts

• There isn't anything in the entire path from prompt to install that gives a user any hint as to why they're doing this. IMO, that should be solved on whatever we link them to from the terminal prompt if this is remaining there outside Windows preview releases.
• I think a general theme in this whole process/move/whatever we want to call it is that the user has context about what the heck PowerShell Core even is, and that's not a valid assumption for the vast majority of users.
• I put forth that a GitHub release download page is not a friendly solution for most Windows users and should not continue to be used as thing we point most users to if we want to increase adoption. At several points in the process we diverge from a single platform (e.g. the terminal on Windows x64) and force the user to navigate both release cadence/timeline issues and other platforms along the way (in the install docs and then again on the GitHub releases page). This can be much better with an aka.ms link going to the current latest stable download (MSI) for the platform - or a dedicated docs page explaining the why and this link to latest. That would lower the hurdle greatly.
  
  
  
  • Related: this latest stable link should probably come from a Microsoft download domain and not GitHub, as there are both confusion and corporate policy issues with installing releases from GitHub.
  
  
• Overall, it's very raw, very "core-y" and makes sense for the team and (let's be honest with ourselves) likely most of the people even finding this issue - but that's not what Windows users signed up for. It's what the team is doing and what makes sense on other platforms, but isn't standard for Windows.

Open Questions

• Will this prompt ship in the next stable Windows release, or only the preview?
  
  
  
  • If so, a user launching the default prompt for Windows has a very non-Windows experience going through the docs and GitHub to manually install the latest...what? Didn't they just upgrade Windows? Let's keep in mind how confusing that can be and tailor any messaging to accommodate that this isn't in a Windows update like many or most users would expect.
  
  
• If yes to Windows stable release prompting - can we have a way to turn it off? Environmental variable, registry tweak, something else?
• Can the latest stable be mirrored on microsoft.com behind a stable aka.ms link?
  
  
  
  • As an example, we've given the Visual Studio, .NET, and SQL teams similar feedback and now have links to latest such as:
  
  
  • VS 2019 latest: https://aka.ms/vs/16/release/vs_Professional.exe (pointed at download.visualstudio.microsoft.com)
  
  
  • I propose something like https://aka.ms/ps/latest/windows (so that the terminal text that ships more slowly need not change) and possibly https://aka.ms/ps/7/windows for specific major versions to accompany it, for handy use by those here, Chocolatey, etc. and scripting for larger environments.
  
  
  • Note: this serves as a broader use case, e.g. scripting it out...in PowerShell! As an example, the IoT section in the installation docs could shave a few steps off for devices with internet access.
  
  

Anyway - I hope we can improve the experience for all users here and hope some of this helps. I do appreciate all of the PS Core work thus far - we're using it in builds for OSS across platforms and more. It's been a huge time saver.

[iSazonov]

/cc @joeyaiello @SteveL-MSFT @sdwheeler for information

[SteveL-MSFT]

We also need to update the message to not be version specific

[doctordns]

with respect to the how it works today steps 3 to 6 - I just teach folks to download the Install-PowerShell script from GitHub.

I know there are loads of very cool one-liners to do this, But here is a more workmanlike and hopefully clearer version of what I use:

New-Item -Path C:\Foo
Set-Location -Path C:\Foo
$URI = "https://aka.ms/install-powershell.ps1"
Invoke-RestMethod -Uri $URI | 
  Out-File -FilePath C:\Foo\Install-PowerShell.ps1
C:\Foo\Install-PowerShell.ps1 -UseMSI -Quiet

For the brave, you can specify the preview or even the daily build (not for the faint-hearted).

Once downloaded, one can then just rerun it (eg to install a new daily build).

[he852100]

Suggest to add feedback link in error prompt。

[iSazonov]

We also need to update the message to not be version specific

We already use https://aka.ms/powershell

PowerShell Documentation - PowerShell

Official product documentation for PowerShell

[SteveL-MSFT]

The link in WinPS should go to a landing page helping Windows PowerShell users migrate to PowerShell 7. We'll work on this content after GA since any changes we make in WinPS won't show up to users for awhile due to Windows release cycle.