Silverlight for Windows Phone Programming Tip – Navigation

When using the Silverlight for Windows Phone APIs to navigate from one page to another, it is necessary to use the Navigate method on the PhoneApplicationPage instance’s NavigationService property. When making this call, it is important to note the required Uri Syntax, as follows:

Navigating to a page in the same assembly:

NavigationService.Navigate(new Uri("/Folder(s)/TargetPage.xaml", UriKind.relative));

Navigating to a page in another assembly:

NavigationService.Navigate(new Uri("/AssemblyName;component/Folder(s)/TargetPage.xaml", UriKind.Relative));

The current MSDN Documentation (update date of 1/28/2001) for the Navigate method does not include any text that specifies the requirements for the syntax or the Uri, so here goes my attempt to provide the missing content:

• The provided Uri must start with a forward slash (/), indicating the content is local to the Xap file. Failure to include the leading slash will result in an ArgumentException (details below) being thrown.
• The UriKind must be specified as UriKind.Relative (or URIKindRelativeOrAbsolute, but why ask for trouble?) Omitting the UriKind uses the default value of URIKind.Absolute, which yields the same ArgumentException
• To navigate to a page in another assembly contained within the same Xap file, the syntax must include the Assembly Name for the assembly that contains the page, then a semicolon and the word “component”, followed by the folder path to the page.
  • The leading slash and the specification of a Relative Uri are still required, with the same consequences if omitted.
  • Omitting the word “component” results in an InvalidOperationException (No Xaml was found at the location…)

The description contained in the Argument exception is actually quite helpful – it reads “Navigation is only supported to relative URIs that are fragments, or begin with ‘/’, or which contain ‘;component.” However, you have to first fail in your attempts to navigate and be in a position to trap and analyze the exception for it to be useful.

Making small and subtle mistakes in the navigation Uri is quite easy to do…not only is missing relevant documentation missing as noted above, but this API also falls quite short in the “Pit of Success” category at the expense of matching up with the Navigation API in regular Silverlight (I have witnessed good presenters’ phone demos get derailed and lose precious time because of some simple omissions in this regard.) A better alternative would have been to have offered a way to avoid the specific nuances of the API in favor of phone-specific methods. (Jeremy’s Ultra-Light Windows Phone 7 MVVM Framework accomplishes something very close/similar.) Fortunately, if you are doing a lot of navigation in your app and would like to include a set of phone-specific NavigateToPhonePage calls which figure out and correct the necessary Uris for you, there is a quick way to do so – using Extension Methods. A set of simple & helpful starter Phone Navigation extension methods follows:


public static class PhoneNavigationServiceExtensions

{

if (navigationService == null) throw new ArgumentNullException("navigationService");

if (!page.StartsWith("/")) page = "/" + page;  //Compensate for lack of leading slash

navigationService.Navigate(new Uri(page, UriKind.Relative));  //Build the Uri, force it to be Relative.


}

public static void NavigateToLocalPhonePage(this NavigationService navigationService, String page)
{
NavigateToPhonePage(navigationService, page);
}

 <br><br>&nbsp;&nbsp;&nbsp;&nbsp; public static void NavigateToExternalPhonePage(this NavigationService navigationService, String assemblyName, String page)

{

}



Given these extensions, the following navigation calls all work without a need to specify the UriKind, and with varying inclusions and omissions of the forward slashes:


// Using NavigateToLocalPhonePage requires nothing more than the path to the page's xaml file

NavigationService.NavigateToLocalPhonePage("Folder(s)/TargetPage.xaml");

// Using NavigateToExternalPhonePage calls out the need for the assembly name and the page’s xaml file path

NavigationService.NavigateToExternalPhonePage(“/WindowsPhoneClassLibrary1”, “/Folder(s)/TargetPage.xaml”);

NavigationService.NavigateToExternalPhonePage(“WindowsPhoneClassLibrary1”, “Folder(s)/TargetPage.xaml”);

// Using the NavigateToPage method directly works for either, but the External page must be specified correctly

NavigationService.NavigateToPhonePage(“Folder(s)/TargetPage.xaml”);

NavigationService.NavigateToPhonePage(“WindowsPhoneClassLibrary1;component/Folder(s)/TargetPage.xaml”);