David Kline : Configuration

Are you having issues with Application Configuration files on the .NET Compact Framework version 2?

DavidKlineMS — Fri, 24 Feb 2006 03:52:00 GMT

I've talked before about application configuration file support in the .NET Compact Framework version 2. I've discussed promoting version 1 applications to run on version 2, and some of the elements of the file's format. Today, I'd like to spend some time talking about some scenarios where application configuration file processing may fail.

Incorrect formatting
By far, the most common issue I have encountered with failing application configuration files is when I have made a mistake when typing the XML. If any of the XML tags or attributes are misspelled, processing of the application configuration file will fail silently.

When none of the versions specified in the supportedRuntime tag can be found, an error message similar to the following will be displayed.

.NET CF Initialization Error
To run this application, you must first install one of the following versions of the .NET Compact Framework:
    v5.6.7890
    v4.5.6789
Contact your application publisher for instructions about obtaining the appropriate version of the .NET Compact Framework.

In the example above, I created an application configuration file which listed two fictitious .NET Compact Framework versions (v4.5.6789 and v5.6.7890).

To combat my tendency towards typing mistakes, I typically create one application configuration file and copy / rename as appropriate. The baseline file I use is listed here.

"XML Core Services and Document Object Model (DOM)" is not installed in the device image
Version 2 of the .NET Compact Framework requires MSXML to be installed for application configuration files to be processed. If you are creating a device image using Platform Builder, "XML Core Services and Document Object Model (DOM)" (also known as SYSGEN_MSXML_DOM), will automatically be added to your image when you add version 2 of the .NET Compact Framework.

Since MSXML was not a dependency of version 1 of the .NET Compact Framework, it may not be available on some devices. On these devices, if version 2 is installed using a cab file, application configuration files may not be processed. Unfortunately, there are no error messages displayed if MSXML cannot be loaded and applications will:

Attempt to run on the version of the .NET Compact Framework for which they were built (ex: version 1)
Attempt to run on the currently installed version of the .NET Compact Framework
If the version of the .NET Compact Framework for which the application was built is not found, fail to run

Take care!
-- DK

Disclaimer(s):
This posting is provided "AS IS" with no warranties, and confers no rights.

Running NetCF v1 applications on v2 post has been updated

DavidKlineMS — Sat, 12 Nov 2005 00:25:00 GMT

Just a quick note for those of you who have already read my "Is your application running on version 2 of the .NET Compact Framework?" post...

Today, I updated the application configuration file data to list all versions of the .NET Compact Framework, including all version 1 service pack releases. When creating your configuration files, please use the following data:

<configuration> <startup> <supportedRuntime version="v2.0.5238"/> <supportedRuntime version="v1.0.4292"/> <supportedRuntime version="v1.0.3316"/> <supportedRuntime version="v1.0.3111"/> <supportedRuntime version="v1.0.2268"/> </startup> </configuration>

Thanks!
-- DK

Disclaimer(s):
This posting is provided "AS IS" with no warranties, and confers no rights.

Is your application running on version 2 of the .NET Compact Framework?

DavidKlineMS — Thu, 10 Nov 2005 05:10:00 GMT

Now that version 2 of the .NET Compact Framework has been released and Visual Studio 2005 has been launched, I thought it would be a good idea to post an update to the application configuration (app.config) file needed to allow your .NET Compact Framework v1 applications to enjoy the benefits of the new release.

To promote your v1 applications to run on version 2 of the .NET Compact Framework,:

Copy the following XML data
<configuration> <startup> <supportedRuntime version="v2.0.5238"/> <supportedRuntime version="v1.0.4292"/> <supportedRuntime version="v1.0.3316"/> <supportedRuntime version="v1.0.3111"/> <supportedRuntime version="v1.0.2268"/> </startup> </configuration>
Create a file called <appname>.exe.config (ex: WebCrawler.exe.config) containing the above XML
Save a copy of the file in the folder (on your device) containing your application (ex: \Program Files\Web Crawler)

By default, the .NET Compact Framework will run your application on the version of the runtime for which it was originally written. Currently available (at the time of this writing) Windows Mobile 2003 and Windows Mobile 5.0 devices contain version 1 of the .NET Compact Framework in ROM. Installing version 2 of the .NET Compact Framework does not overwrite or disable version 1. In this scenario, your applications written for version 1 will continue to use version 1.

The addition of an application configuration file containing the above mentioned data will instruct the .NET Compact Framework to run your application with the specified version (version 2) of the runtime. Your application will now take advantage of the performance improvements we have made in version 2 of the .NET Compact Framework. Please note that since version 1 of the .NET Compact Framework is not aware of application configuration files, having one present on a device without version 2 installed has no affect on your application, it will continue to run with version 1.

While version 1 of the .NET Compact Framework is not application configuration file aware, installing and uninstalling version 2, on a device with version 1, will add configuration file awareness (via the updated mscoree.dll). This is why the above data contains references to all .NET Compact Framework versions (v1, v1 SP1, v1 SP2, v1 SP3 and v2).

Compatibility is a primary goal for the .NET Compact Framework team. If you encounter any issues running your version 1 applications using the above described application configuration file, please let us know via the Microsoft Product Feedback Center.

Take care,
-- DK

Disclaimer(s):
This posting is provided "AS IS" with no warranties, and confers no rights.

[Edit: add version 1 information to config file data]

Running NetCF v1 Applications on v2 - Part II

DavidKlineMS — Tue, 19 Apr 2005 10:20:00 GMT

Several months ago, I posted on using an application configuration file to instruct your NetCF v1 application to run against NetCF v2. As with Beta 1, this file must be named <appname>.exe.config and must be located in the same directory as your application (ex: myapp.exe.config must be in the same directory as myapp.exe). With the release of NetCF v2 Beta2, the application configuration file has a new option - compatibilityversion.

In his Loader Logging post, Steven Pratschner mentioned a "coercion state". He defined this as indicating "whether or not your application was run in backwards compatibility mode". You can specify this compatibility mode using the application configuration file. Steven also has an excellent post that details NetCF application compatibility and configuration files.

Basic configuration file
At it's simplest, the Beta 2 application configuration file is the same as for Beta 1. You supply the desired runtime version using a supportedRuntime XML node:


<configuration>
  <startup>
    <supportedRuntime version="v2.0.5056"/>
  </startup>
</configuration>

The example above was copied from my original post and the version attribute was updated to specify Beta 2's version (2.0.5056).

Adding compatibility mode
Using the example above to run an application built using version 1 of the .NET Compact Framework will result in a compatibilityversion setting of 1.0 to ensure maximum compatibility.

If you wish to explicitly specify the compatibility mode for your application, you can add the compatibilityversion XML node to the above example:


<configuration>
  <runtime>
    <compatibilityversion major="1" minor="0"/>
  </runtime>
  <startup>
    <supportedRuntime version="v2.0.5056"/>
  </startup>
</configuration>

This new application configuration file is functionally equivalent to the previous example. The application will be run against NetCF v2 Beta 2 in NetCF v1 compatibility mode.

There are times when you may wish to have your NetCF v1 application run on NetCF v2 in it's native compatibility mode (as if the application were built against NetCF v2). To do so, you need to override the default behavior by specifying v2 in the compatibilityversion XML node. Please note: Use the following configuration file for diagnostic purposes only.


<configuration>
  <runtime>
    <compatibilityversion major="2" minor="0"/>
  </runtime>
  <startup>
    <supportedRuntime version="v2.0.5056"/>
  </startup>
</configuration>

One of our primary goals for NetCF v2 is compatibility. After you download and install beta 2, it would be much appreciated if you would run your NetCF v1 application(s) on NetCF v2 beta 2 using one of the above application configuration files. If you find any issues, please report them via the Microsoft Product Feedback Center along with the compatibilityversion (if any) specified in your application configuration file. We take application compatibility very seriously and look forward to receiving your results.

Thanks and enjoy the beta!
-- DK

[Edit: fix formatting *2]
[Edit: add link to second Steven Pratschner post]

Disclaimer(s):
This posting is provided "AS IS" with no warranties, and confers no rights.
Some of the information contained within this post may be in relation to beta software. Any and all details are subject to change.

How do I force my NetCF v1 application to run against NetCF v2?

DavidKlineMS — Wed, 04 Aug 2004 01:11:00 GMT

In my “NetCF v2 now supports NTLM” post, I mentioned that the 3 ways to gain NTLM support with existing code are:

Building your application against the v2 beta
Uninstall v1 from your device (not possible on PPC 2003 devices, as v1 is installed in ROM)
Construct an application configuration file for your executable, instructing it to run against the v2 beta

Option number 3 sparked a few questions. Hopefully, this post will help answer those questions.

To force your NetCF v1 application to run against NetCF v2, whether or not v1 is installed on the device (either in RAM or ROM), all you need is a simple XML file in the following format:

This file must be named as follows: <appname>.exe.config. For example, if my executable is simpletest.exe, the name of the configuration file must be simpletest.exe.config. Place the file in your application's folder on the device and you'll be running on NetCF v2.

Please note the last number in the version string. This value must match the exact build number of NetCF v2 for this to work. The value 4135 is the correct build number for NetCF v2 beta1.

One thing I like to do, to help me verify that I have created the configuration file correctly is to display the runtime version somewhere in my application (ex: the About box). To do this, create a label control and assign the runtime version to the Text property as shown below:

runtimeVersionLabel.Text = System.Environment.Version.ToString()

If you do not see “2.0.4135“, you are not running against the NetCF v2 beta. Most likely, this is due to a type-o in your configuration file or that the file cannot be located (copied to the wrong folder, misnamed, etc).

Hope this helps!
--DK

Disclaimers:
This posting is provided "AS IS" with no warranties, and confers no rights.
Some of the information contained within this post may be in relation to beta software. Any and all details are subject to change.