Using the Application Manager

Send Feedback

The Application Manager application, CeAppMgr.exe, is installed when a user installs ActiveSync and resides on the user's desktop computer. The Application Manager handles the installation and removal of applications on a Windows CE–based device. CeAppMgr.exe takes as input an initialization (.ini) file that describes the CAB file containing the application to be installed on the device. For more information on CAB files, see Walkthrough: Packaging a Smart Device Solution for Deployment. For more information on the .ini file format, see Creating an .ini File for the Application Manager.

While debugging your CAB and .ini files, you can test the installation of your application by invoking the Application Manager from the command line. The location of the CeAppMgr.exe can be found in the default registry value of the desktop registry key: HKLM\software\Microsoft\Windows\CurrentVersion\App Paths\CEAppMgr.exe. When you launch the application, you must provide the full path to your .ini file, and if the path contains spaces, it must be contained within quotes. The following is an example command line invoking the Application Manager.

"C:\Program Files\Microsoft ActiveSync\CEAPPMGR.EXE" "C:\temp\HelloWorld.ini".

You can use the "/report" switch to activate the Application Manager's debugging dialogs.

Creating an Installation Application

When deploying your application, you will want to create an installer that will invoke the Application Manager and install your application on the user's device. The following section will walk you through the creation of an installation application. You can create this installer within the existing Microsoft Visual Studio 2005 solution for your application.

  1. Add a new project for your solution. Make sure that the Solution Explorer for your project is visible. On the File menu, point to Add, and then click New Project. You can create your installer in native or managed code. For this example, choose a Visual C#-based Windows Application project.

  2. Add the CAB file and the .ini file for your application to the installer project as resources. Later, these will be written to the user's computer and passed to the Application Manager.

    Right click the icon for your installer project in the Solution Explorer.Select Add and then Existing Item.... Browse for your CAB file and click Add. You will have to select All Files from the file type filter drop down to see it. Repeat the same process to add your .ini file.

    After the file has been added to the project, you should see it in the Solution Explorer in the heirarchy under your installer project. Right click the icon for your CAB file and choose Properties. In the Properties window from the Build Action drop down list, choose Embedded Resource. This will add your CAB file as a binary resource to the installer's assembly. Do the same for your .ini file.

  3. Customize the user-interface (UI) for the installer application. If the form designer is not visible, right click the default form, usually "Form1.cs", and select View Designer. The following figure illustrates the UI for this example.

    All of the UI elements are added to the form by dragging them from the Toolbox window. First, create a TextBox that will be used to specify the directory that will be used to temporarily store the CAB and .ini files. Create a button next to the text box that will be used to allow the user to browse for a temporary directory. Drag a FolderBrowserDialog object from the Toolbox window onto your form. It will not appear on the form itself, but instead will appear in a pane below the form. Next, add two buttons. One should be labeled "Install" and the other, "Cancel". Finally, add some Labels to provide the user with instructions and to label the text field.

  4. Now you should add some handler methods for the general UI components. Double-click the Cancel button in the form designer window. This will open the code view window for the form and autogenerate a click event handler for the button. The following code example simply terminates the application if the user clicks Cancel.

    private void cancelButton_Click(object sender, EventArgs e)
    {
      Application.Exit();
    }
    

    Next, add code that will allow the user to browse for a temporary directory. Switch back to design view and double click on the browse button next to the TextBox to autogenerate a click event handler. The following code example show the implementation of this handler. It launches the folder browser dialog box, and if the user chooses a new folder, it sets the value in the temporarty directory TextBox.

    private void BrowseButton_Click(object sender, EventArgs e)
    {
      if (folderBrowserDialog1.ShowDialog() == DialogResult.OK)
          tempDirectoryTextBox.Text = folderBrowserDialog1.SelectedPath;
    }
    

    Finally, as a nicety, add a line of code to the form's constructor setting the value of the TextBox to the user's temp directory. Before doing this, you should add the directive using System.IO; to the top of your .cs file.

    public Form1()
    {
      InitializeComponent();
      tempDirectoryTextBox.Text = Path.GetTempPath();
    }
    
  5. Now you should add a helper function that will read the CAB and .ini files from the Assembly's resources and write them to the temporary directory. This method will take three arguments, the directory to which the files will be written, the name of the resource to be written, and the filename that will be used when creating the file. The following example shows the implentation of this helper function.

    public void WriteResourceToDisk(string path, string resourceName, string fileName)
    {
      // Open a Stream that will be used to read the resource
      Stream resourceStream = System.Reflection.Assembly.GetExecutingAssembly().GetManifestResourceStream(resourceName);
    
      // Determine the length of the stream.
      long lengthInBytes = resourceStream.Length;
    
      //Create a BinaryReader to read the stream
      BinaryReader sr = new BinaryReader(resourceStream);
    
      //Create a BinaryWriter that will write the stream to disk
      BinaryWriter sw = new BinaryWriter(File.Create(path+fileName));
    
      //Write the stream
      sw.Write(sr.ReadBytes((int)lengthInBytes));
    
      //Close both the read stream and the write stream
      sw.Close();
      sr.Close();
    }
    
  6. The final step in creating the installer application is to invoke the Application Manager and point it to the .ini file for your application. This functionality will be implemented in the click event handler for the Install button. To create this handler, switch to design view and double click the button.

    The first task the handler will perform is to get the temporary directory name from the form's TextBox and write the .ini file and the CAB file to disk using the helper function defined in the previous step. The name of the resources will be their filenames prepended with your installer application's name followed by a period. For example, "MyInstallApp.HelloWorld.CAB". If while debugging your installer, you see that the resource is not being found, you can call the System.Reflection.Assembly.GetExecutingAssembly().GetManifestResourceNames method to determine the names of your resources.

    Next, your install method will need to query for the path of the CeAppMgr.exe executable. This is done by opening the HKLM\software\Microsoft\Windows\CurrentVersion\App Paths\CEAppMgr.exe registry key using the Microsoft.Win32.Registry.LocalMachine.OpenSubKey method. If the registry key cannot be opened (the returned key RegistryKey object is null) it means that ActiveSync is not installed on the user's machine and the Application Manager cannot be run.

    After you have verified that ActiveSync is installed and determined the path to CeAppMgr.exe, you should invoke the application manager by creating a new System.Diagnostics.Process object. After creating the object, set the StartInfo.FileName property to the CeAppMgr.exe path and the StartInfo.Arguments property to the path to your .ini file. Remember to include quotes around this value as the path the user specifies may contain spaces. For debugging purposes, you can enable Application Manager debugging dialogs by prepending the "/report" command line argument to your .ini path.

    The following code example shows the implementation of the Install button click handler that invokes the Application Manager.

    private void installButton_Click(object sender, EventArgs e)
    {
      // Get the tempPath from the form's text box
      string tempPath = tempDirectoryTextBox.Text;
    
    ..// Write the CAB and .ini files to disk using the helper function
      WriteResourceToDisk(tempPath, "MyInstallApp.SmartDeviceCab1.CAB", "SmartDeviceCab1.CAB");
      WriteResourceToDisk(tempPath, "MyInstallApp.HelloWorld.ini", "HelloWorld.ini");
    
    ..// Open the Application Manager registry key
    Microsoft.Win32.RegistryKey key = Microsoft.Win32.Registry.LocalMachine.OpenSubKey("Software\\microsoft\\windows\\currentversion\\app paths\\ceappmgr.exe");
    
    ..// Check to see if the key was opened
      if (key != null)
      {
          // Get the path from the key's default value
          string appPath = key.GetValue(null).ToString();
    
          // Make sure that the path is not empty
          if (appPath != null)
          {
    
              // Create a new Process object
              System.Diagnostics.Process process = new System.Diagnostics.Process();
    
              // Set StartInfo.FileName to the Application Manager path
              process.StartInfo.FileName = appPath;
    
              // Set StartInfo.Arguments to the .ini file path
              process.StartInfo.Arguments = "\"" + tempPath + "helloWorld.ini\"";
    
              // Or start it with Application Manager debugging enabled
              // process.StartInfo.Arguments = "/report \"" + tempPath + "helloWorld.ini\"";
    
              // Start the process to invoke the Application Manager
              process.Start();
    
              // Wait for Application Manager to finish
              while (!process.HasExited) { }
          }
      }
      else
      {
          // The registry key was null.  ActiveSync is not installed.
          // Show an error message.
          MessageBox.Show("This machine does not have ActiveSync installed.");
      }
    
      // Delete the temporary files
      File.Delete(tempPath + "SmartDeviceCab1.CAB");
      File.Delete(tempPath + "helloWorld.ini");
    
      // Quit the installer application
      Application.Exit();
    }
    

Additional Considerations

In the interest of making the code examples presented in this topic concise and readable, robust error checking has been omitted. When creating your installer application, you should consider the errors and exceptions that could be thrown and handle them appropriately.

You cannot be sure that all users have the newest version of Application Manager. If your setup program relies on any ActiveSync 4.0 features, make sure your application checks the ActiveSync version number in the HKLM\Software\Microsoft\Windows CE Services\MajorVersion registry key. If the value stored in the key is greater than or equal to 4.0, then the user has installed the new version of Application Manager.

See Also

Using the Application Manager | Registering with Application Manager | Troubleshooting the Application Manager | Delivering Applications

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.