Consuming a map service

Complexity: Beginner Data Requirement: Installed with software Goal: Create a desktop client application in Microsoft Visual Studio that consumes an ArcGIS Server map service.

In this tutorial, you will create a desktop client application in Microsoft Visual Studio to consume an ArcGIS Server map service. Visual Studio 2010 is used in the example, but the pattern will work in earlier versions. The MapServer proxy and value objects for the map service will be created dynamically in Visual Studio using the SOAP toolkit (wsdl.exe) included with the .NET 2.0+ SDK. The application will use the ArcGIS Server SOAP API via the MapServer proxy and value objects to request a new map image and display it in the desktop client application. An ArcGIS Server map service that is enabled as a web service will be required for this tutorial.

Tutorial data

Sample code for this tutorial is available at: ConsumingMapService.zip

Create the Windows Application project

Steps:

1. Open Visual Studio and click File > New > Project.
2. In the New Project dialog, expand the Visual C# installed templates list and select Windows.
3. Click the .NET Framework drop-down list and choose .NET Framework 2.0.
4. In the templates list, select Windows Forms Application.
5. For the project name, specify SOAPClient.
6. Click OK. The project will open with a form named Form1.

Add a reference to an ArcGIS Server map service

Steps:

1. In Solution Explorer under the SOAPClient project, right-click the References folder and select Add Web Reference.
2. In the Add Web Reference dialog, in the URL combo box, enter the web service endpoint to the WSDL for an ArcGIS Server map service. For example: http://localhost:6080/arcgis/services/NorthAmerica/MapServer?wsdl.
   Note:

   ?wsdl is appended to the URL to specify that the WSDL for the map service should be returned.

3. Click Go. The methods on the MapServer SOAP proxy display.

4. Change the Web Reference name to something intuitive, such as wsmap, and click Add Reference. The MapServer proxy and value objects are created for you.
   Note:

   The Web Reference name is the namespace for the MapServer proxy and value objects.

Add controls to the Windows form

Steps:

1. Add a Button control to the form and set its Text property to Get Map.
2. Add a PictureBox control to the form. Organize the controls on the form using the screenshot below:

Add code to get a map image and display in the PictureBox control

Steps:

1. Double-click the Get Map button to open the Form1.cs code file to the OnClick event. The following code will use the dynamic ArcGIS Server web service proxy and value objects to request a map image from an ArcGIS Server map service.
2. In the OnClick event method, add the following code:

   Create a new instance of the MapServer proxy and set the Url property to a valid ArcGIS Server map service endpoint.

   wsmap.NorthAmerica_MapServer mapserver = new wsmap.NorthAmerica_MapServer();
   mapserver.Url = "http://localhost:6080/arcgis/services/NorthAmerica/MapServer";
   

   To create a map image two value objects are required, a MapDescription and an ImageDescription. The MapDescription provides the information on the content of the map and the ImageDescription provides image properties. For the MapDescription, use the default MapDescription of the default map data frame in the map document associated with the map service.

   wsmap.MapServerInfo mapinfo = mapserver.GetServerInfo(mapserver.GetDefaultMapName());
   wsmap.MapDescription mapdesc = mapinfo.DefaultMapDescription;
   

   The ImageType value object stores the image format and how it will be returned to the client. In this case, a jpeg image will be created and the url to the image on a web server will be returned to the client.

   wsmap.ImageType imgtype = new wsmap.ImageType();
   imgtype.ImageFormat = wsmap.esriImageFormat.esriImageJPG;
   imgtype.ImageReturnType = wsmap.esriImageReturnType.esriImageReturnURL;
   

   The ImageDisplay value object stores the size and resolution of the map image. The size is defined in pixels - in this case the size of the PictureBox control. The image DPI is used by the map server object to calculate map scale. It will be used to determine if scale dependent layers should be drawn and the size or width of feature or graphic symbols.

   wsmap.ImageDisplay imgdisp = new wsmap.ImageDisplay();
   imgdisp.ImageHeight = pictureBox1.Height;
   imgdisp.ImageWidth = pictureBox1.Width;
   imgdisp.ImageDPI = 96;
   

   ImageDescription is a value object that stores a reference to the ImageDisplay and ImageType value objects.

   wsmap.ImageDescription imgdesc = new wsmap.ImageDescription();
   imgdesc.ImageDisplay = imgdisp;
   imgdesc.ImageType = imgtype;
   

   The ExportMapImage method on the MapServer proxy serializes the MapDescription and ImageDescription value objects into a SOAP request for a new map image and submits it to the web service endpoint defined earlier. A SOAP response is returned and the MapServer proxy deserializes the contents and returns a MapImage value object. In this case, MapImage has a property, ImageURL, which stores the url to the map image generated by the ArcGIS Server map service.

   wsmap.MapImage mapimg = mapserver.ExportMapImage(mapdesc, imgdesc);
   

   Using standard .NET network classes to manage HTTP requests and responses, the map image can be retrieved as a byte stream from the map image url. A new native .NET Image is created locally in memory and assigned to the PictureBox control Image property for display.

   System.Net.HttpWebRequest webreq =
       (System.Net.HttpWebRequest)System.Net.WebRequest.Create(mapimg.ImageURL);
   System.Net.HttpWebResponse webresp =
       (System.Net.HttpWebResponse)webreq.GetResponse();
   System.Drawing.Image img = System.Drawing.Image.FromStream(webresp.GetResponseStream());
   pictureBox1.Image = img;
   

Run the application

Start the application and click on the Get Map button. The PictureBox control displays the map image generated by the ArcGIS Server map service.