page.md

-api-id	-api-type
T:Microsoft.UI.Xaml.Controls.Page	winrt class

Microsoft.UI.Xaml.Controls.Page

-description

Represents content that a Frame control can navigate to.

-xaml-syntax

<Page .../>
-or-
<Page ...>
  singleRootElement
</Page>

-remarks

The Page class encapsulates content that the Frame control can navigate to. You will generally create your own page types that derive from the Page class, and use Page (or a custom type) as the root element for the XAML-declared content. You can create new pages using the Add | New Item menu option for your project in Microsoft Visual Studio. This creates a XAML file where the root is a Page element with an x:Class attribute that joins it to the code-behind class that derives from Page. This example shows how this looks for a page called MainPage.

<Page
    x:Class="App1.MainPage"
    ... >
   ...
</Page>

namespace App1
{
    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
        }
    }
}

Tip

Visual Studio includes a template for a blank page that you can populate with content. To accelerate app creation, you can use Template Studio for WinUI. It provides a number of app page templates you can use to add common UI pages into your new app, such as layouts like list/detail or web view, or pages that implement common patterns like app settings.

Layout

Page is a UserControl, therefore you can declare a single XAML object element as Content for the Page. Most pages contain more than one UI element in total. You typically use a panel or items control as the immediate child of a Page, so that you can have the page contain and compose multiple elements of a UI. For more info, see Layouts with XAML and Windows app silhouettes.

Navigation

Create as many pages as you need to present the content in your app, and then navigate to those pages by calling the Frame.Navigate method and passing in a type reference for the page to navigate to. By type reference, we mean an instance of a class that identifies a type in the type system, for the language you are using. For Microsoft .NET that type is System.Type, and you can get a System.Type reference from a page class' name by using the operators typeof (C#) or GetType (Visual Basic). For C++, use TypeName. For more info, see TypeName and winrt::xaml_typename function template.

Through Frame.Navigate, you can also pass in a parameter object to initialize the page to a particular state. The parameter object is loosely typed but serialization of navigation history only works for basic types (see Remarks in Frame.Navigate(Type, Object)). Pages that are navigated to as part of an activation generally pass data from the activation. Other navigation scenarios such as search result pages also have expectations of what info will be contained in the parameter.

This example shows what the Frame.Navigate call looks like.

rootFrame.Navigate(typeof(MainPage), args.Arguments);

rootFrame.Navigate(xaml_typename<Bookstore::MainPage>(), box_value(e.Arguments()));

By default, each navigation creates a new instance of the specific Page (or subclass) requested, and disposes the previous Page instance. This happens even when navigating back to a previously visited page or when the new page type is the same as the previous page type. Apps that involve frequent navigation to the same pages can cache and reuse the page instances to make navigation more efficient. To do this, set the Frame.CacheSize property to specify how many pages to cache. For each page type that you want to cache, you must also set the NavigationCacheMode property to either Enabled or Required. Pages with a Required cache mode are cached regardless of the CacheSize value, and do not count against the CacheSize total.

You can override the page OnNavigatedTo, OnNavigatingFrom, and OnNavigatedFrom methods to perform tasks such as initializing and saving the page state. OnNavigatingFrom can be used to cancel a navigation by setting the Cancel property in the event data from your handler.

For more info, see Implement navigation between two pages.

-examples

These steps outline how to add a Page to a WinUI 3 project, and navigate to it. For a more complete walkthrough, see Implement navigation between two pages.

1. In Visual Studio, create a new C# project from the Blank App, Packaged (WinUI 3 in Desktop) project template. Remove any example code that's included in the template from the MainWindow.xaml and MainWindow.xaml.cs files.

2. Add a new item to the project (WinUI > Blank Page (WinUI 3)) named MainPage.xaml.

3. Then, in App.xaml.cs, edit the OnLaunched method override so that it looks like the code listing below. The code shows how the content of the app's main window is set to a new Frame, which is then navigated to the MainPage that you just added.

protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    m_window = new MainWindow();

    // Create a Frame to act as the navigation context.
    Frame rootFrame = new Frame();

    rootFrame.NavigationFailed += OnNavigationFailed;

    // Place the frame in the current Window
    m_window.Content = rootFrame;

    rootFrame.Navigate(typeof(MainPage), args.Arguments);

    m_window.Activate();
}

-see-also

Frame, UserControl, Navigation design basics, Implement navigation between two pages