How to access ArcGIS for Server from a Web application

Summary

This topic provides steps for creating a Web Application Developer Framework (ADF) application in Visual Studio that works with an ArcGIS for Server local data source. A custom tool is created and used to add a graphic point to the map using ArcGIS for Server value objects, and to buffer that point using ArcObjects on the geographic information system (GIS) server. The Web ADF controls used in this topic are MapResourceManager, Map, Toc, and Toolbar.

In this topic

About accessing ArcGIS for Server from a Web application
Accessing ArcGIS for Server from a Web application

About accessing ArcGIS for Server from a Web application

The Web ADF provides the components necessary to work with ArcGIS for Server services. The Web ADF controls utilize the Common Data Source application programming interface (Common API) implementation classes for ArcGIS for Server local and Internet data sources. ArcGIS for Server local data sources connect to the server object manager (SOM) and work directly with a server object. ArcGIS for Server Internet data sources connect to an ArcGIS for Server Web service endpoint.

A number of base classes (for example, MapResourceBase and GISDataSourceBase) define shared members for both ArcGIS for Server data source types, but different implementation and proxy classes are used to initiate and manage the connection with an ArcGIS for Server service.

The Web ADF works with local and Internet ArcGIS for Server services using the ArcGIS for Server Simple Object Access Protocol (SOAP) API (that is, the ArcGIS for Server data source implementation of the Web ADF Common API uses the ArcGIS for Server SOAP API). This means that almost all interaction between Web ADF controls and Common API implementation classes with ArcGIS for Server data sources use SOAP. For more information, see ArcGIS for Server implementation in the Web ADF.

An ArcGIS for Server local data source can access server context to create and work with objects on the server via ArcObjects Component Object Model (COM) proxies on the client. However, the Web ADF is unaware of these changes unless you explicitly inform the Web ADF components. This topic introduces working with ArcGIS for Server data sources in a Web ADF application. Programming with SOAP API value objects on the client and ArcObjects API COM objects on the server are demonstrated.

Local (DCOM) connections are only supported for ArcGIS for Server versions prior to 10.1.

Accessing ArcGIS for Server from a Web application

Do the following steps to access ArcGIS for Server from a Web application:

Create a Web application using the steps in How to create a Web application with Web controls. When adding MapResourceInfo, select an ArcGIS for Server local data source. For the purposes of this topic, do not use a cached map service. For cached services, a Web ADF graphics layer is used rather than adding custom graphics to the map as you will do in this topic. The Web ADF application appears as shown in the following screen shot:
To add an ArcGIS identity to the Web application, right-click the project in the Solution Explorer, then click Add ArcGIS Identity (required when using ArcGIS for Server local data sources). The Add ArcGIS Identity dialog box appears as shown in the following screen shot:

Add the user name, password, and domain or machine name of the account you are using 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 SOM resides. 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.

Step 3 adds the identity with credentials to the web.config file in the Web application. By default, the credentials are encrypted.

In the Solution Explorer, right-click the Web project and click Add New Item. The Add New Item dialog box appears. Under Visual Studio Installed Templates, select Class, set the class file name to PointBufferTool.cs, and set the language to Visual C# (alternatively, you can use VB .NET). Visual Studio prompts you to create an App_Code folder and place the new class file in it. Click Yes. The PointBufferTool.cs file opens for you to add content. This file contains the executable code associated with the custom tool.
In the Solution Explorer, right-click the Web project and Add ArcGIS Reference. This dialog box works similarly to the Add Reference dialog box, but only shows ArcGIS related assemblies. A couple of ArcObjects Primary Interop Assemblies (PIAs) need to be added to the project to work with ArcObjects remotely via the ArcGIS for Server ArcObjects API. In addition, the Web ADF Common API implementation of ArcGIS for Server data sources, contained in the ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer assembly, enables you to work with ArcGIS for Server capabilities exposed by the Web ADF controls (for example, MapFunctionality). It also provides the ability to connect to ArcObjects on the server via server context. The value objects and proxies utilized by the Web ADF to work with ArcGIS for Server data sources are contained in the ESRI.ArcGIS.ADF.ArcGISServer assembly. On the Add ArcGIS Reference dialog box, select the following components, click Add, then click Finish:

ESRI.ArcGIS.ADF.ArcGISServer
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.Local
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer
ESRI.ArcGIS.Carto
ESRI.ArcGIS.Display
ESRI.ArcGIS.Geometry
ESRI.ArcGIS.Serve
ESRI.ArcGIS.Syste

The reference items are added to the web.config file and are available to use in the Web application.

At the top of the PointBufferTool.cs file, add the following using statements (or Imports statements for VB .NET):

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


        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.Carto
Imports ESRI.ArcGIS.Display
Imports ESRI.ArcGIS.Geometry
Imports ESRI.ArcGIS.esriSystem
Imports ESRI.ArcGIS.Server

Remove the PointBufferTool constructor and implement the IMapServerToolAction interface on the PointBufferTool class as shown in the following code example:

[C#]


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

[VB.NET]


        Public Class PointBufferTool
    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 example 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 ESRI.ArcGIS.ADF.Web.UI.WebControls.Map
mapctrl = CType(args.Control, ESRI.ArcGIS.ADF.Web.UI.WebControls.Map

Place this code and the remainder of the code 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 ToolEventArgs to MapPointEventArgs and get the point (mouse click) provided by the end-user in map coordinates as shown in the following code example:

[C#]


        MapPointEventArgs mpea = (MapPointEventArgs)args;

[VB.NET]


        Dim mpea As MapPointEventArgs = CType(args, MapPointEventArgs)

This point will be added to the ArcGIS for Server data source as a custom graphic. To add custom graphics to the map generated by ArcGIS for Server, 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 ArcGIS for Server resource.

To get the MapFunctionality associated with a map resource item, use the resource item name (in this case "MapResourceItem0") as shown in the following code example:

[C#]


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

[VB.NET]


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

Since it is a type of ArcGIS for Server resource, you can cast the functionality to the ArcGIS for Server-specific MapFunctionality. You need to do this to work with ArcGIS for Server specific implementation classes to draw graphics and work with server context.

The Web ADF manages the state of the ArcGIS for Server resource, functionality, and Map control. It uses ArcGIS for 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 for Server data source implementation in the ESRI.ArcGIS.ADF.ArcGISServer assembly and are shared for Internet and local connections.

When working with an ArcGIS for Server MapFunctionality, the MapDescription property provides a value object that can be used to modify the appearance and content of a map generated by an ArcGIS for Server map service as shown in the following code example. In this topic, you will work with the CustomGraphics property to add custom graphics to the map.

[C#]


        ESRI.ArcGIS.ADF.ArcGISServer.MapDescription mapDescription = mf.MapDescription;

[VB.NET]


        Dim mapDescription As ESRI.ArcGIS.ADF.ArcGISServer.MapDescription = mf.MapDescription

When working with a MapDescription value object on the client, create the objects associated with the custom graphics using value objects. In the following code example, a point retrieved from a click on a Map control is used to create a graphic. Convert the user-defined point from a Web ADF geometry to a PointN value object to store the map coordinates used to draw the graphic. The geometry must be stored as an ArcGIS for Server SOAP PointN value object to be added to a 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.NET]


        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, define a graphic element for point (MarkerElement). A MarkerElement has Geometry and Symbol properties that define where and how the MarkerElement is drawn on the map. The Geometry property is set to the PointN object previously created. 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 as shown in the following code example:

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


        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 can now be added as a graphic to the map created by ArcGIS for Server and rendered in a Map control. The previous steps can be used by both ArcGIS for Server Internet and local data sources to draw graphics on a map. To work with ArcObjects on the GIS server, an ArcGIS for Server local resource is required. The following steps use ArcObjects to buffer the point provided by the end user and return a buffer polygon. The polygon is added to MapDescription as another custom graphic.

A reference to an ArcGIS for Server local map resource must be retrieved. Casting the MapResource of an ArcGIS for Server MapFunctionality to type MapResourceLocal provides access to server context. The ServerContextInfo property on MapResourceLocal exposes the map server's server context as shown in the following code example:

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


        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

With access to the server context, you can create ArcObjects on the GIS server to perform work. Since you have an ArcGIS for Server value object point object, use the Web ADF ArcGIS for Server specific Converter class to create a COM object on the GIS server. A reference to the COM object (ArcObjects) is returned. In this case, a reference to point geometry via the IPoint interface is returned. Buffer operations are available via the ITopologicalOperator interface for a point object in ArcObjects. Cast (or query interface [QI]) to this interface and call the Buffer method. For purposes of this topic, the buffer distance is a proportion of the map extent width. This step is shown in the following code example:

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


        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 resulting generated buffer polygon is available as a polygon object on the GIS server. Since 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 a custom graphic. The Web ADF ArcGIS for Server specific Converter class can convert from ArcObjects on the server (via COM proxy reference) to native client value objects. The following code example shows how to create 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.NET]


        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 PolygonN as a graphic, define a graphic element for polygons (PolygonElement). PolygonElement has Geometry and Symbol properties that define where and how PolygonElement is drawn on the map. The Geometry property is set to the PolygonN object associated with the buffer. The Symbol property is set to the appropriate symbol for the element type, in this case, FillSymbol. FillSymbol stores the style and color of the symbol. This step is shown in the following code example:

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


        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

The MarkerElement that displays the user-provided point and the PolygonElement that displays the ArcObjects generated buffer polygon can be added to the MapFunctionality MapDescription as custom graphics. The CustomGraphics property on the MapDescription value object accepts an array of GraphicElement value objects. MarkerElement and PolygonElement derive from the GraphicElement base class. The following code example shows how to create a GraphicElement array, 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.NET]


        Dim ges(2) As ESRI.ArcGIS.ADF.ArcGISServer.GraphicElement
ges(0) = marker
ges(1) = polyelement1
mapDescription.CustomGraphics = ges

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

[C#]


        mapctrl.RefreshResource(mf.Resource.Name);

[VB.NET]


        mapctrl.RefreshResource(mf.Resource.Name)

The implementation code for the custom tool is complete. To add a tool item to the Toolbar 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 ToolbarCollectionEditor Form dialog box appears. On the Toolbar Items section, select the Tool item and click Add. The new Tool appears under the Current Toolbar Contents section as shown on the following screen shot:

Select the new Tool item and examine its properties. The EnablePostBack property is set to false by default. When set to false, using the tool at runtime triggers an asynchronous callback. When set to 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	PointBufferTool	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 called App_Code.
ServerActionClass	PointBufferTool	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 Buffer tool by activating it in the toolbar and clicking the map. The initial mouse click triggers a callback to execute the code in the PointBufferTool class. The custom tool adds graphics to the ArcGIS for Server map resource and redraws the Map control. Each time the tool is applied, a new point and buffer polygon are drawn as graphics on the map as shown on the following screen shot:

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

Resource
Web-tier
Client-tier

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