Web controls and the server API

---

Some Web applications use the geographic information system (GIS) server via the Web controls. To build sophisticated GIS applications that go beyond the functionality exposed by the Web controls, you need to understand both the server programming model and the relationship between the server application programming interface (API) and the Web controls API.

The following two points are important with respect to Web controls and the server API:

A MapServer is associated with a Map control as one of the control's resources via its MapResourceManager. Each resource has associated functionalities, and these functionalities are constructed as needed by the controls. The functionality manages the MapDescription of the MapServer object in session state. It has a LoadState and SaveState method that load and save the MapDescription to and from session state. These methods are called during the Web page's lifecycle. When you use methods on the map control, such as Zoom and CenterAt, to navigate the map, the functionality internally uses SaveObject and LoadObject to maintain stateful aspects of the application, such as current extent, within session state. The page layout control does the same for the PageDescription and the collection of MapDescriptions associated with the MapServer page layout. The TOC control has methods for turning the visibility of layers displayed in a map control on and off. As with the map and page layout controls, using the methods on the TOC control to turn layers on and off will update the session's copy of the MapDescription.

If you want to manipulate the MapDescription yourself—for example, to add graphics to the map—you can ask the functionality for its MapDescription, in which case you will be manipulating the copy of the map description that the functionality is managing in session state for you.

The controls also manage the acquisition and release of server contexts. As with loading and saving state in the page lifecycle, the acquisition and release of the server context is also handled by the functionality associated with the MapServer as part of the Web page lifecycle.

When a map resource associated with a Map control's DataSource property is set to be a pooled server object, and when you get the functionality from the Map control, the control is internally using CreateServerContext to create a new server context using the DataSource property of the map resource to create a server context for the appropriate MapServer object. When the page lifecycle ends, the control internally calls ReleaseContext to release the context. The methods exposed by the Web controls are stateless, so a server object's state is never altered by calling one of the methods on a Web control.

When a map resource associated with a Map control's DataSource property is set to be a non-pooled server object, the control will create a server context at the beginning of the session and hold on to the same server context for the entire session. The functionality uses the context already in session, and when the page lifecycle ends, the context is not released.