Master Packager Dev

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.

{ "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-PART-NOTICES.txt", "targetPath": "$.installDir\\THIRD-PART-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": { "thumbprint": "Thumprint_string_from_my_imported_certificate_in_Personal_store.", "timestampServer": "http://timestamp.comodoca.com" }, "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"

Package schema

Package
Common package-level details. Properties in this section will be automatically inherited by all specific packages.
Property NameTypeValidatorsDefaultDescription
outputTypesarray  (string)not empty
valid value - msi, msix
-Package output types.
msiobject (MsiPackage)--MSI package-specific details and common value overrides.
msixobject (MsixPackage)--MSIX package-specific details and common value overrides.
outputDirectorystringpackage required
valid path
-Output directory. Value will be automatically appended with the output type.
outputFileNamestring-Combined value of $.packageName $.version.$.outputType. Example - MyPackage 1.0.0.msi.Output file name without extension. Extension will be automatically added depending on the package being built.
packageNamestringpackage required
-Package name.
publisherstringpackage required
-Package publisher.
versionstringpackage required
valid version
-Package version.
platformstringpackage required
valid value - x86, x64, Arm, Arm64
-Package platform.
installDirstringpackage required
valid path
-Package install directory.
iconstringpackage required
valid icon source
-Source path of an icon file used to provide the icon displayed when installing/uninstalling the package. Supported icon sources include .ico, .png, .exe, and .dll files. To select a specific icon from an .exe or .dll file, append the path with an ,index. For example: "icon": "C:\\MyPackage\\MyApp.exe,2".
compressionLevelstringvalid value - None, Normal, Min, Max
NormalPackage compression level.
fileSystemEntriesarray  (FileSystemEntry)--Directories and files in the package.
registriesarray  (Registry)duplicate registry check
-Registries in the package.
shortcutsarray  (Shortcut)at least one msix shortcut required
-Application shortcuts.
urlShortcutsarray  (UrlShortcut)--Web url shortcuts, a.k.a files with .url extension.
environmentVariablesarray  (EnvVar)--Environment variables.
fileAssociationsarray  (FileAssociation)--File associations.
contextMenuarray  (ContextMenu)validat context menu requirements
-Context menu configuration.
servicesarray  (Service)--Windows service applications.
startuparray  (Startup)--Application startup conditions.
digitalSignatureobject (DigitalSignature)--Digital signature of the package.
MsiPackage
MSI-specific package details. This section defines fields that are specific to MSI packages and provides the ability to override common-level package details, if necessary.
Property NameTypeValidatorsDefaultDescription
cabNamestring-#Disk.cabCabinet name. Determines how the CAB file will be stored and specifies the name by which the CAB file will be referenced within the MSI file. # prefix - embedded, no prefix - outside, empty - noncompressed.
cabSizeInBytesnumber-314572800 bytes / 315 MBSize in bytes of the built cabinet file. Value is ignored for noncompressed builds.
baseMsistringvalid path on disk
The Default.msi file, which comes with Master Packager Dev.The MSI file, which is used as the base for the built package.
upgradeCodestringvalid upgrade code
-The upgrade code is used to search for previous versions of the product that will be uninstalled before installation. It should be the same for different versions of the same product.
secondaryUpgradeCodesarray  (SecondaryUpgradeCode)--Upgrade codes for previous product versions. This section is only required if previous product versions had different upgrade codes in past.
propertiesarray  (MsiProperty)--MSI properties.
iniFilesarray  (MsiIniFile)--MSI INI files in the package.
customActionsobject (MsiCustomAction)unique custom action name
-MSI custom actions in the package.
installDialogobject (MsiInstallDialog)-Default Master Packager Dev install dialog.MSI install/repair/uninstall dialog.
detectRunningProcessesarray  (string)--The MSI engine will automatically detect whether any file installed by the package is currently in use by a running process. The purpose of this section is to provide an additional list of processes that need to be detected before installing the package. Each value provided in this section must be a properly formatted and escaped regular expression that will be tested against the process name and executable path. The detected processes will be displayed in the installer UI.
packageDependenciesarray  (MsiPackageDependency)--MSI package dependencies.
outputDirectorystringpackage required
valid path
-Output directory. Value will be automatically appended with the output type.
outputFileNamestring-Combined value of $.packageName $.version.$.outputType. Example - MyPackage 1.0.0.msi.Output file name without extension. Extension will be automatically added depending on the package being built.
packageNamestringpackage required
-Package name.
publisherstringpackage required
-Package publisher.
versionstringpackage required
valid version
-Package version.
platformstringpackage required
valid value - x86, x64, Arm, Arm64
-Package platform.
installDirstringpackage required
valid path
-Package install directory.
iconstringpackage required
valid icon source
-Source path of an icon file used to provide the icon displayed when installing/uninstalling the package. Supported icon sources include .ico, .png, .exe, and .dll files. To select a specific icon from an .exe or .dll file, append the path with an ,index. For example: "icon": "C:\\MyPackage\\MyApp.exe,2".
compressionLevelstringvalid value - None, Normal, Min, Max
NormalPackage compression level.
fileSystemEntriesarray  (FileSystemEntry)--Directories and files in the package.
registriesarray  (Registry)duplicate registry check
-Registries in the package.
shortcutsarray  (Shortcut)at least one msix shortcut required
-Application shortcuts.
urlShortcutsarray  (UrlShortcut)--Web url shortcuts, a.k.a files with .url extension.
environmentVariablesarray  (EnvVar)--Environment variables.
fileAssociationsarray  (FileAssociation)--File associations.
contextMenuarray  (ContextMenu)validat context menu requirements
-Context menu configuration.
servicesarray  (Service)--Windows service applications.
startuparray  (Startup)--Application startup conditions.
digitalSignatureobject (DigitalSignature)--Digital signature of the package.
MsixPackage
MSIX-specific package details. This section defines fields that are specific to MSIX packages and provides the ability to override common-level package details, if necessary.
Property NameTypeValidatorsDefaultDescription
packageDisplayNamestring-$.packageNamePackage display name.
publisherDisplayNamestring-$.publisherPublisher display name.
packageDescriptionstring--Package description.
capabilitiesarray  (string)valid value - accessoryManager, allJoyn, allowElevation, appointments, backgroundMediaPlayback, blockedChatMessages, chat, codeGeneration, contacts, customInstallActions, documentsLibrary, enterpriseAuthentication, gazeInput, globalMediaControl, graphicsCapture, graphicsCaptureProgrammatic, graphicsCaptureWithoutBorder, internetClient, internetClientServer, lowLevelDevices, musicLibrary, objects3D, offlineMapsManagement, phoneCall, phoneCallHistoryPublic, picturesLibrary, privateNetworkClientServer, recordedCallsFolder, remoteSystem, removableStorage, runFullTrust, sharedUserCertificates, spatialPerception, systemManagement, uiAccess, userAccountInformation, userDataTasks, userNotificationListener, videosLibrary, voipCall
-Capabilities required for the MSIX package. MPDEV will detect and add MSIX capabilities, such as localSystemServices, packagedServices, and allowElevation, based on the package content. However, not all capabilities can be automatically detected. Please use this property to specificy needed capabilities. To specific device capabilties please use deviceCapabilities property instead.
deviceCapabilitiesarray  (MsixDeviceCapability)--Device capabilities required by the MSIX package.
manifeststring--Path to the MSIX manifest. This property is optional, as MPDEV will automatically generate the manifest file based on the package contents. When provided, it will fully override the MPDEV-generated manifest file.
allowExternalContentboolean-FalseAllow external content. Used for building sparse MSIX packages.
psfobject (Psf)--Package Support Framework configuration.
installDialogobject (MsixInstallDialog)-Default Master Packager Dev install dialog.MSIX install/repair/uninstall dialog.
outputDirectorystringpackage required
valid path
-Output directory. Value will be automatically appended with the output type.
outputFileNamestring-Combined value of $.packageName $.version.$.outputType. Example - MyPackage 1.0.0.msi.Output file name without extension. Extension will be automatically added depending on the package being built.
packageNamestringpackage required
-Package name.
publisherstringpackage required
-Package publisher.
versionstringpackage required
valid version
-Package version.
platformstringpackage required
valid value - x86, x64, Arm, Arm64
-Package platform.
installDirstringpackage required
valid path
-Package install directory.
iconstringpackage required
valid icon source
-Source path of an icon file used to provide the icon displayed when installing/uninstalling the package. Supported icon sources include .ico, .png, .exe, and .dll files. To select a specific icon from an .exe or .dll file, append the path with an ,index. For example: "icon": "C:\\MyPackage\\MyApp.exe,2".
compressionLevelstringvalid value - None, Normal, Min, Max
NormalPackage compression level.
fileSystemEntriesarray  (FileSystemEntry)--Directories and files in the package.
registriesarray  (Registry)duplicate registry check
-Registries in the package.
shortcutsarray  (Shortcut)at least one msix shortcut required
-Application shortcuts.
urlShortcutsarray  (UrlShortcut)--Web url shortcuts, a.k.a files with .url extension.
environmentVariablesarray  (EnvVar)--Environment variables.
fileAssociationsarray  (FileAssociation)--File associations.
contextMenuarray  (ContextMenu)validat context menu requirements
-Context menu configuration.
servicesarray  (Service)--Windows service applications.
startuparray  (Startup)--Application startup conditions.
digitalSignatureobject (DigitalSignature)--Digital signature of the package.
FileSystemEntry
File or directory included in the package.
  • If sourcePath is a directory, then targetPath will also be treated as a directory. The sourcePath will be recursively scanned for all files and sub-directories, which will be automatically added to the targetPath directory while preserving the original directory and file name structure.
  • If sourcePath is a file, then targetPath will also be treated as a file. However, you can also provide targetPath as a directory path. If targetPath ends with a "\" character, it will be considered a directory. In this case, the file name from sourcePath will be automatically appended to the targetPath.
  • Concrete sourcePath declarations take priority over recursively detected paths.
  • There are no filters to exclude files from the package, and this is intentional. Our goal is to ensure that the packaged application contains the same files and directories as were tested by the developer. Use post-build events to filter out unneeded files or declare each file individually in this section.
Property NameTypeValidatorsDefaultDescription
sourcePathstringrequired
valid path on disk
-Source path of the file or directory.
targetPathstringrequired
valid absolute path
-Target path of the file or directory.
Registry
Windows registry included in the package.
  • To create a registry with a default value, do not provide a name, or set the name as null or an empty string.
  • Registry values for registry types other than strings follow the same format as in the output of the .reg file. For example, if a decimal 12345 DWORD value in a .reg file is dword:00003039, in the package file it must be provided as 00003039.
Property NameTypeValidatorsDefaultDescription
keystringrequired
valid registry key
-Registry key.
namestring--Registry name. Use null or empty name for default registry name.
typestringvalid value - String, ExpandString, Binary, DWord, MultiString, QWord
StringRegistry type.
valuestring--Registry value as per .reg file value format.
Shortcut
Shortcut (application in MSIX) definition.
Property NameTypeValidatorsDefaultDescription
targetstringrequired
valid path
-Shortcut target.
namestring-File name from the shortcut's $.target property minus the file extension.Shortcut name.
locationstring-%PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs\ or %PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs\$.packageName if there is more than one shortcut in package.Shortcut location.
argumentsstring--Shortcut arguments.
workingDirectorystring--Shortcut working directory.
descriptionstring--Shortcut description.
iconstringvalid icon source
Icon extracted from shortcut's $.target.Source path of an icon file used to provide the icon for the shortcut. Supported icon sources include .ico, .png, .exe, and .dll files. To select a specific icon from an .exe or .dll file, append the path with an ,index. For example: "icon": "C:\\MyPackage\\MyApp.exe,2".
UrlShortcut
Web url shortcuts, a.k.a files with .url extension.
Property NameTypeValidatorsDefaultDescription
namestringrequired
unique url shortcut name
-Url shortcut name.
urlstringrequired
valid http url
-Url shortcut target.
locationstring-%PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs\ or %PROGRAMDATA%\Microsoft\Windows\Start Menu\Programs\$.packageName if there is more than one shortcut in package.Url shortcut location.
EnvVar
Environment variable definition.
Property NameTypeValidatorsDefaultDescription
namestringrequired
-Environment variable name.
valuestringrequired
-Environment variable value.
msiobject (MsiEnvVarConfig)-{ "type": "System", "onInstall": "CreateOrUpdate", "onUninstall": "Remove", "valueAction": "AppendEnd" }Environment variable configuration specific to MSI packages.
FileAssociation
File type association definition.
Property NameTypeValidatorsDefaultDescription
fileTypestringrequired
-File type, a.k.a, file extension without the ".", for example, "txt".
executablestringrequired
-Executable associated with the file type.
iconstringvalid icon source
-Source path of an icon file used to provide the icon for the file association. Supported icon sources include .ico, .png, .exe, and .dll files. To select a specific icon from an .exe or .dll file, append the path with an ,index. For example: "icon": "C:\\MyPackage\\MyApp.exe,2".
progIdstring-Depends on $.fileType property - "$.fileType_auto_file", for example, "txt_auto_file".Prog ID.
verbsarray  (Verb)-[{ "name": "Open", "arguments": "\"%1\"" }]Verbs.
ContextMenu
Windows context menu customizations.
Property NameTypeValidatorsDefaultDescription
fileTypestringrequired
-File type association - "*", "Directory" or any file extension, for example "txt".
executablestringrequired
valid path
-Executable file to invoke via context menu.
namestringrequired
-Display name in the context menu.
iconstringvalid path
-Icon displayed in the context menu. Path to this icon must be an existing file that will be available on the system after installing the package. Supported icon sources are .ico, .exe, and .dll files.
argumentsstring-"%1"Arguments passed when invoking the executable via context menu.
Service
Windows service application definition.
Property NameTypeValidatorsDefaultDescription
namestringrequired
max size - 256
illegal characters - / \
-String that gives the service name to install. The string has a maximum length of 256 characters. The service control manager database preserves the case of the characters in the service name, but comparisons of service names are case insensitive. Forward-slash (/) and back-slash (\) are invalid service name characters.
displayNamestringmax size - 256
-String that user interface programs use to identify the service. The string has a maximum length of 256 characters. The service control manager preserves the case of the display name, but display name comparisons are case insensitive.
executablestringrequired
valid path
valid path in package
-Executable path of the service within the package.
argumentsstring--Command line arguments or properties required to run the service.
startAccountstringvalid service start account
LocalSystemName of the account under which the service is logged on. A service account can be defined as one of the following: "LocalSystem", "LocalService", "NetworkService" or, for MSI packages only, any custom value.For MSIX packages custom service start account values are not allowed. For MSI, if $.msi.serviceType="OwnProcess" use an account name in the form: DomainName\UserName. If the account belongs to the built-in domain it is allowed to specify .\UserName. The "LocalSystem" account must be used if the $.msi.serviceType="ShareProcess" or "$.msi.interactive=true".
startupTypestringvalid value - Auto, Manual, Disabled
AutoSpecifies when to start the service.
descriptionstring--Description for the service being configured.
dependenciesarray  (string)--List of service names or load ordering groups that the system must start before this service.
msiobject (MsiServiceConfig)-{ "loadOrderGroup": null, "errorControl": "Normal", "serviceType": "OwnProcess", "interactive": false, "description": null }MSI package-specific Windows service application configuration.
Startup
Defines application startup conditions.
Property NameTypeValidatorsDefaultDescription
typestringrequired
valid value - OnLogin, AfterInstall
-Startup type.
executablestringrequired
valid path
valid path in package
-Executable to invoke.
argumentsstring--Arguments for the executable.
workingDirectorystring--Working directory.
DigitalSignature
Digital signature information section for signing files within the package, including the package itself.
Property NameTypeValidatorsDefaultDescription
thumbprintstringvalid thumbprint
-Thumbprint of a valid, active certificate with a private key, which is imported into the Personal certificate store. The certificate's thumbprint can be found by checking the properties of the certificate file or, when it's imported, in certmgr.exe app.
generateTestCertificateboolean-FalseIndicates whether a new self-signed certificate must be generated for file signing. Please note that this property is exclusively intended for testing purposes and should not be utilized for production applications.Certificate should be imported to Trusted Root Certification Authorities. The password is empty.
timestampServerstringrequired
valid http url
valid timestamp server
-Url of the timestamp server used in file signing process. Example timestamp servers -
http://timestamp.comodoca.com

http://timestamp.sectigo.com
exclusionsarray  (string)valid regex
-List of file path patterns as RegEx expression that will be excluded during file signing.
SecondaryUpgradeCode
Upgrade codes for previous product versions. This section is only required if previous product versions had different upgrade codes in past.
Property NameTypeValidatorsDefaultDescription
upgradeCodestringvalid upgrade code
unique upgrade code
-Upgrade code for previous product version.
versionstringvalid upgrade version
Current package version taken from $.version property.Previous product version.
MsiProperty
MSI property definition.
Property NameTypeValidatorsDefaultDescription
namestringrequired
-Property name.
valuestringproperty value conditionally required
-Property value. Optional when $.saveOnRepair is set as true.
saveOnRepairboolean-FalseSave on repair.
MsiIniFile
MSI INI file included in the package. Creates new INI file or overrides existing INI file entries included in the $.fileSystemEntries section.
Property NameTypeValidatorsDefaultDescription
targetPathstringrequired
valid path
-Target path of the INI file in the package.
sectionsarray  (MsiIniFileSection)not empty
-INI file sections.
MsiCustomAction
Defines different types of MSI custom actions.
Property NameTypeValidatorsDefaultDescription
exearray  (MsiCustomActionExe)--MSI custom actions with executable files.
dllarray  (MsiCustomActionDll)--MSI custom actions with DLL files.
registerDllarray  (MsiCustomActionRegisterDll)--MSI custom actions that register a DLL with regsvr32 executable.
powershellarray  (MsiCustomActionPowershell)--MSI custom actions with Powershell files.
MsiInstallDialog
Install/repair/uninstall dialog customizations.
Property NameTypeValidatorsDefaultDescription
packageDescriptionstring--Package description. Will be displayed in the main page of the install dialog.
publisherUrlstring--Publisher url, for example, http url to companies website. Will be displayed in the main page of the install dialog.
releaseNotesUrlstring--Release notes url. Will be displayed in the main page of the install dialog.
eulaUrlstring--EULA url. Will be displayed in the main page of the install dialog.
primaryAccentstring--Primary accent color code as Hex RGB, for example, #B2DB9F.
MsiPackageDependency
MSI package dependency. Dependencies will be automatically detected before attempting to install the package. The default detection mechanism will read all applications under the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall and HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall registry keys. It will then match the DisplayValue from the registry against the $.namePattern regex pattern and validate whether the DisplayVersion is the same or higher than $.minVersion. Custom dependency detection logic can be enabled by providing a PowerShell script under the $.detectionScript property.To completely bypass dependency detection, set the MP_SKIPDEPCHECK=1 property when launching the installer.
Property NameTypeValidatorsDefaultDescription
displayNamestringrequired
-Dependency display name. Will be displayed in the installer UI and logs.
namePatternstringrequired
-Dependency name search pattern. Must be a valid regex expression.
minVersionstring--Minimum version of the dependency.
detectionScriptstringvalid path on disk
-Custom PowerShell script for dependency detection. Overrides the default detection mechanism. The script will receive values of $.name, $.displayName, $.minVersion, $.optional properties as arguments and should return true/false value in response where true means the dependency was detected on the machine, and false otherwise.
installobject (MsiPackageDependencyInstall)--Package dependency installation configuration: defines how to install missing dependencies. If this section is left empty, the main package will fail installation when a missing dependency is detected.
MsixDeviceCapability
Defines device capability required by the MSIX package to function properly.
Property NameTypeValidatorsDefaultDescription
namestringrequired
-The name of the device capability, either specified as a friendly name or a device interface class GUID.
devicesarray  (MsixDevice)max size - 1000
-Declares a function for a device that is associated with the device capability.
Psf
Package Support Framework configuration. Please note that if your application (files provided in $.fileSystemEntries or $.msix.fileSystemEntries sections) already contains a file named config.json, the PSF framework will not be enabled.
Property NameTypeValidatorsDefaultDescription
disableboolean-FalseIndicates if usage of Package Support Framework must be disabled.
configFilestringrequired
valid path on disk
-MPDEV will attempt to automatically detect and apply necessary application fixups; however, not all fixups can be identified automatically. This property allows you to supply a custom PSF config file, which will be automatically merged with the applied fixups.
MsixInstallDialog
MSIX install/repair/uninstall dialog customizations.
Property NameTypeValidatorsDefaultDescription
primaryAccentstring--Primary accent color code as Hex RGB, for example, #B2DB9F.
appInstallerDataFilePathstringvalid path on disk
-A valid path to a custom MSIXAppInstallerData.xml file. When this path is set, default MPDEV installer UI and the values of $.primaryAccent and $.eulaUrl will be ignored. How to create a custom App Installer experience
MsiEnvVarConfig
MSI package-specific environment variable configuration.
Property NameTypeValidatorsDefaultDescription
typestringvalid value - System, User
SystemEnvironment variable type.
onInstallstringvalid value - Create, CreateOrUpdate, Remove
CreateOrUpdateActions taken with environment variable during MSI package installation.
onUninstallstringvalid value - Remove, Keep
RemoveActions taken with environment variable during MSI package uninstallation.
valueActionstringvalid value - Replace, AppendStart, AppendEnd
AppendEndActions taken with an existing environment variable during MSI package installation.
Verb
Verb definition.
Property NameTypeValidatorsDefaultDescription
namestringrequired
-Verb name.
argumentsstring--Verb arguments.
MsiServiceConfig
MSI package-specific Windows service application configuration.
Property NameTypeValidatorsDefaultDescription
loadOrderGroupstring--Load ordering group to which this service belongs.
errorControlstringvalid value - Ignore, Normal, Critical
NormalAction taken by the startup program if the service fails to start during startup.
serviceTypestringvalid value - OwnProcess, ShareProcess
OwnProcessSpecifies whether the service runs in its own process or shares a process with other services.
interactiveboolean-FalseAdditional property to specify the serice type. Indicates whether the service interacts with the desktop. It can be used in conjunction with any value of the $.serviceType field. The $.startAccount must be set to "LocalSystem" when using this flag.
startAccountPasswordstringvalid start account password
-Password to the account name specified in the $.startAccount property.
MsiIniFileSection
MSI INI file section definition.
Property NameTypeValidatorsDefaultDescription
sectionstringrequired
-Section name in the INI file.
valuesarray  (MsiIniFileValue)not empty
-Key-value pairs in the INI file, within this section.
MsiCustomActionExe
Defines an MSI custom action that triggers the execution of an executable file at particular stage of the installation.
Property NameTypeValidatorsDefaultDescription
namestringrequired
-Name of the custom action.
filePathstringrequired
valid path
valid file type
-Path to the executable file
argumentsstring--Arguments provided when invoking the executable file.
conditionstring--Custom action invocation condition. Some common conditions are:
  • Awalys execute - null or empty.
  • During installation - NOT Installed
  • During repair - Installed and NOT REMOVE
  • During uninstallation - REMOVE~="ALL"
  • Windows 10 - (VersionNT = 1100 AND MsiNTProductType = 1)
  • Windows 11 - (VersionNT = 1100 AND MsiNTProductType = 1)
  • x86 OS - NOT VersionNT64
  • x64 OS - VersionNT64
For more information on MSI conditions, please refer to the Conditional Statement Syntax guidelines.
sequencestringvalid custom action sequence
EndOfExecutionExecution sequence of the custom action. This property accepts 3 types of values:
  • StartOfExecution - Custom action will be executed at the start of the installation process, before the install/uninstall/repair operations take place.
  • EndOfExecution - Custom action will be executed at the end of the installation process, after the install/uninstall/repair operations have taken place.
  • Any short integer (-32768/32768) - Sequence value can be any short integer. The custom action will be executed at the specified sequence.
continueOnErrorboolean-FalseSpecifies whether the installation should proceed in case an error occurs during the execution of the custom action.
MsiCustomActionDll
Defines an MSI custom action that triggers the execution of a DLL file at particular stage of the installation.
Property NameTypeValidatorsDefaultDescription
namestringrequired
-Name of the custom action.
filePathstringrequired
valid path on disk
valid file type
-Path to the DLL file.
entryPointstring--DLL entry point. Value must match the name of the exported function in the DLL.
argumentsstring--Arguments provided when invoking the executable file.
conditionstring--Custom action invocation condition. Some common conditions are:
  • Awalys execute - null or empty.
  • During installation - NOT Installed
  • During repair - Installed and NOT REMOVE
  • During uninstallation - REMOVE~="ALL"
  • Windows 10 - (VersionNT = 1100 AND MsiNTProductType = 1)
  • Windows 11 - (VersionNT = 1100 AND MsiNTProductType = 1)
  • x86 OS - NOT VersionNT64
  • x64 OS - VersionNT64
For more information on MSI conditions, please refer to the Conditional Statement Syntax guidelines.
sequencestringvalid custom action sequence
EndOfExecutionExecution sequence of the custom action. This property accepts 3 types of values:
  • StartOfExecution - Custom action will be executed at the start of the installation process, before the install/uninstall/repair operations take place.
  • EndOfExecution - Custom action will be executed at the end of the installation process, after the install/uninstall/repair operations have taken place.
  • Any short integer (-32768/32768) - Sequence value can be any short integer. The custom action will be executed at the specified sequence.
continueOnErrorboolean-FalseSpecifies whether the installation should proceed in case an error occurs during the execution of the custom action.
MsiCustomActionRegisterDll
Defines an MSI custom action, that registers a DLL with regsvr32 executable.
Property NameTypeValidatorsDefaultDescription
filePathstringvalid path in package
valid file type
-Path to a DLL that must be registred when a package is installed.
unregisterOnUninstallboolean-TrueIndicates if DLL must be unregistered when the package is uninstalled.
MsiCustomActionPowershell
Defines an MSI custom action that triggers the execution of a Powershell file at particular stage of the installation.
Property NameTypeValidatorsDefaultDescription
filePathstringrequired
valid path on disk
valid file type
-Path to the .ps1 file in package. This path is the source path and must exist on a disk before building the MSI package, as the contents of the script file will be embedded into the MSI.
conditionstring--Custom action invocation condition. Some common conditions are:
  • Awalys execute - null or empty.
  • During installation - NOT Installed
  • During repair - Installed and NOT REMOVE
  • During uninstallation - REMOVE~="ALL"
  • Windows 10 - (VersionNT = 1100 AND MsiNTProductType = 1)
  • Windows 11 - (VersionNT = 1100 AND MsiNTProductType = 1)
  • x86 OS - NOT VersionNT64
  • x64 OS - VersionNT64
For more information on MSI conditions, please refer to the Conditional Statement Syntax guidelines.
sequencestringvalid custom action sequence
EndOfExecutionExecution sequence of the custom action. This property accepts 3 types of values:
  • StartOfExecution - Custom action will be executed at the start of the installation process, before the install/uninstall/repair operations take place.
  • EndOfExecution - Custom action will be executed at the end of the installation process, after the install/uninstall/repair operations have taken place.
  • Any short integer (-32768/32768) - Sequence value can be any short integer. The custom action will be executed at the specified sequence.
continueOnErrorboolean-FalseSpecifies whether the installation should proceed in case an error occurs during the execution of the custom action.
MsiPackageDependencyInstall
Package dependency installation configuration: defines how to install missing dependencies. If this section is left empty, the main package will fail installation when a missing dependency is detected.
Property NameTypeValidatorsDefaultDescription
winGetobject (MsiPackageDependencyInstallWinGet)--Package dependency installation configuration via WinGet.
MsixDevice
Defines device that is associated with the device capability.
Property NameTypeValidatorsDefaultDescription
idstringrequired
max size - 512
-The identifier of the device.
functionsarray  (MsixDeviceFunction)not empty
max size - 100
-List of functions for the device.
MsiIniFileValue
MSI INI file key-value pair definition.
Property NameTypeValidatorsDefaultDescription
keystringrequired
-INI file entry key.
valuestringrequired
-INI file entry value.
actionstringrequired
valid value - CreateOrUpdate, Create, CreateOrAppend
CreateOrUpdateINI file entry MSI actions.
MsiPackageDependencyInstallWinGet
Package dependency installation configuration via WinGet.
Property NameTypeValidatorsDefaultDescription
idstringrequired
-WinGet package ID.
argumentsstring---accept-source-agreements --disable-interactivity --force --exactWinGet package installation arguments.
MsixDeviceFunction
Defines the function for the device.
Property NameTypeValidatorsDefaultDescription
typestringrequired
max size - 100
-The type of function for the device.

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.

Package validators

NameDescription
at least one msix shortcut requiredAt least one $.shortcuts object is required to build an MSIX package.
duplicate registry checkValidates if entries in registries array are unique by registry key and name combination.
illegal charactersValidates that the property's value does not contain illegal characters. The list of illegal characters depends on the property being validated.
max sizeValidates that the property's value does not exceed a specified maximum size. This applies to both string and array properties. The maximum property size depends on the property being validated.
not emptyValidates that the property's value is not empty. This applies to both string and array properties.
package requiredValidates that the property's value is neither null nor an empty string. The value must pass validation at either the common or package-specific level.
property value conditionally requiredSpecific validator for the $.msi.properties.n.value property. The value property is optional if saveOnRepair is set as true.
requiredValidates that the property's value is neither null nor an empty string.
unique custom action nameValidates that the names of all defined custom actions are unique.
unique upgrade codeUpgrade code in $.msi.upgradeCode and $.msi.secondaryUpgradeCodes.n.upgradeCode must be unique.
unique url shortcut nameValidates that the names of all defined url shortcuts are unique.
valid absolute pathValidates that the property's value is a valid aboslute file system path and does not contain any illegal characters. This validator does not check the entry's existence on disk.
valid custom action sequenceValidates that the value of the property is either equal to a StartOfExecution or EndOfExecution string, or any short integer value (-32768 to 32768).
valid file typeValidates that the provided value is a file path with a specific file type.
valid http urlValidates that the property's value is a valid HTTP/HTTPS URL.
valid icon sourceValidates that the property's value is a valid source from which to extract an icon. Valid sources for the property's value include .ico, .png, .exe, and .dll files.
valid pathValidates that the property's value is a valid file system path and does not contain any illegal characters. This validator does not check the entry's existence on disk.
valid path in packageValidates that the property's value is a valid target path pointing to a file included in the package under the fileSystemEntries array.
valid path on diskValidates that the property's value is a valid file path pointing to a file or directory that exists in the provided location.
valid regexValidates that the property's value is a valid regex expression.
valid registry keyValidates that the key property's value is a valid registry key. Valid registry keys must start with: HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CURRENT_CONFIG.
valid service start accountSpecific validator for the $.(msi/msix).services.n.startupType property. Setting a start account that is not LocalSystem, LocalService or NetworkService is only supported by MSI packages.
valid start account passwordSpecific validator for the $.(msi).services.n.msi.startAccountPassword property. Start account password cannot be set when startAccount is LocalSystem, LocalService or NetworkService. Use custom start account value instead.
valid thumbprintSpecific validator for the $.digitalSignature.thumbprint property. Validates that the property's value is a thumbprint of a valid, active certificate with a private key, which is imported into the Personal certificate store.
valid timestamp serverSpecific validator for the $.digitalSignature.timestampServer property. Validates that the property's value is a valid HTTP/HTTPS URL and returns a successful (HTTP Status 200) response.
valid upgrade codeValidatest that upgrade code is not null or empty and is a valid GUID.
valid upgrade versionThe version must follow the following format: Major.Minor.Build. The first field is the major version and has a maximum value of 255. The second field is the minor version and has a maximum value of 255. The third field is called the build version or the update version and has a maximum value of 65,535.
valid valueValidates that the property's value is a valid value. The specific list of valid values depends on the property being validated.
valid versionSpecific validator for the $.(msi/msix).version property. Common and MSI version must follow Major.Minor.Build.Revision format where Major cannot be 0 and Revision is optional. MSIX version must follow Major.Minor.Build.Revision format where Major cannot be 0.
validat context menu requirementsWindows context menu extensions for MSI packages are enabled through the deployment of a sparse MSIX package that provides identity to Win32 applications. To deploy this sparse MSIX package, a digital signature is required. Therefore, this validator checks if the $.digitalSignature section is provided.

Command line options

Usage
mpdev [command] [args] [options]
Available commands
CommandDescription
activateActivates MPDEV license.
buildBuilds MPDEV package from provided package JSON file.
help|/?|-?|/h|-h|--helpOutputs help.
version|--versionOutputs MPDEV version.
activate command
Usagempdev activate [license-key] [--all-users]
Argslicense-key | required | License key string.
Options--all-users | optional | Activates user for all users by storing license file next to executable.
Examplempdev activate eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 -all-users
build command
Usagempdev build [path-to-package-json]
Argspath-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.
Examplempdev build "C:\my-package.json" --properties $.version=1.0.0 $.platform=x86.
Global options
OptionDescription
--verboseEnables 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

Full JSON

{ "outputTypes": [ "string" ], "outputDirectory": "string", "outputFileName": "string", "packageName": "string", "publisher": "string", "version": "string", "platform": "string", "installDir": "string", "icon": "string", "compressionLevel": "string", "fileSystemEntries": [ { "sourcePath": "string", "targetPath": "string" } ], "registries": [ { "key": "string", "name": "string", "type": "string", "value": "string" } ], "shortcuts": [ { "target": "string", "name": "string", "location": "string", "arguments": "string", "workingDirectory": "string", "description": "string", "icon": "string" } ], "urlShortcuts": [ { "name": "string", "url": "string", "location": "string" } ], "environmentVariables": [ { "name": "string", "value": "string", "msi": { "type": "string", "onInstall": "string", "onUninstall": "string", "valueAction": "string" } } ], "fileAssociations": [ { "fileType": "string", "executable": "string", "icon": "string", "progId": "string", "verbs": [ { "name": "string", "arguments": "string" } ] } ], "contextMenu": [ { "fileType": "string", "executable": "string", "name": "string", "icon": "string", "arguments": "string" } ], "services": [ { "name": "string", "displayName": "string", "executable": "string", "arguments": "string", "startAccount": "string", "startupType": "string", "description": "string", "dependencies": [ "string" ], "msi": { "loadOrderGroup": "string", "errorControl": "string", "serviceType": "string", "interactive": false, "startAccountPassword": "string" } } ], "startup": [ { "type": "string", "executable": "string", "arguments": "string", "workingDirectory": "string" } ], "digitalSignature": { "thumbprint": "string", "generateTestCertificate": false, "timestampServer": "string", "exclusions": [ "string" ] }, "msi": { "outputDirectory": "string", "outputFileName": "string", "packageName": "string", "publisher": "string", "version": "string", "platform": "string", "installDir": "string", "icon": "string", "compressionLevel": "string", "fileSystemEntries": [ { "sourcePath": "string", "targetPath": "string" } ], "registries": [ { "key": "string", "name": "string", "type": "string", "value": "string" } ], "shortcuts": [ { "target": "string", "name": "string", "location": "string", "arguments": "string", "workingDirectory": "string", "description": "string", "icon": "string" } ], "urlShortcuts": [ { "name": "string", "url": "string", "location": "string" } ], "environmentVariables": [ { "name": "string", "value": "string", "msi": { "type": "string", "onInstall": "string", "onUninstall": "string", "valueAction": "string" } } ], "fileAssociations": [ { "fileType": "string", "executable": "string", "icon": "string", "progId": "string", "verbs": [ { "name": "string", "arguments": "string" } ] } ], "contextMenu": [ { "fileType": "string", "executable": "string", "name": "string", "icon": "string", "arguments": "string" } ], "services": [ { "name": "string", "displayName": "string", "executable": "string", "arguments": "string", "startAccount": "string", "startupType": "string", "description": "string", "dependencies": [ "string" ], "msi": { "loadOrderGroup": "string", "errorControl": "string", "serviceType": "string", "interactive": false, "startAccountPassword": "string" } } ], "startup": [ { "type": "string", "executable": "string", "arguments": "string", "workingDirectory": "string" } ], "digitalSignature": { "thumbprint": "string", "generateTestCertificate": false, "timestampServer": "string", "exclusions": [ "string" ] }, "cabName": "string", "cabSizeInBytes": 0, "baseMsi": "string", "upgradeCode": "string", "secondaryUpgradeCodes": [ { "upgradeCode": "string", "version": "string" } ], "properties": [ { "name": "string", "value": "string", "saveOnRepair": false } ], "iniFiles": [ { "targetPath": "string", "sections": [ { "section": "string", "values": [ { "key": "string", "value": "string", "action": "string" } ] } ] } ], "customActions": { "exe": [ { "name": "string", "filePath": "string", "arguments": "string", "condition": "string", "sequence": "string", "continueOnError": false } ], "dll": [ { "name": "string", "filePath": "string", "entryPoint": "string", "arguments": "string", "condition": "string", "sequence": "string", "continueOnError": false } ], "registerDll": [ { "filePath": "string", "unregisterOnUninstall": false } ], "powershell": [ { "filePath": "string", "condition": "string", "sequence": "string", "continueOnError": false } ] }, "installDialog": { "packageDescription": "string", "publisherUrl": "string", "releaseNotesUrl": "string", "eulaUrl": "string", "primaryAccent": "string" }, "detectRunningProcesses": [ "string" ], "packageDependencies": [ { "displayName": "string", "namePattern": "string", "minVersion": "string", "detectionScript": "string", "install": { "winGet": { "id": "string", "arguments": "string" } } } ] }, "msix": { "outputDirectory": "string", "outputFileName": "string", "packageName": "string", "publisher": "string", "version": "string", "platform": "string", "installDir": "string", "icon": "string", "compressionLevel": "string", "fileSystemEntries": [ { "sourcePath": "string", "targetPath": "string" } ], "registries": [ { "key": "string", "name": "string", "type": "string", "value": "string" } ], "shortcuts": [ { "target": "string", "name": "string", "location": "string", "arguments": "string", "workingDirectory": "string", "description": "string", "icon": "string" } ], "urlShortcuts": [ { "name": "string", "url": "string", "location": "string" } ], "environmentVariables": [ { "name": "string", "value": "string", "msi": { "type": "string", "onInstall": "string", "onUninstall": "string", "valueAction": "string" } } ], "fileAssociations": [ { "fileType": "string", "executable": "string", "icon": "string", "progId": "string", "verbs": [ { "name": "string", "arguments": "string" } ] } ], "contextMenu": [ { "fileType": "string", "executable": "string", "name": "string", "icon": "string", "arguments": "string" } ], "services": [ { "name": "string", "displayName": "string", "executable": "string", "arguments": "string", "startAccount": "string", "startupType": "string", "description": "string", "dependencies": [ "string" ], "msi": { "loadOrderGroup": "string", "errorControl": "string", "serviceType": "string", "interactive": false, "startAccountPassword": "string" } } ], "startup": [ { "type": "string", "executable": "string", "arguments": "string", "workingDirectory": "string" } ], "digitalSignature": { "thumbprint": "string", "generateTestCertificate": false, "timestampServer": "string", "exclusions": [ "string" ] }, "packageDisplayName": "string", "publisherDisplayName": "string", "packageDescription": "string", "capabilities": [ "string" ], "deviceCapabilities": [ { "name": "string", "devices": [ { "id": "string", "functions": [ { "type": "string" } ] } ] } ], "manifest": "string", "allowExternalContent": false, "psf": { "disable": false, "configFile": "string" }, "installDialog": { "primaryAccent": "string", "appInstallerDataFilePath": "string" } } }
Subscribe to our newsletters