Create Your Own Custom Extensions

For years Chocolatey has allowed you to extend Chocolatey with your own PowerShell modules and functions. These are known as extensions.

Overview

Extensions allow you to package up PowerShell functions that you may reuse across packages as a package that other packages can use and depend on. This allows you to use those same functions as if they were part of Chocolatey itself. Chocolatey loads these PowerShell modules up as part of the regular module import load that it does for built-in PowerShell modules.

Why Would I Create an Extension?

To reduce code in your Chocolatey automation scripts. Packaging up logic as functions into a PowerShell module that you can version independently, fix issues in, and enhance without needing to touch existing packages that you have is pretty powerful.

Creating a Chocolatey Extension

When it comes to extensions, Chocolatey takes a conventional approach. You must create a package with the suffix ".extension" and have a extensions folder with at least one PowerShell module in it.

The name of the package should be "extensionname.extension". The name of the package minus ".extension" will be the name of the extension that is installed.

Here's an example: https://chocolatey.org/packages/chocolatey-uninstall.extension. The source is at https://github.com/chocolatey/chocolatey-coreteampackages/tree/master/extensions

Yes, it is really that easy. Enjoy!

Recommendations

Naming Your Extension

Avoid "Chocolatey" as part of the name. Yes the example is named that, but this extension is owned by the Core Chocolatey team, so it makes sense for that to be the name.

PowerShell Modules

Taking a Dependency on an Extension Package

When taking a dependency on an extension package, it is recommended to take a minimum version dependency. If there is functionality that is enhanced in that extension, you should bump that dependency version.

Minimum Version Depdendencies

What does a minimum version depdency look like?

<dependencies>
  <dependency id="chocolatey-uninstall.extension" version="1.1.0" />
</dependencies>

Avoid Version Ranges For Extensions

Avoid version ranges when it comes to extensions as it can lock out fixes and enhancements in the future.


<dependencies>
  <!-- This means at least 1.0.0, and anything less than 2 -->
  <dependency id="chocolatey-uninstall.extension" version="[1.0.0, 2)" />
  <!-- This means anything between 1.0.0 and 2.0.1 (including 2.0.1) is good to go -->
  <dependency id="another.extension" version="[1.0.0, 2.0.1]" />
</dependencies>

Avoid Exact Version Dependencies For Extensions at All Costs

Try to never lock into an exact version dependency:

<!-- DO NOT DO THIS -->
<dependencies>
  <dependency id="chocolatey-uninstall.extension" version="[1.1.0]" />
</dependencies>

This locks every other package into that singular version and does not allow for upgrades and fixes.

Version-less Dependencies

There is also the concept of versionless dependencies.

<dependencies>
  <dependency id="chocolatey-uninstall.extension" />
</dependencies>

Folks typically have used these in the past. They are less bad, but it just means that any version will do.