ARTICLES

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.

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

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.

	MP2Kmag Internet