The .Net Compact Framework Configuration Tool

The .Net Compact Framework 3.5 Power Toys include a new utility called the NetCF Configuration Tool.

The Configuration Tool is a diagnostic tool. You won't typically use it in the course of everyday development, but it will come in handy for tasks like diagnosing failures related to device configuration and authoring configuration files.

While the tool isn't targeted at your application's end users, they will be able to use it with your help should you need them to provide you with information needed to debug a problem remotely. For this reason, the Configuration Tool runs directly on the mobile device instead of on a desktop machine connected to a device.

After describing how to install the tool, I'll discuss its four main functional areas:

  • Displaying which versions of NetCF are installed
  • Displaying the contents of the Global Assembly Cache
  • Authoring device.config files
  • Authoring application configuration files

 

Installing the Configuration Tool

The Configuration Tool isn't automatically installed on the device when you install the Power Toys. Instead, you must copy it to your device manually.

Fortunately there's only one file to copy: NetCFcfg.exe. This file is OS and processor-specific so you'll find it under the appropriate WindowsCE directory in the .Net Compact Framework SDK. I'm running a WindowsMobile 5.0 device, so the Configuration Tool executable for my device is in: C:\Program Files\Microsoft.NET\SDK\CompactFramework\v3.5\WindowsCE\wce500\armv4i on my desktop machine.

It doesn't matter which directory you put the file in on your device. I usually put it in the \windows directory but you can deploy the file to any location you please.

The About tab

The "About tab" describes which versions of NetCF are installed on a device. This is the tab that is displayed when you first launch the Configuration Tool:

It's not unusual to have more than one version of NetCF installed on a device. Most all Windows Mobile and WindowsCE devices come with a version of NetCF in ROM. Another version is often installed in RAM to support an application that requires a newer version of NetCF than the version that came with the device.

When multiple versions of NetCF are installed, it's not always obvious which version is being used to run your application. I've seen several cases where confusion results because an application is running with a different version than expected (see "promoting an application" for a general description of the rules used to determine which version of NetCF will be used to run an application). For example, remote tools like the CLRProfiler and Remote Performance Monitor launch an application on device in order to profile it or gather other performance statistics. If your application is launched with a version of NetCF other than the one the tool is expecting, the application may start but the tool won't be able to gather the diagnostic information it is looking for.

Knowing which versions of NetCF are installed on the device, which version was used to build your application, and the rules used to determine which version will be used to run your application can help you determine whether any unexpected behavior you are seeing results from the "wrong version of NetCF" problem.

The GAC tab

The GAC tab lists the assemblies installed in the Global Assembly Cache:

It helps to know the contents of the GAC when diagnosing assembly load failures. It may be you think an assembly is in the GAC when it isn't, or NetCF may load an assembly from the GAC when you don't expect it to. If you encounter a failure to load an assembly, use Loader Logging to find out why, then check the contents of the GAC using the Configuration Tool if the failure looks related to the GAC.

 

The Device Policy tab

In a previous post I described how to use device.config to cause all applications on a device to run with a given version of NetCF. The Configuration Tool enables you to edit device.config using a GUI rather than having to modify the XML by hand.

The Device Policy tab let's you choose a version of NetCF to run all "unconfigured" applications on the device. By "unconfigured" I mean all applications that do not have an application configuration file that contains a supportedRuntime element. 

In addition to the installed versions of NetCF, you can also select the value "Default". Doing so will remove all supportedRuntime elements from device.config causing the device to revert to its default behavior for selecting a runtime.

Keep in mind that not all values you select on this tab are "valid" for all applications. For example, if I chose 1.0.4292 in the example above, no applications built with later versions of NetCF would run (unless they had configurations files of their own that overrode the device-wide setting).

The Application Policy tab

In addition to specifying device-wide policy using the Device Policy tab, you can also specify which version of NetCF should be used to run a specific application by using the Application Policy tab.

The top combo box on the Application Policy tab is pre-populated with all NetCF applications that are installed on the device. After selecting an application, use the lower combo box to select a version of NetCF to run the application. Under the covers this dialog is adding (or removing) supportedRuntime elements from your application's configuration file.

Any value chosen using the Application Policy tab overrides values chosen using the Device Policy tab.

Thanks,

Steven

This posting is provided "AS IS" with no warranties, and confers no rights.