Creating an installer

To create an installer using the WiX template, complete the following steps. As an example, the steps needed to create the installer for the sample integrating application are described.

  1. Create a working folder.

The steps for creating the installer will be performed in the working folder. For this example, the folder is named “Sample Installer” and is located at the root level.

  1. Copy the template items to the working folder.

The following items from the Installer sample must be copied to the working folder:

 

  1. Rename the template files.

Rename the Template.wxs file to match the completed installer name. For this example, the file was renamed to Develop.wxs, which means that Develop.msi will be the final installer filename.

Rename the Template.wxl file to match the new name for the template project. For this example, the file was rename to Develop.wxl to match the name chosen for the project file.

  1. Copy the files to install into the working folder.

Copy all of the files you want to install into the working folder. These files typically include:

 

  1. Edit the project file for the installer.

Using a text editor, open the project file (.wxs file) for the installer project. You will make changes throughout this file. Areas to edit are indicated by comments in the file. Specify the following:

Product ID   This value is a GUID that uniquely identifies a major version of a product. It is also called the Product Code. This value must be changed for each major release of your product. For instance, version 8.0 and version 9.0 of a product would have different product IDs. Any international editions of a product must also have different product IDs.

Upgrade code   This value is a GUID that identifies the product. This value remains constant throughout the life of the product. The same value must be used in every version of the product that is released.

Upgrade information   This information specifies what previous versions of a product this installer can upgrade. The upgrade code must be added to this section. Also, supply the version number values that specify the maximum (newest) version of your product that this installer can upgrade. Typically, this will be a value large enough to include all previous versions of your product. For example, to upgrade all versions prior to 10, use Maximum='9.9.9'.

Version   A string that indicates the major, minor, build, and revision numbers for the release. The major, minor, and build numbers are significant for comparing versions. Be sure to use them consistently for releases of your product. For example, version 9.0 build 1 revision 0 of a product would have the following version string: '9.0.1.0'

Cabinet file name   This string specifies the name of the cabinet (.cab) file that will be used for the installer. Use a value that corresponds to the installer you’re creating. For example, the cabinet file for the sample installer is “Develop.cab”.

Component entries   The component entries specify the items to be included in the installer. Each item installed for your integration will have a separate component in this section. Each component must be identified with a GUID that remains constant over the life of your product to allow the Windows Installer to properly handle updates. The following are the component entries for the components installed by the sample integration.

<Component Id='Develop.cnk' Guid='EC747C55-814D-4fb8-8DB1-70BF67D5AFEC' DiskId='1'>
	<File Id='Develop.cnk' ShortName='Develop.cnk' Name='Develop.cnk'
	Source='$(sys.CURRENTDIR)\Develop.cnk'/>
	<IniFile Id='GPDICVER_INI' Name='GPDicVer.ini' Directory='INSTALLDIR'
	Action='addLine'  Section='General' Key='Prod3333' Value='1'/>
</Component>

<Component Id='Develop.chm' Guid='8CA10247-7A9C-48e7-9E2C-58B74E36109D' DiskId='1'>
	<File Id='Develop.chm' ShortName='Develop.chm' Name='Develop.chm'
	Source='$(sys.CURRENTDIR)\Develop.chm'/>
</Component>

Notice that for the Develop.cnk component, a value is specified to be written to the GPDictVer.ini file. This value specified should include the product ID and install information slot number you specified when you build the dictionary chunk with Dexterity Utilities.

Feature components   This section specifies which components are included with each feature defined by the installer. The template installer has only one feature defined, so all components will be included in this section. The component IDs listed here must match those you specified in the previous step. The following are the two components included for the sample integration. Notice that the component IDs match those defined in the previous section.

<ComponentRef Id='Develop.cnk'/>
<ComponentRef Id='Develop.chm'/>
  1. Edit the localization file for the installer.

Using a text editor, open the localization file (.wxl file) for the installer project. You will make changes throughout this file. Areas to edit are indicated by comments in the file that state EDIT THESE.

  1. Edit the launch file information.

Using a text editor, open the Data_SetFile.wxi file. This file contains information about what will be written to and removed from the Microsoft Dynamics GP launch file. Edit the following items:

Product ID   This should be the integer product ID you use for your integrating application.

Feature   By default, this will be “Template”. If you changed the feature name in the .wxs project file, you must change this setting to match the name you chose.

Product information   The last group of entries in this file specifies the product information for the integrating application. These entries must match the information that you specified in the Product Information window in Dexterity Utilities when you created your dictionary chunk. For instance, the following entries are used for the sample integrating application’s installer.

<Data Column="PRODID">3333</Data>
<Data Column="NAME">Sample Integrating App.</Data>
<Data Column="APPDIC">Develop.dic</Data>
<Data Column="FRMDIC">F3333.dic</Data>
<Data Column="RPTDIC">R3333.dic</Data>
  1. Edit the CustomActions script file.

Using a text editor, open the CustomActions.vbs script file that is located in the Include folder. At the beginning of this file you will see four constants that must be updated. Edit the following items:

InstallToUpgrade   For this value, specify the Upgrade Code for your integration, with no dashes, prepended with the letters “UC”.

ApplicationDictionary   This value specifies the name of the dictionary from the previous version of the integration. The dictionary must be deleted or moved during the update process, or the dictionary chunk for the new version will not unchunk properly.

The template installer moves the previous version of the dictionary to the “Data” folder and renames it to include the “Prev_” prefix. The dictionary can then be used when upgrading the forms and reports dictionaries.

FormsDictionary   This value specifies the name of the forms dictionary for the integration.

ReportsDictionary   This value specifies the name of the reports dictionary for the integration.

  1. Compile the project.

Open a command prompt. Set the current folder to the working folder where you are building the installer. Use the following syntax with the candle command to compile the installer project:

candle filename.wxs

Replace filename with the name of your installer project file. The command should process, create a .wixobj object file, and not display any errors. If errors are displayed, correct them and compile again.

  1. Link the project.

The linking process creates the .msi installer file and incorporates the localization information. Use the following syntax with the light command to link the installer project:

light filename.wixobj -loc locfile.wxl

Replace filename with the name of your installer project file. Replace locfile with the name of the localization file used for your project. Again, no errors should be reported.

  1. Update the Setup.ini file.

This .ini file provides information to the Setup.msi, indicating the product name and the .msi file to be launched. For example, the following setting are used for the sample integrating application:

[Setup]
PROD_NAME=Sample Integrating Application
PROD_SHORT_NAME=Sample Integrating Application
INSTALL=Develop.msi
  1. Update the license agreement.

The LicenseAgreement.rtf file will be displayed in the installer. The user must agree to the license terms displayed for the installer to continue. Update this file to include the license terms for your integration.

  1. Assemble the components for the installer.

The following components are needed for the completed installer:

 

It’s important that you use the version of the Setup.msi file that matches the version of Microsoft Dynamics GP your integrating application works with. For example, if you are integrating with version 11.0 of Microsoft Dynamics GP, the version information for Setup.msi you use should indicate this. To see the version that Setup.msi works with, position the pointer over the Setup.msi icon and display the tooltip. The version will be indicated in the comment.

[spacer]

  1. Test the completed installer.

The basic installer is complete, and can be tested in a Microsoft Dynamics GP installation. Start the installer by double-clicking the Setup.msi file.

Launch the installer by running Setup.msi, not the installer file you created. Launching your .msi file directly will cause an error.

Documentation Feedback