en-US/about_Whiskey_ProGetUniversalPackage_Task.help.txt

TOPIC
    about_Whiskey_ProGetUniversalPackage_Task
 
SUMMARY
    Creates a ProGet universal package.
 
DESCRIPTION
    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 relative to the whiskey.yml file. You can change the root path the task uses to resolve these paths with the `SourceRoot` 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 wildcards and file names. All directories in the `Path` property are filtered with this list, i.e. only items under each directory in `Path` that matches an item in `Include` will be added to your package.
    * `Exclude`: a list of wildcards, file names, and directory names to exclude from the package. Sometimes a whitelist can be a little greedy and include some files or directories you might not want. Any file or directory that matches an item in this list will be excluded from the package.
    * `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](https://inedo.com/support/documentation/upack/universal-packages/metacontent-guidance/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.
    * `SourceRoot`: this changes the root path used to resolve the relative paths in the Path property. Use this element when your application's root directory isn't the same directory your whiskey.yml file is in. This path should be relative to the whiskey.yml file.
    * `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.
 
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
 
    The above demonstrates how to use the `Exclude` property to exclude files from the package. If this is what's on the file system:
 
        bin\
            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.
 
    ## 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 SourceRoot property.
            SourceRoot: 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