Convert PowerShell Functions to C# CmdLets

[gep13]

Checklist

• I have verified this is the correct repository for opening this issue.
• I have verified no other issues exist related to my request.

Is Your Feature Request Related To A Problem? Please describe.

Within the Chocolatey Licensed Extension, we extend the functionality that is provided by some of the Chocolatey PowerShell functions, for example for the Package Throttle feature, which means changing how the Get-WebFile function works.

Extending this functionality can be problematic as it deals with switching between PowerShell and C#, and there are no direct entry points to provide this additional functionality.

Describe The Solution. Why is it needed?

We should convert all the Chocolatey PowerShell Functions, i.e. the Install-ChocolateyPath.ps1 to be a C# CmdLets.

This will allow for better inheritance/overloading of Chocolatey functionality within things like the Chocolatey Licensed Extension, as well as providing the necessary entry points to extend the functionality as/when required.

In addition, this will prevent duplication of code between Chocolatey CLI and CLE.

Additional Context

N/A

Related Issues

• Ensure Install-ChocolateyPath adds a new entry to the PATH when part of it is already there #3318
• Helper cmdlet documentation updates for CLI v3.0 docs#1074

Tasks

Beta Give feedback

1. Amend contributing documentation with a guide on how we write C# Cmdlets for PowerShell #3539
   0 - Backlog Documentation +2
2. Format-FileSize.ps1
3. Get-CheckSumValid.ps1 - (#3477) Replace Get-ChecksumValid with Assert-ValidChecksum cmdlet. #3525
4. Get-ChocolateyConfigValue.ps1
5. Get-ChocolateyPath.ps1
6. Get-ChocolateyUnzip.ps1
7. Get-ChocolateyWebFile.ps1
8. Get-EnvironmentVariable.ps1
9. Get-EnvironmentVariableNames.ps1
10. Get-FtpFile.ps1
11. Get-OSArchitectureWidth.ps1
12. Get-PackageParameters.ps1
13. Get-ToolsLocation.ps1
14. Get-UACEnabled.ps1
15. Get-UninstallRegistryKey.ps1
16. Get-VirusCheckValid.ps1
17. Get-WebFile.ps1
18. Get-WebFileName.ps1
19. Install-BinFile.ps1
20. Install-ChocolateyEnvironmentVariable.ps1
21. Install-ChocolateyExplorerMenuItem.ps1
22. Install-ChocolateyFileAssociation.ps1
23. Install-ChocolateyInstallPackage.ps1
24. Install-ChocolateyPackage.ps1
25. Install-ChocolateyPath.ps1
26. Install-ChocolateyPinnedTaskBarItem.ps1
27. Install-ChocolateyPowerShellCommand.ps1
28. Install-ChocolateyShortcut.ps1
29. Install-ChocolateyVsixPackage.ps1
30. Install-Vsix.ps1
31. Set-EnvironmentVariable.ps1
32. Set-PowerShellExitCode.ps1
33. Start-ChocolateyProcessAsAdmin.ps1
34. Test-ProcessAdminRights.ps1
35. Uninstall-BinFile.ps1
36. Uninstall-ChocolateyEnvironmentVariable.ps1
37. Uninstall-ChocolateyPackage.ps1
38. Uninstall-ChocolateyZipPackage.ps1
39. Update-SessionEnvironment.ps1
40. Write-FunctionaCallLogMessage.ps1
41. Before next release: ensure all associated docs PRs (Helper cmdlet documentation updates for CLI v3.0 docs#1074) are merged
42. Before next release: ensure we update the Chocolatey.PowerShell.dll-help.xml external help file in this repository after the docs PRs are merged

[gep13]

Some of the above work was completed in the 2.3.0 release of Chocolatey CLI, where we introduced the concept of the Uninstall-ChocolateyPath CmdLet. At the time, it made sense to convert the Install-ChocolateyPath Function from PowerShell to a C# CmdLet, so that there was consistency in how they operated. It also gave us the opportunity to test/validate that everything worked as expected within the Chocolatey Licensed Extension, when changing the dependency to use 2.3.0 of CLI.

[gep13]

I have marked this issue as a Breaking Change, as it does have the potential to have an impact on how some other systems work with Chocolatey CLI.

[vexx32]

@gep13 since it's been agreed this will be a breaking change, should we put this in the 3.0 milestone?

[vexx32]

Before this issue is closed out completely, we should look to update the Chocolatey.PowerShell.dll-help.xml file in the repository here. And for that to be done, we will need to merge the draft PRs in the docs repository.

I'll add an entry to the task list here to track this as well.

[vexx32]

Additionally, I'm checking off Write-FunctionCallLogMessage for two reasons: first, it is one of the "internal use only" commands that was never meant to be part of the public API, as documented in its help information; second, it has already been incorporated into the ChocolateyCmdlet functionality and embedded into the BeginProcessing() override method defined on that base cmdlet.