Export (0) Print
Expand All
Expand Minimize

Extending the Windows CE .NET Platform Wizard

 

Mike Hall
Microsoft Corporation

Steve Maillet
Entelechy Consulting

August 1, 2003

Summary: Shows you how to extend the Windows CE .NET Platform Wizard by creating your own all-new platform wizard. (12 printed pages)

You've probably all been through the Platform Wizard a number of times, and picked one of the pre-created configurations—Web Pad, Gateway, Internet Appliance, or whatever—and have then added or removed a set of features to customize the operating system to meet your device specific needs. Well, just recently I was working with the Smart Display Adaptation Kit (SDAK). The set-up application for the adaptation kit adds an additional item into the Microsoft® Windows® CE .NET New Platform Wizard, the Smart Display. When selected, this pulls the set of features needed by the Smart Display platform from the catalog, including the Smart Display shell, networking components, and so forth. This got me thinking: If the Smart Display Adaptation Kit can extend the list of platforms available to the new platform wizard, then I should also be able to extend the list by creating my very own custom platform wizard. Once I have completed this, I could distribute the platform wizard file(s) either within my development group or to external customers, so they can reproduce the exact same platform but on their hardware reference platform. (One thing to note is that the creation of new platform wizards is not documented or supported, which is another good reason for writing this month's article!)

Before we start with creating our own platform wizard, we should probably take a look at how Platform Builder knows about its current list of platforms. Take a look at the following folder: C:\Program Files\Windows CE Platform Builder\4.20\cepb\bin\IDE\Wizards. You will see a bunch of .XML files, each defining an existing platform wizard exposed by Platform Builder. (Yippee, it's time to write some XML!) You will of course need a suitable editor for your XML files—Platform Builder, Microsoft® Visual Studio® .NET, Microsoft® Notepad, or even the command-line tool, Edit. (Did you even know that the old MS-DOS ASCII editor tool shipped with Windows XP?)

Actually, however, even easier than creating your own wizard, we will cheat and modify one of the existing ones. In fact, even if you are planning on starting from scratch, you might be better off copying an existing file and modifying to suit your needs.

The first step in knowing how to create your custom wizard is to get an understanding of the layout of the XML file. Here's the Tiny Kernel platform wizard file:

<?xml version="1.0" encoding="UTF-8"?>
<PlatformBuilderWizard xmlns="x-schema:PB_Wizard.xdr" BaseConfig = "HLBASE" 
PlatformDes="Provides the starting point for the smallest functional 
Windows CE operating system image." PlatformTitle="Tiny Kernel">
</PlatformBuilderWizard>

Wow! Is that it?! Tiny Kernel is based on HLBASE, the headless base configuration of Windows CE (take a look at the "BaseConfig" item within the XML). It has a platform description and title; that's all there is to it. The entire XML file is less than 1 KB. Then again, we could jump totally to the other extreme and take a look at Custom Device.xml, which is close to 200 KB in size and provides a complete customized platform based on 19 pages of questions. Instead, we will probably want to look at something in between these two extremes, even though the Custom Device XML file is a good reference for components and their associated GUIDs, as it contains ALL the items exposed out of the catalog.

Anyway, here's a cut down version of the Internet Appliance platform wizard:

<?xml version="1.0" encoding="UTF-8"?>
<PlatformBuilderWizard xmlns="x-schema:PB_Wizard.xdr" BaseConfig = "IABASE" 
PlatformDes="Provides the starting point for a browser-based 
consumer Internet appliance with a fixed display, such as CRT or LCD,
 and a keyboard." PlatformTitle="Internet Appliance">
   <DefaultSettings>
      <Component IncludeComponent="8D56A7ED-BE03-4D8A-8D33-8FF2A76331F6"/>
      <Component IncludeComponent="E4902D0F-4208-40C5-9261-97B11C4ADC31"/>
      <Component IncludeComponent="BE03A7DB-3630-473E-8BCE-B60C10B7DF48"/>
      <Component IncludeComponent="3DB27231-B662-46B2-9A20-BCDB9672F10B"/>
      <Component IncludeComponent="C79B8B9A-2FA9-4A14-89FD-843DD3361DC3"/>
      <Component IncludeComponent="E184D24D-A087-428F-A344-A4D6DF23469E"/>
      <BuildOption Name="IMGRAM64" BuildOptionDefault="DEBUG_ONLY" />
   </DefaultSettings>
   <SelectionPage>
      <Title>Application &amp; Media</Title>
      <Comment>Select the application and media options you want 
               to include in your platform.</Comment>
      <Description>Select the application and media options you want to
                   include in your platform.</Description>
      <Help>17000</Help>
      <ICON>178</ICON>
      <Options>
         <Option OptionDefault="YES">
            <Name>.NET Compact Framework</Name>
            <Description>A feature that enables applications and services
                  designed for the .NET compact framework.</Description>
            <Component IncludeComponent="272A74B5-989A-4361-9FE2-
                                         6C35063A373B"/>
            <Component IncludeComponent="C57F5E2B-DCD5-4D00-8C8B-
                                         7EAC20ADA502"/>
         </Option>
         <Option>
            <Name>Inbox</Name>
            <Description>A Windows CE-based e-mail 
                         application.</Description>
            <Component IncludeComponent="EDAD9ACA-28EB-4681-BC1C-
                                         09B15473F56A"/>
         </Option>
         <Option>
            <Name>Internet Browser</Name>
            <Description>Internet browsers.</Description>
            <Options ChildSelection="SINGLE">
               <Option OptionDefault="YES">
                  <Name>Internet Explorer 6.0</Name>
                  <Description>A full-featured browser comparable to 
                               desktop implementation of Internet 
                               Explorer 6.0.</Description>
                  <Component IncludeComponent="B1E0F57A-1800-49AA-81A0-
                                               3F5A3841CC99"/>
                  <Component IncludeComponent="6EEEA7D7-95CD-440E-A90B-
                                               FE3891537672"/>
               </Option>
               <Option>
                  <Name>Internet Explorer 6.0 with TV-Style
                        Navigation</Name>
                  <Description>A full-featured browser comparable to
                               desktop implementation of Internet Explorer
                               6.0 with TV-Style Navigation 
                               features.</Description>
                  <Component IncludeComponent="6EEEA7D7-95CD-440E-A90B-
                                               FE3891537672"/>
                  <Component IncludeComponent="EE29B0A6-D6DE-4F2A-9AA2-
                                               71DBA88E69F4"/>
               </Option>
            </Options>
         </Option>
         <Option>
            <Name>Microsoft File Viewers</Name>
            <Description>Microsoft viewers for Excel, PowerPoint, Word,
                         image, and .pdf files.</Description>
            <Options>
               <Option>
                  <Name>Microsoft Document Viewer</Name>
                  <Description>Microsoft file viewer for Word (.doc)
                               files.</Description>
                  <Component IncludeComponent="032B4DC2-B59E-4DA1-B1BC-
                                               AFF3BBFA33C7"/>
               </Option>
               <Option>
                  <Name>Microsoft Image Viewer</Name>
                  <Description>Microsoft file viewer for image 
                               files.</Description>
                  <Component IncludeComponent="6A56DCEE-C303-4410-8C8E-
                                               089FCB0D5D81"/>
               </Option>
            </Options>
         </Option>
         <Option>
            <Name>Standard SDK for Windows CE .NET</Name>
            <Description>A feature that adds all the features required for
            a minimum standard set of APIs for your platform. Software 
            development kits (SDKs) created with this feature will contain 
            at least the necessary APIs to qualify as a Windows CE 
            Standard SDK.</Description>
            <Component IncludeComponent="7872F625-A657-4C74-B8D3-
                                         19DEF74A1FF5"/>
      </Options>
   </SelectionPage>
   <SelectionPage>
      <Title>Networking &amp; Communications</Title>
      <Comment>Select the networking and communication options you want to 
               include in your platform.</Comment>
      <Description>Select the networking and communication options you 
                   want to include in your platform.</Description>
      <Help>17000</Help>
      <ICON>178</ICON>
    </SelectionPage>
</PlatformBuilderWizard>

All of the sample wizards contain hardware-independent features. None of the wizards reference device drivers directly. The New Platform Wizard asks the user which BSP they are using before the selection of the appropriate configuration wizard. When a user steps through the New Platform Wizard, it appears as if you are running through one continuous flow. Actually, under the hood there are two independent tasks being run: selection of hardware platform (and processor) [PLATFORM folder], and selection of Platform Wizard [PUBLIC folder]. The New Platform Wizard will then pull the hardware-dependent platform and hardware-independent public components together to form your project workspace.

All components are referenced in the XML file by the components GUID. This reminds me when, way back in 1994, I was working at the Microsoft OLE 2.0 developer's conference in London (England). A member of the audience asked how we could prove mathematically the uniqueness of a GUID. A well-known Program Manager for OLE explained that the probability of creating two GUIDs with the same value is about the same as two random particles colliding in space to form an avocado. What an excellent explanation!

Platform Builder doesn't contain a mechanism for looking up components based on their GUID, but you can search by name, or by partial name. We can, however, make use of one of the existing Platform Wizard XML files. The Custom Platform XML file contains all of the core components exposed by the default Platform Builder Catalog. This, of course, doesn't get updated when any additional or third-party CEC files are added to Platform Builder.

Okay, so anyhow, back to the plot... Let's examine the content of the Internet Appliance XML file. This exposes all of the items needed to create our own wizard. Let's start from the top of the file and work our way down:

<?xml version="1.0" encoding="UTF-8"?>


<PlatformBuilderWizard xmlns="x-schema:PB_Wizard.xdr" 
BaseConfig = "IABASE" PlatformDes="Provides the starting point for a
 browser-based consumer Internet appliance with a fixed display, such as
 CRT or LCD, and a keyboard." PlatformTitle="Internet Appliance">

Since this is an XML file, we need an XML header—enough said.

The PlatformBuilderWizard item contains the following.

  • BaseConfig = IABASE. This can be "IABASE" (Display based) or "HLBASE" (Headless).
  • PlatformDes = "Provides the..." This is a description for the platform.
  • PlatformTitle = "Internet Appliance". This is the name of the platform as it appears in the New Platform Wizard within Platform Builder.

Next, we get Default Settings. These are features that are always added to the platform. Here's a cut-down version of the Internet Appliance configuration. Let's take the first item from the list; the GUID is 8D56A7ED-BE03-4D8A-8D33-8FF2A76331F6:

   <DefaultSettings>
      <Component IncludeComponent="8D56A7ED-BE03-4D8A-8D33-8FF2A76331F6"/>
      <Component IncludeComponent="E4902D0F-4208-40C5-9261-97B11C4ADC31"/>
      <Component IncludeComponent="BE03A7DB-3630-473E-8BCE-B60C10B7DF48"/>
      <Component IncludeComponent="3DB27231-B662-46B2-9A20-BCDB9672F10B"/>
      <Component IncludeComponent="C79B8B9A-2FA9-4A14-89FD-843DD3361DC3"/>
      <Component IncludeComponent="E184D24D-A087-428F-A344-A4D6DF23469E"/>
      <BuildOption Name="IMGRAM64" BuildOptionDefault="DEBUG_ONLY" />
   </DefaultSettings>

We can look up the GUID in the Custom Device XML file. I used Notepad. It would be fairly simple to write a utility to do reverse lookup on GUIDs against the Custom Device XML file. It turns out that this component is the Waveform Audio component. Here's the extract from the Custom Devices XML file, which shows the GUID and description.

     <Option>
        <Name>Waveform Audio</Name>
        <Description>Waveform Audio</Description>
        <Component IncludeComponent="8D56A7ED-BE03-4D8A-8D33-
                                     8FF2A76331F6"/>
        <Conditional TestFor="EXIST" TestVariable="HLBASE"/>
        <Conditional TestFor="EXIST" TestVariable="IABASE"/>
     </Option>

The rest of the XML file defines the pages of the wizard as they appear in the New Platform Wizard within Platform Builder.

The layout for the XML is as follows: One or more selection pages; each page has a title, comment, description, help, and icon. The values for help and icon are fixed.

We then include one or more options, each option contains the name, description, and GUID(s) for the component. You may want some items to be selected by default. For example, the Internet Appliance configuration defines that the Microsoft® .NET Compact Framework is enabled (the user can always turn this off when running through the wizard). Let's examine the various ways in which components can be configured. Here's the basic layout for the selection pages:

<SelectionPage>
  <Title>Page Title Goes Here...</Title>
  <Comment>A Comment to Describe the Page Goes Here</Comment>
  <Description>Describe the purpose of this page</Description>
  <Help>17000</Help>
  <Icon>178</Icon>
  <Options>
    <Option>
    </Option>
  </Options>
</SelectionPage>
<SelectionPage>
  <Title>Page Title Goes Here...</Title>
  <Comment>A Comment to Describe the Page Goes Here</Comment>
  <Description>Describe the purpose of this page</Description>
  <Help>17000</Help>
  <Icon>178</Icon>
  <Options>
    <Option>
    </Option>
  </Options>
</SelectionPage>

The most common way to include a component is to have the component unselected. The user can then select the component while the wizard is running. In this example we are showing the Inbox application.

   <Option>
      <Name>Inbox</Name>
      <Description>A Windows CE-based e-mail application.</Description>
      <Component IncludeComponent="EDAD9ACA-28EB-4681-BC1C-09B15473F56A"/>
   </Option>

You can also set a component's default action to be selected. This is achieved through the added option, optionDefault="YES".

   <Option OptionDefault="YES">
      <Name>.NET Compact Framework</Name>
      <Description>A feature that enables applications and services 
                   designed for the .NET compact framework.</Description>
      <Component IncludeComponent="272A74B5-989A-4361-9FE2-6C35063A373B"/>
      <Component IncludeComponent="C57F5E2B-DCD5-4D00-8C8B-7EAC20ADA502"/>
   </Option>

Now, the interesting thing about the .NET Compact Framework (beyond the obvious fact that .NET Compact Framework application development is wildly interesting anyhow) is that this lists two GUIDs against the one option—time to head over to the Custom Device XML file to figure out what these two options are.

272A74B5-989A-4361-9FE2-6C35063A373B = .NET Compact Framework 1.0
C57F5E2B-DCD5-4D00-8C8B-7EAC20ADA502 = OS Dependencies for .NET Compact Framework 1.0

That totally makes sense. If we include the .NET Compact Framework, then we will also need the .NET Compact Framework O/S Dependencies (refer back to the MSDN article from April 2003, Developing Your First .NET Compact Framework Application for Windows CE .NET 4.1.

So what do we do if we have multiple selections? There are two options. The first option is the case where we have one or more components and only one should be selected during the wizard. For instance, with Microsoft® Internet Explorer 6.0 there are two options, Internet Explorer 6.0, or Internet Explorer 6.0 with TV-Style Navigation. We want the user to select None, or one of the options, but not both. This is achieved through the ChildSelection="SINGLE" option.

 <Option>
    <Name>Internet Browser</Name>
    <Description>Internet browsers.</Description>
    <Options ChildSelection="SINGLE">
       <Option OptionDefault="YES">
          <Name>Internet Explorer 6.0</Name>
          <Description>A full-featured browser comparable to desktop 
              implementation of Internet Explorer 6.0.</Description>
          <Component IncludeComponent="B1E0F57A-1800-49AA-81A0-
                                       3F5A3841CC99"/>
          <Component IncludeComponent="6EEEA7D7-95CD-440E-A90B-
                                       FE3891537672"/>
       </Option>
       <Option>
          <Name>Internet Explorer 6.0 with TV-Style Navigation</Name>
          <Description>A full-featured browser comparable to desktop
                       implementation of Internet Explorer 6.0 with TV-
                       Style Navigation features.</Description>
          <Component IncludeComponent="6EEEA7D7-95CD-440E-A90B-
                                       FE3891537672"/>
          <Component IncludeComponent="EE29B0A6-D6DE-4F2A-9AA2-
                                       71DBA88E69F4"/>
       </Option>
    </Options>
 </Option>

A good example of having a number of child items the user could select, while not limiting the number of children to be selected, is the File Viewers. A user may elect to have none of the file viewers on a platform, or may elect to have one, or more of the file viewers selected.

 <Option>
    <Name>Microsoft File Viewers</Name>
    <Description>Microsoft viewers for Excel, PowerPoint, Word, image, and 
                 .pdf files.</Description>
    <Options>
       <Option>
          <Name>Microsoft Document Viewer</Name>
          <Description>Microsoft file viewer for Word (.doc)
                       files.</Description>
          <Component IncludeComponent="032B4DC2-B59E-4DA1-B1BC-
                                       AFF3BBFA33C7"/>
       </Option>
       <Option>
          <Name>Microsoft Image Viewer</Name>
          <Description>Microsoft file viewer for image 
                       files.</Description>
          <Component IncludeComponent="6A56DCEE-C303-4410-8C8E-
                                       089FCB0D5D81"/>
       </Option>
    </Options>
 </Option>

Pretty simple, eh? We now know that the XML file is simply a listing of components from the catalog arranged into suitable pages. Each of these components are hosted by a CE Component (CEC) file. We can see the current list of installed CE Components in Platform Builder by using the File | Manage Catalog Features menu item, which shows us the list of currently installed Catalog Features (components). This list is totally extensible. Take a look back over the last couple of months' articles, and you will notice that we've included a number of sample CEC files to get you started. Platform Wizard XML files contain a list of user-selectable hardware-independent components, which are referenced through the components GUID.

Microsoft recently released a Platform Export Tool, which provides a mechanism for you to share your current platform workspace. This includes all of the hardware-dependent and independent features. This is a useful tool that relies on everyone using the same underlying hardware platform. Using a custom Platform Wizard, it would be possible to create a platform workspace that matches your configuration of components and doesn't rely on a specific underlying hardware platform.

So, the moment you've been waiting for, the all-new, totally improved, Internet Appliance Ex (I thought it would be good to keep in line with the Windows API naming convention here) Platform Wizard...

Since we know that the Internet Appliance Platform Wizard contains one or more SelectionPage items, I've added my own additional page between Step 4, "Applications and Media," and Step 5, "Networking and Communication." The all-new Step 5 contains the features every platform should have—Games. Here's how the new Step 5 looks.

Figure 1. The "all new" Internet Appliance Step 5

One thing to note about the Platform Wizard: you can clearly see the size of platform being displayed at the bottom right of the dialog. This is the total size of the platform with all current components added, not just the size of Solitaire! If we remove the check box from Solitaire, the platform size reduces by approximately 150 KB.

So there we have it—creating or extending the Platform Wizard is extremely simple. The Windows CE Platform Export Tool is a great tool for sharing existing platform workspaces if everyone is using the same underlying hardware. Creating a Platform Wizard is a great way to share the underlying platform configuration in a hardware-independent way.

 

Get Embedded

Mike Hall is a Product Manager in the Microsoft Embedded and Appliance Platform Group (EAPG). Mike has been working with Windows CE since 1996—in developer support, Embedded System Engineering, and the Embedded product group. When not at the office, Mike can be found with his family, working on Skunk projects, or riding a Honda ST1100.

Steve Maillet is the Founder and Senior Consultant for Entelechy Consulting. Steve has provided training and has developed Windows CE solutions for clients since 1997, when CE was first introduced. Steve is a frequent contributor to the Microsoft Windows CE development newsgroups. When he's not at his computer burning up the keys, Steve can be found jumping out of airplanes at the nearest drop zone.

Show:
© 2014 Microsoft