Skip to content

Latest commit

 

History

History
141 lines (88 loc) · 9.62 KB

HelpersReference.md

File metadata and controls

141 lines (88 loc) · 9.62 KB
Raw

Chocolatey Package Functions aka Helpers Reference

Main Functions

These functions call other functions and many times may be the only thing you need in your [[chocolateyInstall.ps1 file|ChocolateyInstallPS1]].

  • [[Install-ChocolateyPackage|HelpersInstallChocolateyPackage]]
  • [[Install-ChocolateyZipPackage|HelpersInstallChocolateyZipPackage]]
  • [[Install-ChocolateyPowershellCommand|HelpersInstallChocolateyPowershellCommand]]
  • [[Install-ChocolateyVsixPackage|HelpersInstallChocolateyVsixPackage]]

Error / Success Functions

  • [[Write-ChocolateySuccess|HelpersWriteChocolateySuccess]] - DEPRECATED
  • [[Write-ChocolateyFailure|HelpersWriteChocolateyFailure]] - DEPRECATED

You really don't need a try catch with chocolatey powershell files anymore.

More Functions

Administrative Access Functions

When creating packages that need to run one of the following commands below, one should add the tag admin to the nuspec.

  • [[Install-ChocolateyPackage|HelpersInstallChocolateyPackage]]
  • [[Start-ChocolateyProcessAsAdmin|HelpersStartChocolateyProcessAsAdmin]]
  • [[Install-ChocolateyInstallPackage|HelpersInstallChocolateyInstallPackage]]
  • [[Install-ChocolateyPath|HelpersInstallChocolateyPath]] - when specifying machine path
  • [[Install-ChocolateyEnvironmentVariable|HelpersInstallChocolateyEnvironmentVariable]] - when specifying machine path
  • [[Install-ChocolateyExplorerMenuItem|HelpersInstallChocolateyExplorerMenuItem]]
  • [[Install-ChocolateyFileAssociation|HelpersInstallChocolateyFileAssociation]]

Non-Administrator Safe Functions

Some folks expressed a desire to have Chocolatey not run as administrator to reach continuous integration and developers that are not administrators on their machines.

These are the functions from above as one list.

  • [[Install-ChocolateyZipPackage|HelpersInstallChocolateyZipPackage]]
  • [[Install-ChocolateyPowershellCommand|HelpersInstallChocolateyPowershellCommand]]
  • [[Write-ChocolateySuccess|HelpersWriteChocolateySuccess]]
  • [[Write-ChocolateyFailure|HelpersWriteChocolateyFailure]]
  • [[Get-ChocolateyWebFile|HelpersGetChocolateyWebFile]]
  • [[Get-ChocolateyUnzip|HelpersGetChocolateyUnzip]]
  • [[Install-ChocolateyPath|HelpersInstallChocolateyPath]] - when specifying user path
  • [[Install-ChocolateyEnvironmentVariable|HelpersInstallChocolateyEnvironmentVariable]] - when specifying user path
  • [[Install-ChocolateyDesktopLink|HelpersInstallChocolateyDesktopLink]] - DEPRECATED - see [[Install-ChocolateyShortcut|HelpersInstallChocolateyShortcut]]
  • [[Install-ChocolateyPinnedTaskBarItem|HelpersInstallChocolateyPinnedTaskBarItem]]
  • [[Install-ChocolateyShortcut|HelpersInstallChocolateyShortcut]] - v0.9.9+
  • [[Update-SessionEnvironment|HelpersUpdateSessionEnvironment]]

Complete List (alphabetical order)

  • Get-BinRoot [src] - this is a horribly named function that doesn't do what new folks think it does. It gets you the tools root folder, which by default is set to c:\tools, not the $env:ChocolateyInstall\bin folder.

  • Get-CheckSumValid [src]

  • Get-ChocolateyUnzip [src]

  • Get-ChocolateyWebFile [src]

  • Get-EnvironmentVariable [src]

  • Get-EnvironmentVariableNames [src]

  • Get-FtpFile [src]

  • Get-ProcessorBits [src]

  • Get-UACEnabled [src]

  • Get-VirusCheckValid [src] :warning: not implemented!

  • Get-WebFile [src]

  • Get-WebHeaders [src]

  • Install-ChocolateyDesktopLink [src]

  • Install-ChocolateyEnvironmentVariable [src]

  • Install-ChocolateyExplorerMenuItem [src]

  • Install-ChocolateyFileAssociation [src]

  • Install-ChocolateyInstallPackage [src]

  • Install-ChocolateyPackage [src]

  • Install-ChocolateyPath [src]

  • Install-ChocolateyPinnedTaskBarItem [src]

  • Install-ChocolateyPowershellCommand [src]

  • Install-ChocolateyShortcut [src]

  • Install-ChocolateyVsixPackage [src]

  • Install-ChocolateyZipPackage [src]

  • Set-EnvironmentVariable [src]

  • Start-ChocolateyProcessAsAdmin [src]

  • Test-ProcessAdminRights [src]

  • Uninstall-ChocolateyPackage [src]

  • Uninstall-ChocolateyZipPackage [src]

  • Update-SessionEnvironment [src]

  • Write-ChocolateyFailure [src]

  • Write-ChocolateySuccess [src]

  • Write-FileUpdateLog [src]

Variables

There are also a number of environment variables providing access to some values from the nuspec and other information that may be useful. They are accessed via $env:variableName.

  • chocolateyPackageFolder = the folder where Chocolatey has downloaded and extracted the NuGet package, typically C:\ProgramData\chocolatey\lib\packageName.
  • chocolateyPackageName (since 0.9.9) = The package name, which is equivalent to the <id> tag in the nuspec
  • chocolateyPackageVersion (since 0.9.9) = The package version, which is equivalent to the <version> tag in the nuspec

chocolateyPackageVersion may be particularly useful, since that would allow you in some cases to create packages for new releases of the updated software by only changing the <version> in the nuspec and not having to touch the chocolateyInstall.ps1 at all. An example of this:

$url = "http://www.thesoftware.com/downloads/thesoftware-$env:chocolateyPackageVersion.zip"

Install-ChocolateyZipPackage '$env:chocolateyPackageName' $url $binRoot

Remember, if you want to use chocolateyPackageName or chocolateyPackageVersion you should declare a dependency on Chocolatey 0.9.9 in the nuspec

<dependencies>
  <!-- Chocolatey 0.9.9 required in order to access the chocolateyPackageName and chocolateyPackageVersion environment variables -->
  <dependency id="chocolatey" version="0.9.9" />
</dependencies>