MapDotNet UX Help

Refer to this topic to learn how to use the methods of the Services in your applications.

Getting Started

To start developing applications that use MapDotNet UX Services directly:

  1. Add a 'Service Reference' that refers to your MapDotNet UX Service to your Visual Studio 20xx project.  Available services are

    AdminService.svc - this service is used to manage map files and data tables.
    FeatureService.svc - this service is used for queries.
    FeatureUpdateService.svc - this service is used to edit data records.
    MapService.svc - this service is used to get map images and legend icons.

    There is also a WMS Service discussed below but it is not a WCF service and is not accessed through a service reference.

  2. Create client objects for service references. 
    The following is sample code to create a MapService client.  It assumes that you named your service reference "MapServiceReference" and that you have a variable called "serviceURL" holding the URL base to a MapDotNet UX web services instance.

    MapServiceReference.MapServiceClient client = new MapServiceReference.MapServiceClient(
                "BasicHttpBinding_IMapService",
                serviceURL + "MapService.svc");

    If you are using the RIM controls, the Services member of an MDNSMapTileRequestor or an MDNGeomTileRequestor has factory methods for obtaining service clients. The HTML5 client control uses the REST services only.

  3. Refer to the reference documentation provided here to learn how to make requests and receive responses from the services.

  4. Keep in mind that the SDK includes class libraries that allow you to create requests, serialize them, and de-serialize responses into object hierarchies easily.

Common Uses

The most common uses of the services are obtaining maps, querying layers for attribute data, and editing data.

  1. Obtaining maps.

    The following methods of the map service (MapService.svc) are frequently used.  See the SDK reference for the ISC.MapDotNetServer.Common.Maps namespace for a discussion of classes used by this service.

    string[] GetMapIDs(bool showOnlyEditable);
    Returns an array of available map IDs.

    string GetBaselineMapDescriptionState(string mapID);
    Returns a serialized Map object.  Connection strings are removed from this representation.

    string GetLegendIcon(string mapID, string requestXml, string layerID, string classID, double scale, int width, int height);
    Returns a serialized MapResponse containing a legend icon for the specified Map, Layer, and Classification.  requestXML is an optional MapRequest with rendering instructions and, optionally, a Map object with customized Layer data.

    string GetMap(string requestXml, Guid cancelWorkKey);
    Returns a serialized MapResponse containing the requested map.  requestXML is a serialized MapRequest.  The server implementation is asynchronous.  If you use an asynchronous client method, you can provide a Guid as the cancelWorkKey and the Guid can be used as an argument to CancelGetMap.  Make sure you use a different Guid in each call to BeginGetMap.  If you are not using asynchronous client processing you can pass Guid.Empty as the cancelWorkKey.

    string GetMapWithSpecifiedCaching(string requestXml, MapCacheOptions cacheOption, Guid cancelWorkKey);
    Much like GetMap, but allows you to specify the desired map caching behavior.  Caching must be enabled for this to be of use.

    void CancelGetMap(Guid cancelWorkKey);
    Call this to cancel a pending map request (either of the above two calls) when using asynchronous client methods.  Your BeginGetMap callback handler will still be called but if the cancel request was received before the map request was completed, the Canceled flag will be set on the map response.  If a cancel request is received after a map request is complete it is ignored.

    For more on asynchronous client methods, see http://msdn.microsoft.com/en-us/library/ms228972.aspx.

  2. Querying.

    The following methods of the query service (FeatureService.svc) are frequently used.  See the SDK reference for the ISC.MapDotNetServer.Common.Data namespace for a discussion of classes used by this service.

    string Query(string queryRequest, Guid cancelWorkKey);
    Returns a serialized QueryResponse containing the query results.  queryRequest is a serialized QueryRequest object.  The server implementation is asynchronous and the cancelWorkKey may be used in much the same way it is for the GetMap and CancelGetMap methods discussed above.

    void CancelQuery(Guid cancelWorkKey);
    Call this to cancel a pending query when using asynchronous client methods.

  3. Editing.

    The following method of the edit service (FeatureUpdateService.svc) is frequently used.  See the SDK reference for the ISC.MapDotNetServer.Common.Data and ISC.MapDotNetServer.Common.Data.EditDataModel namespaces for a discussion of classes used by this service.

    string Edit(string editRequest)
    Returns a serialized DataTable.  editRequest is a serialized EditRequest object.  Note that the DataTable returned is an instance of ISC.MapDotNetServer.Common.Data.EditDataModel.DataTable, not System.Data.DataTable.  The DataTable will correspond to the one attached to the EditRequest, but the only row values that will be present will be RowState, RowError, and any primary key column that was populated with auto-generated values during row inserts.

  4. WMS

    WMS is not a WCF service as are the others.  WMS is a protocol for map sharing developed by the Open Geospatial Consortium, Inc.® (OGC).  MapDotNet UX supports a basic WMS, that is, one with map services but not feature (WFS) services.

    WMS is primarily used for publishing maps for use in third-party applications, but WMS maps may also be consumed by your own RIM projects by using a WMSTileRequestor or by creating appropriate HTTP query strings for WMS GetMap and GetCapabilities requests.

The Admin Service

The admin service, while less commonly used, has powerful features for managing map files and data sources.  Studio makes use of the AdminService to perform many of its functions.

  1. Map File Management

    string GetMapFile(string mapID);
    Returns a serialized Map object.  Unlike MapService.GetBaselineMapDescriptionState, this includes connection strings.

    string InsertMapFile(string serializedMap);
    string UpdateMapFile(string serializedMap);
    string DeleteMapFile(string mapID);

    These methods are used to add a new map to the service, to update an existing map, or to delete an existing map.

    string GetSpatialTableDescription(
    ConnectionDataSourceSpecification.ConnectionTypes connectionType,
    string serializedConnectionString,
    string tableName);
    string[]
    GetSpatialTableDescriptions(
    ConnectionDataSourceSpecification.ConnectionTypes connectionType,
    string
    serializedConnectionString);
    These methods are used to get information about either a specific spatial data table or all spatial data tables available for a given connection.  The "serializedConnectionString" argument is a serialized instance of the ISC.MapDotNetServer.Common.ConnectionString class.  The return value is either a single serialized ISC.MapDotNetServer.Common.Data.Interrogation.SpatialTableDescription or an array of them.

    string CreateSpatialTable(
    ConnectionDataSourceSpecification.ConnectionTypes connectionType,
    string serializedConnectionString,
    string serializedTableDescription,
    string serializedIndexSpecification);

    This method is used to create a new spatial table.  This is not supported for shapefile or ArcSDE connections.  The "serializedConnectionString" argument is a serialized instance of the ISC.MapDotNetServer.Common.ConnectionString class.  The "serializedTableDescription" is a serialized ISC.MapDotNetServer.Common.Data.Interrogation.SpatialTableDescription.  The "serializedIndexSpecification" is a serialized ISC.MapDotNetServer.Common.Data.Interrogation.SpatialIndexSpecification.  The return value is a serialized ISC.MapDotNetServer.Common.Data.Interrogation.SpatialTableOperationResult.

    string DropSpatialTable(
    ConnectionDataSourceSpecification.ConnectionTypes connectionType,
    string serializedConnectionString,
    string tableName);
    string TruncateSpatialTable(
    ConnectionDataSourceSpecification.ConnectionTypes connectionType,
    string serializedConnectionString,
    string tableName);

    These methods are used to drop a spatial table or to remove all the data from one.  These are not supported for shapefile connections.  The "serializedConnectionString" argument is a serialized instance of the ISC.MapDotNetServer.Common.ConnectionString class.  The return value is a serialized ISC.MapDotNetServer.Common.Data.Interrogation.SpatialTableOperationResult.