Appendix A

Migrating Older ASP.NET Projects

In some cases, you will build your ASP.NET 4.5 applications from scratch — starting everything new. In many instances, however, this is not an option. You need to take an ASP.NET application that was previously built on the 1.0, 1.1, 2.0, 3.5, or 4.0 versions of the .NET Framework and migrate the application so that it can run on the .NET Framework 4.5.

This appendix focuses on migrating ASP.NET 1.x, 2.0, 3.5, or 4.0 applications to the 4.5 Framework.

MIGRATING IS NOT DIFFICULT

Be aware that Microsoft has done a lot of work to ensure that the migration process from ASP.NET 1.x is as painless as possible. In most cases, your applications run with no changes needed.

When moving a 1.x, 2.0, 3.5, or 4.0 application to 4.5, you don’t have to put the ASP.NET application on a new server or make any changes to your present server beyond installing the .NET Framework 4.5.

After you install the .NET Framework 4.5, you see the framework versions on your server at C:\WINDOWS\Microsoft.NET\Framework, as illustrated in Figure A-1. There is also the 64-bit version at C:\Windows\Microsoft.Net\Framework64 as well if your server is a 64-bit machine.

FIGURE A-1

In this case, you can see that all the official versions of the .NET Framework installed, including v1.0.3705, v1.1.4322, v2.0.50727, v3.0, v3.5, v4.0, and v4.5

Running Multiple Versions of the Framework Side by Side

From Figure A-1, you can see that running multiple versions of the .NET Framework side by side is possible. ASP.NET 1.0, ASP.NET 1.1, ASP.NET 2.0, ASP.NET 3.5, ASP.NET 4, and ASP.NET 4.5 applications can all run from the same server. Different versions of ASP.NET applications that are running on the same server run in their own worker processes and are isolated from one another.

In-Place Upgrade

The .NET Framework 4.5 is an in-place upgrade that replaces the .NET Framework 4. When you install the .NET Framework 4.5, the installer replaces the existing files that were installed by the .NET Framework 4 and upgrades them to the .NET Framework 4.5. You will not see a folder called v4.5, as you saw similar folders for each of the previous frameworks in Figure A-1.

So if you had ASP.NET 4 applications running on a server that had the .NET Framework 4 installed, after installing the .NET Framework 4.5 all ASP.NET 4 applications will start running on the .NET Framework 4.5. When you install the .NET Framework 4.5, all application pools that were running ASP.NET 4 will now be running as ASP.NET 4.5.

Because the .NET 4.5 Framework is an in-place upgrade, Microsoft has done a considerable amount of work to ensure that there is backward compatibility between the .NET 4.0 Framework and the .NET 4.5 Framework. This means that ASP.NET 4 applications should continue to work without any errors after installing the .NET Framework 4.5.

Upgrading Your ASP.NET Applications

When you install the .NET Framework 4.5, it does not remap all your ASP.NET applications so that they now run off the new framework instance. Instead, you selectively remap applications to run off of the ASP.NET 4.5 Framework.

---

NOTE You should always test your older ASP.NET application by first running it on the newer version of ASP.NET in a developer or staging environment. Do not change the version to a newer version on a production system without first testing for any failures.

---

If you are not ready to upgrade your entire application to a newer version of ASP.NET, one option is to create additional virtual directories in the root virtual directory of your application and target the portions of the application to the versions of the .NET Framework that you want them to run on. This enables you to take a stepped approach in your upgrade process.

If you are upgrading from ASP.NET 2.0 to ASP.NET 3.5, there really is very little that you have to do. Upgrading to version 4.0 is a bit different than it was when upgrading from version 2.0 to 3.5 because the 3.5 version of the .NET Framework was built upon the .NET Framework 2.0. In this case, the System.Web DLL in both versions of the framework was the same. Now, though, the .NET Framework 4 is a complete recompilation of the framework. .NET Framework 4.5 is built on top of .NET Framework 4 so when you install .NET Framework 4.5 on a server with .NET Framework 4, then your server will be running on .NET Framework 4.5

The differences are even more evident when working with the IIS Manager on Windows 8. From this management tool, you can see that the DefaultAppPool is running off version 4.0.xxxxx of the .NET Framework, as shown in Figure A-2.

FIGURE A-2

Upgrading your application to ASP.NET 4.5 using Visual Studio 2012 causes the IDE to make all the necessary changes to the application’s configuration file. This is illustrated later in this appendix.

WHEN MIXING VERSIONS—FORMS AUTHENTICATION

If you have an ASP.NET application that utilizes multiple versions of the .NET Framework, as was previously mentioned, you must be aware of how forms authentication works in ASP.NET 2.0, 3.5, 4.0, and 4.5.

In ASP.NET 1.x, the forms authentication process uses Triple DES encryption (3DES) for the encryption and decryption process of the authentication cookies. Ever since ASP.NET 2.0, though, it has now been changed to use the Advanced Encryption Standard (AES) encryption technique.

AES is faster and more secure. However, because the two encryption techniques are different, you must change how ASP.NET 4.5 generates these keys. You do this by changing the <machineKey> section of the web.config file in your ASP.NET 4.5 application so that it works with Triple DES encryption instead (as presented in Listing A-1).

LISTING A-1: Changing your ASP.NET 4.5 application to use Triple DES encryption

<configuration>
  <system.web>
       <machineKey validation="3DES" decryption="3DES"
    validationKey="1234567890123456789012345678901234567890"
    decryptionKey="1234567890123456789012345678901234567890" />
      </system.web>
</configuration>

By changing the machine key encryption/decryption process to utilize Triple DES, you enable the forms authentication to work across an ASP.NET application that is using both the .NET Framework 1.x and 4. Also, this example shows the validationKey and decryptionKey attributes using a specific set of keys. These keys should be the same as those you utilize in your ASP.NET 1.x application.

You should understand that you are not required to make these changes when upgrading an ASP.NET 2.0 or 3.5 application to ASP.NET 4.5 because they are all enabled to use AES encryption and are not using Triple DES encryption. If you are mixing an ASP.NET 1.x application along with ASP.NET 2.0, 3.5, 4.0, or 4.5, you must move everything to use Triple DES encryption, as shown in Listing A-1.

UPGRADING—ASP.NET RESERVED FOLDERS

As described in Chapter 3 of this book, ASP.NET 4.5 includes a number of application folders that are specific to the ASP.NET Framework. In addition to the Bin folder that was a reserved folder in ASP.NET 1.x, the following folders are all reserved in ASP.NET 2.0, 3.5, 4.0, and 4.5:

• Bin: This folder stores the application DLL and any other DLLs used by the application. This folder was present in both ASP.NET 1.0 and 1.1. It is also present in ASP.NET 2.0, 3.5, 4.0 and 4.5.
• App_Code: This folder is meant to store your classes, .wsdl files, and typed data sets. Any items stored in this folder are automatically available to all the pages within your solution.
• App_Data: This folder holds the data stores utilized by the application. It is a good, central spot to store all the data stores used by your application. The App_Data folder can contain Microsoft SQL Express files (.mdf files), Microsoft Access files (.mdb files), XML files, and more.
• App_Themes: Themes are a way of providing a common look-and-feel to your site across every page. You implement a theme by using a .skin file, CSS files, and images used by the server controls of your site. All these elements can make a theme, which is then stored in the App_Themes folder of your solution.
• App_GlobalResources: This folder enables you to store resource files that can serve as data dictionaries for your applications if these applications require changes in their content (based on things such as changes in culture). You can add Assembly Resource Files (.resx) to the App_GlobalResources folder, and they are dynamically compiled and made part of the solution for use by all the .aspx pages in the application.
• App_LocalResources: Quite similar to the App_GlobalResources folder, the App_LocalResources folder is a simple method to incorporate resources that can be used for a specific page in your application.
• App_WebReferences: You can use the App_WebReferences folder and have automatic access to the remote web services referenced from your application.
• App_Browsers: This folder holds .browser files, which are XML files used to identify the browsers making requests to the application and to elucidate the capabilities these browsers have.

The addition of the App_ prefix to the folder names ensures that you do not already have a folder with a similar name in your ASP.NET 1.x applications. If, by chance, you do have a folder with one of the names you plan to use, you should change the name of your previous folder to something else because these ASP.NET 4.5 application folder names are unchangeable.

ASP.NET 4.5 PAGES COME AS HTML5

ASP.NET 4.5, by default, constructs its pages to be HTML5-compliant. You can see the setting for HTML5 in the Visual Studio 2012 IDE, as shown in Figure A-3.

FIGURE A-3

In this case, you can see a list of options for determining how the ASP.NET application outputs the code for the pages. By default, it is set to HTML5. You can also make a change to the web.config file so that the output is not XHTML-specific (as illustrated in Listing A-2).

LISTING A-2: Reversing the XHTML capabilities of your ASP.NET 4.5 application

<configuration>
  <system.web>
       <xhtmlConformance mode="Legacy" />
      </system.web>
</configuration>

Setting the mode attribute to Legacy ensures that XHTML is not used, but instead, ASP.NET 4.5 will use what was used in ASP.NET 1.x.

Note that using the Legacy setting as a value for the mode attribute will sometimes cause problems for your application if you are utilizing Ajax. One of the symptoms that you might experience is that, instead of doing a partial-page update (as Ajax does), you will get a full-page postback. This is because the page is not XHTML-compliant. The solution is to set the mode property to Traditional or Strict and to make your pages XHTML-compliant.

If you take this approach, you also have to make some additional changes to any new ASP.NET 4.5 pages that you create in Visual Studio 2012. Creating a new ASP.NET 4.5 page in Visual Studio 2012 produces the results illustrated in Listing A-3.

LISTING A-3: A typical ASP.NET 4.5 page

<%@ Page Language="VB" %>
<!DOCTYPE HTML>
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    
    </div>
    </form>
</body>
</html>

From this listing, you can see that a <!DOCTYPE ...> element is included at the top of the page. This element signifies to some browsers (such as Microsoft’s Internet Explorer) that the page is XHTML-compliant. If this is not the case, you want to remove this element altogether from your ASP.NET 4.5 page. In addition to the <!DOCTYPE> element, you also want to change the <html> element on the page from:

<html xmlns="http://www.w3.org/1999/xhtml">

to the following:

<html>

The original also signifies that the page is XHTML-compliant (even if it is not) and must be removed if your pages are not XHTML-compliant.

NO HARD-CODED .JS FILES IN ASP.NET 4.5

ASP.NET 1.x provides some required JavaScript files as hard-coded .js files. For instance, in ASP.NET a JavaScript requirement was necessary for the validation server controls and the smart navigation capabilities to work. If you are utilizing either of these features in your ASP.NET 1.x applications, ASP.NET could pick up the installed .js files and use them directly.

These .js files are found at C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\ASP.NETClientFiles. Looking at this folder, you see three .js files — two of which deal with the smart navigation feature (SmartNav.js and SmartNavIE5.js) and one that deals with the validation server controls (WebUIValidation.js). Because they are hard-coded .js files, opening them and changing or altering the code in these files to better suit your needs is possible. In some cases, developers have done just that.

If you have altered these JavaScript files in any manner, you must change some code when migrating your ASP.NET application to ASP.NET 2.0, 3.5, or 4.5. ASP.NET 4.5 dynamically includes .js files from the System.Web.dll instead of hard-coding them on the server. In ASP.NET 4.5, the files are included via a handler — WebResource.axd.

VISUAL STUDIO 2012 PROJECT COMPATIBILITY

As previously mentioned, if you have a preexisting ASP.NET 1.x application, you can run the application on the ASP.NET 4 run time by simply making the appropriate changes in IIS to the application pool. Using the IIS manager or the MMC Snap-In, you can select the appropriate framework on which to run your application from the provided drop-down list.

ASP.NET 4.5 applications work with the Visual Studio 2012 IDE. If you still intend to work with ASP.NET 1.0 or 1.1 applications, you should keep Visual Studio .NET 2002 or 2003, respectively, installed on your machine. Installing Visual Studio 2012 gives you a complete, new copy of Visual Studio and does not upgrade the previous Visual Studio .NET 2002 or 2003 IDEs. All copies of Visual Studio can run side by side.

If you want to run ASP.NET 4.x applications on the .NET Framework 4.5, but you also want to convert the entire ASP.NET project for the application to ASP.NET 4.5, you can use Visual Studio 2012 to help you with the conversion process. After the project is converted, you can build and run the application from Visual Studio 2012. The application is now built and run on the ASP.NET 4 run time.

Visual Studio 2012 has solution- and project-level compatibility with Visual Studio 2010. This means that if you created an ASP.NET application using Visual Studio 2010, you can open this application in Visual Studio 2012, make changes, and open the same application in Visual Studio 2010. All the artifacts of the application will be preserved. This is a very useful feature that supports mixed-mode development, where now you can use Visual Studio 2012 to target applications for ASP.NET 4.0 and ASP.NET 4.5.

---

WARNING Remember: Do not upgrade production solutions without testing your programs first in a staging environment to ensure that your application is not affected by the changes between versions of the .NET Framework.

---

MIGRATING FROM ASP.NET 2.0/3.5/4.0 TO 4.5

Visual Studio 2012 enables you to build applications that can target more than one framework. For instance, Visual Studio .NET 2002 would only let you build 1.0 applications. If you wanted to build .NET Framework 1.1 applications, you were required to install and use Visual Studio .NET 2003. At the same time, Visual Studio .NET 2003 would not enable you to build .NET Framework 1.0 applications, meaning that if you were dealing with applications that made use of either framework, you were required to have both IDEs on your computer.

When you create a new project in Visual Studio 2012, you have the option of targeting the project at any of the following frameworks:

• .NET Framework 2.0
• .NET Framework 3.0
• .NET Framework 3.5
• .NET Framework 4
• .NET Framework 4.5

If you open an ASP.NET application that is built upon the .NET Framework 2.0, you can retarget the application to a newer version of the framework quite easily from the IDE. To do this, right-click the project in the Solution Explorer and select Property Pages from the provided menu. This gives you a form that enables you to change the target framework of the application. In this case, you can see the default options on a Microsoft Windows 8 computer (as shown in Figure A-4).

FIGURE A-4

Changing the target framework as illustrated in Figure A-4 requires Visual Studio 2012 to close and reopen your solution. After this is complete, you will see that even the web.config file was changed to account for working with the newer version of the framework. You might have to address some issues that deal with any breaking changes that have been presented between the releases of ASP.NET, but you can get a quick list of those problems by building the solution within Visual Studio.

SUMMARY

The nice thing with the Visual Studio 2012 IDE is that you are able to upgrade just your ASP.NET solution and not upgrade the framework version to which your solution is targeted. However, in upgrading your ASP.NET solution to the .NET Framework 4.5, you might find that Visual Studio makes this an easy task to achieve.

This appendix looked at upgrading using the IDE as well as some important changes between the releases that are aimed at making your migration as easy as possible.