How to respond to requests for directions from another app (XAML)

Article
08/31/2015

This topic describes how to write an app that responds to requests for driving or walking directions when called by another app installed on the device. The other app requests directions by calling the ms-drive-to or ms-walk-to Uri scheme.

Important How to provide turn-by-turn directions is beyond the scope of this topic and is not described here. The code sample in this topic simply displays the destination specified in the request.

For more info about handling Uri activation, see How to handle URI activation. For info about how to write an app that requests directions, see How to request driving or walking directions.

Registering to handle a Uri association

To register to handle a Uri association

In the Extensions element of the app manifest file, which must immediately follow the Tokens element, use the following format to specify the navigation protocol or protocols that your app can handle. Your app does not have to handle both Uri associations.
```
<Extensions>
      <Protocol Name="ms-drive-to" NavUriFragment="encodedLaunchUri=%s" TaskID="_default"/>
      <Protocol Name="ms-walk-to" NavUriFragment="encodedLaunchUri=%s" TaskID="_default"/>
    </Extensions>
```

Listening for a Uri

To listen for a Uri

Create a Uri mapping class to map the request received from the calling app to a page in your app. Here is an example of a Uri mapping class that parses the Uri and calls the ShowDestination.xaml page with the arguments required by the page.

class DirectionsRequestUriMapper : UriMapperBase
    {

        public override Uri MapUri(Uri uri)
        {
            string tempUri = Uri.UnescapeDataString(uri.ToString());

            // Does the Uri contain a request for driving directions or walking directions?
            if (tempUri.Contains("ms-drive-to") || tempUri.Contains("ms-walk-to"))
            {
                // Parse the Uri.
                char[] uriDelimiters = { '?', '=', '&' };
                string[] uriParameters = tempUri.Split(uriDelimiters);
                string destLatitude = uriParameters[4];
                string destLongitude = uriParameters[6];
                string destName = uriParameters[8];

                // Map the request for directions to the ShowDestination page of the app.
                return new Uri(
                    "/ShowDestination.xaml?" +
                    "latitude=" + destLatitude + "&" +
                    "longitude=" + destLongitude + "&" +
                    "name=" + destName,
                    UriKind.Relative);
            }
            // Otherwise, handle the Uri normally.
            return uri;
        }
    }

First, the sample code decodes the Uri received from the calling app.

Here is an example of the encoded Uri that your app receives from the sample shown earlier in this topic:

/Protocol?encodedLaunchUri=ms-drive-to%3A%3Fdestination.latitude%3D47.6451413797194%26destination.longitude%3D-122.141964733601%26destination.name%3DRedmond%2C%20WA

Next the sample splits the Uri into its component parts:

(array index 0) /Protocol
(array index 1) uri
(array index 2) ms-drive-to
(array index 3) destination.latitude
(array index 4) 47.6451413797194
(array index 5) destination.longitude
(array index 6) -122.141964733601
(array index 7) destination.name
(array index 8) Redmond, WA

Finally the sample assembles the following Uri to call the ShowDestination.xaml page with the arguments required by the page:

/ShowDestination.xaml?latitude=47.6451413797194&longitude=-122.141964733601&name=Redmond, WA

From Solution Explorer, open the App.xaml.cs code file. Add the following line of code to the InitializePhoneApplication method to enable the Uri mapping class.

private void InitializePhoneApplication()
        {
            ...

            RootFrame = new PhoneApplicationFrame();
            ...

            // Assign the Uri mapper class to the application frame.
            RootFrame.UriMapper = new DirectionsRequestUriMapper();

            ...

        }

Handling the Uri

To handle the Uri

Create the target page that handles the request for directions to the specified destination. This sample creates a page named ShowDestination.xaml that simply displays the parameter values passed to the page in the Uri.

The starting point is not specified in the request, and is assumed to be the current location. Before you use location services to get the current location, make sure that the user has given consent to use the phone’s location. For more info and sample code, see Quickstart: Detecting a user's location.

In ShowDestination.xaml, add a textbox to the page to display the parameter values.

 <!--ContentPanel - place additional content here-->
        <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
            <TextBox x:Name="tbDestinationParams" HorizontalAlignment="Left" Height="516" Margin="10,10,0,0" TextWrapping="Wrap" VerticalAlignment="Top" Width="436" IsReadOnly="True"/>
        </Grid>

In ShowDestination.xaml.cs, add code to process the Uri in the page’s OnNavigatedTo event. This code simply displays the parameter values passed to the page in the Uri.

protected override void OnNavigatedTo(NavigationEventArgs e)
        {
            base.OnNavigatedTo(e);

                // Extract the arguments from the query string passed to the page.
                IDictionary<string, string> uriParameters = this.NavigationContext.QueryString;
                string destLatitude = uriParameters["latitude"];
                string destLongitude = uriParameters["longitude"];
                string destName = uriParameters["name"];

                this.tbDestinationParams.Text = "\tlatitude = " + destLatitude + "\r\n" +
                                                "\tlongitude = " + destLongitude + "\r\n" +
                                                "\tname = " + destName;

        }

The following screen shot shows the parameter values displayed by the preceding sample.

How to request driving or walking directions

How to respond to requests for directions from another app (XAML)

Registering to handle a Uri association

Listening for a Uri

Handling the Uri

Related topics

Additional resources