| Introduction If you have ever developed an application that is intended to be shipped and distributed to an end user machine, you know how important it is to create an installer that takes care of all the details required to have that software work perfectly. Creating such an installer for a Palm conduit is no easy task, and I hope to give you a good run through of exactly how to do it. We will first list our requirements for the application itself, then cover exactly what we need to do to install the conduit correctly. Once that is done, we will add the installer application to our solution within VS .NET and test the installation on our machine. Installer Requirements There are two main sections required for our installer to function correctly. The first deals with our application's specific requirements, what files need to be installed for our conduit, etc., and the second deals with requirements for registering our conduit with the Palm application on the desktop so the synchronization process knows it needs to call our application during its execution. Application Requirements
In order for the actual conduit application to work correctly we must ensure a few things: - The proper version of the .NET Framework is installed. If not, the installer attempts to install the redistributable of the required version.
- The assembly (PBlgConduit.exe) is on the target machine.
- The actual palm application (PalmBlog.prc) is on the target machine.
- The support files for the Palm application (NSBRuntim.prc) is on the target machine.
Conduit Requirements
There is an important CHM file that ships with the CDK documentation to help us outline these requirements, "CDK403\Com\Docs\COMSyncCompanion.chm". In section 4 of that document (Titled "Writing an Installer"), the sub section "Installer Tasks" covers most of the theory behind what we need to do. Here is a summary from that document: - Run the PalmCOMInstaller.exe on the user's system. This mini-installer installs the COM Sync objects required by your COM-based conduit and registers them with Windows.
- Register your conduit with HotSync Manager by using the Conduit Manager, PDCondMgr.RegisterConduit (required for any conduit).
- Restart or refresh HotSync Manager (after you register your conduit) by using PDHotSyncUtility.RestartHotSyncMgr or RefreshConduitInfo (required for any conduit).
- Queue databases or applications to be installed on the handheld (or files to be installed on handheld expansion cards) during the next HotSync operation by using PDInstall.InstallFileToHH or InstallFileToSlot (required for any databases or files to be put on the handheld).
Now that we have our requirements laid out we will need to create a project that we can execute to perform the above steps during the installation process. Let's add a new C# Windows Application named "ManagedConduitInstaller" to the solution. We choose a Windows Application because we want to also provide a selection box for the user to choose the appropriate person for the hand-held
synchronization process. Often a single machine can be used to synchronize multiple users' Palm devices. We will replace the Main() method in the Windows Form application with our own custom code to perform the installation; this will give us the ability to optionally show dialog. Refer back to the documentation (COMSynchCompanion.chm) and take a look at the section titled "Using PDCondMgr and PDConduitInfo Objects" (Under "4. Writing an Installer", "Code Samples for Registering a COM-Based Conduit"). Here is the appropriate Visual Basic code we need to execute to install our conduit. However, we will need to convert the code into managed C#. Consider reviewing all of the code for this project, including the UI elements for selecting a specific user. Notice how I'm taking the arguments passed into the Main() method and parsing them into the appropriate variables and then calling the RegisterConduit method with those variables. Essentially this allows the project to be reused for any Palm conduit installation. Later we will see how to interact with this project. For your reference I have included the RegisterConduit Method in figure 1.1 below. Figure 1.1 The upgraded RegisterConduit() method in Managed C# publicstaticbool RegisterConduit(string sCreatorID, string COMClassID, string DeskTopDataDirectory, string DeskTopDataFile, string DisplayName, string FileName, string HandHeldDB, int Priority, string JavaClassName, string JavaClassPath, string installFileToHH, string installPath) { //lets first copy all the files over
to the Palm folder PDStandardLib.PDInstallClass install = new PDStandardLib.PDInstallClass(); string home =
install.GetPath(PDStandardLib.EPDPathType.EPDPathHome); int lCreatorID=0; PDStandardLib.PDCondMgrClass mgr = new PDStandardLib.PDCondMgrClass(); PDStandardLib.PDConduitInfo info = new PDStandardLib.PDConduitInfoClass(); PDStandardLib.PDHotSyncUtilityClass util = new PDStandardLib.PDHotSyncUtilityClass(); lCreatorID=mgr.StringToCreatorID(sCreatorID); //' Make sure a valid CreatorID
could be retrieved from the string. if(lCreatorID==0) { MsgBox("CreatorID '" + sCreatorID + "'
was invalid."); returntrue; } //' Set the conduit entries info.COMClassID=home + @"\" + COMClassID; //"c:\palm\pblgconduit.exe"; info.CreatorID=lCreatorID; info.DeskTopDataDirectory=DeskTopDataDirectory;// "PalmBlog"; info.DeskTopDataFile=DeskTopDataFile; //"PalmBlog"; info.DisplayName=DisplayName; //"Palm
Blog"; info.FileName=FileName; //"PalmBlog"; info.HandHeldDB=HandHeldDB; //"PalmBlog.prc"; info.Priority = Priority; //2; info.JavaClassName=JavaClassName; info.JavaClassPath=JavaClassPath; mgr.RegisterConduit(info); util.RefreshConduitInfo(); if(installFileToHH!=null && installFileToHH!="") { Form1 form = new Form1(); form.installFileToHH=home + @"\" +
installFileToHH; Application.Run(form); //installFileToHH returnfalse; } returntrue; } Creating the Installation Project Right click on the solution in the Solution Explorer and choose "Add", "New Project...". Under the section titled "Setup and Deployment Projects" choose "Setup Wizard" and give it the name "PalmBlogInstaller". This should take you step by step through a wizard: - The first step it just an introduction; hit next.
- Step 2 gives us four options, divided into two groups. We want to choose the (default) first option out of the first group ("Create a setup for a Windows Application"), and hit next.
- Step 3 gives us the options for items we want to include during the installation process. I have chosen the following:
a. Primary output from PblgConduit
b. Primary output from PalmDBImporter
c. Primary output from ManagedConduitInstaller - Step 4 give us the ability to choose additional files to add during the install. This is where we will add a few files:
a. PalmBlog.prc
b. PalmCOMInstaller.exe that ships with the CDK
c. NSBRuntime.prc - Complete the wizard.
Once you hit "Finish" for the wizard, it should create the project for you. It should also pop up a warning dialog box telling you that two dependencies relating to the COM conduit cannot automatically be determined. We will not need to worry about this because the PalmCOMInstaller will take care of those files; just hit ok. Once that is finished, you should see a tree on the left with a few folders listed. Click the "Application Folder" item to view what files will be installed into the target machine's application folder. Notice that it did bring all of the references and assemblies from the original project into this folder. This should satisfy all the application requirements for our installer. Let's now work on getting the conduit requirements satisfied. We first need to make sure that the PalmCOMInstaller.exe gets called. To do this, in the Solution Explorer, click on the actual node of the PalmBlogInstaller project. You should see some new icons shown at the top of the Solution Explorer, "File System Editor", "Registry Editor", "File Types Editor", "User Interface Editor", "Custom Actions Editor", "Launch Conditions Editor". Choose the "Custom Actions Editor" button. Now you should see a different tree to the left, with a root node of "Custom Actions" and a child named "Install". Right-click this node and choose "Add Custom Action". Within the application folder you should be able to add the PalmCOMInstaller.exe file. Next, view the properties for that new item in the tree. You should see the property "Arguments". Let's plug in the appropriate arguments found in the readme.txt file that shipped with the CDK: "-s -a -s" This set of parameters will suppress or silence all dialogs associated with the installation execution. Next we need to register the conduit within the synchronization process. For this we will use the project we created above, the ManagedConduitInstaller. Using the "Custom Actions Editor", add a custom action for our "Primary output from ManagedConduitInstaller (Active)" project. We will need to set the "Arguments" property: COMClassID="PBlgConduit.exe"
CreatorID=PBlg DeskTopDataDirectory=PalmBlog DeskTopDataFile=PalmBlog.dat
DisplayName="Palm Blog" FileName=PalmBlog.dat HandHeldDB=PalmBlog.pdb
installfiletohh="PalmBlog.prc" installpath="[TARGETDIR]" Notice how we are only using a space-separated string list of each name/value pair that we need to send to our installer. Also notice that if you want to have a name in one of the items sent, enclose its value in parenthesis ("). Now that we have setup the installer to meet all of our requirements, we will need to test the installation. Testing the Installation Once you are ready to test the installer, right click that project and choose "Rebuild". This will rebuild all the necessary projects, create the installer needed (including all of the other necessary files), and package all of it up into one installer. Once you are successful at building the project, you should see "Install" when you right click the installer project again. Choose it to test the installer. You should first be prompted for a destination folder; choose your main Palm folder. You will then see the PalmCOMInstaller.exe being executed and finally our ManagedConduitInstaller project should run. If either ManagedConduitInstaller project does not run, check its properties in the Custom Actions screen; make sure that the "Installer" property is set to "False". If you have any problems with the install, right click the same project and choose "Uninstall", try to determine what the problem is, rebuild, and then install again. You should be able to install and uninstall over and over until you are satisfied with the results. In order to ensure that the ManagedConduitInstaller is working and installing our conduit correctly, simply open up the CondConfig.exe tool that ships with the CDK. There should be an entry for our PBlg Creator ID. Within this tool you can edit or delete the entry for the PBlg Creator ID in order to test that the installer is working. Also note that if you do set the COM conduit path to something like VS .NET's executable (devenv.exe), it will launch VS .NET itself and allow you to choose the correct solution and then debug that solution, all within the synchronization process. Conclusion Creating the installer is a fairly painless step in the entire application development process. Of course this will change as your application grows, and the installer needs to perform more complex operations and support more operating systems. There will be some issues with testing it to ensure that it is working on all targeted OSes, but I will leave that up to you to sort through. If you have any problems or issues with this or any other article I have written, feel free and contact me at any time. About the Author Robert Chartier has developed IT solutions for more than nine years with a diverse background in both software and hardware development. He is internationally recognized as an innovative thinker and leading IT architect with frequent speaking engagements showcasing his expertise. He's been an integral part of many open forums on cutting-edge technology, including the .NET Framework and Web Services. His current position as vice president of technology for Santra Technology (http://www.santra.com) has allowed him to focus on innovation within the Web Services market space. He uses expertise with many Microsoft technologies, including .NET, and a strong background in Oracle, BEA Systems, Inc.'s BEA WebLogic, IBM, Java 2 Platform Enterprise Edition (J2EE), and similar technologies to support his award-winning writing. He frequently publishes to many of the leading developer and industry support Web sites and publications. He has a bachelor's degree in Computer Information Systems. Robert Chartier can be reached at rob@santra.com.
|
