How to access ArcIMS from a Web application

Summary The Web Application Developer Framework (ADF) provides components that work with ArcIMS services. The Web ADF includes a full-featured ArcIMS application programming interface (API) that provides a pure .NET managed solution for ArcIMS developers. The Web ADF controls and Common Data Source API (Common API) utilize the ArcIMS API to work with ArcIMS image services via Hypertext Transfer Protocol (HTTP) or Transmission Control Protocol (TCP).

This topic provides step-by-step instructions for creating a Web ADF application in Visual Studio 2005 that works with an ArcIMS data source. A custom tool is created and used to add a graphic point to the map using the ArcIMS API. The Web ADF controls used are MapResourceManager, Map, Toc, and Toolbar.

Create a Web application using the steps in How to create a Web application with Web controls. When adding MapResourceInfo, select an ArcIMS data source.
The Web ADF application window appears as shown in the following screen shot:

In Solution Explorer, right-click the Web project and click Add New Item. The Add New Item dialog box opens. Under Visual Studio Installed Templates, select Class. If you're using C#, set the class file name to PointTool.cs and the language to Visual C#; if you're using Visual Basic, set the class file name to PointTool.vb and the language to Visual Basic. Visual Studio prompts you to create an App_Code folder and place the new class file in it. Click Yes. The PointTool file opens for you to add content. This file contains the executable code associated with the custom tool.
In Solution Explorer, right-click the Web project and click Add ArcGIS Reference. This dialog box works similarly to the Add Reference dialog box, but only shows ArcGIS-related assemblies. The ESRI.ArcGIS.ADF.IMS assembly contains most of the ArcIMS API functionality. The Common API implementation of the ArcIMS data source must be added to connect to the ArcIMS API. In the Add ArcGIS Reference dialog box, select the following components, click Add, then click Finish:

ESRI.ArcGIS.ADF.Web.DataSources.ArcIMS
ESRI.ArcGIS.ADF.IMS

At the top of the PointTool file, add the following using statements:

[C#]


        using ESRI.ArcGIS.ADF.Web.UI.WebControls.Tools;
using ESRI.ArcGIS.ADF.Web.UI.WebControls;
using ESRI.ArcGIS.ADF.Web.DataSources.IMS;
using ESRI.ArcGIS.ADF.IMS.Display.AcetateElement;
using ESRI.ArcGIS.ADF.IMS.Display.Symbol;
using ESRI.ArcGIS.ADF.IMS.Carto;
using ESRI.ArcGIS.ADF.IMS.Carto.Layer;

[VB.NET]


        Imports ESRI.ArcGIS.ADF.Web.UI.WebControls.Tools
Imports ESRI.ArcGIS.ADF.Web.UI.WebControls
Imports ESRI.ArcGIS.ADF.Web.DataSources.IMS
Imports ESRI.ArcGIS.ADF.IMS.Display.AcetateElement
Imports ESRI.ArcGIS.ADF.IMS.Display.Symbol
Imports ESRI.ArcGIS.ADF.IMS.Carto
Imports ESRI.ArcGIS.ADF.IMS.Carto.Layer

Remove the PointTool constructor if present, and implement the IMapServerToolAction interface on the PointTool class as shown in the following code:

[C#]


        public class PointTool: IMapServerToolAction
{
    public void ServerAction(ToolEventArgs args){}
}

[VB.NET]


        Public Class PointTool
    Implements IMapServerToolAction
    
    Public Sub ServerAction(ByVal args As ToolEventArgs) _
                            Implements IMapServerToolAction.ServerAction
        
    End Sub

End Class

In the ServerAction method (Sub), insert the following code to get a reference to the Map control from the ToolEventArgs.Control property:

[C#]


        ESRI.ArcGIS.ADF.Web.UI.WebControls.Map mapctrl;
mapctrl = (ESRI.ArcGIS.ADF.Web.UI.WebControls.Map)args.Control;

[VB.NET]


        Dim mapctrl As Map
mapctrl = CType(args.Control, ESRI.ArcGIS.ADF.Web.UI.WebControls.Map)

Place this code, and the remainder of the code referenced in this topic, before the close of the method. That is, before the first of the two closing braces in C#, and before the End Sub in VB.NET.

Since the ClientAction for the tool is set to Point, cast the ToolEventArgs to MapPointEventArgs and get the point (mouse click) provided by the end-user in map coordinates as shown in the following code:

[C#]


        MapPointEventArgs mpea = (MapPointEventArgs)args;

[VB.NET]


        Dim mpea As MapPointEventArgs = CType(args, MapPointEventArgs)

To add custom graphics to the map generated by ArcIMS, you need to get the Web ADF functionality associated with drawing map images. When a Map control consumes a resource, it generates a MapFunctionality, one for each resource. As a result, a Map control can have an array of map functionalities. In this topic, there is one map (ArcIMS) resource. To get the MapFunctionality associated with a map resource item, use the resource item name (in this case "MapResourceItem0").

Use the following code to get the MapFunctionality associated with this resource:

[C#]


        ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapFunctionality mf;
mf = (ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapFunctionality)mapctrl.GetFunctionality(
    "MapResourceItem0");

[VB.NET]


        Dim mf As ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapFunctionality
mf = CType(mapctrl.GetFunctionality("MapResourceItem0"), _
     ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapFunctionality)

Since it is a type of ArcIMS resource, you can cast the functionality to the ArcIMS-specific MapFunctionality. You need to do this to work with the ArcIMS API and the contents of the service.

The Web ADF manages the state of the ArcIMS resource, functionality, and Map control. It uses ArcIMS API classes, which are inherently stateless, in a shallowly stateful manner (state maintained on the client—in this case, the Web ADF application). The primary ArcIMS class used to interact with a map service is MapView. Each MapFunctionality uses MapView to modify the appearance and content of a map generated by an ArcIMS image map service as shown in the following code:

[C#]


        ESRI.ArcGIS.ADF.IMS.Carto.MapView mapview = mf.MapView;

[VB.NET]


        Dim mapview As ESRI.ArcGIS.ADF.IMS.Carto.MapView = mf.MapView

In the next few steps, you'll create an acetate layer, add custom graphics, and add the layer to the ArcIMS map service via MapView. When working with a MapView object, you need to work with other objects that MapView understands, namely those contained in the ArcIMS API.

In the following step, a point retrieved from a user-click in a Map control is used to create a graphic. In this case, the click point is passed to the example code by a Web ADF tool.

The geometry of the click point is stored as an ADF type (ESRI.ArcGIS.ADF.Web.Geometry). This point is accessible via the MapPoint property on the event arguments provided to the tool. The ArcIMS data source implementation library provides a convenient converter class to convert between ADF and IMS geometry types. Convert the user-defined point from the ADF geometry to an ArcIMS point using the class provided by the Web ADF for conversion between ADF and ArcIMS geometry types:

[C#]


        ESRI.ArcGIS.ADF.IMS.Geometry.Point ims_map_point = 
    (ESRI.ArcGIS.ADF.IMS.Geometry.Point)
    ESRI.ArcGIS.ADF.Web.DataSources.IMS.Converter.ToIMSGeometry(mpea.MapPoint);

[VB.NET]


        Dim ims_map_point As ESRI.ArcGIS.ADF.IMS.Geometry.Point = _
                                                          CType(ESRI.ArcGIS.ADF.Web.DataSources.IMS.Converter.ToIMSGeometry(mpea.MapPoint), _
                                                          ESRI.ArcGIS.ADF.IMS.Geometry.Point)

To add graphics to the map image generated by ArcIMS, create an acetate layer. You'll use this layer to store one or more graphic elements. Before creating the acetate layer, confirm it's not already part of the MapView layer collection. If it's not, create the layer, set its name, and add it to the MapView layer collection as shown in the following code:

[C#]


        ESRI.ArcGIS.ADF.IMS.Carto.Layer.AcetateLayer alayer = 
    (ESRI.ArcGIS.ADF.IMS.Carto.Layer.AcetateLayer)mapview.Layers.FindByName(
    "acetate_name");
if (alayer == null)
{
    alayer = new ESRI.ArcGIS.ADF.IMS.Carto.Layer.AcetateLayer();
    alayer.Name = "acetate_name";
    mapview.Layers.Add(alayer);
}

alayer.Visible = true;

[VB.NET]


        Dim alayer As ESRI.ArcGIS.ADF.IMS.Carto.Layer.AcetateLayer = _
                                                             CType(mapview.Layers.FindByName("acetate_name"), _
                                                             ESRI.ArcGIS.ADF.IMS.Carto.Layer.AcetateLayer)
If alayer Is Nothing Then
    alayer = New ESRI.ArcGIS.ADF.IMS.Carto.Layer.AcetateLayer()
    alayer.Name = "acetate_name"
    mapview.Layers.Add(alayer)
End If
alayer.Visible = True

To render an ArcIMS API Point as a graphic, create a GeometryElement and set its symbol as shown in the following code. A GeometryElement has Element and Symbol properties that define where and how it is drawn on the map. The Element property is set to the ArcIMS Point object created earlier. The Symbol property is set to the appropriate symbol for the element type—in this case, a marker symbol. The SimpleMarkerSymbol class stores the type, color, and size of the symbol. In this step, you also set the outline symbol.

[C#]


        ESRI.ArcGIS.ADF.IMS.Display.AcetateElement.GeometryElement ge = new
    ESRI.ArcGIS.ADF.IMS.Display.AcetateElement.GeometryElement
    (ESRI.ArcGIS.ADF.IMS.Display.AcetateElement.AcetateUnits.Database);
ge.Element = ims_map_point;


ESRI.ArcGIS.ADF.IMS.Display.Symbol.SimpleMarkerSymbol sms = new
    ESRI.ArcGIS.ADF.IMS.Display.Symbol.SimpleMarkerSymbol();
sms.Color = System.Drawing.Color.SpringGreen;
sms.Type = ESRI.ArcGIS.ADF.IMS.Display.Symbol.MarkerSymbolType.Star;
sms.OutlineColor = System.Drawing.Color.Black;
sms.Width = 24;
ge.Symbol = sms;

[VB.NET]


        Dim ge As New ESRI.ArcGIS.ADF.IMS.Display.AcetateElement.GeometryElement( _
                                                                         ESRI.ArcGIS.ADF.IMS.Display.AcetateElement.AcetateUnits.Database)
ge.Element = ims_map_point
Dim sms As New ESRI.ArcGIS.ADF.IMS.Display.Symbol.SimpleMarkerSymbol()
sms.Color = System.Drawing.Color.SpringGreen
sms.Type = ESRI.ArcGIS.ADF.IMS.Display.Symbol.MarkerSymbolType.Star
sms.OutlineColor = System.Drawing.Color.Black
sms.Width = 24
ge.Symbol = sms

Add GeometryElement to the acetate layer as a graphic. Each acetate layer maintains a collection of elements, accessible via the AcetateElements property on the AcetateLayer. Add GeometryElement to the collection as shown in the following code:

[C#]


        ESRI.ArcGIS.ADF.IMS.Display.AcetateElement.AcetateElementCollection aec =
    alayer.AcetateElements;
aec.Add(ge);

[VB.NET]


        Dim aec As ESRI.ArcGIS.ADF.IMS.Display.AcetateElement.AcetateElementCollection = _
                                                                                 alayer.AcetateElements
aec.Add(ge)

Call the Map.RefreshResource() method to inform the Map control that its content has changed as shown in the following code:

[C#]


        mapctrl.RefreshResource(mf.Resource.Name);

[VB.NET]


        mapctrl.Refresh(mf.Resource.Name)

The implementation code for the custom tool is complete. To add a tool item to the Toolbar control to execute the custom tool, select the Toolbar control in design view or in the Properties window, then click the ellipsis for the ToolbarItems property. The Toolbar Collection Editor Form dialog box opens. Under Toolbar Items, select the tool item and click Add. The new tool appears under Current Toolbar Contents as shown in the following screen shot:

Screen shot of theToolbar Collection Editor Form dialog box.

Select the new tool item and examine its Properties.

The EnablePostBack property is set to false by default. When it's false, using the tool at runtime triggers an asynchronous callback. If it's true, using the tool triggers a synchronous postback. Keep the EnablePostBack property set to false and set the properties as shown in the following table:

Property	Value	Description
Text	PointTool	Label for the tool in the toolbar
ClientAction	Point	Client event passed to the server
Name	PointTool	Object name of the tool if used in code
ServerActionAssembly	App_Code	Class libraries associated with a Web site are compiled into an assembly called App_Code
ServerActionClass	PointTool	Name of the custom class that implements IMapServerToolAction and is executed when this tool is used in the map

Run the application. Use the Point tool by activating it in the toolbar, then clicking the map. The initial mouse click triggers a callback to execute the code in the PointTool class. The custom tool adds graphics to an acetate layer in the ArcIMS map resource and redraws the Map control. Each time the tool is applied, a point graphic (in this case, a green star) is added to the map as shown in the following screen shot:

Graphics in a Web ADF application can be rendered at the following levels:

Resource
Web tier
Client tier

This topic explained how to work with graphics at the resource level. For more options on creating graphics with a Web ADF application, see the Graphics layers section in the Web ADF and data sources topic.