Using Web ADF controls in an ASP.NET Web Part and SharePoint 2007

Rex Hansen, a Product Engineer for the .Net Web ADF, contributed this post:

Update: The post below applies to ArcGIS Server 9.2. Click here to see the 9.3 instructions.

The organization of information within a Web site can be challenging, especially when attempting to accommodate multiple end users with different work habits and capabilities. To support this situation, many Web sites utilize some form a portal technology which can provide a framework to modularize information and personalize its presentation. First introduced in ASP.NET 2.0, the Web Parts framework fulfills this need by providing an ASP.NET solution for portal developers. In general, ASP.NET Web Parts are controls that enable developers to encapsulate related functionality and give end users the ability to modify the content, appearance, and behavior of Web pages directly in a browser.

There are a number of options for building an ASP.NET Web Part in Visual Studio 2005: drag and drop Web Part controls in a page, build a Web user control, or create a custom Web Part control. In most cases, Web Parts are supposed to be added\removed at runtime during a user session, so dragging and dropping Web Part controls in a page at design-time does not offer a realistic solution. Web ADF controls will work in user controls, but not if the user control is in a Web Part. This problem is rooted in managing state and control ids for callbacks and cannot be overcome in ArcGIS Server 9.2. This leaves the last option, a custom Web Part control, which also gives you the most control over how the Web Part functions. There are two stages to consider here: support for Web ADF controls in a custom Web Part and deployment of the Web Part. In essence, getting Web ADF controls to work in a custom Web Part involves building a custom composite Web control that inherits from System.Web.UI.WebControls.WebParts.WebPart. Other than the standard pattern for creating a custom composite Web control, such as adding controls during CreateChildControls(), a number of Web ADF control specific issues must be considered:

• In a custom Web Part, Web ADF controls are added dynamically. During a request to a page, the page and its controls (including the Web Part) iterate through their lifecycle. This becomes important when dealing with resources added to a resource manager. Once added, they are maintained in state and retrieved when the resource manager is recreated during the control lifecycle. So as not to keep re-adding resources every time the resource manager is created during the Web Part lifecycle, you need to check session state for the presence of the resource items. If present, do not re-add the resources.
• A set of HTML hidden input elements (fields) are injected in the page at runtime if a Web ADF control is present. These fields store information about the current tool, map mode, and screen coordinates associated with tool interaction in the map, etc. One field, ESRIWebADFHiddenFields, stores a list of all the other field names (input values). This list is used to include the other field values in a callback request. If the Web ADF controls are added after the initial request to the page (such as what happens when a Web Part is added during a full postback to the page), the ESRIWebADFHiddenFields value is empty. As a result, tool interaction with the map is not functional. To workaround this issue, you need to manually set the value of the ESRIWebADFHiddenFields element. Note this will only affect Web Parts that are added after initial page load. If a Web Part is added during initial page load, these fields will be set correctly. Adding more than one Web Part with a Web ADF Map and Toolbar will likely cause conflicts and render some tool interaction with the map non-functional. There is no easy way to overcome this in 9.2. As a result, it is best to add only one Web Part with a Map-Toolbar per page.

On to working with SharePoint - Building a portal site which uses Web Parts can be time consuming; integrating the site into other enterprise systems can be difficult and inefficient; and lastly, managing the site can be overly complex and convoluted. In an attempt to manage enterprise content, intelligence and search systems effectively, Microsoft has created Microsoft Office SharePoint Server 2007, or MOSS for short. MOSS is good for what it claims to do (be an all encompassing enterprise system for sharing information), but it is not simple. Like many software products, more capability means greater complexity. One option for customizing the presentation of content and providing access to business logic is developing custom ASP.NET Web Parts and deploying them on a SharePoint server. An ASP.NET Web Part can be deployed relatively easily with SharePoint 2007. The SharePoint SDK includes a WebPart class which derives from the ASP.NET WebPart. The SharePoint WebPart class offers a few benefits, such as cross-page and non-WebPart connections, which primarily facilitate backward compatibility with SharePoint 2003. For more information on Web Part development with SharePoint 2007, Scott Guthrie provides a bevy of valuable information and links in his blog post Writing Custom WebParts for SharePoint 2007. You can use Sahil Malik’s walkthrough at the beginning of the post to get started creating a custom ASP.NET Web Part.

There are a few issues to consider when deploying a Web Part that contains Web ADF controls in SharePoint 2007:

• SharePoint 2007 was designed to function using the full page postback pattern. As a result, tools in a Web ADF Toolbar may need to trigger a full postback within a custom Web Part to communicate with other parts in the page. Unfortunately the postback event never gets to the tool, so some additional code is required to raise the post back event to the correct control (e.g. Map). See the sample code for more details.
• The SharePoint 2007 server may not have session state enabled, which is necessary for the Web ADF controls to function. If not enabled, SharePoint will return a fairly ambiguous error when attempting to add your custom Web Part to the SharePoint server.

The 9.3 Web ADF will resolve many of the limitations and issues encountered when working with 9.2 Web ADF controls in a Web Part. 9.3 Web ADF controls will be fully supported for use in custom user and composite controls, both of which may be deployed as a Web Part. Multiple Web Parts containing multiple Web ADF controls can function within the same application. The use of ESRIWebADFHiddenFields will be reduced if not removed. And full postbacks initiated by toolbar items will be supported internally.

The sample code includes two projects. The class library project contains the custom Web Part with a MapResourceManager, Map and Toolbar control. The file system Web application contains a simple aspx page designed to emulate a runtime scenario where an end user wants to add a Web Part within the current session. Note, to personalize the page (e.g. add a Web Part at runtime) the current session must be associated with an authenticated user. By default, a file system Web site will used integrated authentication. If deploying as a Web application in IIS, you will need to disable anonymous access to the Web application in IIS. Enabling integrated authentication may offer the easiest solution since you do not need to configure or explicitly set authentication details, instead the authenticated user will be the user account under which the client (browser) is running.

The default personalization provider for ASP.NET 2.0 is SQL Express. If you do not have SQL Express installed, a personalization store will not be created (upon initial execution of the application) and an error will be returned when attempting to add the custom Web Part to the page at runtime. To alleviate this requirement, I have added a custom personalization provider that uses text files. The code, markup, and discussion for this technique is provided here: http://msdn2.microsoft.com/en-us/library/aa479037.aspx

Download the sample code