Accessing ArcGIS Server from a Web application

The Web ADF provides the components necessary to work with ArcGIS Server services. The Web ADF controls utilize the Common API implementation classes for both ArcGIS Server local and internet data sources. ArcGIS Server local data sources connect to the ArcGIS Server Object Manager (SOM) and work with a server object directly. ArcGIS Server internet data sources connect to an ArcGIS Server Web service endpoint. A number of base classes (e.g. MapResourceBase, GISDataSourceBase) define shared members for both ArcGIS Server data source types, but different implementation and proxy classes are used to initiate and manage the connection with an ArcGIS Server service. The Web ADF works with local and internet ArcGIS Services using the ArcGIS Server SOAP API. To put this another way, the ArcGIS Server data source implementation of the Web ADF Common API uses the ArcGIS Server SOAP API. This means that almost all interaction between Web ADF controls and Common API implementation classes with ArcGIS Server data sources use SOAP. See the ArcGIS Server implementation discussion for more details. Note that an ArcGIS Server local data source can access server context to create and work with objects on the server via ArcObjects COM proxies on the client. However, the Web ADF is unaware of these changes unless you explicitly inform the Web ADF components. Use the following walkthrough as an introduction to working with ArcGIS Server data sources in a Web ADF application. Programming with both SOAP API Value objects on the client and ArcObjects API COM objects on the server will be demonstrated.

This tutorial will provide step-by-step instructions for creating a Web ADF application in Visual Studio 2005 that works with an ArcGIS Server local data source. A custom tool will be created and used to add a graphic point to the Map using ArcGIS Server Value objects and buffer that point using ArcObjects on the GIS Server. 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 ArcGIS Server local data source. For the purposes of this tutorial, do not choose a cached map service. For cached services, you would use a Web ADF graphics layer instead of adding custom graphics to the map as you will do in this tutorial.

The Web ADF application should appear as follows:
Add an ArcGIS identity to the web application. This is required when using ArcGIS Server local data sources. To add an identity, right-click on the project in the Solution Explorer window of Visual Studio, and choose Add ArcGIS Identity... from the context menu. This displays the Add ArcGIS Identity dialog. Enter the user name, password, and domain or machine name for the account you wish to use for this application.

The account used in the identity must be an existing account that is a member of the agsusers or agsadmin group on the machine where the ArcGIS Server Object Manager (SOM) runs. The account must also be recognized by the computer where you are running Visual Studio. Therefore, if the SOM is not running on the local Visual Studio machine, the account must be a domain account, and the local Visual Studio computer must be a member of the domain.

This step adds the identity with credentials to the web.config file in the web application. By default the credentials are encrypted.
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. Set the class file name to "PointBufferTool.cs" and make sure the language is "Visual C#" (Alternatively, you can use VB.NET. Code is provided in both languages below). Visual Studio will prompt you to create an "App_Code" folder and place the new class file inside. Click Yes. The PointBufferTool.cs 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. A couple of ArcObjects Primary Interop Assemblies need to added to the project to work with ArcObjects remotely via the ArcGIS Server ArcObjects API. In addition, the Web ADF Common API implementation of ArcGIS Server data sources, contained in the ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer assembly, enables you to work with ArcGIS Server capabilities exposed by Web ADF controls (e.g. MapFunctionality). It also provides the ability to hook into ArcObjects on the server via server context. The value objects and proxies utilized by the Web ADF to work with ArcGIS Server data sources are contained in the ESRI.ArcGIS.ADF.ArcGISServer assembly. In the dialog, select the following components, click Add, then Finish:
```
ESRI.ArcGIS.ADF.ArcGISServer
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer
ESRI.ArcGIS.Carto
ESRI.ArcGIS.Display
ESRI.ArcGIS.Geometry
ESRI.ArcGIS.Server
ESRI.ArcGIS.System
```
After selecting these components, click Add, then click Finish. The reference items are added to the web.config file and are available to use within the web project.

At the top of the PointBufferTool.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.ArcGISServer;
using ESRI.ArcGIS.Carto;
using ESRI.ArcGIS.Display;
using ESRI.ArcGIS.Geometry;
using ESRI.ArcGIS.esriSystem;
using ESRI.ArcGIS.Server;

[VB]

Imports ESRI.ArcGIS.ADF.Web.UI.WebControls.Tools
Imports ESRI.ArcGIS.ADF.Web.UI.WebControls
Imports ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer
Imports ESRI.ArcGIS.Server
Imports ESRI.ArcGIS.Carto
Imports ESRI.ArcGIS.GeomeTry
Imports ESRI.ArcGIS.esriSystem
Imports ESRI.ArcGIS.Display

Remove the PointBufferTool constructor and implement the IMapServerToolAction interface on the PointBufferTool class. The code for the class should appear as follows:

[C#]

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

[VB]

Public Class PointBufferTool
    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 ESRI.ArcGIS.ADF.Web.UI.WebControls.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 ArcGIS Server data source as custom graphics.
[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 ArcGIS Server, 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, and ArcGIS Server 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 ArcGIS Server resource, we can cast the functionality to the ArcGIS Server specific MapFunctionality. We'll need to do this to work with ArcGIS Server specific implementation classes to draw graphics and work with server context.

[C#]
```
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapFunctionality mf; 
mf = (ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapFunctionality)mapctrl.GetFunctionality("MapResourceItem0");
```
[VB]
```
Dim mf As ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapFunctionality
mf = CType(mapctrl.GetFunctionality("MapResourceItem0"), _
   ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapFunctionality)
```
The Web ADF manages the state of the ArcGIS Server resource, functionality and Map control for us. It uses ArcGIS Server Value objects and proxies, which are inherently stateless, in a shallowly stateful manner (state maintained on the client). The Value objects are included as part of the ArcGIS Server data source implementation in the ESRI.ArcGIS.ADF.ArcGISServer assembly and are shared for internet and local connections. When working with an ArcGIS Server MapFunctionality, the MapDescription property provides a Value object which can be used to modify the appearance and content of a map generated by an ArcGIS Server map service. In this tutorial, we'll work with the CustomGraphics property to add a set of custom graphics to the map.

[C#]
```
ESRI.ArcGIS.ADF.ArcGISServer.MapDescription mapDescription = mf.MapDescription;
```
[VB]
```
Dim mapDescription As ESRI.ArcGIS.ADF.ArcGISServer.MapDescription = mf.MapDescription
```
Since we're working with a MapDescription Value object on the client, we need to create the objects associated with our custom graphics using Value objects too. 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.Point) and accessible via the MapPoint property on the event arguments provided to the tool. The ArcGIS Server data source implementation library provides a convenient converter class to convert between ADF and ArcGIS Server geometry types. We need an ArcGIS Server SOAP PointN (ESRI.ArcGIS.ADF.ArcGISServer.PointN) to render as graphics in an MapDescription graphic element array.

[C#]
```
ESRI.ArcGIS.ADF.ArcGISServer.PointN ags_map_point;
ags_map_point = ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.Converter.FromAdfPoint(adf_map_point);
```
[VB]
```
Dim ags_map_point As ESRI.ArcGIS.ADF.ArcGISServer.PointN
ags_map_point = ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.Converter.FromAdfPoint(adf_map_point)
```

To render the PointN as a graphic, we need to define a graphic element for points, a MarkerElement. A MarkerElement has a Geometry and Symbol property to define where and how it is drawn on the map. The Geometry property is set to the PointN object created earlier. The Symbol property is set to the appropriate symbol for the element type - in this case, a MarkerSymbol. The MarkerSymbol stores the type, color, and size of the symbol.

[C#]

ESRI.ArcGIS.ADF.ArcGISServer.RgbColor rgb;
rgb = new ESRI.ArcGIS.ADF.ArcGISServer.RgbColor(); 
rgb.Red = 0;
rgb.Green = 255;
rgb.Blue = 0; 
rgb.AlphaValue = 255;

ESRI.ArcGIS.ADF.ArcGISServer.SimpleMarkerSymbol sms; 
sms = new ESRI.ArcGIS.ADF.ArcGISServer.SimpleMarkerSymbol(); 
sms.Style = ESRI.ArcGIS.ADF.ArcGISServer.esriSimpleMarkerStyle.esriSMSDiamond; 
sms.Color = rgb;
sms.Size = 20.0;

ESRI.ArcGIS.ADF.ArcGISServer.MarkerElement marker; 
marker = new ESRI.ArcGIS.ADF.ArcGISServer.MarkerElement(); 
marker.Symbol = sms;
marker.Point = ags_map_point;

[VB]

Dim rgb As New ESRI.ArcGIS.ADF.ArcGISServer.RgbColor()
rgb.Red = 0
rgb.Green = 255
rgb.Blue = 0
rgb.AlphaValue = 255

Dim sms As New ESRI.ArcGIS.ADF.ArcGISServer.SimpleMarkerSymbol()
sms.Style = ESRI.ArcGIS.ADF.ArcGISServer.esriSimpleMarkerStyle.esriSMSDiamond
sms.Color = rgb
sms.Size = 20.0

Dim marker As New ESRI.ArcGIS.ADF.ArcGISServer.MarkerElement()
marker.Symbol = sms
marker.Point = ags_map_point

The MarkerElement is ready to be added as a graphic to the map created by ArcGIS Server and rendered in a Map control. The steps presented thusfar can be used by both ArcGIS Server internet and local data sources to draw graphics in a map. To work with ArcObjects on the GIS Server an ArcGIS Server local resource is required. The following steps will use ArcObjects to buffer the point provided by the end user and return a buffer polygon. The polygon will be added to MapDescription as another custom graphic. First, a reference to an ArcGIS Server local map resource must be retrieved. Casting the MapResource of an ArcGIS Server MapFunctionality to type MapResourceLocal will provide access to server context. The ServerContextInfo property on MapResourceLocal exposes the map server's server context.

[C#]
```
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceLocal mrl;
mrl = (ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceLocal) mf.MapResource; 
ESRI.ArcGIS.Server.IServerContext serverContext = mrl.ServerContextInfo.ServerContext;
```
[VB]
```
Dim mrl As ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceLocal
mrl = CType(mf.MapResource, _
   ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.MapResourceLocal)
Dim serverContext As ESRI.ArcGIS.Server.IServerContext = _
   mrl.ServerContextInfo.ServerContext
```

Now that we have access to server context, we can create ArcObjects on the GIS Server to perform work. Since we already have an ArcGIS Server Value object point object, we can use the Web ADF's ArcGIS Server specific Converter class to use the Value object to create a COM object on the GIS Server. A reference to the COM object (ArcObject) is returned. In this case, a reference to point geometry via the IPoint interface is returned. For a point object in ArcObjects, buffer operations are available via the ITopologicalOperator interface. Cast (or query interface) to this interface and call the Buffer method. For purposes of this example, the buffer distance is a proportion of the map extent width.

[C#]

ESRI.ArcGIS.Geometry.IPoint ipnt; 
ipnt = (ESRI.ArcGIS.Geometry.IPoint) 
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.Converter.ValueObjectToComObject(ags_map_point,
   serverContext);
ESRI.ArcGIS.Geometry.ITopologicalOperator topop = (ESRI.ArcGIS.Geometry.ITopologicalOperator)ipnt;
double bufferdistance = mapctrl.Extent.Width/6;
ESRI.ArcGIS.Geometry.IPolygon bufferpolygon = 
   (ESRI.ArcGIS.Geometry.IPolygon)topop.Buffer(bufferdistance);

[VB]

Dim ipnt As ESRI.ArcGIS.Geometry.IPoint
ipnt = CType( _
   ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.Converter.ValueObjectToComObject(ags_map_point, serverContext), _
   ESRI.ArcGIS.Geometry.IPoint)
Dim topop As ESRI.ArcGIS.Geometry.ITopologicalOperator = _
   CType(ipnt, ESRI.ArcGIS.Geometry.ITopologicalOperator)
Dim bufferdistance As Double = mapctrl.Extent.Width / 6
Dim bufferpolygon As ESRI.ArcGIS.Geometry.IPolygon = _
   CType(topop.Buffer(bufferdistance), ESRI.ArcGIS.Geometry.IPolygon)

The result buffer polygon has been generated and is available as a polygon object on the GIS Server. Since the ArcGIS Server MapFunctionality uses a client-side, Value object version of MapDescription, the polygon must be converted to a Value object to be added to the MapDescription as custom graphics. The Web ADF's ArcGIS Server specific Converter class can also convert from ArcObjects on the server (via COM proxy reference) to native client Value objects. The code below creates a PolygonN Value object from the buffer polygon.

[C#]
```
ESRI.ArcGIS.ADF.ArcGISServer.PolygonN buffer_polyn;
buffer_polyn = (ESRI.ArcGIS.ADF.ArcGISServer.PolygonN)ESRI.ArcGIS.ADF.ArcGISServer.Converter.ComObjectToValueObject
   (bufferpolygon, serverContext, typeof(ESRI.ArcGIS.ADF.ArcGISServer.PolygonN));
```
[VB]
```
Dim buffer_polyn As ESRI.ArcGIS.ADF.ArcGISServer.PolygonN
buffer_polyn = CType(ESRI.ArcGIS.ADF.ArcGISServer.Converter.ComObjectToValueObject _
   (bufferpolygon, serverContext, GetType(ESRI.ArcGIS.ADF.ArcGISServer.PolygonN)), _
   ESRI.ArcGIS.ADF.ArcGISServer.PolygonN)
```

To render the PolygonN as a graphic, we need to define a graphic element for polygons, a PolygonElement. A PolygonElement has a Geometry and Symbol property to define where and how it is drawn on the map. The Geometry property is set to the PolygonN object associated with our buffer. The Symbol property is set to the appropriate symbol for the element type - in this case, a FillSymbol. The FillSymbol stores the style and color of the symbol.

[C#]

ESRI.ArcGIS.ADF.ArcGISServer.RgbColor rgb1;
rgb1 = new ESRI.ArcGIS.ADF.ArcGISServer.RgbColor();
rgb1.Red = 255; 
rgb1.Green = 255; 
rgb1.Blue = 0; 
rgb1.AlphaValue = 255;

ESRI.ArcGIS.ADF.ArcGISServer.SimpleFillSymbol sfs1;
sfs1 = new ESRI.ArcGIS.ADF.ArcGISServer.SimpleFillSymbol(); 
sfs1.Style = ESRI.ArcGIS.ADF.ArcGISServer.esriSimpleFillStyle.esriSFSForwardDiagonal;
sfs1.Color = rgb1;

ESRI.ArcGIS.ADF.ArcGISServer.PolygonElement polyelement1; 
polyelement1 = new ESRI.ArcGIS.ADF.ArcGISServer.PolygonElement(); 
polyelement1.Symbol = sfs1; 
polyelement1.Polygon = buffer_polyn;

[VB]

Dim rgb1 As New ESRI.ArcGIS.ADF.ArcGISServer.RgbColor()
rgb1.Red = 255
rgb1.Green = 255
rgb1.Blue = 0
rgb1.AlphaValue = 255

Dim sfs1 As New ESRI.ArcGIS.ADF.ArcGISServer.SimpleFillSymbol()
sfs1.Style = ESRI.ArcGIS.ADF.ArcGISServer.esriSimpleFillStyle.esriSFSForwardDiagonal
sfs1.Color = rgb1

Dim polyelement1 As New ESRI.ArcGIS.ADF.ArcGISServer.PolygonElement()
polyelement1.Symbol = sfs1
polyelement1.Polygon = buffer_polyn

Both the MarkerElement to display the user-provided point and the PolygonElement to display the ArcObjects generated buffer polygon are ready to be added to the MapFunctionality MapDescription as custom graphics. The CustomGraphics property on the MapDescription Value object accepts an array of GraphicElement Value objects. Both MarkerElement and PolygonElement derive from the GraphicElement base class. So all we need to do is create a new GraphicElement array and initialize it with the number of elements. Add the MarkerElement and PolygonElement to the array and assign it to the MapDescription.CustomGraphics property.

[C#]
```
ESRI.ArcGIS.ADF.ArcGISServer.GraphicElement[] ges; 
ges = new ESRI.ArcGIS.ADF.ArcGISServer.GraphicElement[2]; 
ges[0] = marker; 
ges[1] = polyelement1; 
mapDescription.CustomGraphics = ges;
```
[VB]
```
Dim ges(2) As ESRI.ArcGIS.ADF.ArcGISServer.GraphicElement
ges(0) = marker
ges(1) = polyelement1
mapDescription.CustomGraphics = ges
```
To inform the Map control that its content has changed, call the Map.RefreshResource() method and pass the resource name that references the ArcGIS Server 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 Buffer Tool	Label for the tool in the Toolbar
ClientAction	Point	Client event passed to the server
Name	PointBufferTool	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	PointBufferTool	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 PointBufferTool class. The custom tool adds graphics to the ArcGIS Server map resource and redraws the Map control. Each time the tool is applied, a new point and buffer polygon are drawn as graphics in 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.