Smartphone 2003应用程序的打包安装

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.

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*

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*

* Taken from Smartphone 2003 SDK Help

Table 3. Windows CE® Strings for Smartphone*

* 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.