How to add a Map control to a page in Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

 

This topic describes the various ways to add a Map control to a Windows Phone 8 project. The Map control is part of the libraries in Windows Phone SDK 8.0. Because the Map control is not a core control in memory, it must be referenced properly before you can use it. You must also add an ID_Cap_Map capability before you add the control to the project.

Tip

This topic describes how to write code that displays a map inside your app. If you simply want to display a map, you can also use the Maps task, which launches the built-in Maps app. For more info, see How to use the Maps task for Windows Phone 8.

For a sample that demonstrates some of the tasks described in this topic, download the Simple Map control sample.

For useful extensions to the Maps API, including a Pushpin, download the Windows Phone Toolkit.

This topic contains the following sections.

 

Adding the Map capability

You must add an ID_Cap_Map capability before you add the Map control.

To add the ID_Cap_Map capability

  1. In Visual Studio 2012, create a new Windows Phone 8 project named MapApplication.

  2. In the MapApplication project, click the Properties folder, and then double-click WMAppManifest.xml file.

  3. In WMAppManifest.xml file, click the Capabilities tab.

  4. In the Capabilities table, select ID_Cap_Map capability.

Adding a Map control by using the Toolbox

The easiest way to add a Map control and reference it properly is to drag it from the Toolbox and drop it to your XAML designer or XAML view.

To add a Map control from the Toolbox

  1. In the MapApplication project, open the Toolbox, and then open the All Windows Phone Controls.

  2. From the Toolbox, drag the Map control to the XAML or designer view.

    Visual Studio performs the following tasks automatically.

    • Adds a reference to Microsoft.Phone.Maps assembly.

    • In the <phone:PhoneApplicationPage> start tag of the XAML page, adds the following XML namespace declaration for the SDK namespace.

      xmlns:Controls="clr-namespace:Microsoft.Phone.Maps.Controls;assembly=Microsoft.Phone.Maps"
      
    • Adds the following XAML to your page if you drag the control to XAML view.

      <Controls:Map />

      -or-

    • Adds the following XAML if you drag the control to the design view.

      <Controls:Map HorizontalAlignment="Left" Margin="158,265,0,0" VerticalAlignment="Top"/>
      

Adding the Map control by using XAML

To add a Map control manually by using XAML, you must first add a reference to Microsoft.Phone.Maps assembly, and then you must map an XML namespace to the assembly.

To add a reference to the Microsoft.Phone.Maps assembly in Visual Studio

  1. In your MapApplication project, right-click the Project menu, and then select Add Reference.

  2. In the Reference Manager dialog box, click Browse.

  3. Browse to C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\WindowsPhone\v8.0.

  4. Double-click the Microsoft.Phone.Maps.dll file.

  5. Click OK.

To add an XML namespace mapping

  1. Open MainPage.xaml.

  2. In the <phone:PhoneApplicationPage> start tag of the XAML page, add the following XML namespace declaration for the SDK namespace.

    xmlns:Controls="clr-namespace:Microsoft.Phone.Maps.Controls;assembly=Microsoft.Phone.Maps"
    

To add the Map control by using XAML

  1. Open Mainpage.xaml.

  2. Add the following XAML to the ContentPanel grid.

    <Controls:Map></Controls:Map>
    

Adding the Map control by using code

Once you have a reference to Microsoft.Phone.Maps assembly, you can add the Map control by using code. The following example creates a Map control named MyMap and then adds it to ContentPanel grid.

To add the Map control by using code

  1. Open MainPage.xaml.cs.

  2. Add the following using statement.

    Using Microsoft.Phone.Maps.Controls;
    
  3. Add the following code.

    public MainPage()
    {
       InitializeComponent();
       Map MyMap = new Map();
       ContentPanel.Children.Add(MyMap);
    }
    

Adding the ApplicationID and AuthenticationToken

Before you can publish an app that uses the Map control, you have to get an ApplicationId and AuthenticationToken from the Windows Phone Dev Center and add the values to your code. The values that you get are specific to the individual app for which you request them.

To get an ApplicationID and AuthenticationToken from the Dev Center 

  1. After you have finished your app, begin the app submission process.

  2. On the Submit app page, click Map services.

    The Map services page opens.

  3. On the page, click Get token.

    The new ApplicationID and AuthenticationToken are displayed on the same page.

  4. Copy the values and paste them into your code as described in the following procedure.

  5. Rebuild your app with the new code and upload and updated copy to the Store.

You have to set the values of both the ApplicationId and AuthenticationToken properties after the first Map control has been loaded, not just instantiated. If you destroy all instances of the Map control in your app and then create a new instance, you have to set these properties again.

To specify the ApplicationID and AuthenticationToken in your code

  1. In Visual Studio, in your code, create an event handler for the Loaded event of the Map control.

  2. Copy each of the values that you obtained from the Dev Center and assign them to the respective properties, as show in the following code:

            private void myMapControl_Loaded(object sender, RoutedEventArgs e)
            {
                Microsoft.Phone.Maps.MapsSettings.ApplicationContext.ApplicationId = "ApplicationID";
                Microsoft.Phone.Maps.MapsSettings.ApplicationContext.AuthenticationToken = "AuthenticationToken";
            }
    

Terms of use for map services

Continued use of map services is governed by the Terms of Use. Microsoft may share with Nokia the developer IDs that are using the map services, because Nokia supplies some of these services.

See Also

Reference

Map

Other Resources

Maps and navigation for Windows Phone 8

Map control design guidelines for Windows Phone

How to add UIElements to a Map control in Windows Phone 8

How to display route and directions on a map in Windows Phone 8