|
Building MSIX/APPX Packages
InstallAware may also build your setups as packages, beginning with InstallAware version X9.
InstallAware may build your setups as packages, beginning with InstallAware version X5.
packages are compatible with (October 2017 Update) and later. packages may be built on (July 2016 Update) and later.
packages are compatible with and later. packages may be built on and later.
The following requirements apply to setup projects being built as either or packages:
- At least one file and shortcut must be defined in your setup project, or the conversion will fail.
- Your setup project version must be specified using exactly four digits, such as 1.0.0.0 (this tool does automatically append additional digits where possible).
The following considerations apply to the build process:
- All files and registry keys you are installing as part of your existing setup will be built.
- The tool will intelligently parse file system and registry paths and attempt to replicate the exact structure found within your installation.
- The tool will parse all shortcuts defined in your installation, add them all to your package, and also offer you to choose one shortcut as your entry point application.
- Beginning with InstallAware version X13, the tool also supports service installations as defined by the Install Service command - in which case, entry point applications and/or shortcuts are not required.
- The tool will parse file type definitions in your installation and add them all to your package. Please note that if you have specified file types in your setup manually using Write Registry commands instead of the dedicated Create File Type/Advertised File Type commands, the tool will not recognize such file type definitions automatically. In this scenario, simply replace such Write Registry commands with native Create File Type/Advertised File Type counterparts, and run this tool again after saving your changes.
- Where possible, script variables, such as path variables, will be replaced with their literal values, intelligently resolving to states meaningful for the build process.
- Compiler variables will be substituted with their literal values as found in your InstallAware project file.
- Conditional compilation (excluding parts of your scripts based on compiler variable values) is supported beginning with InstallAware version X6 Creators Update.
- self-registration is supported through Install Files and Register Library commands for libraries which are designated as self-registering, beginning with InstallAware version X8.
- All of your include scripts will be processed.
- Any conditions on script execution will be ignored.
- Your package will be built in 32 bit mode or 64 bit mode based on the bitness of your installation.
- Code signing your package will make use of your own code signing certificate file as stored in your project Build Settings.
- Where your project Build Settings include the option, the contents of your package will be code signed according to the regular meaning of that build option. Please note that the code signing of the actual files being packaged inside your is not controlled by the command line and/or user interface options discussed below; these options only apply to the code signing of the external package itself, and not its contents.
To start the tool, click the , and choose .
Building a MSIX/APPX Package
Start building your package by following the steps below:
- Enter the full path to the InstallAware project to build as a MSIX/APPX package in the field.
- Click the button to begin the build process.
- In the next few moments, the conversion process merges all your setup scripts and parses project content.
Continue creating your package following the sections below.
Select Entry Point Shortcut
In the dialog, choose the shortcut to execute when the button is clicked in your MSIX/APPX setup after installation on target systems.
If you are installing one or more services and have defined no shortcuts, this step may be skipped.
Shortcut
Lists the user visible name of the shortcut.
Check the box next to the shortcut to publish as your package entry point. This shortcut becomes the target of the button displayed in the for your package. Other shortcuts will still be accessible on the target system on the .
Target Path
Lists the native file system folder containing the application launched by the shortcut, to help you identify the correct shortcut during the selection process (actual native file system locations are not accessible from package shortcuts).
Package Parameters
Package Name
Enter the file name of your package file in this field (without any file extension).
Save Converted Package To
Enter the full path of the folder to save your package in this field. You may type in a new folder path, and it will be created automatically.
Target Package Type
Choose either the newest MSIX package format, or the legacy APPX package format. Your selection here influences the minimum operating system your package runs on.
Please note that MSIX packages are unsupported on server platforms, for which only APPX packages are available.
Target Architecture
You may override the target package architecture here, by manually selecting a different architecture in this field.
Please note that typically the detected architecture is accurate, and is based on the contents of your setup script.
Package Extensions
If you will be submitting your application to the , choose .
To create a , supporting deployments, choose .
To include both kinds of package extensions in your package, choose . Do not select this option if you are planning to submit your application to the .
You may override the default minimum and maximum operating system versions your package supports for the platform(s) you have selected by deselecting the check-box, and manually populating the and fields for the relevant platform(s).
MSIX Core
To enable support, choose the MSIX package format, and then check the relevant operating system platforms and choose the minimum and maximum versions. Please note that enabling support makes your package incompatible with submissions.
MSIX Core Runtime Requirements
This tool supports targets () as of InstallAware X11.
MSIX Core Pre-Requisites
As of this writing, runtime installers may be obtained from:
https://github.com/microsoft/msix-packaging/releases
You may use the Application Runtime Wizard, or at a lower level, the (Un)Install MSI Setup command, to install the appropriate MSI packages for your target platforms as part of your installation to enable support on downlevel platforms.
Code Signing Requirements
Before MSIX packages are installed on downlevel platforms, the certificates used to sign them must be installed on the target system using Run Program (or alternately, from an elevated command prompt):
certutil -addstore root <certificate path>
Additionally, you must add your trusted certificate under the .
As of this writing, more details on this process are available at:
https://docs.microsoft.com/en-us/windows/msix/msix-core/deploy-with-msix-core
Distribution and Attributes
Distribution Type
Choose if you will be submitting your package to the . packages cannot be code signed using your own code signing certificate, or they will not be accepted into the . Your package will be automatically signed by as part of your submission process.
Choose if you will be providing your package directly to your end-users for manual installation. packages must be code signed using your own code signing certificate, or end-users will not be able to install them. It is therefore not recommended that you check the box for these types of packages, unless you plan to manually code sign your package after building it. Please note that even if the option is checked, your package will still be unsigned if your project Build Settings have disabled code signing.
Package Attributes
This section contains values which are critical to the acceptance of your package. These values must be typed, or copied and pasted, exactly as they are found in your developer account.
As of this writing:
- If you don't already have a developer account, you may create one at https://developer.microsoft.com/en-us/store/register.
- If you already have your developer account ready, log in to your account at https://developer.microsoft.com/en-us/dashboard/apps/overview, and select the application you are building the package for using the drop-down menu, located immediately below your .
- If you wish to create a new application, or are creating an application for the first time, click https://dev.windows.com/en-us/dashboard/Application/New where you begin by reserving the name for your application.
- Once your application overview is showing (for an existing or newly created application), expand the menu, and choose the submenu to access the required values below.
When building packages, these values are not mandatory, and will be populated using your Project Settings and Build Settings where omitted.
Package/Identity/Name
When building for the , type, or copy and paste, the exact value shown in the section of your app's page. This field is of the form MyCompany.MyProduct.
When building for , specify a unique alphanumeric string in this field. Where omitted, the Product Name found in your project settings will be used.
Package/Identity/Publisher
When building for the , type, or copy and paste, the exact value shown in the section of your app's page. This field is of the form CN=3144A47C-6DFC-444D-8779-BB78B5A9ABB4.
When building for , and code signing is enabled, you may leave this field blank. If not left blank, this field must exactly match the value found in the Subject field of your code signing certificate, or code signing will fail. Leave this field blank to allow the automatic retrieval of this information from the code signing certificate referred to in your Build Settings.
When building for , code signing is disabled, and this field is blank, the Manufacturer found in your project settings will be used to populate this field. If you plan to code sign your package after initially building it without code signing, ensure to enter the exact value found in the Subject field of the code signing certificate which will be ultimately used to sign your package, or the signing will fail.
Package/Properties/PublisherDisplayName
When building for the , type, or copy and paste, the exact value shown in the section of your app's page. This field is of the form My Company.
When building for , specify your company name this field. Where omitted, the Manufacturer found in your project settings will be used.
Product Name
When building for the , type, or copy and paste, (one of) the name(s) you reserved for your product. This field is of the form My Product. Upon acceptance, your application will be displayed in the using the value assigned in this field.
As of this writing, you reserve names for your application by choosing the submenu underneath the menu for your application.
If you have reserved more than one name for your application, type the name you wish to associate this package with. You may later rebuild your package with one of the other names you have reserved, at any time you wish to change the display name of your application in the .
When building for , specify your product name this field. Where omitted, the Product Name found in your project settings will be used.
Display Attributes
This section contains values which are cosmetic in nature.
Description
Type the optional, user friendly description of your package here.
Logo
Type, or click the button to select a JPEG or PNG logo for your package. This logo will be shown when your package is being installed.
When unspecified, a default InstallAware logo will be used.
The logo dimensions are typically 50x50.
Checking for Updates
For MSIX packages only, you may automatically check for package updates.
An file will be generated to facilitate this check. For example, if you are creating a package called , the generated file will be named ; found in the same output location as your MSIX package folder.
For updates to work, this file must be provided to end-users for facilitating the installation, instead of the MSIX package itself. In other words, your end-users must launch this file, instead of the MSIX package, to begin the installation.
The MSIX package and the file must both be hosted on the Internet or on your network. Any time your MSIX package is updated, the file built by this process will also be updated. Both updated files must be refreshed at the location where they are hosted at, for the updates to seamlessly flow through to your end-users.
Generate AppInstaller File for Package Updates
Check this box to enable package update delivery.
HTTPS
Select this radio button to check for package updates over the Internet. The generated file and MSIX package must be downloadable at this location with their original names. In other words, the file names as originally generated must be preserved when you are uploading - this field must only specify the download path for the files, and not include actual file names.
UNC Path
Select this radio button and type the full network path to check for package updates over the network. The generated file and MSIX package must be accessible at this location with their original names. In other words, the file names as originally generated must be preserved when you are copying - this field must only specify the network folder for the files, and not include actual file names.
Update Check Frequency
This field sets the update polling interval.
On Application Launch
Select this radio button to specify that updates should be checked for only upon the launch of the application contained inside the MSIX package.
Hours Between Checks
Select this radio button and type the number of hours to check for application updates. The update location will be polled regularly at the set interval for updates.
The application contained inside the MSIX package does not need to be running with this method of polling.
You may supply any value between and (inclusive) in this field. Please note that supplying here is identical to selecting the radio button above.
Prompt User About the Update
Check this box to allow the end-user to accept or decline the update. The prompt will be shown starting only with (October 2018 Update) and later.
Persisting Package Settings
After filling in the required details above, clicking the button completes package creation and builds your package to the specifications obtained from your source InstallAware project and the details supplied in this tool.
Your settings will be automatically saved into a (new) file with your project name as the file name, and the string literal MPRX as the file extension. When you run this tool in the future, default settings will be loaded from this file, to help accelerate rebuilding the package without having to re-enter all of the individual package creation settings.
When building packages from the command line, the default parameters as described below are replaced with the values contained in the MPRX file.
Building Packages from the Command Line
You may also run the tool from the command line. Every field of the tool has corresponding command line parameters.
The first command line parameter must always be the full path to the InstallAware project file to build (with file extension). If any of your command line parameters include spaces, remember to enclose them within double quote signs on the command line.
The remainder command line parameters may be provided in any order and are described below.
| Parameter | Meaning |
|---|---|
| entrypoint: | Case sensitive and optional. |
| name: | Indicates the file name of the package. |
| output: | Package build folder. May specify a new, non-existent folder. |
| desktop | Add extensions to the package. Required for submission to the . This parameter is implied as the default extension type to use when /desktop, /server, and /both are all unspecified. |
| server | Add extensions to the package. Required for support. Incompatible with submissions. |
| both | Add both and extensions to the package. Incompatible with submissions. Please note that you must use /both instead of using /desktop and /server together on the command line. |
| msixcore: | After the colon, specify none, desktop, server, or both to respectively disable extensions (overriding persisted settings in the MPRX file), add extensions to the package, add extensions to the package, or add both and extensions to the package. Makes the package incompatible with submissions when any extensions to the package have been enabled. |
| architecture: | Optional, used to override the heuristic package bitness detection based on analysis of the setup script. Provide x86 or x64 or arm64 based on the desired CPU architecture you would like to explicitly specify. |
| minverdesktop: | Applicable when extensions are enabled. Specifies the minimum Desktop operating system version required for the package. Must specify a number in the range 0 through 8 after the colon, where 0 indicates , 8 indicates , and similarly for the values in between. The default for this setting is 0 () which is implied when the parameter is omitted. If the minimum operating system requested is , a MSIX package will be built. With any lower value, an APPX package will be built instead. |
| maxverdesktop: | Applicable when extensions are enabled. Specifies the maximum Desktop operating system version allowed for the package. Must specify a number in the range 0 through 8 after the colon, where 0 indicates , 8 indicates , and similarly for the values in between. The default for this setting is 3 () which is implied when the parameter is omitted. |
| minverserver: | Applicable when extensions are enabled. Specifies the minimum Server operating system version required for the package. Must specify a number in the range 0 through 8 after the colon, where 0 indicates , 8 indicates , and similarly for the values in between. The default for this setting is 0 () which is implied when the parameter is omitted. Do not specify this parameter when building MSIX packages as the build will immediately fail. |
| maxverserver: | Applicable when extensions are enabled. Specifies the maximum Desktop operating system version allowed for the package. Must specify a number in the range 0 through 8 after the colon, where 0 indicates , 8 indicates , and similarly for the values in between. The default for this setting is 3 () which is implied when the parameter is omitted. Do not specify this parameter when building MSIX packages as the build will immediately fail. |
| minvermsixcoredesktop: | Applicable when and extensions are enabled. Specifies the minimum Desktop operating system version required for the package. Must specify a number in the range 0 through 3 after the colon, where 0 indicates , 1 indicates , 2 indicates , and 3 indicates . The default for this setting is 0 () which is implied when the parameter is omitted. |
| maxvermsixcoredesktop: | Applicable when extensions are enabled. Specifies the maximum Desktop operating system version allowed for the package. Must specify a number in the range 0 through 3 after the colon, where 0 indicates , 1 indicates , 2 indicates , and 3 indicates . The default for this setting is 3 () which is implied when the parameter is omitted. |
| minvermsixcoreserver: | Applicable when extensions are enabled. Specifies the minimum Server operating system version required for the package. Must specify a number in the range 0 through 3 after the colon, where 0 indicates , 1 indicates , 2 indicates , and 3 indicates . The default for this setting is 0 () which is implied when the parameter is omitted. |
| maxvermsixcoreserver: | Applicable when and extensions are enabled. Specifies the maximum Desktop operating system version allowed for the package. Must specify a number in the range 0 through 3 after the colon, where 0 indicates , 1 indicates , 2 indicates , and 3 indicates . The default for this setting is 3 () which is implied when the parameter is omitted. |
| sideload | Build the package for sideloading. Incompatible with submissions. |
| store | Build the package for submission to the . This parameter is implied as the default target when neither /sideload nor /store is specified on the command line. |
| nosign | Skips code signing the package with your code signing certificate (as obtained from your project Build Settings). This parameter is implied when /store is specified or implied. Not recommended when /sideload is specified, as sideloading requires packages to be signed using your own code signing certificate. |
| identity: | Evaluated exactly as the Package/Identity/Name field described above. |
| publisher: | Evaluated exactly as the Package/Identity/Publisher field described above. |
| publishername: | Evaluated exactly as the Package/Properties/PublisherDisplayName field described above. |
| packagename: | Evaluated exactly as the Product Name field described above. |
| description: | The optional user friendly description of your package. |
| logo: | The optional full path to the JPEG or PNG logo file of your package. |
| appinstaller: | The optional address (string value), polling interval (integer value between and inclusive), and update prompt (either or ) settings for your package. Available for MSIX packages only. Specify using the format for UNC paths and for Internet paths. Please ensure to use double quotes around this entire parameter. |
As long as parameters other than the first command line parameter are specified, the build begins immediately and non-interactively, even in the case of missing parameters. This enables the tool to participate in unattended builds, possibly as part of a larger automated build process, such as batch files.
When parameters are missing, defaults are obtained from the persisted package settings file with the MPRX file extension described above. Where settings are missing in that file, or the file does not yet exist; defaults are sourced from your Project Settings and Build Settings where possible.
Building from the command line does NOT commit any changes to the MPRX file.
Examples:
UwpAppXConv.exe "C:\my installers\my setup.mpr"
In the above example, the tool will prepare to build the setup project at the location . Because no additional switches have been specified, the actual build will not begin until end-user interaction.
UwpAppXConv.exe "C:\my installers\my setup.mpr" /name:PackageName "/output:c:\my installers\appx" /identity:MyCompany.MyProduct /publisher:CN=3144A47C-6DFC-444D-8779-BB78B5A9ABB4 "/publishername:My Company" "/packagename:My Product" /architecture:x64
In the above example, the tool will immediately build the setup project at the location , into an APPX file at the location . The folder specified will be created automatically as part of the build process, if it does not already exist. The package will be built for submission to the , using the reserved product name My Product, under My Company's account, where the package name identity is MyCompany.MyProduct and the package publisher identity is CN=3144A47C-6DFC-444D-8779-BB78B5A9ABB4. The built package will target the / 64-bit architectures, even if the source setup is not 64 bit.
UwpAppXConv.exe "C:\my installers\my setup.mpr" /name:PackageName "/output:c:\my installers\msix" /identity:MyCompany.MyProduct /publisher:CN=3144A47C-6DFC-444D-8779-BB78B5A9ABB4 "/publishername:My Company" "/packagename:My Product" /minverdesktop:4 /maxverdesktop:4
In the above example, the tool will immediately build the setup project at the location , into a MSIX file at the location . The folder specified will be created automatically as part of the build process, if it does not already exist. The package will be built for submission to the , using the reserved product name My Product, under My Company's account, where the package name identity is MyCompany.MyProduct and the package publisher identity is CN=3144A47C-6DFC-444D-8779-BB78B5A9ABB4. The package will require at least as its minimum operating system, and the package indicates that the latest operating system it has been tested against is also .
The tool returns the following codes to indicate success/failure:
- 0: Process completed successfully
- 1: Invalid or missing command line parameter(s)
- 2: Error during process