After adding a web reference using Visual Studio .NET, you can choose whether to make the service URL dynamic, meaning that the proxy classes are generated such that the service URLs can be configured and managed via the config file (web.config for web applications and app.config for Windows applications). The default option is a static service URL. Figure 5-6 shows the web reference property to change the URL’s behavior.

If you look at the FindServiceSoap constructor with the dynamic service URL option, the class constructor looks as follows:

    public FindServiceSoap()
    {
        string urlSetting =
         System.Configuration.ConfigurationSettings.AppSettings["myapp.CommonService"];
        if ((urlSetting != null))
        {

Figure 5-6. URL behavior setting

          this.Url = string.Concat(urlSetting, "FindService.asmx");
        }
        else
       {
        this.Url = "http://findv3.staging.mappoint.net/Find-30/FindService.asmx";
       }
    }

The constructor first tries to obtain the service URL from the configuration file, and when it can’t find it in the configuration file, it reassigns the static service URL. It is important to note that only the non-asmx part of the service URL is made configurable, while the asmx (for example, FindService.asmx) filename is still hardcoded. To support this dynamic URL behavior, add the following application key in the configuration file to access staging MapPoint Web Service:

    <appSettings>
      <add key="myapp.CommonService"
        value="http://findv3.staging.mappoint.net/Find-30/"/>
      </appSettings>
    </configuration>

Along similar lines, add the following value to access the production MapPoint Web Service:

    <appSettings>
      <add key="myapp.CommonService"
        value="http://findv3.service.mappoint.net/Find-30/"/>
      </appSettings>
    </configuration>

To enable dynamic service URL behavior, in an ideal world, you would select the Dynamic option for the URL Behavior property from Visual Studio .NET, and you would be all set—except that you aren’t. The dynamic URL feature in Visual Studio .NET does not work for MapPoint Web Service. In Visual Studio .NET, the static/dynamic service URL feature was designed for web services with one service endpoint per WSDL document, which means there is only class that implements SoapHttpClientProtocol type per Reference.cs or Reference.vb file. Even if there is more than one service endpoint, the assumption was that the base URL of the service is always the same; however, for MapPoint Web Service, one WSDL actually points to four services that have three physical service endpoints . So, in order to make your MapPoint Web Service proxy class properly enabled with dynamic URL behavior, you need to do the following steps:

First, add the following key to your configuration file:

    <appSettings>
      <add key="myapp.CommonService"
        value="http://findv3.staging.mappoint.net/Find-30/Common.asmx"/>
      <add key="myapp.FindService"
        value="http://findv3.staging.mappoint.net/Find-30/Find.asmx"/>
      <add key="myapp.RouteService"
        value="http://routev3.staging.mappoint.net/Route-30/Route.asmx"/>
      <add key="myapp.RenderService"
        value="http://renderv3.staging.mappoint.net/Render-30/Render.asmx"/>
    </appSettings>

Next, modify the service soap class constructors as shown below:

CommonServiceSoap class:

    public CommonServiceSoap() {
      string urlSetting =
        System.Configuration.ConfigurationSettings.AppSettings["myapp.CommonService"];
      if ((urlSetting != null)) {
         this.Url = urlSetting;
      }
      else {
          this.Url = "http://findv3.staging.mappoint.net/Find-30/CommonService.asmx";
      }
    }

FindServiceSoap class:

    public FindServiceSoap() {
      string urlSetting =
        System.Configuration.ConfigurationSettings.AppSettings["myapp.FindService"];
      if ((urlSetting != null)) {
        this.Url = urlSetting;
      }
      else {
          this.Url = "http://findv3.staging.mappoint.net/Find-30/FindService.asmx";
      }
    }

RouteServiceSoap class:

    public RouteServiceSoap() {
      string urlSetting =
       System.Configuration.ConfigurationSettings.AppSettings["myapp.RouteService"];
      if ((urlSetting != null)) {
        this.Url = urlSetting;
      }
      else {
          this.Url = "http://routev3.staging.mappoint.net/route-30/RouteService.asmx";
      }
    }

RenderServiceSoap class:

    public RenderServiceSoap() {
      string urlSetting =
       System.Configuration.ConfigurationSettings.AppSettings["myapp.RenderService"];
      if ((urlSetting != null)) {
        this.Url = urlSetting;
      }
      else {
          this.Url =
           "http://renderv3.staging.mappoint.net/render-30/RenderService.asmx";
      }
    }

With this code in place, your application uses the service URL specified in the configuration file; when no configuration setting is found, staging service URLs are used instead.

Before we move to the next section, it is important to note that the modifications that you make to the Reference.cs or Reference.vb file are not persisted when you refresh the web reference. Be careful when you refresh the MapPoint Web Service web reference.

You need to secure MapPoint Web Service credentials through proper application configuration. MapPoint Web Service is a subscription-based web service, and each of your MapPoint Web Service requests must be authenticated to obtain a valid

response; for this purpose, MapPoint Web Service uses digest authentication. When you make a web service method call, you must assign your credentials to the service class.

For example, if you are invoking the Find method on the FindServiceSoap class, you need to assign your MapPoint Web Service credentials before calling the method:

    //Create service class instance
    FindServiceSoap findservice = new FindServiceSoap();
    //Assign credentials - Do not do this!
    findservice.Credentials =
       new System.Net.NetworkCredential("yourid", "yourpassword");
    //Invoke the method
    findservice.find(...);

In this code, the credentials are assigned using the System.Net.NetworkCredential object by hardcoding the user ID and password. There is a maintenance risk associated with this approach; for security reasons, you are required to change your MapPoint Web Service account password once every 45 to 60 days. When the time comes to change your password, you need to update the password and re-compile. In order to avoid these maintenance headaches, make the user ID and password configurable from a configuration file (app.config or web.config). Storing the user ID and password in clear text in the configuration file may pose a security threat, so you need to store the credentials in the configuration file in encrypted form.

There are multiple ways of encrypting your MapPoint Web Service ID and password. In any case, you must develop an encryption library using either the Data Protection APIs or Encryption APIs . The simplest way, of course, is to use the Windows Data Protection APIs (DPAPI ). The DPAPI support two kinds of entropies : machine store entropy and user store entropy . In both cases, you can also provide private entropy , which adds an additional layer of security.

Since the Data Protection APIs are Win32 APIs, you need to build C# wrappers around them. A sample implementation of the DPAPI is included in the companion material (project Chapter05); the DataProtectionCore sample class can be used for encrypting and decrypting the MapPoint Web Service ID and password. The following code shows how to encrypt any given string using the DataProtectionCore sample class:

    public static string Encrypt(string input)
    {
      Chapter05.EncryptionUtil.DataProtectorCore dp
      = new Chapter05.EncryptionUtil.DataProtectorCore(
          Chapter05.EncryptionUtil.Store.USE_MACHINE_STORE);
       byte[] encryptedBuffer =
           dp.Encrypt(System.Text.ASCIIEncoding.ASCII.GetBytes(input),
                        null);
       return Convert.ToBase64String(encryptedBuffer);
    }

Once the user ID and password are encrypted as shown in the previous code, you can store them in the configuration file as follows:

    <configuration>
      <appSettings>
        <add key="MapPointWebServiceID"
              value="CAAAAAAADZgAAqAAAQ....tYt9br2PpFHM0AXJd/tIJ/bbb74="/>
        <add key="MapPointWebServicePassword"
              value="AQAAANCMnd8BFdE ....HTPITIgU6FQcAXJd/tIJXteE8/wQ=="/>
      </appSettings>
    </configuration>

Now your MapPoint Web Service ID and password are secure in the configuration file; however, your MapPoint Web Service application cannot readily use the encrypted MapPoint Web Service ID and password from the configuration file. You need to write a decrypt routine:

    public static string Decrypt(string input)
    {
       Chapter05.EncryptionUtil.DataProtectorCore dp
       = new Chapter05.EncryptionUtil.DataProtectorCore(
          Chapter05.EncryptionUtil.Store.USE_MACHINE_STORE);
       byte[] decryptedBuffer = dp.Decrypt(Convert.FromBase64String(input)
                         , null);
       return System.Text.Encoding.ASCII.GetString(decryptedBuffer);
    }

In this routine, the input string is decrypted back to the original ASCII text. Once you have this decrypt routine, you can always read the encrypted MapPoint Web Service ID and password, decrypt them, and pass them to the MapPoint Web Service:

    //Create a find service instance
    FindServiceSoap find = new FindServiceSoap();
    //Assign credentials
    find.Credentials = new System.Net.NetworkCredential(
    Decrypt(ConfigurationSettings.AppSettings["MapPointWebServiceID"]),
    Decrypt(ConfigurationSettings.AppSettings["MapPointWebServicePassword"]));
    . . .
    //Find places
    FindResults results = find.Find(spec);

The Encrypt and Decrypt methods are available in the companion material in the Chapter05 class.

Finally, for performance reasons, always assign the PreAuthenticate property on the service SOAP class to True so that your application can avoid any extraneous round-trips to the server just for authentication. For example, on FindServiceSoap service class, set the value as shown:

    findservice.PreAuthenticate = true;

Now that you know how to prepare your development environment for MapPoint Web Service application development, let’s get into the MapPoint Web Service object model before we start programming.

MapPoint Web Service makes more than 45 data sources available for you to program with. These 45 data sources can be broadly categorized into three types of data sources:

Let’s look at each data source type in detail.

Map data sources Map data sources contain the geographic data used to perform location-oriented tasks, such as finding places and addresses, calculating routes, and rendering maps. All these data sources support entities, which represent the physical existing “things” in the real world, such as airports, coffee shops, libraries, roads and so forth. Table 5-2 shows the Map Data Sources available in MapPoint Web Service.

Point of interest data sources MapPoint Web Service provides more than 35 point of interest data sources containing information about millions of businesses and organizations in several countries and regions in Europe and North America. The data contained in these data sources is organized by Standard Industry Code (SIC) and includes properties such as location and contact information. You can use these data sources to find businesses either by searching attributes (such as store names, cities, etc.) or by performing a proximity search around a given latitude and longitude (such as a store-locator).

Almost all point of interest data are provided by external data vendors (such as NavTeq or Acxiom) to Microsoft, so these data sources are named after their vendor’s name. For example, if you want to use the point of interest data in the North American region provided by NavTeq, use the NavTeq.NA data source.

Along with the vendor-supplied point of interest data sources, MapPoint Web Service also provides one sample point of interest database for a fictitious company called Fourth Coffee Company. The data source for this company, MapPoint.FourthCoffeeSample, contains fictitious coffee shops across North America and Europe. This data source can be used as an example of how your business data can be uploaded as point of interest data to the MapPoint Web Service servers.

Icon data sources MapPoint Web Service provides one icon data source, MapPoint.Icons, which contains over 900 icon images that you can use with the Pushpin object when rendering a map. Each icon image in the icon data source is indexed with either text or numbers that can be used in your application to indicate to use of a pushpin. Identify the icon data source for the pushpin image, and then render that pushpin using one of the map data sources.

Now that you know what MapPoint data sources are, let’s look at customer data sources in detail.

Customer data sources are created and maintained by customers that use MapPoint Web Service; however, the actual data is hosted on MapPoint Web Service servers. For example, if your company wants to show your office locations on MapPoint Web Service-rendered maps, you need to upload your office location data to MapPoint Web Service servers. The uploaded data is geo-coded and stored in a data source specifically associated with your MapPoint Web Service account. This data source is only accessible by you, and no other MapPoint Web Service customer can read or write to this data source.

You will be automatically assigned a custom data source with a pre-assigned name when you sign up for the MapPoint Web Service, but you can also create your own data sources apart from the pre-assigned one. For example, if your company name that is registered with MapPoint Web Service account is CompanyXyz, and your MapPoint Web Service ID is 6909, your default data source name will be CompanyXyz.6909, and any new data sources that you create will contain this name as their first part. If you want to create a new data source to store only your office locations with the name Office, the data source name will be CompanyXyz.6909.Office.

You can create new data sources either manually by using the Customer Services web site (https://mappoint-css.partners.extranet.microsoft.com/cscv3/) or programmatically by using the Customer Data Service API (see Chapter 8 for more details).

MapPoint Web Service currently supports only point of interest data and icon data for customer data sources , which means that you can only upload points of interests and your own icons to use in your MapPoint Web Service applications.

With so many data sources available in MapPoint Web Service, if you are wondering how to remember which data source performs each location-oriented task, you can find out the capabilities of any data source programmatically in MapPoint Web Service.

Each data source in the MapPoint Web Service environment supports certain location-oriented and non-oriented tasks. The data source capabilities define which data source supports each task.

The data source capabilities are the metadata defined for each data source, which you can use to find out which tasks that data source can support. For example, to find out what all the tasks that can be performed by the data source MapPoint.NA are, query the capabilities metadata using the CommonServiceSoap API. The data source capabilities are programmatically represented as the DataSourceCapability flagged-enumeration whose values are shown in Table 5-3.

Data source capabilities can be grouped by their basic functionality, such as find, render, and route, which we will look at in detail in the next couple of chapters; also remember that one single data source can support more than one of these capabilities. For example, the MapPoint.NA data source supports CanDrawMaps, CanFindAddress, CanFindPlace, and CanRoute.

Finally, before we wrap up our discussion on data sources, you need to be familiar with which languages these data sources support .

Although MapPoint Web Service currently supports 10 languages, not every data source currently supports all 10 languages. The core geographic coverage data sources, MapPoint.NA, MapPoint.EU, MapPoint.BR, and MapPoint.AP, support the nine languages shown in Table 5-4.

The data sources MapPoint.Moon and MapPoint.World support all of these languages as well as Japanese (language code ja and LCID 1041).

It is also important to note that the MapPoint.Icons data source and all MapPoint point of interest data sources are available only in United States English.

Language preference in MapPoint Web Service is exposed via the CultureInfo object using the UserInfoHeader class, which you can use to set a desired culture Name or Lcid value from the previous table. The following code shows how to request a culture specific setting during a FindService call:

    //Create a Find Service proxy class instance
    FindServiceSoap find = new FindServiceSoap();
    //Assign Credentials

    . . .
    //Set culture specific settings
    //Create the user info header instance
    find.UserInfoFindHeaderValue = new UserInfoFindHeader();
    //Initialize culture value and set italian
    find.UserInfoFindHeaderValue.Culture = new CultureInfo();
    find.UserInfoFindHeaderValue.Culture.Name = "it";
    //Assign data source name and invoke find method
    . . .

When you set a specific culture for the Find Service, the find results returned by the service are expressed in the culture requested. For example, if you try finding Redmond, WA with “en-US” as your culture information, you get Redmond, Washington, United States as the display name of the found entity, but the same find request returns the “Redmond, Washington, Stati Uniti d’America” when you set the culture info as “it” to get return results in Italian culture format.