NavigationService Class

Reference

Definition

Namespace:: System.Windows.Navigation

Assembly:: PresentationFramework.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Contains methods, properties, and events to support navigation.

public ref class NavigationService sealed

public sealed class NavigationService

type NavigationService = class

Public NotInheritable Class NavigationService

Inheritance: Object
NavigationService

Remarks

NavigationService encapsulates the ability to download content within the context of a browser-style navigation.

Content can be any type of .NET Framework object and HTML files. In general, however, pages are the preferred as the way to package content for navigation (see Page).

Content can be navigated to by providing an instance of an object and calling an overload of the Navigate method that accepts an object:

Alternatively, content can be navigated to by passing a relative or absolute URI to one of the Navigate method overloads that accepts a URI:

When content is navigated to by URI, NavigationService will return an object that contains the content.

The lifetime of a navigation can be tracked through the following events:

Not all events are raised each time that a navigation occurs; the set of events that are raised is determined by the type of navigation that occurs (content or content fragment) and how the navigation completes (canceled, stopped, or failed).

The following figure illustrates the sequence in which these events are raised:

Page navigation flow chart

During or after a navigation, NavigationService provides information about the content that is being navigated to, including the URI of the content being navigated to (Source), the URI of the current content (CurrentSource), and an object that contains the content that was navigated to (Content).

When content is navigated to, NavigationService records the navigation as an entry in navigation history. An entry is added to back navigation history when either a new navigation occurs, by calling the Navigate method, or by navigating to an entry in forward navigation history, by calling GoForward. An entry is added to forward navigation history by navigating to an entry in back navigation history, by calling GoBack. CanGoBack and CanGoForward report whether there are entries in back and forward navigation history, respectively. Also, the most recent entry in back navigation history can be removed by calling RemoveBackEntry.

By default, NavigationService does not store an instance of a content object in navigation history. Instead, NavigationService creates a new instance of the content object each time it is navigated to by using navigation history. This behavior is designed to avoid excessive memory consumption when large numbers and large pieces of content are being navigated to. Consequently, the state of the content is not remembered from one navigation to the next. However, WPF provides several techniques by which you can store a piece of state for a piece of content in navigation history.

Using AddBackEntry, you can also remember multiple sets of state for a single page instance.

NavigationService is a sealed class and therefore cannot be instantiated; instead, NavigationService is used by navigators to enable navigation. In WPF, there are two navigators: NavigationWindow and Frame.

Visually, XBAPs use Internet Explorer as a navigator, to provide an integrated user experience. Physically, however, XBAPs actually use NavigationWindow as the navigator; the MainWindow property of an XBAP running in Internet Explorer will return a reference to the NavigationWindow, and the navigation history that is managed by the NavigationWindow is integrated with the navigation history that is managed by Internet Explorer in the following ways:

When content is navigated to by calling Navigate, GoBack, and GoForward from within an XBAP the relevant navigation history entries are also added to Internet Explorer navigation history.
When entries in the Internet Explorer navigation UI are selected, Internet Explorer causes NavigationService to navigate back or forwards to the content that is associated with those entries.

Note

A Frame can provide its own navigation history, or use the navigation history of the navigator that hosts it. If Frame provides its own navigation history, it can display its own navigation UI to navigate through the entries in navigation history; those entries are not added to the navigation history of the host navigator (NavigationWindow, Frame, browser) and, consequently, cannot be navigated to from the navigation UI of each (see JournalOwnership).

For more information about XBAP support, see Frequently asked questions about WPF browser-hosted applications (XBAP).

Properties

CanGoBack	Gets a value that indicates whether there is at least one entry in back navigation history.
CanGoForward	Gets a value that indicates whether there is at least one entry in forward navigation history.
Content	Gets or sets a reference to the object that contains the current content.
CurrentSource	Gets the URI of the content that was last navigated to.
Source	Gets or sets the URI of the current content, or the URI of new content that is currently being navigated to.

Methods

AddBackEntry(CustomContentState)	Adds an entry to back navigation history that contains a CustomContentState object.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetNavigationService(DependencyObject)	Gets a reference to the NavigationService for the navigator whose content contains the specified DependencyObject.
GetType()	Gets the Type of the current instance. (Inherited from Object)
GoBack()	Navigates to the most recent entry in back navigation history, if there is one.
GoForward()	Navigate to the most recent entry in forward navigation history, if there is one.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
Navigate(Object, Object)	Navigate asynchronously to content that is contained by an object, and pass an object that contains data to be used for processing during navigation.
Navigate(Object)	Navigate asynchronously to content that is contained by an object.
Navigate(Uri, Object, Boolean)	Navigate asynchronously to source content located at a URI, pass an object containing navigation state for processing during navigation, and sandbox the content.
Navigate(Uri, Object)	Navigate asynchronously to source content located at a URI, and pass an object that contains data to be used for processing during navigation.
Navigate(Uri)	Navigate asynchronously to content that is specified by a URI.
Refresh()	Reloads the current content.
RemoveBackEntry()	Removes the most recent journal entry from back history.
StopLoading()	Stops further downloading of content for the current navigation request.
ToString()	Returns a string that represents the current object. (Inherited from Object)

Events

FragmentNavigation	Occurs when navigation to a content fragment begins, which occurs immediately, if the desired fragment is in the current content, or after the source XAML content has been loaded, if the desired fragment is in different content.
LoadCompleted	Occurs when content that was navigated to has been loaded, parsed, and has begun rendering.
Navigated	Occurs when the content that is being navigated to has been found, and is available from the Content property, although it may not have completed loading.
Navigating	Occurs when a new navigation is requested.
NavigationFailed	Occurs when an error occurs while navigating to the requested content.
NavigationProgress	Occurs periodically during a download to provide navigation progress information.
NavigationStopped	Occurs when the StopLoading() method is called, or when a new navigation is requested while a current navigation is in progress.

Applies to

Share via