(Better?) MapGuide API Documentation

While googling for some class in the MapGuide API and forgetting I have a local doxygen-generated copy of the Web API documentation on hand, I stumbled onto this wonderful site call NuDoq which crawls all NuGet packages for relevant API documentation and provides a really slick interface for searching through classes/interfaces/properties/etc.

It obviously picked up the NuGet packages I've created for the .net binding to the MapGuide API and I have to say that the documentation generated by NuDoq is much more usable and accessible that our current doxygen-generated offering. And they even let you download the documentation for offline consumption too, always helpful to have. Sadly, there's still plenty of TODOs sprinkled through the transplanted API documentation, which is obviously telling us there are plenty of classes that still need documenting.

• NuDoq-generated documentation for mapguide-api-base
• NuDoq-generated documentation for mapguide-api-web

Expanded .net development options for MapGuide Open Source 2.4

If you're a .net developer, you'll probably be interested in the expanded array of .net development options for MapGuide.

For the final release of MapGuide Open Source 2.4, we've taken the NuGet packaging work that we've done for mg-desktop and extended it to also include the official MapGuide API. As a result, we had to make some modifications to the existing nuget packages to accommodate the official MapGuide API, and to stay under the 30mb package limit in the NuGet gallery.

There are now 5 different nuget packages (in x86 and x64 flavors, suffixed by -x86 and -x64 respectively):

• mapguide-api-base
• mapguide-api-web
• mg-desktop-net40
• mg-desktop-viewer-net40
• cs-map-dictionaries (this package is CPU-agnostic and is not suffixed)

Whose dependency chain is like so

So based on the type of application you're trying to build, you have the following package configurations.

Building a normal MapGuide .net web application? Install the mapguide-api-web package, that will automatically install the mapguide-api-base pre-requisite. The full set of files in these two packages is the same set of files under the mapviewernet/bin directory that you've always been asked to copy over to your .net application in the past.

Building a desktop-based MapGuide application? Install the mg-desktop-net40 package, that will automatically install the mapguide-api-base pre-requisite. You will also need to have the CS-Map coordinate system dictionaries on hand in order to be able to use any of the MgCoordinateSystem classes in the MapGuide API, or you can install the optional cs-map-dictionaries package that contains a subset of the coordinate system dictionary files.

Building a desktop-based MapGuide windows application? Install the mg-desktop-viewer-net40 package, which will automatically install any upstream pre-requisites. Again, install the cs-map-dictionaries package if you require coordinate system dictionaries.

Building an application that only uses the shared MapGuide components (eg. MgCoordinateSystem)? Install the mapguide-api-base package, and optionally install the cs-map-dictionaries package.

The main benefit of the NuGet approach, is that you no longer fall to the rookie mistake of forgetting to copy over the unmanaged dlls to your application's output directory, as all these nuget packages will insert the appropriate post-build events into your project files to automatically do this for you!

Previously, setting up a skeleton MapGuide .net web application would've been something like this:

1. Create new project in Visual Studio 2010 or 2012
2. Copy over all files from mapviewernet/bin into a staging directory in your project
3. Reference the OSGeo.MapGuide assemblies from the staging directory
4. Set up a post-build event to copy over all unmanaged dlls from the staging directory to your application's output directory
5. Add a call to MapGuideApi.MgInitializeWebTier with the path to the webconfig.ini in the startup routine of your web application.

With the nuget version, this is now:

1. Create new project in Visual Studio 2010 or 2012
2. Install-Package mapguide-api-web-x86 or Install-Package mapguide-api-web-x64
3. Add a call to MapGuideApi.MgInitializeWebTier with the path to the webconfig.ini in the startup routine of your web application.

3 error prone steps (and probably the cause of most .net newbie questions) have been eliminated by nuget.

These nuget packages also include the relevant intellisense files to hopefully keep you away from the main API reference as much as possible :)

Now although NuGet greatly simplifies things, there may be some un-tested scenarios (eg. Continuous Integration) where this type of setup may not work perfectly. Another thing to note is that the .net assemblies in these NuGet packages are all signed whereas the equivalent assemblies that come with MapGuide Open Source 2.4 are not. If you cannot use signed MapGuide assemblies (I can't think of a reason why not), then nuget probably isn't the choice for you and you are better off sticking with the old fashioned way.

As I've mentioned when I first announced the nuget support. I'm still learning this nuget stuff. If I've done something wrong, or something could be done better. Do let me know.

MapGuide-related packages on nuget.org

mg-desktop: The NuGet edition

So with the latest release of mg-desktop, I was supposed to have a NuGet version ready as well.

For those who don't know what NuGet is, it is a Visual Studio 2010 extension which basically functions like an apt-get for libraries and tools in Visual Studio. A command-line version of NuGet also exists.

It turns out nuget.org didn't like my original mg-desktop package which was 38MB in total, so I had to get creative in slicing and dicing this package down to sub-packages of reasonable size, without compromising the utility of the individual sub-packages. The resulting mg-desktop package is now a set of following sub-packages:

• mapguide-api-base
• mg-desktop
• mg-desktop Viewer

mapguide-api-base^ contains the core MapGuide API components

• Foundation
• Geometry
• PlatformBase
• A subset of the CS-Map coordinate system dictionaries

This package is sufficient enough to build applications using only the Coordinate System and Geometry APIs of MapGuide, though you will need to set up the coordinate system dictionary path manually as there is no Platform.ini (which defines this path) to initialize if you are solely using this package. So you will need to have the MENTOR_DICTIONARY_PATH environment variable defined, or point the path manually like so.

mg-desktop* contains the mg-desktop specific components. It has a dependency on mapguide-api-base and will download/install it too if required. This does not have the viewer component, which is a separate package.

mg-desktop Viewer is the viewer component for mg-desktop. It has a dependency on mg-desktop and will download/install it too if required. It will also auto-reference System.Windows.Forms and System.Drawing in your project if needed.

So depending on your particular needs, you select the appropriate packages with NuGet, which will download the required packages/dependencies and automagically set up everything for you (references, post-build steps, etc).

One important thing to note about this package is that it the 32-bit build of mg-desktop for .net Framework 4.0. You cannot consume this package for .net projects whose framework version is < 4.0 and in order for your application to run on 64-bit systems, the root executable project must be explicitly set to x86 and not AnyCPU. Stick with the zip distribution if you are using .net Framework 3.5 or older.

The other important thing to note is that this is my first NuGet package upload. My NuGet n00biness is on full display :-) If there are any problems with any of the packages, I'd appreciate any pointers or patches sent my way to fix these problems.

Download

• mapguide-api-base package home
• mg-desktop package home
• mg-desktop viewer package home

^ I'll probably split off the CS-Map dictionaries into a separate package in a future version. Also if I ever decide to NuGet-ify the official assemblies for MapGuide Open Source 2.4, it will definitely have a dependency on this package.

* Likewise, I'll probably split off FDO into its own package