Upgrading ASP.NET AJAX 1.0 Websites and Web Applications to .NET Framework 3.5
8/10/2007 UPDATE: This blog post was edited to include simplified instructions to work around a known issue w/ Multitargeting support in VS 2008 Beta 2. See “Machine Prerequisites” below.
Microsoft Visual Studio 2008 Beta 2 is finally released, and with it comes a bunch of great new features for writing and maintaining ASP.NET AJAX applications. Additionally, a new version of ASP.NET AJAX is included in the .NET Framework 3.5, which includes improvements over the current ASP.NET AJAX 1.0 release. This article walks you through the steps you’ll need to follow to upgrade your existing ASP.NET AJAX 1.0 Websites and Web Application Projects to use the AJAX support in .NET Framework 3.5 and Visual Studio 2008 Beta 2.
Note: With the new Multitargeting support in Microsoft Visual Studio 2008, It is also possible to continue maintaining ASP.NET AJAX 1.0-based Websites and Web Application Projects in VS 2008 without upgrading them. Click here to learn the steps you can take to maintain and/or create new ASP.NET AJAX 1.0 applications using Microsoft Visual Studio 2008 Beta 2.
Machine Prerequisites:
1. Download and install Microsoft Visual Studio 2008 Beta 2
2. After the Beta 2 installation has finished, you should run this script to ensure that the installation of .NET Framework 3.5 Beta 2 will not affect the development of ASP.NET AJAX 1.0 applications. You should do this immediately after installing VS Beta 2.
3. Apply the following workaround to fix a known issue with Visual Studio’s Multitargeting support for AJAX 1.0. Note that this workaround will *not* be required for the VS 2008 RTM release:
Workaround to Fix VS 2008 Beta 2 Multitargeting Support for AJAX 1.0
1. In Window’s Explorer, go to this folder:
\Program Files\Reference Assemblies\Microsoft\Framework\v3.5
2. Create a folder entitled “Backup” at this location
3. Make a back-up copy of these two assemblies in the new “Backup” folder, and
then delete them from \Program Files\Reference Assemblies\Microsoft\Framework\v3.5:
System.Web.Extensions.dll
System.Web.Extensions.Design.dll
Note: This workaround causes two known side effects to Web Application Projects in VS 2008:
Creating a new 3.5 Web Application Project has a "broken" reference to System.Web.Extensions 0.0.0.0 in the client references list (Project Properties > References). If you build the project, you will encounter this error: The referenced assembly "D:\Program Files\Reference Assemblies\Microsoft\Framework\v3.5\System.Web.Extensions.dll" was not found. If this assembly is produced by another one of your projects, please make sure to build that project before building this one. In order to correct this, you need to manually remove this reference, then Browse... to the location of the System.Web.Extensions 3.5 backup you made in step 3 above to add the reference back to the project.
When upgrading a Web Application Project that uses AJAX 1.0 to .NET Framework 3.5, VS doesn't remove the reference to System.Web.Extensions 1.0.6 in the client references list (Project Properties > References). You need to manually remove this reference and then Browse... to the location of the System.Web.Extensions 3.5 backup you made in step 3 above to add the reference back to the project. This issue and workaround is described in more detail below.
Step One: Upgrade Your ASP.NET AJAX Website
1. First, make a backup of your project, then launch Microsoft Visual Studio 2008 Beta 2.
2. In the File menu, choose Open Website… to open your Website’s folder or IIS virtual directory
a. If you are opening a Web Application project instead, choose “Open Project…”, and navigate to the project file to open it. Follow the steps of the Visual Studio Conversion wizard to migrate the project.
3. When Visual Studio 2008 prompts to upgrade the Website or Web Application, select “Yes”
Important Note: When upgrading a Web Application Project that uses AJAX 1.0 to .NET Framework 3.5, VS doesn't remove the reference to System.Web.Extensions 1.0.6 in the client references list (Project Properties > References). You need to manually remove this reference and then Browse... to the location of the System.Web.Extensions 3.5 backup you made in step 3 above to add the reference back to the project, following these steps:
1. Right-click the project node in Solution Explorer, and choose “Properties”
2. Click the “References” tab
3. Click the reference to “System.Web.Extensions” version 1.0.6 and click the “Remove” button
4. Click the “Add Reference” button
5. Switch to the “Browse” tab
6. Browse to the backup location for the 3.5 version of System.Web.Extensions.dll under \Program Files\Reference Assemblies\Microsoft\Framework\v3.5\Backup and click “OK” to add this reference.
Step Two: Update the ASP.NET AJAX Control Toolkit assembly
If your application uses the ASP.NET AJAX Control Toolkit, you will need to follow these additional instructions to update the toolkit assembly in your application to a new release that works with .NET Framework 3.5:
1. Click here to go to the ASP.NET AJAX Toolkit Release page
2. Download the latest version of the toolkit for .NET Framework version 3.5 (choose one):
a. AjaxControlToolkit-Framework3.5-NoSource.zip
b. AjaxControlToolkit-Framework3.5.zip (includes source code)
3. In Windows Explorer, right-click the zip file and choose “Extract All…” to extract the contents to an “AjaxControlToolkit-Framework3.5” folder in the same directory
4. Copy the AjaxControlToolkit.dll assembly from AjaxControlToolkit-Framework3.5\SampleWebSite\Bin to your application’s Bin directory, replacing the previous version of the toolkit assembly
(Optional): Install the ASP.NET AJAX Toolkit controls to the VS 2008 toolbox
You can also populate the toolbox in VS 2008 with the ASP.NET AJAX Toolkit controls by following these instructions:
1. Open a Web Form (.aspx page) in your project
2. Right-click the Toolbox and choose “Add Tab”
3. Give the new tab a name, such as “ASP.NET AJAX Toolkit 3.5”
4. Right click underneath the new tab and select “Choose Items…” (note that it can take awhile to bring up the this dialog for the first time)
5. In the Choose Toolbox Items dialog, click the Browse… button
6. Browse to \AjaxControlToolkit-Framework3.5\SampleWebSite\Bin, select AjaxControlToolkit.dll, and click the “Open” button.
7. You should see the toolkit controls selected in the Choose Toolbox Items dialog. Click OK to add these controls to the toolbox.
Step Three: Update Web.config to allow 3rd-party AJAX 1.0 components to use .NET Framework 3.5
As described above in Step Two, a new version of the Microsoft ASP.NET AJAX Control Toolkit is available that is compiled against the ASP.NET AJAX (System.Web.Extensions) assembly in .NET Framework 3.5. However, your application may also be using 3rd-party components/assemblies that were compiled against ASP.NET AJAX 1.0. In order for these components to continue working under the .NET Framework 3.5, you must add the following bindingRedirect section to the Web.config file of your ASP.NET AJAX 3.5 application. This causes the 3rd-party component to bind to the 3.5 version of System.Web.Extensions instead of the 1.0 version.
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<dependentAssembly>
<assemblyIdentity name="System.Web.Extensions" publicKeyToken="31bf3856ad364e35"/>
<bindingRedirect oldVersion="1.0.0.0-1.1.0.0" newVersion="3.5.0.0"/>
</dependentAssembly>
</assemblyBinding>
</runtime>
Important: For this configuration to work, ASP.NET AJAX 1.0 must also be installed to the machine.
The bindingRedirect only applies at runtime, so at design-time the third-party component will still be referencing System.Web.Extensions 1.0. As a result, you may encounter the following issues:
· If the third-party component is an ExtenderControl, it will not get the VS 2008 ExtenderControl designer enhancements.
· You will not get intellisense for references to scripts inside the third-party assembly.
· You may get this warning when building your site: “Assuming assembly reference 'System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' matches 'System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35', you may need to supply runtime policy.”
Conclusion
Your Website is now completely upgraded and ready to take advantage of ASP.NET AJAX 3.5!
