Microsoft .NET Compact Framework for Windows CE .NET

Article
06/29/2006

Paul Yao, Windows Embedded MVP
The Paul Yao Company

July 2002

Applies to:
Microsoft® Windows® CE .NET with Microsoft Platform Builder 4.0
Microsoft .NET Compact Framework

Summary: Microsoft Windows Embedded MVP, Paul Yao provides an overview of the Microsoft .NET initiatives as it applies to embedded systems developers for the Windows Embedded Developer Community. (12 printed pages)

Advantages of .NET Over Win32
.NET Fundamentals
.NET Compact Framework in Embedded Devices
Running .NET Programs
Required Windows CE Components for .NET Compact Framework
Conclusion
Acronyms and Terms
For More Information

Note   This white paper describes the basic elements of the Microsoft .NET initiative, as it applies to embedded systems developers. The .NET Compact Framework described here will ship with a development add-on to Microsoft Visual Studio .NET, called Smart Device Extensions (SDE). As of this writing, a Technology Preview of SDE has shipped, and a beta is expected by June 2002. The topics covered in this white paper include:
      Advantages of .NET over Microsoft Win32
      .NET Fundamentals
      .NET Compact Framework in Embedded Devices
This content is for informational purposes and is provided only as a convenience. The entire risk of use or results in connection with the use of this article remains with the user.
                                                  Windows Hardware Engineering Conference

Author's Disclaimer and Copyright:

WinHEC Sponsors' Disclaimer The contents of this document have not been authored or confirmed by Microsoft or the WinHEC conference co-sponsors (hereafter "WinHEC Sponsors"). Accordingly, the information contained in this document does not necessarily represent the views of the WinHEC Sponsors and the WinHEC Sponsors cannot make any representation concerning its accuracy. THE WinHEC SPONSORS MAKE NO WARRANTIES, EXPRESS OR IMPLIED, WITH RESPECT TO THIS INFORMATION.

Microsoft, Windows, Windows NT, ActiveX, Visual Basic, Visual Studio, and Win32 are trademarks or registered trademarks of Microsoft Corporation in the United States and/or other countries. Other product and company names mentioned herein may be the trademarks of their respective owners.

Advantages of .NET Over Win32

The Microsoft® .NET (pronounced "Dot-Net") Compact Framework is a new Application Programming Interface (API) for Microsoft Windows® for Pocket PC and for Microsoft Windows CE .NET. This new API brings to mobile and embedded devices many of the benefits that the full .NET Framework brings to Windows-based desktop platforms. The .NET Compact Framework offers programmers two choices of programming languages—an enhanced, .NET-compatible version of Microsoft Visual Basic® known as Visual Basic .NET, and Microsoft Visual C#™ (pronounced "see-sharp"), which is a new member of the C and C++ language family developed especially for Microsoft .NET.

Longtime Windows CE programmers might ask whether Windows CE needs yet another API. What's wrong with what we have? What does .NET add to Windows CE? When does it make sense to adopt it? This white paper explores these issues.

What's Wrong With Win32?

Microsoft Win32® is the core API for both desktop Windows—that is, for Microsoft Windows XP—and for embedded and mobile versions of Windows—which in this context means Windows CE. But it is not the only API, and with good reason: it is low-level, quirky, prone to memory leaks, and in general, hard to use.

There are other programming interfaces, including the Microsoft Foundation Class (MFC) library for C++ programmers and Microsoft Visual Basic and Microsoft eMbedded Visual Basic. These other APIs were created largely to address shortcomings in Win32, but each has its own deficiencies and limitations. MFC, for example, is essentially a thin layer on top of Win32. So, while MFC compensates for and hides many of the warts of Win32, it shares some Win32 shortcomings—in particular a quirky naming convention and a propensity for memory leaks. Visual Basic on the Windows-based desktop platform and its smaller Windows CE cousin, eMbedded Visual Basic, are each too limited to serve as a standard API. In fact, with the coming of .NET Compact Framework, Microsoft has announced that eMbedded Visual Basic will not be enhanced in future versions of Windows CE, and it will also not be ported to new CPU architectures.

Quirky or not, Win32 has its place. In a memory-constrained environment, it is the only way to go since it creates the smallest executables. (Although obviously in a memory constrained environment you want to be doubly careful about avoiding memory leaks!) For certain types of software—primarily operating system extensions—you have no choice but to use Win32. This is true for device drivers, shell extensions, control panel applets, within the OEM Adaptation Layer (OAL), and in other low-level modules. In such cases, it is the only available programming interface.

What is Better About .NET?

The .NET initiative represents a systematic effort at making programming more efficient. That is, .NET is not just one thing, but also a basket of several things. Each element of .NET represents ways to help make it easier to write code; taken together, all of them represent a major re-orientation—what some might call a revolution. For longtime Microsoft customers, it represents nothing less than Microsoft's re-invention of itself with an Internet-centric orientation. And everyone who develops software for any version of Windows—desktop or embedded—needs to gauge how (and not whether) .NET affects them.

But why are these changes needed? They are needed because software development is still a very labor-intensive, error prone activity. By contrast, advances in silicon density—and tools to design the complex circuits within silicon—have produced stunning advances in hardware. Software development advances have been far more modest. But given the importance of software—for some businesses, software is a key arena for adding value—efforts to improve software development productivity is likely to yield significant and lasting dividends.

.NET Fundamentals

There has been much written on .NET, and so this white paper can only skim the surface. For the purposes of understanding what .NET Compact Framework provides, I summarize here the key elements of .NET that apply to building mobile and embedded applications on the Pocket PC and on Windows CE .NET-enabled devices.

.NET is many things. I will focus on some of the key elements and, owing to space constraints, leave some elements unmentioned. More details about .NET are found at the Microsoft .NET Web site.

.NET Application Classes

The .NET initiative provides for three general application classes:

Windows Forms—Traditional GUI applications running on a client system. The .NET Compact Framework supports a subset of the desktop .NET Framework for building Windows CE-based GUI applications.
Web Forms—Browser-based applications—which mean HTML-based applications—that have a client-side component and a Web server-side component. While the .NET Compact Framework itself has no built-in support for Web Forms, browser-based Windows CE-based applications benefit from the improved flexibility of a .NET-based Web server. When the Microsoft Mobile Internet Toolkit (MMIT) is installed on such a server, it enhances even further the ability to provide support for a wide range of portable-device markup languages, including HTML, Compact HTML (cHTML), and the Wireless Application Protocol/Wireless Markup Language (WAP/WML).
Web Services—A Web-server based Remote Procedure Call (RPC) mechanism that uses XML-encoded datagrams that are built according to the SOAP protocol, and transmitted via the HTTP protocols. The .NET Compact Framework supports the creation of Web service clients, but not Web service servers. Developers who want to deploy Windows CE-based Web service servers can do so using the SOAP Toolkit for Windows CE, which is available with Windows CE .NET with Microsoft Platform Builder.

Windows CE .NET-based applications will benefit from all three types of application classes. But the two types directly supported by the .NET Compact Framework are Windows Forms, and Web service clients. Web Forms will support Windows CE devices, but all of the logic will be server-based. As far as the Web browsers are concerned, normal HTML (or WAP or cHTML) gets transmitted between a Windows CE-based device and a .NET-enabled Server running the Microsoft Mobile Internet Toolkit (MMIT).

The .NET architecture lets you connect together code from different programming languages. I call these "common elements", because the names of these all have the word "common" in them. In this context, common means standard. Here are some of the common elements of .NET:

Common Language Runtime (CLR)—A runtime environment for running .NET executables, providing program loading, memory management, and other core operating system features.
Common Type System—Standard types accessible from all .NET-compatible programming languages.
Common Language Interface—Standard linkage between classes, methods, interfaces, enumerations, and other programming elements of .NET.
Common Intermediate Language—Also known as "Microsoft intermediate language" or MSIL—a standard, CPU-independent machine language level code into which all .NET executables get written.

The .NET Framework

The .NET Framework is an object-oriented API that is designed to be easy to use. In the same way that a well-designed user-interface is "discoverable", the .NET API was built to make it easy to program once you understand the basics. By way of comparison, consider how Win32 functions have a minimum of packaging—basically a set of functions scattered among a set of dynamic link libraries (DLLs). When a programmer writes Win32 code to create and control a window—the fundamental user-interface object—functions with names like CreateWindow, MoveWindow, and ShowWindow are needed. While the documentation helps you find these and related functions, the structure of DLLs are not designed to make functions easy to find. All functions—2,500 on Windows CE .NET and more than twice that on Windows XP—drift in a sea of include files, library files, and DLLs. To discover individual functions, you must be ever vigilant, forever casting a net in a search for pieces that might someday prove useful.

.NET addresses this issue by using various types of containers. And, in fact, .NET has various types of containers for both code and data. Let's consider first the .NET code containers.

Functions are packaged into classes, and classes are packaged into namespaces (which can then be packaged into other namespaces). For example, you create and control windows using functions in a class called Form. The Form class resides in the System.Windows.Forms namespace. A namespace name and a class name can be put together to create a fully qualified name. In the example just cited, the Form class can be unambiguously referenced as System.Windows.Forms.Form. Within this class, you find the elements to work with windows.

The .NET API also makes extensive use of containers to hold data. For example, the Form class holds a container object—of type ControlCollection—named Controls. You add controls to a window by calling ControlCollection.Add, remove controls by calling ControlCollection.Remove, determine the number of controls on a form by checking the ControlCollection.Count property, and walk the list of available controls using the enumerator made available by the ControlCollection.GetEnumerator method. As these examples show, a class name and member function names can be connected together just as a namespace name and a class name can be connected.

Many data containers have an enumerator, just as the Forms class has the enumerator accessible in the ControlCollection collection object. An enumerator lets you get a complete list of things within the collection. In the example earlier, it's a simple matter to look at the controls in a window by asking the Controls collection to provide a list.

All of this organization of code and data points to an API that is remarkably consistent. That is, once you are familiar with the basic idea of a namespace, you can see how it helps you find related functions when you have to work with an object you have not worked with before. And once you are familiar with how data objects can be put into containers, it becomes easy to understand how to add, delete, enumerate, and in general work with collections of objects. What .NET provides, then, is a consistency and ease of use that is the result of a great deal of design and thought on the part of the .NET system architects. All of this will help programmers be more productive.

Common Type System

The Common Type System (CTS) provides a wide range of expected types—signed and unsigned integers (8-bit, 16-bit, 32-bit, and 64-bit) and floating point. In addition, there are types for dates, times, and decimal—precise, fixed-point numbers (see Table 1). This common set of types simplifies interoperability between different languages. On Windows CE, you can write .NET programs using two different programming languages, both C# and Visual Basic .NET.

Table 1. Common .NET Types

.NET Framework Type	C# Alias	Visual Basic .NET Alias	Size
System.Byte	Byte	Byte	1 byte
System.Char	Char	Char	2 bytes
System.Int16	Short	Short	2 bytes
System.Int32	Int	Integer	4 bytes
System.Int64	Long	Long	8 bytes
System.Decimal	decimal	Decimal	16 bytes
System.Single	Float	Single	4 bytes
System.Double	Double	Double	8 bytes
System.DateTime	DateTime	Date	8 bytes
System.String	String	String	Varies

Common Language Interface

The Common Language Interface (CLI) defines the bindings needed for function calls. This—along with the common types described earlier—make it a simple matter to write code in one language and access it from another language. Unlike previous Windows APIs, you are free to mix and match different languages and have them interoperate with a minimum of effort and no loss of information. By contrast, it takes a bit of work to call a Win32 library from Visual Basic. And it is quite difficult to call a C++ function from Visual Basic (a key reason that Microsoft ActiveX® Automation was invented in the first place).

Common Intermediate Language

.NET executable files are written in a CPU-independent machine-level code known as the Microsoft intermediate language (MSIL). This has been submitted to ECMA, the European Standards body, in a form called the "Common Intermediate Language" (CIL). Whatever name you use to refer to them—MSIL or CIL—these executable files can be shipped to run on any system running the .NET Framework or the .NET Compact Framework. At run time, the loader converts MSIL instructions into ARM, x86, MIPS, or SHx instructions, and it is the native code that runs. This is sometimes referred to as a Just-In-Time (JIT) execution strategy.

This means that it is possible to build a single executable file that can run on any Windows CE-based platform. Such an executable file can also run on a Windows-based desktop platform—either an x86 Pentium system or even a 64-bit Itanium system. The portability that this promises will allow you to write remarkably portable code. The key to this portability will be to target the subset of the desktop .NET framework that is implemented in the .NET Compact Framework, and to also avoid the Windows CE-specific extensions—portions not available on the desktop—that have been made in the .NET Compact Framework.

In addition to its portability, MSIL has another advantage: smaller executables. An MSIL executable is generally smaller than a comparable x86, ARM, MIPS, or SHx executable.

.NET Compact Framework in Embedded Devices

Microsoft Platform Builder lets you configure and build Windows CE images for custom hardware. All images are built from one of two base configurations: a Headless (HLBASE) configuration and a display-based (IABASE) configuration. While each can be modified to be like the other, the one that is more appropriate for the Compact Framework is IABASE. Much of the .NET Compact Framework, after all, is for building GUI applications—and GUI development is not an option on a headless (HLBASE) system. Table 2 summarizes the twelve configuration types available in the New Platform Wizard of the Platform Builder. The ones in the Display-Based (IABASE) column are the ones that are suited for the .NET Compact Framework.

Table 2. Windows CE .NET Platform Builder Configurations

Headless (HLBASE) Configurations	Display-Based (IABASE) Configurations
Media Appliance	Cell Phone or Smart Phone
Residential Gateway	Digital Imaging Device
Tiny Kernel	Industrial Automation Device
	Internet Appliance
	PDA or Mobile Handheld
	Retail Point-of-Sale Device
	Set-Top Box
	Web Pad
	Windows Thin Client

Add .NET Compact Framework to a configuration by adding the "Technology Preview .NET Compact Framework" from the following part of the Platform Builder Catalog: "Core OS / Display based devices / Applications & Services Development." If you examine the CESYSGEN.BAT file, you'll see that this adds the dotnetprof2 module to the DCOM_MODULES environment variable.

Table 3 summarizes the files that make up .NET Compact Framework. These files reside in the following Platform Builder directory: WINCE400\OTHERS\DOTNET. Four of the files are CPU-specific Win32 executable files. The rest are called "Managed" files, which means several things. First, these are portable executables with MSIL machine instructions. What makes them "managed" is that they are written according to a set of rules, the chief of which is that they do not handle memory pointers. Instead, they rely on the garbage collector in the .NET common language runtime to manage their memory for them.

Table 3. .NET Compact Framework Support Files

CPU Specific Files	Managed (MSIL) Files
mscoree.dll	microsoft.visualbasic.dll
WFInter.dll	mscorlib.dll
DbgIpcPlatMan.dll	system.data.dll
	system.dll
	system.drawing.dll
	system.net.irda.dll
	system.web.services.dll
	system.windows.forms.dll
	system.xml.dll

Microsoft released a Windows CE .NET (and Pocket PC) compatible version of the .NET Compact Framework in the form of a Technology Preview. For developers who want a taste of the .NET Compact Framework, the technology preview offers a chance to crank some code, and to compare the Windows CE-based version of .NET with the desktop version.

As mentioned earlier, some of these files ship with the Platform Builder version 4.0 and later. However, there are two files missing from the Platform Builder directory (at least, they were missing from the Release Candidate). The missing files were dbnetlib.dll and DbgIpcPlatMan.dll. You can find these files with a special version of Microsoft Visual Studio® .NET that contains the Smart Device Extensions (SDE). When all of these files are present on an appropriately configured Windows CE .NET-based platform, that platform is then able to run a .NET executable. It's worth noting that this special version of Visual Studio .NET that ships with the SDE is different from the final, shipping version that became available in January, 2002.

Running .NET Programs

A .NET program—on both the desktop and on Windows CE—ships in the form of a regular Win32 PE file. That is, to the casual observer, a Win32 executable and a .NET executable seem the same—applications have a file extension of .EXE, and shared libraries have an extension of .DLL.

A Win32 executable is different from a .NET executable in two ways: (1) a flag set in the header, and (2) the libraries on which they are dependent. When the operating system loader notices the .NET flag, it calls a special function to load the MSIL functions through the JIT processor. (On Windows CE .NET, the name of this function is CeModuleJit). .NET executables are dependent on—that is, they import functions from—MSCOREE.DLL. This is one of the native Win32 DLLs that support the .NET Compact Framework.

Two things are needed to enable the .NET Compact Framework. One is the set of files described earlier. The second is that all of the Windows CE components needed to support the .NET objects must be present. For example, the GWES module must be present to support GUI applications. When you add the .NET Compact Framework to an image, Platform Builder automatically adds in the required Windows CE elements.

On a Pocket PC (or a Pocket PC 2002), the same thing can be accomplished by simply copying the files into the \windows directory. And in fact, the same is true for any Windows CE .NET-based device. Assuming that the needed portions of COREDLL.DLL and WINSOCK.DLL are present, a .NET Compact Framework program will run as long as the supporting library files are present.

Required Windows CE Components for .NET Compact Framework

How can you tell whether a given Windows CE .NET build can support the .NET Compact Framework or not? As you may know, when components are incorporated into a Windows CE image, one or more environment variables get set. In the Platform Builder IDE, these are automatically defined for you when you drag components from the catalog onto a platform. While the IDE provides a very nice graphical view to a user, it has its shortcomings. For example, how can you document what is in a system, compare two platforms, or judge—like we're trying to do now—whether a specific platform has a minimum set of components? You can determine exactly what is present in a given image by looking at the set of environment variables, which get written to a file named CECONFIG.H when a platform image gets made.

CECONFIG.H contains a list of the environment variables for the components that were included when a platform was built. This file is automatically included in the Windows CE image—the familiar NK.BIN—that is created for a platform. This means that even if you didn't build a specific Windows CE .NET platform, you can still refer to the CECONFIG.H file to learn what components are needed. Once you have this file, the next step is to compare those components with the list in List 1.

Windows CE .NET Components Needed to Support the .NET Compact Framework

Modules Needed By MSCOREE.DLL

CE_MODULES_FILESYS
CE_MODULES_GWES
COREDLL_COREMAIN
COREDLL_CORELOC or COREDLL_LOCUSA
COREDLL_FULL_CRT
COREDLL_CORESIOW
NK_NKMAPFILE
GWES_CURSOR or GWES_MCURSOR
GWES_KBDUI

Modules Needed By NETCFAGL1_0.DLL

CE_MODULES_GWES
COREDLL_LMEM
COREDLL_GDI_C or COREDLL_MGDI_C
COREDLL_WMGR_C
COREDLL_RECTAPI
GWES_FOREGND
GWES_ICON
GWES_IMGCTL
GWES_MSGQUE
GWES_MGTT or GWES_MGRAST or GWES_GDIFONTS or GWES_PGDI
GWES_MGBITMAP or GWES_PGDI
GWES_MGBLT or GWES_PGDI
GWES_MGBLT2 or GWES_PGDI
GWES_MGBASE or GWES_PGDI
GWES_MGDRAW
GWES_MGDRAW or GWES_PGDI
GWES_MGDRWTXT or GWES_PGDI
GWES_MGPAL
GWES_MGRGN or GWES_PGDI
GWES_NCLIENT
GWES_SBCMN
GWES_TIMER
GWES_WMBASE
GWES_WINMGR

Modules Needed By DBNETLIB.DLL

COREDLL_COREMAIN
COREDLL_CORELOC or COREDLL_LOCUSA
CE_MODULES_FILESYS
COREDLL_FULL_CRT

Modules Needed By DBGIPCPLATMAN.DLL

COREDLL_LMEM

Conclusion

So when should you use the .NET Compact Framework API and when should you use the Win32 API? For certain core components, you'll need to use the Win32 API: device drivers, control panel applets, shell extensions, and for the OEM Adaptation Layer. You are also likely to use the Win32 API for a headless (HLBASE-based) platform, or for any platform that must run in a particularly small memory footprint.

For all other cases, when building a GUI application for Windows CE .NET or later, you are likely to want to use the .NET Compact Framework. In particular, client applications—windows, menus, dialogs, controls—are a natural for the .NET Compact Framework. So are applications that want to access Web services—that is, Web service clients. For each of these, the .NET Compact Framework is a natural. And because of the high level of compatibility with the desktop .NET Framework, it is particularly straightforward to build a .NET Compact Framework version of a desktop .NET Framework application.

In sum, you'll likely write a .NET Compact Framework application whenever you get the chance. The new C# programming language, the new Visual Studio .NET development environment, the Windows CE-specific Smart Device Extensions (SDE), and the updated Windows CE .NET emulator all make it a fun—and productive—environment for which to develop.

Acronyms and Terms

**API
**Application Programming Interface

**CHTML
**Compact HTML

**CIL
**Common Intermediate Language

**CLI
**Common Language Interface

**CLR
**Common Language Runtime

**CTS
**Common Type System

**HTML
**Hypertext Markup Language

**MFC
**Microsoft Foundation Class

**MMIT
**Microsoft Mobile Internet Toolkit

**MSIL
**Microsoft Intermediate Language

**OAL
**OEM Application Layer

**SDE
**Smart Device Extensions

**VB
**Visual Basic

**WAP
**Wireless Application Protocol

**Win32
**Windows 32-Bit Application Programming Interface

**WML
**Wireless Markup Language

**XML
**Extensible Markup Language

For More Information

For the latest, Windows CE .NET Developer information:

The online documentation and context-sensitive Help included with Windows CE .NET also provide comprehensive background information and instructions for using Windows CE .NET.

To access the online documentation:

Open Platform Builder 4.0.
To view the documentation, select the Contents tab on the Help menu.

Note Install the latest Windows CE .NET Product Help File updates from the Windows Embedded Download Center on MSDN.

Microsoft Windows Embedded Developer Center

You can always find the latest developer information including news, product documentation, technical articles, columns, How To's, Downloads, Code Samples, Fixes and Updates for Windows CE .NET on the MSDN® Windows Embedded Developer Center.

Visit the Windows Embedded Community for resources that help you stay current on platform technologies including Tips and Tricks, chats, newsgroups, featured downloads and more. You can also share your development expertise, gain from valuable peer-to-peer support relationships and find answers to many Windows CE .NET related questions.