Accessing ArcIMS from a Web application

The Web ADF provides the components necessary to work with ArcIMS services. The Web ADF includes a full-featured ArcIMS API which provides a pure .NET managed solution for ArcIMS developers. The Web ADF controls and Common API utilize the ArcIMS API to work with ArcIMS image services via HTTP or TCP. This tutorial will provide step-by-step instructions for creating a Web ADF application in Visual Studio 2005 that works with an ArcIMS data source. A custom tool will be created and used to add a graphic point to the Map using the ArcIMS API. The following Web ADF controls will be used: MapResourceManager, Map, Toc, Toolbar.

Create a new Web application using the steps in the Creating a Web application with the Web controls tutorial. When adding a MapResourceInfo, select an ArcIMS data source.

The Web ADF application should appear as follows:
In Solution Explorer, right-click the Web project and select "Add New Item...". In the Add New Item dialog, under the Visual Studio Installed Templates section, select the "Class" item. If using C#, set the class file name to "PointTool.cs" and make sure the language is "Visual C#"; if using VB, set the class file name to "PointTool.vb" and make sure the language is "Visual Basic". Visual Studio will prompt you to create an "App_Code" folder and place the new class file inside. Click Yes. The PointTool.cs (or .vb) file should open for you to start adding content. This file will contain the executable code associated with the custom tool.
In Solution Explorer, right-click the Web project and select "Add ArcGIS Reference...". This dialog works similarly to the Add Reference dialog, but only shows ArcGIS-related assemblies. One assembly contains the bulk of the ArcIMS API functionality: ESRI.ArcGIS.ADF.IMS. In addition, the Common API implementation of the ArcIMS data source needs to be added to hook into the ArcIMS API. In the dialog, select the following components, click Add, then Finish:
```
ESRI.ArcGIS.ADF.Web.DataSources.ArcIMS
ESRI.ArcGIS.ADF.IMS
```

At the top of the PointTool.cs 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]

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. The code for the class should appear as follows:

[C#]

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

[VB]

Public Class PointTool
    Implements IMapServerToolAction

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

    End Sub
End Class

Inside the ServerAction method (Sub), insert code to get a reference to the Map control from the ToolEventArgs.Control property. This and the remainder of the code in the tutorial should be placed before the close of the method (for C#, before the first of the two closing braces; for VB, before the End Sub).
[C#]
```
ESRI.ArcGIS.ADF.Web.UI.WebControls.Map mapctrl;
mapctrl = (ESRI.ArcGIS.ADF.Web.UI.WebControls.Map)args.Control;
```
[VB]
```
Dim mapctrl As Map
mapctrl = CType(args.Control, ESRI.ArcGIS.ADF.Web.UI.WebControls.Map)
```
Since the ClientAction for the tool will be set to "Point", cast the ToolEventArgs to MapPointEventArgs and get the point (mouse click) provided by the end-user in map coordinates. This point will be added to the ArcIMS image service as custom graphics in an acetate layer.
[C#]
```
MapPointEventArgs mpea = (MapPointEventArgs)args;



								[VB]
```
```
Dim mpea As MapPointEventArgs = CType(args, MapPointEventArgs)
```
Since we're going to add custom graphics to the map generated by ArcIMS, we 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 MapFunctionalities. In this tutorial, there is only one resource, an ArcIMS resource. To get the MapFunctionality associated with a map resource item, use the resource item name (in this case "MapResourceItem0"). Since we know it is a type of ArcIMS resource, we can cast the functionality to the ArcIMS specific MapFunctionality. We'll need to do this to hook into the ArcIMS API and work with contents of the service.

[C#]
```
ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapFunctionality mf; 
mf = (ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapFunctionality)mapctrl.GetFunctionality("MapResourceItem0");
 
```
[VB]
```
Dim mf As ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapFunctionality
mf = CType(mapctrl.GetFunctionality("MapResourceItem0"), _
     ESRI.ArcGIS.ADF.Web.DataSources.IMS.MapFunctionality)
```
The Web ADF manages the state of the ArcIMS resource, functionality and Map control for us. 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 the MapView. Each MapFunctionality uses a MapView to modify the appearance and content of a map generated by an ArcIMS image map service. In this tutorial, we'll create a new acetate layer, add custom graphics and add the layer to the ArcIMS map service via the MapView.

[C#]
```
ESRI.ArcGIS.ADF.IMS.Carto.MapView mapview = mf.MapView;
```
[VB]
```
Dim mapview As ESRI.ArcGIS.ADF.IMS.Carto.MapView = mf.MapView
```
Since we're working with a MapView object, we need to work with other objects the MapView understands, namely those contained in the ArcIMS API. In this example, we're using a point retrieved from a user-click in a Map control via an ADF tool. The geometry is stored as an ADF type (ESRI.ArcGIS.ADF.Web.Geometry) and 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. We need an IMS geometry type (ESRI.ArcGIS.ADF.IMS.Geometry) to render as graphics in an acetate layer.

[C#]< PRE > 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] < PRE > 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, we need to create an acetate layer. Since we'll use the same acetate layer to store one or more graphic elements, first we'll check if the acetate layer is already part of the MapView's layer collection. If not, we'll create a new acetate layer, set its name, and add it to the MapView's layer collection.

[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]

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, we need to create a GeometryElement and set its symbol. A MarkerElement has an Element and Symbol property to 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 example, we've 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]

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

The GeometryElement is ready to added as a graphic to the acetate layer. Each acetate layer maintains a collection of elements, accessible via the AcetateElements property on the AcetateLayer. Simply add the GeometryElement to the collection.

[C#]
```
ESRI.ArcGIS.ADF.IMS.Display.AcetateElement.AcetateElementCollection aec = 
	alayer.AcetateElements;
aec.Add(ge);
  
```
[VB]
```
Dim aec As ESRI.ArcGIS.ADF.IMS.Display.AcetateElement.AcetateElementCollection = _
   alayer.AcetateElements
aec.Add(ge)
```
To inform the Map control that its content has changed, call the Map.RefreshResource() method and pass the resource name that references the ArcIMS service.

[C#]
```
mapctrl.RefreshResource(mf.Resource.Name);
```
[VB]
```
mapctrl.RefreshResource(mf.Resource.Name)
```
Now that the implementation code for our custom tool is finished, we need to add a tool item to the Toolbar control to trigger the action that executes the custom tool. Select the Toolbar control in design view or in the Properties window, then click the ellipsis for the ToolbarItems property. In the ToolbarItems Collection Editor dialog, add a new "Tool" item. In the Toolbar Items section, select the Tool item and click the Add button. The new Tool should appear under the Current Toolbar Items section.

Select the new Tool item and examine its Properties.

Note that the EnablePostBack property is set to false by default. If false, using the tool at runtime will trigger an asynchronous callback. If true, using the tool will trigger a synchronous postback. Keep the EnablePostBack property set to "False". Set the following properties:

Property	Value	Description
Text	Point Tool	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 named App_Code
ServerActionClass	PointTool	The name of the custom class which implements IMapServerToolAction and will be executed when this tool is used in the map

Run the application. Use the "Point Buffer Tool" tool by activating the tool in the toolbar and clicking on the map. The initial mouse click will trigger 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, another point graphic (green star) is added to the map.

Note: graphics in a Web ADF application can be rendered at three levels: the resource, the Web-tier, or the client tier. This walkthrough is an example of working with graphics at the resource level. For more discussion on different options for creating graphics with a Web ADF application, see the section on Graphics Layers.