Type: object

Package definition used to generate MSI installers.

root version
Type: string

The schema version used for this JSON/YAML document.

The following properties are required:

  • package

root arguments
Type: array of object

Collection of package build-time arguments to be passed to the build command for preprocessing. For an argument named 'host' you can declare $<host> where you want its value to be replaced. Command example: openmsi build --arg host=example.com.

The following properties are required:

  • name
No Additional Items

Each item of this array must be:

root arguments arguments items
Type: object

root arguments arguments items name
Type: string

Name of the argument.

root arguments arguments items defaultValue
Type: string

Value to assume in case the argument is omitted. Default is an empty string.

root package
Type: object

Application package details

root package id
Type: stringFormat: uuid

GUID package identifier. If omitted a new Id will be automatically generated for each build (recommended).

root package productName
Type: string

Name of the product installed by this package. Displayed to user in many places.

root package manufacturer
Type: string

Company or author of the product.

root package description
Type: string

Package and/or description.

root package version
Type: string

Application version in SemVer/Microsoft flavor format: Major.Minor.Build.Revision. Revision is optional. To create an upgrade package, you need a new 'productCode' and a greater 'productVersion'.

root package productCode
Type: stringFormat: uuid

GUID identifying a version or a range of versions which might change with major product upgrades. To create an upgrade package, you need a new 'productCode' and a greater 'productVersion'.

root package upgradeCode
Type: stringFormat: uuid

GUID identifying the product across different installations. Stays constant across all versions of the same product.

root package productLanguage
Type: integer

The application main language code. Default is '1033' (en-US). For more details go to https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-lcid/70feba9f-294e-491e-b6eb-56532684c37f.

root package productIconSource
Type: string

Relative path to the main application icon. Used by Windows when displaying the application information (ARPPRODUCTICON).

root package productComments
Type: string

Short comments about the product. Used by Windows when displaying the application information (ARPCOMMENTS).

root package productContact
Type: string

A description of a point of contact for product support. Used by Windows when displaying the application information (ARPCONTACT). Note that since Windows 10 this information is hidden.

root package productPhoneNumber
Type: string

Phone number for product support. Used by Windows when displaying the application information (ARPHELPTELEPHONE). Note that since Windows 10 this information is hidden.

root package productUrlSupport
Type: stringFormat: uri

Link to a web page with support for the application. Used by Windows when displaying the application information (ARPURLINFOABOUT).

root package productUrlHelp
Type: stringFormat: uri

Link to a web page with help resources about the application. Used by Windows when displaying the application information (ARPHELPLINK).

root package productUrlUpdateInfo
Type: stringFormat: uri

Link to a web page with details about this release or product releases. Used by Windows when displaying the application information (ARPURLUPDATEINFO).

root package productAllowRepair
Type: boolean

Specifies if the application setup supports the 'Repair' option. Used by Windows when displaying the application information (ARPNOREPAIR). Default is false.

root package productAllowChange
Type: boolean

Specifies if the application setup supports the 'Change' option. Used by Windows when displaying the application information (ARPNOMODIFY). Default is false.

root package summaryTitle
Type: string

Package summary title.

root package summaryComments
Type: string

Package summary comments.

root package summaryKeywords
Type: string

Package keywords separated by spaces to help with indexing and searches.

root package properties
Type: object

Package author defined installation properties

root package openMsiProperties
Type: object

Properties used by OpenMSI to provide the built-in wizard templates. You can override these properties. For more information go to <a href='https://openmsi.dev/documentation'></a>.

root package outputFilename
Type: string

The output name to be attributed to the .msi file generated. Optional. Default is '[productname]-installer.msi'.

root assets
Type: array

Collection of files used during installation only. Those files will not be deployed.

 No Additional Items

Each item of this array must be:

root assets assets items
Type: object

root assets assets items name
Type: string

Unique name of the asset for internal references.

root assets assets items source
Type: string

Relative path to the asset file. Common assets file types are *.ico, *.bmp, *.png, *.jpg, *.dll, *.exe, and others.

root files
Type: array

Collection of Application files or directories. Those files will be deployed.

 No Additional Items

Each item of this array must be:

root files files items
Type: object

root files files items source
Type: string

Application file or directory to be deployed. When a directory is specified all sub-directories are included.

root files files items installFolder
Type: boolean

Specifies if a directory should be treated as the install folder. Packages must have exactly one entry with this property set to true. Default is 'false'.

root files files items targetDirectory
Type: enum (of string)

The target directory symbolic name available in Windows Installer options. These are also properties available during installation with the physical path as their value. Default is 'ProgramFiles64Folder'. Tip: Remember you have to escape the backslash character and declare it as an explicitly string: "UserProfile\DesktopFolder"

Must be one of:

  • "CommonAppDataFolder"
  • "MyPicturesFolder"
  • "ProgramFiles64Folder"
  • "ProgramFiles64Folder\\CommonFiles64Folder"
  • "PUBLIC"
  • "TemplateFolder"
  • "UserProfile"
  • "UserProfile\\AppDataFolder"
  • "UserProfile\\DesktopFolder"
  • "UserProfile\\FavoritesFolder"
  • "UserProfile\\LocalAppDataFolder"
  • "UserProfile\\PersonalFolder"
  • "UserProfile\\SendToFolder"
  • "UserProfile\\StartMenuFolder"
  • "UserProfile\\StartMenuFolder\\ProgramMenuFolder"
  • "UserProfile\\StartMenuFolder\\ProgramMenuFolder\\AdminToolsFolder"
  • "UserProfile\\StartMenuFolder\\StartupFolder"
  • "WindowsFolder"
  • "WindowsFolder\\FontsFolder"
  • "WindowsFolder\\System16Folder"
  • "WindowsFolder\\System64Folder"
  • "WindowsFolder\\SystemFolder"

root files files items target
Type: string

Optional file name or directory to which this file or directory should be deployed. Relative and under 'targetDirectory'. If you specify a directory in 'source', default is '[Manufacturer][ProductName]', otherwise if 'source' is a file, default is the 'source' filename inside 'targetDirectory' folder. You can use [Manufacturer] and [ProductName] properties as placeholders. E.g.: [Manufacturer][ProductName]\README.md or \FolderA\NewFilename.txt.

root files files items exclude
Type: array of string

Files or sub-directories relative to 'source' directory you want excluded from the deployable files harvested. For obvious reasons if you specify a file in 'source' you cannot set this property. There is intentionally no support for patterns or globbing. If you have a complex scenario, you might want to execute a Post Publish script to clean the 'source' directory before the installer build.

 No Additional Items

Each item of this array must be:

root files files items exclude exclude items
Type: string

root dialogs
Type: array of object

The YAML UI files describing the installer dialogs, controls, events, and conditions. After OpenMSI bootstrap logic the initial dialog is always 'WelcomeDlg' or 'MaintenanceWelcomeDlg' in case there is an UI.

 No Additional Items

Each item of this array must be:

root dialogs dialogs items
Type: object

root dialogs dialogs items source
Type: string

A Dialog YAML file or directory containing *dialog.yaml files (e.g. *Dialog.yaml, *.dialog.yaml).

root services
Type: array of object

A collection of Windows Services to be deployed.

 No Additional Items

Each item of this array must be:

root services services items
Type: object

root services services items name
Type: string

The Service name (not displayed to users).

root services services items displayName
Type: string

The name displayed to users in Windows Services console, for example.

root services services items description
Type: string

A user visible description of the purpose or purposes of the service.

root services services items serviceType
Type: enum (of string)

The account must be set to 'LocalSystem' or left unset when specifying 'Interactive'.

Must be one of:

  • "OwnProcess"
  • "SharedProcess"
  • "Interactive"

root services services items startType
Type: enum (of string)

The method Windows should use to start this service. Default is Automatic.

Must be one of:

  • "Automatic"
  • "Manual"
  • "Disabled"

root services services items account
Type: string

A valid account name the service should use to Log On.

root services services items password
Type: string

The account password the service should use to Log On.

root services services items executable
Type: string

The executable file name between the specified deployed files to associated with this service. Must be unique between all harvested file names.

root services services items arguments
Type: string

Arguments that should be passed during the associated executable startup command.

root registry
Type: array

Entries to be created in Windows Registry. These entries are automatically turned into installation public properties with the name specified in uppercase.

The following properties are required:

  • root
No Additional Items

Each item of this array must be:

root registry registry items
Type: object

root registry registry items root
Type: enum (of string)

Default is 'CurrentUserOrLocalMachine' (depending on the installation scope).

Must be one of:

  • "CurrentUserOrLocalMachine"
  • "ClassesRoot"
  • "CurrentUser"
  • "LocalMachine"
  • "Users"

root registry registry items key
Type: string

The registry key under which the value should be stored. Writing keys in root is strongly not recommended. Default is 'Software[Manufacturer][ProductName]' or 'SOFTWARE[Manufacturer][ProductName]' depending on the scope of installation, user or machine respectively.

root registry registry items name
Type: string

The registry variable name. Must follow the Windows Registry rules. If not specified the value will be set as Key's default value'. Default is ''.

root registry registry items value
Type: string

The registry value to be written during installation. You can use an existing property (e.g. [ProductVersion] or [MyPackageProperty]). To set a list use the sequence [~] to delimit strings. To change the default string type (REGSZ) use prefixes like: #x (REGBINARY), #% (REGEXPANDSZ), and # (REG_DWORD - number).

root registry registry items property
Type: string

Property name (without brackets; e.g. ProductVersion or MyCustomProperty). If specified there will be an attempt to set the property's value with the corresponding Windows Registry value during upgrades and installations. Default is ''.

root environment
Type: array of object

Installation managed environment variables.

 No Additional Items

Each item of this array must be:

root environment environment items
Type: object

root environment environment items name
Type: string

Environment variable name.

root environment environment items value
Type: string

Environment variable value.

root environment environment items onInstall
Type: enum (of string)

Specifies how handle this environment variable during installation. If 'Remove' is specified and the value is not empty, the environment variable will not be removed unless its value matches the value specified. Default is 'CreateOrReplace'.

Must be one of:

  • "CreateOrReplace"
  • "CreateOrInsertAtStart"
  • "CreateOrInsertAtEnd"
  • "CreateIfNotExists"
  • "Remove"

root environment environment items onUninstall
Type: enum (of string)

Specifies if the environment variable should be removed or not during uninstall. Default is 'Remove'.

Must be one of:

  • "Remove"
  • "Leave"

root environment environment items type
Type: enum (of string)

The type of the environment variable. Default is 'System'.

Must be one of:

  • "System"
  • "User"

root iniFiles
Type: array of object
No Additional Items

Each item of this array must be:

root iniFiles iniFiles items
Type: object

root iniFiles iniFiles items filename
Type: string

The *.ini file name. The directory is always the WindowsFolder symbolic folder (%SystemRoot%). The folder location is a requirement from Windows Installer in order to allow read and write operations during upgrades. Default is 'AppSettings.ini'.

root iniFiles iniFiles items sections
Type: array of object

The .ini file sections.

No Additional Items

Each item of this array must be:

root iniFiles iniFiles items sections sections items
Type: object

root iniFiles iniFiles items sections sections items section
Type: string

The .ini file section name.

root iniFiles iniFiles items sections sections items items
Type: array of object
No Additional Items

Each item of this array must be:

root iniFiles iniFiles items sections sections items items items items
Type: object

root iniFiles iniFiles items sections sections items items items items key
Type: string

The unique by section Key identifying this entry.

root iniFiles iniFiles items sections sections items items items items value
Type: string

The value content for this entry. Value can be a property reference.

root iniFiles iniFiles items sections sections items items items items writeMode
Type: enum (of string)

The way installation should write this entry. Default is 'CreateOrUpdate'.

Must be one of:

  • "CreateOrUpdate"
  • "CreateIfNotExists"
  • "CreateOrAppend"

root iniFiles iniFiles items sections sections items items items items readMode
Type: enum (of string)

The way installation should attempt to read this entry (during upgrades, for example). Default is 'ReadIfExists'.

Must be one of:

  • "ReadIfExists"
  • "Ignore"

root shortcuts
Type: array of object

A collection of Windows shortcuts to be created during the installation process.

 No Additional Items

Each item of this array must be:

root shortcuts shortcuts items
Type: object

root shortcuts shortcuts items name
Type: string

Shortcut name displayed to users.

root shortcuts shortcuts items description
Type: string

A short description to users about this shortcut.

root shortcuts shortcuts items directory
Type: enum (of string)

The symbolic Windows directory where this shortcut will be placed. Default is 'UserProfile\StartMenuFolder\ProgramMenuFolder'.

Must be one of:

  • "CommonAppDataFolder"
  • "MyPicturesFolder"
  • "ProgramFiles64Folder"
  • "ProgramFiles64Folder\\CommonFiles64Folder"
  • "PUBLIC"
  • "TemplateFolder"
  • "UserProfile"
  • "UserProfile\\AppDataFolder"
  • "UserProfile\\DesktopFolder"
  • "UserProfile\\FavoritesFolder"
  • "UserProfile\\LocalAppDataFolder"
  • "UserProfile\\PersonalFolder"
  • "UserProfile\\SendToFolder"
  • "UserProfile\\StartMenuFolder"
  • "UserProfile\\StartMenuFolder\\ProgramMenuFolder"
  • "UserProfile\\StartMenuFolder\\ProgramMenuFolder\\AdminToolsFolder"
  • "UserProfile\\StartMenuFolder\\StartupFolder"
  • "WindowsFolder"
  • "WindowsFolder\\FontsFolder"
  • "WindowsFolder\\System16Folder"
  • "WindowsFolder\\System64Folder"
  • "WindowsFolder\\SystemFolder"

root shortcuts shortcuts items directorySubFolder
Type: string

The subfolder(s) path where this shortcut will be placed. This is a relative path to 'directory'. You might use [Manufacturer] and [ProductName] as placeholders. Default is empty. E.g.: '[Manufacturer][ProductName]'.

root shortcuts shortcuts items targetDirectory
Type: enum (of string)

The symbolic Windows directory where the shortcut target, usually an executable, is set to be placed. E.g.: 'ProgramFiles64Folder'. If the 'target' is an URI, 'targetDirectory' should be empty.

Must be one of:

  • "CommonAppDataFolder"
  • "MyPicturesFolder"
  • "ProgramFiles64Folder"
  • "ProgramFiles64Folder\\CommonFiles64Folder"
  • "PUBLIC"
  • "TemplateFolder"
  • "UserProfile"
  • "UserProfile\\AppDataFolder"
  • "UserProfile\\DesktopFolder"
  • "UserProfile\\FavoritesFolder"
  • "UserProfile\\LocalAppDataFolder"
  • "UserProfile\\PersonalFolder"
  • "UserProfile\\SendToFolder"
  • "UserProfile\\StartMenuFolder"
  • "UserProfile\\StartMenuFolder\\ProgramMenuFolder"
  • "UserProfile\\StartMenuFolder\\ProgramMenuFolder\\AdminToolsFolder"
  • "UserProfile\\StartMenuFolder\\StartupFolder"
  • "WindowsFolder"
  • "WindowsFolder\\FontsFolder"
  • "WindowsFolder\\System16Folder"
  • "WindowsFolder\\System64Folder"
  • "WindowsFolder\\SystemFolder"

root shortcuts shortcuts items target
Type: string

The subfolder path where the shortcut target, usually an executable, is set to be installed. This is a relative path to 'targetDirectory'. You might use [Manufacturer] and [ProductName] as placeholders. Default is empty. E.g.: '[Manufacturer][ProductName]\Demo.App.Service.exe'.

root shortcuts shortcuts items arguments
Type: string

The command-line arguments for the shortcut.

root shortcuts shortcuts items iconSource
Type: string

The *.ico file source to the shortcut icon.

root shortcuts shortcuts items showMode
Type: enum (of string)

The Show command for the application window.

Must be one of:

  • "Normal"
  • "Maximized"
  • "Minimized"

root extensions
Type: array of object

A collection of associations from file extensions to your application.

 No Additional Items

Each item of this array must be:

root extensions extensions items
Type: object

root extensions extensions items extension
Type: string

The extension without the preceding dot users will see associated with the program executable. E.g.: 'dem'.

root extensions extensions items programId
Type: string

A short descriptive program identifier consistent across versions. E.g.: DemoApp.document.

root extensions extensions items description
Type: string

A short description for users about the file type. Usually the meaning of the extension abbreviation.

root extensions extensions items iconSource
Type: string

Use this property if you want to override the default Windows Explorer behavior of showing the handler Icon and instead show a different icon in files associated with the executable handler. IMPORTANT: File extensions icons must be deployed in the same directory of their executable handlers, that means this *.ico must be between the harvested files by 'Files' property.

root extensions extensions items iconIndex
Type: integer

The first image index in the 'multi icon' file in 'iconSource' you want Windows Explorer to show to users for files with this extension. The number of resolutions must match for every icon inside a 'multi icon' *.ico file. It is recommended to provide icons with at least 16x16, 24x24, 32x32, 48x48, and 256x256 resolutions. If 'iconSource' is provided default is '0'.

root extensions extensions items handlerDirectory
Type: enum (of string)

The symbolic Windows directory where the executable handler is set to be placed. E.g.: 'ProgramFiles64Folder'.

Must be one of:

  • "CommonAppDataFolder"
  • "MyPicturesFolder"
  • "ProgramFiles64Folder"
  • "ProgramFiles64Folder\\CommonFiles64Folder"
  • "PUBLIC"
  • "TemplateFolder"
  • "UserProfile"
  • "UserProfile\\AppDataFolder"
  • "UserProfile\\DesktopFolder"
  • "UserProfile\\FavoritesFolder"
  • "UserProfile\\LocalAppDataFolder"
  • "UserProfile\\PersonalFolder"
  • "UserProfile\\SendToFolder"
  • "UserProfile\\StartMenuFolder"
  • "UserProfile\\StartMenuFolder\\ProgramMenuFolder"
  • "UserProfile\\StartMenuFolder\\ProgramMenuFolder\\AdminToolsFolder"
  • "UserProfile\\StartMenuFolder\\StartupFolder"
  • "WindowsFolder"
  • "WindowsFolder\\FontsFolder"
  • "WindowsFolder\\System16Folder"
  • "WindowsFolder\\System64Folder"
  • "WindowsFolder\\SystemFolder"

root extensions extensions items handler
Type: string

The relative path to 'handlerDirectory' to the handler executable. You may use [Manufacturer] and [ProductName] as placeholders. Default is empty. E.g.: '[Manufacturer][ProductName]\Demo.App.Service.exe'.

root extensions extensions items verbs
Type: array of object

At least one verb is recommended.

 No Additional Items

Each item of this array must be:

root extensions extensions items verbs verbs items
Type: object

root extensions extensions items verbs verbs items verb
Type: enum (of string)

The action associated with this file Windows will show to users in Windows Explorer file context menu, for example.

Must be one of:

  • "Edit"
  • "Open"
  • "Print"
  • "PrintTo"
  • "Read"

root extensions extensions items verbs verbs items command
Type: string

The command Window will execute when this verb is selected by users. This property is normally left unaltered. Default '"[#handler-component]"'.

root extensions extensions items verbs verbs items argument
Type: string

The argument passed to the command when this verb is selected by users. This property is normally left unaltered. Default '"%1"'.

root customActions
Type: array of object

Custom actions to be executed during installation. For now, OpenMSI only supports .NET10+ DLLs based code for custom actions. More information: https://openmsi.dev/documentation/custom-actions.

 No Additional Items

Each item of this array must be:

root customActions customActions items
Type: object

root customActions customActions items action
Type: string

Name of the custom action.

root customActions customActions items sourceType
Type: enum (of string)

The type of resource Windows Installer will call. OpenMSI supports Dynamic Link Library (.dll) and Windows Executables (.exe) types.

Must be one of:

  • "DllAsset"
  • "DllDeployed"
  • "ExecutableAsset"
  • "ExecutableDeployed"
  • "ExecutableDeployedDirectory"
  • "ExecutablePath"
  • "Property"

root customActions customActions items schedule
Type: enum (of string)

The sequence position in which this custom action should be executed. Default is 'AfterCostFinalize'.

Must be one of:

  • "AfterCostFinalize"
  • "AfterInstallInitialize"
  • "BeforeInstallFiles"
  • "AfterInstallFiles"
  • "BeforeInstallFinalize"

root customActions customActions items scheduleType
Type: enum (of string)

How Windows Installer should handle the scheduling. Default is 'FirstSequence'.

Must be one of:

  • "Always"
  • "FirstSequence"
  • "OncePerProcess"
  • "ClientRepeat"

root customActions customActions items source
Type: string

Depending on 'sourceType' this property expects different values. DllAsset: the *.dll asset name; DllDeployed: the full file name (symbolic + path-to/file.dll); ExecutableAsset: the *.exe asset name; ExecutableDeployed: the *.exe full file name (symbolic + path-to/file.exe); ExecutableDeployedDirectory: the symbolic directory; ExecutablePath: a property with the full path to the executable. Property: property name without brackets. An example of a symbolic + path folder is 'ProgramFiles64Folder[Manufacturer][ProductName]'.

root customActions customActions items target
Type: string

Depending on 'sourceType' this property expects different values. DllAsset: the *.dll entry point method; DllDeployed: the *.dll entry point method; ExecutableAsset: command line; ExecutableDeployed: command line; ExecutableDeployedDirectory: command line; ExecutablePath: executable full path and arguments; Property: value to set the property in source, another property is allowed ([AnotherProperty]). Command line meaning executable and arguments.

root customActions customActions items condition
Type: string

The condition(s) for this custom action to be executed. Empty means always. Must use Windows Installer conditional statement syntax. For example: 'NOT Installed'. For more information: https://openmsi.dev/documentation/custom-actions.