Tuesday, 9 October 2012

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.


Wilson H said...


i am experiencing some issue when i try to use the nuget package.

i got this error message

Error 1 The command "
xcopy /s /y "C:\inetpub\wwwroot\test\packages\mapguide-api-base-x64.\mapguide-api-base\*.*" "C:\inetpub\wwwroot\test\test\bin\"
xcopy /s /y "C:\inetpub\wwwroot\test\packages\mapguide-api-web-x64.\mapguide-api-web\*.*" "C:\inetpub\wwwroot\test\test\bin\"" exited with code 4. test

do you this may be misconfiguration on my side?

Jackie Ng said...

Are you debugging with local IIS? (you'd have to be if debugging 64-bit MapGuide applications)

IIS is probably holding a lock on those DLLs from a previous debugging run. So you'd have to recycle its application pool everytime before debugging to free those locks. It's ugly but like I've said, things aren't perfect.

Wilson H said...

before anything, i really want to thank you for this great tool.

now, i am using local IIS, after recycling the application pool this worked, but as you said, it needs to be done each time.

this is a really minor inconvenience (at least for me) and will keep the testing if i see anything else.