Programming MapPoint in .NET

Chapter 1. Hello, MapPoint!

So, you want to develop location-based applications using .NET! Microsoft MapPoint technologies offer a wide variety of applications, services, and tools to enable you to develop powerful location-based applications using .NET technologies.

In this introductory chapter, I will go through different location-based application categories and architectures and explain which MapPoint product or technology is appropriate to use in certain scenarios; specifically, I will discuss the fundamental differences between the following three products and technologies from MapPoint:

• MapPoint 2004

• MapPoint Web Service

• MapPoint Location Server

Location-Based Application Categories

Fundamentally, location-based applications are applications that either know how to process location-based information or make use of their location for other processing. To that end, location-based applications can be categorized into two major categories: location-enabled applications and location-aware (or real-time) applications.

Location-Enabled Applications

Location-enabled applications understand location and know how to process it. For example, a conventional store locator is a location-enabled application—simply specify a location and provide a distance within which you want to find stores. Another example is a simple maps-and-directions application that can calculate driving directions using starting and ending addresses and display them on a map. These applications know how to interpret and process the location information.

Location-Aware Applications

Location-aware applications are similar to location-enabled applications except that they are aware of their own location, so they can use it for processing information. For example, a simple maps-and-directions application connected to a GPS device can provide you with up-to-date driving directions based on your current location, or it can even recalculate the driving directions if you leave your planned route! Another example is a store-locator application that knows where you are and automatically recommends nearby stores based on your current location. Location-aware applications are usually known as real-time location applications .

The intelligence of location awareness comes from the real-time location information obtained either by using an external hardware device, such as GPS, or by other means, such as mobile phone operator networks.

Location Application Architectures

Beyond the application categories, you need to be aware of application architectures when building location-based applications. Location-based applications can be built using two different architectures:

• Disconnected location-based applications

• Connected location-based applications

Let’s look at each of these categories in detail.

Disconnected Location-Based Applications

Disconnected location-based applications contain location information and related processing framework locally on the hosted computer hard disk, which means that network connectivity is not required for the application’s functionality. A typical disconnected location-based application architecture is shown in Figure 1-1.

The main advantage of this architecture is that the location data resides locally, so the applications can provide a faster and richer user experience; however, having data locally may also be viewed as a limitation for other reasons, such as the size of the application (since location data can easily grow to a few Gigabytes) and the data becoming out-of-date due to lack of frequent updates. The advantages include:

• Continuous availability of the application and data with no dependency on network connectivity

• Rich user interface

• Ideal architechture for thick client scenarios, where computing power and memory are available to handle complex processing on the client device

Figure 1-1. Disconnected location-based application architecture

However, there are also disadvantages:

• Larger application footprint

• Local location data that becomes out-of-date over time

• Different applications for different platforms (Windows versus Mobile)

• Not ideal architecture for thin client (such as web) scenarios

The decision to develop a disconnected location-based application should be based entirely on factors such as connectivity and functional richness of the application, which we will discuss in more detail later in this chapter.

Connected Location-Based Applications

Connected location-based applications contain location information and related processing framework on remotely located servers instead of the local hard disk, which means that a network connection is essential for the application to run. Typical connected-location based application architecture is shown in Figure 1-2.

The main advantage of this architecture is that the location data and the related processing framework reside remotely, so the applications can be lightweight. Since the applications are loosely coupled to the location data, it is easy to update the data frequently to keep it up-to-date. The advantages of this architecture include:

• Smaller application footprint

• Ideal architecture for thin client scenarios

• Easy architecture in which to keep data up-to-date

• Easy architecture in which to develop applications for different platforms (Windows and Mobile)

Figure 1-2. Connected location-based application architecture

However, there are still disadvantages:

• Architecture that requires continuous network connectivity

• Architecture in which you may be charged for each transaction in a commercial Web service scenario

Now that you have been introduced to location application categories and different architectures, let’s see how Microsoft MapPoint technologies enable you to build both connected and disconnected location-based applications.

Developing Location-Enabled Applications

Location-enabled applications know how to interpret and process location information. The kinds of applications that fall into this category include:

Generic maps and directions

Provide basic planning-related functionalities, such as displaying a desired location on a map and calculating driving directions from one point to another point. For example, both MapPoint 2004 and Streets & Trips 2004 provide this functionality right out of the box.

Location-based data visualization (or thematic mapping )

Helps you to visualize the data using geographic extent. For example, using MapPoint 2004, you can view information such as population statistics in any given city in the United States, or color-code the map based on population density.

Store Finders, ATM Finders, and similar applications

Find points of interest around a desired location. For example, you can find a nearby coffee shop when you are traveling in a new town or find local bloggers in the area in which you live.

To build this category of applications using MapPoint technologies, you have two choices: disconnected applications using MapPoint 2004, and connected applications using MapPoint Web Service.

Disconnected Applications Using MapPoint 2004

MapPoint 2004 is a powerful desktop mapping application that provides a rich set of APIs for both managed and unmanaged application development. MapPoint 2004 is well-suited for disconnected location-enabled application architecture, which means that the location-enabled application and required location data reside locally on the host computer’s hard disk, and no network connectivity is required for the application’s functionality.

Along with normal location-based APIs, such as Find, Route, and Render, MapPoint 2004 also offers a rich set of functions (also APIs) for thematic mapping, territory management, and spatial data import from a variety of source formats such as Excel, Access, Txt, and so on.

The APIs provided by MapPoint 2004 are COM- (Component Object Model) based APIs; however, thanks to .NET Framework runtime callable wrappers , you can program with the COM APIs using .NET’s managed code. MapPoint 2004 also provides an ActiveX control that enables MapPoint 2004 application integration into your applications so that you can reuse most of the MapPoint 2004’s application user interface.

Figure 1-3 shows how your applications stack on MapPoint 2004 architectural layers.

When you redistribute applications that you have developed using MapPoint 2004, make sure that the target machines have MapPoint 2004 installed as well. It is also possible to include MapPoint 2004 runtime and data along with your application if you become a MapPoint 2004 application reseller. Also, note that the MapPoint 2004 licensing model prevents you from developing web-based applications using the ActiveX control.

Figure 1-3. MapPoint 2004-based application stack

Tip

For further details on application redistribution using MapPoint 2004 information, go to http://msdn.microsoft.com/library/?url=/library/en-us/mappoint2004/BIZAPIAboutDistributingMapPointControl.asp?frame=true.

With this introduction, let’s look at a simple Windows application that uses MapPoint 2004 ActiveX control to display a map.

Hello, MapPoint 2004!

Using Visual Studio .NET , you can program with MapPoint ActiveX Control just like any other .NET Windows Forms Control.

Tip

If you do not have MapPoint ActiveX Control added to your Visual Studio .NET Toolbox, see Chapter 2 to learn about how to prepare your development environment to use MapPoint ActiveX control.

When you drag-and-drop the MapPoint ActiveX Control onto a Windows Form, Visual Studio .NET automatically adds a reference to your project and defines a private instance of the ActiveX control:

    private AxMapPoint.AxMappointControl axMappointControl1;

Using this ActiveX control instance, you can open up a map and place a pushpin at its center:

    //Create a new map
    axMappointControl1.NewMap(MapPoint.GeoMapRegion.geoMapNorthAmerica);
    //Get map center location
    MapPoint.Location location =  axMappointControl1.ActiveMap.Location;
    //Add a pushpin at this location
    MapPoint.Pushpin pushpin
          = axMappointControl1.ActiveMap.AddPushpin(location, "Center");
    //Assign a symbol
    pushpin.Symbol = 64;
    //Select and highlight the location
    pushpin.Select( );
    pushpin.Highlight = true;
    //Write annotation
    pushpin.Note = "This is the centroid of America!";
    //Show tooltip (Balloon State)
    pushpin.BalloonState = MapPoint.GeoBalloonState.geoDisplayBalloon;

When you place the above code in the Form.Load event handler and run the application, the Windows Form displays the map as shown in Figure 1-4.

Figure 1-4. Displaying a map with a pushpin using MapPoint ActiveX Control

Finally, MapPoint 2004 provides required location data locally; however, the data available with MapPoint 2004 contains only map data for the United States, Canada, and Mexico. To access map and location data for Europe, use MapPoint 2004 Europe Edition. At the time of this writing, MapPoint 2004 supports only North America, Western Europe, and some parts of Eastern Europe.

Connected Applications Using MapPoint Web Service

MapPoint Web Service is a Microsoft-hosted XML Web Service that is fully compliant with SOAP and WSDL standards. MapPoint Web Service makes it very easy for you to develop connected location-enabled applications. One of the advantages of using MapPoint Web Service is that the location data and the necessary processing framework are hosted by Microsoft on MapPoint servers, so your applications remain very thin and always have up-to-date location data. In addition, since MapPoint Web Service is a SOAP XML Web Service, it is possible to develop location-based applications that are both platform agnostic and programming language agnostic.

Along with normal location-based APIs, such as Find, Route, and Render, MapPoint Web Service also offers a full set of APIs for custom points of interest data upload and download to enable automated data management.

The APIs provided by MapPoint Web Service are SOAP-based APIs that can be accessed using any XML-enabled programming languages. Using the .NET framework makes it easy to develop applications with MapPoint Web Service; for example, using the following code, you can render a map with a pushpin similar to Figure 1-4:

    //Create an instance of the render service object
    RenderServiceSoap renderService = new RenderServiceSoap( );
    renderService.Credentials =
             new System.Net.NetworkCredential("myid", "mypassword");

    //Create an instance of MapSpecification
    MapSpecification mapSpec = new MapSpecification( );
    //Assign data source name
    mapSpec.DataSourceName = "MapPoint.NA";

    //Add pushpin
    //Create and add a pushpin
    Pushpin pin = new Pushpin( );
    //Assign data source
    pin.IconDataSource = "MapPoint.Icons";
    //Assign icon name
    pin.IconName = "1";
    //Assign label
    pin.Label = "This is the centroid of America!";
    //Assign location
    pin.LatLong = new LatLong( );
    pin.LatLong.Latitude = 38.79;
    pin.LatLong.Longitude = -98.79;
    //Add pushpin to map specificiation
    mapSpec.Pushpins = new Pushpin[] {pin};

    //Create options
    mapSpec.Options = new MapOptions( );

    //Assign options
    mapSpec.Options.Format = new ImageFormat( );
    mapSpec.Options.Format.Height = this.mapImage.Height;
    mapSpec.Options.Format.Width = this.mapImage.Width;

    //Assign view by height and width if it is the view
    ViewByHeightWidth vbh = new ViewByHeightWidth( );
    vbh.Height = 400;
    vbh.Width = 600;
    vbh.CenterPoint = pin.LatLong;

    //Zoom out to see the entire country
    mapSpec.Options.Zoom = 10;

    //Assign view
    mapSpec.Views = new MapView[] {vbh};

    //Get map
    MapImage[] mapImages = renderService.GetMap(mapSpec);

    this.mapImage.Image = new Bitmap(new System.IO.MemoryStream(mapImages[0].MimeData.Bits));

If you don’t understand anything about these steps, don’t worry—we will look at Map Rendering in detail in Chapter 8. When the code is run, the map is displayed as shown in Figure 1-5.

It looks like a lot more code than MapPoint ActiveX Control, but it is very simple once you understand the MapPoint Web Service object model. Also, it is important to note that the above code returns the binary form of the map image, which displays the map in a .NET Windows Forms Picture Box control; when you use a Web Form application using ASP.NET, you can request the map in a URL format, which can be used in an HTML IMG tag.

Figure 1-6 shows how your applications build on top of MapPoint Web Service architectural layers.

Location data in MapPoint Web Service is hosted on Microsoft MapPoint servers, and all of the map and location data is available for developers via the programmable APIs. This provides greater flexibility in building global location-based applications that work for multiple countries and regions.

Location data in the MapPoint Web Service environment is represented in terms of data sources; each dataset represents data for a particular country or region; for example, North American region map and location data is contained in the MapPoint.NA data source. So, if you develop a store finder application using MapPoint Web Service using the MapPoint.NA data source, and you want to reuse the application code for Europe, change the data source name from MapPoint.NA to MapPoint.EU (compare the procedure used here to one using MapPoint 2004). Location-based applications can be configured to use just about any map data, since MapPoint Web Service provides the loose coupling between your application layer and the data layer.

Figure 1-5. Displaying a map using MapPoint Web Service

Figure 1-6. MapPoint Web Service-based application stack

MapPoint Web Service currently supports map and location data for countries and regions in North America, Europe, and Pacific Asia.

Developing Location-Aware Applications

Location-aware applications (or real-time location applications ) apply your current location when processing information to provide smart choices. The kinds of applications that fall into this category are:

• Real-time navigation software

• Fleet tracking applications

• Friend and family finder applications

To build this category of applications using MapPoint technologies, you have two choices (yes, again!): disconnected and connected applications .

Disconnected Applications Using MapPoint 2004 and GPS

MapPoint 2004 provides necessary APIs and location data to build location-enabled applications; however, you can also build disconnected location-aware applications using MapPoint 2004 by interfacing a location-aware hardware such as Global Positioning Satellite (or simply GPS) devices. Even though MapPoint 2004 does not provide ready-to-use APIs for GPS interfacing, it is relatively easy to use real-time information from a GPS device in the MapPoint application environment.

Figure 1-7 shows how your location-aware applications build on MapPoint 2004 and a GPS device.

This architectural layer is not very different from Figure 1-3, except that this application uses a GPS device for real-time information.

Tip

For further details on how to interface MapPoint 2004 with a GPS device, see Chapter 4.

The most common scenarios for this architecture include real-time navigation applications, real-time location based information logging applications.

Figure 1-7. Location-aware application using MapPoint 2004 with a GPS device

Connected Applications Using MapPoint Location Server

MapPoint Location Server is an enterprise-hosted server that enables real-time location scenarios using a locatable device, such as a mobile phone or a pager. MapPoint Location Server does not require any location-related hardware, such as GPS devices; instead, it locates a provisioned (registered) user’s mobile device by communicating with a mobile operator. In a typical scenario, a user requests his position using a mobile device equipped with a client that communicates with MapPoint Location Server. When MapPoint Location Server receives the request from the client, it identifies the mobile operator for the user and sends a location request to the mobile operator, which responds by sending back the real-time location of the user, expressed as latitude and longitude coordinates. MapPoint Location Server then requests a map or other location information from MapPoint Web Service to process the user’s real-time location.

All communications specific to a mobile operator are hidden from end users and developers. Thus, MapPoint Location Server works as an aggregator for mobile operators by abstracting implementation details that are specific to the mobile operator to obtain a real-time location. Once the location is obtained, it can be used for many purposes, such as finding nearby ATMs, calculating driving directions based on current location, and so on.

Figure 1-8 shows the overall architecture for a location-aware application using MapPoint Location Server.

MapPoint Location Server exposes a SOAP XML-based web service that provides methods to obtain real-time location using a mobile phone number or a pager number. This functionality was intentionally exposed as a web service, since it can be consumed by any client on any platform with minimal effort; it is very easy to develop connected location-aware applications for Windows or mobile platforms. Also, while MapPoint Location Server obtains real-time location using mobile devices and mobile operator networks, it uses MapPoint Web Service to obtain other location-based information.

Figure 1-8. Application architecture using MapPoint Location Server

How It All Fits Together

By now, you might be confused about which product to use for each type of application. To clarify your choices, Figure 1-9 summarizes your options.

Figure 1-9. MapPoint Platform development choices

Where Are We?

Microsoft MapPoint technologies provide a wide variety of applications, services, and tools to develop location-enabled applications and location-aware applications for both connected and disconnected scenarios. To recap:

• To develop disconnected location-enabled applications , use MapPoint 2004.

• To develop connected location-enabled applications, use MapPoint Web Service.

• To develop disconnected location-aware applications , use MapPoint 2004 with GPS.

• To develop connected location-aware applications , use MapPoint Location Server .

If you are wondering how to digest so much information about all these products in one introductory chapter, don’t worry; I will discuss MapPoint 2004, MapPoint Web Service, and MapPoint Location Server in detail in the upcoming chapters.

Let’s get started!