MaestroAPI basics

This page describes how to use the MapGuide Maestro API in your own application.

MapGuide Communication

The official MapGuide API communicates directly with the Server process. But there exists another interface: the Web interface. A test form for the Web interface can be found at ​http://localhost/!MapGuide/mapagent/index.html (assuming you have already installed the MapGuide server and WebExtension for IIS). Even though there is no documentation for this interface, it is fairly easy to guess what the different parameters are for. By examining these pages, it is simple to see that they all post the parameters to the mapagent.fcgi handler.

Interface types

To use the MaestroAPI, you must reference the MapGuideAPI.dll. Once you have a reference to this file, you can create two types of connections called HttpServerConnection and LocalNativeConnection. The first uses the http interface mentioned above, the other use the MapGuide binaries to connect to the server. Using the http method is much more flexible, but does not support some FDO operations, such as creating a new SDF file, and has some added overhead from the WebServer. The later requires an initialization file and an open port set up, but it has the benfit of increased speed.

The HttpServerConnection solves dependency of server version, and removes the need for openening anything but the Web Server.

The LocalNativeConnection provides a faster alternative in the case where an extra open port is not a security issue. It is also removes the need for a recompilation when the server binaries change (at least backwards compatible).

Specific information for the HttpServerConnection

The HttpServerConnection is 100% managed, and uses no external libraries, except ​TF-net for queries with geometry. HttpServerConnection uses a full URL to the mapagent.fcgi. The most common url would be: ​http://localhost/MapGuide/mapagent/mapagent.fcgi

There is a fallback mechanism that allows usage of the shorter URL: ​http://localhost/MapGuide

But it requires a failed call, and thus has a bit more overhead in the setup phase.

Extra setup for the LocalNativeConnection

If you choose LocalNativeConnection, you must also reference the file MapGuideDotNetAPI.dll. There is a signed version of this file distributed with the binaries, because the official dll was not signed. There is also a signed copy in the MaestroAPI source code folder.

The official MapGuide API also reads a configuration file called webconfig.ini. This file must also be present in the directory. Please note that using an outdated version of this file will cause the official API to throw a "File Not Found" exception, even though the file is readable.

Finally, to use the LocalNativeConnection, some dll files from the MapGuide server is required. The easiest way to retrieve these, is to simply copy the contents of the WebServerExtensions\www\mapviewernet\bin into the folder where the MapGuideDotNetAPI.dll is located. These binaries are version dependant, and must match the server version. Be carefull not to overwrite the MapGuideDotNetAPI.dll.

Using the interface

Both connection classes implement the interface !MapGuideAPI.ServerConnectionI, so if you only declare your connection to be of this type, you can change connection type as you please:

MaestroAPI.ServerConnectionI connection = new MaestroAPI.HttpServerConnection(url, sessionID, locale);

Note that the above method is deprecated for releases after 2.0 and will be eventually removed. The recommended way to create a connection for releases after 2.0 is as follows:

MaestroAPI.ServerConnectionI connection = MaestroAPI.ConnectionFactory.CreateHttpConnection(url, sessionID, locale, true);

Or, using the "generic" but more verbose way:

MaestroAPI.ServerConnectionI connection = MaestroAPI.ConnectionProviderRegistry.CreateConnection("Maestro.Http", "Url=" + url + ";SessionId=" + sessionID + ";Locale=" + locale + ";AllowUntestedVersion=true");

Once you have a connection instance, you can load and save resources:

MaestroAPI.MapDefintion mapDef = connection.GetMapDefinition(resourceId);
mapDef.BackgroundColor = System.Drawing.Color.Yellow;
connection.SaveResource(mapDef);

Notice that the mapDef is a type with properties, and not an Xml document. All properties on the object are typesafe, and provides full intellisense support (well, potentially. It is a huge amount of work to comment all the properties, so it is not 100% complete yet). This is a major help if you want to do more than just manipulate the runtime map.

The Runtime Map

A very special part of the MapGuide server, is the Runtime map. Whenever you start a MapGuide application, the viewer takes the MapDefinition (in Xml format) and constructs a binary version of the Xml version. This binary version holds all info from the MapDefinition along with some extra info about the layers (primary key, etc). There exists no http interface to create this runtime map, but I have created a managed equvalent that supports all versions of the MapGuide server (from MGOS 1.0 / MGE2009 to MGOS 2.0).

If you use the regular viewer, you annot pre-create this, as the viewer blindly re-creates this on startup. You must modify the mapframe.? file if you want to override this behavior. Unfortunately this will break on each upgrade. I'm not quite sure what options are avalible in Fusion.

Whenever you are interacting with a viewer, you must modify the Runtime map, NOT the mapdefinition. You must use the classes under the MaestroAPI.RuntimeClasses namespace for manipulating this class. The official documentation is a bit fussy on making the distinction between a runtime map (binary) and a map defintion (xml).

Example usage for the runtime class is:

MaestroAPI.RuntimeClasses.RuntimeMap map = connection.GetRuntimeMap(resourceID);
MaestroAPI.RuntimeClasses.RuntimeMapLayer layer = map.Layers[layername];
layer.DisplayOrder = 0;
layer.NeedsRefresh = true;
connection.SaveRuntimeMap(resourceID, map);

If you want to dwelve into the internal workings of the MaestroAPI, please look here: Understanding the Code structure.