MapGuide tidbits: MgInitializeWebTier

This is the first of a series of posts that focuses on various aspects of MapGuide and its related technologies. There may have been various posts in the past with a similar focus, but now we'll be using an official umbrella title for such posts.

So the topic of this post is the function you've probably seen many times: MgInitializeWebTier

In any MapGuide code examples, you'll probably see this function called first before anything else in the MapGuide API is used, so what does it do?

There are various classes in the MapGuide API that need to be set up with a whole bunch of configuration values defined in webconfig.ini. This function sets up all these configuration values in one shot so all the classes in the MapGuide API have access to your configured values in webconfig.ini. This is why you generally call this function first before using any classes from the MapGuide API.

What happens if you call this function multiple times? Nothing. Subsequent calls will return immediately.

At what scope does MgInitializeWebTier apply to? The configuration values apply at the process level, this means:

• Your whole application (if you're building a console/windows MapGuide application)
• Your application pool (if you're building a asp.net MapGuide application in IIS)
• Your php-cgi.exe process (if you're building a PHP MapGuide application is IIS)
• Your Apache httpd process (if you're building a PHP MapGuide application served by Apache)
• Your tomcat process (if you're building a Java MapGuide application)

Meaning if you change some values in webconfig.ini, you generally have to do the following for the new values to take effect:

• Restart the application (if you're building a console/windows MapGuide application)
• Recycle the IIS application pool (if you're building a asp.net MapGuide application in IIS)
• Kill the php-cgi.exe process (if you're building a PHP MapGuide application is IIS). IIS will spawn a new php-cgi process the next time a PHP script is run.
• Restart Apache (if you're building a PHP MapGuide application served by Apache)
• Restart tomcat (if you're building a Java MapGuide application)

Are there cases where we can get away with not calling this function? Yes. If you are writing code that only operates against the Foundation, Geometry and PlatformBase libraries, then there is no actual MgInitializeWebTier to call into. Such initialization concerns are generally handled by the PlatformBase-derived library (MapGuideApi.MgInitializeWebTier for MapGuide, MgdPlatform.Initialize for mg-desktop).

If you are building an application that uses the MgCoordinateSystem series of APIs (from MgGeometry), then there is some small initialization you need to take care of. These classes need to know where the coordinate system dictionaries are located. Generally this is defined by the MENTOR_DICTIONARY_PATH environment variable. So if you are building such an application (and you don't have access to the MgInitializeWebTier function), you need to set this environment variable to your coordinate system dictionary path first before you can use any MgCoordinateSystem API.

So what's the minimum thing can you take out of all of this? For cleanliness, you only need to call MgInitializeWebTier once when the application starts up. Classic ASP.net provides an Application_Start entry point in Global.asax that is an ideal spot to insert such a function call. For other web frameworks, you need to consider whether:

• Such a similar process-wide entry point is provided by said framework
• The process life-cycle of said framework

When in doubt, you can just call MgInitializeWebTier first before using any class from the MapGuide API.

Hopefully this post sheds some light on when and why you need to call this function.