Migrating the Web ADF from 9.2 to 9.3

In this topic

• About migrating the Web ADF
• Migrating Web mapping applications
• Migrating custom Web ADF applications

About migrating the Web ADF

Migrating Web mapping applications

• Manager—Web mapping application Web sites managed by 9.2 and 9.3 Manager are stored in Sites.xml in the Manager Web application. After installing 9.3 Manager and logging in, you can choose to view current managed Web applications by clicking the Applications tab on the console panel on the left side of the page. If the Sites.xml file references at least one 9.2 application, the following dialog box appears in which to migrate all applications:
  
  
  
  
  When finished, a migration report and status is provided for all Web sites, and all Web applications will use the 9.3 Web ADF components. The following are differences in the Web application:
• Application incorporates the 9.3 Identify tool
• MapTips are enabled on results
• Measure tool graphic remains on extent changes and disappears when another tool is selected
Once migrated, your Web application runs using the 9.3 Web ADF libraries, but retain the look and feel of the 9.2 Web Mapping Application template. To edit a Web application in Manager, upgrade it to the 9.3 Web Mapping Application template. You will be prompted by Manager to upgrade when you try to edit your 9.2 Web application. Upgrading a Web mapping application changes the structure of the application to provide the new 9.3 Web mapping application.
• Web Mapping Application Migration utility—To migrate applications built with the 9.2 Web Mapping Application template outside of Manager, use the Web Application Migration utility. The Web application will not be upgraded to the 9.3 Web Mapping Application template, although it will contain enhancements packaged with the 9.3 Web ADF controls.
  
  To use the utility, click Start, All Programs, ArcGIS, ArcGIS Server for the Microsoft .NET Framework, Web Mapping Application Migration utility. On the ArcGIS Server Web Mapping Utility dialog box, select the applicable check box or check boxes for the current Web site you want to migrate. You can also select a location on the file system to migration Web applications. Only Web applications that contain 9.2 Web mapping application content shows in the list. See the following screen shot:
  
  
  
  
  The Web Mapping Application Migration utility does the following:
• Creates a folder in the Web application root named _92upgradebackup, and copies files updated or replaced in the migration process. These files include web.config, WebMapApp.js, display_measure.js, MapIdentify.cs, Measure.ascx, and Measure.ascx.cs.
• In the web.config file, adds a reference to the System.Web.Extensions assembly.
• In the web.config file, changes the version of the Web ADF assembly references to 9.3.
• Replaces WebMapApp.js in the JavaScript folder.
• Replaces MapIdentify.cs in the App_Code folder.
• Replaces Measure.ascx and Measure.ascx.cs.
• Adds MapIdentifyControl.cs in the App_Code folder.
• Adds MapIdentify.js in the JavaScript folder.
• Adds callbackActivityIndicator2.gif in the images folder.
These modifications enable the Web application to function using the 9.3 Web ADF components. The Web application retains the interface of the 9.2 Web Mapping Application template. For more information on changes in the 9.3 Web ADF, see What's new in 9.3.

Migrating custom Web ADF applications

1. Change the version of the Web ADF and ArcObjects assemblies to use 9.3—You can change the existing reference using Visual Studio. For Web applications, you can modify the web.config file. The specific assembly version is available on the Add Reference dialog box in Visual Studio, in the Global Assembly Cache (GAC), or right-click the assembly in Windows Explorer, and select the Properties and Version tab. The assemblies are installed in the <ArcGIS Install>\DotNet folder.  
   
   To change references for multiple applications at the same time, use the Find and Replace dialog box in Visual Studio. To change reference versions for all files (namely, web.config, *.aspx, and *.csproj) in a directory, open Visual Studio and click Edit, Find and Replace, then Replace in Files. Type the old 9.2 version to find, then the new 9.3 version to use during the replace operation, and select the folder in which the change should occur. To find all 9.2 versions, use regular expressions to locate the text to change. Check the find option Regular Expressions and type the value to find as 9.2.[0-9].[0-9][0-9][0-9][0-9]. 
2. Add a reference to the System.Web.Extensions assembly—This assembly is required for all projects, including Web applications and class libraries that reference Web ADF server controls. This includes references to ESRI.ArcGIS.ADF.UI.WebControls, ESRI.ArcGIS.ADF.Tasks, and ESRI.ArcGIS.ADF.ArcGISServer.Editor. You can add the reference using the Visual Studio Add Reference dialog box.
   
   In Visual Studio 2008, you can set the target version of your Web application to .NET 2.0, 3.0, or 3.5. If building an application with .NET 3.5, select the 3.5 version of the System.Web.Extensions assembly; otherwise, choose the 1.x version. Usually, this enables the Web ADF application to build and function successfully. 

• Using the ASP.NET Asynchronous JavaScript and XML (AJAX) partial postback pattern (adding a ScriptManager to the page)—In general, adding a ScriptManager to a page enables the partial postback pattern for use by the page and its controls. The ScriptManager must be the first control on the page. Additional changes can be required to enable partial postbacks. If working with an existing ASP.NET 2.0 application, a set of ASP.NET AJAX entries must be present in the web.config for partial postbacks to function. For detailed information on configuring an existing Web site to use ASP.NET, see Microsoft ASP.NET AJAX. If these entries are not present, add them manually. If working with an ASP.NET 3.5 application (in Visual Studio 2008), ASP.NET AJAX functionality is already included; therefore, it is not required to manually add these entries.
  
  Converting a Web ADF application to use ASP.NET AJAX partial postbacks instead of client callbacks involves a detailed understanding of the differences between both patterns. For more information, see Working with AJAX and ASP.NET. For more information on AJAX implementation in the Web ADF, see AJAX capabilities in the Web ADF.
• Custom tasks—Custom tasks built with 9.2 must be recompiled and built against the 9.3 assemblies to be used in a 9.3 Web application. A custom task might be deployed in a 9.3 Web ADF application configured to use the .NET 2.0 callback pattern or the ASP.NET AJAX partial postback pattern. As a result, page life cycle and Web request content might change (for example, partial postbacks call render events on the page and controls). Certify that the custom task functions in a partial postback solution if it is for use in a Web ADF application that contains the ASP.NET AJAX ScriptManager control.   
• Customized Web ADF JavaScript libraries—The Web ADF JavaScript files used to support Web ADF controls and functionality has completely changed in 9.3. Although it was unsupported to modify these files in 9.2, the capability to do so was provided via the UseDefaultWebResources and WebResourceLocation, and copies of the files were provided with the 9.2 Web ADF runtime. For 9.3, these properties only apply to images used by Web ADF controls; they cannot be used to reference JavaScript files on disk. The 9.3 Web ADF includes a public JavaScript Library to program against and extend, and is not designed to be replaced or modified.
• Managing shallowly stateful changes to pooled server objects using ArcObjects—In 9.2, managing stateful changes to a pooled server object (shallowly stateful) was possible, given the ability to access server context at the appropriate time to modify and reset the server object. Since all Web requests associated with Web ADF components in a Web application traversed the page life cycle (including map draw, queries, and table of contents [TOC] changes), managing a server object involved managing when to modify the server object in the life cycle. In 9.3, map draw operations do not iterate through the page life cycle. Instead, an Hypertext Transfer Protocol (HTTP) handler, ESRI.ArcGIS.ADF.Web.UI.WebControls.MapHandler, is solely responsible for managing map draw operations. Other actions, such as those initiated from map tools, commands, or TOC changes, still iterate through the page life cycle. As a result, shallowly stateful patterns that worked in 9.2 will not function in 9.3. 
  
  To remedy this situation and take advantage of MapHandler's performance enhancement, changes to the server object state need to be duplicated or shared for map draw and all other Web requests. The MapHandler offers a set of events to override and modify resources before and after map draw. To override the events, create a class and derive from the MapHandler class, and define the events to override. For more information on this technique, see the sample, ArcGIS add dynamic data.