About 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 Data Source application programming interface (Common API) implementation classes for ArcGIS Server local and Internet data sources. ArcGIS Server local data sources connect to the ArcGIS Server Object Manager (SOM) and work directly with a server object. ArcGIS Server Internet data sources connect to an ArcGIS Server Web service endpoint.
A number of base classes (for example, MapResourceBase and 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 Server 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.
For more information, see ArcGIS Server implementation in the Web ADF.
An ArcGIS 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 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.
Accessing ArcGIS 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 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:
- Add an ArcGIS identity to the Web application by right-clicking the project in the Solution Explorer window of Visual Studio, and clicking Add ArcGIS Identity on the context menu. This is required when using ArcGIS Server local data sources.
The Add ArcGIS Identity dialog box opens as shown in the following screen shot:
- Enter the user name, password, and domain or machine name of the account you're 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 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, 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 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 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 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 Server data sources are contained in the ESRI.ArcGIS.ADF.ArcGISServer assembly. In 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.Server
- ESRI.ArcGIS.System
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:
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:
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 to get a reference to the Map control from the ToolEventArgs.Control property:
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:
MapPointEventArgs mpea = (MapPointEventArgs)args;
[VB.NET]
Dim mpea As MapPointEventArgs = CType(args, MapPointEventArgs)
This point will be added to the ArcGIS Server data source as a custom graphic.
To add custom graphics to the map generated by ArcGIS Server, 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 ArcGIS 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:
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 Server resource, you can cast the functionality to the ArcGIS Server-specific MapFunctionality. You need to do this to work with ArcGIS Server-specific implementation classes to draw graphics and work with server context.
- The Web ADF manages the state of the ArcGIS Server resource, functionality, and Map control. 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 that can be used to modify the appearance and content of a map generated by an ArcGIS Server map service as shown in the following code. In this topic, you'll work with the CustomGraphics property to add custom graphics to the map.
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, you need to create the objects associated with the custom graphics using value objects. In the following code, a point retrieved from a user-click in 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 Server SOAP PointN value object in order to be added to a MapDescription graphic element array.
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 points (a 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:
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 Server and rendered in a Map control. The steps already presented can be used by both ArcGIS Server Internet and local data sources to draw graphics on a map. To work with ArcObjects on the GIS server, an ArcGIS 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 Server local map resource must be retrieved. Casting the MapResource of an ArcGIS 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:
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 server context, you can create ArcObjects on the GIS server to perform work. Since you have an ArcGIS Server value object point object, use the Web ADF ArcGIS 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) 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:
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 Server-specific Converter class can convert from ArcObjects on the server (via COM proxy reference) to native client value objects. The following code shows how to create a PolygonN value object from the buffer polygon:
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:
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 shows how to create a new 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:
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:
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 Toolbar Collection Editor Form dialog box opens. In the Toolbar Items section, select the Tool item and click Add. The new Tool appears under the Current Toolbar Items section as shown in the following screen shot:
- 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
|
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 Server map resource and redraws the Map control. Each time the tool is applied, a new point and a buffer polygon are drawn as graphics on 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 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.