Convert PowerShell Functions to C# CmdLets

gep13 commented 4 months ago

Checklist

[X] I have verified this is the correct repository for opening this issue.
[X] 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

https://github.com/chocolatey/choco/issues/3318
https://github.com/chocolatey/docs/issues/1074
```
### Tasks
```
[ ] #3539
[ ] Format-FileSize.ps1
[ ] Get-CheckSumValid.ps1 - https://github.com/chocolatey/choco/pull/3525
[ ] Get-ChocolateyConfigValue.ps1
[ ] Get-ChocolateyPath.ps1
[ ] Get-ChocolateyUnzip.ps1
[ ] Get-ChocolateyWebFile.ps1
[x] Get-EnvironmentVariable.ps1
[x] Get-EnvironmentVariableNames.ps1
[ ] Get-FtpFile.ps1
[ ] Get-OSArchitectureWidth.ps1
[ ] Get-PackageParameters.ps1
[ ] Get-ToolsLocation.ps1
[ ] Get-UACEnabled.ps1
[ ] Get-UninstallRegistryKey.ps1
[ ] Get-VirusCheckValid.ps1
[ ] Get-WebFile.ps1
[ ] Get-WebFileName.ps1
[ ] Install-BinFile.ps1
[ ] Install-ChocolateyEnvironmentVariable.ps1
[ ] Install-ChocolateyExplorerMenuItem.ps1
[ ] Install-ChocolateyFileAssociation.ps1
[ ] Install-ChocolateyInstallPackage.ps1
[ ] Install-ChocolateyPackage.ps1
[x] Install-ChocolateyPath.ps1
[ ] Install-ChocolateyPinnedTaskBarItem.ps1
[ ] Install-ChocolateyPowerShellCommand.ps1
[ ] Install-ChocolateyShortcut.ps1
[ ] Install-ChocolateyVsixPackage.ps1
[ ] Install-Vsix.ps1
[x] Set-EnvironmentVariable.ps1
[ ] Set-PowerShellExitCode.ps1
[ ] Start-ChocolateyProcessAsAdmin.ps1
[x] Test-ProcessAdminRights.ps1
[ ] Uninstall-BinFile.ps1
[ ] Uninstall-ChocolateyEnvironmentVariable.ps1
[ ] Uninstall-ChocolateyPackage.ps1
[ ] Uninstall-ChocolateyZipPackage.ps1
[x] Update-SessionEnvironment.ps1
[x] Write-FunctionaCallLogMessage.ps1
[ ] Before next release: ensure all associated docs PRs (https://github.com/chocolatey/docs/issues/1074) are merged
[ ] 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 commented 4 months ago

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 commented 4 months ago

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 commented 1 month ago

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

vexx32 commented 1 month ago

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 commented 1 month ago

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.

chocolatey / choco