Mobile Corner

UriMapper in Windows Phone

Nick Randolph looks at how you can use a UriMapper to help structure your Windows Phone application.

• By Nick Randolph
• 01/12/2012

In an earlier post on Search Extensibility in Windows Phone 7, a UriMapper was used to translate the launch URI invoked by Bing Search into a MappedUri; in this case, a page within the Windows Phone application. In this article we're going to look at how to use a UriMapper to aid in structuring and navigating within your Windows Phone application. As a refresher, here's the UriMapper we defined in the App.xaml, and how it was connected to the PhoneApplicationFrame in the App.xaml.cs file.

App.xaml
<Application.Resources>
    <uriMapper:UriMapper x:Key="UriMapper">
            <uriMapper:UriMapping Uri="/SearchExtras"
                            MappedUri="/MainPage.xaml" />
    </uriMapper:UriMapper>
</Application.Resources>

App.xaml.cs
RootFrame = new PhoneApplicationFrame() {
                                UriMapper = Resources["UriMapper"] as UriMapper
                            };

We're going to start by changing the UriMapping to the following:

<uriMapper:UriMapping Uri="/{Page}" MappedUri="/{Page}Page.xaml" />

This mapping will translate any URI that starts with "/" by appending the "Page.xaml" suffix. This assumes that all the pages within our application will end with "Page.xaml", but means that instead of navigating to "/SecondPage.xaml", we can instead navigate to just "/Second".

This becomes useful if we later decide that all our pages are going to be in a folder called "Pages". Previously, you would have had to search through your entire application looking for any Navigate methods and modify the URI to include the "/Pages" prefix. Using UriMapping, all you need to do is change the mapping to include the prefix.

<uriMapper:UriMapping Uri="/{Page}" MappedUri="/Pages/{Page}Page.xaml" />

As your Windows Phone application grows, you may decide to break your application up into separate assemblies. In this case, you can again use a UriMapping to locate the page to which the user is navigating. For example, the following mapping will locate the MySatellitePage.xaml, which is in an assembly called Satellite:

<uriMapper:UriMapping Uri="/MySatellite" 
                      MappedUri="/Satellite;component/Pages/MySatellitePage.xaml" />

Deep Linking
Another place where the use of a UriMapping is important is when you're using deep linking in order to direct users to a specific location within the application. This may be from a Live Tile (as determined by the URI specified when creating the tile), or from a Toast notification (the Param element determines the URI within the application to be navigated to when the user taps on the toast).

The simple approach is to use the URI of the page you want to launch (e.g., "/MyLaunchPage.xaml"). However, this introduces a strong coupling between the application structure and the notifications being sent from the server. Instead, we can add a UriMapping similar to the following, which maps a "/Toast" URI through to the launch page:

<uriMapper:UriMapping Uri="/Toast" 
                      MappedUri="/MyLaunchPage.xaml" />

Now, if we need to change the structure of the application, we can do so easily by updating the mapping. Without the UriMapping we'd have to update both the Windows Phone application and the server code, and ensure they're both updated at the same time – a nearly impossible task.

You'll notice that we haven't specified any query parameters in any declared mappings. This is because they'll automatically get mapped across from the URI to the MappedUri. In the case of the last UriMapping, for example, a URI of "/Toast?customerId=1234" will get mapped to "/MyLaunchPage.xaml?customerId=1234".

I've demonstrated a number of scenarios where a UriMapper can be used to improve navigation and the structure of your Windows Phone application. Learn to use this powerful tool, and you'll be writing more efficient code before you know it.