Master Packager Dev

Getting started
Command line options
Package schema
Package validation

Getting started

Before you get started

The MPDEV package consists of two main sections:
- Common section - applies to all packages.
- Package-specific section - applies to a specific package only.
All properties in the common section apply to all packages being built and can be overridden or appended in the package-specific sections. Additionally, each package-specific section provides package-specific properties.
The msi and msix properties define package-specific sections.
Strings in the package that match Windows environment variables, such as %PATH%, will be automatically expanded during the build process. If such an environment variable does not exist, it will be replaced with an empty string. To suppress environment variable expansion, the value can be escaped with another pair of % characters, for example %%PATH%%.
It is possible to set custom environment variables before package build so that they can be used in the JSON. For example you can set an environment variable for the version as MYVERSION=1.0.0 and set the version to "version": "%MYVERSION%".
$.iniFiles, $.registries and $.environmentVariables MSI sections during installation will try to resolve strings with enclosing square brackets to an MSI property value, if no such property is found it will be resolved with an empty string. Example [SomeString] will try to resolve the value of property SomeString. More information about it can be found here
Any property within the package can be referenced in the values of other properties. For example: "outputFileName": MyPackage_$.platform_$.version
Source path - a path somewhere on your disk.
Target path - the path within your package where the file/directory will be installed.
Source paths can be provided as either relative or absolute paths. Relative paths are expanded based on the directory from which the mpdev executable is invoked. Use the --working-dir argument to alter the working directory during the build process.
Target paths can only be provided as absolute paths.
To use a custom MSI file as a template for the build, set the msi.baseMsi property.
To use a custom MSIX manifest file, set the msix.manifest property. If this property is set, MPDEV will not generate its own manifest file based on the package contents.
MPDEV uses the MSIX Package Support Framework to enable features that are not natively supported by MSIX. To disable the Package Support Framework, set msix.usePsf to false.

Package example

In this example, MPDEV package is built in a directory that contains following sub-directories and files:

My Simple App\output - directory where built packages (msi and msix) will be stored.
My Simple App\build - directory containing application source files.
My Simple App\Installer Files - directory containing files that need to be added to the installer but are not outputted by the app's build process.

All source files and directories will be targeting C:\Program Files(x86)\My Simple App folder.

{
  "$schema": "https://www.masterpackager.com/support-master-packager-dev/mpdev-schema.json",
  "outputTypes": [ "msi", "msix" ],
  "outputDirectory": "My Simple App\\output",
  "packageName": "MySimpleApp",
  "publisher": "I am MasterPackager Dev",
  "version": "1.0.0",
  "platform": "x86",
  "installDir": "%ProgramFiles(x86)%\\My Simple App",
  "icon": "My Simple App\\Installer Files\\Icon.ico",
  "fileSystemEntries": [
    {
      "sourcePath": "My Simple App\\build",
      "targetPath": "$.installDir"
    },
    {
      "sourcePath": "My Simple App\\build\\NeedsDifferentNameAndFolder.dll",
      "targetPath": "$.installDir\\OtherFolder\\DifferentName.dll"
    },
    {
      "sourcePath": "My Simple App\\Installer Files\\THIRD-PARTY-NOTICES.txt",
      "targetPath": "$.installDir\\THIRD-PARTY-NOTICES.txt"
    }
  ],
  "registries": [
    {
      "key": "HKEY_LOCAL_MACHINE\\SOFTWARE\\MySimpleApp",
      "value": "This is value for default key."
    },
    {
      "key": "HKEY_LOCAL_MACHINE\\SOFTWARE\\MySimpleApp",
      "name": "SomeName",
      "value": "Packaging should not be hard!"
    }
  ],
  "shortcuts": [
    {
      "target": "$.installDir\\MyApp.exe"
    }
  ],
  "environmentVariables": [
    {
      "name": "MyEnvVar",
      "value": "Simple, right?"
    },
    {
      "name": "%%WILL_NOT_EXPAND%%",
      "value": "%WILL_EXPAND%"
    }
  ],
  "digitalSignature": {
    "signWith": "AzureTrustedSigning",
    "endpoint": "https://eus.codesigning.azure.net",
    "codeSigningAccountName": "AccountName",
    "certificateProfileName": "ProfileName",
    "timestampServer": "http://timestamp.acs.microsoft.com",
    "exclusions": [
      "My Simple App\\\\DoNotSignAnythingUnderThisFolder",
      "My Simple App\\\\build\\\\DoNotSignThisFile.dll"
    ]
  },

  "msi": {
    "upgradeCode": "{9C2C8235-1FD9-42BA-ADBF-1AE86A8F1642}",
    "installDialog": {
      "packageDescription": "This is my Simple App.",
      "publisherUrl": "https://www.mysimpleapp.com/",
      "releaseNotesUrl": "https://www.mysimpleapp.com/release-notes",
      "eulaUrl": "https://www.mysimpleapp.com/eula",
      "primaryAccent": "#01787B"
    }
  },
  "msix": {
    "installDialog": {
      "primaryAccent": "#01787B"
    }
  }
}

How to build a package?

mpdev build package.json

How to activate a license?

mpdev activate "eyJhbGciiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6IGVycGFja2FnZXIuY29tIiwiZXhDIyLBhbnkiLCJ0eXBlIjoiUHJvIn0.1WXV7Cz1SmVdT47gl8AnAQJx1g"

Command line options

Usage
mpdev [command] [args] [options]

Available commands
Command	Description
activate	Activates MPDEV license.
build	Builds MPDEV package from provided package JSON file.
help\|/?\|-?\|/h\|-h\|--help	Outputs help.
version\|--version	Outputs MPDEV version.

activate command
Usage	mpdev activate [license-key] [--all-users]
Args	license-key \| required \| License key string.
Options	--all-users \| optional \| Activates user for all users by storing license file next to executable.
Example	mpdev activate eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 -all-users

build command
Usage	mpdev build [path-to-package-json]
Args	path-to-package-json \| required \| Path to MPDEV package JSON file.
Options	--working-dir <WORKING_DIR> \| optional \| Changes location of the working directory during build. All relative source paths in the package will be specified based on the provided working directory. --properties <$.propertyName=value> \| optional \| Creates a new property that can be referenced in the package JSON file or overrides the value of an existing JSON property in the package schema. All properties must start with the "$." prefix and be separated by whitespace. All properties must be defined in key-value pairs separated by "=" character. If a property value contains whitespace, the value must be enclosed in double quotes.
Example	mpdev build "C:\my-package.json" --properties $.version=1.0.0 $.platform=x86.

Global options
Option	Description
--verbose	Enables verbose mode.
--use-msbuild-message-format <true\|false>	Enables MSBuild message format. This option is enabled by default for "activate" and "build" commands. Learn more

Package schema

The JSON schema for the latest version of Master Packager Dev is available at https://www.masterpackager.com/support-master-packager-dev/mpdev-schema.json .

Local version included with every installer is available at C:\Program Files\Master Packager Ltd\Master Packager Dev\mpdev-schema.json.

Schema defines the structure of the package file but does not include all validation rules, as many validations require dynamic, context-dependent checks. To fully validate a package, run mpdev build path-to-your-package.json, which will report all validation errors found in your MPDEV package file. See the Package validation section for details on validation rules and error messages.

Package validation

The MPDEV build command validates the package schema and data before the actual build begins. Validation output can contain warnings and/or errors. At least one error will immediately fail the build, while warnings will allow the build to proceed. It is highly recommended to address all warnings before releasing the package into production. Validation results will be displayed in the command line in the following format:

mpdev: info: Validating package...
mpdev: info: Package validation failed.
mpdev: warning: $.icon | Icon is not provided. Icon can be added as one of the following types - ".ico", ".png" or ".exe".
mpdev: warning: $.msix.shortcuts.0.location | It is not recommended to create a shortcut on the user's desktop as it is their private space.
mpdev: warning: $.msix.shortcuts.0.location | Shortcuts should be located in "C:\ProgramData\Microsoft\Windows\Start Menu\Programs".
mpdev: warning: $.registries.4.key | It is not recommended for applications to write registry in HKLM hive outside of "HKEY_LOCAL_MACHINE\SOFTWARE" and "HKEY_LOCAL_MACHINE\SYSTEM" keys.
mpdev: error: $.fileSystemEntries.0.sourcePath | Field is required.
mpdev: error: $.fileSystemEntries.2.sourcePath | File not found - "C:\\My File.txt".
mpdev: error: $.registries.0.type | Invalid field value - "Foo". Valid values are - "String", "ExpandString", "Binary", "DWord", "MultiString", "QWord".

All command line messages are produced in MSBuild and Visual Studio format, so when built in Visual Studio all messages will be visible in the "Error List" panel. Validation messages can be dissected in the following manner. We will use this validation message as an example:

mpdev: error: $.registries.0.type | Invalid field value - " Foo". Valid values are - "String" , "ExpandString" , "Binary" , "DWord" , "MultiString" , "QWord" .

mpdev: - mpdev app name, required to comply with the MSBuild and Visual studio diagnostic messages format.
error: - validation severity level - error, warning
$.registries.0.type - property path in the package JSON file. Here's what each component means:
- $ - indicates the root level.
- registries - refers to the "registries" property.
- 0 - represents the zero element in the registries array.
- key - the key property within the registries object.
Invalid field value - "Foo". Valid values are - "String", "ExpandString", "Binary", "DWord", "MultiString", "QWord". - this brief text message describes why the validation failed and provides guidance on how to address the issue.