Learn how to deploy configuration settings in a unified way on devices running Microsoft® Windows Mobile® 6 Professional or Windows Mobile 6 Standard. After a general discussion about the native configuration infrastructure that is available on devices running Windows Mobile Professional or Windows Mobile Standard, a sample application and code examples, written in C#, demonstrate practical uses of this infrastructure including an XML Web service and client applications for devices running Windows Mobile Professional or Windows Mobile Standard. (18 printed pages)

Microsoft Windows Mobile 6 Professional

Microsoft Windows Mobile 6 Classic

Microsoft Windows Mobile 6 Standard

Microsoft Visual Studio® 2005

Microsoft .NET Compact Framework version 2.0

Introduction

Configuration Manager

Provisioning XML Files

CAB Provisioning Format File

Creating a CPF File

Delivering Provisioning XML

Provisioning Sample

Code Walkthrough

Deployment Resources

Conclusion

Deployment is a very broad term, but the overall goal is to be sure devices are up-to-date in terms of configuration settings and installed applications. The requirements for enterprise deployment include the following:

• Device configuration
  
• Application installation and configuration
  
• Software, license, and hardware asset tracking
  
• Documents and file transfer
  

Other articles have covered the last three bullets well (see the Deployment Resources section), so this article focuses on device configuration. Smart devices such as devices running Windows Mobile Professional and Windows Mobile Standard have a lot of configuration options available, and to make the end users set up the configuration options can be devastating for the organization's device support services and, in the end, the total cost of ownership. You can find proof of this fact in the online forums for support about configuring settings for network connections such as e-mail message, Bluetooth, General Packet Radio Services (GPRS), virtual private network (VPN), and other network settings.

Many custom solutions and even commercial products are available to assist the device deployment, but a native infrastructure is also built into the Microsoft Windows® CE operating system that developers can use on devices running Windows Mobile Professional and Windows Mobile Standard.

At the heart of this native infrastructure is the Configuration Manager. It processes a special type of XML file that includes configuration information. The Configuration Manager distributes assignments to various configuration service providers (CSPs) to complete the configuration settings that are included in the XML file. For example, the Registry CSP handles the management of registry keys. This distribution allows the Configuration Manager to track all of the changes and to transact the configuration. If the configuration fails at any point, the Configuration Manager automatically rolls back the changes to the previous state. These transactions ensure that the device remains in a reliable state, regardless of problems during configuration. For example, if a configuration makes some changes to the registry and then tries to change another setting that is not available, the Configuration Manager reverses the changes that were already made, the application presents an error message to the user, and the device returns to its previous state.

The Configuration Manager enforces security on the attempted configurations. For more extensive information, see the Windows Mobile 6 SDK. The Configuration Manager is also the hub of activity for over-the-air (OTA) configuration, downloads, and configuration updates. The Configuration Manager OTA functionality includes both a push and a pull of configuration information. The push is possible from a provisioning server to the device by using Short Message Service (SMS) or Wireless Application Protocol (WAP) push (by using a WAP gateway). Because pushing configuration settings mostly target operators rather than enterprises, it is outside this article's scope. This article's sample covers the pull of configuration information.

Table 1 is a list of some interesting CSPs that are available to the Configuration Manager.

Table 1. Some interesting configuration service providers that are available to the Configuration Manager

For more details, such as information about what CSPs are available on devices running Windows Mobile Professional and Windows Mobile Standard, see the Configuration Service Provider Reference for Windows Mobile Devices.

The first step to configure a mobile device with provisioning XML is to create a valid, properly formatted XML document. The Configuration Manager requires a document that conforms to the WAP-183-PROVCONT-20010724 specification and the Smartphone Extended Configuration format. The provisioning XML must conform to the MSPROV DTD format. Devices running Windows Mobile Professional and Windows Mobile Standard support only Universal Transformation Format 8 (UTF–8) encoded provisioning XML.

The following code example shows a provisioning XML file.

<wap-provisioningdoc>
  <characteristic type="Registry">
    <characteristic type="HKLM\Software\Provisioning\TestKey">
      <parm name="TestValue" value="test" datatype="string" /> 
    </characteristic>
  </characteristic>
</wap-provisioningdoc>

You can find the name of the CSP, in this case Registry, in the second element, named characteristics. The first setting, the second characteristics, has the path and name of the new registry key. This setting can take several parameters with all of the registry values that should be added (or updated) to the registry key. Even if a string data type is used here, the CSP supports many different data types (such as Boolean, integer, float, and date). The provisioning XML to remove the registry value looks like the following code example.

<wap-provisioningdoc>
   <characteristic type="Registry">
      <characteristic type="HKLM\Software\Provisioning\TestKey">
         <noparm name="TestValue" />
      </characteristic>
   </characteristic>
</wap-provisioningdoc>

To remove the whole registry key, use the following provisioning XML code example.

<wap-provisioningdoc>
   <characteristic type="Registry">
      <nocharacteristic type="HKLM\Software\Provisioning\TestKey"/>
   </characteristic>
</wap-provisioningdoc>

You can find more provisioning samples later in this article.

A CAB Provisioning Format (CPF) file is the way to package provisioning XML files. A CPF file is actually a traditional cabinet (.cab) file that is processed as a cabinet file, including the way security is managed.

You can compress the CPF file by using the MSZip compression algorithm (which is essentially the same as the standard deflate [RFC 1951] compression specification), which significantly reduces the file size and transmission time. You can also sign a CPF file through the Microsoft Authenticode® signing tools. These tools enable a role mask to be assigned to the provisioning request based on the role mask that is stored with a matching certificate on the device.

The simplest form of CPF file is a cabinet file that has only one file, which is a provisioning XML file that is named _setup.xml.

The first step to create a CPF file is to create a valid provisioning XML file, as shown in the following code example.

<wap-provisioningdoc>
  <characteristic type="BrowserFavorite">
    <characteristic type="MSDN Mobile Developer Center">
      <parm name="URL" value="http://msdn.microsoft.com/mobility"/>
    </characteristic>
  </characteristic>
</wap-provisioningdoc>

You can find the name of the CSP, BrowserFavorite, in the second element, characteristics. The first setting, the second characteristics, has the actual name of the new favorite link. This setting only takes one parameter (URL), which is the actual URL of the favorite. The corresponding provisioning XML to remove the same favorite looks like the following code example.

<wap-provisioningdoc>
  <characteristic type="BrowserFavorite">
    <nocharacteristic type="MSDN Mobile Developer Center" />
  </characteristic>
</wap-provisioningdoc>

Note that the BrowserFavorite CSP only supports adding and removing favorites on the root level (not in subfolders).

The first code example in this section adds a browser favorite and puts the provisioning XML in a file named _setup.xml. Then, you can use the Makecab utility to create a CPF file by using the following syntax:

makecab.exe _setup.xml msdnmoblink.cab

This syntax creates the CPF file (msdnmoblink.cab) including the provisioning XML file (_setup.xml) as the only entry. The _setup.xml file will be compressed because this is the default option.

You can now publish this file on a Web server, and any user of a device running Windows Mobile Professional or Windows Mobile Standard can navigate to this file and make it a new favorite in Microsoft Internet Explorer® on the device. For more delivery options, see the Delivering Provisioning XML section.

This section discusses the options that are available to enterprises for delivering provisioning XML documents to Windows Mobile–based devices. They roughly divide into two categories:

1. Physical access delivery.
   Requires physical access to the device by an administrator or user.
   
2. Network-based delivery.
   Includes both OTA delivery and delivery over a physical Local Area Network (LAN). OTA includes all wireless technologies.
   

For a device manufacturer or mobile operator, there is also an option to place provisioning files in ROM but, because this option is rarely available to most enterprises, this article does not discuss it.

The following sections list the available options by category.

Physical Delivery

Network Delivery

The sample application was created with Microsoft Visual Studio 2005, is written in C#, and targets the .NET Compact Framework. The sample application shows how to deploy confirmation settings on a device running Windows Mobile Professional and Windows Mobile Standard by using XML Web services, the Configuration Manager, and its configuration service providers.

The purpose of the sample application is to show that you can use a device running Windows Mobile Professional and Windows Mobile Standard to retrieve configuration information from a server in the correct format, and you can apply that configuration locally to the device. Figure 1 shows how you can set up an e-mail account using this technique.

Figure 1. The Get E-Mail Settings command on a device running Windows Mobile Professional

When the sample application is started, the user first enters the e-mail address in the E-Mail box, and then taps the Get E-Mail Settings command. The sample application makes a request to an XML Web service for the e-mail settings information. When that information is returned, the device is configured using those settings. A new e-mail account is set up, and after you open the messaging application (by tapping Start, and then by tapping Messaging), you can use the new account to send and receive e-mail messages.

Several predefined links have also been set up on the server, and the Get Links command fills the Links list with the available links to install. When you select a link in the list, the Install Link command becomes available, as shown in Figure 2.

Figure 2. The Install Link command on a device running Windows Mobile Professional

When you choose this command, the sample application makes another call to the same XML Web service, but this time it retrieves the information about the link. The link is installed as a favorite in the Internet browser, and you can use the new link in Internet Explorer (by tapping Start, and then by tapping Internet Explorer).

Figure 3 shows how the e-mail setup looks on a device running Windows Mobile Standard.

Figure 3. The Get E-Mail Settings command on a device running Windows Mobile Standard

The functionality is identical to the device running Windows Mobile Professional. When you open the messaging application (by choosing Start, and then choosing Messaging), you can use the new account to send and receive e-mail messages.

By choosing the Get Links command, the list of links appears on another screen. Again, when you select a link in the list, the Install Link command becomes available, as shown in Figure 4.

Figure 4. The Install Link command on a device running Windows Mobile Standard

Again, choosing the Install Link command makes the link available in the Internet browser. You can use the new link in Internet Explorer (by choosing Start, and then choosing Internet Explorer).

Even though this sample application is somewhat simplified, there are many possibilities to make configuration information available to users using these techniques.

In the sample application, the back-end source of information is a Microsoft SQL Server™ 2005 database with the following table structure, as shown in the following code example.

CREATE TABLE Settings (
  ServiceName nvarchar(50) NOT NULL,
  PopServer nvarchar(50) NOT NULL,
  SmtpServer nvarchar(50) NOT NULL 
)

CREATE TABLE Users (
  UserID uniqueidentifier PRIMARY KEY DEFAULT (newid()) NOT NULL,
  Name nvarchar(50) NOT NULL,
  UserName nvarchar(30) NOT NULL,
  Password nvarchar(20) NOT NULL,
  DomainName nvarchar(20) NULL,
  EmailAddress nvarchar(50) NOT NULL,
)

CREATE TABLE Links (
  LinkID uniqueidentifier PRIMARY KEY DEFAULT (newid()) NOT NULL,
  Name nvarchar(50) NOT NULL,
  URL nvarchar(255) NOT NULL,
  SortOrder int DEFAULT (0) NOT NULL,
)

The Settings table only has one row, which includes the overall settings, and the Users table includes the information about each user's e-mail settings. In a real-world scenario, the data in both of these tables would probably come from another source, such as an Active Directory directory service. The Links table includes information about common browser favorites (URLs with names).

These tables have the following data, as shown in the following code example.

INSERT INTO Settings (ServiceName, PopServer, SmtpServer)
  VALUES('Exchange', 'pop.microsoft.com', 'smtp.microsoft.com')

INSERT INTO Users (Name, UserName, Password, DomainName, EmailAddress)
  VALUES('Some One', 'someone@microsoft.com', 'test', NULL,
  'someone@microsoft.com')

INSERT INTO Links (Name, URL, SortOrder) VALUES (
  'MSDN Mobile Developer Center', 'http://msdn.microsoft.com/mobility/', 0)
INSERT INTO Links (Name, URL, SortOrder) VALUES ('OpenNETCF',
  'http://www.opennetcf.org/', 1)
INSERT INTO Links (Name, URL, SortOrder) VALUES (
  'Pocket PC Developer Network', 'http://www.pocketpcdn.com/', 2)
INSERT INTO Links (Name, URL, SortOrder) VALUES ('Business Anyplace',
  'http://www.businessanyplace.net/', 3)
INSERT INTO Links (Name, URL, SortOrder) VALUES ('Devbuzz',
  'http://www.devbuzz.com/', 4)

This article's sample includes the previous table definitions and insertion of data as a database script.

Provisioning E-mail Settings

[WebMethod]
public string GetEmailSettings(string email)
{
  DataSet ds = new DataSet();
  using(SqlConnection cn = new SqlConnection(this.connectionString))
  {
    cn.Open();
    SqlDataAdapter da = new SqlDataAdapter("SELECT * FROM Settings", cn);
    da.Fill(ds, "Settings");
    da.SelectCommand.CommandText =
      "SELECT * FROM Users WHERE EmailAddress='" + email + "'";
    da.Fill(ds, "Users");
  }

  XmlDocument xml = new XmlDocument();
  XmlElement root = (XmlElement)xml.AppendChild(
    xml.CreateElement("wap-provisioningdoc"));
  XmlElement characteristic = (XmlElement)root.AppendChild(
    xml.CreateElement("characteristic"));
  characteristic.SetAttributeNode(
    xml.CreateAttribute("type")).InnerText = "EMAIL2";
  characteristic = (XmlElement)characteristic.AppendChild(
    xml.CreateElement("characteristic"));
  characteristic.SetAttributeNode(
    xml.CreateAttribute("type")).InnerText = Guid.NewGuid().ToString("B");

  DataRow dr = ds.Tables["Settings"].Rows[0];
  addParm(xml, characteristic, "SERVICENAME", dr["ServiceName"].ToString());
  addParm(xml, characteristic, "SERVICETYPE", "POP3");
  addParm(xml, characteristic, "INSERVER", dr["PopServer"].ToString());
  addParm(xml, characteristic, "OUTSERVER", dr["SmtpServer"].ToString());

  dr = ds.Tables["Users"].Rows[0];
  addParm(xml, characteristic, "NAME", dr["Name"].ToString());
  addParm(xml, characteristic, "AUTHNAME", dr["UserName"].ToString());
  addParm(xml, characteristic, "AUTHSECRET", dr["Password"].ToString());
  if(dr["DomainName"] != DBNull.Value)
    addParm(xml, characteristic, "AUTHNAME", dr["DomainName"].ToString());
  addParm(xml, characteristic, "REPLYADDR", dr["EmailAddress"].ToString());

  MemoryStream ms = new MemoryStream();
  XmlTextWriter xtw = new XmlTextWriter(ms, Encoding.UTF8);
  xml.WriteContentTo(xtw);
  xtw.Flush();
  ms.Seek(0, System.IO.SeekOrigin.Begin);
  StreamReader sr = new StreamReader(ms);
  string s = sr.ReadToEnd();

  return s;
}

private void addParm(XmlDocument xml, XmlElement c, string parmName, string parmValue)
{
  XmlElement parm = (XmlElement)c.AppendChild(xml.CreateElement("parm"));
  parm.SetAttributeNode(xml.CreateAttribute("name")).InnerText = parmName;
  parm.SetAttributeNode(xml.CreateAttribute("value")).InnerText = parmValue;
}

<wap-provisioningdoc>
  <characteristic type="EMAIL2">
    <characteristic type="{c910231b-2d93-4aba-a730-85cb168a8727}">
      <parm name="SERVICENAME" value="Exchange" />
      <parm name="SERVICETYPE" value="POP3" />
      <parm name="INSERVER" value="pop.microsoft.com" />
      <parm name="OUTSERVER" value="smtp.microsoft.com" />
      <parm name="NAME" value="Some One" />
      <parm name="AUTHNAME" value="someone@microsoft.com" />
      <parm name="AUTHSECRET" value="test" />
      <parm name="REPLYADDR" value="someone@microsoft.com" />
    </characteristic>
  </characteristic>
</wap-provisioningdoc>

private void getEmailSettingsMenuItem_Click(object sender, System.EventArgs e)
{
  try
  {
    WebServices.Service ws = new WebServices.Service();
    //ws.Credentials = new NetworkCredential("username", "password", "domain");
    string xml = ws.GetEmailSettings(emailTextBox.Text);
    XmlDocument xmlDoc = new XmlDocument();
    xmlDoc.LoadXml(xml);
    ConfigurationManager.ProcessConfiguration(xmlDoc, false);
    MessageBox.Show("E-mail settings installed successfully!", this.Text);
  }
  catch(Exception ex)
  {
    MessageBox.Show("Could not get e-mail settings! (" + ex.Message + ")",
      this.Text);
  }
}

Provisioning Browser Favorites

[WebMethod]
public DataSet GetLinkList()
{
  DataSet ds = new DataSet();
  using(SqlConnection cn = new SqlConnection(this.connectionString))
  {
    cn.Open();
    SqlDataAdapter da = new SqlDataAdapter(
      "SELECT Name, LinkID, URL FROM Links ORDER BY SortOrder", cn);
    da.Fill(ds, "Links");
  }
  return ds;
}

private void getLinksMenuItem_Click(object sender, System.EventArgs e)
{
  Cursor.Current = Cursors.WaitCursor;
  try
  {
    WebServices.Provisioning ws = new WebServices.Provisioning();
    DataSet ds = ws.GetLinkList();

    ListViewItem lvi;
    listView.BeginUpdate();
    listView.Items.Clear();
    foreach (DataRow dr in ds.Tables[0].Rows)
    {
      lvi = new ListViewItem(dr["Name"].ToString());
      lvi.SubItems.Add(dr["LinkID"].ToString());
      lvi.SubItems.Add(dr["URL"].ToString());
      listView.Items.Add(lvi);
    }
    listView.EndUpdate();
    if(listView.Items.Count > 0)
      listView.Items[0].Selected = true;
    listView.Focus();
  }
  catch(Exception ex)
  {
    MessageBox.Show("Could not get link list! (" + ex.Message + ")",
      this.Text);
  }
  Cursor.Current = Cursors.Default;
}

[WebMethod]
public string GetLinkSettings(string linkID)
{
  DataSet ds = new DataSet();
  using(SqlConnection cn = new SqlConnection(this.connectionString))
  {
    cn.Open();
    SqlDataAdapter da = new SqlDataAdapter("SELECT * FROM Links WHERE LinkID='" + linkID + "'", cn);
    da.Fill(ds, "Links");
  }
  DataRow dr = ds.Tables["Links"].Rows[0];

  XmlDocument xml = new XmlDocument();
  XmlElement root = (XmlElement)xml.AppendChild(
    xml.CreateElement("wap-provisioningdoc"));
  XmlElement characteristic = (XmlElement)root.AppendChild(
    xml.CreateElement("characteristic"));
  characteristic.SetAttributeNode(
    xml.CreateAttribute("type")).InnerText = "BrowserFavorite";
  characteristic = (XmlElement)characteristic.AppendChild(
    xml.CreateElement("characteristic"));
  characteristic.SetAttributeNode(
    xml.CreateAttribute("type")).InnerText = dr["Name"].ToString();
  addParm(xml, characteristic, "URL", dr["URL"].ToString());

  MemoryStream ms = new MemoryStream();
  XmlTextWriter xtw = new XmlTextWriter(ms, Encoding.UTF8);
  xml.WriteContentTo(xtw);
  xtw.Flush();
  ms.Seek(0, System.IO.SeekOrigin.Begin);
  StreamReader sr = new StreamReader(ms);
  string s = sr.ReadToEnd();

  return s;
}

private void installLinkMenuItem_Click(object sender, System.EventArgs e)
{
  Cursor.Current = Cursors.WaitCursor;
  try
  {
    WebServices.Service ws = new WebServices.Service ();
    string xml = ws.GetLinkSettings(
      listView.Items[listView.SelectedIndices[0]].SubItems[1].Text);
    XmlDocument xmlDoc = new XmlDocument();
    xmlDoc.LoadXml(xml);
    ConfigurationManager.ProcessConfiguration(xmlDoc, false);
    MessageBox.Show("Link installed successfully!", this.Text);
  }
  catch(Exception ex)
  {
    MessageBox.Show("Could not get link list! (" + ex.Message + ")", this.Text);
  }
  Cursor.Current = Cursors.Default;
}

There are many resources on deployment for devices running Windows Mobile Professional and Windows Mobile Standard, and for the .NET Compact Framework developer, the following articles should be of interest:

• Create Self-Updating Applications with the .NET Compact Framework by Alex Feinman, introduces the idea of using XML Web services to check for application updates, download them if available, and finally, install them on the device.
  
• Deployment Patterns for the Microsoft .NET Compact Framework by Dan Fox and Jon Box, brings the ideas from Alex' article (see previous bullet) to a more solid and flexible infrastructure.
  
• Deploying .NET Compact Framework 2.0 Applications with .cab and .msi Files by Chris Tacke, walks you through the steps of creating a setup.
  
• Creating an MSI Package that Detects and Updates the .NET Compact Framework by Stan Adermann describes how to create a Microsoft Installer (.msi) package that can detect the presence of the .NET Compact Framework on a device, can determine if the device needs to be upgraded, and can install or upgrade the .NET Compact Framework with an application.
  
• Windows Mobile-based Smartphone Applications Deployment Demystified explains how to successfully generate .cab files for Smartphones.
  
• Installing Multiple .cab Files with the Same Setup Application by Alexandru Balut shows how to combine multiple .cab files.
  

All resources have something to contribute to your interest, and to get a good picture of the subject, the recommendation is to find out as much information as possible.

The following are some commercial products for device management:

• Systems Management Server is a traditional systems management product, and it has been extended with a Device Management Feature Pack to support devices running Windows Mobile Professional or Windows Mobile Standard without any software installed on the client.
  
• Athena from Odyssey Software enables devices to be managed remotely via TCP/IP by using either an Internet browser or XML Web services.
  
• MobiControl from SOTI Software builds on their remote technology (from Pocket Controller) to access devices over TCP/IP, ActiveSync, or a serial connection.
  
• OneBridge from Sybase (formerly an Extended Systems product) is a mature product that includes most of the required device management functionality that developers want.
  

The commercial products include a wide range of features, and the recommendation is to evaluate the products (most provide downloadable trial versions) to see how they fit into your requirements.

Deployment and device management will always be increasingly interesting targets for optimization because they come as a given consequence of the increasing use of mobile devices in enterprises. A simple, direct (no packaging and publishing), unified (for devices running Windows Mobile Professional or Windows Mobile Standard), but yet powerful model that is set up to manage deployment of configuration settings will ease the pressure on the support organization and surely cut costs. Get to know the configuration service providers and what they can offer by extending the provided sample into your own device management solution.