Windows Mobile-based Smartphone Applications Deployment Demystified

 

Microsoft

February 2004

Applies to:
   Microsoft® .NET Compact Framework
   Windows Mobile-based Smartphones
   Windows Mobile 2003 Second Edition software for Smartphones
   Microsoft Visual Studio® .NET 2003

Summary: Discussion surrounds deployment options for mobile applications built using the .NET Compact Framework. We'll concentrate on the use of CabWizSP.exe, the command line tool used to bundle a redistributable file for end users of your application. (7 printed pages)

Download Smartphone 2003 Deployment.msi from the Microsoft Download Center.

Contents

Introduction to Deployment on Smartphones
First Things First
Let's Get to Work!?!
Putting It All Together
A Walkthrough
Wrap-up

Introduction to Deployment on Smartphones

Mobile operators are already introducing Windows Mobile™ 2003 software for Smartphones. This provides an exciting opportunity to build and deploy applications for a new form factor device.

For Microsoft® Visual Studio® .NET 2003 developers, this paper helps you understand how to support deployment to a Smartphone device. The focus will be on the process to create a cabinet file for distribution to Smartphone devices using CabWizSP.exe. Additionally, though it is possible to deploy custom-built applications to an 'Operator Locked' device, this should not be done without some preparation.

First Things First

To understand Smartphone application deployment, you need to be aware of the security execution model under which Smartphone applications run. Each wireless carrier has the ability with Windows Mobile software for Smartphone to customize the security execution environment of devices running on their specific network. The scenario could easily exist where an application may install and execute on a device on one carrier's network while a similar device on another carrier's network has a much more restrictive security policy and the application execution would fail or quite possibly not even install.

There are 3 basic configurations in the security model in Windows Mobile software for Smartphones: Unrestricted, Restricted, and Standard.

  • Unrestricted — Applications install and run on the device regardless of whether they are signed.
  • Restricted — Signed applications install and run while unsigned applications neither install nor run.
  • Standard — Applications that are signed with a certificate install and run without a prompt. Applications that are not signed will still install and run, but the user is prompted in each case.

There is a developer's guide to the Smartphone security model on MSDN that includes information of the options available to a carrier for security policy, which additionally provides guidance on the configuration of your development environment.

If you're thinking about developing applications for Windows Mobile-based Smartphones, you should check out Mobile2Market, which provides a process that helps you take your Pocket PC and Smartphone applications to market.

Let's Get to Work!?!

Ok, let's face the facts. The build command available in Visual Studio .NET does not work well with the Smartphone SDK. The Smartphone 2003 SDK README does indeed point this out. If you're reading this article because you kept getting build errors on your Smartphone application when trying to create the CAB file, you are not alone. Guidance on fixing the files generated by the build command is provided in this MSDN article. This article focuses on building an installation from scratch. It is especially confusing because the Build command indeed does work for Pocket PC and Pocket PC Phone edition Microsoft .NET Compact Framework projects.

When you run the Build command, it generates a number of files. One of these files is buildcab.bat. The buildcab.bat file only contains a single line that makes a call to CabWizSP.exe. There is not much magic going on here. However the command line call to CabWizSP.exe can become so long it is quicker and less error prone to create a batch file rather than type a long command line. The batch file will make your life easier!

The Smartphone SDK installs CabWizSP.exe as part of its tools, which are typically installed to the folder C:\Program Files\Windows CE Tools\wce420\SMARTPHONE 2003\Tools. A sample buildcab.bat will look like this:

CabWizSP.exe AppName.inf /err CabWizSP.err.log /cpu ARMV4 X86

The BuildCab.bat file included with this article looks like this:

"D:\Program Files\Windows CE Tools\wce420\SMARTPHONE 2003\Tools\CabwizSP.exe" "Magic 8 Ball_SMP.inf" /err CabWizSP.err.log

You will notice in the above calls several different command line parameters. There are actually seven different command line parameters available that could be used with CabWizSP.exe to create a cab file. Notice I am building Cab files for both the Smartphone and the Visual Studio emulator using the /cpu flag in the first example. I am also pushing any errors during Cab file creation to the file CabWizSP.err.log. This is in both examples.

The flags are quite self explanatory, however there is a table below that explains them. I would like to point out that you should generally not use the /nouninstall flag. You should always provide an easy way for the user to remove your program from their device. Users may access this dialog from within the Add/Remove Programs dialog box in ActiveSync®, via the menu path Tools -> Add/Remove Programs.

Table 1. CabWizSP.exe Flags*

Flag Description
/dest Destination directory for the .cab files. If no directory is specified, the .cab files are created in the same directory as the .inf file directory.
/err File name for a log file that contains all warnings and errors that are encountered when the .cab files are compiled. If no file name is specified, errors are displayed in message boxes. If a file name is used, the CabWizSP.exe application runs without the user interface (UI); this is useful for automated builds.
/cpu Creates a .cab file for each cpu type that is specified. A cpu type is used in the.inf file to differentiate between processor types.
/platform Creates a .cab file for each platform label that is specified. A platform label is used in the .inf file to differentiate between different platform and processor types.
/prexml Full path and file name to a valid XML file that contains Smartphone provisioning XML that is read by Configuration Manager. This /prexml file is added to the .cab _setup.xml file before the instructions in the .inf file.
/postxml Full path and file name to a valid XML file that contains Smartphone provisioning XML that is read by Configuration Manager. This postxml file is added to the .cab file _setup.xml file after the instructions in the .inf file.
/nouninstall Tells the Smartphone that it should not create an uninstall document for this .cab file. The .cab file will not receive an entry in the Remove Programs screen.

*Taken from Smartphone 2003 SDK Help

I'm not going to discuss pre and post provisioning of a Smartphone device either. They are better served by an article dedicated to Smartphone configuration and provisioning using XML that is achieved through using /prexml and /postxml. Also, I would like readers to be awake and alert upon finishing this document.

Putting It All Together

At this point we are almost ready to actually run the command, but wait, we need to discuss one last topic: how to create an appropriate .inf file for CabWizSP.exe consumption. The information file is very important because it is where you specify several different aspects of your application. It will contain not just metadata, but where to install you application on the device and which shortcuts to create so a user can actually use your program once they have installed it on their device.

Tables, tables, tables; there are quite a few tables in this discussion. It is valuable to have all the information in a single place rather than spending the afternoon, evening, and quite possibly the next few days in the Smartphone 2003 SDK help files. So in keeping with the tables theme, here are a few more tables. These tables are useful background for the installer walkthrough section that follows them.

Table 2. .inf File Sections*

Section Required Description
Version Yes The application's version.
CEStrings Yes String substitutions for application and directory names. The string must be in uppercase.
Strings No String definitions for one or more strings.
CEDevice Yes The device platform for which the application is targeted.
DefaultInstall Yes The default installation of the application.
SourceDisksNames Yes The name and path of the disk on which the application resides.
SourceDisksFiles Yes The name and path of the files in which the application resides.
DestinationDirs Yes The names and paths of the destination directories for the application on the target device.
CopyFiles Yes Default files to copy to the target device.
AddReg No Keys and values that the .cab file will add to the registry on the device.

Note: We recommend that installed applications use the HKCU\Software\ branch of the registry to store information.

CEShortCuts No Shortcuts the cab installer creates on the device upon installation of the application.
Platform No The platform and the platform version number that is valid for selective installations.

* Taken from Smartphone 2003 SDK Help

Table 3. Windows CE® Strings for Smartphone*

Identifier Smartphone Directory
%CE1% \Program Files
%CE2% \Windows
%CE11% \Windows\Start Menu\Programs
%CE14% \Windows\Start Menu\Programs\Games
%CE17% \Windows\Start Menu
%CE18% <default volume, dependent on device configuration>
%CE19% \Application Data

* Taken from Smartphone 2003 SDK Help

That's the end of the data tables, promise. There is one house cleaning fact left. In the previous table, the identifiers actually run %CE1% through %CE20%, those not in the table are not currently used in this release of the Smartphone SDK, but are reserved.

A Walkthrough

Now let's walk through a sample configuration file piece by piece:

[Version]
Signature="$Windows NT$"      ; required as-is
Provider="Microsoft"            ; max of 30 chars, cannot use XML reserved chars
CESignature="$Windows CE$"      ; required as-is

The only part you may change is the Provider string value. You cannot have an empty string nor can you use any of the XML reserved characters like \/:*?" < >|&. Also the string in Provider is concatenated with AppName in the CEStrings section.

[CEStrings]
AppName="Magic 8 Ball"      ; max of 40 chars, no XML reserved chars
InstallDir=%CE1%\%AppName%   ; Installation directory on device

[CEDevice]
VersionMin=4.00            ; required as-is
VersionMax=4.99            ; required as-is

In our example, since Provider is concatenated with AppName we will have the value "Microsoft Magic 8 Ball" show up in the ActiveSync programs list. However, the device will only show o the value contained in AppName, in case you were concerned about long program names showing up on your device. InstallDir is where we install our binary or any other files we may have in our cab file, again, in our case it is "Magic 8 Ball.exe" and it is installed into \Program Files.

If you do not supply a value for InstallDir the cab installer will prompt the user for a location to install your application.

[DefaultInstall]               ; operations to complete during install
CEShortcuts=Shortcuts         ; Create a shortcut
CopyFiles=Files.Common         ; Copy files, in our case "Magic 8 Ball.exe"

[SourceDisksNames]            ; directory that holds source data
1=,"Common1",,"SPEight\bin\Release\"

[SourceDisksFiles]            ; listing of all files to be included in cab
Magic 8 Ball.exe=1

DefaultInstall contains instructions for the cab installer to complete during installation on the device listed in name-value pairs. Acceptable variables are CopyFiles to perform copy operations, AddReg for registry operations, and CEShortcuts to create shortcuts to your binary from the Start Menu.

SourceDisksNames is the location on your computer of the source files where CabWizSP.exe should look to bundle into the cabinet file. Notice I created a relative link in the sample file as show above.

SourceDisksFiles is a name-value pair listing of all the files to be included in the cabinet file paired with their source directories from SourcDisksNames.

[DestinationDirs]               ; default directory destination for each entry
Files.Common=0,%InstallDir%
Shortcuts=0,%CE2%\Start Menu

[Files.Common]               ; alias for use in DefaultInstall above
Magic 8 Ball.exe,,,0

[Shortcuts]                  ; shortcut created in destination directory
Magic 8 Ball,0,Magic 8 Ball.exe,%CE14%

Next comes a listing of the default destinations for our files and shortcuts, this is configured in DestinationDirs.

Files.Common is an example of a user-created section and Shortcuts is the shortcut created. In our case, a shortcut is created in \Windows\Start Menu\Programs\Games, meaning the navigation path to "Magic 8 Ball" would be Start -> More -> Games -> Magic 8 Ball if you install the sample cab file on your phone.

There are many ways a cab file installation might be started:

  • A link from a website, over the air (OTA)
  • An attachment in an e-mail message
  • Copy cabinet file via ActiveSync to \Storage\windows\Start Menu\Accessories, then navigate to cabinet via Start Menu on phone, Start -> More -> Accessories-> Magic 8 Ball_SMP.cab
  • Copy cabinet file to storage media and open in phone

I should mention concerning the last 2 options for installation, once the cabinet file is executed and the Cab Installer has finished it will delete the cabinet file. This is a nice feature of the installer and possibly a gotcha in the case of loading it from storage media as in the last installation option. If you want to maintain a copy of the cab, make it read only before putting it onto the Smartphone.

Wrap-up

All kidding aside, it is quite a simple matter to build a file that is ready to be distributed to Smartphone users. In the future, this process will be supported from within the Visual Studio IDE. Until that happens, you will need to tinker with .inf files and cabwizsp.exe in order to build your own installation files.