The development of AU is finished and there will be no new versions. The latest version is 2022.10.24.

Chocolatey Automatic Package Updater Module

This PowerShell module implements functions that can be used to automate Chocolatey package updates.

To learn more about Chocolatey automatic packages, please refer to the relevant documentation. To see AU in action see video tutorial.

Features

Use only PowerShell to create automatic update script for given package.
Handles multiple streams with a single update script.
Automatically downloads installers and provides/verifies checksums for x32 and x64 versions.
Verifies URLs, nuspec versions, remote repository existence etc.
Automatically sets the nuspec descriptions from a README.md files.
Update single package or any subset of previously created AU packages with a single command.
Multithread support when updating multiple packages.
Repeat or ignore specific failures when updating multiple packages.
Plugin system when updating everything, with few integrated plugins to send email notifications, save results to gist and push updated packages to git repository.
Use of global variables to change functionality.
Sugar functions for Chocolatey package maintainers.
Great performance - hundreds of packages can be checked and updated in several minutes.

Installation

AU module requires minimally PowerShell version 5: $host.Version -ge '5.0'

To install it, use one of the following methods:

PowerShell Gallery: Install-Module au.
Chocolatey: cinst au.
Download latest 7z package or latest build artifact.

To quickly start using AU, fork au-packages-template repository and rename it to au-packages.

NOTE: All module functions work from within specific root folder. The folder contains all of your Chocolatey packages.

Creating the package updater script

The AU uses update.ps1 script that package maintainers should create in the package directory. No templates are used, just plain PowerShell.

To write the package update script, it is generally required to implement 2 functions: au_GetLatest and au_SearchReplace.

`au_GetLatest`

This function is used to get the latest package information.

As an example, the following function uses Invoke-WebRequest to download a page (#1). After that it takes a href attribute from the first page link that ends with .exe word as a latest URL for the package (#2). Then it conveniently splits the URL to get the latest version for the package (#3), a step that is highly specific to the URL but very easy to determine.

function global:au_GetLatest {
     $download_page = Invoke-WebRequest -Uri $releases -UseBasicParsing #1
     $regex   = '.exe$'
     $url     = $download_page.links | ? href -match $regex | select -First 1 -expand href #2
     $version = $url -split '-|.exe' | select -Last 1 -Skip 2 #3
     return @{ Version = $version; URL32 = $url }
}

The returned version is later compared to the one in the nuspec file and if remote version is higher, the files will be updated. The returned keys of this HashTable are available via global variable $global:Latest (along with some keys that AU generates). You can put whatever data you need in the returned HashTable - this data can be used later in au_SearchReplace.

`au_SearchReplace`

Function returns HashTable containing search and replace data for any package file in the form:

    @{
        file_path1 = @{
            search1 = replace1
            ...
            searchN = replaceN
        }
        file_path2 = @{ ... }
        ...
    }

Search and replace strings are operands for PowerShell replace operator. You do not have to write them most of the time however, they are rarely changed.

File paths are relative to the package directory. The function can use $global:Latest variable to get any type of information obtained when au_GetLatest was executed along with some AU generated data such as PackageName, NuspecVersion etc.

The following example illustrates the usage:

function global:au_SearchReplace {
    @{
        "tools\chocolateyInstall.ps1" = @{
            "(^[$]url32\s*=\s*)('.*')"      = "`$1'$($Latest.URL32)'"           #1
            "(^[$]checksum32\s*=\s*)('.*')" = "`$1'$($Latest.Checksum32)'"      #2
        }
    }
}

Here, line of the format $url32 = '<package_url>' in the file tools\chocolateyInstall.ps1 will have its quoted string replaced with latest URL (#1). The next line replaces value of the variable $checksum32 on the start of the line with the latest checksum that is automatically injected in the $Latest variable by the AU framework (#2). Replacement of the latest version in the nuspec file is handled automatically.

NOTE: The search and replace works on lines, multiple lines can not be matched with single regular expression.

Update

With above functions implemented calling the Update-Package (alias update) function from the AU module will update the package when needed.

You can then update the individual package by running the appropriate update.ps1 script from within the package directory:

PS C:\chocolatey\dngrep> .\update.ps1
dngrep - checking updates using au version 2016.9.14
nuspec version: 2.8.15.0
remote version: 2.8.16.0
New version found
Automatic checksum started
Downloading dngrep 32 bit
  from 'https://github.com/dnGrep/dnGrep/releases/download/v2.8.16.0/dnGREP.2.8.16.x86.msi'

Download of dnGREP.2.8.16.x86.msi (3.36 MB) completed.
Package downloaded and hash calculated for 32 bit version
Downloading dngrep 64 bit
  from 'https://github.com/dnGrep/dnGrep/releases/download/v2.8.16.0/dnGREP.2.8.16.x64.msi'

Download of dnGREP.2.8.16.x64.msi (3.39 MB) completed.
Package downloaded and hash calculated for 64 bit version
Updating files
  dngrep.nuspec
    updating version:  2.8.15.0 -> 2.8.16.0
  tools\chocolateyInstall.ps1
    (^[$]url32\s*=\s*)('.*') = $1'https://github.com/dnGrep/dnGrep/releases/download/v2.8.16.0/dnGREP.2.8.16.x86.msi'
    (^[$]url64\s*=\s*)('.*') = $1'https://github.com/dnGrep/dnGrep/releases/download/v2.8.16.0/dnGREP.2.8.16.x64.msi'
    (^[$]checksum32\s*=\s*)('.*') = $1'CE4753735148E1F48FE0E1CD9AA4DFD019082F4F43C38C4FF4157F08D346700C'
    (^[$]checksumType32\s*=\s*)('.*') = $1'sha256'
    (^[$]checksum64\s*=\s*)('.*') = $1'025BD4101826932E954AACD3FE6AEE9927A7198FEEFFB24F82FBE5D578502D18'
    (^[$]checksumType64\s*=\s*)('.*') = $1'sha256'
Attempting to build package from 'dngrep.nuspec'.
Successfully created package 'dngrep.2.8.16.0.nupkg'
Package updated

This is best understood via the example - take a look at the real life package installer script and its AU updater.

Automatic package description from README.md

If a package directory contains the README.md file, its content will be automatically set as description of the package with first 2 lines omitted - you can put on those lines custom content that will not be visible in the package description.

To disable this option use -NoReadme switch with the Update-Package function. You can still call it manually from within au_AfterUpdate, which you may want to do in order to pass custom parameters to it:

function global:au_AfterUpdate ($Package)  {
     Set-DescriptionFromReadme $Package -SkipLast 2 -SkipFirst 5
}

To extract descriptions from existing packages into README.md files the following script can be used:

ls | ? PSIsContainer | ? { !(Test-Path $_\README.md) } | % {
  [xml] $package = gc $_\*.nuspec -ea 0 -Encoding UTF8
  if (!$package) { return }

  $meta = $package.package.metadata
  $readme = ('# <img src="{1}" width="48" height="48"/> [{0}](https://chocolatey.org/packages/{0})' -f $meta.id, $meta.iconUrl), ''
  $readme += $meta.description -split "`n" | % { $_.Trim() }
  $readme -join "`n" | Out-File -Encoding UTF8 $_\README.md
  $meta.id
}

Checks

The update function does the following checks:

The $Latest.Version will be checked to match a valid nuspec pattern.
Any hash key that starts with the word Url, will be checked for existence and MIME textual type, since binary is expected here.
If the remote version is higher then the nuspec version, the Chocolatey site will be checked for existence of this package version (this works for unpublished packages too). This allows multiple users to upd

Au

Install / Use

README