Universal Packages

A Universal Package is a file that contains other files such as programs, configurations, application components, plugins, libraries, or any other kind of content. It also contains a manifest file that uniquely identifies the package with a name/version and optionally describes its contents.

Unlike other packaging formats (NuGet, Rpm, etc.), Universal Packages were not designed for a specific use case (.NET libraries, Linux applications, etc.) and were designed to be as simple to use as possible.

You can create Universal Packages manually by hand or by using one of the free and open Universal Packaging Tools.

Universal Package Format

There isn't much to a universal package file; there are just two requirements:

1. is a ZIP archive format with a .upack file extension
2. has a manifest file in the root directory named upack.json with a few required fields

For example, a very basic Universal Package for my-app version 1.3.9 might look like this:

upack.json
packages/my-app.config
packages/my-app.exe
packages/my-app.dll

{
 "name": "my-app",
 "version": "1.3.9"
}

You could create this package file manually or using the pgutil CLI tool. For example:

$ pgutil upack create --name=my-app --version=1.3.9 --source-directory=.\package-files\my-app --target-directory=.\universal-packages

Alternatively, if you have already created a upack.json manifest for your Universal Package, you can specify this instead:

$ pgutil upack create --manifest=.\package-files\my-app\upack.json --source-directory=.\package-files\my-app --target-directory=.\universal-packages

That command will package the .\my-app folder into the my-app-1.3.9.upack ZIP archive file. See the Universal Feeds & Packages page to learn more.

Package Content and Metacontent

Files contained in the package/ folder within a Universal Package ZIP archive are referred to as content. When you "install" or "unpackage" a Universal Package to a folder on disk, that folder will only contain the files from the ZIP archive's package/ folder.

You can use the upack install pgutil command to install a package from a ProGet feed. For example:

$ pgutil upack install --package=my-app --version=1.3.9 --feed=universal --target=.\my-app

That command will basically do the opposite of the create command and write the content files to the .\my-app folder.

Installing packages will also create an entry in the Universal Package Registry. This is a local system that tracks and manages installed Universal Packages, creating a record of the packages metadata.

All other files within a Universal Package (including upack.json) are referred to as metacontent. For most use cases, you will never need to use or access metacontent, but it might come in handy for advanced scenarios like embedding installation scripts, build logs, Software Bill of Material (SBOM) files, etc.

Manifest (upack.json) Specification

The upack.json file is a JSON object with the following properties:

Required or Implicit Properties

Additional Descriptive Properties (Optional)

Audit-based Properties (Optional)

An R denotes a required property.

Additional Metadata

This object may contain additional properties as needed. However, if you need to add additional metadata, it's strongly recommended that you prefix these properties with an underscore (_)... just on the off-chance that a property you add will exist in a future version of the specification, or is returned in other metadata queries.

Example Manifest Files (upack.json)

Using Extended Fields

The following manifest adds a group (which is a part of the package's identifier) and two custom properties (_sourceRoot, _deployTarget). Note how they are prefixed with an underscore to avoid future naming conflicts.

{
 "group": "virtudyne/simdesk",
 "name": "var-index-service",
 "version": "5.3.9",
 "_sourceRoot": "$/global/vindex/branches/v5-hotfix"
 "_deployTarget": "/var/vsimdesk/vindex"
}

Full/Complete Manifest

The following manifest uses just about every property available; note how the description is markdown formatted.

{
 "group": "initrode/vendors/abl",
 "name": "ABLast",
 "version": "2.2.1",
 "title": "ast distribution files for ABL",
 "icon": "package://ablast.svg",
 "description": "This contains [ast distro](http://initrode-net.local/ast) files specific to ABL",
 "dependencies": [ "initrode/vendors-common:ast-common:2.0.0" ],
 "createdDate": "2017-11-09T04:03:01Z",
 "createdReason": "ABLast v2.2.1 #18 (ID8843) ",
 "createdUsing": "BuildMaster/5.6.11",
 "createdBy": "THoven"
}

Inedo Extensions (Plugins) Manifest

The following is the manifest for our AWS extension (i.e. Plugin) package which uses array-based custom properties. You can also see that this particular manifest was repackaged as part of a CI/CD process.

{
  "group": "inedox",
  "name": "AWS",
  "version": "3.1.0",
  "title": "Amazon AWS",
  "description": "Contains a ProGet Package Store backed by Amazon S3, and operations for working with S3 storage in Otter and BuildMaster.",
  "icon": "https://inedo.com/den/logos/AWS.png",
  "_inedoSdkVersion": "3.1.0",
  "_inedoProducts": [ "BuildMaster", "Otter", "ProGet" ],
  "_targetFrameworks": [ "net452", "net6.0", "net8.0" ],
  "repackageHistory": [
    {
      "id": "inedox:AWS:3.1.0-CI.2",
      "using": "ProGet/24.0.17"
    },
    {
      "id": "inedox:AWS:3.1.0-RC.2",
      "using": "ProGet/24.0.17"
    }
  ]
}

Universal Package Tools

The main tool used to create and manage Universal Packages and installations is the pgutil CLI tool. This will require some minor configuration to use, and offers several commands:

• upack create: Will create a Universal Package at a specified location
• upack install: Will "Install" or "unpack" a Universal Package to a specified location
• upack list: Will list all installed Universal Packages
• upack update: Will update the installation with another version from a specified Universal Package feed
• upack remove: Will uninstall the specified Universal Package

You can learn more about how to use these commands on the Universal Feeds & Packages page.

Deprecated & Older Tools

Over the years, users have gotten more comfortable using Command-line tools. As such, we decided to abandon some of the earlier Universal Package tools we created.

Although we do not maintain these tools anymore, you may find them useful. If you think we should revive/rebuild them, just let us know.

UPack Command-line Interface

upack is a cross-platform command-line tool for creating and installing universal packages; you can also see which packages are installed on a machine.

• Download upack (github.com)
• upack Source Code (github.com)

Inedo.UPack

Inedo.UPack is a set of utilities for working with Universal Packages and feeds.

• Inedo.UPack NuGet Package (nuget.org)
• Inedo.UPack Source Code (github.com)

Universal Package Explorer

A Windows desktop application that allows you to easily create, view, and publish universal packages. You can load a .upack file from disk or directly from a ProGet universal feed.

• Download Universal Package Explorer (github.com)
• Universal Package Explorer Source Code (github.com)

Push to ProGet Visual Studio Extension

Allows you to publish universal packages directly from Visual Studio.

• Install in Visual Studio (Tools > Extensions and Updates > Online > Search for "ProGet" > Download, Install, and Restart Visual Studio)
• download the extension from the Visual Studio Gallery directly.

ProGet Jenkins Plugin

Integrates ProGet with Jenkins allowing Jenkins jobs to create and upload, or download and extract, universal packages. It still works, but it's no longer actively maintained.

• See ProGet Jenkins Plugin