HelpersReference - Nilzor/chocolatey GitHub Wiki

##Main Helpers These helpers call other helpers and have error handling built in. When using just them, you don't need to put error handling in your chocolateyInstall.ps1 file. These helpers call down to the other helpers and encapsulate everything nicely so that it is possible to have one line chocolateyInstall.ps1 files.

Install-ChocolateyPackage
Install-ChocolateyZipPackage
Install-ChocolateyPowershellCommand
Install-ChocolateyVsixPackage - v0.9.8.20+

##Error/SuccessHelpers

Write-ChocolateySuccess
Write-ChocolateyFailure

If do anything besides use the main helpers, it is strongly suggested you format your chocolateyInstall.ps1 as follows:

try {
  
  #Your code here...

  Write-ChocolateySuccess '__NAME__'
} catch {
  Write-ChocolateyFailure '__NAME__' $($_.Exception.Message)
  throw 
}

##More Helpers These helpers require you to wrap a try catch around your chocolateyInstall.ps1 file. See the example script above.

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

###Non-Administrator Safe Helpers 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. Starting with chocolatey v0.9.8.3, this has been possible.

These are the helpers from above as one list.

##Overview

###Helpers in alphabetical order (needs updating)

  • Get-BinRoot [src]
    Gets the path to where binaries should be installed. Either by environmental variable ChocolateyBinRoot or by default. E.g. C:\Tools
$scriptPath = (Split-Path -parent $MyInvocation.MyCommand.Definition)
Get-ChocolateyUnzip "c:\someFile.zip" $scriptPath somedirinzip\somedirinzip
  • Get-CheckSumValid [src]
  • Get-ChocolateyUnzip [src]
    Unzips a .zip file and returns the location for further processing.
$scriptPath = (Split-Path -parent $MyInvocation.MyCommand.Definition)
Get-ChocolateyUnzip "c:\someFile.zip" $scriptPath somedirinzip\somedirinzip
  • Get-ChocolateyWebFile [src]
    Downloads a file from the internets.
Get-ChocolateyWebFile '__NAME__' 'C:\somepath\somename.exe' 'URL' '64BIT_URL_DELETE_IF_NO_64BIT'
  • Get-FtpFile [src]
  • Get-ProcessorBits [src]
    Get the system architecture address width; return the system architecture address width (32 or 64). Optionally return true or false by specifying a width to test against.
$architecture = Get-ProcessorBits; # 64
$is32bit = Get-ProcessorBits 32; # false
  • Get-UACEnabled [src]
  • Get-VirusCheckValid [src]
    :warning: not implemented!
  • Get-WebFile [src]
  • Get-WebHeaders [src]
  • Install-ChocolateyDesktopLink [src]
    This adds a shortcut on the desktop to the specified file path.
Install-ChocolateyDesktopLink -TargetFilePath "C:\tools\NHibernatProfiler\nhprof.exe"

This will create a new Desktop Shortcut pointing at the NHibernate Profiler exe.
  • Install-ChocolateyEnvironmentVariable [src]
    Creates a persistent environment variable
Install-ChocolateyEnvironmentVariable "JAVA_HOME" "d:\oracle\jdk\bin"
Creates a User environmet variable "JAVA_HOME" pointing to
"d:\oracle\jdk\bin".
  • Install-ChocolateyExplorerMenuItem [src]
    Creates a windows explorer context menu item that can be associated with a command
C:\PS>$sublimeDir = (Get-ChildItem $env:systemdrive\chocolatey\lib\sublimetext* | select $_.last)
C:\PS>$sublimeExe = "$sublimeDir\tools\sublime_text.exe"
C:\PS>Install-ChocolateyExplorerMenuItem "sublime" "Open with Sublime Text 2" $sublimeExe

This will create a context menu item in Windows Explorer when any file is right clicked. The menu item will appear with the text "Open with Sublime Text 2" and will invoke sublime text 2 when selected.
  • Install-ChocolateyFileAssociation [src]
    Creates an association between a file extension and a executable
C:\PS>$sublimeDir = (Get-ChildItem $env:systemdrive\chocolatey\lib\sublimetext* | select $_.last)
C:\PS>$sublimeExe = "$sublimeDir\tools\sublime_text.exe"
C:\PS>Install-ChocolateyFileAssociation ".txt" $sublimeExe

This will create an association between Sublime Text 2 and all .txt files. Any .txt file opened will by default open with Sublime Text 2.
  • Install-ChocolateyInstallPackage [src]
    Installs a package
Install-ChocolateyInstallPackage '__NAME__' 'EXE_OR_MSI' 'SILENT_ARGS' 'FilePath'
  • Install-ChocolateyPackage [src]
    Installs a package
Install-ChocolateyPackage '__NAME__' 'EXE_OR_MSI' 'SILENT_ARGS' 'URL' '64BIT_URL_DELETE_IF_NO_64BIT'
  • Install-ChocolateyPath [src]
  • Install-ChocolateyPinnedTaskBarItem [src]
    Creates an item in the task bar linking to the provided path.
Install-ChocolateyPinnedTaskBarItem "${env:ProgramFiles(x86)}\Microsoft Visual Studio 11.0\Common7\IDE\devenv.exe"

This will create a Visual Studio task bar icon.
  • Install-ChocolateyPowershellCommand [src]
  • Install-ChocolateyShortcut [src]
    This adds a shortcut, at the specified location, with the option to specify a number of additional properties for the shortcut, such as Working Directory, Arguments, Icon Location, and Description.
Install-ChocolateyShortcut -shortcutFilePath "C:\test.lnk" -targetPath "C:\test.exe"

This will create a new shortcut at the location of "C:\test.lnk" and link to the file
located at "C:\text.exe"
  • Install-ChocolateyVsixPackage [src]
    Downloads and installs a VSIX package for Visual Studio
Install-ChocolateyVsixPackage "MyPackage" http://visualstudiogallery.msdn.microsoft.com/ea3a37c9-1c76-4628-803e-b10a109e7943/file/73131/1/AutoWrockTestable.vsix

This downloads the AutoWrockTestable VSIX from the Visual Studio Gallery and installs it to the latest version of VS.
  • Install-ChocolateyZipPackage [src]
    Downloads and unzips a package
Install-ChocolateyZipPackage '__NAME__' 'URL' "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"
  • Start-ChocolateyProcessAsAdmin [src]
  • Uninstall-ChocolateyPackage [src]
    Uninstalls a package
Uninstall-ChocolateyPackage '__NAME__' 'EXE_OR_MSI' 'SILENT_ARGS' 'FilePath'
  • UnInstall-ChocolateyZipPackage [src]
    UnInstalls a previous installed zip package
UnInstall-ChocolateyZipPackage '__NAME__' 'filename.zip'
  • Update-SessionEnvironment [src]
    Updates the environment variables of the current powershell session with any environment variable changes that may have occured during a chocolatey package install.
  • Write-ChocolateyFailure [src]
  • Write-ChocolateySuccess [src]
  • Write-Debug [src]
  • Write-Error [src]
  • Write-FileUpdateLog [src]
  • Write-Host [src]

Home