Pin using reason leads to wrong error message

[Bluejanis]

Checklist

• [X] I confirm there are no unresolved issues reported on the Chocolatey Status page.
• [X] I have verified this is the correct repository for opening this issue.
• [X] I have verified no other issues exist related to my problem.
• [X] I have verified this is not an issue for a specific package.
• [X] I have verified this issue is not security related.
• [X] I confirm I am using official, and not unofficial, or modified, Chocolatey products.

What You Are Seeing?

A single pin command must be listed. Please see the help menu for those commands

What is Expected?

Adding the pin or an error why it did nor work.

How Did You Get This To Happen?

I wanted to add a pin for a package like the documentation said:

choco pin add --name="'ums'" --version="'13.8.0'" --reason="'choco v14.0 is a beta version'"

This did not work, but showed the following error: A single pin command must be listed. Please see the help menu for those commands Well the help menu is where I got the commands from, so it was very confusing.

After some experimentaion I realized its because of the reason option. Leaving only that part out and it worked.

Back to the help page I noticed the original reason said something like "reasons available in business editions only", which I did not even read. It seemed like an example text, so why bother reading. I replaced it without thinking twice with my own text. Its probably not just an example text, but the reason the command failed I assume. So maybe that would be a good error message when using it anyways.

System Details

• Operating System: Windows 10
• Windows PowerShell version: 5.1.19041.4239
• Chocolatey CLI Version: v2.2.2
• Chocolatey Licensed Extension version: ?
• Chocolatey License type: Community
• Terminal/Emulator: PowerShell

Installed Packages

chocolatey 2.2.2
chocolatey-compatibility.extension 1.0.0
chocolatey-core.extension 1.4.0
chocolatey-dotnetfx.extension 1.0.1
chocolatey-misc-helpers.extension 0.0.4
chocolatey-visualstudio.extension 1.11.1
chocolatey-windowsupdate.extension 1.0.5
ums 13.8.0
[...]

Output Log

PS C:\WINDOWS\system32> choco pin add --name="'ums'" --version="'13.8.0'" --reason="'choco v14.0 is a beta version'" --debug --verbose
Chocolatey v2.2.2
Chocolatey is running on Windows v 10.0.19045.0
Attempting to delete file "C:/ProgramData/chocolatey/choco.exe.old".
Attempting to delete file "C:\ProgramData\chocolatey\choco.exe.old".
Command line: "C:\ProgramData\chocolatey\choco.exe" pin add --name='ums' --version='13.8.0' "--reason='choco v14.0 is a beta version'" --debug --verbose
Received arguments: pin add --name='ums' --version='13.8.0' --reason='choco v14.0 is a beta version' --debug --verbose
RemovePendingPackagesTask is now ready and waiting for PreRunMessage.
Sending message 'PreRunMessage' out if there are subscribers...
[Pending] Removing all pending packages that should not be considered installed...
Sending message 'PostRunMessage' out if there are subscribers...
Chocolatey had an error occur:
System.ApplicationException: A single pin command must be listed. Please see the help menu for those commands
   bei chocolatey.infrastructure.app.commands.ChocolateyPinCommand.ParseAdditionalArguments(IList`1 unparsedArguments, ChocolateyConfiguration configuration)
   bei chocolatey.infrastructure.app.runners.ConsoleApplication.<>c__DisplayClass0_1.<Run>b__5(IList`1 unparsedArgs)
   bei chocolatey.infrastructure.app.configuration.ConfigurationOptions.ParseArgumentsAndUpdateConfiguration(ICollection`1 args, ChocolateyConfiguration configuration, Action`1 setOptions, Action`1 afterParse, Action validateConfiguration, Action helpMessage)
   bei chocolatey.infrastructure.app.runners.ConsoleApplication.<>c__DisplayClass0_0.<Run>b__3(ICommand command)
   bei chocolatey.infrastructure.app.runners.GenericRunner.FindCommand(ChocolateyConfiguration config, Container container, Boolean isConsole, Action`1 parseArgs)
   bei chocolatey.infrastructure.app.runners.GenericRunner.Run(ChocolateyConfiguration config, Container container, Boolean isConsole, Action`1 parseArgs)
   bei chocolatey.infrastructure.app.runners.ConsoleApplication.Run(String[] args, ChocolateyConfiguration config, Container container)
   bei chocolatey.console.Program.Main(String[] args)
Exiting with 1

Additional Context

I would also suggest to add a highlight to the wrong parameter in the help page and command help.

[pauby]

Is the example text on this page? For example:

choco pin add --name="'git'" --version="'1.2.3'" --reason="'reasons available in business editions only'"

To have Chocolatey CLI ignore unavailable options, disable the ignoreInvalidOptionsSwitches feature.

[github-actions[bot]]

Is this still relevant? If so, what is blocking it? Is there anything you can do to help move it forward? This issue will be closed in 14 days if it continues to be inactive.

[tbeckenhauer]

This is still a valid issue.

[pauby]

@tbeckenhauer this issue is waiting on a response to the last comment. Without that, it will be closed.

[rose-a]

Is the example text on this page?

@pauby Yes it is. I ran into this, too.

The documentation page would certainly benefit from a note box highlighting that --reason is only available in the business edition, because something along "available in business editions only" could very well be a valid reason for pinning a package in practice. And to see that info in the Options and Switches section you need to first scroll the page and then hover and scroll the code box...

[github-actions[bot]]

Is this still relevant? If so, what is blocking it? Is there anything you can do to help move it forward? This issue will be closed in 14 days if it continues to be inactive.

[pauby]

@rose-a I feel that the documentation is adequate in that it indicates the --reason switch it available only for business editions. It indicates that in the text of the reason.

choco pin add --name="'git'" --version="'1.2.3'" --reason="'reasons available in business editions only'"

If you also look at the switch itself, further down on the page, it says:

     --reason, --pin-reason, --note=VALUE
     Pin Reason - Text information about why you are setting a pin. Available 
       in business editions. 

As the documentation is generated from the functions / cmdlets themselves, there is no simple for us to separate that out (being constrained by the comment based help functionality) at this time.

As there isn't anything we can do here, and, as I mentioned above, the original person raising the issue has not responded, I'm going to go ahead and close this. We can always open it again if needed.

[rose-a]

As the documentation is generated from the functions / cmdlets themselves, there is no simple for us to separate that out (being constrained by the comment based help functionality) at this time.

Fair enough.

[Bluejanis]

The documentation page would certainly benefit from a note box highlighting that --reason is only available in the business edition, because something along "available in business editions only" could very well be a valid reason for pinning a package in practice. And to see that info in the Options and Switches section you need to first scroll the page and then hover and scroll the code box...

Yes, 100% agree.

As the documentation is generated from the functions / cmdlets themselves, there is no simple for us to separate that out (being constrained by the comment based help functionality) at this time.

Maybe the documentation does not need to be changed, if the generated error message in the console would be more helpful?

This is the current error message, I think it is confusing, since the error is a different one:

System.ApplicationException: A single pin command must be listed. Please see the help menu for those commands

Would it be possible to change the pin cmdlet? Writing a helpful error message when using the illegal --reason switch, when not using the business license?

I only created this issue, because I stumbled on the error, when I was just testing out the function. I am obviously no expert in chocolatey, otherwise I might have known this.

[pauby]

This is the current error message, I think it is confusing, since the error is a different one:

System.ApplicationException: A single pin command must be listed. Please see the help menu for those commands

Would it be possible to change the pin cmdlet? Writing a helpful error message when using the illegal --reason switch, when not using the business license?

The open-source edition of Chocolatey CLI doesn't know about the --reason switch, as it's not available in open-source. The error message isn't specific because, in this circumstance, it can't be.

[Bluejanis]

I think it should know about the --reason switch, even if it is just to inform the user, that you can use it only with the commercial version.

[pauby]

@Bluejanis I appreciate your comments, however as I indicated above it doesn't and that is due to how Chocolatey CLI works. Making that change is breaking a significant undertaking. It's not work we plan to do.

[TheCakeIsNaOH]

The error message isn't specific because, in this circumstance, it can't be.

This is not the case for the install directory override switch, the open source version has an explicit error message that the switch is not supported in open source: https://github.com/chocolatey/choco/blob/8fc766e4e71d0be43534f0ef6720417b2c65e6de/src/chocolatey/infrastructure.app/commands/ChocolateyInstallCommand.cs#L249-L259

It should be possible to add a similar piece of code to the pin command adding an error about the --reason switch, and I don't think it would be a breaking change (certainly could be missing something though).