Migrating from .NET 1.1 to 2.0, 3.0 and 3.5

Yesterday I visited once again a customer that is currently migrating .NET Applications to the latest version. About 1 year ago I wrote a post on migrating application from .NET version 1.1 to 2.0 and 3.0. At the end of last year version 3.5 has also been released, so now a lot of customers don’t know if it better or not to directly migrate to version 3.5.

My advice is that it is better to do the big step and therefore migrate (just once) everything to the .NET Framework 3.5 and therefore start to use the new Visual Studio 2008 and the new features and technologies (like LINQ) offered by this latest framework version. In a migration discussion it is also important to show customers where they have to pay attention in the migration process. In fact if you decide migrating everything to .NET 3.5 you have to know that .NET 3.5 comes with a SP that applies to .NET Framework 2.0 and 3.0 (as shown in the following figure):

Moreover by installing Visual Studio 2008, you automatically get .NET Framework 3.5. One of the most interesting feature of VS2008 is multitargeting: you have the option to chose between different framework version: .NET Framework 2.0, 3.0 or 3.5. In reality the available versions (because of the installation of version 3.5) are .NET Framework 2.0 SP1, 3.0 SP1 and 3.5. What does it mean for you? If you open your “old” 2.0 application and you recompile it, you are actually recompiling it using version 2.0 SP1. Of course the decision of migrating everything to 2.0 SP1 / 3.0 SP1 depends a lot on the situation you have on your servers and clients: what kind of framework version is deployed and what are the barriers (approval, delivery, presence of others applications that you can’t control, …). So, ideally it would be nice if you could migrate everything to 3.5, but in the reality you may have to find compromises. In any case if you decide to migrate everything to .NET 3.5 you may find the following links followed by a post I wrote about one year ago quite useful:

· Problems that are fixed in the .NET Framework 2.0 Service Pack 1
· Problems that are fixed in the .NET Framework 3.0 Service Pack 1

Note: in my old post I'm mentioning Visual Studio 2005 SP1. Of course if you decide to migrate directly to .NET 3.5 what I'm telling about
VS2005 SP1 is still valid for VS2008.

Hope it helps,

Ken Casada

From my old blog post about migrating .NET application from version 1.1 to 2.0, 3.0

Why I decided to write this post?

There are always quite a lot of customers asking questions about migrating .NET 1.1 to 2.0. Moreover recently Microsoft released version 3.0 of the .NET Framework, version 3.0 that is also part of the new Windows Vista Operating System. So I think that now it’s a good idea to makes things a little bit clearer on the newest version and of course to show you which are the possibility to migrate your application, so that you can profit of all the advantages offered by the newest version. Of course I will mention which are the possible problems you can encounter and how you can solve all these in the best way. While writing this post I found that the documentation on MSDN is not always up to date and quite fragmented. That’s why I tried to resume information found around the web and make it up to date. I also found really useful information on Scott Guthrie’s Blog https://weblogs.asp.net/scottgu and Peter Laudati’s Blog https://blogs.msdn.com/peterlau/. Thanks guys!

OK. Then let’s starts…

The most important thing to know is that at the base the .NET Framework 3.0 use version 2.0 of the Framework. There are no technical changes. If you have already version 2.0 and you install version 3.0, the DLLs of version 2.0 will not be replaced. If you don’t already have version 2.0 (the same that is provided with Visual Studio 2005), when you install version 3.0 you automatically install version 2.0 plus 4 new pieces, 4 new technologies: Windows Presentation Foundation, Windows Communication Foundation, Windows Workflows Foundation and Windows CardSpace. I will not cover the details about these 4 new technologies (if you are interested in these 4 new technologies you can get extra information from the official Microsoft Website https://msdn2.microsoft.com/en-us/netframework/default.aspx or from the community web site https://www.netfx3.com)

.NET Framework 3.0 it’s not a modification of version 2.0, it’s just the framework 2.0 with these 4 new added Technologies: WPF, WF, WCF and Windows CardSpace

What does it mean that? If you are already using .NET Framework Version 2.0, by installing version 3.0, you don’t break any existing application.

That’s why for the rest of this post I will focus myself on the migration of .NET Application from version 1.1 to Version 2.0. To start let mention which are the possible upgrade scenarios.

The first option is not upgrading: I know, it sounds funny. But you should really ask yourself if you really need to migrate at all. If you have a 1.1 application that is working just fine and you don’t have any plans to modify or update it, you can leave it as it is. It works just fine. In any case what I really encourage to do is a cost/benefits analysis of your particular situation. See if it makes sense to upgrade your application. In many cases not upgrading might be the right solution for you. So it depends really on the situation you are.

The problem is that in the reality we often have more applications with different needs but just 1 machine. You may for instance just have 1 web server and 2 web applications: one already using version 2.0 and one still compiled and tested with version 1.1.

So, what you need in this case is a way to maintain your old application with 1.x, but at the same time have the opportunity to write new applications with the new 2.0 version. What can you do? You can have both framework version installed on the same machine. In our specific sample 1 web server with both framework versions installed: version 1.1 and version 2.0. So what you can do is just upgrading the framework to 2.0 (or directly to 3.0 as, as I mentioned before, by installing 3.0 you also gets 2.0 and so have both framework versions installed on the same machine. In our specific case our old apps will then use the old framework version, while our new apps will use version 2.0 of the framework. In this case we speak from “side by side execution”.

Another possibility is to run our apps in “2.0 backwards compatibility mode”. What does it mean? That you keep your app compiled in 1.1, but your application is executed using 2.0.

OK, But what’s happen in general when you load, when you run a .NET 1.1 application on a machine that has both 1.1 and 2.0 framework version installed? Which version will be used? Actually this question opens a lot of others questions. Let’s have a look at the following table:

(*) There are some breaking changes in .NET Framework 2.0
https://msdn2.microsoft.com/en-us/netframework/aa570326.aspx

In fact in the following table show us different situations. In the first column we have the type of application. The first is a .NET stand-alone application (Web or Windows Client) compiled for 1.1, the second is the same type of application but this time compiled for 2.0.

The third and the fourth rows represent unmanaged application that host the Common Language Runtime, so non .NET applications that manually load the CLR in order to run .NET code; for instance unmanaged applications that load an Add-In written in .NET.

If you have a look to the first column nothing special must be said. In fact if you just have version 1.1, it’s clear that .NET applications compiled for 2.0 will not work.

By the second and the third columns things are a little bit more interesting: if you have a 2.0 application, always version 2.0 will be loaded (that’s also logical!). Where you need to really pay more attention and testing, are the scenarios in bold: the first important thing to say is that the framework version 2.0 is mostly backwards compatible with the 1.1 framework. What does it mean that? That even if your applications are compiled for 1.1 they should run fine on the 2.0 framework. Therefore the scenario in bold should work out for you most of the time if you choose not to migrate your 1.1 application forward. But (and there is always a “but”), there are some breaking changes in the 2.0 framework. That’s the reason why I put red asterisks by the bold scenarios that point you to a link. If you navigate to the specified link (https://msdn2.microsoft.com/en-us/netframework/aa570326.aspx) you will get the list of breaking changes. By analyzing this list you will probably notice that the majority of your applications don’t even implement any of these cases à your 1.1 application will probably work without problem with 2.0!

Breaking changes are categorized in design-time changes (Visual Studio changes: design, compile, project upgrade) and runtime changes (.NET Framework). Runtime changes impact application compiled with 1.0 or 1.1 running on 2.0, but can also impact application originally written in 1.0 or 1.1 and then recompiled for 2.0. Instead, design-time changes do not impact application compiled for 1.0 or 1.1 and just running on 2.0. You just get design time changes if you recompile your application to 2.0. So, my advice is of course to have a look to this list and if your application implements one of the presented issues, then implement the described workaround.

In any case if your 1.1 application fails to run on 2.0 for whatever reason, you still have the possibility to load it with the old framework version and thus using the scenario described in the 3^rd column, in which you have both framework version installed on the same machine J.

On the above table we still have a special case left in which we have an unmanaged application that use a .NET application compiled for 1.1. In this specific case, the unmanaged application always loads the newest installed version of the .NET Framework by default.
While managed application built with 1.1 continue to load framework 1.1 as long as 1.1 is installed, in the case of an unmanaged application that host a .NET application compiled with 1.1, the unmanaged application will always load the newest installed version of the .NET Framework by default. In some cases this could be a problem and if you really have a problem with this behavior there is still a workaround; there is a possibility a possibility to force the unmanaged application to load the old Framework Version.

What you have to do? First you have to locate the unmanaged EXE, where the exe of your application is located. Create a text file and as name use the one of your application EXE file and add the “.config” extension. Then, inside the file you have created paste the following configuration tag (where it is clearly said that the version to be used is version 1.1).

Create the text file: <unmanagedEXEname>.exe.config
(Ex: myapp.exe è myapp.exe.config)

Paste this text into the new text file:

<?xml version="1.0”>

<configuration>

            <startup>

                  <supportedRuntime version=“v1.1.4322”/>

            </startup>

</configuration>

In case you want to load a Web Application with a specific framework Version you don’t have to edit any configuration file, but things are a little bit easier. First important thing to say is that by installing the .NET Framework 2.0, by default this will not change any existing Web Application to 2.0. If you want to change the used version it’s enough to open IIS, and inside the site properties dialog of your web application, select the ASP.NET tab and select the framework version which must be used by your application. The ASP.NET Tab it’s a new Tab à you only get it by installing .NET Framework 2.0.

Another important thing to know: don’t try to mix ASP.NET 1.1 and 2.0 apps within a single AppPool on Windows Server 2003! You can also try, but you will see that it doesn’t work!

By now we have seen how your .NET application will work on machines that have only the 2.0 framework, and machines that have both versions of the framework installed. We still have one option left: converting our application to 2.0. What does it mean? We don’t want to keep our assemblies compiled for 1.1, but we really want to recompile everything with 2.0 and profiting of the new .NET 2.0 feature.

As first upgrade your Visual Studio 2005 to SP1. The target of VS2005 is clear the .NET framework version 2.0. The installation of the SP1 is really very important, because SP1 helps you a lot with the conversion process (solve a lot of conversion problems that were present before). For the developers who are already using Windows Vista, since the beginning of March there is a specific update for VS2005 targeting Windows Vista user (https://www.microsoft.com/downloads/details.aspx?familyid=90e2942d-3ad1-4873-a2ee-4acc0aace5b6&displaylang=en)

But what we have to do if we want to migrate our applications from .NET 1.1 to 2.0? Which are steps involved in this migration process? Where do we have to start?

As first you have to backup your VS2003 solution before attempting any migration; then you have to open the vs2002/2003 project/solution in VS2005 SP1. A conversion wizard will then be started and will convert your project/solution file to VS2005. Finally compile everything. Everything will be compiled with 2.0 and so you got a .NET Framework 2.0 application. Of course this is quite a quick and dirty answer, but if you are migrating a Windows Form application, the majority of times this quite easy answer will be all it takes for you. Instead, if you are migrating an ASP.NET Web application, you have to do some extra work…

But let’s start with non web application first. As I mentioned most of the time, opening the application in VS2005 and running it through the conversion wizard will be all it takes. This will merely update the project files (.vbproj/.csproj) to work with 2005. It will not update your application code to take advantage of the new .NET 2.0 features. At this point, when you compile your existing 1.1 code, it will be compiled against the 2.0 framework. If the code doesn’t compile, check out the list of breaking changes in the 2.0 framework I mentioned before.

For migrating Web Application, there can be more work involved since the project model for web applications has changed greatly in VS2005. Or let’s better say that we have 2 Options for migrating an ASP.NET 1.1 application to 2.0. Actually when Visual Studio 2005 was released there was just the possibility to migrate to the new default web site project (let’s call it Option#2), but later after user’s complains about the difficulties they had migrating to the new project, Microsoft decided to release another project model (Web Application Project, I will call it Option#1). Initially Option#1 was released as a separate download, now a fixed version is part of the Visual Studio 2005 SP1. That’s why is so important to use VS2005 SP1. That is all you need today, no extra download.

So the first option is to migrate to the Web Application Project template that basically uses the same model as the previous VS2003 project type. And because of that, it’s the easiest way to convert your application to .net framework 2.0, especially if you have a complex web application.

In the case of a Web Application Project we have a project file and only files that are referenced inside this project file are part of the project and are displayed in the solution explorer and are compiled during a build. What is not the case with Option#2, where there is no project file and all files in the folder are part of the project.

Which model to choose? As I said it’s probably easier to migrate to the Web Application Model because it contains minimal changes compared to VS2003. On the other side I also have to say that the WebSite model was introduced because there was a specific need to have this type of project. As example I bring you some described by this post on Scott Guthrie’s Blog. If you think to the real world, web projects are almost always built using a variety of different tools in parallel. Images are worked on using tools like Photoshop, Illustrator. CSS are maybe edited with FrontPage, the code using Visual Studio. Sometimes the same person performs all of these tasks, typically for larger project they are split up across multiple people working together. One of the biggest complaints about VS2003 is how hard it is to manage these cross-tool workflows. For example a designer might update a CSS file in a web project to use a new background image, and add the new image to an images directory under the web project using their image editing tool. If the web developer using VS2003 does not coordinate this change by updating his or her project file to remove the old image and add the new image to the project file manifest, then they will find that things work ok during development, but they will fail in production since the new image will not be copied/deployed when the web project is built to a new location.

Another problem that you can have is that you always need to check-out the project file every time a file is changed added/renamed or is deleted. If you have a complex project with multiple users this can be a problem.

In conclusion, which model to chose? It depends. It depends really on your requirements. Some users will find the new Web site project option more appropriate for their applications, while other users will prefer the Web application project option. Web applications provide the best path for upgrading existing Visual Studio.NET 2003 applications to Visual Studio 2005, and are highly recommended for that scenario. Going forward, Microsoft will fully support both the model.

If you choose Option #1 what you have to do?

1.       First you have to validate your solution in VS2003. If you are using a remote project, copy your remote project locally, otherwise the migration wizard will have a problem. Open your solution with VS2003 and build the whole solution. Validate all your solution and be sure that your application is working correctly.

2.      With the second step we start the migration process. So, you have to open the solution file in VS2005. At this point the Conversion Wizard is automatically launched. The migration wizard proposes you to make a backup of your current solution. Do that! It’s really important; if for whatever reason you want to go back you always have your backup. The conversion will update the solution file and the project file to be compliant with VS2005. After the solution and project files are upgraded to Visual Studio 2005 format, validate that your application builds without errors and runs as expected. At this point, the most common error will be conflicts with names that have been introduced in the.NET Framework version 2.0. For example, the new personalization feature introduces classes with the names like Profile or Membership. The Profile name, in particular, is fairly commonly used by developers who want to keep track of user information (ambiguous class reference). To fix this kind of error, you can either fully qualify existing names with a namespace or rename the members so they do not conflict. You will maybe get warning about using obsolete members. You often get the warning telling you that a method has been deprecated, just to tell you that sometime in a future major version the method will not be supported anymore. When you get a warning of this type you always get an alternative method to call (the compiler suggests you to use another method).
By compiling you may also obtain an error caused by a breaking change we I mentioned before, but as I said, probably the majority of your applications will compile without problems.
Finally start the application and validate all the functionality.

3.      The next step is to convert your web project to use Partial Classes. What are Partial Classes? Partial Classes it’s a new technique introduced with the .NET framework 2.0, which allow us to separate what has been generated by the designer and the part that has been customized by the user.
With Visual Studio 2003 we have P1.aspx and then the code-behind file with the .cs extension (obviously in the case we are working with C#). In the case of Visual Studio 2005 we have the split of the code-behind file in 2 entities. One is the .aspx.cs and the other is the designer file. The designer file will contain the generated code of the designer.

Visual Studio 2003

Visual Studio 2005

In the first case we establish a connection between the aspx file and the code-behind file with the “CodeBehind” directive. We say explicitly that the code behind file is P1.aspx.cs; and this file contains the normal class definition that you already know (public class P1….). In the case of Visual Studio 2005 things are a little bit different. The definition of our class is split in 2 parts, in 2 different files. The class definition itself is “public partial class P2”. The .aspx.cs file contains the code defined by the user, while the designer file the auto-generated code.
What’s important here is not to discuss all the advantages of this solution, but how to convert your solution to use partial classes. It’s very simple: you just have to right click on the root node of your web project and select “Convert to Web Application”. This will move the generated designer code into the “designer.cs” file. Build everything and do evtl. Some fixup. If a control declaration has been accidentally removed (personally I never had this problem) and so if you need to add the missed declaration, add it to the code behind file (not to the designer file).

4.      The 4th step is to fix up HTML errors. Why that? Because Visual Studio 2005 generates and validates XHTML-compliant markup. This help you build Web applications that are standards compliant and helps minimize issues with browser-specific rendering. Visual Studio 2003 did not generate XHTML –compliant markup, so you might see validation and rendering issues with pages created in Visual.NET 2003.
The conversion Wizard keeps the HTML validation setting to Internet Explorer 6 (which was the Visual Studio .NET 2003 default setting). If you want to make your HTML XHTML compliant you can change the validation setting and using the compiler help instructions make your HTML XHTML compliant.

Let’s now see the involved steps if you want to migrate to the Visual Studio 2005 web site model:

1.      The first step is as before the validation inside Visual Studio 2003. Open your solution inside Visual Studio 2003 and validate it: test that everything builds fine and works as it should.

2.      The second step consist in a review of the site architecture for possible conflicts:

a)                  If you have multiple project files referring to the same set of files it is possible for those files to be migrated twice (usually if these happen it means that there is a duplicate). If you really need to reference the same set of files, I think that the easiest thing to do is to migrate to the Web Application Project.

b)                  If you have two pages referencing the same code-behind file; that’s bad design. Change it and use one unique code-behind file for each “WebForm” and “UserControl”.

c)                   If you have other projects referencing the web project, you have to move the shared code to a separate class library and then make a reference to this class library.

d) In Visual Studio.NET 2003 you had to explicitly decide whether or not to include files in your Web project. As with the web site model no project file exists, all files inside a folder are considered part of project. Since the conversion wizard will ignore these files, these files will be leaved where they are, no conversion process will be applied. What you can do when the conversion is finished, is to exclude these files with “Exclude from Project“ (right mouse click). These commands will just put an exclude extension to the specific files and unluckily is not done automatically by the wizard.

3.     To start the conversion Wizard you have to select “Open WebSite” from the “File” menu, select Local IIS. During the conversion process, the first step you are asked to execute, is to backup your project. Here you just need to pay attention in case you decide to define by yourself the backup folder. In fact this must be a folder outside the one of your Web application! … otherwise you will get a caos (Remember: with the web site project all files inside a folder are considered part of a project. So pay attention on this point!).
In case your solution has multiple projects, for instance your project and other non web projects, you first have to migrate the non-web-project and then in a second moment using “Add Existing Web Site” the web project itself (this will start the conversion Wizard for the web project)

4.      The 4^th step is probably the most complicated one, because quite a lot of manual fixup can be necessary. As first, as described for the Web Application Project (step 2), you have to try to compile everything and to solve evtl. conflicts. What has been said before is still valid. In addition to that there is some extra “clean-up work” to do. Here I reported some example:

a)      You may remember that Visual Studio 2003 generated resource file for each Web Form and user Control and in general users did not use them for whatever reason.
The conversion wizard doesn’t remove them, but what I suggest is to create your own resource file inside the new App_GlobalResourceFolder and move all the resource declaration inside this file and then remove all “.resx” files that are not anymore used at WebForm or UserControl level. So you will have a cleaned solution.

b)      In VS2003 the designer auto-generated member functions like “OnInit” and “InitializeComponent()” in the code-behind class file. These functions are not used by VS2005 but will be called if they exist. These functions are not removed from the conversion Wizard. So, once you have migrated your application, you can remove these functions from the code-behind file (of course just if there is no user specific code). It’s just a clean-up work.

c) VS2005 and in particular the new web site model brings a new compilation model. In VS2003 the compilation was done by Visual Studio 2003 for all “.cs” and “.vb” files and those files where compiled into a single assembly inside the bin folder. In VS2005 we don’t work just with one assembly but we have multiple assemblies and because of this change generally you also have to do some general fix up. Luckily quite a lot is done by the conversion Wizard, but sometimes you might need to fix-up something manually. What I suggest is to have a look at the following article https://msdn2.microsoft.com/en-us/library/aa479312.aspx that reports the common web project conversion issues and solutions. If you work with Visual Studio SP1 (includes the final version of the conversion wizard), you will see that most of the issues has been already solved and so no manual fix-up is needed. That why I strongly recommend the installation of the VS2005 SP1!

5.      The last step is as always making your application XHTML compliant. This step is optional and for any details I forward you to point 4 of the other migration option (Web Application Project).

Note: on this topic I recently hold a TechTalk. You can download the slides from the following address: https://www.microsoft.com/switzerland/msdn/de/events/techtalk/migration.mspx