Introduction

This document describes what the MapGuideAPI is and how to use it in your own applications.

Background

There already exists a .Net API for communicating with the MapGuide Server, so why create a new one?

I originally started out using the avalible .Net API, but found that it had many shortcommings.

• SWiG

The official API is merely a wrapper over C++ classes, created with the SWiG system. This produces a working interface, and works well with untyped languages such as PHP. It does not work well with the .Net framework, because the intellisense(c) system displays constructors that does not exist. It also lacks all integrated documentation. A particularly annoying problem is that streams are not .Net streams, but a wrapped C++ class called MgStream. This stream is/was very unstable and very cumbersome to read from.

• Xml data

All data stored in the MapGuide Server is Xml data. The API supports reading this data as Xml (with the mentioned stream problem). To manipulate this Xml requires a great insight in how the Xml documents are constructed, and does not have any intellisense(c) support.

• Missing features

Some properties of different objects are not avalible through the API, such as the RequiresRefresh property of the Layer in a runtime map.

• Communcation setup

The API communicates directly with the server process, through TCP/IP. While this is fairly efficient when the server and client is on the same machine, it is a problem when the client is not on the same LAN as the the server. Merely opening the port in the firewall will bring all sorts of security issues. Another problem with this model, is that all classes are serialized into a binary format, and is version dependant. The current build system changes the version number of the API for each build, which forces .Net users to rebuild their application for each MapGuide server version.

I decided to build a new API that could solve all the above problems. This version will not be included in the MapGuide release, because MapGuide supports PHP, JSP and .Net, and any API extension must be avalible in all languages.

MapGuide Communcation

As mentioned above, the MapGuide API communicates directly with the Server process. Another interface is 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 file.

Interface types

To use the MapGuideAPI, 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 uses 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. 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 has no additional dependencies. It takes 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 sorter 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 MapGuideNativeAPI.dll. This file is a slight modification of the MapGuideDotNetAPI.dll from the official MapGuide release. The modifications are made to let it run under the 1.1 version of the .Net framework, and support all versions of the official MapGuide API.

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 MapGuideNativeAPI.dll is located. These binaries are version dependant, and must match the server version.

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:

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

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

MapGuideAPI.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 solves the SWiG problem and Xml problem described above.

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 / MGE2007 to MGOS 2.0).

You cannot 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 MapGuideAPI.RuntimeClasses namespace for manipulating this class. The official API 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:

MapGuideAPI.RuntimeClasses.RuntimeMap map = connection.GetRuntimeMap(resourceID);
MapGuideAPI.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 MapGuideAPI, please look here: Understanding the Code structure.