The Art of IntelliSense: Three ways to use IntelliSense with Bing Maps APIs

Do you find that you spend more time digging through documentation trying to figure out what properties do rather than spending time building great apps? IntelliSense can help.

A few weeks ago, someone asked me if there was any IntelliSense support for Bing Maps. I vaguely remembered there being an open source project that added IntelliSense for Bing Maps AJAX v6.3 in Visual Studio. With a quick search on Bing I found the project on CodePlex and the original blog post about it. I noticed that one of our Bing Maps MVPs, Nicolas Boonaert, had started to put together IntelliSense functionality for Bing Maps AJAX V7 a few years ago. Since then a lot of new features and functionalities have been added to V7, so I reached out to Nicolas, and in our spare time over the last couple of weeks we added IntelliSense for the rest of the API.

IntelliSense provides us with three really useful functionalities:

1. When you type a period or opening bracket after a known class name or value, like “Microsoft,” a dropdown list of possible properties appears. This saves you from having to remember every single possible property and function name in the API.
2. It provides a description about what a property or function does.
3. It provides information for different signatures that a function might use. This is useful when some functions have optional parameters. Below is an example that shows the IntelliSense when using the MapTypeId enumerator:

Screenshot: IntelliSense when using the MapTypeId enumerator

Below is an example showing one signature of the Polygon class:

Example: One signature of the Polygon class

How to implement

Now that we’ve covered how wonderfully useful this IntelliSense library is, it’s time to show you how to use it in your project. There are three different methods that can be used.

Method 1 – Download Library from CodePlex:

1. Download the zipped up Bing Maps V7 IntelliSense project from CodePlex here.
2. Unzip the file and copy the Microsoft.Maps-vsdoc.js file from the BMJS folder to your project.
3. At the top of all the JavaScript files that use Bing Maps, add a reference to the Microsoft.Maps-vsdoc.js file. Be sure to include the correct path to where this file is located in your project.

   /// 

    

4. Start using IntelliSense in your project.

Method 2 – NuGet Package using the NuGet Package Manager:

With this method you can install the IntelliSense as a NuGet package using the NuGet Package Manager User Interface.

1. In Visual Studios open the Tools menu, select NuGet Package Manager and then click Manage NuGet Packages for Solution.

   Screenshot: NuGet Package Manager

2. In the left side panel of the NuGet package manager select Online → nuget.org, then in the search bar enter “Bing Maps IntelliSense”. In the results locate the Bing Maps JavaScript IntelliSense Helper v7.0 package, select it and press the Install button.

   Screenshot: Install Bing Maps JavaScript IntelliSense Helper v7.0 package

3. In the window that appears select the projects in your solution that you want to install this package in and press the OK button. You will find the Microsoft.Maps-vsdoc.js file in the Scripts/BMJS folder.

   Screenshot: Scripts/BMJS folder

4. At the top of all the JavaScript files that use Bing Maps, add a reference the Microsoft.Maps-vsdoc.js file. Be sure to include the correct path to where this file is located in your project.

   /// "/Scripts/BMJS/Microsoft.Maps-vsdoc.js"/>

    

5. Start using IntelliSense in your project.

Method 3 – NuGet Package using the Package Manager Console

With this method you can install the IntelliSense as a NuGet package using the NuGet Package Manager Console.

1. In Visual Studios open the Tools menu, select NuGet Package Manager and then click Package Manager Console.

   Screenshot: NuGet Package Manager

2. In the console window enter Install-Package BingMapsIntelliSense_7 and press enter.

   Screenshot: Package Manager Console

3. In the window that appears select the projects in your solution you want to install this package in and press the OK button. You will find the Microsoft.Maps-vsdoc.js file in the Scripts/BMJS folder.

   Screenshot: Scripts/BMJS folder

4. At the top of all the JavaScript files that use Bing Maps add a reference the Microsoft.Maps-vsdoc.js file. Be sure to include the correct path to where this file is located in your project.

   /// "/Scripts/BMJS/Microsoft.Maps-vsdoc.js"/>

    

5. Start using IntelliSense in your project.

Important Note: Do not add the Microsoft.Maps-vsdoc.js file as a script reference in your HTML file. If you do, it’s possible that it will overwrite the Bing Maps namespace when the page loads and would likely throw an error and/or not load the map correctly.

Implemented workarounds

The Bing Maps AJAX V7 and Bing Maps for Windows Store apps APIs makes use of anonymous objects for setting options and event handler arguments. These cannot be easily documented using IntelliSense. The following describes some workarounds that have been implemented to provide some insight into these objects using IntelliSense.

Anonymous objects

These have been handled in a couple of different ways in this IntelliSense library. Every method/constructor that takes in an anonymous object has multiple signatures. The first one will list all the properties of the object and their types, the second signature will attempt to list one property, its type and description per line. This works well when the object doesn’t have a lot of properties, however when it does then it may get cut off. The third signature is a reference to a class that is a placeholder and exists under the AnonymousObject namespace. This is useful for when the object is returned from a method as IntelliSense will work on the returned object. For example, try something like this:

/// 

map = new Microsoft.Maps.Map(document.getElementById("mapElement"), {
    credentials: 'YOUR_BING_MAPS_KEY'
});var mapOptions = map.getOptions();
mapOptions.disablePanning = true;
map.setOptions(mapOptions);

You will notice that IntelliSense appears for the disablePanning property since the IntelliSense knows what the object that is returned by the getOptions function looks like.

Event callback parameters

Both the event related methods addHandler or addTrottledHandler take in the following parameters: an object to add the event to, the name of an event to attach to, and a callback function for when the event is fired. For any class that has events, all the supported events are listed in its description. There is also an AnonymousObject called EventCallback, which has a list of all the different events and their target object.

Below is an example of how to find out what type of object will be passed to the event callback function:

Example: How to find out what type of object will be passed to the event callback function

From this IntelliSense we see that when using the click event, the event callback will receive a MouseEventArgs object, which is again an AnonymousObject that we can use to assist us when creating the callback function.

Below is an example of how to get a reference to the object that fired the event in the callback function:

Example: How to get a reference to the object that fired the event in the callback function

Note that the AnonymousObject is only meant for providing information via IntelliSense and does not exist in the API. Once you have created your event callback function, remove all references to the AnonymousObject class. In the case of the examples used thus far, we would end up with code that looks like this:

Example: Code result

- Ricky Brundritt, Bing Maps Program Manager