Consider the following scenario: You want to upgrade an existing application to take advantage of new functionality of the .NET Compact Framework 2.0, but you also need to support the original version of the application that runs on the .NET Compact Framework 1.0. As long as you target only devices that Visual Studio 2005 supports, you can start by upgrading your existing Visual Studio .NET 2003 solution as described earlier. You will end up with an upgraded solution in Visual Studio 2005 that still targets the .NET Compact Framework 1.0. You can verify that by looking at the version number of one of the .NET Compact Framework assemblies, as indicated by the red circle in the following figure.

Figure 1. A .NET Compact Framework 1.0 application in Visual Studio 2005

If you now want to have the same application target the .NET Compact Framework 2.0 as well, you can create a new project inside the same solution. Make sure that this new project is a Device Project. Visual Studio 2005 automatically creates a project for you that targets the .NET Compact Framework 2.0. To make sure that you will use the same source files as the original project, you must delete all source files from the just-created project. The source files you need to delete are named Form1.csand Program.cs. Next, you must add the source files from the original .NET Compact Framework 1.0 application to the new project. To ensure that you use the same source files in both projects, add them as a link. To add a source file as a link, right-click on a project in Solution Explorer, and then click Add Existing Item. In the Add Existing Itemdialog box, select the file that you want to add. Instead of clicking the Addbutton, click the arrow to the right of it (as shown in the following figure), and then click Add As Link.

Figure 2. Adding a source file as a link

In Solution Explorer, you get a visual indication when a file is added as a link. When you see an arrow by the lower-left side of a file, that file is a link to another file. In the following figure, Form1.cs is added as a link to the CF2Application. The physical file only exists once.

Even though Form1.cs is now identical for both projects, you can also see in Figure 3 that the newly added project targets the .NET Compact Framework 2.0, as indicated by the red circle.

Figure 3. A .NET Compact Framework 2.0 application in Visual Studio 2005

Building the entire solution that is shown in Figure 3 results in having two different versions of the same application: one targets the .NET Compact Framework 1.0 and the other targets the .NET Compact Framework 2.0. Because you added the Form1.cs source file to the new CF2Application project as a link, making changes to this source file in one project will also influence the other project.

In the sample solution that is shown in Figure 3, you may want to use functionality in the .NET Compact Framework 2.0 project that is not available in the .NET Compact Framework 1.0. To do so while maintaining a single code base, use conditional compilation. Conditional compilation enables you to select specific sections of code to compile, while excluding other sections. By using conditional compilation, you can distinguish between shared code and code that is specific for either one of the .NET Compact Framework versions that you want to target. To make use of this technique, you can add conditional compilation directives that will compile only that code that is relevant for the particular version of the .NET Compact Framework that you want to target. Conditional compilation statements influence the way an application is compiled.

The following code example demonstrates how to use conditional compilation.

To be able to have specific code for one of the different versions of the application, you can define your own conditional compilation symbols. You can define conditional compilation symbols in source code or in the project's Propertiesbox. If you have two different versions of the same application, each targeting a different version of the .NET Compact Framework, we recommend that you set the conditional compilation constants in the project settings for each project. In doing this, you assure that the C# compiler always compiles the correct code for a particular version of the application. In the Builddialog box of the Project Settings, you can set conditional compilation symbols, as shown in Figure 4. You can set as many different conditional compilation symbols as you need for each of the projects in your solution. To set a conditional compilation symbol in the project settings, follow these steps:

1. In Solution Explorer, select the CF1Applicationproject.
   
   
2. On the Projectmenu in Visual Studio 2005, select the CF1Application Propertiesentry.
   
   
3. The CF1Application Propertiesdialog box is displayed.
   
   
4. In the CF1Application Propertiesdialog box, select the Buildtab.
   
   
5. Find the Conditional compilation symbolstext box, and enter the NETCF1symbol, preceded by a white space.
   
   

To add a conditional compilation symbol to the CF2Applicationproject inside the same solution, follow these steps:

1. In Solution Explorer, select the CF2Applicationproject.
   
   
2. On the Projectmenu in Visual Studio 2005, select the CF2Application Propertiesentry.
   
   
3. The CF2Application Propertiesdialog box is displayed.
   
   
4. In the CF2Application Propertiesdialog box, select the Buildtab.
   
   
5. Find the Conditional compilation symbolstext box, and enter the NETCF2symbol, preceded by a white space.
   
   

Figure 4. Setting conditional compilation symbols in Visual Studio 2005

Figure 4 shows how to set a conditional compilation symbol for the CF1Application in the SampleApplication solution. Similarly, you have set a different symbol for the CF2Application. In Solution Explorer, you can see that Form1.cs as part of the CF2Application project is a linked file, which is indicated by the arrow in the file icon. The Form1.cs file is the same physical file as the file that is in the CF1Application project.

If you modify the code in the button1_Clickevent handler, you can execute specific actions for the CF1Application and CF2Application projects, making use of the conditional compilation symbols that you just added.

The following code example shows how to use the conditional compilation symbols in the button1_Clickevent handler.

It is also possible to target a different device for each application, as shown in the following figure.

Figure 5. Running the same code base in different devices by using different versions of the .NET Compact Framework

If you need to support applications that target Windows Mobile–based devices, such as Pocket PC, Pocket PC 2002, or Smartphone 2003, or if you cannot install the .NET Compact Framework 2.0 for use on newer devices, you might benefit from OpenNETCF.org's Smart Device Framework (SDF).

In version 1.4, OpenNETCF.org's SDF is an extensive set of classes that complement the .NET Compact Framework. It is compatible with the .NET Compact Framework 1.0 and the .NET Compact Framework 2.0. The SDF is a robust, shared source library that integrates seamlessly into Visual Studio .NET 2003. The SDF provides many of the classes, properties, and methods that are available in the full .NET Framework, plus many additional classes that are specific to the Windows CE environment.

The SDF provides significant .NET Compact Framework 2.0 functionality for use with .NET Compact Framework 1.0–connected applications. The SDF contains a number of UI controls that are not available in the .NET Compact Framework 1.0, but are available in the .NET Compact Framework 2.0. The SDF also contains many extensions to existing classes in the .NET Compact Framework 1.0. The SDF and the .NET Compact Framework offer carefully selected namespaces, along with method and property name compatibility. In this way, you can use the SDF to create and maintain applications that run on multiple devices and that target the .NET Compact Framework 1.0 and the new functionality in the .NET Compact Framework 2.0.

For several controls that are available in the .NET Compact Framework 1.0, the SDF contains enhanced functionality that matches the functionality of those controls in the .NET Compact Framework 2.0. For example, Figure 8 lists the new controls in the "Windows.Forms" namespace for the .NET Compact Framework 2.0.

Figure 8. New controls in the "Windows.Forms" namespace for the .NET Compact Framework 2.0

In Figure 8, the controls in blue are also available in the SDF, usually with the same properties and methods as in the .NET Compact Framework 2.0 version of the controls, although they sometimes have slight differences. To distinguish between .NET Compact Framework controls and SDF controls, the SDF controls are part of the "OpenNETCF.Windows.Forms" namespace. The SDF contains additional UI controls, and it extends and adds many other classes of which developers who use the .NET Compact Framework can take advantage.

The next sample application has a single form that contains a DateTimePicker control, a Label control, and a TextBox control. The application is designed to select a date, to show it in the TextBox control, and store the selected date in the registry on the device. The application must work for the .NET Compact Framework versions 1.0 and 2.0, while sharing as much source code as possible. Because a DateTimePicker control is not available in the .NET Compact Framework 1.0, you must make use of OpenNETCF.org's Smart Device Framework 1.4 for the version of the application that works with the .NET Compact Framework 1.0. Since the Smart Device Framework 1.4 integrates with Visual Studio .NET 2003, the .NET Compact Framework 1.0 application is developed in Visual Studio .NET 2003. The .NET Compact Framework 2.0 version of the application is developed in Visual Studio 2005.

Figure 9 illustrates the UI of the application inside Visual Studio .NET 2003. In the ToolBox, you can see familiar .NET Compact Framework 1.0–based device controls and an additional set of OpenNETCF Controls. You can use these controls when you install the Smart Device Framework.

Figure 9. UI of a sample application to demonstrate sharing source code

The application uses a DateTimePicker control, which is not available in the .NET Compact Framework 1.0. However, by using the installed Smart Device Framework, you can use a DateTimePicker control in the .NET Compact Framework 1.0 application by dragging it from OpenNETCF Controls to the form. In doing so, you are making use of .NET Compact Framework 2.0 functionality inside a .NET Compact Framework 1.0 application.

In the following code example, you can see three empty event handlers, one for the Form1_Loadevent, one for the Form1_Closingevent, and one for the dateTimePicker1_ValueChangedevent. This code—running under the .NET Compact Framework 1.0—is the starting point for an application that uses two different approaches to share as much source code as possible between a version running under the .NET Compact Framework 1.0 and a version running under the .NET Compact Framework 2.0. The first approach to sharing code is to separate UI Code from Business Logic. The second approach to sharing code is to make use of Object Oriented Techniques. Both are described in the upcoming sections.

After you add a number of event handlers to the application, the source code for this form looks like the following code example (omitting the code that the form designer inserts).

You can share as much code as possible between .NET Compact Framework version 1.0 and 2.0 applications by separating business logic from UI code.

Like most applications, the sample application used in this article takes action upon receiving different events. The actions are executed in the different event handlers of the application. Apart from connecting event handlers to UI controls, you should try to implement any other code in one or more separate classes that provide the functionality for the application. To do so, you can create a new class in your .NET Compact Framework 1.0 project and create methods that will be called by the different event handlers inside Form1, as shown in the class diagram in the following figure.

Figure 10. Implementing business logic in a separate class

As you might expect, and as shown in the class diagram in Figure 10, the functionality to be executed in the application is put into the Form1Logicclass. The only functionality for which Form1is responsible is to maintain the UI and to call a method inside Form1Logiceach time the user requests a particular action. The code inside Form1Logiccan be shared between different versions of the application. As described earlier in this article, the functionality of the application is very simple:

• In the Form1_Loadevent handler, the code will inspect the device registry to determine whether a selected date has been stored for the application. If it has, the program should retrieve that date, set it to the DateTimePicker control, and set it to the TextBox control. If no information is found in the registry, the current date will appear in both controls. The functionality to retrieve date information from the registry is implemented in the RetrieveLastDatemethod of the Form1Logicclass.
  
  
• In the Form1_Closingevent handler, the code will store the date that is currently selected in the DateTimePicker control into the device registry. The functionality to achieve this action is implemented in the StoreLastDatemethod of the Form1Logicclass.
  
  
• In the dateTimePicker1_ValueChangedevent handler, the code will copy the newly selected date to the TextBox control. Because no additional functionality is needed—this action is an update of a UI control—you can decide to leave that functionality inside Form1.
  
  

Inside Form1, you need to provide access to Form1Logic. To achieve this access, you can declare a variable of type Form1Logicin Form1and instantiate it in the constructor of Form1, as you can see in the following code example.

Assuming that you have created the Form1Logicclass, which contains all of the functionality that needs to be executed, you need to call the methods of Form1Logiconly when events occur. The following code example shows the three different event handlers that are defined in Form1. Two of the event handlers are calling methods in Form1Logic, and one does a simple UI update.

As you can see from the preceding code example, you have to maintain very little code inside Form1. This is an important point because Form1will not be shared among the different versions of the application due to the form designer issues described earlier in this article. Omitting the functionality of Form1Logicfor now, you need to create a new application in Visual Studio 2005 with the same UI as the previous application that will target the .NET Compact Framework 2.0. You need to add the same event handlers to get the same behavior for the application.

As you can see in Solution Explorerin Figure 11, the project already contains the class Form1Logic, which is implemented in the file Form1Logic.cs. Form1Logicis added as a link, as described earlier in this article. Therefore, the project has one physical source file—Form1Logic.cs—that will be shared between a .NET Compact Framework 1.0–connected application (CF1 application) that was developed in Visual Studio .NET 2003, and a .NET Compact Framework 2.0–connected application (CF2 application) that was developed in Visual Studio 2005.

Figure 11. UI of the sample application built in Visual Studio 2005

Similar to the code for the CF1 application, you can call methods of Form1Logicwhen events occur. The following code example shows the three different event handlers that are defined in Form1for the CF2 application. Two of the event handlers are calling methods in Form1Logic; one does a simple UI update.

As you can see, the code for the event handlers in the V2 application is identical to the code for the event handlers in the V1 application. The most important difference is that you now use the DateTimePicker control that is available in the .NET Compact Framework 2.0 instead of the DateTimePicker control from the OpenNETCF.org Smart Device Framework.

Because the DateTimePicker control in the Smart Device Framework uses the same properties and methods that are available for the .NET Compact Framework 2.0 DateTimePicker control, the code looks exactly the same.

The source code in Form1Logic.cs is most interesting because both applications share it.

In the preceding code example, conditional compilation enables us to distinguish between using directives to import types that are defined either in the "OpenNETCF.Win32" namespace or in the "Microsoft.Win32" namespace. Each application is designed to use the registry to store and retrieve data. The CF1 application does not have classes to access the registry. Therefore, in the CF1 application, you use registry classes that are available in the Smart Device Framework in the "OpenNETCF.Win32" namespace.

Because the .NET Compact Framework 2.0 has registry classes available, you can use those registry classes instead of the Smart Device Framework classes in the CF2 application. Again, the methods and properties of each set of registry classes are the same. You only need to refer to the correct namespace in order to use the particular registry classes that you require. The preceding code example is simple, and most of it can be shared between the two different versions of the application because the used SDF classes and .NET Compact Framework 2.0 classes closely match. You will probably need to do more work when working with a more complex application, but the approach can be the same.

When using a separate class for business logic, you must distinguish clearly between UI code and actual functionality. The UI code will be duplicated. In the UI code, you will have to call different methods that implement the business logic.

Another approach is to make use of object-oriented techniques like inheritance. In this approach, a class—the derived class—gains the nonprivate data and behavior of the base class in addition to other data or behaviors that it defines for itself. If you derive a class from Form1and add business logic to that class, the derived class can also be a candidate for source code sharing between different versions of the application.

To demonstrate this approach, the functionality of the previous code example is implemented in a different way. The use of inheritance has advantages because you can make use of the polymorphism capabilities of the C# programming language in the following ways:

• You can change the data and behavior of a base class.
  
  
• You can replace the base member with a new derived member.
  
  
• You can override a virtual base member.
  
  

When you ensure that the event handlers in the base class ( Form1) are defined as protected virtual, they are candidates for overriding default behavior. You will make use of overriding functionality in the remainder of this article.

For this approach, as shown in the class diagram in Figure 12, the functionality to be executed in the application is again placed into the Form1Logicclass, but Form1Logicinherits from Form1and overrides the event handlers that were defined in the base class. Again, Form1is responsible only for maintaining the UI. Because you now derive Form1Logicfrom Form1, however, there is no need to explicitly call member functions of Form1Logic.

Figure 12. Business logic in an inherited class

The UI for this sample application is exactly the same as the UI in the preceding code example as shown in Figure 11. In the following code example for a CF1 application, both the Form1_Loadand Form1_Closingevent handlers are declared as protected virtual, meaning that they can be overridden in a derived class. These event handlers contain no code. The actual implementation is in the derived class Form1Logic, that you can find later in this article. Even though the dateTimePicker1_ValueChanged event handler is declared as protected virtualas well, it does contain code to update the Text property of a text box. This means that a derived class may choose to override this functionality, but if it does not do so, the code in the base class will be executed.

The code example that follows also reveals a remarkable characteristic. Instead of instantiating a new Form1class in the Application.Runmethod, you now instantiate the derived class Form1Logic. Because Form1Logicis derived from Form1, Form1Logicis in fact a form. Therefore, it can be passed to the Application.Runmethod.

To provide access to the different UI controls in the derived class, you also have to ensure that the Modifiersproperty of the UI controls to which you need access (in the sample, dateTimePicker1and textBox1) are changed from privateto protected.

Again, you need to create a separate project for a CF2 application with the same UI as the CF1 application, this time targeting the .NET Compact Framework 2.0. You need to add the same event handlers to get the same behavior in the application. To use functionality from the derived class Form1Logicwhile keeping it as a single source file for both the CF1 and CF2 applications, you need to add it to your project as a linked file, as described in the Create Different Versions of the Same Applicationsection earlier in the article.

The following code example for the Form1class of the CF2 application is similar to the code of the CF1 application shown previously.

In .NET Compact Framework 2.0 applications, the Mainmethod is moved to its own source file: Program.cs. Instead of instantiating a new Form1class in the Application.Runmethod, you again must instantiate the derived class Form1Logic. With that change, the Program.csfile will look like the following code example.

When you are using inheritance to share code between two different versions of your application, you should be aware of the following issues. Because you derive Form1Logicfrom Form1, Form1Logicis in fact a form. Inside both versions of Visual Studio, Form1Logicappears as a form in Solution Explorer. It even seems as though you can open Form1Logicin the form designer. In Visual Studio .NET 2003, you get an error when you try to open Form1Logicin the form designer, because the .NET Compact Framework 1.0 does not support visual inheritance. However, in Visual Studio 2005, you can open Form1Logicin the form designer. In addition, it may seem as though you can add more controls to your derived form. Doing so, however, will lead to problems.

Because you added Form1Logicas a link to the V2 project, the actual Form1Logicsource file is located in a different folder than the other files of the V2 application. When you open Form1Logicwith the form designer, Visual Studio 2005 attempts to open and create a Form1Logic.resx file. In doing so, it apparently detects that Form1Logic.cs is located somewhere else, which results in the error shown in Figure 13.

Figure 13. Error when you try to add controls to the derived form by using the form designer

If you want to add additional controls to your V2 application, you should add them to the base class ( Form1). This advice is not a limitation because the base class is unique for the V2 application.

Again, the source code is most interesting in Form1Logic.cs because that code is shared between both applications. The following code example for Form1Logic.cs illustrates that Form1Logicis now derived from Form1. Again, you use conditional compilation to distinguish between V1 and V2 application logic. It is now also evident that one method is exclusively available for the V2 application— dateTimePicker1_ValueChanged.

Just as the sample that uses a separate class to implement the business logic, deriving a class from Form1results in reasonably simple code. Again, most of the code can be shared between the two different versions of the application. This capability is due to the fact that the used Smart Device Framework classes and .NET Compact Framework 2.0 classes closely match.

This way of sharing source code has an advantage over the previously described way because less application-specific code needs to be written in the Form1class. However, the application may experience a performance penalty because overwriting methods in a derived class results in an indirect call to the particular method. In fact, two separate calls are needed to reach the desired method. When you use inheritance, you must be careful not to open the derived classes in the form designer because you will encounter problems, as shown in figure 13. Also, because functionality is now found in a class derived from a Windows.Formclass, the distinction between UI code and business logic is less clear.

Running each version of the application results in a slight difference in behavior, because the V2 application overrides an additional method to show a selected date in a short format in the textbox. Figure 14 shows both versions of the application, running on different devices with different versions of the .NET Compact Framework. The emulator on the left side of Figure 14 shows the .NET Compact Framework 1.0 version of the application running on a Pocket PC 2002 emulator. This version makes use of OpenNETCF.org’s Smart Device Framework. On the right side is the .NET Compact Framework 2.0 version of the application running on a Windows Mobile 5.0 Pocket PC emulator. As you can see, the user experience for both versions of the application is the same.

Figure 14. CF1 and CF2 application sharing the same source code