Programming with MapPoint 2004 using the .NET Framework
This article by Chandu Thota discusses how to program with the MapPoint 2004 object model using the Microsoft® .NET Framework
Microsoft Corporation
January 2004
Applies to: MapPoint 2004
Requirements: MapPoint 2004, Microsoft .NET Framework and Visual
Studio .NET 2003.
Experience: Targeted at
an experienced .NET developer.
Contents:
- Introduction
- Programming MapPoint 2004 - Step by Step Approach
- Coding for Special Conditions
- Conclusion
Introduction
MapPoint 2004 provides a rich object
model to build powerful business intelligence and location based applications.
However, the MapPoint 2004 object model was originally designed for COM based
programming and if you are currently programming using the .NET Framework, you
need build MapPoint 2004 applications using the interoperable assemblies
generated from the COM type libraries. This article outlines the step by step
approach to build MapPoint 2004 applications, by developing an Address Finder
application, using the .NET Framework. This article also discusses a couple of
tricky conditions and resolutions that you may face while developing with
MapPoint 2004 using the .NET Framework.
Programming MapPoint 2004: Step by Step Approach
In this section I'm going to outline a step-by-step approach
to build MapPoint 2004 applications by developing an example application that
finds addresses.
As I have discussed in the previous section, the MapPoint 2004 object
model is originally designed for COM programming model. In order to build applications
using the Microsoft .NET Framework you need the interoperable assemblies for the MapPoint
COM library. If you are using Visual Studio .NET, you can do so using the Add
Reference option from the project context menu, after creating a new project, as shown
below:

When you see the Add Reference dialog window,
select the COM tab and select the Microsoft MapPoint 11.0 Object Library ( )
to add the MapPoint 2004 type library as a reference to your project, as shown in the
following picture:

Now, let's start writing some C# code by
importing the MapPoint 2004 namespace:
//Add MapPoint namespace
using MapPoint;
Adding this namespace makes your code look cleaner when using
MapPoint types. However, if you are developing a Windows application it is
important to note that this namespace defines an Application interface that whose
name conflicts with the Application class defined in the System.Windows.Forms
namespace. To resolve this conflict you have to fully qualify either one of these
two classes with their namespaces. The next step is to create
an instance of the MapPoint 2004 application object:
//Define an application instance
ApplicationClass app = null;
//Create an application class instance app = new ApplicationClass();
The MapPoint 2004 application instance always exposes an active
map instance which can be used to perform any location oriented tasks. In this
example I'm going to use the active map instance to find an address.
//Now get the location
FindResults frs = app.ActiveMap.FindAddressResults(" ",
" ", string.Empty,
"WA", "", null);
As you may have noticed already, the FindAddressResults method
returns the FindResults which is a collection of locations found. There are two
ways to access the list of locations from the FindResults instance:
1. Obtain an
enumerator and enumerate through the location list. This method is useful if
you want to provide a list of all matching addresses; for example, providing
a list of addresses in case of an ambiguity.
//Get an enumerator
IEnumerator ienum = frs.GetEnumerator();
//Loop through the enumerator
while(ienum.MoveNext())
{
Location loc = ienum.Current as Location;
if(loc != null)
{
//process the location
string s = loc.StreetAddress.Value;
} }
2. Use the get/set accessor
methods to get the locations using indexes. This method is useful when
you want to retrieve a specific item without iterating through the
collection; for example, always retrieve the first match from the collection.
//Define an index
object index = 1;
//Access the location item using the accessor method
location = frs.get_Item(ref index) as Location;
As you might have observed from the above code, the
FindResults collection does not support accessing collection items via
the indexers; hence you have to use the get_Item and set_Item methods.
Finally, when you are done with finding the address, you have to close the application object to make sure that the MapPoint 2004 application instance doesn’t live in the memory; you can do so by writing the following code: //Quit the application if(app != null) app.Quit(); app = null; The following code listing shows the find address function that has been discussed in this section so far: //Define an application instance ApplicationClass app = null; //Define a location instance Location location = null; //Define a FindResults instance FindResults frs = null; try { //Create an application class app = new ApplicationClass(); //Now get the location frs = app.ActiveMap.FindAddressResults(" ", " ", string.Empty, "WA", "", null); //Check if the find query is succesfull if(frs != null && frs.Count > 0) { object index = 1;
location = frs.get_Item(ref index) as Location; //Male the MapPoint 2004 application visible //and go to that location app.Visible = true; location.GoTo(); //Do your processing with the location MessageBox.Show(location.StreetAddress.Value); } } catch(Exception ex) { string message = ex.Message; } finally { if(app != null) { try { app.Quit(); } catch { //This means your app has already quit! } finally { app = null;
}
}
}
In this section, you have seen
how to build a simple address finding application using MapPoint 2004
and the Microsoft .NET Framework. In the next section I'm going to
discuss a couple special conditions that you face very frequently while
programming with MapPoint 2004.
Coding for Special Conditions
This section discusses the two most frequent special
conditions that you face while programming with MapPoint 2004.
Working with methods with optional parameters
When you use a method with optional parameters and you
do not have valid parameters to pass, you must use the type
System.Reflection.Missing.Value. For example the DisplayDataMap method
on a MapPoint DataSet class has the following method signature:
DisplayDataMap([DataMapType], [DataField], [ShowDataBy], [CombineDataBy], [DataRangeType], [DataRangeOrder], [ColorScheme], [DataRangeCount], [ArrayOfCustomValues], [ArrayOfCustomNames], [DivideByField], [ArrayOfDataFieldLabels], [ArrayOfPushpinSymbols])
As you can see all of the parameters are optional
parameters. Working with methods like this necessitates the usage
of the missing type defined in the .NET Framework. The following
example shows how to use the missing value for optional parameters:
//Define a missing value type
object missing = System.Reflection.Missing.Value;
//Use the missing type for optional parameters that are not needed DataMap mydatamap = mydataset.DisplayDataMap(GeoDataMapType.geoDataMapTypeShadedArea,
field, GeoShowDataBy.geoShowByRegion1,
GeoCombineDataBy.geoCombineByDefault,
GeoDataRangeType.geoRangeTypeDiscreteLogRanges,
GeoDataRangeOrder.geoRangeOrderDefault, 15, 3,
missing, missing, missing, missing, missing);
Working with Collections
As you may remember from the previous section, it is a
little tricky to work with collections since the collections in COM
interoperable assemblies don’t support indexers. There are two ways
to retrieve collection items:
1. Using an enumerator and
2. Using the get/set accessor methods
Each of these methods has its own merits. By using the
enumerator, you can get the entire list of collection items, however,
there are some cases where you need to access a specific item in a given collection and you have to use the get/set accessor methods. For example if you have to retrieve the population demographic data for the year 2002 from MapPoint 2004, you have to do the following: //Create an application class app = new ApplicationClass(); //Get demographics dataset from the activemap mydataset = app.ActiveMap.DataSets.GetDemographics(GeoCountry.geoCountryUnitedStates); //Create a key - you need this as an index key for the fields object key = "Population (2002)"; //Now get the field using the key defined above collection Field field = mydataset.Fields.get_Item(ref key); Conclusion In this article you have seen how to build applications using MapPoint 2004 using the .NET Framework. You have also learned how to handle special conditions such as methods with optional parameters and
collections. The code and the special condition considerations also work with
MapPoint 2002 when an appropriate reference is added.
References
·
For more samples and code snippets related to MapPoint 2004 on my
web log: http://www.csthota.com/mappoint/
· MapPoint 2004 o
bject model help on MSDN:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mappoint2004/BIZAboutProgramming.asp?frame=true
Discuss this story in the forum.
Author: Chandu Thota Email: cthota(AT)microsoft.com URL: http://www.esynaps.com Chandu Thota works for Microsoft Corporation in the MapPoint User Experience team. Having been a developer for more than 5 years, he wakes up everyday with a goal to make things as simple and efficient as possible for developers to build applications on the MapPoint platform.
Chandu has published several articles related to the Microsoft .NET Framework and founded an online .NET Web Services portal, http://www.esynaps.com. He is also a co-author of the books Understanding the .NET Framework and Building an ASP.NET Intranet, both published by Apress.
|