How to: Calculate a Route between Waypoints Using the Bing Route Service

• Nov 13, 2018
• 8 minutes to read

This example demonstrates how to calculate a route between several waypoints and change the appearance of a route path using the Microsoft Bing Route web service. Do this as follows.

• Create an InformationLayer object and add it to the MapControl.Layers collection.
• Create a BingRouteDataProvider object and assign it to the InformationLayer.DataProvider property.
• To calculate a route, call the BingRouteDataProvider.CalculateRoute method and pass a list of waypoints as its argument.

• To customize the route path appearance, handle the InformationDataProviderBase.LayerItemsGenerating event and modify the MapPointer.Text property of each MapPushpin and customize the MapPolyline appearance.

  Note that the polyline for the route and map pushpins for waypoints is generated automatically and the LayerItemsGenerating event occurs because the InformationDataProviderBase.GenerateLayerItems property value is true by default.

Note

Refer to How to: Get a Bing Maps Key if you run the application and see a window with the following error message: “The specified Bing Maps key is invalid. To create a developer account, refer to https://www.microsoft.com/en-us/maps/create-a-bing-maps-key“.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-calculate-a-route-between-waypoints-and-customize-the-appearance-of-a-route-path-usin-e5100

WaitForm1.cs

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using DevExpress.XtraWaitForm;

namespace ConnectToRouteService {
    public partial class WaitForm1 : WaitForm {
        public WaitForm1() {
            InitializeComponent();
            this.progressPanel1.AutoHeight = true;
        }

        #region Overrides

        public override void SetCaption(string caption) {
            base.SetCaption(caption);
            this.progressPanel1.Caption = caption;
        }
        public override void SetDescription(string description) {
            base.SetDescription(description);
            this.progressPanel1.Description = description;
        }
        public override void ProcessCommand(Enum cmd, object arg) {
            base.ProcessCommand(cmd, arg);
        }

        #endregion
    }
}

Form1.cs

using DevExpress.XtraMap;
using System.Collections.Generic;
using System.Drawing;
using System.Windows.Forms;

namespace ConnectToRouteService {
    public partial class Form1 : DevExpress.XtraEditors.XtraForm {
        const string yourBingKey = "YOUR BING KEY";
        BingRouteDataProvider routeProvider;

        public Form1() {
            InitializeComponent();
        }

        private void Form1_Load(object sender, System.EventArgs e) {
            imageProvider.BingKey = yourBingKey;

            routeProvider = new BingRouteDataProvider { BingKey = yourBingKey };
            informationLayer.DataProvider = routeProvider;
            #region #Waypoints
            // Create three waypoints and add them to a route waypoints list. 
            List<RouteWaypoint> waypoints = new List<RouteWaypoint> {
                new RouteWaypoint("New York", new GeoPoint(41.145556, -73.995)),
                new RouteWaypoint("Oklahoma", new GeoPoint(36.131389, -95.937222)),
                new RouteWaypoint("Las Vegas", new GeoPoint(36.175, -115.136389))
            };
            #endregion #Waypoints
            // Call the BingRouteDataProvider.CalculateRoute method.
            splashScreenManager.ShowWaitForm();
            routeProvider.CalculateRoute(waypoints);

            // Handle the BingRouteDataProvider.LayerItemsGenerating event.
            routeProvider.LayerItemsGenerating += routeLayerItemsGenerating;
        }

        private void routeLayerItemsGenerating(object sender, LayerItemsGeneratingEventArgs e) {
            if(e.Cancelled || (e.Error != null)) return;

            //char pushpinMarker = 'A';
            foreach(MapItem item in e.Items) {
                //MapPushpin pushpin = item as MapPushpin;
                //if(pushpin != null) {
                //    pushpin.Text = pushpinMarker++.ToString();
                //}
                MapPolyline polyline = item as MapPolyline;
                if(polyline != null) {
                    polyline.Stroke = Color.FromArgb(0xFF, 0x00, 0x72, 0xC6);
                    polyline.StrokeWidth = 4;
                }
            }
            splashScreenManager.CloseWaitForm();
            mapControl.ZoomToFit(e.Items, 0.4);
        }
    }
}

Program.cs

// Developer Express Code Central Example:
// How to calculate a route between waypoints and customize the appearance of a route path using a Microsoft Bing Route web service
// 
// This example demonstrates how to calculate a route between several waypoints and
// change the appearance of a route path by means of the Microsoft Bing Route web
// service.
// 
// To calculate a route between waypoints, call the
// BingRouteDataProvider.CalculateRoute
// (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapBingRouteDataProvider_CalculateRoutetopic)
// method and pass a list of waypoints as its argument.
// 
// To customize the route
// path appearance, do the following:
// 
// - Handle the
// BingRouteDataProvider.RouteCalculated event;
// - Access the route path using the
// RouteCalculationResult
// (http://documentation.devexpress.com/#WindowsForms/clsDevExpressXtraMapRouteCalculationResulttopic)
// object inside the BingRouteDataProvider.RouteCalculated event handler's
// BingRouteCalculatedEventArgs
// (http://documentation.devexpress.com/#WindowsForms/clsDevExpressXtraMapBingRouteCalculatedEventArgstopic);
// -
// Create a MapPolyline
// (http://documentation.devexpress.com/#WindowsForms/clsDevExpressXtraMapMapPolylinetopic)
// with calculated route points. To access the route points collection, use the
// BingRouteResult.RoutePath
// (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapBingRouteResult_RoutePathtopic)
// property;
// - Customize the stroke and stroke width of the map polyline using the
// MapItem.Stroke
// (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapMapItem_Stroketopic)
// and MapItem.StrokeWidth
// (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapMapItem_StrokeWidthtopic)
// properties. The map pushpins are generated automatically at each route waypoint
// position because the InformationDataProviderBase.GenerateLayerItems
// (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapInformationDataProviderBase_GenerateLayerItemstopic)
// property is set to true by default. Note that the pushpins' text contains an
// empty string. To number route waypoints (from start to finish) in the pushpin,
// handle the InformationDataProviderBase.LayerItemsGenerating
// (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapInformationDataProviderBase_LayerItemsGeneratingtopic)
// event and modify the MapPointer.Text
// (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapMapPointer_Texttopic)
// property. Note that if you run this sample as is, you will get a warning message
// saying that the specified Bing Maps key is invalid. To learn more about Bing Map
// keys, please refer to the How to: Get a Bing Maps Key
// (http://help.devexpress.com/#WindowsForms/CustomDocument15102) tutorial.
// 
// You can find sample updates and versions for different programming languages here:
// http://www.devexpress.com/example=E5100


using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using System.Windows.Forms;

namespace ConnectToRouteService {
    static class Program {
        /// <summary>
        /// The main entry point for the application.
        /// </summary>
        [STAThread]
        static void Main() {
            Application.EnableVisualStyles();
            Application.SetCompatibleTextRenderingDefault(false);
            Application.Run(new Form1());
        }
    }
}

Program.vb

' Developer Express Code Central Example:
' How to calculate a route between waypoints and customize the appearance of a route path using a Microsoft Bing Route web service
' 
' This example demonstrates how to calculate a route between several waypoints and
' change the appearance of a route path by means of the Microsoft Bing Route web
' service.
' 
' To calculate a route between waypoints, call the
' BingRouteDataProvider.CalculateRoute
' (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapBingRouteDataProvider_CalculateRoutetopic)
' method and pass a list of waypoints as its argument.
' 
' To customize the route
' path appearance, do the following:
' 
' - Handle the
' BingRouteDataProvider.RouteCalculated event;
' - Access the route path using the
' RouteCalculationResult
' (http://documentation.devexpress.com/#WindowsForms/clsDevExpressXtraMapRouteCalculationResulttopic)
' object inside the BingRouteDataProvider.RouteCalculated event handler's
' BingRouteCalculatedEventArgs
' (http://documentation.devexpress.com/#WindowsForms/clsDevExpressXtraMapBingRouteCalculatedEventArgstopic);
' -
' Create a MapPolyline
' (http://documentation.devexpress.com/#WindowsForms/clsDevExpressXtraMapMapPolylinetopic)
' with calculated route points. To access the route points collection, use the
' BingRouteResult.RoutePath
' (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapBingRouteResult_RoutePathtopic)
' property;
' - Customize the stroke and stroke width of the map polyline using the
' MapItem.Stroke
' (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapMapItem_Stroketopic)
' and MapItem.StrokeWidth
' (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapMapItem_StrokeWidthtopic)
' properties. The map pushpins are generated automatically at each route waypoint
' position because the InformationDataProviderBase.GenerateLayerItems
' (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapInformationDataProviderBase_GenerateLayerItemstopic)
' property is set to true by default. Note that the pushpins' text contains an
' empty string. To number route waypoints (from start to finish) in the pushpin,
' handle the InformationDataProviderBase.LayerItemsGenerating
' (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapInformationDataProviderBase_LayerItemsGeneratingtopic)
' event and modify the MapPointer.Text
' (http://documentation.devexpress.com/#WindowsForms/DevExpressXtraMapMapPointer_Texttopic)
' property. Note that if you run this sample as is, you will get a warning message
' saying that the specified Bing Maps key is invalid. To learn more about Bing Map
' keys, please refer to the How to: Get a Bing Maps Key
' (http://help.devexpress.com/#WindowsForms/CustomDocument15102) tutorial.
' 
' You can find sample updates and versions for different programming languages here:
' http://www.devexpress.com/example=E5100


Imports System
Imports System.Collections.Generic
Imports System.Linq
Imports System.Threading.Tasks
Imports System.Windows.Forms

Namespace ConnectToRouteService
    Friend NotInheritable Class Program

        Private Sub New()
        End Sub

        ''' <summary>
        ''' The main entry point for the application.
        ''' </summary>
        <STAThread> _
        Shared Sub Main()
            Application.EnableVisualStyles()
            Application.SetCompatibleTextRenderingDefault(False)
            Application.Run(New Form1())
        End Sub
    End Class
End Namespace

Form1.vb

Imports DevExpress.XtraMap
Imports System.Collections.Generic
Imports System.Drawing
Imports System.Windows.Forms

Namespace ConnectToRouteService
    Partial Public Class Form1
        Inherits DevExpress.XtraEditors.XtraForm

        Private Const yourBingKey As String = "YOUR BING KEY"
        Private routeProvider As BingRouteDataProvider

        Public Sub New()
            InitializeComponent()
        End Sub

        Private Sub Form1_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Load
            imageProvider.BingKey = yourBingKey

            routeProvider = New BingRouteDataProvider With {.BingKey = yourBingKey}
            informationLayer.DataProvider = routeProvider
'            #Region "#Waypoints"
            ' Create three waypoints and add them to a route waypoints list. 
            Dim waypoints As New List(Of RouteWaypoint)() From { _
                New RouteWaypoint("New York", New GeoPoint(41.145556, -73.995)), _
                New RouteWaypoint("Oklahoma", New GeoPoint(36.131389, -95.937222)), _
                New RouteWaypoint("Las Vegas", New GeoPoint(36.175, -115.136389)) _
            }
'            #End Region ' #Waypoints
            ' Call the BingRouteDataProvider.CalculateRoute method.
            splashScreenManager.ShowWaitForm()
            routeProvider.CalculateRoute(waypoints)

            ' Handle the BingRouteDataProvider.LayerItemsGenerating event.
            AddHandler routeProvider.LayerItemsGenerating, AddressOf routeLayerItemsGenerating
        End Sub

        Private Sub routeLayerItemsGenerating(ByVal sender As Object, ByVal e As LayerItemsGeneratingEventArgs)
            If e.Cancelled OrElse (e.Error IsNot Nothing) Then
                Return
            End If

            'char pushpinMarker = 'A';
            For Each item As MapItem In e.Items
                'MapPushpin pushpin = item as MapPushpin;
                'if(pushpin != null) {
                '    pushpin.Text = pushpinMarker++.ToString();
                '}
                Dim polyline As MapPolyline = TryCast(item, MapPolyline)
                If polyline IsNot Nothing Then
                    polyline.Stroke = Color.FromArgb(&HFF, &H0, &H72, &HC6)
                    polyline.StrokeWidth = 4
                End If
            Next item
            splashScreenManager.CloseWaitForm()
            mapControl.ZoomToFit(e.Items, 0.4)
        End Sub
    End Class
End Namespace

WaitForm1.vb

Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Data
Imports System.Drawing
Imports System.Text
Imports System.Windows.Forms
Imports DevExpress.XtraWaitForm

Namespace ConnectToRouteService
    Partial Public Class WaitForm1
        Inherits WaitForm

        Public Sub New()
            InitializeComponent()
            Me.progressPanel1.AutoHeight = True
        End Sub

        #Region "Overrides"

        Public Overrides Sub SetCaption(ByVal caption As String)
            MyBase.SetCaption(caption)
            Me.progressPanel1.Caption = caption
        End Sub
        Public Overrides Sub SetDescription(ByVal description As String)
            MyBase.SetDescription(description)
            Me.progressPanel1.Description = description
        End Sub
        Public Overrides Sub ProcessCommand(ByVal cmd As System.Enum, ByVal arg As Object)
            MyBase.ProcessCommand(cmd, arg)
        End Sub

        #End Region
    End Class
End Namespace