Developing Your First .NET Compact Framework Application for Windows CE .NET 4.1

Article
08/28/2006

Mike Hall
Microsoft Corporation

Steve Maillet
Entelechy Consulting

April 4, 2003

Summary: Shows how to connect Visual Studio .NET 2003 to a Windows CE .NET 4.1-based device, and explains how to create your first C# .NET Compact Framework-based application. (12 printed pages)

I'm sure that many of you have a copy of Microsoft® Visual Studio® .NET 2003, and have already been writing Compact Framework applications for your Pocket PC devices. Perhaps you've been following along with the excellent Two for the Road MSDN column by John Kennedy and Larry Roof. You may also have downloaded the Microsoft® .NET Compact Framework 1.0 RTM bits from the Microsoft Web site and have updated Platform Builder 4.1 with the RTM bits...

But now what? How exactly do you get started with writing applications for Microsoft® Windows® CE .NET 4.1 based devices? If your device has ActiveSync support, then it's easy. Visual Studio .NET can determine the processor type, download and install the Compact Framework runtime DLLs, and then you're all set. It's not quite so simple, however, if you have a device that doesn't support ActiveSync.

We've been using an SH4-based reference board for the Windows CE hands-on labs at the recent Windows Embedded Developers Conferences. This is a really neat device that has power in, and Ethernet, but no keyboard, mouse, or display. The board uses a remote display application that runs on your desktop and gives you the ability to interact with the reference board using your desktop's mouse, display, and keyboard. Pretty slick! Since it doesn't have serial or USB, I cannot use ActiveSync on this device.

ActiveSync needs to make an initial connection over serial or USB before you can switch to using Ethernet, so how do we configure Visual Studio .NET 2003 to talk to our platform that only supports Ethernet? There are a number of steps we need to walk through.

First, you should update Platform Builder 4.1 to include the RTM Compact Framework bits. If you are going to be shipping a device with an embedded .NET Compact Framework application, then you will want to include the RTM Compact Framework bits into your final operating system image. Note that Visual Studio .NET 2003 can download and unpack the Compact Framework into RAM if the Framework isn't included in ROM/Flash. The update is straight forward; download the updated bits from Windows CE .NET 4.1 .NET Compact Framework 1.0 RTM Update.

Second, we need to install some utilities that can prepare our device for Visual Studio .NET application deployment. These utilities, known as the Windows CE Utilities for Visual Studio .NET 2003Add-on pack can be downloaded from here.

Next we need to build an operating system image that's capable of supporting Compact . Framework applications; note that version 1.0 of the Compact Framework only supports display-based devices.

I'm sure that you have been through the Platform Wizard for Windows CE .NET 4.1, so I will only point out the interesting deltas from building any typical platform. I've selected the Intrinsyc SH4 Board Support Package (BSP), and have also selected the Internet Appliance configuration as a starting point for my platform.

Step 5 of the Platform Wizard allows me to choose Applications and Media. This is where I get to add the .NET Compact Framework to my operating system image, if required (see below). Don't forget that if you miss a component from the wizard, you can always add the component from the catalog at a later time.

Figure 1. Adding the .NET Compact Framework to an operating system image

I've chosen not to add the .NET Compact Framework to my image. I will let Visual Studio .NET download and unpack the Framework at application build/deployment time. This raises an interesting issue, though. By now you should have completely read the release notes for the .NET Compact Framework RTM download, and have realized that your operating system needs a number of operating system components in order to support Compact Framework development. Hand selecting each of the required components each and every time you add the .NET Compact Framework component to your operating system image would be a painful process, so I've put together a simple Macro component that wraps up each of the components needed to support .NET Compact Framework development. The "Core" component is listed below.

CECInfo
(
  Name ( "NETCF_CORE" )
  CECVersion ( 4.10 )
  Description ( ".NET Compact Framework Core" )
  GUID ( {0EA248F7-22C9-47fe-9F0F-DF36C48FCBC1} )
  Vendor ( "Microsoft" )
)
ComponentType
(
  Name ( ".NET Compact Framework Core" )
  GUID ( {52D42055-FD93-4cd9-A822-32BBE36D943D} )
  Description ( ".NET Compact Framework Core" )
  Group ( "\NETCF_Core" )
  Vendor ( "Microsoft" )
  MaxResolvedImpsAllowed( 1 )
  Implementations
  (
    Implementation
    (
      Name ( ".NET Compact Framework Core" )
      GUID ( {BF92FD82-9D5D-46f6-AC96-93EA3BD42660} )
      Version ( "4.1.0.0" )
      Locale ( 0409 )
      Vendor ( "Microsoft" )
      Date ( "11/11/2002" )
      Variable( "SYSGEN_CPP_SEH", "1" )
      Variable( "SYSGEN_CRYPTO", "1" )
      Variable( "SYSGEN_WININET", "1" )
      Variable( "SYSGEN_WEBVIEW", "1" )
      Variable( "__SYSGEN_WCELOAD", "1" )
      SizeIsCPUDependent( 0 )
      BuildMethods
      (
        BuildMethod
        (
          GUID ( {DC4D2D99-F255-4bf5-A5E2-1631A834B22D} )
          Step ( PreMakeImg )
          CPU ( "DEFAULT" )
          CoreOS ( "IABASE" )
        )
      )
    )
  )
)

I find this macro component to be extremely useful. I'd been building and using a number of different operating system images, all of which included the .NET Compact Framework, and they were working just fine. Then I had one platform that failed to run a Compact Framework application. I read the release notes and compared the list of components; everything appeared to be fine. So I deleted the workspace and then rebuilt the operating system image—same problem. The only difference between this image and the others, which were working okay, is that I didn't have the .NET Compact Framework component included from the catalog. I wanted Visual Studio to download and unpack the Framework on the device. Visual Studio .NET 2003 was able to connect to my reference board and download the appropriate cab files, but then the application wouldn't run. Well, it turns out I had left out the Wceload components, which are responsible for unpacking CAB files. (This wouldn't have been an issue had I included the .NET Compact Framework in my operating system image, since there wouldn't have been anything to unpack!)

In any case, here's the list of components you need in your platform image to support .NET Compact Framework development. This includes the WCELOAD sysgen variable, which is needed if you intend on having the .NET Compact Framework downloaded and installed on your device, and the corresponding sysgen variables.

C++ Exception Handling—SYSGEN_CPP_SEH.
Cryptography Services (CryptoAPI)—SYSGEN_CRYPTO.
Windows Internet Services—SYSGEN_WININET.
Pocket Internet Explorer HTMLView (WEBVIEW)—SYSGEN_WEBVIEW.
Wceload—__SYSGEN_WCELOAD.

**Note **The release notes don't mention adding the Wceload component. For the most part, you will be including the .NET Compact Framework in your operating system image. Therefore this won't usually be an issue.

We now either add the .NET Core component (see above) to the operating system image, or search the catalog to find each of the required components, or add the sysgen variables by hand. This final option is achieved through the Platform | Settings menu option in Platform Builder. Click the Environment Variables tab, and click New. Type the name of the environment variable in the Variable Name edit control, then enter the value "1" in the Variable Value edit control. Click OK, and the environment variable is set. I'm showing __SYSGEN_WCELOAD purely as an example of how to set environment variables.

Figure 2. Setting an environment variable

Here's how the Platform Settings dialog looks once the environment variable for __SYSGEN_WCELOAD has been added.

Figure 3. Platform Settings—environment variables

Well, alrighty then, we're now ready to build our operating system image. This is simple enough; just use the Build | Build Platform menu option.

Once the operating system is downloaded and is running on the reference board, we then need a way to hook up Visual Studio .NET 2003 to the Windows CE .NET 4.1 device—this is where the Windows CE Utilities for Visual Studio .NET 2003 Add-on pack comes in.

The utilities are installed to C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\WinCE Utilities (assuming a default install of Visual Studio .NET 2003).

There are two parts to the Authentication tools. The first is a device-side application, SDAuthUtilDevice.exe, which is processor specific. So in my case, using an SH4-based reference board, I need to run the application on my device, which is in the C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\WinCE Utilities\Authentication Util\WinCE4\sh4 folder. The second part of the Authentication tools is a desktop application, SDAuthUtil.exe, which is in the C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\WinCE Utilities\Authentication Util folder.

As usual, there is more than one way we can run the device-side application, SDAuthUtilDevice.exe. We could include the application into the operating system image, and then simply run the application from the devices explorer shell. We could copy the application to our _FLATRELEASEDIR, and then use Platform Builder to run the application using the Target | Run Programs menu option. Quick note: the Target | Run Programs menu enumerates all the .EXE files found in the build release folder. Some of the programs in this folder might not be included in the final operating system image (nk.bin). This is fine, however, as Platform Builder will push the selected application to the device and then run the application. (This has the exact same effect as using the CE Shell command, S SDAuthUtilDevice.exe.) Or we could use the Remote File Viewer to push the application to the device and then run the application using the Windows Explorer. I've used the Remote File Viewer to push the application to my device, and then run the application on the device. Here's how the application looks when running.

Figure 4. The device-side application, SDAuthUtilDevice.exe

We need to click the Start button within the device-side application before running the desktop application. This puts the device-side application into "listen" mode, waiting for the desktop application to connect. The device-side application displays the device IP address of the device (which you should make a note of, since you will need this later when configuring Visual Studio). This is needed by the desktop application, and by Visual Studio .NET 2003—more on this shortly.

Here's how the host-side application looks. Note that I've entered the IP address that was returned by the device-side application.

Figure 5. The desktop utility, SDAuthUtil.exe

To configure the device, we need to click the Set Up Device button on the Smart Device (kind of obvious really). After a few seconds, the following MessageBox will be displayed.

Figure 6. The device is now ready for Visual Studio .NET

You're probably wondering what the device-side and desktop-side applications have just done. The message box gives the game away. You can see that an application called ConmanClient.exe has just been launched on the device. We can use Platform Builder to confirm that the application is running. I've used the gi proc command in the CE Target Control window to list out the current running applications.

Figure 7. List of running processes on the target device

SDAuthUtilDevice and ConmanClient are both running. Once we've setup our reference board, we can then disconnect the desktop-side application. Simply hit the Close button on the desktop Smart Device Authentication Utility application. This will also close the device-side application, SDAuthUtilDevice.exe. ConmanClient.exe will continue running.

The SH4 implementation of ConManClient.exe is downloaded to the reference board by the desktop application from the following folder on the desktop PC: C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\ConnectionManager\Target\wce400\sh4.

So far we've built an operating system image that is capable of hosting a Compact Framework application. We've also used the Windows CE Utilities for Visual Studio .NET 2003 Add-on pack to prepare an SH4 reference board. We can now turn our attention to Visual Studio .NET 2003 and how to configure this.

Visual Studio .NET 2003 gives you the ability to create applications for Pocket PC, or Windows CE .NET (embedded devices) in either C# or Visual Basic .NET. In both cases you can target either a real device, or the emulation environment for the device. These applications are known as a Smart Device Application in the Visual Studio New Project Wizard.

Configuring the connection between Visual Studio and a Windows CE .NET device is pretty straightforward. On the Tools menu, click Options, and click Devices tools. Once there, select the Devices option. This will display options for Windows CE .NET Device (this is the one we want), or Windows CE .NET Emulator (this gives us the ability to set the amount of memory available to the emulator and some of the hardware pass-through options).

With Windows CE .NET device selected on the Visual Studio .NET Options dialog, we can then set the transport and configure the transport options. There are two transport options available for Windows CE .NET devices: TCP Connect, and IrDA. We will select TCP Connect Transport.

Figure 8. Visual Studio—setting the transport

With the TCP Transport selected, we can then click the Configure button. This brings up the dialog box shown in Figure 9. Since we already know the IP address of our device (You did write this down when the SDAuthUtilDevice.exe displayed this, right? If not, you can always double-click the networking icon on the Windows CE .NET device task bar), we select the Use specific IP address option, and enter the IP address of the device. Okay, we're now finished setting up the connection from Visual Studio .NET 2003 to our embedded device running Windows CE .NET 4.1. The next step is to write a super-cool C# application to test out the connection.

Figure 9. Configuring Visual Studio with the device IP address

Please welcome the "Cool Tools" application (or Hello World++). This extremely simple C# application contains one button and an edit control. We hit the button, and the words "Cool Tools" appear in the edit control. Pretty lame, but this is enough to show that all the bits are working correctly. Figure 10 shows the user interface for the C# application.

Figure 10. The C# application user interface

The code that lives behind the "Click Me!" button is extremely simple. Here's the code:

private void button1_Click(object sender, System.EventArgs e)
{
    textBox1.Text="Cool Tools!";
}

With the code written, it's now time to test out the application. Within Visual Studio, select either Debug, Start, or Debug, Start without debugging. Visual Studio .NET will show a progress bar that indicates how much of the framework has been downloaded to the device. Once on the device, the .CAB files will need to be unpacked (don't forget to include the WCELOAD component in your operating system image), and then the application will/should start.

Figure 11. Unpacking the .CAB file on the device

And here's the final running application in all its glory...

Figure 12. The C# application running on the device

We've created an operating system image that has included the .NET Compact Framework dependencies. We've also created a (simple) C# "Cool Tools" application to run on Windows CE .NET. We now need to integrate the application into the final operating system image, so that we can run this independently of Visual Studio .NET 2003.

So, here's what we need to do. First, we add the RTM .NET Compact Framework component to our operating system image using the Platform Builder Catalog. We then add the Framework dependencies, either through SYSGEN variables, or through the NETCF Core component (listed above). We then need to add the application to the operating system image—take a look at last month's article for information about including applications. We need to get a copy of the C# application into our build release directory, and also modify the .BIB file for our platform. You should take a look at the release notes for the .NET Compact Framework 1.0. This clearly states that applications created with the .NET Compact Framework should be added to the FILES section of a .BIB file, NOT to the MODULES section. Here's how my PROJECT.BIB looks for my SDApp1.exe program.

;
; Copyright (c) Microsoft Corporation.  All rights reserved.
;
;
; Use of this source code is subject to the terms of the Microsoft end-user
; license agreement (EULA) under which you licensed this SOFTWARE PRODUCT.
; If you did not accept the terms of the EULA, you are not authorized to use
; this source code. For a copy of the EULA, please see the LICENSE.RTF on your
; install media.
;
MODULES
;  Name            Path                                           Memory Type
;  --------------  ---------------------------------------------  -----------


FILES
;  Name            Path                                           Memory Type
;  --------------  ---------------------------------------------  -----------

   SDApp1.exe   $(_FLATRELEASEDIR)\SDApp1.exe                       NK   S

We can then build the operating system, deploy to our device, and run the .NET Compact Framework application just like any other native application included into the NK.BIN file for our device. That's all there is to it. There's a device-side application, a desktop-side application from the smart device authentication utilities, which configures the device to be ready to accept connections from Visual Studio .NET, and some configuration needed within Visual Studio itself. Adding the .NET Compact Framework and supporting components is a snap, and including a Compact Framework application is no different than adding any other application or file to an operating system image. You should now have all the information needed to write some very cool C# or Visual Basic .NET applications for Windows CE .NET 4.1.

If you create any .NET Compact Framework wrapper classes for Windows CE .NET 4.1, or any cool or interesting .NET Compact Framework applications, I'd love to hear about them. Please mail me at mikehall@microsoft.com.

Next month we will take a look at componentization and footprint issues in general.

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.

Developing Your First .NET Compact Framework Application for Windows CE .NET 4.1

Additional resources