Migration Guide
Bing Maps V7 to V8 Bing Maps V7 to V8 Migration Guide
Contents 1.0 Introduction ...... 4 1.1 Why Bing Maps v8? ...... 4 1.2 Suggested Migration Plan ...... 5 1.3 Technical Resources ...... 5 2.0 What’s New in Bing Maps V8 ...... 6 2.1 Map Script URL ...... 6 2.2 Asynchronous load the Map ...... 7 2.3 Release Branches ...... 7 2.4 Localization ...... 8 2.5 Key New Features ...... 8 3.0 Breaking Changes from Bing Maps V7 ...... 12 3.1 Deprecated Modules...... 12 3.2 Deprecated Classes ...... 12 3.3 Deprecated Class Function, Properties or Events ...... 14 3.4 Breaking Class Function or Property Changes ...... 18 3.5 Custom HTML Pushpins ...... 18 3.6 EntityCollection deprecation ...... 20 3.7 Infobox Breaking Change ...... 21 3.8 Map Center Offset Workaround ...... 22 4. 0 Code Optimizations in V8 ...... 23 4.1 Loading the Map ...... 23 4.2 Adding an array of shapes to the map ...... 23 4.3 Changing the Color of the Pushpins ...... 24 4.4 Setting the Color of a Polygon or Polyline ...... 25 4.5 Getting the Location of a Mouse Event ...... 25 4.6 Adding Events to an Array of Shapes ...... 26 4.7 Polygons with holes ...... 26 4.8 Loading Multiple Modules ...... 28 4.9 Adding Tile Layers to the Map ...... 28 4.10 Bing Maps REST Services ...... 30
Bing Maps V7 to V8 Migration Guide
5.0 Bing Maps V7 Modules CodePlex Project support ...... 32 6.0 Additional Bing Maps Tips ...... 34 6.1 Optimizing Transactions with the REST services ...... 34 6.2 Data Tips & Tricks ...... 34 6.3 Determining a User’s Location ...... 35 7.0 Useful Tools & Support ...... 38 7.1 Migration Support ...... 38 7.2 Bing Maps Blog ...... 38 Appendix A: Fiddler Redirect test ...... 39
Bing Maps V7 to V8 Migration Guide
1.0 Introduction This guide is designed to support you in your Bing Maps migration from version 7 to version 8. This resource provides detailed comparisons between the JavaScript API of these two versions of Bing Maps as well as comparative code samples, migration suggestions and best practices for migrating your code to the newest version of Bing Maps. As you read this document you should gain an understanding of the benefits of Bing Maps v8 and how to leverage it in your existing mapping applications. 1.1 Why Bing Maps v8? The version 7 of Bing Maps has been around for over 6 years. Version 8 of Bing Maps was just recently released and offers numerous advantages over v7, many of which are highlighted in section 2.0 What’s New in Bing Maps V8 of this document. The Bing Maps v8 web control is the recommended migration path from v7. Version 8 is over 80% backwards compatible with the v7 control which should help minimize the effort involved in migrating apps.
The Bing Maps V8 control contains several new innovative features and functionalities and there is a well laid out roadmap for bring new features to V8 on a regular basis.
Faster and more fluid map control
When it comes to performance the v8 is miles ahead of v7. Version 8 is capable of rendering data much faster than versions 7, and can also render a lot more data too. When dealing with small data sets on a standard browser this might not be that noticeable but if you need to display a large data set or are using a mobile browser this increased performance makes a big difference.
Increased culture support
Version 7 supported 22 different culture codes (languages). Version 8 supports significantly more culture codes and uses the Bing Maps REST services to perform geocode and route requests which has support for 117 languages.
Many new features
Over the years Bing Maps customers and developers have requested number of new features and functionalities. Many of these are now available in v8. Some of the most notable one’s being;
Bing Maps V7 to V8 Migration Guide
1.2 Suggested Migration Plan To assist you with planning, we have compiled this list of high‐level steps to use as a baseline plan to move your codebase and development practices to version 8 equivalents. While your ultimate plan will depend on your specific situation, the following steps outline suggested components of any effort:
1) Review existing application and identify where Bing Maps v7 code is being used. 2) As an option, before touching any code test your existing app against version 8 as it is by using the steps outlined in Appendix A: Fiddler Redirect test 3) Identify which features of Bing Maps v7 are being used and review the migration information in this document. 4) Migrate code to version v8 of Bing Maps and update script reference to point to the new v8 map control URL. 5) Test your migrated application. 6) Deploy your application to your production environment. 1.3 Technical Resources Here is a list of useful technical resources for the Bing Maps v8 web control.
Bing Maps v8 Interactive SDK Bing Maps v8 documentation Bing Maps MSDN documentation (All Bing Maps APIs) Bing Maps MSDN Forums Bing Maps Dev Center Bing Maps REST Services (MSDN) Bing Spatial Data Services (MSDN) Bing Maps Terms of Use
Bing Maps V7 to V8 Migration Guide
2.0 What’s New in Bing Maps V8 The Bing Maps v8 control reduces development time by requiring less code to implement more features into your app. It also brings significance performance improvement by using the HTML5 canvas, which provides the ability to render vector data over 10 times faster than previous versions of Bing Maps. It also supports rendering thousands of more shapes, allowing users to view more data and gain deeper insights into their data. In addition to this a number of exciting new features such as Autosuggest, Streetside imagery, and many business intelligence tools have been added.
Over 5 years of customer and developer feedback was used to understand the types of apps developers were creating with Bing maps. From this knowledge several improvements were made in the V8 SDK which better aligns with the type with these types of apps. 2.1 Map Script URL One of the first noticeable changes in the Bing Maps V8 API is the map script URL used to load the code needed for Bing Maps. http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0
If you wanted to use the V7 map control on a secure HTTPS site not only did you have to use an HTTPS domain for the URL, but you also had to add a query URL parameter. https://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&s=1
This URL has been a source of confusion for developers new to Bing Maps for the following reasons:
The name Virtual Earth is the legacy name that was used for the Bing Maps platform before it was rebranded as Bing Maps in 2009. Developers who are new to Bing Maps are often unaware of the name change. The dev subdomain was meant to indicate that this URL was for the Bing Maps developer API. However, to some this was interpreted as development environment which lead to developers asking where the production environment is. Bing Maps lets developers build their apps against the production service using a basic key during their development cycle. Having to add the extra query parameter when using HTTPS has been a common step many developers missed.
With the release of Bing Maps V8, this was the perfect time to update the map script URL to address these issues. http://www.bing.com/api/maps/mapcontrol
If you want to use HTTPS, simply add and “s” to “http”. https://www.bing.com/api/maps/mapcontrol
Alternatively, if your app is hosted on a server, you can drop http:/https: from the URL and the browser will automatically retrieve the correct version of the map control.
Bing Maps V7 to V8 Migration Guide
//www.bing.com/api/maps/mapcontrol
2.2 Asynchronous load the Map With V8 you can asynchronously load the map control by making use of the “async defer” keywords in the script tag and by adding a callback function to the map script URL. This provides a slight performance improvement when the page load. Here is an example of how to do this:
2.3 Release Branches There are three branches of the Bing Maps V8 SDK that can be accessed. This provides the option to access new features as your own pace.
Branch Description release The main branch of the SDK that is used in most applications. New features have been fully tested and known bugs found while in the experimental branch have been fixed. experimental New features are made available as soon as they have been developed. These features are still being tested and may have bugs in them. This branch is recommended for developers who want to try out the latest and greatest features as soon as they are available. frozen New features are added only after they have been in the release branch for a period of time and all known bugs have been fixed. This branch is recommended for mission critical apps that are willing to wait longer for new features in exchange for the extra stability.
To point your application to a specific branch simply add “&branch=[branch_version]” to the map script URL. If a branch is not specified, the release branch is automatically loaded. For example, the following URL can be used to load the experimental branch.
Tip: Before releasing your application into production, ensure that the branch isn’t set to experimental and test against the branch you plan to use.
Bing Maps V7 to V8 Migration Guide
2.4 Localization Localization of maps is the process of rendering maps in a specific language other than the default. Both v7 and v8 support localization. Version 7 required that you pass in a culture code to set the language of the map, however version 8 automatically tries to detect the appropriate culture code for a user based on their browser settings and location. This saves a lot of work in trying to manage the culture of the map yourself. However, like v7 it is possible to specify a culture code, which will override the default behavior. This is useful when testing, or if you only want the map to support a single language. If you do wish limit the map to a single language, the following is an example of how this was done in v7 and how it can be done in v8.
Before: v7
To get a localized map using v7, add an mkt parameter to the API script reference.