MapDotNet UX uses a map model that leverages XAML. The map model uses classes in ISC.MapDotNetServer.Common and ISC.MapDotNetServer.Common.Maps. Note that the contents of these namespaces are slightly different under Silverlight. These differences will be discussed where applicable.
Maps are generally created using MapDotNet Studio. Maps are represented in code by the map model, which may be manipulated for runtime changes to map displays.
The most common use for the map model is to request a map. This is done through the MapRequest class. If you are working directly with a map service (MapService.svc) through a client proxy, you will serialize a MapRequest and pass it to one of the GetMap methods. In this case you will need to deserialize and handle the MapResponse yourself. If you are using the RIM controls, the Descriptor for a TileLayer that uses an MDNSMapTileRequestor will be a MapRequest. Note: if the RIM map is set up declaratively, the Descriptor in the markup is a string. It is not available as a MapRequest until the RIM Map's TileLayerSetupComplete event occurs.
Properties of the MapRequest class include:
The MapRequest has an instance method, Serialize, that serializes the request to a string. Under Silverlight there is only one version, but otherwise there are two. You should always use the method that takes the simplifyBaselineLayers argument and set it to true. This will significantly reduce the size of the serialized request.
The map object represents a map as a collection of Layers that reference a data source and have rendering instructions. The most common use of the map is within a MapRequest. Map layers can be modified to change how a map will be rendered. If you are using the RIM controls, use the TileLayer.NotifyDescriptorChange() method to refresh the map display after making edits to the Map, map Layers, or layer Classifications.
Properties of the Map class include:
TestForCrossingMaximumExtents - if this is true and MaximumExtents is set, the renderer will attempt to check whether shapes cross the edges of the extents. To use this, the extents should be world bounds, therefore this is testing whether shapes cross the antimeridian (180th meridian). A shape is assumed to cross if it is wider than half the world but less than the full width of the world. The test is applied to the individual parts of multi-shapes. This corrects common problems rendering geographic features that cross the antimeridian, but a side effect is that shapes greater than half the width of the world cannot be correctly rendered. This is set true in the templates used in Studio.
The Layer object references a source of spatial data and has instructions for rendering this data.Properties of the Layer class include:
DefaultClassificationStyle - a RenderStyle object that is used to provide default values for Classification.Style properties that are not set. If there are no Classifications, a single classification using this style is assumed. If a Classification has no style, this is used. When used with multiple Classifications, this allows only the properties that change to be set in each Classification's Style property.
Classifications contain rendering instructions for a layer. A Classification includes details about when a classification is applicable, as well as the actual rendering style.Properties of the Classification class include:
The RenderStyle class contains the actual rendering instructions. There are several things to note about this class.
The RenderStyle class has a large number of properties and subclasses. They are listed here by usage. RenderStyle properties used to render lines and area shapes:
RenderStyle properties used to render points:
RenderStyle properties used to render text (values from Layer.LabelColumn):
The response to a map request is a serialized MapResponse. If a TileLayer is used, it handles the map response. If you call the map service directly, you will need to deserialize and handle the response.
Properties of the MapResponse class include:
RenderStyle objects can contain various WPF objects as XAML. XAML readers and writers can encounter objects that expect to be created within the context of single-threaded-apartment (STA) threads. For applications using the RIM controls this should not be a problem. In certain other contexts, it mat be necessary to create an STA thread to do serialization or deserialization. There are two considerations for such threads.
This issue applies to RenderStyle and all containing classes- Classification, Layer, Map, and MapRequest. It does not apply to the MapResponse.
The following methods are used to get Map objects or to request map images.
string GetBaselineMapDescriptionState(string mapID);
Returns a serialized Map object. Connection strings are removed from this representation.
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, string cacheName, 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 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.
If you want legend icons for your maps you will need to make requests to the MapService's GetLegendIcon method.
string GetLegendIcon(string mapID, string requestXml, string layerID, string classID, double scale, int width, int height);
This returns a serialized MapResponse where most properties other than ImageArray are unset.
The arguments are: