Improve "Administrator rights are required..." error message

[philosophicles]

Summary of the new feature / enhancement

Context

There are various situations in which Install-Module gives this error message:

Install-Package: Administrator rights are required to install or update. Log on to the computer with an account that has Administrator rights, and then try again, or install by adding "-Scope CurrentUser" to your command. You can also try running the Windows PowerShell session with elevated rights (Run As Administrator).

In some cases the error has specific folder paths included, affecting these parts:

...are required to install modules in 'C:\Program Files\PowerShell\Modules'. Log on...

...and then try again, or install 'C:\Users\my.username\Some\Path\To\Documents\Powershell\Modules' by adding...

Problem with this error message

I imagine this message was written for PowerShellGet v1. It was appropriate then. However, PowerShellGet v2 changed the default -Scope parameter value from AllUsers to CurrentUser as noted here and elsewhere.

This means that an instruction to "add -Scope CurrentUser" is never really appropriate any more. Depending on the current state when the error occurred, it may be appropriate to remove -Scope AllUsers from the command, or to switch to an elevated shell and add -Scope AllUsers.

In any context, mentioning "add -Scope CurrentUser" is confusing or misleading for users, who might incorrectly infer from this that the default is AllUsers.

Secondary problems/critique

1. I think the target folder path should always be included in the error message.
2. I think "Run As Administrator" will be far more commonly appropriate as a way to get elevated privileges, than logging onto the computer with a different user account. Emphasis of these two options should be switched - more normal one mentioned first.
3. Is the phrase "the Windows PowerShell session" OK here? This is equally (or more) likely to be PowerShell Core.
4. There are other things it might be worth mentioning in this message: (1) checking if Windows' Controlled Folder Access (Ransomware Protection) is interfering with the installation (2) Checking if OneDrive sync is interfering. (For examples see this issue or this issue. I think perhaps many other people report this error message and one of these two things is to blame, but the issue is never fully resolved for them so it's hard to find them via search. Example: I'm personally quite sure this error report will have been caused by Controlled Folder Access.)

Proposed technical implementation details (optional)

I would suggest messages along the following lines, depending on effective installation scope when error is raised.

If effective scope is AllUsers

Install-Module: Administrator rights are required to install modules for all users in 'C:\Program Files\PowerShell\Modules'. Either reopen PowerShell using 'Run As Administrator', or log on to the computer with an account that has Administrator rights, then run this command again. Alternatively, install this module for the current user only by omitting the -Scope parameter.

A variation on this might be needed for situations when the user requested an update to an existing package, in which case the final sentence is probably inappropriate.

Otherwise

If we're here, the scope is CurrentUser, either explicitly or implicitly.

Install-Module: unable to install this module in 'C:\Users\my.username\Some\Path\To\Documents\Powershell\Modules'. Check you have rights to edit files and folders at this location. In some cases, Windows Controlled Folder Access may have blocked the action, or another application such as Microsoft OneDrive may be interfering with folder access. Alternatively, try installing the module for all users by adding "-Scope AllUsers" to your command and running it in a PowerShell session with Administrator rights.

I don't think this message needs to spell out exactly how to get a PowerShell session with Admin rights. If the user doesn't achieve that before running with -Scope AllUsers then they'll see the other message format that gives better information on how to achieve an elevated shell.

[SydneyhSmith]

Thanks @philosophicles really appreciate the detailed issue-- lots of good points made! We are going to add this to our v3 project as reference for validating our scoping error messages going forward

[NeighborGeek]

Thanks @philosophicles, your detailed description here was spot on when I ran into the issue today, and allowed me to work around it. Controlled Folder Access was blocking the module install for the CurrentUser scope, and I was able to allow the activity from the protection history entry in Windows Security. For some reason, I was also getting the error when trying to install in AllUsers Scope, though in that case CFA was not blocking access to the path, so I'm not sure why it errored. Regardless, thanks to your post here I did get the module installed for myself and can get back to what I was working on.