This tutorial will guide you step by step in using the Windows Mobile/CE features provided by Advanced Installer. You will learn how to create a Windows Mobile CAB project for your mobile application, customize it according to your requirements and eventually build a MSI package that will install the resultant CABs through desktop ActiveSync on a cradled device.

For the rest of this tutorial we shall assume that you have developed a mobile application for one of the oldest and most popular board games, chess. Your chess application features several characteristics:

• It is designed for Windows Mobile Pocket PC devices starting from Pocket PC 2003 Second Edition, being screen orientation-aware.
• The animation and board graphics require a third-party ActiveX control, basically a self-registering DLL module.
• Some registry entries must be made on the target device, providing default game settings.
• You want to associate the ".pgn" extension (Portable Game Notation) with your chess application such that accessing files with this extension through File Explorer on a target device launches the recorded chess game in simulation mode.

• 1. Create project
• 2. Enter application details
• 3. Add files and folders to your project
• 4. Add registry keys and values
• 5. CAB package settings and target platforms specification
• 6. Create file associations
• 7. Build and test the CAB package
• 8. Create and maintain multiple configurations
• 9. Digitally sign CAB packages and included files
• 10. Create desktop ActiveSync installer
• 11. Add mobile application prerequisites to ActiveSync installer

1. Create project

If Advanced Installer is not currently running, launch it by double-clicking a desktop icon or selecting it from the “Start” menu. When the application starts, you will see a dialog where you can choose the type of the project you want to create.

Select “Windows Mobile CAB” and press the OK button. The new project has been created and from now on you will edit it.

Save the project and give it an appropriate name - let's say "MobileChess" for this example.

2. Enter application details

You can specify general details regarding your mobile application in the Product Details page, which should be the active view upon the creation of a new project. Fill the fields in the right pane with the corresponding data, for instance:

In this page you can also specify whether the user will be allowed to choose the installation volume when installing the CAB package on a target device. By default, an application can be installed to main storage memory. However, if secondary storage (such as a storage card) is available, the user can then choose the volume that has adequate free space.

3. Add files and folders to your project

The next step is to add to the project the files and/or folders that compose your application. For this tutorial we shall assume that the application consists of the following files:

• the main executable file "Chess.exe" (compiled for the StrongARM processor)
• a self-registering COM module "SelfRegister.dll", compiled for the same processor type
• 2 text files (with a ".pgn" extension) containing notable recorded chess games in PGN format

Switch to the “Files and Folders” page and select the “Install Directory” item in the tree from the left pane of the view.

Click on the [ Add Files ] toolbar button and select the files of your application. You can also drag & drop files from Explorer in the right list control. After performing this operation, you should obtain something similar to the following:

Once the files are added, their name will appear in the list control from the right-side pane of the view. Double-clicking a particular file or selecting “Properties...” from its context-menu will open the “Edit File” dialog. In the “Properties” tab of this dialog you can change the file name or the source path, as well as set the desired file system attributes on a target device. In the “Options” tab you can set several installation options for a file.

Now double-click on "SelfRegister.dll" or select “Properties...” from its context-menu in order to open the “Edit File” dialog. In the “Options” tab select the “Self-register” checkbox under the “Install Options” group. Press the “OK” button once finished.

Now we shall create a shortcut to the main game executable under the following directory shown in the left tree control: "\Windows\Start Menu\Programs\Games". This directory has the %CE14% associated macro.

In order to create the shortcut follow the steps below:

1. Select the above mentioned folder in the left tree control.
2. Click the “New Shortcut” toolbar button - this will open the “Choose Installation File” dialog.
3. Select "Chess.exe" in this dialog and then click “OK”.
4. This will open the “New Shortcut” dialog.
5. Change the shortcut name to Chess Tutorial.lnk and then press the “OK” button.

4. Add registry keys and values

We shall assume that the following registry values must be created on a target device:

• The first registry value named "Installation Directory" stores the application folder you have defined previously in the Product Details page. This value will be resolved at install-time to the corresponding folder on a target device.
• 2 REG_DWORD registry values, "Difficulty" and "Game mode" - providing default game settings.

Switch to the “Registry” page and select the following registry path in the tree control: "HKEY_LOCAL_MACHINE\Software\%Provider% %AppName%"

Click on the [ New Key ] toolbar button to create a registry key. Edit the key name to "Settings".

Add a value under this new key using the [ New Value ] toolbar button. Clicking this button will open the “New Registry Value” dialog.

In the "Name" text field enter "Installation Directory", the name of your first registry value. In the "Data" field enter "%InstallDir%". Leave the other settings to their default values.

Use the same steps in order to create the other 2 registry values, making sure that you set their type correctly to REG_DWORD. Once all the registry values have been added, you should obtain something similar to the following:

5. CAB package settings and target platforms specification

This section will serve as an introduction for the multiple configurations concept and will focus especially on basic tasks. A subsequent section will expand on the information presented herein, thus showing how more complex requirements can be satisfied.

Suppose that your chess game has these requirements:

• It can be installed only on devices with a StrongARM processor, since all binaries are compiled for this CPU type.
• It is designed for Pocket PC devices starting from Windows Mobile 2003 Second Edition, but it does not run on the SmartPhone platform. You do plan to support the SmartPhone platform in the future - if so, a subsequent section in the tutorial will show you how to maintain and handle multiple configurations.
• Because your application is designed for Windows Mobile 2003 Second Edition and later devices and it is screen orientation-aware, you want to prevent a common installation warning (in order to gain your users' trust).
• Some custom code needs to be executed at install time and thus you have developed a custom setup DLL for this purpose.

We shall focus on each of these requirements one at a time, but in order to do so, you first need to select the “Configurations” page in the left menu.

In this section you will work only with the default configuration which is created at the same time the project itself is created. You can change its name in the tree control to something more meaningful if you wish, but you are not required to.

In the “Media” tab you can specify the output directory and file name for the CAB package, as well as the full path to the custom setup DLL you have developed (the last requirement mentioned above). After performing these steps, you may obtain something similar to the following:

Now switch to the “Target Platforms” tab and select the options shown below:

These settings should be self explanatory as they all fulfil each of our first three requirements, in the order we have introduced them initially.

6. Create file associations

As stated in the beginning of the tutorial, a requirement would be to associate the ".pgn" extension (Portable Game Notation) with your chess game. You can either do this directly by creating the required registry entries in the Registry page, or you can use the specialized view provided by Advanced Installer, which greatly simplifies the task.

Switch to the “File Associations” page and follow the steps below:

1. Click the “New Extension” toolbar button - this will open the “Choose Installation File” dialog.
2. Select "Chess.exe" in this dialog and then click “OK”.
3. This will add a new extension item in the left tree control - edit the extension text to pgn.
4. In the right pane you can enter a description for files of this type and also change the executable that is launched when such a file is accessed through File Explorer on a target device.

After performing these steps you should obtain something similar to the following:

7. Build and test the CAB package

You are now ready to build the CAB package.

Click on the [ Build ] toolbar button - the “Build Project” dialog that appears will show you the overall build progress.

8. Create and maintain multiple configurations

This section will describe more advanced topics related to configuration handling: targeting multiple platforms and device types using a single project, as well as per-configuration resource management.

When creating a new configuration, by default it contains all project resources and has the default project settings. In order to customize it you have the option to exclude various resources from it. You can exclude the following from a configuration:

• Files
• Shortcuts
• Registry values
• File associations

For now, let us assume the following:

• Since the first version of your chess game has been a real success on the Pocket PC platform, many SmartPhone users have requested a version that will run on their devices. As a result, you have ported your chess application to the SmartPhone platform. This of course will require a distinct CAB package installer, because there are different game binaries for the Pocket PC and SmartPhone platforms.
• Secondly, you have also created 2 distinct versions of your game for the Pocket PC platform: one that is intended for the older Pocket PC 2003 Second Edition devices and the other intended for newer devices such as Windows Mobile 5 Pocket PCs. The reason for this change might be your interest in newer technologies such as DirectX and Direct3D Mobile, which are supported only by the latest devices, not by Windows Mobile 2003 Second Edition (who knows only about GAPI - Game API).
• The binaries that compose your chess game are "Chess.exe" and "SelfRegister.dll", as discussed in a previous section.

In conclusion, considering the above assumptions, there will be 3 versions of these binaries: one for Pocket PC 2003 Second Edition devices, one for Windows Mobile 5 Pocket PCs and one for SmartPhone devices. Hence 2 questions may arise at this point:

1. Is it possible to target multiple platforms and device types using the same project - that is, create several CAB packages with distinct settings from a single project?
2. And if so, since there are different binaries (files), is it even possible to specify this within the project?

And from what has been discussed thus far, you probably anticipate that both tasks can be achieved. Do read on in order to find out how.

The first task, targeting multiple platforms and device types with a single project is possible through multiple configurations - in our case there will be a total of 3 configurations, each one intended for a platform and/or device type mentioned above.

Now switch to the “Configurations” page, “Media” tab and follow the steps below:

1. Rename the "Default" configuration to something more meaninful, say "PPC2003SE". The CAB package corresponding to this configuration is intended for Pocket PC 2003 Second Edition devices.
2. For consistency, we want to store the output of each configuration in a distinct folder on disk, so please change the output folder for the "PPC2003SE" configuration to: "C:\ChessTutorial\advinst\output\ppc2003se", for instance. Refer to the first screenshot from this former section for more details about the settings from this tab.
3. Now switch to the “Target Platforms” tab and make sure that only the option "Pocket PC 2003 Second Edition" is selected in the list of device types, as per the above comments. Refer to the second screenshot in the above mentioned section for details.
4. Now we shall create a new configuration for Windows Mobile 5 Pocket PCs. There are 2 ways to achieve this:
   1. You can either create a new configuration using the corresponding toolbar button.
   2. Or you can duplicate the existing one, by selecting the “Duplicate” context-menu option (you need Advanced Installer 7.3 or newer in order to use this feature).
5. Either way, set the options for the new configuration in a similar way as before:
   1. Name: WM5PPC (for instance)
   2. Output folder: "C:\ChessTutorial\advinst\output\wm5ppc"
   3. Processor and Screen Orientation Options: (same as for the initial configuration)
   4. Target Device Types: "Windows Mobile 5 Pocket PC" and "Windows Mobile 6 Pocket PC (Classic and Professional)"

The next step of course is to create the last configuration, the one targeting the SmartPhone platform. Please refer to the following screenshots for details about this:

The “Target Platforms” tab for the "SmartPhone" configuration should look as follows:

The second task, specifying different source file paths per configuration can be achieved fairly easy.

Switch to the “Files and Folders” page and follow the steps given below:

1. Double-click on "Chess.exe" or select “Properties” from its context-menu in order to open the “Edit File” dialog.
2. Select the “Configurations” tab in this dialog. Note that this tab is visible only when there is more than one configuration defined within your project.
3. Select the option “Include file only in the selected configurations” - this will enable the configurations list underneath.
4. When selecting a row in this list control, an ellipsis [ ... ] button will appear at the right list margin.
5. Clicking the [ ... ] button will allow you to browse for a file on your hard-drive. In this way you can change the per-configuration source path for any file included in the project.
6. After performing the necessary modifications for "Chess.exe", you should obtain something like the following:

Performing the appropriate changes for "SelfRegister.dll" (in a similar way) is left as an exercise for the interested reader.

At this point you may build the project and test the resulted CAB packages on the device types mentioned throughout this section.

9. Digitally sign CAB packages and included files

Advanced Installer offers great flexibility in working with a digital certificate within a Windows Mobile CAB project:

1. You can effortlessly sign all the generated CAB packages.
2. Each executable code file (EXE, DLL, OCX etc) can be signed individually.
3. You can choose which CAB package(s) must not be signed (on a per-configuration basis).

Switch to the “Digital Signature” page, specify a software publisher certificate and enter the necessary details in the corresponding fields.

After specifying a digital certificate to be used for signing, you need to select the “Sign the package” option. This will ensure that all CAB packages will be signed, except for those configurations for which the signing has been explicitly disabled. The following screenshot shows an example:

Signing one or more executable code files from the project is fairly easy. Switch to the “Files and Folders” page, select the file(s) that need to be signed in the right list control and then choose “Properties...” from their context menu. In the “Edit File” dialog select “Digitally sign the file” from the “Options” tab.

You can disable signing on a per-configuration basis. Considering the above observation, let us specify that the CAB package intended for the Pocket PC 2003 Second Edition platform should not be signed, as shown below:

10. Create desktop ActiveSync installer

Desktop ActiveSync installations represent the most common delivery mechanism for Windows Mobile/CE CAB packages. Advanced Installer provides a dedicated view which allows you to specify the mobile applications that should be registered with the Windows CE Application Manager.

This is performed automatically when the MSI package is installed. You can specify the order in which the corresponding CAB packages are installed as well as how they are grouped together, in order to achieve the smallest possible number of prompts from the Application Manager (if this is a requirement).

Create a new non-Simple MSI project through the “New Project” dialog (select from the main menu “File -> New”). At least a Professional project type is required in order to use the ActiveSync feature.

Save the project and give it an appropriate name - let's say "MobileChessDesktop" for this example.

Switch to the “Files and Folders” page and add to the project the CAB packages resulted from the 3 configurations we have defined in a previous section.

In our case, we shall add the 3 output subdirectories ("ppc2003se", "smartphone" and "wm5ppc") under the “Application Folder” tree item. You can drag & drop these directories from Explorer, for instance. Each of these directories contains one "MobileChessTutorial.cab" file intended for a distinct platform and/or device type.

After adding the CAB packages, you should obtain something similar to the following:

Now switch to the “ActiveSync” page.

Click on the [ New Application ] toolbar button - this will open the “Choose Installation File” dialog. Select one of the CAB files you have added previously in the Files and Folders page.

The CAB packages targeting the other platforms can be added subsequently to the “CAB Files” list by clicking the [ Add... ] button. Their order can also be changed easily using the [ Up ] / [ Down ] buttons.

The following screenshot shows an example of how you may specify the settings for your mobile application:

It is possible to condition the installation of mobile applications defined within a group and/or activate the debugging dialogs in the Application Manager (for troubleshooting purposes). The default settings are shown below:

Furthermore, by selecting the root “WinCE Application Manager” node, you can alter the global conditions that control if and when the Application Manager executable runs. The default settings are shown in the following screenshot:

You can now build the MSI package and install it. If a device is already connected through ActiveSync, the correct CAB package should be downloaded and installed on it. Otherwise, the mobile application will be transferred during the next device connection.

11. Add mobile application prerequisites to ActiveSync installer

Deploying mobile application prerequisites (.NET Compact Framework, SQL Server Compact etc.) through ActiveSync, can be done in a similar way. The prerequisite software is usually installed on a cradled device before the application itself.

Follow the steps below for each of your prerequisites:

• Add the CAB packages for the mobile application prerequisites in the Files and Folders page.
• Create the required ActiveSync applications and groups in the ActiveSync page.
• Change their installation order and how they are grouped together by using drag & drop in the tree control from the ActiveSync page.

The following is an example of how your project could look like in case you needed to deploy both .NET Compact Framework 3.5 and SQL Server Compact 3.5 together with your application. The order in the tree control, from top to bottom, shows the actual order of installation on a cradled device.

The End

This concludes our tutorial.