MaestroAPI and MapGuideDotNetApi with LocalNative connections

This document describes how to use the MapGuideDotNetApi with MapGuide Maestro API.

Why all the trouble

The MaestroAPI is signed with a StrongName key, so you can use it in both strong name signed applications as well as non-signed applications.

If you use the LocalNative connection, Maestro uses the MapGuide binaries to connect to MapGuide. Each version of MapGuide has a new version of the MapGuideDotNetApi, which is often not signed, and usually changes version numbers.

This makes it difficult to use with MaestroAPI, as it is compiled with a reference to a signed MapGuideDotNetApi.

What to do

To work with another version than the one MaestroAPI was compiled for, you need a signed version of the MapGuideDotNetApi and a bindingRedirect.

How to obtain the signed version of MapGuideDotNetApi

If you are targeting a main release of MapGuide, there may be a ready made MapGuideDotNetApi.dll here: ​http://trac.osgeo.org/mapguide/browser/trunk/Tools/Maestro/MaestroAPI/Signer/SignedVersions

If you the version you need is not listed, you can sign the one you have, using this commandline:

signer.exe -k maestroapi.key -outdir .\out -a MapGuideDotNetApi.dll

The maestroapi.key is also avalible from the above link.

Signer.exe is from the ​Signer project.

If your MapGuideDotNetApi.dll is already signed, you need to play tricks with Signer, or simply build the dll from the MapGuide source.

How to use bindingRedirect

As MaestroAPI is compiled with a reference to a certain version of MapGuideDotNetApi, you cannot just update the dll.

Microsoft MSDN has a description of ​the problem and solution.

Basically you place a configuration file with the same name as your executable. For web applications, the file must be named web.config. Example:

MyApplication.exe
MyApplication.exe.configuration

There is a sample config file with the ​pre-signed dll's

You simply add a <bindingRedirect> xml element stating the new version to bind to, eg:

<bindingRedirect oldVersion="2.0.0.2308" newVersion="1.0.0.1" />

You can then replace the MapGuideDotNetApi dll with the one with the new version number.

An optional step is to also point to the correct file. You must do this is the new file is not named MapGuideDotNetApi.dll:

<codeBase version="1.0.0.1" href="C:\MapGuideDotNetApi-2.1.dll"/>

Unfortunately the href path must be absolute.

RFC68

If you use MapGuide Open Source 2.2 or MapGuide Enterprise 2011 or newer releases, the above instructions won't work due to RFC68 splitting MapGuideDotNetApi.dll into 5 separate assemblies. These new releases still work, the process in signing these assemblies is slightly different.

Updated instructions can be found here: ​http://themapguyde.blogspot.com/2010/10/using-maestro-in-native-mode-with.html