ProGetUniversalPackage Task

Overview

The ProGetUniversalPackage task creates a universal ProGet package (i.e. a .upack file). You must specify a package name and description with the Name and Description properties, respectively.

Specify the directories and files you want in the package with the Path property. The paths should be relative to the whiskey.yml file. Each item is added to the package using its path relative to the whiskey.yml file. Directories are filtered by the Include property, which is a list of filenames and/or wildcard patterns. Only files that match at least one item in this list will be included in your package.

This PowerShell command will create a YAML whitelist for all files under a path:

Get-ChildItem -Path $PATH -Recurse |
    Select-Object -ExpandProperty 'Extension' |
    Select-Object -unique |
    Sort-Object |
    ForEach-Object { '- "*{0}"' -f $_ }

The package is saved to the output directory as $Name.upack where $Name is replaced with the name of your package.

A version.json file is put into the root of your package. It contains the version information for the current build. It looks like this:

{
    "SemVer2":  "2017.412.286-rc.1+master.1acb317",
    "SemVer2NoBuildMetadata":  "2017.412.286-rc.1",
    "PrereleaseMetadata":  "rc.1",
    "BuildMetadata":  "master.1acb317",
    "SemVer1": "2017.412.286-rc1",
    "Version":  "2017.412.286"
}

It has these properties:

• BuildMetadata: this is either the build number, branch, and commit ID or the branch and commit ID, each separated by a period ..
• PrereleasMetadata: this is any pre-release metadata from the Version property from your whiskey.yml file. If there is not Version in your whiskey.yml file, this field will be empty.
• SemVer2: the full semantic version of the application.
• SemVer2NoBuildMetadata: this is the version number used when creating packages. We omit the build metadata so that we don't upload duplicate packages (i.e. every build generates unique build metadata even if that version of code was already built and published.
• SemVer1: a semantic version compatible for use with systems that don't yet support the v2 semantic version spec, e.g. NuGet.
• Version: the MAJOR.MINOR.PATCH version number of the application.

Properties

• Name (mandatory): the package's name.
• Description (mandatory): the package's description. This shows in ProGet and helps people know about your application.
• Path (mandatory): the directories and filenames to include in the package. Each path must exist and be under the build root. You can change the root path the task uses to resolve these paths with the WorkingDirectory common property. Each item is added to the package at the same relative path as its source item. If you have two paths with the same name, the second item will replace the first. You can customize the path of the item in the package by converting the value into a key/value pair, e.g. source_dir\source_file.ps1: destination_dir\destination_file.ps1. To specify the package root as the custom destination path for an item use ., e.g. source_dir\sub_dir: . would place the contents of the source_dir\sub_dir directory in the package root.
• Include (mandatory): a whitelist of file/directory names and file/directory paths. Wildcards accepted. If an item is a name (i.e. it has no directory separator character), all files/directories whose name matches any item in the list is included. If an item is a path (i.e. it has at least one directory separator character), all files/directories whose path relative to the working directory matches any item in the list is included.
• Exclude: a list of file/directory names and file/directory paths. Wildcards accepted. If an item is a name (i.e. it has no directory separator character), all files/directories whose name matches any item in the list is excluded. If an item is a path (i.e. it has at least one directory separator character), all files/directories whose path relative to the working directory matches any item in the list is excluded.
• ManifestProperties: name/value mappings to be set in the package's upack.json file. Mandatory upack.json properties are automatically added if they are not specified (e.g. Name and Description). This property gets converted to JSON and is added to the upack.json as-is. See the upack.json Manifest Specification for required properties and format.
• ThirdPartyPath: a list of directores and files that should be included in the package unfiltered. These are paths that are copied without using the Include or Exclude elements. This is useful to include items you depend on but have no control over, like Node.js applications' node_modules directory.
• CompressionLevel: the compression level to use when creating the package. The default is Optimal. Valid values are Optimal (smaller package but created slower), Fastest (larger package but created faster), and NoCompression (largest file, created fastest, no compression).
• Version: the package version (MAJOR.MINOR.PATCH), without any prerelease or build metadata. Usually, the version for the current build is used. Prerelease and build metadata for the current build is added.
• ProGetAutomationVersion: the version of the ProGetAutomation module to use. The default is 1.*.

Examples

Example 1

Build:
- ProGetUniversalPackage:
    Name: Example1
    Description: This package demonstrates the YAML for using the ProGetUniversalPackage task.
    Path:
    - bin
    - REAMDE.md
    Include:
    - "*.dll"

The above example shows the YAML for creating a ProGet Universal Package. Given the file system looks like this:

bin\
    Assembly.dll
    Assembly.pdb
    Assembly.xml
src\
    Assembly.cs
README.md
whiskey.yml

The package will look like this:

package\
    bin\
        Assembly.dll
    README.md
    version.json
upack.json

Because the Include list only includes *.dll, the Assembly.pdb and Assembly.xml files are not included in the package.

The version.json file is created by the task and contains the version metadata for this build.

The upack.json file contains the universal package metadata required by ProGet.

Example 2

Build:
- ProGetUniversalPackage
    Name: Example2
    Description: This package demonstrates the YAML for using the ProGetUniversalPackage task.
    Path:
    - bin
    Include:
    - "*.dll"
    - "*.pdb"
    Exclude:
    - SomeOtherAssembly.pdb
    - bin\unwanted_artifacts

The above demonstrates how to use the Exclude property to exclude files and directories from the package. If this is what's on the file system:

bin\
    unwanted_artificats\
        Unwanted.dll
        Unwanted.pdb
    Assembly.dll
    Assembly.pdb
    SomeOtherAssembly.dll
    SomeOtherAssembly.pdb
whiskey.yml

The package will look like this:

package\
    bin\
        Assembly.dll
        Assembly.pdb
        SomeOtherAssembly.dll
    version.json
upack.json

Note that the bin\SomeOtherAssembly.pdb file is not in the package even though it matches an item in the Include whitelist. It is excluded because it matches an item in the Exclude blacklist. The files in the bin\unwanted_artifacts directory are excluded because the directory's path matches bin\unwanted_artifacts from the exclude list.

Example 3

Build:
- ProGetUniversalPackage
    Name: Example3
    Description: This package demonstrates how the `ThirdPartyPath` property works.
    Path:
    - dist
    Include:
    - "*.js"
    - "*.json"
    - "*.css"
    ThirdPartyPath:
    - node_modules

This example demonstrates how to use the ThirdPartyPath property. If the file system looks like this:

dist\
    index.js
    default.css
    data.json
node_modules\
    rimraf\
        LICENSE
        otherfiles
whiskey.yml

the package will look like this:

package\
    dist\
        index.js
        default.css
        data.json
    node_modules\
        rimraf\
            LICENSE
            otherfiles
    version.json
upack.json

Notice that all files/directories under node_modules are included because node_modules is in the ThirdPartyPath list. Directores in ThirdPartyPath are included in the package as-is, with no filtering.

Example 4

Build:
- ProGetUniversalPackage
    Name: Example4
    Description: This package demonstrates how the customize paths in the package.
    Path:
    - source: destination
    Include:
    - "*.dll"

This example demonstrates how to customize the path an item should have in the package. If this is the file system:

source\
    Assembly.dll
    Assembly.pdb
whiskey.yml

the package will look like this:

package\
    destination\
        Assembly.dll
    version.json
upack.json

Notice that the source directory is added to the package as destination. This is done by making the value of an item in the Path list from a string into a key/value pair (e.g. key: value).

Example 5

Build:
- ProGetUniversalPackage
    Name: Example5
    Description: Demonstration of the WorkingDirectory property.
    WorkingDirectory: Whiskey
    Path:
    - Functions
    - "*.ps*1"
    Include:
    - "*.ps*1"
    ThirdPartyPath:
    - ProGetAutomation

This example demonstrates how to change the root directory the task uses to resolve the relative paths in the Path. If the file system is:

Whiskey\
    Functions\
        New-WhiskeyContext.ps1
    Whiskey.psd1
    Whiskey.psm1
    BuildMasterAutomation\
        BuildMasterAutomation.psd1
        BuildMasterAutomation.psm1
whiskey.yml

the package will be:

package\
    Functions\
        New-WhiskeyContext.ps1
    Whiskey.psd1
    Whiskey.psm1
    BuildMasterAutomation\
        BuildMasterAutomation.psd1
        BuildMasterAutomation.psm1
    version.json
upack.json

Notice that the top-level Whiskey directory found on the file system isn't part of the package. Because it is defined as the source root, it is considered the root of the files to put in the package, so is omitted from the package.

Example 6

Build:
- ProGetUniversalPackage:
    Name: Example6
    Description: This package demonstrates the YAML for using the ProGetUniversalPackage task with custom upack.json metadata.
    Path:
    - REAMDE.md
    ManifestProperties:
        CreatedBy: WhiskeyAutomation
        Tags:
        - Tag1
        - Tag2

The above example shows the YAML for creating a ProGet Universal Package with custom upack.json metadata.

The upack.json file in the package will contain the following content:

{
    "Name":  "Example6",
    "Description":  "This package demonstrates the YAML for using the ProGetUniversalPackage task with custom upack.json metadata.",
    "Title":  "Example6",
    "Version":  "1.2.3-rc.1",
    "CreatedBy":  "WhiskeyAutomation",
    "Tags":  [
                "Tag1",
                "Tag2"
            ]
}

Example 7

Build:
- ProGetUniversalPackage:
    Name: Example7
    Description: This package demonstrates using the package root as a custom destination.
    Path:
    - .output\assembly: .
    Include:
    - "*.dll"

This example demonstrates how to specify the package root . when customizing the path an item should have in the package. If this is the file system:

.output\
    assembly\
        Assembly1.dll
        Assembly2.dll
whiskey.yml

the package will look like this:

package\
    Assembly1.dll
    Assembly2.dll
    version.json
upack.json