From 076379dd0e13dfe3316d28d4a7b5e0b0a81a57fd Mon Sep 17 00:00:00 2001 From: TheCakeIsNaOH Date: Mon, 10 Oct 2022 22:20:31 -0500 Subject: [PATCH] (#563) Add documentation about hooks --- input/en-us/features/hook.md | 46 ++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 input/en-us/features/hook.md diff --git a/input/en-us/features/hook.md b/input/en-us/features/hook.md new file mode 100644 index 0000000000..aa18314110 --- /dev/null +++ b/input/en-us/features/hook.md @@ -0,0 +1,46 @@ +--- +Order: 75 +xref: hooks +Title: Extend Chocolatey With PowerShell Scripts (Hooks) +Description: Run PowerShell before and after Package Automation Scripts +--- + +A feature is available in Chocolatey CLI v1.2.0, which allows you to extend a package's automation script(s) with additional PowerShell scripts, called hooks. + +## Overview + +Hooks allow you to run code before a package automation script like a `chocolateyInstall.ps1` runs, or after. They even work when automation scripts are not included in the package. Each script can selectively target a single package ID, or run for all packages. Then they can be distributed using `.hook` packages. + +## Creating Hook Scripts + +Hook scripts are PowerShell `.ps1` files, and are run in the same environment as package automation scripts run, so they have access to all of the same environment variables and helpers. + +The conditions for when a hook is run is based on the filename of the hook. The filename format is `--.ps1`. The first section is for the timing of when the hook script runs. Filenames that start with `pre` run before the package automation script (e.g. the `chocolateyInstall.ps1`), while filenames that start with `post` are run afterwards. The second section of the filename determines which package automation script the hook is run before or after. The third section of the filename is either a string of the package ID for which the hook should be run, or the keyword `all` to specify that the hook should be run for all package IDs. + +If a package does not contain a `chocolateyInstall.ps1`, but a `pre-install-all.ps1` hook is installed, then that hook will still run at the point in the package install as the `chocolateyInstall.ps1` would have been run if the package had included it. + +## Creating Hook Packages + +Hooks can be installed just like extensions, via a specific package type, namely `.hook`. The name of the installed hook folder is the package id, minus the `.hook`. + +How to create a Hook package: +1. Create a package with a `.hook` suffix like `choco new name.hook` +1. Delete the created files and folders except for the `.nuspec` +1. Create a `hook` folder in the root of the package (next to the `.nuspec`). +1. Put your hook PowerShell script files inside the `hook` folder. +1. Pack and install your new Hook package. + + +## Recommenations + +### Still under development + +Hook scripts and packages are still new, so guidelines and best practices are still being determined. Follow along at the [Chocolatey Community Hooks Repository](https://github.com/chocolatey-community/chocolatey-hooks) for the latest information. + +### Avoid taking dependencies on regular packages + +It is best to avoid having a `.hook` package taking a dependency on regular packages. This is so the included hooks from the package can be installed before other packages get initially installed. For example, if there is a `pre-install-git.ps1` hook and the `.hook` package it is included in takes a dependency on `git`, then the `chocolateyInstall.ps1` from the `git` package would have already run before the hook is installed, which is counterproductive. + +### Do take dependencies on extension packages + +If any hook script in a `.hook` package require helpers from an `.extension` package, then make sure that they `.hook` package takes a dependency on that `.extension` package.