Stone_Red/docs-desktop
1
0
Fork 0
mirror of https://github.com/Stone-Red-Code/docs-desktop.git synced 2026-09-05 07:56:11 +02:00
Code Issues Packages Projects Releases Wiki Activity

Initial WPF content migrated (#17)

Browse Source 
* Reset branch for WPF changes

* Convert BMP to PNG; fix link-out-of-scope err

* Add snippets for WPF... 6794 files!!!!

* Add missing snippets

* update file updated between migration

* Fix paths to include

* update breadcrumb and toc

* fix index links

* fix index links

* fix index links

* fix markdown
This commit is contained in:
Andy De George
2020-09-04 09:46:28 -07:00
committed by GitHub
parent dba50d6bf1
commit da363692ff
8215 changed files with 508408 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dotnet-desktop-guide/framework/wpf/app-development/application-management-overview.md
+391
View File
@@ -0,0 +1,391 @@
---
title: "Application Management Overview"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "application management [WPF]"
ms.assetid: 32b1c054-5aca-423b-b4b5-ed8dc4dc637d
---
# Application Management Overview
All applications tend to share a common set of functionality that applies to application implementation and management. This topic provides an overview of the functionality in the <xref:System.Windows.Application> class for creating and managing applications.
## The Application Class
In WPF, common application-scoped functionality is encapsulated in the <xref:System.Windows.Application> class. The <xref:System.Windows.Application> class includes the following functionality:
- Tracking and interacting with application lifetime.
- Retrieving and processing command-line parameters.
- Detecting and responding to unhandled exceptions.
- Sharing application-scope properties and resources.
- Managing windows in standalone applications.
- Tracking and managing navigation.
<a name="The_Application_Class"></a>
## How to Perform Common Tasks Using the Application Class
If you are not interested in all of the details of the <xref:System.Windows.Application> class, the following table lists some of the common tasks for <xref:System.Windows.Application> and how to accomplish them. By viewing the related API and topics, you can find more information and sample code.
|Task|Approach|
|----------|--------------|
|Get an object that represents the current application|Use the <xref:System.Windows.Application.Current%2A?displayProperty=nameWithType> property.|
|Add a startup screen to an application|See [Add a Splash Screen to a WPF Application](how-to-add-a-splash-screen-to-a-wpf-application.md).|
|Start an application|Use the <xref:System.Windows.Application.Run%2A?displayProperty=nameWithType> method.|
|Stop an application|Use the <xref:System.Windows.Application.Shutdown%2A> method of the <xref:System.Windows.Application.Current%2A?displayProperty=nameWithType> object.|
|Get arguments from the command line|Handle the <xref:System.Windows.Application.Startup?displayProperty=nameWithType> event and use the <xref:System.Windows.StartupEventArgs.Args%2A?displayProperty=nameWithType> property. For an example, see the <xref:System.Windows.Application.Startup?displayProperty=nameWithType> event.|
|Get and set the application exit code|Set the <xref:System.Windows.ExitEventArgs.ApplicationExitCode%2A?displayProperty=nameWithType> property in the <xref:System.Windows.Application.Exit?displayProperty=nameWithType> event handler or call the <xref:System.Windows.Application.Shutdown%2A> method and pass in an integer.|
|Detect and respond to unhandled exceptions|Handle the <xref:System.Windows.Application.DispatcherUnhandledException> event.|
|Get and set application-scoped resources|Use the <xref:System.Windows.Application.Resources%2A?displayProperty=nameWithType> property.|
|Use an application-scope resource dictionary|See [Use an Application-Scope Resource Dictionary](how-to-use-an-application-scope-resource-dictionary.md).|
|Get and set application-scoped properties|Use the <xref:System.Windows.Application.Properties%2A?displayProperty=nameWithType> property.|
|Get and save an application's state|See [Persist and Restore Application-Scope Properties Across Application Sessions](persist-and-restore-application-scope-properties.md).|
|Manage non-code data files, including resource files, content files, and site-of-origin files.|See [WPF Application Resource, Content, and Data Files](wpf-application-resource-content-and-data-files.md).|
|Manage windows in standalone applications|See [WPF Windows Overview](wpf-windows-overview.md).|
|Track and manage navigation|See [Navigation Overview](navigation-overview.md).|
<a name="The_Application_Definition"></a>
## The Application Definition
To utilize the functionality of the <xref:System.Windows.Application> class, you must implement an application definition. A WPF application definition is a class that derives from <xref:System.Windows.Application> and is configured with a special MSBuild setting.
### Implementing an Application Definition
A typical WPF application definition is implemented using both markup and code-behind. This allows you to use markup to declaratively set application properties, resources, and register events, while handling events and implementing application-specific behavior in code-behind.
The following example shows how to implement an application definition using both markup and code-behind:
[!code-xaml[ApplicationSnippets#ApplicationXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationSnippets/CSharp/App.xaml#applicationxaml)]
[!code-csharp[ApplicationSnippets#ApplicationCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationSnippets/CSharp/App.xaml.cs#applicationcodebehind)]
[!code-vb[ApplicationSnippets#ApplicationCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationSnippets/visualbasic/application.xaml.vb#applicationcodebehind)]
To allow a markup file and code-behind file to work together, the following needs to happen:
- In markup, the `Application` element must include the `x:Class` attribute. When the application is built, the existence of `x:Class` in the markup file causes MSBuild to create a `partial` class that derives from <xref:System.Windows.Application> and has the name that is specified by the `x:Class` attribute. This requires the addition of an XML namespace declaration for the XAML schema (`xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"`).
- In code-behind, the class must be a `partial` class with the same name that is specified by the `x:Class` attribute in markup and must derive from <xref:System.Windows.Application>. This allows the code-behind file to be associated with the `partial` class that is generated for the markup file when the application is built (see [Building a WPF Application](building-a-wpf-application-wpf.md)).
> [!NOTE]
> When you create a new WPF Application project or WPF Browser Application project using Visual Studio, an application definition is included by default and is defined using both markup and code-behind.
This code is the minimum that is required to implement an application definition. However, an additional MSBuild configuration needs to be made to the application definition before building and running the application.
### Configuring the Application Definition for MSBuild
Standalone applications and XAML browser applications (XBAPs) require the implementation of a certain level of infrastructure before they can run. The most important part of this infrastructure is the entry point. When an application is launched by a user, the operating system calls the entry point, which is a well-known function for starting applications.
Traditionally, developers have needed to write some or all of this code for themselves, depending on the technology. However, WPF generates this code for you when the markup file of your application definition is configured as an MSBuild `ApplicationDefinition` item, as shown in the following MSBuild project file:
```xml
<Project
DefaultTargets="Build"
xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
...
<ApplicationDefinition Include="App.xaml" />
<Compile Include="App.xaml.cs" />
...
</Project>
```
Because the code-behind file contains code, it is marked as an MSBuild `Compile` item, as is normal.
The application of these MSBuild configurations to the markup and code-behind files of an application definition causes MSBuild to generate code like the following:
[!code-csharp[auto-generated-code](~/samples/snippets/csharp/VS_Snippets_Wpf/AppDefAugSnippets/CSharp/App.cs)]
[!code-vb[auto-generated-code](~/samples/snippets/visualbasic/VS_Snippets_Wpf/AppDefAugSnippets/VisualBasic/App.vb)]
The resulting code augments your application definition with additional infrastructure code, which includes the entry-point method `Main`. The <xref:System.STAThreadAttribute> attribute is applied to the `Main` method to indicate that the main UI thread for the WPF application is an STA thread, which is required for WPF applications. When called, `Main` creates a new instance of `App` before calling the `InitializeComponent` method to register the events and set the properties that are implemented in markup. Because `InitializeComponent` is generated for you, you don't need to explicitly call `InitializeComponent` from an application definition like you do for <xref:System.Windows.Controls.Page> and <xref:System.Windows.Window> implementations. Finally, the <xref:System.Windows.Application.Run%2A> method is called to start the application.
<a name="Getting_the_Current_Application"></a>
## Getting the Current Application
Because the functionality of the <xref:System.Windows.Application> class are shared across an application, there can be only one instance of the <xref:System.Windows.Application> class per <xref:System.AppDomain>. To enforce this, the <xref:System.Windows.Application> class is implemented as a singleton class (see [Implementing Singleton in C#](https://docs.microsoft.com/previous-versions/msp-n-p/ff650316(v=pandp.10))), which creates a single instance of itself and provides shared access to it with the `static`<xref:System.Windows.Application.Current%2A> property.
The following code shows how to acquire a reference to the <xref:System.Windows.Application> object for the current <xref:System.AppDomain>.
[!code-csharp[ApplicationManagementOverviewSnippets#GetCurrentAppCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationManagementOverviewSnippets/CSharp/MainWindow.xaml.cs#getcurrentappcode)]
[!code-vb[ApplicationManagementOverviewSnippets#GetCurrentAppCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationManagementOverviewSnippets/VisualBasic/MainWindow.xaml.vb#getcurrentappcode)]
<xref:System.Windows.Application.Current%2A> returns a reference to an instance of the <xref:System.Windows.Application> class. If you want a reference to your <xref:System.Windows.Application> derived class you must cast the value of the <xref:System.Windows.Application.Current%2A> property, as shown in the following example.
[!code-csharp[ApplicationManagementOverviewSnippets#GetSTCurrentAppCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationManagementOverviewSnippets/CSharp/MainWindow.xaml.cs#getstcurrentappcode)]
[!code-vb[ApplicationManagementOverviewSnippets#GetSTCurrentAppCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationManagementOverviewSnippets/VisualBasic/MainWindow.xaml.vb#getstcurrentappcode)]
You can inspect the value of <xref:System.Windows.Application.Current%2A> at any point in the lifetime of an <xref:System.Windows.Application> object. However, you should be careful. After the <xref:System.Windows.Application> class is instantiated, there is a period during which the state of the <xref:System.Windows.Application> object is inconsistent. During this period, <xref:System.Windows.Application> is performing the various initialization tasks that are required by your code to run, including establishing application infrastructure, setting properties, and registering events. If you try to use the <xref:System.Windows.Application> object during this period, your code may have unexpected results, particularly if it depends on the various <xref:System.Windows.Application> properties being set.
When <xref:System.Windows.Application> completes its initialization work, its lifetime truly begins.
<a name="Application_Lifetime"></a>
## Application Lifetime
The lifetime of a WPF application is marked by several events that are raised by <xref:System.Windows.Application> to let you know when your application has started, has been activated and deactivated, and has been shut down.
<a name="Splash_Screen"></a>
### Splash Screen
Starting in the .NET Framework 3.5 SP1, you can specify an image to be used in a startup window, or *splash screen*. The <xref:System.Windows.SplashScreen> class makes it easy to display a startup window while your application is loading. The <xref:System.Windows.SplashScreen> window is created and shown before <xref:System.Windows.Application.Run%2A> is called. For more information, see [Application Startup Time](../advanced/application-startup-time.md) and [Add a Splash Screen to a WPF Application](how-to-add-a-splash-screen-to-a-wpf-application.md).
<a name="Starting_an_Application"></a>
### Starting an Application
After <xref:System.Windows.Application.Run%2A> is called and the application is initialized, the application is ready to run. This moment is signified when the <xref:System.Windows.Application.Startup> event is raised:
[!code-csharp[Startup-event](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationStartupSnippets/CSharp/App.xaml.cs?range=3-11,31-33)]
[!code-vb[Startup-event](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationStartupSnippets/visualbasic/application.xaml.vb?range=5-11,30-32)]
At this point in an application's lifetime, the most common thing to do is to show a UI.
<a name="Showing_a_User_Interface"></a>
### Showing a User Interface
Most standalone Windows applications open a <xref:System.Windows.Window> when they begin running. The <xref:System.Windows.Application.Startup> event handler is one location from which you can do this, as demonstrated by the following code.
[!code-xaml[AppShowWindowHardSnippets#StartupEventMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/AppShowWindowHardSnippets/CSharp/App.xaml#startupeventmarkup)]
[!code-csharp[AppShowWindowHardSnippets#StartupEventCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/AppShowWindowHardSnippets/CSharp/App.xaml.cs#startupeventcodebehind)]
[!code-vb[AppShowWindowHardSnippets#StartupEventCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/AppShowWindowHardSnippets/VisualBasic/Application.xaml.vb#startupeventcodebehind)]
> [!NOTE]
> The first <xref:System.Windows.Window> to be instantiated in a standalone application becomes the main application window by default. This <xref:System.Windows.Window> object is referenced by the <xref:System.Windows.Application.MainWindow%2A?displayProperty=nameWithType> property. The value of the <xref:System.Windows.Application.MainWindow%2A> property can be changed programmatically if a different window than the first instantiated <xref:System.Windows.Window> should be the main window.
When an XBAP first starts, it will most likely navigate to a <xref:System.Windows.Controls.Page>. This is shown in the following code.
[!code-xaml[XBAPAppStartupSnippets#StartupXBAPMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/XBAPAppStartupSnippets/CSharp/App.xaml#startupxbapmarkup)]
[!code-csharp[XBAPAppStartupSnippets#StartupXBAPCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/XBAPAppStartupSnippets/CSharp/App.xaml.cs#startupxbapcodebehind)]
[!code-vb[XBAPAppStartupSnippets#StartupXBAPCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/XBAPAppStartupSnippets/VisualBasic/Application.xaml.vb#startupxbapcodebehind)]
If you handle <xref:System.Windows.Application.Startup> to only open a <xref:System.Windows.Window> or navigate to a <xref:System.Windows.Controls.Page>, you can set the `StartupUri` attribute in markup instead.
The following example shows how to use the <xref:System.Windows.Application.StartupUri%2A> from a standalone application to open a <xref:System.Windows.Window>.
[!code-xaml[ApplicationManagementOverviewSnippets#OverviewStartupUriMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationManagementOverviewSnippets/CSharp/App.xaml#overviewstartupurimarkup)]
The following example shows how to use <xref:System.Windows.Application.StartupUri%2A> from an XBAP to navigate to a <xref:System.Windows.Controls.Page>.
[!code-xaml[PageSnippets#XBAPStartupUriMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/PageSnippets/CSharp/App.xaml#xbapstartupurimarkup)]
This markup has the same effect as the previous code for opening a window.
> [!NOTE]
> For more information on navigation, see [Navigation Overview](navigation-overview.md).
You need to handle the <xref:System.Windows.Application.Startup> event to open a <xref:System.Windows.Window> if you need to instantiate it using a non-parameterless constructor, or you need to set its properties or subscribe to its events before showing it, or you need to process any command-line arguments that were supplied when the application was launched.
<a name="Processing_Command_Line_Arguments"></a>
### Processing Command-Line Arguments
In Windows, standalone applications can be launched from either a command prompt or the desktop. In both cases, command-line arguments can be passed to the application. The following example shows an application that is launched with a single command-line argument, "/StartMinimized":
`wpfapplication.exe /StartMinimized`
During application initialization, WPF retrieves the command-line arguments from the operating system and passes them to the <xref:System.Windows.Application.Startup> event handler via the <xref:System.Windows.StartupEventArgs.Args%2A> property of the <xref:System.Windows.StartupEventArgs> parameter. You can retrieve and store the command-line arguments using code like the following.
[!code-xaml[ApplicationStartupSnippets#HandleStartupXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationStartupSnippets/CSharp/App.xaml#handlestartupxaml)]
[!code-csharp[ApplicationStartupSnippets#HandleStartupCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationStartupSnippets/CSharp/App.xaml.cs#handlestartupcodebehind)]
[!code-vb[ApplicationStartupSnippets#HandleStartupCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationStartupSnippets/visualbasic/application.xaml.vb#handlestartupcodebehind)]
The code handles <xref:System.Windows.Application.Startup> to check whether the **/StartMinimized** command-line argument was provided; if so, it opens the main window with a <xref:System.Windows.WindowState> of <xref:System.Windows.WindowState.Minimized>. Note that because the <xref:System.Windows.Window.WindowState%2A> property must be set programmatically, the main <xref:System.Windows.Window> must be opened explicitly in code.
XBAPs cannot retrieve and process command-line arguments because they are launched using ClickOnce deployment (see [Deploying a WPF Application](deploying-a-wpf-application-wpf.md)). However, they can retrieve and process query string parameters from the URLs that are used to launch them.
<a name="Application_Activation_and_Deactivation"></a>
### Application Activation and Deactivation
Windows allows users to switch between applications. The most common way is to use the ALT+TAB key combination. An application can only be switched to if it has a visible <xref:System.Windows.Window> that a user can select. The currently selected <xref:System.Windows.Window> is the *active window* (also known as the *foreground window*) and is the <xref:System.Windows.Window> that receives user input. The application with the active window is the *active application* (or *foreground application*). An application becomes the active application in the following circumstances:
- It is launched and shows a <xref:System.Windows.Window>.
- A user switches from another application by selecting a <xref:System.Windows.Window> in the application.
You can detect when an application becomes active by handling the <xref:System.Windows.Application.Activated?displayProperty=nameWithType> event.
Likewise, an application can become inactive in the following circumstances:
- A user switches to another application from the current one.
- When the application shuts down.
You can detect when an application becomes inactive by handling the <xref:System.Windows.Application.Deactivated?displayProperty=nameWithType> event.
The following code shows how to handle the <xref:System.Windows.Application.Activated> and <xref:System.Windows.Application.Deactivated> events to determine whether an application is active.
[!code-xaml[ApplicationActivationSnippets#DetectActivationStateXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationActivationSnippets/CSharp/App.xaml#detectactivationstatexaml)]
[!code-csharp[ApplicationActivationSnippets#DetectActivationStateCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationActivationSnippets/CSharp/App.xaml.cs#detectactivationstatecodebehind)]
[!code-vb[ApplicationActivationSnippets#DetectActivationStateCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationActivationSnippets/visualbasic/application.xaml.vb#detectactivationstatecodebehind)]
A <xref:System.Windows.Window> can also be activated and deactivated. See <xref:System.Windows.Window.Activated?displayProperty=nameWithType> and <xref:System.Windows.Window.Deactivated?displayProperty=nameWithType> for more information.
> [!NOTE]
> Neither <xref:System.Windows.Application.Activated?displayProperty=nameWithType> nor <xref:System.Windows.Application.Deactivated?displayProperty=nameWithType> is raised for XBAPs.
<a name="Application_Shutdown"></a>
### Application Shutdown
The life of an application ends when it is shut down, which can occur for the following reasons:
- A user closes every <xref:System.Windows.Window>.
- A user closes the main <xref:System.Windows.Window>.
- A user ends the Windows session by logging off or shutting down.
- An application-specific condition has been met.
To help you manage application shutdown, <xref:System.Windows.Application> provides the <xref:System.Windows.Application.Shutdown%2A> method, the <xref:System.Windows.Application.ShutdownMode%2A> property, and the <xref:System.Windows.Application.SessionEnding> and <xref:System.Windows.Application.Exit> events.
> [!NOTE]
> <xref:System.Windows.Application.Shutdown%2A> can only be called from applications that have <xref:System.Security.Permissions.UIPermission>. Standalone WPF applications always have this permission. However, XBAPs running in the Internet zone partial-trust security sandbox do not.
#### Shutdown Mode
Most applications shut down either when all the windows are closed or when the main window is closed. Sometimes, however, other application-specific conditions may determine when an application shuts down. You can specify the conditions under which your application will shut down by setting <xref:System.Windows.Application.ShutdownMode%2A> with one of the following <xref:System.Windows.ShutdownMode> enumeration values:
- <xref:System.Windows.ShutdownMode.OnLastWindowClose>
- <xref:System.Windows.ShutdownMode.OnMainWindowClose>
- <xref:System.Windows.ShutdownMode.OnExplicitShutdown>
The default value of <xref:System.Windows.Application.ShutdownMode%2A> is <xref:System.Windows.ShutdownMode.OnLastWindowClose>, which means that an application automatically shuts down when the last window in the application is closed by the user. However, if your application should be shut down when the main window is closed, WPF automatically does that if you set <xref:System.Windows.Application.ShutdownMode%2A> to <xref:System.Windows.ShutdownMode.OnMainWindowClose>. This is shown in the following example.
[!code-xaml[ApplicationShutdownModeSnippets#OnMainWindowCloseMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationShutdownModeSnippets/CS/Page1.xaml#onmainwindowclosemarkup)]
When you have application-specific shutdown conditions, you set <xref:System.Windows.Application.ShutdownMode%2A> to <xref:System.Windows.ShutdownMode.OnExplicitShutdown>. In this case, it is your responsibility to shut an application down by explicitly calling the <xref:System.Windows.Application.Shutdown%2A> method; otherwise, your application will continue running even if all the windows are closed. Note that <xref:System.Windows.Application.Shutdown%2A> is called implicitly when the <xref:System.Windows.Application.ShutdownMode%2A> is either <xref:System.Windows.ShutdownMode.OnLastWindowClose> or <xref:System.Windows.ShutdownMode.OnMainWindowClose>.
> [!NOTE]
> <xref:System.Windows.Application.ShutdownMode%2A> can be set from an XBAP, but it is ignored; an XBAP is always shut down when it is navigated away from in a browser or when the browser that hosts the XBAP is closed. For more information, see [Navigation Overview](navigation-overview.md).
#### Session Ending
The shutdown conditions that are described by the <xref:System.Windows.Application.ShutdownMode%2A> property are specific to an application. In some cases, though, an application may shut down as a result of an external condition. The most common external condition occurs when a user ends the Windows session by the following actions:
- Logging off
- Shutting down
- Restarting
- Hibernating
To detect when a Windows session ends, you can handle the <xref:System.Windows.Application.SessionEnding> event, as illustrated in the following example.
[!code-xaml[ApplicationSessionEndingSnippets#HandlingSessionEndingXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationSessionEndingSnippets/CSharp/App.xaml#handlingsessionendingxaml)]
[!code-csharp[ApplicationSessionEndingSnippets#HandlingSessionEndingCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationSessionEndingSnippets/CSharp/App.xaml.cs#handlingsessionendingcodebehind)]
[!code-vb[ApplicationSessionEndingSnippets#HandlingSessionEndingCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationSessionEndingSnippets/visualbasic/application.xaml.vb#handlingsessionendingcodebehind)]
In this example, the code inspects the <xref:System.Windows.SessionEndingCancelEventArgs.ReasonSessionEnding%2A> property to determine how the Windows session is ending. It uses this value to display a confirmation message to the user. If the user does not want the session to end, the code sets <xref:System.ComponentModel.CancelEventArgs.Cancel%2A> to `true` to prevent the Windows session from ending.
> [!NOTE]
> <xref:System.Windows.Application.SessionEnding> is not raised for XBAPs.
#### Exit
When an application shuts down, it may need to perform some final processing, such as persisting application state. For these situations, you can handle the <xref:System.Windows.Application.Exit> event, as the `App_Exit` event handler does in the following example. It is defined as an event handler in the *App.xaml* file. Its implementation is highlighted in the *App.xaml.cs* and *Application.xaml.vb* files.
[!code-xaml[Defining-the-Exit-event-handler](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOApplicationModelSnippets/CSharp/App.xaml?highlight=1-7)]
[!code-csharp[Handling-the-Exit-event](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOApplicationModelSnippets/CSharp/App.xaml.cs?highlight=42-55)]
[!code-vb[Handling-the-Exit-event](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOApplicationModelSnippets/visualbasic/application.xaml.vb?highlight=34-45)]
For the complete example, see [Persist and Restore Application-Scope Properties Across Application Sessions](persist-and-restore-application-scope-properties.md).
<xref:System.Windows.Application.Exit> can be handled by both standalone applications and XBAPs. For XBAPs, <xref:System.Windows.Application.Exit> is raised when in the following circumstances:
- An XBAP is navigated away from.
- In Internet Explorer, when the tab that is hosting the XBAP is closed.
- When the browser is closed.
#### Exit Code
Applications are mostly launched by the operating system in response to a user request. However, an application can be launched by another application to perform some specific task. When the launched application shuts down, the launching application may want to know the condition under which the launched application shut down. In these situations, Windows allows applications to return an application exit code on shutdown. By default, WPF applications return an exit code value of 0.
> [!NOTE]
> When you debug from Visual Studio, the application exit code is displayed in the **Output** window when the application shuts down, in a message that looks like the following:
>
> `The program '[5340] AWPFApp.vshost.exe: Managed' has exited with code 0 (0x0).`
>
> You open the **Output** window by clicking **Output** on the **View** menu.
To change the exit code, you can call the <xref:System.Windows.Application.Shutdown%28System.Int32%29> overload, which accepts an integer argument to be the exit code:
[!code-csharp[ApplicationExitSnippets#AppExitCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationExitSnippets/CSharp/MainWindow.xaml.cs#appexitcode)]
[!code-vb[ApplicationExitSnippets#AppExitCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationExitSnippets/visualbasic/mainwindow.xaml.vb#appexitcode)]
You can detect the value of the exit code, and change it, by handling the <xref:System.Windows.Application.Exit> event. The <xref:System.Windows.Application.Exit> event handler is passed an <xref:System.Windows.ExitEventArgs> which provides access to the exit code with the <xref:System.Windows.ExitEventArgs.ApplicationExitCode%2A> property. For more information, see <xref:System.Windows.Application.Exit>.
> [!NOTE]
> You can set the exit code in both standalone applications and XBAPs. However, the exit code value is ignored for XBAPs.
<a name="Unhandled_Exceptions"></a>
### Unhandled Exceptions
Sometimes an application may shut down under abnormal conditions, such as when an unanticipated exception is thrown. In this case, the application may not have the code to detect and process the exception. This type of exception is an unhandled exception; a notification similar to that shown in the following figure is displayed before the application is closed.
![Screenshot that shows an unhandled exception notification.](./media/application-management-overview/unhandled-exception-notification.png)
From the user experience perspective, it is better for an application to avoid this default behavior by doing some or all of the following:
- Displaying user-friendly information.
- Attempting to keep an application running.
- Recording detailed, developer-friendly exception information in the Windows event log.
Implementing this support depends on being able to detect unhandled exceptions, which is what the <xref:System.Windows.Application.DispatcherUnhandledException> event is raised for.
[!code-xaml[detecting-unhandled-exceptions](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationDispatcherUnhandledExceptionSnippets/CSharp/App.xaml#handledispatcherunhandledexceptionxaml)]
[!code-csharp[code-to-detect-unhandled-exceptions](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationDispatcherUnhandledExceptionSnippets/CSharp/App.xaml.cs)]
[!code-vb[code-to-detect-unhandled-exceptions](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationDispatcherUnhandledExceptionSnippets/visualbasic/application.xaml.vb)]
The <xref:System.Windows.Application.DispatcherUnhandledException> event handler is passed a <xref:System.Windows.Threading.DispatcherUnhandledExceptionEventArgs> parameter that contains contextual information regarding the unhandled exception, including the exception itself (<xref:System.Windows.Threading.DispatcherUnhandledExceptionEventArgs.Exception%2A?displayProperty=nameWithType>). You can use this information to determine how to handle the exception.
When you handle <xref:System.Windows.Application.DispatcherUnhandledException>, you should set the <xref:System.Windows.Threading.DispatcherUnhandledExceptionEventArgs.Handled%2A?displayProperty=nameWithType> property to `true`; otherwise, WPF still considers the exception to be unhandled and reverts to the default behavior described earlier. If an unhandled exception is raised and either the <xref:System.Windows.Application.DispatcherUnhandledException> event is not handled, or the event is handled and <xref:System.Windows.Threading.DispatcherUnhandledExceptionEventArgs.Handled%2A> is set to `false`, the application shuts down immediately. Furthermore, no other <xref:System.Windows.Application> events are raised. Consequently, you need to handle <xref:System.Windows.Application.DispatcherUnhandledException> if your application has code that must run before the application shuts down.
Although an application may shut down as a result of an unhandled exception, an application usually shuts down in response to a user request, as discussed in the next section.
<a name="Application_Lifetime_Events"></a>
### Application Lifetime Events
Standalone applications and XBAPs don't have exactly the same lifetimes. The following figure illustrates the key events in the lifetime of a standalone application and shows the sequence in which they are raised.
![Standalone Application &#45; Application Object Events](./media/applicationmodeloverview-applicationobjectevents.png "ApplicationModelOverview_ApplicationObjectEvents")
Likewise, the following figure illustrates the key events in the lifetime of an XBAP, and shows the sequence in which they are raised.
![XBAP &#45; Application Object Events](./media/applicationmodeloverview-applicationobjectevents-xbap.png "ApplicationModelOverview_ApplicationObjectEvents_xbap")
## See also
- <xref:System.Windows.Application>
- [WPF Windows Overview](wpf-windows-overview.md)
- [Navigation Overview](navigation-overview.md)
- [WPF Application Resource, Content, and Data Files](wpf-application-resource-content-and-data-files.md)
- [Pack URIs in WPF](pack-uris-in-wpf.md)
- [Application Model: How-to Topics](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/ms749013(v=vs.100))
- [Application Development](index.md)
dotnet-desktop-guide/framework/wpf/app-development/build-and-deploy-how-to-topics.md
+29
View File
@@ -0,0 +1,29 @@
---
title: "Build and Deploy How-to Topics"
ms.date: "03/30/2017"
f1_keywords:
- "AutoGeneratedOrientationPage"
helpviewer_keywords:
- "WPF application [WPF], building"
- "WPF application [WPF], deploying"
ms.assetid: 88952ad2-5b74-48ca-a4c5-3f4fbb53ce12
---
# Build and deploy how-to topics
The following topics show how to create project files for the various [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] application types.
## In this section
- [Configure IIS 5.0 and IIS 6.0 to Deploy WPF Applications](how-to-configure-iis-5-0-and-iis-6-0-to-deploy-wpf-applications.md)
- [Configure Visual Studio to Debug a XAML Browser Application to Call a Web Service](configure-vs-to-debug-a-xaml-browser-to-call-a-web-service.md)
- [Detect Whether the .NET Framework 3.0 Is Installed](how-to-detect-whether-the-net-framework-3-0-is-installed.md)
- [Detect Whether the .NET Framework 3.5 Is Installed](how-to-detect-whether-the-net-framework-3-5-is-installed.md)
- [Detect Whether the WPF Plug-In for Firefox Is Installed](how-to-detect-whether-the-wpf-plug-in-for-firefox-is-installed.md)
## Related sections
- [Building a WPF Application](building-a-wpf-application-wpf.md)
- [Deploying a WPF Application](deploying-a-wpf-application-wpf.md)
- [Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md)
- [How to: Create a New WPF Browser Application Project](https://docs.microsoft.com/previous-versions/visualstudio/visual-studio-2010/bb628663(v=vs.100))
- [Determine the Installed Version of WPF (.NET Framework 3.5)](https://docs.microsoft.com/previous-versions/dotnet/netframework-3.5/aa349641(v=vs.90))
dotnet-desktop-guide/framework/wpf/app-development/building-a-wpf-application-wpf.md
+188
View File
@@ -0,0 +1,188 @@
---
title: "Compile an app"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "WPF application [WPF], building"
ms.assetid: a58696fd-bdad-4b55-9759-136dfdf8b91c
---
# Compile a WPF Application
Windows Presentation Foundation (WPF) applications can be built as .NET Framework executables (.exe), libraries (.dll), or a combination of both types of assemblies. This topic introduces how to build WPF applications and describes the key steps in the build process.
<a name="Building_a_WPF_Application_using_Command_Line"></a>
## Building a WPF Application
A WPF application can be compiled in the following ways:
- Command-line. The application must contain only code (no XAML) and an application definition file. For more information, see [Command-line Building With csc.exe](/dotnet/csharp/language-reference/compiler-options/command-line-building-with-csc-exe) or [Building from the Command Line (Visual Basic)](/dotnet/visual-basic/reference/command-line-compiler/building-from-the-command-line).
- Microsoft Build Engine (MSBuild). In addition to the code and XAML files, the application must contain an MSBuild project file. For more information, see "MSBuild".
- Visual Studio. Visual Studio is an integrated development environment that compiles WPF applications with MSBuild and includes a visual designer for creating UI. For more information, see [Write and manage code using Visual Studio](/visualstudio/ide/index-writing-code) and [Design XAML in Visual Studio](/visualstudio/xaml-tools/designing-xaml-in-visual-studio).
<a name="The_Windows_Presentation_Foundation_Build_Pipeline"></a>
## WPF Build Pipeline
When a WPF project is built, the combination of language-specific and WPF-specific targets are invoked. The process of executing these targets is called the build pipeline, and the key steps are illustrated by the following figure.
![WPF build process](./media/wpfbuildsystem-figure1.png "WPFBuildSystem_Figure1")
<a name="Pre_Build_Initializations"></a>
### Pre-Build Initializations
Before building, MSBuild determines the location of important tools and libraries, including the following:
- The .NET Framework.
- The Windows SDK directories.
- The location of WPF reference assemblies.
- The property for the assembly search paths.
The first location where MSBuild searches for assemblies is the reference assembly directory (%ProgramFiles%\Reference Assemblies\Microsoft\Framework\v3.0\\). During this step, the build process also initializes the various properties and item groups and performs any required cleanup work.
<a name="Resolving_references"></a>
### Resolving References
The build process locates and binds the assemblies required to build the application project. This logic is contained in the `ResolveAssemblyReference` task. All assemblies declared as `Reference` in the project file are provided to the task along with information on the search paths and metadata on assemblies already installed on the system. The task looks up assemblies and uses the installed assembly's metadata to filter out those core WPF assemblies that need not show up in the output manifests. This is done to avoid redundant information in the ClickOnce manifests. For example, since PresentationFramework.dll can be considered representative of an application built on and for WPF, and since all WPF assemblies exist at the same location on every machine that has the .NET Framework installed, there's no need to include all information on all .NET Framework reference assemblies in the manifests.
<a name="Markup_Compilation___Pass_1"></a>
### Markup Compilation—Pass 1
In this step, [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files are parsed and compiled so that the runtime does not spend time parsing XML and validating property values. The compiled [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file is pre-tokenized so that, at run time, loading it should be much faster than loading a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file.
During this step, the following activities take place for every [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file that is a `Page` build item:
1. The [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file is parsed by the markup compiler.
2. A compiled representation is created for that [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] and copied to the obj\Release folder.
3. A CodeDOM representation of a new partial class is created and copied to the obj\Release folder.
In addition, a language-specific code file is generated for every [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file. For example, for a Page1.xaml page in a Visual Basic project, a Page1.g.vb is generated; for a Page1.xaml page in a C# project, a Page1.g.cs is generated. The ".g" in the file name indicates the file is generated code that has a partial class declaration for the top-level element of the markup file (such as `Page` or `Window`). The class is declared with the `partial` modifier in C# (`Extends` in Visual Basic) to indicate there is another declaration for the class elsewhere, usually in the code-behind file Page1.xaml.cs.
The partial class extends from the appropriate base class (such as <xref:System.Windows.Controls.Page> for a page) and implements the <xref:System.Windows.Markup.IComponentConnector?displayProperty=nameWithType> interface. The <xref:System.Windows.Markup.IComponentConnector> interface has methods to initialize a component and connect names and events on elements in its content. Consequently, the generated code file has a method implementation like the following:
```csharp
public void InitializeComponent() {
if (_contentLoaded) {
return;
}
_contentLoaded = true;
System.Uri resourceLocater =
new System.Uri(
"window1.xaml",
System.UriKind.RelativeOrAbsolute);
System.Windows.Application.LoadComponent(this, resourceLocater);
}
```
```vb
Public Sub InitializeComponent() _
If _contentLoaded Then
Return
End If
_contentLoaded = True
Dim resourceLocater As System.Uri = _
New System.Uri("mainwindow.xaml", System.UriKind.Relative)
System.Windows.Application.LoadComponent(Me, resourceLocater)
End Sub
```
By default, markup compilation runs in the same <xref:System.AppDomain> as the MSBuild engine. This provides significant performance gains. This behavior can be toggled with the `AlwaysCompileMarkupFilesInSeparateDomain` property. This has the advantage of unloading all reference assemblies by unloading the separate <xref:System.AppDomain>.
<a name="Pass_2_of_Markup_Compilation"></a>
### Markup Compilation—Pass 2
Not all [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages are compiled at during pass 1 of markup compilation. [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files that have locally defined type references (references to types defined in code elsewhere in the same project) are exempt from compilation at this time. This is because those locally defined types exist only in source and have not yet been compiled. In order to determine this, the parser uses heuristics that involve looking for items such as `x:Name` in the markup file. When such an instance is found, that markup file’s compilation is postponed until the code files have been compiled, after which, the second markup compilation pass processes these files.
<a name="File_Classification"></a>
### File Classification
The build process puts output files into different resource groups based on which application assembly they will be placed in. In a typical nonlocalized application, all data files marked as `Resource` are placed in the main assembly (executable or library). When `UICulture` is set in the project, all compiled [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files and those resources specifically marked as language-specific are placed in the satellite resource assembly. Furthermore, all language-neutral resources are placed in the main assembly. In this step of the build process, that determination is made.
The `ApplicationDefinition`, `Page`, and `Resource` build actions in the project file can be augmented with the `Localizable` metadata (acceptable values are `true` and `false`), which dictates whether the file is language-specific or language-neutral.
<a name="Core_Compilation"></a>
### Core Compilation
The core compile step involves compilation of code files. This is orchestrated by logic in the language-specific targets files Microsoft.CSharp.targets and Microsoft.VisualBasic.targets. If heuristics have determined that a single pass of the markup compiler is sufficient, then the main assembly is generated. However, if one or more [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files in the project have references to locally defined types, then a temporary .dll file is generated so the final application assemblies may be created after the second pass of markup compilation is complete.
<a name="Manifest_generation"></a>
### Manifest Generation
At the end of the build process, after all the application assemblies and content files are ready, the ClickOnce manifests for the application are generated.
The deployment manifest file describes the deployment model: the current version, update behavior, and publisher identity along with digital signature. This manifest is intended to be authored by administrators who handle deployment. The file extension is .xbap (for XAML browser applications (XBAPs)) and .application for installed applications. The former is dictated by the `HostInBrowser` project property and as a result the manifest identifies the application as browser-hosted.
The application manifest (an .exe.manifest file) describes the application assemblies and dependent libraries and lists permissions required by the application. This file is intended to be authored by the application developer. In order to launch a ClickOnce application, a user opens the application's deployment manifest file.
These manifest files are always created for XBAPs. For installed applications, they are not created unless the `GenerateManifests` property is specified in the project file with value `true`.
XBAPs get two additional permissions over and above those permissions assigned to typical Internet zone applications: <xref:System.Security.Permissions.WebBrowserPermission> and <xref:System.Security.Permissions.MediaPermission>. The WPF build system declares those permissions in the application manifest.
<a name="Incremental_Build_Support"></a>
## Incremental Build Support
The WPF build system provides support for incremental builds. It is fairly intelligent about detecting changes made to markup or code, and it compiles only those artifacts affected by the change. The incremental build mechanism uses the following files:
- An $(*AssemblyName*)_MarkupCompiler.Cache file to maintain current compiler state.
- An $(*AssemblyName*)_MarkupCompiler.lref file to cache the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files with references to locally defined types.
The following is a set of rules governing incremental build:
- The file is the smallest unit at which the build system detects change. So, for a code file, the build system cannot tell if a type was changed or if code was added. The same holds for project files.
- The incremental build mechanism must be cognizant that a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page either defines a class or uses other classes.
- If `Reference` entries change, then recompile all pages.
- If a code file changes, recompile all pages with locally defined type references.
- If a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file changes:
- If [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is declared as `Page` in the project: if the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] does not have locally defined type references, recompile that [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] plus all [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages with local references; if the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] has local references, recompile all [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages with local references.
- If [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is declared as `ApplicationDefinition` in the project: recompile all [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages (reason: each [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] has reference to an <xref:System.Windows.Application> type that may have changed).
- If the project file declares a code file as application definition instead of a [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file:
- Check if the `ApplicationClassName` value in the project file has changed (is there a new application type?). If so, recompile the entire application.
- Otherwise, recompile all [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages with local references.
- If a project file changes: apply all preceding rules and see what needs to be recompiled. Changes to the following properties trigger a complete recompile: `AssemblyName`, `IntermediateOutputPath`, `RootNamespace`, and `HostInBrowser`.
The following recompile scenarios are possible:
- The entire application is recompiled.
- Only those [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files that have locally defined type references are recompiled.
- Nothing is recompiled (if nothing in the project has changed).
## See also
- [Deploying a WPF Application](deploying-a-wpf-application-wpf.md)
- [WPF MSBuild Reference](/visualstudio/msbuild/wpf-msbuild-reference)
- [Pack URIs in WPF](pack-uris-in-wpf.md)
- [WPF Application Resource, Content, and Data Files](wpf-application-resource-content-and-data-files.md)
dotnet-desktop-guide/framework/wpf/app-development/building-and-deploying-wpf-applications.md
+34
View File
@@ -0,0 +1,34 @@
---
title: Build and deploy apps
ms.date: "03/30/2017"
f1_keywords:
- "AutoGeneratedOrientationPage"
helpviewer_keywords:
- "building applications [WPF]"
- "deploying applications [WPF]"
- "builds [WPF]"
ms.assetid: 5198df5e-dda0-4ddc-a275-e0a7a4693524
---
# Building and Deploying WPF Applications
The build and deployment model provides the capability to build and deploy applications locally and remotely, including the following:
- MSBuild: the .NET build system located in the Microsoft.Build.Tasks.Windows namespace.
- Resources: working with UI resources.
- ClickOnce Deployment: the .NET publishing and deployment system.
## In This Section
[Building a WPF Application](building-a-wpf-application-wpf.md)
[Deploying a WPF Application](deploying-a-wpf-application-wpf.md)
[How-to Topics](build-and-deploy-how-to-topics.md)
## Reference
MSBuild
## Related Sections
[Application Management Overview](application-management-overview.md)
[Windows in WPF](windows-in-wpf-applications.md)
[Navigation Overview](navigation-overview.md)
[WPF XAML Browser Applications Overview](wpf-xaml-browser-applications-overview.md)
[Hosting](hosting-wpf-applications.md)
dotnet-desktop-guide/framework/wpf/app-development/configure-vs-to-debug-a-xaml-browser-to-call-a-web-service.md
+61
View File
@@ -0,0 +1,61 @@
---
title: "How to: Configure Visual Studio to Debug a XAML Browser Application to Call a Web Service"
ms.date: "03/30/2017"
helpviewer_keywords:
- "debugging XBAPs that call a Web service [WPF]"
- "debugging security exceptions for XBAPs [WPF]"
- "security exception for XBAPs [WPF], debugging"
- "configuring Visual Studio to debug XAML browser applications [WPF]"
- "configuring Visual Studio to debug XBAPs [WPF]"
ms.assetid: fd1db082-a7bb-4c4b-9331-6ad74a0682d0
---
# How to: Configure Visual Studio to Debug a XAML Browser Application to Call a Web Service
XAML browser applications (XBAPs) run within a partial-trust security sandbox that is restricted to the Internet zone set of permissions. This permission set restricts Web service calls to only Web services that are located at the XBAP application's site of origin. When an XBAP is debugged from Visual Studio 2005, though, it is not considered to have the same site of origin as the Web service it references. This causes security exceptions to be raised when the XBAP attempts to call the Web service. However, a Visual Studio 2005 XAML Browser Application (WPF) project can be configured to simulate having the same site of origin as the Web service it calls while debugging. This allows the XBAP to safely call the Web service without causing security exceptions.
## Configuring Visual Studio
To configure Visual Studio 2005 to debug an XBAP that calls a Web service:
1. With a project selected in **Solution Explorer**, on the **Project** menu, click **Properties**.
2. In the **Project Designer**, click the **Debug** tab.
3. In the **Start Action** section, select **Start external program** and enter the following:
`C:\WINDOWS\System32\PresentationHost.exe`
4. In the **Start Options** section, enter the following into the **Command line arguments** text box:
`-debug` *filename*
The *filename* value for the **-debug** parameter is the .xbap filename; for example:
`-debug c:\example.xbap`
> [!NOTE]
> This is the default configuration for solutions that are created with the Visual Studio 2005 XAML Browser Application (WPF) project template.
1. With a project selected in **Solution Explorer**, on the **Project** menu, click **Properties**.
2. In the **Project Designer**, click the **Debug** tab.
3. In the **Start Options** section, add the following command-line parameter to the **Command line arguments** text box:
`-debugSecurityZoneURL` *URL*
The *URL* value for the **-debugSecurityZoneURL** parameter is the URL for the location that you want to simulate as being the site of origin of your application.
As an example, consider a XAML browser application (XBAP) that uses a Web service with the following URL:
`http://services.msdn.microsoft.com/ContentServices/ContentService.asmx`
The site of origin URL for this Web service is:
`http://services.msdn.microsoft.com`
Consequently, the complete **-debugSecurityZoneURL** command-line parameter and value is:
`-debugSecurityZoneURL http://services.msdn.microsoft.com`
## See also
- [WPF Host (PresentationHost.exe)](wpf-host-presentationhost-exe.md)
dotnet-desktop-guide/framework/wpf/app-development/deploying-a-wpf-application-wpf.md
+122
View File
@@ -0,0 +1,122 @@
---
title: "Deploy an app"
description: Explore the deployment technologies that Windows and the .NET Framework use for Windows Presentation Foundation (WPF) applications.
ms.date: "03/30/2017"
helpviewer_keywords:
- "WPF applications [WPF], deployment"
- "deployment [WPF], applications"
ms.assetid: 12cadca0-b32c-4064-9a56-e6a306dcc76d
---
# Deploy a WPF Application
After Windows Presentation Foundation (WPF) applications are built, they need to be deployed. Windows and the .NET Framework include several deployment technologies. The deployment technology that is used to deploy a WPF application depends on the application type. This topic provides a brief overview of each deployment technology, and how they are used in conjunction with the deployment requirements of each WPF application type.
<a name="Deployment_Technologies"></a>
## Deployment Technologies
Windows and the .NET Framework include several deployment technologies, including:
- XCopy deployment.
- Windows Installer deployment.
- ClickOnce deployment.
<a name="XCopy_Deployment"></a>
### XCopy Deployment
XCopy deployment refers to the use of the XCopy command-line program to copy files from one location to another. XCopy deployment is suitable under the following circumstances:
- The application is self-contained. It does not need to update the client to run.
- Application files must be moved from one location to another, such as from a build location (local disk, UNC file share, and so on) to a publish location (Web site, UNC file share, and so on).
- The application does not require shell integration (Start menu shortcut, desktop icon, and so on).
Although XCopy is suitable for simple deployment scenarios, it is limited when more complex deployment capabilities are required. In particular, using XCopy often incurs the overhead for creating, executing, and maintaining scripts for managing deployment in a robust way. Furthermore, XCopy does not support versioning, uninstallation, or rollback.
<a name="Windows_Installer"></a>
### Windows Installer
Windows Installer allows applications to be packaged as self-contained executables that can be easily distributed to clients and run. Furthermore, Windows Installer is installed with Windows and enables integration with the desktop, the Start menu, and the Programs control panel.
Windows Installer simplifies the installation and uninstallation of applications, but it does not provide facilities for ensuring that installed applications are kept up-to-date from a versioning standpoint.
For more information about Windows Installer, see [Windows Installer Deployment](/visualstudio/deployment/deploying-applications-services-and-components#create-an-installer-package-windows-desktop).
<a name="ClickOnce_Deployment"></a>
### ClickOnce Deployment
ClickOnce enables Web-style application deployment for non-Web applications. Applications are published to and deployed from Web or file servers. Although ClickOnce does not support the full range of client features that Windows Installer-installed applications do, it does support a subset that includes the following:
- Integration with the Start menu and Programs control panel.
- Versioning, rollback, and uninstallation.
- Online install mode, which always launches an application from the deployment location.
- Automatic updating when new versions are released.
- Registration of file extensions.
For more information about ClickOnce, see [ClickOnce Security and Deployment](/visualstudio/deployment/clickonce-security-and-deployment).
<a name="Deploying_WPF_Applications"></a>
## Deploying WPF Applications
The deployment options for a WPF application depend on the type of application. From a deployment perspective, WPF has three significant application types:
- Standalone applications.
- Markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] applications.
- XAML browser applications (XBAPs).
<a name="Deploying_Standalone_Applications"></a>
### Deploying Standalone Applications
Standalone applications are deployed using either ClickOnce or Windows Installer. Either way, standalone applications require full trust to run. Full trust is automatically granted to standalone applications that are deployed using Windows Installer. Standalone applications that are deployed using ClickOnce are not automatically granted full trust. Instead, ClickOnce displays a security warning dialog that users must accept before a standalone application is installed. If accepted, the standalone application is installed and granted full trust. If not, the standalone application is not installed.
<a name="Deploying_Markup_Only_XAML_Applications"></a>
### Deploying Markup-Only XAML Applications
Markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages are usually published to Web servers, like HTML pages, and can be viewed using Internet Explorer. Markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages run within a partial-trust security sandbox with restrictions that are defined by the Internet zone permission set. This provides an equivalent security sandbox to HTML-based Web applications.
For more information about security for WPF applications, see [Security](../security-wpf.md).
Markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages can be installed to the local file system by using either XCopy or Windows Installer. These pages can be viewed using Internet Explorer or Windows Explorer.
For more information about XAML, see [XAML Overview (WPF)](/dotnet/desktop-wpf/fundamentals/xaml).
<a name="Deploying_XAML_Browser_Applications"></a>
### Deploying XAML Browser Applications
XBAPs are compiled applications that require the following three files to be deployed:
- *ApplicationName*.exe: The executable assembly application file.
- *ApplicationName*.xbap: The deployment manifest.
- *ApplicationName*.exe.manifest: The application manifest.
> [!NOTE]
> For more information about deployment and application manifests, see [Building a WPF Application](building-a-wpf-application-wpf.md).
These files are produced when an XBAP is built. For more information, see [How to: Create a New WPF Browser Application Project](https://docs.microsoft.com/previous-versions/visualstudio/visual-studio-2010/bb628663(v=vs.100)). Like markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages, XBAPs are typically published to a Web server and viewed using Internet Explorer.
XBAPs can be deployed to clients using any of the deployment techniques. However, ClickOnce is recommended since it provides the following capabilities:
1. Automatic updates when a new version is published.
2. Elevation privileges for the XBAP running with full trust.
By default, ClickOnce publishes application files with the .deploy extension. This can be problematic, but can be disabled. For more information, see [Server and Client Configuration Issues in ClickOnce Deployments](/visualstudio/deployment/server-and-client-configuration-issues-in-clickonce-deployments).
For more information about deploying XAML browser applications (XBAPs), see [WPF XAML Browser Applications Overview](wpf-xaml-browser-applications-overview.md).
<a name="Installing__NET_Framework_3_0"></a>
## Installing the .NET Framework
To run a WPF application, the Microsoft .NET Framework must be installed on the client. Internet Explorer automatically detects whether clients are installed with .NET Framework when WPF browser-hosted applications are viewed. If the .NET Framework is not installed, Internet Explorer prompts users to install it.
To detect whether the .NET Framework is installed, Internet Explorer includes a bootstrapper application that is registered as the fallback Multipurpose Internet Mail Extensions (MIME) handler for content files with the following extensions: .xaml, .xps, .xbap, and .application. If you navigate to these file types and the .NET Framework is not installed on the client, the bootstrapper application requests permission to install it. If permission is not provided, neither the .NET Framework nor the application is installed.
If permission is granted, Internet Explorer downloads and installs the .NET Framework using the Microsoft Background Intelligent Transfer Service (BITS). After successful installation of the .NET Framework, the originally requested file is opened in a new browser window.
For more information, see [Deploying the .NET Framework and Applications](/dotnet/framework/deployment/index).
## See also
- [Building a WPF Application](building-a-wpf-application-wpf.md)
- [Security](../security-wpf.md)
dotnet-desktop-guide/framework/wpf/app-development/dialog-boxes-overview.md
+305
View File
@@ -0,0 +1,305 @@
---
title: "Dialog Boxes Overview"
description: Learn about the varieties of dialog boxes in Windows Foundation Presentation (WPF) that you can use to gather and display information.
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "modeless dialog boxes [WPF]"
- "dialog boxes [WPF]"
- "message boxes [WPF]"
- "modal dialog boxes [WPF]"
ms.assetid: 0d23d544-a393-4a02-a3aa-d8cd5d3d6511
---
# Dialog boxes overview
Standalone applications typically have a main window that both displays the main data over which the application operates and exposes the functionality to process that data through [!INCLUDE[TLA#tla_ui](../../../includes/tlasharptla-ui-md.md)] mechanisms like menu bars, tool bars, and status bars. A non-trivial application may also display additional windows to do the following:
- Display specific information to users.
- Gather information from users.
- Both display and gather information.
These types of windows are known as *dialog boxes*, and there are two types: modal and modeless.
A *modal* dialog box is displayed by a function when the function needs additional data from a user to continue. Because the function depends on the modal dialog box to gather data, the modal dialog box also prevents a user from activating other windows in the application while it remains open. In most cases, a modal dialog box allows a user to signal when they have finished with the modal dialog box by pressing either an **OK** or **Cancel** button. Pressing the **OK** button indicates that a user has entered data and wants the function to continue processing with that data. Pressing the **Cancel** button indicates that a user wants to stop the function from executing altogether. The most common examples of modal dialog boxes are shown to open, save, and print data.
A *modeless* dialog box, on the other hand, does not prevent a user from activating other windows while it is open. For example, if a user wants to find occurrences of a particular word in a document, a main window will often open a dialog box to ask a user what word they are looking for. Since finding a word doesn't prevent a user from editing the document, however, the dialog box doesn't need to be modal. A modeless dialog box at least provides a **Close** button to close the dialog box, and may provide additional buttons to execute specific functions, such as a **Find Next** button to find the next word that matches the find criteria of a word search.
Windows Presentation Foundation (WPF) allows you to create several types of dialog boxes, including message boxes, common dialog boxes, and custom dialog boxes. This topic discusses each, and the [Dialog Box Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Windows/DialogBox) provides matching examples.
<a name="Message_Boxes"></a>
## Message boxes
A *message box* is a dialog box that can be used to display textual information and to allow users to make decisions with buttons. The following figure shows a message box that displays textual information, asks a question, and provides the user with three buttons to answer the question.
![A Word Processor dialog box asking if you want to save the changes to the document before the application closes.](./media/dialog-boxes-overview/word-processor-dialog.png)
To create a message box, you use the <xref:System.Windows.MessageBox> class. <xref:System.Windows.MessageBox> lets you configure the message box text, title, icon, and buttons, using code like the following.
[!code-csharp[DialogBoxesOverviewSnippets#MsgBoxConfigureCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/CSharp/Window1.xaml.cs#msgboxconfigurecodebehind)]
[!code-vb[DialogBoxesOverviewSnippets#MsgBoxConfigureCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/VisualBasic/window1.xaml.vb#msgboxconfigurecodebehind)]
To show a message box, you call the `static`<xref:System.Windows.MessageBox.Show%2A> method, as demonstrated in the following code.
[!code-csharp[DialogBoxesOverviewSnippets#MsgBoxShowCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/CSharp/Window1.xaml.cs#msgboxshowcodebehind)]
[!code-vb[DialogBoxesOverviewSnippets#MsgBoxShowCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/VisualBasic/window1.xaml.vb#msgboxshowcodebehind)]
When code that shows a message box needs to detect and process the user's decision (which button was pressed), the code can inspect the message box result, as shown in the following code.
[!code-csharp[DialogBoxesOverviewSnippets#MsgBoxShowAndResultCODEBEHIND1](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/CSharp/Window1.xaml.cs#msgboxshowandresultcodebehind1)]
[!code-vb[DialogBoxesOverviewSnippets#MsgBoxShowAndResultCODEBEHIND1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/VisualBasic/window1.xaml.vb#msgboxshowandresultcodebehind1)]
For more information on using message boxes, see <xref:System.Windows.MessageBox>, [MessageBox Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Windows/MessageBox), and [Dialog Box Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Windows/DialogBox).
Although <xref:System.Windows.MessageBox> may offer a simple dialog box user experience, the advantage of using <xref:System.Windows.MessageBox> is that is the only type of window that can be shown by applications that run within a partial trust security sandbox (see [Security](../security-wpf.md)), such as XAML browser applications (XBAPs).
Most dialog boxes display and gather more complex data than the result of a message box, including text, selection (check boxes), mutually exclusive selection (radio buttons), and list selection (list boxes, combo boxes, drop-down list boxes). For these, Windows Presentation Foundation (WPF) provides several common dialog boxes and allows you to create your own dialog boxes, although the use of either is limited to applications running with full trust.
<a name="Common_Dialogs"></a>
## Common dialog boxes
Windows implements a variety of reusable dialog boxes that are common to all applications, including dialog boxes for opening files, saving files, and printing. Since these dialog boxes are implemented by the operating system, they can be shared among all the applications that run on the operating system, which helps user experience consistency; when users are familiar with the use of an operating system-provided dialog box in one application, they don't need to learn how to use that dialog box in other applications. Because these dialog boxes are available to all applications and because they help provide a consistent user experience, they are known as *common dialog boxes*.
Windows Presentation Foundation (WPF) encapsulates the open file, save file, and print common dialog boxes and exposes them as managed classes for you to use in standalone applications. This topic provides a brief overview of each.
<a name="Open_File_Dialog"></a>
### Open File dialog
The open file dialog box, shown in the following figure, is used by file opening functionality to retrieve the name of a file to open.
![An Open dialog box showing the location to retrieve the file.](./media/dialog-boxes-overview/open-file-dialog-box.png)
The common open file dialog box is implemented as the <xref:Microsoft.Win32.OpenFileDialog> class and is located in the <xref:Microsoft.Win32> namespace. The following code shows how to create, configure, and show one, and how to process the result.
[!code-csharp[DialogBoxesOverviewSnippets#OpenFileDialogBoxCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/CSharp/Window1.xaml.cs#openfiledialogboxcodebehind)]
[!code-vb[DialogBoxesOverviewSnippets#OpenFileDialogBoxCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/VisualBasic/window1.xaml.vb#openfiledialogboxcodebehind)]
For more information on the open file dialog box, see <xref:Microsoft.Win32.OpenFileDialog?displayProperty=nameWithType>.
> [!NOTE]
> <xref:Microsoft.Win32.OpenFileDialog> can be used to safely retrieve file names by applications running with partial trust (see [Security](../security-wpf.md)).
<a name="Save_File_Dialog"></a>
### Save File dialog box
The save file dialog box, shown in the following figure, is used by file saving functionality to retrieve the name of a file to save.
![A Save As dialog box showing the location to save the file.](./media/dialog-boxes-overview/save-file-dialog-box.png)
The common save file dialog box is implemented as the <xref:Microsoft.Win32.SaveFileDialog> class, and is located in the <xref:Microsoft.Win32> namespace. The following code shows how to create, configure, and show one, and how to process the result.
[!code-csharp[DialogBoxesOverviewSnippets#SaveFileDialogBoxCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/CSharp/Window1.xaml.cs#savefiledialogboxcodebehind)]
[!code-vb[DialogBoxesOverviewSnippets#SaveFileDialogBoxCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/VisualBasic/window1.xaml.vb#savefiledialogboxcodebehind)]
For more information on the save file dialog box, see <xref:Microsoft.Win32.SaveFileDialog?displayProperty=nameWithType>.
<a name="Print_Dialog"></a>
### Print dialog box
The print dialog box, shown in the following figure, is used by printing functionality to choose and configure the printer that a user would like to print data to.
![Screenshot that shows a Print dialog box.](./media/dialog-boxes-overview/print-data-dialog-box.png)
The common print dialog box is implemented as the <xref:System.Windows.Controls.PrintDialog> class, and is located in the <xref:System.Windows.Controls> namespace. The following code shows how to create, configure, and show one.
[!code-csharp[DialogBoxesOverviewSnippets#PrintDialogBoxCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/CSharp/Window1.xaml.cs#printdialogboxcodebehind)]
[!code-vb[DialogBoxesOverviewSnippets#PrintDialogBoxCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxesOverviewSnippets/VisualBasic/window1.xaml.vb#printdialogboxcodebehind)]
For more information on the print dialog box, see <xref:System.Windows.Controls.PrintDialog?displayProperty=nameWithType>. For detailed discussion of printing in WPF, see [Printing Overview](../advanced/printing-overview.md).
<a name="Custom_Dialog_Boxes"></a>
## Custom dialog boxes
While common dialog boxes are useful, and should be used when possible, they do not support the requirements of domain-specific dialog boxes. In these cases, you need to create your own dialog boxes. As we'll see, a dialog box is a window with special behaviors. <xref:System.Windows.Window> implements those behaviors and, consequently, you use <xref:System.Windows.Window> to create custom modal and modeless dialog boxes.
<a name="Creating_a_Modal_Custom_Dialog_Box"></a>
### Creating a modal custom dialog box
This topic shows how to use <xref:System.Windows.Window> to create a typical modal dialog box implementation, using the `Margins` dialog box as an example (see [Dialog Box Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Windows/DialogBox)). The `Margins` dialog box is shown in the following figure.
![A Margins dialog box with fields to define left margin, top margin, right margin, and bottom margin.](./media/dialog-boxes-overview/margin-size-dialog-box.png)
#### Configuring a modal dialog box
The user interface for a typical dialog box includes the following:
- The various controls that are required to gather the desired data.
- An **OK** button that users click to close the dialog box, return to the function, and continue processing.
- A **Cancel** button that users click to close the dialog box and stop the function from further processing.
- A **Close** button in the title bar.
- An icon.
- **Minimize**, **Maximize**, and **Restore** buttons.
- A **System** menu to minimize, maximize, restore, and close the dialog box.
- A position above and in the center of the window that opened the dialog box.
- The ability to be resized where possible to prevent the dialog box from being too small, and to provide the user with a useful default size. This requires that you set both the default and a minimum dimensions.
- The ESC key as a keyboard shortcut that causes the **Cancel** button to be pressed. You do this by setting the <xref:System.Windows.Controls.Button.IsCancel%2A> property of the **Cancel** button to `true`.
- The ENTER (or RETURN) key as a keyboard shortcut that causes the **OK** button to be pressed. You do this by setting the <xref:System.Windows.Controls.Button.IsDefault%2A> property of the **OK** button `true`.
The following code demonstrates this configuration.
[!code-xaml[MarginsDialogBox XAML file](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MarginsDialogBox.xaml?range=1-16,106-112)]
[!code-csharp[MarginsDialogBox C# code-behind](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MarginsDialogBox.xaml.cs?range=1-12,67-68)]
[!code-vb[MarginsDialogBox VB code-behind](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/MarginsDialogBox.xaml.vb?range=1-11,61-62)]
The user experience for a dialog box also extends into the menu bar of the window that opens the dialog box. When a menu item runs a function that requires user interaction through a dialog box before the function can continue, the menu item for the function will have an ellipsis in its header, as shown here.
[!code-xaml[Menu bar of MainWindow.Xaml file](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MainWindow.xaml#L26-L27)]
When a menu item runs a function that displays a dialog box which does not require user interaction, such as an About dialog box, an ellipsis is not required.
#### Opening a modal dialog box
A dialog box is typically shown as a result of a user selecting a menu item to perform a domain-specific function, such as setting the margins of a document in a word processor. Showing a window as a dialog box is similar to showing a normal window, although it requires additional dialog box-specific configuration. The entire process of instantiating, configuring, and opening a dialog box is shown in the following code.
[!code-csharp[Opening a modal dialog box](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MainWindow.xaml.cs?range=1-11,78-88,193-195)]
[!code-vb[Opening a modal dialog box](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/MainWindow.xaml.vb?range=1-9,58-67,130-132)]
Here, the code passes default information (the current margins) to the dialog box. It also sets the <xref:System.Windows.Window.Owner%2A?displayProperty=nameWithType> property with a reference to the window that is showing the dialog box. In general, you should always set the owner for a dialog box to provide window state-related behaviors that are common to all dialog boxes (see [WPF Windows Overview](wpf-windows-overview.md) for more information).
> [!NOTE]
> You must provide an owner to support user interface (UI) automation for dialog boxes (see [UI Automation Overview](/dotnet/framework/ui-automation/ui-automation-overview)).
After the dialog box is configured, it is shown modally by calling the <xref:System.Windows.Window.ShowDialog%2A> method.
#### Validating user-provided data
When a dialog box is opened and the user provides the required data, a dialog box is responsible for ensuring that the provided data is valid for the following reasons:
- From a security perspective, all input should be validated.
- From a domain-specific perspective, data validation prevents erroneous data from being processed by the code, which could potentially throw exceptions.
- From a user-experience perspective, a dialog box can help users by showing them which data they have entered is invalid.
- From a performance perspective, data validation in a multi-tier application can reduce the number of round trips between the client and the application tiers, particularly when the application is composed of Web services or server-based databases.
To validate a bound control in WPF, you need to define a validation rule and associate it with the binding. A validation rule is a custom class that derives from <xref:System.Windows.Controls.ValidationRule>. The following example shows a validation rule, `MarginValidationRule`, which checks that a bound value is a <xref:System.Double> and is within a specified range.
[!code-csharp[Margin validation rules](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MarginValidationRule.cs)]
[!code-vb[Margin validation rules](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/MarginValidationRule.vb)]
In this code, the validation logic of a validation rule is implemented by overriding the <xref:System.Windows.Controls.ValidationRule.Validate%2A> method, which validates the data and returns an appropriate <xref:System.Windows.Controls.ValidationResult>.
To associate the validation rule with the bound control, you use the following markup.
[!code-xaml[Associating a validation rule with a control](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MarginsDialogBox.xaml?range=1-16,57-68,111-112)]
Once the validation rule is associated, WPF will automatically apply it when data is entered into the bound control. When a control contains invalid data, WPF will display a red border around the invalid control, as shown in the following figure.
![A Margins dialog box with a red border around the invalid left margin value.](./media/dialog-boxes-overview/invalid-left-margin-dialog.png)
WPF does not restrict a user to the invalid control until they have entered valid data. This is good behavior for a dialog box; a user should be able to freely navigate the controls in a dialog box whether or not data is valid. However, this means a user can enter invalid data and press the **OK** button. For this reason, your code also needs to validate all controls in a dialog box when the **OK** button is pressed by handling the <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event.
[!code-csharp[Validating all controls in a dialog box](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MarginsDialogBox.xaml.cs?range=1-8,26-29,33-68)]
[!code-vb[Validating all controls in a dialog box](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/MarginsDialogBox.xaml.vb?range=1-8,27-29,33-62)]
This code enumerates all dependency objects on a window and, if any are invalid (as returned by <xref:System.Windows.Controls.Validation.GetHasError%2A>, the invalid control gets the focus, the `IsValid` method returns `false`, and the window is considered invalid.
Once a dialog box is valid, it can safely close and return. As part of the return process, it needs to return a result to the calling function.
#### Setting the modal dialog result
Opening a dialog box using <xref:System.Windows.Window.ShowDialog%2A> is fundamentally like calling a method: the code that opened the dialog box using <xref:System.Windows.Window.ShowDialog%2A> waits until <xref:System.Windows.Window.ShowDialog%2A> returns. When <xref:System.Windows.Window.ShowDialog%2A> returns, the code that called it needs to decide whether to continue processing or stop processing, based on whether the user pressed the **OK** button or the **Cancel** button. To facilitate this decision, the dialog box needs to return the user's choice as a <xref:System.Boolean> value that is returned from the <xref:System.Windows.Window.ShowDialog%2A> method.
When the **OK** button is clicked, <xref:System.Windows.Window.ShowDialog%2A> should return `true`. This is achieved by setting the <xref:System.Windows.Window.DialogResult%2A> property of the dialog box when the **OK** button is clicked.
[!code-csharp[Responding to the OK button](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MarginsDialogBox.xaml.cs?range=1-8,25-27,32-33,67-68)]
[!code-vb[Responding to the OK button](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/MarginsDialogBox.xaml.vb?range=1-8,27,31-33,61-62)]
Note that setting the <xref:System.Windows.Window.DialogResult%2A> property also causes the window to close automatically, which alleviates the need to explicitly call <xref:System.Windows.Window.Close%2A>.
When the **Cancel** button is clicked, <xref:System.Windows.Window.ShowDialog%2A> should return `false`, which also requires setting the <xref:System.Windows.Window.DialogResult%2A> property.
[!code-csharp[Responding to the Cancel button](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MarginsDialogBox.xaml.cs?range=1-8,19-24,67-68)]
[!code-vb[Responding to the Cancel button](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/MarginsDialogBox.xaml.vb?range=1-8,22-25,61-62)]
When a button's <xref:System.Windows.Controls.Button.IsCancel%2A> property is set to `true` and the user presses either the **Cancel** button or the ESC key, <xref:System.Windows.Window.DialogResult%2A> is automatically set to `false`. The following markup has the same effect as the preceding code, without the need to handle the <xref:System.Windows.Controls.Primitives.ButtonBase.Click> event.
[!code-xaml[Markup instead of handling the Click event](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MarginsDialogBox.xaml#L109-L109)]
A dialog box automatically returns `false` when a user presses the **Close** button in the title bar or chooses the **Close** menu item from the **System** menu.
#### Processing data returned from a modal dialog box
When <xref:System.Windows.Window.DialogResult%2A> is set by a dialog box, the function that opened it can get the dialog box result by inspecting the <xref:System.Windows.Window.DialogResult%2A> property when <xref:System.Windows.Window.ShowDialog%2A> returns.
[!code-csharp[Processing data returned from the modal dialog box](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MainWindow.xaml.cs?range=1-10,77-79,89-96,194-195)]
[!code-vb[Processing data returned from the modal dialog box](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/MainWindow.xaml.vb?range=1-9,58,69-73,131-132)]
If the dialog result is `true`, the function uses that as a cue to retrieve and process the data provided by the user.
> [!NOTE]
> After <xref:System.Windows.Window.ShowDialog%2A> has returned, a dialog box cannot be reopened. Instead, you need to create a new instance.
If the dialog result is `false`, the function should end processing appropriately.
<a name="Creating_a_Modeless_Custom_Dialog_Box"></a>
### Creating a modeless custom dialog box
A modeless dialog box, such as the Find Dialog Box shown in the following figure, has the same fundamental appearance as the modal dialog box.
![Screenshot that shows a Find dialog box.](./media/dialog-boxes-overview/find-modeless-dialog-box.png)
However, the behavior is slightly different, as described in the following sections.
#### Opening a modeless dialog box
A modeless dialog box is opened by calling the <xref:System.Windows.Window.Show%2A> method.
[!code-xaml[XAML to define a modeless dialog box](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MainWindow.xaml#L21-L22)]
[!code-csharp[Opening a modeless dialog box](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MainWindow.xaml.cs?range=1-10,65-76,194-195)]
[!code-vb[Openng a modeless dialog box](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/MainWindow.xaml.vb?range=1-9,18-23,131,132)]
Unlike <xref:System.Windows.Window.ShowDialog%2A>, <xref:System.Windows.Window.Show%2A> returns immediately. Consequently, the calling window cannot tell when the modeless dialog box is closed and, therefore, does not know when to check for a dialog box result or get data from the dialog box for further processing. Instead, the dialog box needs to create an alternative way to return data to the calling window for processing.
#### Processing data returned from a modeless dialog box
In this example, the `FindDialogBox` may return one or more find results to the main window, depending on the text being searched for without any specific frequency. As with a modal dialog box, a modeless dialog box can return results using properties. However, the window that owns the dialog box needs to know when to check those properties. One way to enable this is for the dialog box to implement an event that is raised whenever text is found. `FindDialogBox` implements the `TextFoundEvent` for this purpose, which first requires a delegate.
[!code-csharp[The TextFoundEventHandler delegate](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/TextFoundEventHandler.cs)]
[!code-vb[The TextFoundEventHandler delegate](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/TextFoundEventHandler.vb)]
Using the `TextFoundEventHandler` delegate, `FindDialogBox` implements the `TextFoundEvent`.
[!code-csharp[The TextFound event](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/FindDialogBox.xaml.cs?range=1-17,125-126)]
[!code-vb[The TextFound event](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/FindDialogBox.xaml.vb?range=1-15,102-103)]
Consequently, `Find` can raise the event when a search result is found.
[!code-csharp[Raising the TextFound event](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/FindDialogBox.xaml.cs?range=1-9,50-52,91-94,124-127)]
[!code-vb[Raising the TextFound event](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/FindDialogBox.xaml.vb?range=1-9,15,60-64,102-103)]
The owner window then needs to register with and handle this event.
[!code-csharp[Registering and handling the event](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/MainWindow.xaml.cs?range=1-10,184-195)]
[!code-vb[Registering and handling the event](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/MainWindow.xaml.vb?range=1-9,126-132)]
#### Closing a modeless dialog box
Because <xref:System.Windows.Window.DialogResult%2A> does not need to be set, a modeless dialog can be closed using system provide mechanisms, including the following:
- Clicking the **Close** button in the title bar.
- Pressing ALT+F4.
- Choosing **Close** from the **System** menu.
Alternatively, your code can call <xref:System.Windows.Window.Close%2A> when the **Close** button is clicked.
[!code-csharp[Calling the Close method](~/samples/snippets/csharp/VS_Snippets_Wpf/DialogBoxSample/CSharp/FindDialogBox.xaml.cs?range=1-9,119-126)]
[!code-vb[Calling the Close method](~/samples/snippets/visualbasic/VS_Snippets_Wpf/DialogBoxSample/VisualBasic/FindDialogBox.xaml.vb?range=1-9,99-103)]
## See also
- [Popup Overview](../controls/popup-overview.md)
- [Dialog Box Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Windows/DialogBox)
dotnet-desktop-guide/framework/wpf/app-development/filterinputmessage.md
+41
View File
@@ -0,0 +1,41 @@
---
title: "FilterInputMessage"
ms.date: "03/30/2017"
helpviewer_keywords:
- "raw input [WPF]"
- "FilterInputMessage method [WPF]"
ms.assetid: 4d74c6cf-7d1d-49ff-96c1-231340ce54f5
---
# FilterInputMessage
Called by PresentationHost.exe whenever a message is received unless E_NOTIMPL is returned.
## Syntax
```cpp
HRESULT FilterInputMessage( [in] MSG* pMsg ) ;
```
## Parameters
`pMsg`
[in] The WM_INPUT message sent to the window that is getting raw input.
## Property Value/Return Value
HRESULT:
S_OK - The filter did not process the message and further processing may occur.
S_FALSE - The filter processed this message and no further processing should occur.
E_NOTIMPL – If this value is returned, [FilterInputMessage](filterinputmessage.md) is not called again. This might be returned from a host application that is only interested in providing custom progress and error user interfaces to PresentationHost.exe is not interested in being forwarded raw input messages from PresentationHost.exe.
## Remarks
PresentationHost.exe is the target of various raw input devices, including keyboard, mice, and remote controls. Sometimes, behavior in the host application is dependent on input that would otherwise be consumed by PresentationHost.exe. For example, a host application may depend on receiving certain input messages to determine whether or not to display specific user interface elements.
To allow the host application to receive the necessary input messages to provide these behaviors, PresentationHost.exe forwards appropriate raw input messages to the hosted application by calling [FilterInputMessage](filterinputmessage.md).
The hosted application receives raw input messages by registering with the set of raw input devices (Human Interface Devices) returned by [GetRawInputDevices](getrawinputdevices.md).
## See also
- [WM_INPUT message](/windows/desktop/inputdev/wm-input)
dotnet-desktop-guide/framework/wpf/app-development/firefox-add-ons-to-support-net-application-deployment.md
+34
View File
@@ -0,0 +1,34 @@
---
title: "Firefox Add-ons to Support .NET Application Deployment"
ms.date: "03/30/2017"
helpviewer_keywords:
- "Firefox add-ons for .NET application deployment"
- "WPF plug-in for Firefox"
- ".NET application deployment [WPF], deploying with Firefox add-ons"
- ".NET Framework Assistant for Firefox"
ms.assetid: 2403403b-9b14-48e9-b70d-fa288a3c9081
---
# Firefox Add-ons to Support .NET Application Deployment
The Windows Presentation Foundation (WPF) plug-in for Firefox and the .NET Framework Assistant for Firefox enable XAML browser applications (XBAPs), loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)], and ClickOnce applications to work with the Mozilla Firefox browser.
## WPF Plug-in for Firefox
The WPF plug-in for Firefox enables XBAPs and loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files to be navigated to and run at the top-level or in an HTML IFRAME in the Firefox browser. An XBAP is a WPF application that can be published to a Web server and launched within supported browsers. Loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is a XAML-only file that can be navigated to and displayed in supported browsers, much like an XML file.
The WPF plug-in for Firefox is installed with the .NET Framework 3.5. Window 7 includes the .NET Framework 3.5, but does not include the WPF plug-in for Firefox. You cannot install the WPF plug-in for Firefox on Windows 7.
The .NET Framework 4 does not include the WPF plug-in for Firefox. However, if both the .NET Framework 3.5 and .NET Framework 4 are installed, the WPF plug-in for Firefox is installed with the .NET Framework 3.5. Therefore .NET Framework 4 applications will still run because the WPF Host will load the correct version of the framework. For more information, see [WPF Host (PresentationHost.exe)](wpf-host-presentationhost-exe.md).
## .NET Framework Assistant for Firefox
The .NET Framework Assistant for Firefox enables stand-alone ClickOnce applications to run from the Firefox browser. The .NET Framework Assistant for Firefox functions identically when it is installed before and after the Firefox browser. When the Firefox browser is launched and the .NET Framework 3.5 SP1 is installed, Firefox finds and installs the .NET Framework Assistant for Firefox. Users can configure the .NET Framework Assistant for Firefox to do the following:
- Prompt before running the ClickOnce application.
- Report all installed versions of the .NET Framework or just the latest version.
The .NET Framework Assistant for Firefox is included with the .NET Framework 3.5 SP1. For information about removing the .NET Framework Assistant for Firefox, see [How to remove the .NET Framework Assistant for Firefox](https://support.microsoft.com/help/963707/how-to-remove-the-net-framework-assistant-for-firefox).
## See also
- [Deploying a WPF Application](deploying-a-wpf-application-wpf.md)
- [WPF XAML Browser Applications Overview](wpf-xaml-browser-applications-overview.md)
- [Detect Whether the WPF Plug-In for Firefox Is Installed](how-to-detect-whether-the-wpf-plug-in-for-firefox-is-installed.md)
dotnet-desktop-guide/framework/wpf/app-development/getcustomui.md
+44
View File
@@ -0,0 +1,44 @@
---
title: "GetCustomUI"
ms.date: "03/30/2017"
helpviewer_keywords:
- "custom error messages [WPF]"
ms.assetid: e55180fc-35bb-4f80-a136-772b5eb3e4e5
---
# GetCustomUI
Called by PresentationHost.exe to get custom progress and error messages from the host, if implemented.
## Syntax
```cpp
HRESULT GetCustomUI( [out] BSTR* pwzProgressAssemblyName, [out] BSTR* pwzProgressClassName, [out] BSTR* pwzErrorAssemblyName, [out] BSTR* pwzErrorClassName );
```
## Parameters
`pwzProgressAssemblyName`
[out] A pointer to the assembly that contains the host-supplied progress user interface.
`pwzProgressClassName`
[out] The name of the class that is the host-supplied progress user interface, preferably a XAML file with <xref:System.Windows.Controls.Page> is its top-level element. This class resides in the assembly that is specified by `pwzProgressAssemblyName`.
`pwzErrorAssemblyName`
[out] A pointer to the assembly that contains the host-supplied error user interface.
`pwzErrorClassName`
[out] The name of the class that is the host-supplied error user interface, preferably a XAML file with <xref:System.Windows.Controls.Page> is its top-level element. This class resides in the assembly that is specified by `pwzErrorAssemblyName`.
## Property Value/Return Value
HRESULT: Ignored.
## Remarks
A host application may have a specific theme that PresentationHost.exe’s default user interfaces may not conform to. If this is the case, the host application can implement [GetCustomUI](getcustomui.md) to return progress and error user interfaces to PresentationHost.exe. PresentationHost.exe will always call [GetCustomUI](getcustomui.md) before using its default user interfaces.
This function is called once during PresentationHost’s initialization.
## See also
- [IWpfHostSupport](iwpfhostsupport.md)
dotnet-desktop-guide/framework/wpf/app-development/getrawinputdevices.md
+37
View File
@@ -0,0 +1,37 @@
---
title: "GetRawInputDevices"
ms.date: "03/30/2017"
helpviewer_keywords:
- "raw input [WPF]"
ms.assetid: c4d37ecd-065a-4d1c-9e6c-26804ae968ca
---
# GetRawInputDevices
Allows PresentationHost.exe to discover the raw input devices (Human Interface Devices) that the host application is interested in.
## Syntax
```cpp
HRESULT GetRawInputDevices( [out] IEnumRAWINPUTDEVICE **ppEnum );
```
## Parameters
`ppEnum`
[out] A pointer to an [IEnumRAWINPUTDEVICE](ienumrawinputdevice.md) for enumerating the raw input devices.
## Property Value/Return Value
HRESULT:
S_OK - [IEnumRAWINPUTDEVICE](ienumrawinputdevice.md) will only be used by PresentationHost.exe if S_OK is returned.
E_NOTIMPL
## Remarks
Raw input devices are the set of input devices that includes keyboards, mice, and less traditional devices like remote controls.
Once the list of raw input devices has been retrieved, PresentationHost.exe registers with the devices to receive WM_INPUT notification messages.
## See also
- [GetRawInputDeviceList](/windows/desktop/api/winuser/nf-winuser-getrawinputdevicelist)
- [FilterInputMessage](filterinputmessage.md)
dotnet-desktop-guide/framework/wpf/app-development/hosting-wpf-applications.md
+25
View File
@@ -0,0 +1,25 @@
---
title: Host apps
ms.date: "03/30/2017"
f1_keywords:
- "AutoGeneratedOrientationPage"
helpviewer_keywords:
- "WPF application [WPF], hosting"
- "application hosting [WPF]"
- "hosting applications [WPF]"
ms.assetid: 1f73067d-c60a-4e9a-b513-c817ee7da3a1
---
# Hosting WPF Applications
WPF XAML Browser Applications (XBAPs) are rich-client applications that can be deployed to a Web server and started in a browser. The WPF Host (PresentationHost.exe) is registered as the shell and MIME handler for XBAP and XAML files. Therefore, Internet Explorer knows to start the WPF Host when an XBAP is launched. Firefox users can install Firefox add-ons that enable Firefox to host XBAPs as well. An XBAP can be hosted in other browsers or stand-alone applications by using the native browser hosting APIs provided by WPF.
## In This Section
[WPF XAML Browser Applications Overview](wpf-xaml-browser-applications-overview.md)
[WPF Host (PresentationHost.exe)](wpf-host-presentationhost-exe.md)
[Firefox Add-ons to Support .NET Application Deployment](firefox-add-ons-to-support-net-application-deployment.md)
[Native WPF Browser Hosting Support APIs](native-wpf-browser-hosting-support-apis.md)
## Related Sections
[Application Management Overview](application-management-overview.md)
[Windows in WPF](windows-in-wpf-applications.md)
[Navigation Overview](navigation-overview.md)
[Build and Deploy](building-and-deploying-wpf-applications.md)
dotnet-desktop-guide/framework/wpf/app-development/how-to-add-a-splash-screen-to-a-wpf-application.md
+45
View File
@@ -0,0 +1,45 @@
---
title: "How to add a splash screen"
description: Find out how to add a startup window, or splash screen, to a Windows Presentation Foundation (WPF) application.
ms.date: 08/18/2018
helpviewer_keywords:
- "WPF [WPF], splash screen"
- "startup window [WPF]"
- "SplashScreen class [WPF]"
- "splash screen [WPF]"
ms.assetid: d70a25c4-5fb9-4c27-b01d-b1b8ef39b3fd
---
# How to: Add a Splash Screen to a WPF Application
This topic shows how to add a startup window, or *splash screen*, to a Windows Presentation Foundation (WPF) application.
## To add an existing image as a splash screen
1. Create or find an image that you want to use for the splash screen. You can use any image format that is supported by the Windows Imaging Component (WIC). For example, you can use the BMP, GIF, JPEG, PNG, or TIFF format.
2. Add the image file to the WPF Application project.
3. In **Solution Explorer**, select the image.
4. In the Properties window, click the drop-down arrow for the **Build Action** property.
5. Select **SplashScreen** from the drop-down list.
6. Press **F5** to build and run the application.
The splash screen image appears in the center of the screen, and then fades when the main application window appears.
## To exclude the splash screen from build
1. In **Solution Explorer**, select the splash screen image.
2. In the **Properties** window, set the **Build Action** to **None**.
## To remove the splash screen from an application
In **Solution Explorer**, delete the splash screen image.
## See also
- <xref:System.Windows.SplashScreen>
- [How to: Add Existing Items to a Project](https://docs.microsoft.com/previous-versions/visualstudio/visual-studio-2010/9f4t9t92(v=vs.100))
dotnet-desktop-guide/framework/wpf/app-development/how-to-automatically-size-a-window-to-fit-its-content.md
+19
View File
@@ -0,0 +1,19 @@
---
title: "How to: Automatically Size a Window to Fit Its Content"
description: Learn how to set the property that specifies how a window resizes to fit its content in Windows Presentation Foundation (WPF).
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "resizing windows to fit content [WPF]"
- "windows [WPF], resizing to fit content"
- "sizing windows to fit content [WPF]"
ms.assetid: 333ca72a-c2f3-4414-9303-3fdabaaa1b32
---
# How to: Automatically Size a Window to Fit Its Content
This example shows how to set the <xref:System.Windows.Window.SizeToContent%2A> property to specify how a window resizes to fit its content.
## Example
[!code-csharp[HOWTOWindowManagementSnippets#SetWindowSizeToContentPropertyCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/CSharp/MainWindow.xaml.cs#setwindowsizetocontentpropertycode)]
[!code-vb[HOWTOWindowManagementSnippets#SetWindowSizeToContentPropertyCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/visualbasic/mainwindow.xaml.vb#setwindowsizetocontentpropertycode)]
dotnet-desktop-guide/framework/wpf/app-development/how-to-call-a-page-function.md
+31
View File
@@ -0,0 +1,31 @@
---
title: "How to: Call a Page Function"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "calling page functions [WPF]"
- "page functions [WPF], calling"
- "functions [WPF], calling"
ms.assetid: a4808397-c6d5-406a-83e0-0091f0c15ae4
---
# How to: Call a Page Function
This example shows how to call a page function from a [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] page.
## Example
You can navigate to a page function using a uniform resource identifier (URI), just as you can when you navigate to a page. This is shown in the following example.
[!code-csharp[HOWTOPageFunctionSnippets#NavigateToAPageFunctionLikeAPageCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/CSharp/CallingPage.xaml.cs#navigatetoapagefunctionlikeapagecodebehind)]
[!code-vb[HOWTOPageFunctionSnippets#NavigateToAPageFunctionLikeAPageCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/VisualBasic/CallingPage.xaml.vb#navigatetoapagefunctionlikeapagecodebehind)]
If you need to pass data to the page function, you can create an instance of it and pass the data by setting a property. Or, as the following example shows, you can pass the data using a non-parameterless constructor.
[!code-xaml[HOWTOPageFunctionSnippets#CallAPageFunctionXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/CSharp/CallingPage.xaml#callapagefunctionxaml)]
[!code-csharp[HOWTOPageFunctionSnippets#CallAPageFunctionCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/CSharp/CallingPage.xaml.cs#callapagefunctioncodebehind)]
[!code-vb[HOWTOPageFunctionSnippets#CallAPageFunctionCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/VisualBasic/CallingPage.xaml.vb#callapagefunctioncodebehind)]
## See also
- <xref:System.Windows.Navigation.PageFunction%601>
dotnet-desktop-guide/framework/wpf/app-development/how-to-configure-iis-5-0-and-iis-6-0-to-deploy-wpf-applications.md
+150
View File
@@ -0,0 +1,150 @@
---
title: "How to: Configure IIS 5.0 and IIS 6.0 to Deploy WPF Applications"
titleSuffix: ""
ms.date: "03/30/2017"
helpviewer_keywords:
- "MIME types [WPF], registering"
- "adjusting content expiration setting [WPF]"
- "registering file extensions [WPF]"
- "deploying applications [WPF]"
- "applications [WPF], deploying"
- "Web servers [WPF], configuring to deploy WPF applications"
- "configuring Web servers to deploy WPF applications [WPF]"
- "content expiration setting [WPF], adjusting"
- "file extensions [WPF], registering"
- "registering MIME types [WPF]"
ms.assetid: c6e8c2cb-9ba2-4e75-a0d5-180ec9639433
---
# How to: Configure IIS 5.0 and IIS 6.0 to Deploy WPF Applications
You can deploy a [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] application from most Web servers, as long as they are configured with the appropriate Multipurpose Internet Mail Extensions (MIME) types. By default, Microsoft Internet Information Services (IIS) 7.0 is configured with these MIME types, but Microsoft Internet Information Services (IIS) 5.0 and Microsoft Internet Information Services (IIS) 6.0 are not.
This topic describes how to configure Microsoft Internet Information Services (IIS) 5.0 and Microsoft Internet Information Services (IIS) 6.0 to deploy [!INCLUDE[TLA2#tla_winclient](../../../includes/tla2sharptla-winclient-md.md)] applications.
> [!NOTE]
> You can check the *UserAgent* string in the registry to determine whether a system has .NET Framework installed. For details and a script that examines the *UserAgent* string to determine whether .NET Framework is installed on a system, see [Detect Whether the .NET Framework 3.0 Is Installed](how-to-detect-whether-the-net-framework-3-0-is-installed.md).
<a name="content_expiration"></a>
## Adjust the Content Expiration Setting
You should adjust the content expiration setting to 1 minute. The following procedure outlines how to do this with IIS.
1. Click the **Start** menu, point to **Administrative Tools**, and click **Internet Information Services (IIS) Manager**. You can also launch this application from the command line with "%SystemRoot%\system32\inetsrv\iis.msc".
2. Expand the IIS tree until you find the **Default Web site** node.
3. Right-click **Default Web site** and select **Properties** from the context menu.
4. Select the **HTTP Headers** tab and click "Enable Content Expiration".
5. Set the content to expire after 1 minute.
<a name="register_mime_types"></a>
## Register MIME Types and File Extensions
You must register several MIME types and file extensions so that the browser on the client's system can load the correct handler. You need to add the following types:
|Extension|MIME Type|
|---------------|---------------|
|.manifest|application/manifest|
|.xaml|application/xaml+xml|
|.application|application/x-ms-application|
|.xbap|application/x-ms-xbap|
|.deploy|application/octet-stream|
|.xps|application/vnd.ms-xpsdocument|
> [!NOTE]
> You do not need to register MIME types or file extensions on client systems. They are registered automatically when you install Microsoft .NET Framework.
The following Microsoft Visual Basic Scripting Edition (VBScript) sample automatically adds the necessary MIME types to IIS. To use the script, copy the code to a .vbs file on your server. Then, run the script by running the file from the command line or double-clicking the file in Microsoft Windows Explorer.
```vb
' This script adds the necessary Windows Presentation Foundation MIME types
' to an IIS Server.
' To use this script, just double-click or execute it from a command line.
' Running this script multiple times results in multiple entries in the IIS MimeMap.
Dim MimeMapObj, MimeMapArray, MimeTypesToAddArray, WshShell, oExec
Const ADS_PROPERTY_UPDATE = 2
' Set the MIME types to be added
MimeTypesToAddArray = Array(".manifest", "application/manifest", ".xaml", _
"application/xaml+xml", ".application", "application/x-ms-application", _
".deploy", "application/octet-stream", ".xbap", "application/x-ms-xbap", _
".xps", "application/vnd.ms-xpsdocument")
' Get the MimeMap object
Set MimeMapObj = GetObject("IIS://LocalHost/MimeMap")
' Call AddMimeType for every pair of extension/MIME type
For counter = 0 to UBound(MimeTypesToAddArray) Step 2
AddMimeType MimeTypesToAddArray(counter), MimeTypesToAddArray(counter+1)
Next
' Create a Shell object
Set WshShell = CreateObject("WScript.Shell")
' Stop and Start the IIS Service
Set oExec = WshShell.Exec("net stop w3svc")
Do While oExec.Status = 0
WScript.Sleep 100
Loop
Set oExec = WshShell.Exec("net start w3svc")
Do While oExec.Status = 0
WScript.Sleep 100
Loop
Set oExec = Nothing
' Report status to user
WScript.Echo "Windows Presentation Foundation MIME types have been registered."
' AddMimeType Sub
Sub AddMimeType (Ext, MType)
' Get the mappings from the MimeMap property.
MimeMapArray = MimeMapObj.GetEx("MimeMap")
' Add a new mapping.
i = UBound(MimeMapArray) + 1
ReDim Preserve MimeMapArray(i)
Set MimeMapArray(i) = CreateObject("MimeMap")
MimeMapArray(i).Extension = Ext
MimeMapArray(i).MimeType = MType
MimeMapObj.PutEx ADS_PROPERTY_UPDATE, "MimeMap", MimeMapArray
MimeMapObj.SetInfo
End Sub
```
> [!NOTE]
> Running this script multiple times creates multiple MIME map entries in the Microsoft Internet Information Services (IIS) 5.0 or Microsoft Internet Information Services (IIS) 6.0 metabase.
After you have run this script, you may not see additional MIME types from the Microsoft Internet Information Services (IIS) 5.0 or Microsoft Internet Information Services (IIS) 6.0 Microsoft Management Console (MMC). However, these MIME types have been added to the Microsoft Internet Information Services (IIS) 5.0 or Microsoft Internet Information Services (IIS) 6.0 metabase. The following script will display all the MIME types in the Microsoft Internet Information Services (IIS) 5.0 or Microsoft Internet Information Services (IIS) 6.0 metabase.
```vb
' This script lists the MIME types for an IIS Server.
' To use this script, just double-click or execute it from a command line
' by calling cscript.exe
dim mimeMapEntry, allMimeMaps
' Get the MimeMap object.
Set mimeMapEntry = GetObject("IIS://localhost/MimeMap")
allMimeMaps = mimeMapEntry.GetEx("MimeMap")
' Display the mappings in the table.
For Each mimeMap In allMimeMaps
WScript.Echo(mimeMap.MimeType & " (" & mimeMap.Extension + ")")
Next
```
Save the script as a `.vbs` file (for example, `DiscoverIISMimeTypes.vbs`) and run it from the command prompt using the following command:
```console
cscript DiscoverIISMimeTypes.vbs
```
dotnet-desktop-guide/framework/wpf/app-development/how-to-create-an-add-in-that-is-a-ui.md
+118
View File
@@ -0,0 +1,118 @@
---
title: "How to: Create an Add-In That Is a UI"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "creating an add-in that is a UI [WPF]"
- "add-ins [WPF], UI"
- "creating UI add-ins [WPF]"
- "UI add-ins [WPF], creating"
- "implementing UI add-ins [WPF]"
- "pipeline segments [WPF], creating add-ins"
ms.assetid: 86375525-282b-4039-8352-8680051a10ea
---
# How to: Create an Add-In That Is a UI
This example shows how to create an add-in that is a Windows Presentation Foundation (WPF) which is hosted by a WPF standalone application.
The add-in is a UI that is a WPF user control. The content of the user control is a single button that, when clicked, displays a message box. The WPF standalone application hosts the add-in UI as the content of the main application window.
**Prerequisites**
This example highlights the WPF extensions to the .NET Framework add-in model that enable this scenario, and assumes the following:
- Knowledge of the .NET Framework add-in model, including pipeline, add-in, and host development. If you are unfamiliar with these concepts, see [Add-ins and Extensibility](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/bb384200(v%3dvs.100)). For a tutorial that demonstrates the implementation of a pipeline, an add-in, and a host application, see [Walkthrough: Creating an Extensible Application](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/bb788290(v%3dvs.100)).
- Knowledge of the WPF extensions to the .NET Framework add-in model. See [WPF Add-Ins Overview](wpf-add-ins-overview.md).
## Example
To create an add-in that is a WPF UI requires specific code for each pipeline segment, the add-in, and the host application.
<a name="Contract"></a>
## Implementing the Contract Pipeline Segment
When an add-in is a UI, the contract for the add-in must implement <xref:System.AddIn.Contract.INativeHandleContract>. In the example, `IWPFAddInContract` implements <xref:System.AddIn.Contract.INativeHandleContract>, as shown in the following code.
[!code-csharp[SimpleAddInIsAUISample#ContractCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInIsAUISample/CSharp/Contracts/IWPFAddInContract.cs#contractcode)]
[!code-vb[SimpleAddInIsAUISample#ContractCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInIsAUISample/VisualBasic/Contracts/IWPFAddInContract.vb#contractcode)]
<a name="AddInViewPipeline"></a>
## Implementing the Add-In View Pipeline Segment
Because the add-in is implemented as a subclass of the <xref:System.Windows.FrameworkElement> type, the add-in view must also subclass <xref:System.Windows.FrameworkElement>. The following code shows the add-in view of the contract, implemented as the `WPFAddInView` class.
[!code-csharp[SimpleAddInIsAUISample#AddInViewCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInIsAUISample/CSharp/AddInViews/WPFAddInView.cs#addinviewcode)]
[!code-vb[SimpleAddInIsAUISample#AddInViewCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInIsAUISample/VisualBasic/AddInViews/WPFAddInView.vb#AddInViewCode)]
Here, the add-in view is derived from <xref:System.Windows.Controls.UserControl>. Consequently, the add-in UI should also derive from <xref:System.Windows.Controls.UserControl>.
<a name="AddInSideAdapter"></a>
## Implementing the Add-In-Side Adapter Pipeline Segment
While the contract is an <xref:System.AddIn.Contract.INativeHandleContract>, the add-in is a <xref:System.Windows.FrameworkElement> (as specified by the add-in view pipeline segment). Therefore, the <xref:System.Windows.FrameworkElement> must be converted to an <xref:System.AddIn.Contract.INativeHandleContract> before crossing the isolation boundary. This work is performed by the add-in-side adapter by calling <xref:System.AddIn.Pipeline.FrameworkElementAdapters.ViewToContractAdapter%2A>, as shown in the following code.
[!code-csharp[SimpleAddInIsAUISample#AddInSideAdapterCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInIsAUISample/CSharp/AddInSideAdapters/WPFAddIn_ViewToContractAddInSideAdapter.cs#addinsideadaptercode)]
[!code-vb[SimpleAddInIsAUISample#AddInSideAdapterCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInIsAUISample/VisualBasic/AddInSideAdapters/WPFAddIn_ViewToContractAddInSideAdapter.vb#addinsideadaptercode)]
In the add-in model where an add-in returns a UI (see [Create an Add-In That Returns a UI](how-to-create-an-add-in-that-returns-a-ui.md)), the add-in adapter converted the <xref:System.Windows.FrameworkElement> to an <xref:System.AddIn.Contract.INativeHandleContract> by calling <xref:System.AddIn.Pipeline.FrameworkElementAdapters.ViewToContractAdapter%2A>. <xref:System.AddIn.Pipeline.FrameworkElementAdapters.ViewToContractAdapter%2A> must also be called in this model, although you need to implement a method from which to write the code to call it. You do this by overriding <xref:System.AddIn.Pipeline.ContractBase.QueryContract%2A> and implementing the code that calls <xref:System.AddIn.Pipeline.FrameworkElementAdapters.ViewToContractAdapter%2A> if the code that is calling <xref:System.AddIn.Pipeline.ContractBase.QueryContract%2A> is expecting an <xref:System.AddIn.Contract.INativeHandleContract>. In this case, the caller will be the host-side adapter, which is covered in a subsequent subsection.
> [!NOTE]
> You also need to override <xref:System.AddIn.Pipeline.ContractBase.QueryContract%2A> in this model to enable tabbing between host application UI and add-in UI. For more information, see "WPF Add-In Limitations" in [WPF Add-Ins Overview](wpf-add-ins-overview.md).
Because the add-in-side adapter implements an interface that derives from <xref:System.AddIn.Contract.INativeHandleContract>, you also need to implement <xref:System.AddIn.Contract.INativeHandleContract.GetHandle%2A>, although this is ignored when <xref:System.AddIn.Pipeline.ContractBase.QueryContract%2A> is overridden.
<a name="HostViewPipeline"></a>
## Implementing the Host View Pipeline Segment
In this model, the host application typically expects the host view to be a <xref:System.Windows.FrameworkElement> subclass. The host-side adapter must convert the <xref:System.AddIn.Contract.INativeHandleContract> to a <xref:System.Windows.FrameworkElement> after the <xref:System.AddIn.Contract.INativeHandleContract> crosses the isolation boundary. Because a method isn't being called by the host application to get the <xref:System.Windows.FrameworkElement>, the host view must "return" the <xref:System.Windows.FrameworkElement> by containing it. Consequently, the host view must derive from a subclass of <xref:System.Windows.FrameworkElement> that can contain other UIs, such as <xref:System.Windows.Controls.UserControl>. The following code shows the host view of the contract, implemented as the `WPFAddInHostView` class.
[!code-csharp[WPFAddInHostView class](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInIsAUISample/CSharp/HostViews/WPFAddInHostView.cs#HostViewCode)]
[!code-vb[WPFAddInHostView class](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInIsAUISample/VisualBasic/HostViews/WPFAddInHostView.vb#HostViewCode)]
<a name="HostSideAdapter"></a>
## Implementing the Host-Side Adapter Pipeline Segment
While the contract is an <xref:System.AddIn.Contract.INativeHandleContract>, the host application expects a <xref:System.Windows.Controls.UserControl> (as specified by the host view). Consequently, the <xref:System.AddIn.Contract.INativeHandleContract> must be converted to a <xref:System.Windows.FrameworkElement> after crossing the isolation boundary, before being set as content of the host view (which derives from <xref:System.Windows.Controls.UserControl>).
This work is performed by the host-side adapter, as shown in the following code.
[!code-csharp[Host-side adapter](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInIsAUISample/CSharp/HostSideAdapters/WPFAddIn_ContractToViewHostSideAdapter.cs#HostSideAdapterCode)]
[!code-vb[Host-side adapter](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInIsAUISample/VisualBasic/HostSideAdapters/WPFAddIn_ContractToViewHostSideAdapter.vb#HostSideAdapterCode)]
As you can see, the host-side adapter acquires the <xref:System.AddIn.Contract.INativeHandleContract> by calling the add-in-side adapter's <xref:System.AddIn.Pipeline.ContractBase.QueryContract%2A> method (this is the point where the <xref:System.AddIn.Contract.INativeHandleContract> crosses the isolation boundary).
The host-side adapter then converts the <xref:System.AddIn.Contract.INativeHandleContract> to a <xref:System.Windows.FrameworkElement> by calling <xref:System.AddIn.Pipeline.FrameworkElementAdapters.ContractToViewAdapter%2A>. Finally, the <xref:System.Windows.FrameworkElement> is set as the content of the host view.
<a name="AddIn"></a>
## Implementing the Add-In
With the add-in-side adapter and add-in view in place, the add-in can be implemented by deriving from the add-in view, as shown in the following code.
[!code-csharp[Add-in implementation](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInIsAUISample/CSharp/WPFAddIn1/AddInUI.xaml.cs#AddInCodeBehind)]
[!code-vb[Add-in implementation](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInIsAUISample/VisualBasic/WPFAddIn1/AddInUI.xaml.vb#AddInCodeBehind)]
From this example, you can see one interesting benefit of this model: add-in developers only need to implement the add-in (since it is the UI as well), rather than both an add-in class and an add-in UI.
<a name="HostApp"></a>
## Implementing the Host Application
With the host-side adapter and host view created, the host application can use the .NET Framework add-in model to open the pipeline and acquire a host view of the add-in. These steps are shown in the following code.
[!code-csharp[Acquiring a host view of the add-in](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInIsAUISample/CSharp/Host/MainWindow.xaml.cs#GetUICode)]
[!code-vb[Acquiring a host view of the add-in](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInIsAUISample/VisualBasic/Host/MainWindow.xaml.vb#GetUICode)]
The host application uses typical .NET Framework add-in model code to activate the add-in, which implicitly returns the host view to the host application. The host application subsequently displays the host view (which is a <xref:System.Windows.Controls.UserControl>) from a <xref:System.Windows.Controls.Grid>.
The code for processing interactions with the add-in UI runs in the add-in's application domain. These interactions include the following:
- Handling the <xref:System.Windows.Controls.Button><xref:System.Windows.Controls.Primitives.ButtonBase.Click> event.
- Showing the <xref:System.Windows.MessageBox>.
This activity is completely isolated from the host application.
## See also
- [Add-ins and Extensibility](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/bb384200(v%3dvs.100))
- [WPF Add-Ins Overview](wpf-add-ins-overview.md)
dotnet-desktop-guide/framework/wpf/app-development/how-to-create-an-add-in-that-returns-a-ui.md
+88
View File
@@ -0,0 +1,88 @@
---
title: "How to: Create an Add-In That Returns a UI"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "creating an add-in that returns a UI [WPF]"
- "implementing add-in pipeline segments [WPF]"
- "add-in [WPF], returns a UI"
ms.assetid: 57f274b7-4c66-4b72-92eb-81939a393776
---
# How to: Create an Add-In That Returns a UI
This example shows how to create an add-in that returns a Windows Presentation Foundation (WPF) to a host WPF standalone application.
The add-in returns a UI that is a WPF user control. The content of the user control is a single button that, when clicked, displays a message box. The WPF standalone application hosts the add-in and displays the user control (returned by the add-in) as the content of the main application window.
**Prerequisites**
This example highlights the WPF extensions to the .NET Framework add-in model that enable this scenario, and assumes the following:
- Knowledge of the .NET Framework add-in model, including pipeline, add-in, and host development. If you are unfamiliar with these concepts, see [Add-ins and Extensibility](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/bb384200(v%3dvs.100)). For a tutorial that demonstrates the implementation of a pipeline, an add-in, and a host application, see [Walkthrough: Creating an Extensible Application](/previous-versions/dotnet/netframework-4.0/bb788290(v%3dvs.100)).
- Knowledge of the WPF extensions to the .NET Framework add-in model, which can be found here: [WPF Add-Ins Overview](wpf-add-ins-overview.md).
## Example
To create an add-in that returns a WPF UI requires specific code for each pipeline segment, the add-in, and the host application.
<a name="Contract"></a>
## Implementing the Contract Pipeline Segment
A method must be defined by the contract for returning a UI, and its return value must be of type <xref:System.AddIn.Contract.INativeHandleContract>. This is demonstrated by the `GetAddInUI` method of the `IWPFAddInContract` contract in the following code.
[!code-csharp[SimpleAddInReturnsAUISample#ContractCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/CSharp/Contracts/IWPFAddInContract.cs#contractcode)]
[!code-vb[SimpleAddInReturnsAUISample#ContractCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/VisualBasic/Contracts/IWPFAddInContract.vb#contractcode)]
<a name="AddInView"></a>
## Implementing the Add-In View Pipeline Segment
Because the add-in implements the UIs it provides as subclasses of <xref:System.Windows.FrameworkElement>, the method on the add-in view that correlates to `IWPFAddInView.GetAddInUI` must return a value of type <xref:System.Windows.FrameworkElement>. The following code shows the add-in view of the contract, implemented as an interface.
[!code-csharp[SimpleAddInReturnsAUISample#AddInViewCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/CSharp/AddInViews/IWPFAddInView.cs#addinviewcode)]
[!code-vb[SimpleAddInReturnsAUISample#AddInViewCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/VisualBasic/AddInViews/IWPFAddInView.vb#addinviewcode)]
<a name="AddInSideAdapter"></a>
## Implementing the Add-In-Side Adapter Pipeline Segment
The contract method returns an <xref:System.AddIn.Contract.INativeHandleContract>, but the add-in returns a <xref:System.Windows.FrameworkElement> (as specified by the add-in view). Consequently, the <xref:System.Windows.FrameworkElement> must be converted to an <xref:System.AddIn.Contract.INativeHandleContract> before crossing the isolation boundary. This work is performed by the add-in-side adapter by calling <xref:System.AddIn.Pipeline.FrameworkElementAdapters.ViewToContractAdapter%2A>, as shown in the following code.
[!code-csharp[SimpleAddInReturnsAUISample#AddInSideAdapterCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/CSharp/AddInSideAdapters/WPFAddIn_ViewToContractAddInSideAdapter.cs#addinsideadaptercode)]
[!code-vb[SimpleAddInReturnsAUISample#AddInSideAdapterCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/VisualBasic/AddInSideAdapters/WPFAddIn_ViewToContractAddInSideAdapter.vb#addinsideadaptercode)]
<a name="HostView"></a>
## Implementing the Host View Pipeline Segment
Because the host application will display a <xref:System.Windows.FrameworkElement>, the method on the host view that correlates to `IWPFAddInHostView.GetAddInUI` must return a value of type <xref:System.Windows.FrameworkElement>. The following code shows the host view of the contract, implemented as an interface.
[!code-csharp[SimpleAddInReturnsAUISample#HostViewCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/CSharp/HostViews/IWPFAddInHostView.cs#hostviewcode)]
[!code-vb[SimpleAddInReturnsAUISample#HostViewCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/VisualBasic/HostViews/IWPFAddInHostView.vb#hostviewcode)]
<a name="HostSideAdapter"></a>
## Implementing the Host-Side Adapter Pipeline Segment
The contract method returns an <xref:System.AddIn.Contract.INativeHandleContract>, but the host application expects a <xref:System.Windows.FrameworkElement> (as specified by the host view). Consequently, the <xref:System.AddIn.Contract.INativeHandleContract> must be converted to a <xref:System.Windows.FrameworkElement> after crossing the isolation boundary. This work is performed by the host-side adapter by calling <xref:System.AddIn.Pipeline.FrameworkElementAdapters.ContractToViewAdapter%2A>, as shown in the following code.
[!code-csharp[SimpleAddInReturnsAUISample#HostSideAdapterCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/CSharp/HostSideAdapters/WPFAddIn_ContractToViewHostSideAdapter.cs#hostsideadaptercode)]
[!code-vb[SimpleAddInReturnsAUISample#HostSideAdapterCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/VisualBasic/HostSideAdapters/WPFAddIn_ContractToViewHostSideAdapter.vb#hostsideadaptercode)]
<a name="AddIn"></a>
## Implementing the Add-In
With the add-in-side adapter and add-in view created, the add-in (`WPFAddIn1.AddIn`) must implement the `IWPFAddInView.GetAddInUI` method to return a <xref:System.Windows.FrameworkElement> object (a <xref:System.Windows.Controls.UserControl> in this example). The implementation of the <xref:System.Windows.Controls.UserControl>, `AddInUI`, is shown by the following code.
[!code-xaml[SimpleAddInReturnsAUISample#AddInUIMarkup](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/CSharp/WPFAddIn1/AddInUI.xaml#addinuimarkup)]
[!code-csharp[SimpleAddInReturnsAUISample#AddInUICodeBehind](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/CSharp/WPFAddIn1/AddInUI.xaml.cs#addinuicodebehind)]
[!code-vb[SimpleAddInReturnsAUISample#AddInUICodeBehind](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/VisualBasic/WPFAddIn1/AddInUI.xaml.vb#addinuicodebehind)]
The implementation of the `IWPFAddInView.GetAddInUI` by the add-in simply needs to return a new instance of `AddInUI`, as shown by the following code.
[!code-csharp[SimpleAddInReturnsAUISample#AddInCode](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/CSharp/WPFAddIn1/AddIn.cs#addincode)]
[!code-vb[SimpleAddInReturnsAUISample#AddInCode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/VisualBasic/WPFAddIn1/AddIn.vb#addincode)]
<a name="App"></a>
## Implementing the Host Application
With the host-side adapter and host view created, the host application can use the .NET Framework add-in model to open the pipeline, acquire a host view of the add-in, and call the `IWPFAddInHostView.GetAddInUI` method. These steps are shown in the following code.
[!code-csharp[SimpleAddInReturnsAUISample#GetUICode](~/samples/snippets/csharp/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/CSharp/Host/MainWindow.xaml.cs#getuicode)]
[!code-vb[SimpleAddInReturnsAUISample#GetUICode](~/samples/snippets/visualbasic/VS_Snippets_Wpf/SimpleAddInReturnsAUISample/VisualBasic/Host/MainWindow.xaml.vb#getuicode)]
## See also
- [Add-ins and Extensibility](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/bb384200(v%3dvs.100))
- [WPF Add-Ins Overview](wpf-add-ins-overview.md)
dotnet-desktop-guide/framework/wpf/app-development/how-to-detect-whether-the-net-framework-3-0-is-installed.md
+120
View File
@@ -0,0 +1,120 @@
---
title: "How to: Detect Whether the .NET Framework 3.0 Is Installed"
ms.date: "03/30/2017"
helpviewer_keywords:
- "WinFX Runtime user-agent string"
- "presence of WPT [WPF], detecting"
- "detecting WPF presence [WPF]"
ms.assetid: 7f71d652-1749-4379-945a-aa2e3994cb43
---
# How to: Detect Whether the .NET Framework 3.0 Is Installed
Before administrators can deploy Microsoft .NET Framework applications on a system, they must first confirm that the .NET Framework runtime is present. This topic provides a script written in HTML/JavaScript that administrators can use to determine whether the .NET Framework is present on a system.
> [!NOTE]
> For more detailed information on installing, deploying, and detecting the Microsoft .NET Framework, see the discussion in [Deploying Microsoft .NET Framework Version 3.0](https://docs.microsoft.com/previous-versions/dotnet/articles/aa480198(v=msdn.10)).
<a name="content_expiration"></a>
## Detect the ".NET CLR" User-Agent String
When .NET Framework is installed, the MSI adds ".NET CLR" and the version number to the UserAgent string. The following example shows a script embedded in a simple HTML page. The script searches the UserAgent string to determine whether .NET Framework is installed, and displays a status message on the results of the search.
```html
<HTML>
<HEAD>
<TITLE>Test for the .NET Framework 3.0</TITLE>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8" />
<SCRIPT LANGUAGE="JavaScript">
<!--
var dotNETRuntimeVersion = "3.0.04425.00";
function window::onload()
{
if (HasRuntimeVersion(dotNETRuntimeVersion))
{
result.innerText =
"This machine has the correct version of the .NET Framework 3.0: "
+ dotNETRuntimeVersion
}
else
{
result.innerText =
"This machine does not have the correct version of the .NET Framework 3.0."
}
result.innerText += "\n\nThis machine's userAgent string is: " +
navigator.userAgent + ".";
}
//
// Retrieve the version from the user agent string and
// compare with the specified version.
//
function HasRuntimeVersion(versionToCheck)
{
var userAgentString =
navigator.userAgent.match(/.NET CLR [0-9.]+/g);
if (userAgentString != null)
{
var i;
for (i = 0; i < userAgentString.length; ++i)
{
if (CompareVersions(GetVersion(versionToCheck),
GetVersion(userAgentString[i])) <= 0)
return true;
}
}
return false;
}
//
// Extract the numeric part of the version string.
//
function GetVersion(versionString)
{
var numericString =
versionString.match(/([0-9]+)\.([0-9]+)\.([0-9]+)/i);
return numericString.slice(1);
}
//
// Compare the 2 version strings by converting them to numeric format.
//
function CompareVersions(version1, version2)
{
for (i = 0; i < version1.length; ++i)
{
var number1 = new Number(version1[i]);
var number2 = new Number(version2[i]);
if (number1 < number2)
return -1;
if (number1 > number2)
return 1;
}
return 0;
}
-->
</SCRIPT>
</HEAD>
<BODY>
<div id="result" />
</BODY>
</HTML>
```
If the search for the ".NET CLR " version is successful, the following type of status message appears:
`This machine has the correct version of the .NET Framework 3.0: 3.0.04425.00`
`This machine's userAgent string is: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1; .NET CLR 1.1.4322; InfoPath.1; .NET CLR 2.0.50727; .NET CLR 3.0.04425.00).`
Otherwise, the following type of status message appears:
`This machine does not have correct version of the .NET Framework 3.0.`
`This machine's userAgent string is: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1; .NET CLR 1.1.4322; InfoPath.1; .NET CLR 2.0.50727).`
dotnet-desktop-guide/framework/wpf/app-development/how-to-detect-whether-the-net-framework-3-5-is-installed.md
+127
View File
@@ -0,0 +1,127 @@
---
title: "How to: Detect Whether the .NET Framework 3.5 Is Installed"
ms.date: "03/30/2017"
helpviewer_keywords:
- "verifying whether.NET Framework 3.5 is installed [WPF]"
- "detecting .NET Framework 3.5 installation [WPF]"
- "detecting whether.NET Framework 3.5 is installed [WPF]"
- "determining whether.NET Framework 3.5 is installed [WPF]"
ms.assetid: 8556a9d2-1eb8-48ef-919c-5baf22a2a9a2
---
# How to: Detect Whether the .NET Framework 3.5 Is Installed
Before administrators can deploy Windows Presentation Foundation (WPF) applications on a system that targets the .NET Framework 3.5, they must first confirm that the .NET Framework 3.5 runtime is present. This topic provides a script written in HTML/JavaScript that administrators can use to determine whether the .NET Framework 3.5 is present on a system.
> [!NOTE]
> For more detailed information on installing, deploying, and detecting the .NET Framework, see [Install the .NET Framework for developers](/dotnet/framework/install/guide-for-developers).
## Example
When the .NET Framework 3.5 is installed, the MSI adds ".NET CLR" and the version number to the UserAgent string. The following example shows a script embedded in a simple HTML page. The script searches the UserAgent string to determine whether the .NET Framework 3.5 is installed, and displays a status message on the results of the search.
> [!NOTE]
> This script is designed for Internet Explorer. Other browsers may not include .NET CLR information in the UserAgent string.
```html
<HTML>
<HEAD>
<TITLE>Test for the .NET Framework 3.5</TITLE>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8" />
<SCRIPT LANGUAGE="JavaScript">
<!--
var dotNETRuntimeVersion = "3.5.0.0";
function window::onload()
{
if (HasRuntimeVersion(dotNETRuntimeVersion))
{
result.innerText =
"This machine has the correct version of the .NET Framework 3.5."
}
else
{
result.innerText =
"This machine does not have the correct version of the .NET Framework 3.5." +
" The required version is v" + dotNETRuntimeVersion + ".";
}
result.innerText += "\n\nThis machine's userAgent string is: " +
navigator.userAgent + ".";
}
//
// Retrieve the version from the user agent string and
// compare with the specified version.
//
function HasRuntimeVersion(versionToCheck)
{
var userAgentString =
navigator.userAgent.match(/.NET CLR [0-9.]+/g);
if (userAgentString != null)
{
var i;
for (i = 0; i < userAgentString.length; ++i)
{
if (CompareVersions(GetVersion(versionToCheck),
GetVersion(userAgentString[i])) <= 0)
return true;
}
}
return false;
}
//
// Extract the numeric part of the version string.
//
function GetVersion(versionString)
{
var numericString =
versionString.match(/([0-9]+)\.([0-9]+)\.([0-9]+)/i);
return numericString.slice(1);
}
//
// Compare the 2 version strings by converting them to numeric format.
//
function CompareVersions(version1, version2)
{
for (i = 0; i < version1.length; ++i)
{
var number1 = new Number(version1[i]);
var number2 = new Number(version2[i]);
if (number1 < number2)
return -1;
if (number1 > number2)
return 1;
}
return 0;
}
-->
</SCRIPT>
</HEAD>
<BODY>
<div id="result" />
</BODY>
</HTML>
```
If the search for the ".NET CLR " version is successful, the following type of status message appears:
`This machine has the correct version of the .NET Framework 3.5.`
`This machine's userAgent string is: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0; SLCC1; .NET CLR 2.0.50727; .NET CLR 1.1.4322; InfoPath.2; .NET CLR 3.0.590; .NET CLR 3.5.20726; MS-RTC LM 8).`
Otherwise, the following type of status message appears:
`This machine does not have the correct version of the .NET Framework 3.5. The required version is v3.5.0.0.`
`This machine's userAgent string is: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0; SLCC1; .NET CLR 2.0.50727; .NET CLR 1.1.4322; InfoPath.2; .NET CLR 3.0.590; MS-RTC LM 8).`
## See also
- [Detect Whether the .NET Framework 3.0 Is Installed](how-to-detect-whether-the-net-framework-3-0-is-installed.md)
dotnet-desktop-guide/framework/wpf/app-development/how-to-detect-whether-the-wpf-plug-in-for-firefox-is-installed.md
+67
View File
@@ -0,0 +1,67 @@
---
title: Detect Whether WPF Plug-In for Firefox Is Installed
titleSuffix: ""
ms.date: "03/30/2017"
helpviewer_keywords:
- "plug-in for Firefox [WPF]"
- "detecting Firefox installation [WPF]"
- "checking for the Firefox plug-in [WPF]"
- "Firefox [WPF], detecting installation"
- "detecting whether the WPF plug-in for Firefox is installed [WPF]"
ms.assetid: 5f839373-e3fb-44f1-88ad-4a0761f02189
---
# How to: Detect Whether the WPF Plug-In for Firefox Is Installed
The Windows Presentation Foundation (WPF) plug-in for Firefox enables XAML browser applications (XBAPs) and loose XAML files to run in the Mozilla Firefox browser. This topic provides a script written in HTML and JavaScript that administrators can use to determine whether the WPF plug-in for Firefox is installed.
> [!NOTE]
> For more information about installing, deploying, and detecting the .NET Framework, see [Install the .NET Framework for developers](/dotnet/framework/install/guide-for-developers).
## Example
When the .NET Framework 3.5 is installed, the client computer is configured with a WPF plug-in for Firefox. The following example script checks for the WPF plug-in for Firefox and then displays an appropriate status message.
```html
<HTML>
<HEAD>
<TITLE>Test for the WPF plug-in for Firefox</TITLE>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8" />
<SCRIPT type="text/javascript">
<!--
function OnLoad()
{
// Check for the WPF plug-in for Firefox and report
var msg = "The WPF plug-in for Firefox is ";
var wpfPlugin = navigator.plugins["Windows Presentation Foundation"];
if( wpfPlugin != null ) {
document.writeln(msg + " installed.");
}
else {
document.writeln(msg + " not installed. Please install or reinstall the .NET Framework 3.5.");
}
}
-->
</SCRIPT>
</HEAD>
<BODY onload="OnLoad()" />
</HTML>
```
If the check for the WPF plug-in for Firefox is successful, the following status message is displayed:
`The WPF plug-in for Firefox is installed.`
Otherwise, the following status message is displayed:
`The WPF plug-in for Firefox is not installed. Please install or reinstall the .NET Framework 3.5.`
## See also
- [Detect Whether the .NET Framework 3.0 Is Installed](how-to-detect-whether-the-net-framework-3-0-is-installed.md)
- [Detect Whether the .NET Framework 3.5 Is Installed](how-to-detect-whether-the-net-framework-3-5-is-installed.md)
- [WPF XAML Browser Applications Overview](wpf-xaml-browser-applications-overview.md)
dotnet-desktop-guide/framework/wpf/app-development/how-to-determine-if-a-page-is-browser-hosted.md
+26
View File
@@ -0,0 +1,26 @@
---
title: "How to: Determine If a Page is Browser Hosted"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "hosted pages in browser [WPF]"
- "pages [WPF], hosted in browser"
ms.assetid: 737e0f26-8371-49b4-9579-70879e51e1aa
---
# How to: Determine If a Page is Browser Hosted
This example demonstrates how to determine if a <xref:System.Windows.Controls.Page> is hosted in a browser.
## Example
A <xref:System.Windows.Controls.Page> can be host agnostic and, consequently, can be loaded into several different types of hosts, including a <xref:System.Windows.Controls.Frame>, a <xref:System.Windows.Navigation.NavigationWindow>, or a browser. This can happen when you have a library assembly that contains one or more pages, and which is referenced by multiple standalone and browsable (XAML browser application (XBAP)) host applications.
The following example demonstrates how to use <xref:System.Windows.Interop.BrowserInteropHelper.IsBrowserHosted%2A?displayProperty=nameWithType> to determine if a <xref:System.Windows.Controls.Page> is hosted in a browser.
[!code-csharp[HOWTOBrowserInteropHelperSnippets#IsBrowserHostedCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOBrowserInteropHelperSnippets/CSharp/Page1.xaml.cs#isbrowserhostedcode)]
[!code-vb[HOWTOBrowserInteropHelperSnippets#IsBrowserHostedCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOBrowserInteropHelperSnippets/visualbasic/page1.xaml.vb#isbrowserhostedcode)]
## See also
- <xref:System.Windows.Controls.Frame>
- <xref:System.Windows.Controls.Page>
dotnet-desktop-guide/framework/wpf/app-development/how-to-get-all-windows-in-an-application.md
+20
View File
@@ -0,0 +1,20 @@
---
title: "How to: Get all Windows in an Application"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "window objects [WPF], getting"
ms.assetid: f120f06e-993b-4a97-9657-af0d1986981f
---
# How to: Get all Windows in an Application
This example shows how to get all <xref:System.Windows.Window> objects in an application.
## Example
Every instantiated <xref:System.Windows.Window> object, whether visible or not, is automatically added to a collection of window references that is managed by <xref:System.Windows.Application>, and exposed from <xref:System.Windows.Application.Windows%2A>.
You can enumerate <xref:System.Windows.Application.Windows%2A> to get all instantiated windows using the following code:
[!code-csharp[HOWTOWindowManagementSnippets#GetAllWindows](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/CSharp/CustomWindow.xaml.cs#getallwindows)]
[!code-vb[HOWTOWindowManagementSnippets#GetAllWindows](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/visualbasic/customwindow.xaml.vb#getallwindows)]
dotnet-desktop-guide/framework/wpf/app-development/how-to-get-and-set-the-main-application-window.md
+33
View File
@@ -0,0 +1,33 @@
---
title: "How to: Get and Set the Main Application Window"
description: Follow this example to get and set the main application window within Windows Presentation Foundation (WPF) application.
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "windows objects [WPF], setting"
- "setting windows objects [WPF]"
- "windows objects [WPF], getting"
- "getting windows objects [WPF]"
ms.assetid: ec902bc4-4a59-46f5-8ec1-963b46789356
---
# How to: Get and Set the Main Application Window
This example shows how to get and set the main application window.
## Example
The first <xref:System.Windows.Window> that is instantiated within a Windows Presentation Foundation (WPF) application is automatically set by <xref:System.Windows.Application> as the main application window. The first <xref:System.Windows.Window> to be instantiated will most likely be the window that is specified as the startup uniform resource identifier (URI) (see <xref:System.Windows.Application.StartupUri%2A>).
The first <xref:System.Windows.Window> could also be instantiated using code. One example is opening a window during application startup, like the following:
[!code-csharp[HOWTOWindowManagementSnippets#FirstWindowUsingCodeCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/CSharp/App.xaml.cs#firstwindowusingcodecodebehind)]
[!code-vb[HOWTOWindowManagementSnippets#FirstWindowUsingCodeCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/visualbasic/application.xaml.vb#firstwindowusingcodecodebehind)]
Sometimes, the first instantiated <xref:System.Windows.Window> is not actually the main application window e.g. a splash screen. In this case, you can specify the main application window using markup, like the following:
[!code-xaml[ApplicationMainWindowSnippets#SetApplicationMainWindowXAML](~/samples/snippets/xaml/VS_Snippets_Wpf/ApplicationMainWindowSnippets/XAML/App.xaml#setapplicationmainwindowxaml)]
Whether the main window is specified automatically or manually, you can get the main window from <xref:System.Windows.Application.MainWindow%2A> using the following code, like the following:
[!code-csharp[ApplicationMainWindowSnippets#GetApplicationMainWindowCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/ApplicationMainWindowSnippets/CSharp/App.xaml.cs#getapplicationmainwindowcode)]
[!code-vb[ApplicationMainWindowSnippets#GetApplicationMainWindowCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/ApplicationMainWindowSnippets/visualbasic/application.xaml.vb#getapplicationmainwindowcode)]
dotnet-desktop-guide/framework/wpf/app-development/how-to-get-the-return-value-of-a-page-function.md
+27
View File
@@ -0,0 +1,27 @@
---
title: "How to: Get the Return Value of a Page Function"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "functions [WPF], getting return values of"
- "page functions [WPF], getting return values of"
- "return values of page functions [WPF]"
- "getting [WPF], return values of page functions"
ms.assetid: 75470af6-256c-4c46-87e7-705080723a1c
---
# How to: Get the Return Value of a Page Function
This example shows how to get the result that is returned by a page function.
## Example
To get the result that is returned from a page function, you need to handle <xref:System.Windows.Navigation.PageFunction%601.Return> of the page function you are calling.
[!code-xaml[HOWTOPageFunctionSnippets#CallAPageFunctionXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/CSharp/CallingPage.xaml#callapagefunctionxaml)]
[!code-csharp[HOWTOPageFunctionSnippets#GetPageFunctionResultCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/CSharp/CallingPage.xaml.cs#getpagefunctionresultcodebehind)]
[!code-vb[HOWTOPageFunctionSnippets#GetPageFunctionResultCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/VisualBasic/CallingPage.xaml.vb#getpagefunctionresultcodebehind)]
## See also
- <xref:System.Windows.Navigation.PageFunction%601>
dotnet-desktop-guide/framework/wpf/app-development/how-to-navigate-back-through-navigation-history.md
+26
View File
@@ -0,0 +1,26 @@
---
title: "How to: Navigate Back Through Navigation History"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "history [WPF], navigating back"
- "navigation [WPF], through navigation history (back)"
ms.assetid: 9343234b-d864-441d-b8a7-d895cba80a87
---
# How to: Navigate Back Through Navigation History
This example illustrates how to navigate to entries in back navigation history.
## Example
Code that is running from content that is hosted in a <xref:System.Windows.Navigation.NavigationWindow>, <xref:System.Windows.Controls.Frame> using <xref:System.Windows.Navigation.NavigationService>, or Internet Explorer can navigate back through navigation history, one entry at a time.
Navigating back one entry requires first checking that there are entries in back navigation history, by inspecting the **CanGoBack** property, before navigating back one entry, by calling the **GoBack** method. This is illustrated in the following example:
[!code-csharp[HOWTONavigationSnippets#NavigateBackCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTONavigationSnippets/CSharp/HomePage.xaml.cs#navigatebackcode)]
[!code-vb[HOWTONavigationSnippets#NavigateBackCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTONavigationSnippets/visualbasic/homepage.xaml.vb#navigatebackcode)]
**CanGoBack** and **GoBack** are implemented by <xref:System.Windows.Navigation.NavigationWindow>, <xref:System.Windows.Controls.Frame>, and <xref:System.Windows.Navigation.NavigationService>.
> [!NOTE]
> If you call **GoBack**, and there are no entries in back navigation history, an <xref:System.InvalidOperationException> is raised.
dotnet-desktop-guide/framework/wpf/app-development/how-to-navigate-forward-or-back-through-navigation-history.md
+37
View File
@@ -0,0 +1,37 @@
---
title: "How to: Navigate Forward or Back Through Navigation History"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "history [WPF], navigating forward"
- "navigation [WPF], through navigation history (forward)"
ms.assetid: 5939d574-5f53-469e-85f5-1f2b13607caa
---
# How to: Navigate Forward or Back Through Navigation History
This example illustrates how to navigate forward or back to entries in navigation history.
## Example
Code that runs from content in the following hosts can navigate forward or back through navigation history, one entry at a time.
- <xref:System.Windows.Navigation.NavigationWindow> using <xref:System.Windows.Navigation.NavigationService>
- <xref:System.Windows.Controls.Frame> using <xref:System.Windows.Navigation.NavigationService>
- Internet Explorer
Before you can navigate forward one entry, you must first check that there are entries in forward navigation history by inspecting the **CanGoForward** property. To navigate forward one entry, you call the **GoForward** method. This is illustrated in the following example:
[!code-csharp[HOWTONavigationSnippets#NavigateForwardCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTONavigationSnippets/CSharp/HomePage.xaml.cs#navigateforwardcode)]
[!code-vb[HOWTONavigationSnippets#NavigateForwardCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTONavigationSnippets/visualbasic/homepage.xaml.vb#navigateforwardcode)]
Before you can navigate back one entry, you must first check that there are entries in back navigation history by inspecting the **CanGoBack** property. To navigate back one entry, you call the **GoBack** method. This is illustrated in the following example:
[!code-csharp[HOWTONavigationSnippets#NavigateBackCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTONavigationSnippets/CSharp/HomePage.xaml.cs#navigatebackcode)]
[!code-vb[HOWTONavigationSnippets#NavigateBackCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTONavigationSnippets/visualbasic/homepage.xaml.vb#navigatebackcode)]
**CanGoForward**, **GoForward**, **CanGoBack**, and **GoBack** are implemented by <xref:System.Windows.Navigation.NavigationWindow>, <xref:System.Windows.Controls.Frame>, and <xref:System.Windows.Navigation.NavigationService>.
> [!NOTE]
> If you call **GoForward**, and there are no entries in forward navigation history, or if you call **GoBack**, and there are no entries in back navigation history, an <xref:System.InvalidOperationException> is thrown.
dotnet-desktop-guide/framework/wpf/app-development/how-to-navigate-to-a-page.md
+32
View File
@@ -0,0 +1,32 @@
---
title: "How to: Navigate to a Page"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "pages [WPF], navigating to"
- "navigation [WPF], to page"
ms.assetid: 2a556fc0-748b-417f-a58a-0d05a7afb66f
---
# How to: Navigate to a Page
This example illustrates several ways in which a page can be navigated to from a <xref:System.Windows.Navigation.NavigationWindow>.
## Example
It is possible for a <xref:System.Windows.Navigation.NavigationWindow> to navigate to a page using one of the following:
- The <xref:System.Windows.Navigation.NavigationWindow.Source%2A> property.
- The <xref:System.Windows.Navigation.NavigationWindow.Navigate%2A> method.
[!code-csharp[HOWTONavigationSnippets#NavigateToPageCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTONavigationSnippets/CSharp/MainWindow.xaml.cs#navigatetopagecode)]
[!code-vb[HOWTONavigationSnippets#NavigateToPageCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTONavigationSnippets/visualbasic/mainwindow.xaml.vb#navigatetopagecode)]
> [!NOTE]
> Uniform resource identifiers (URIs) can be either relative or absolute. For more information, see [Pack URIs in WPF](pack-uris-in-wpf.md).
## See also
- <xref:System.Windows.Controls.Frame>
- <xref:System.Windows.Controls.Page>
- <xref:System.Windows.Navigation.NavigationService>
dotnet-desktop-guide/framework/wpf/app-development/how-to-open-a-dialog-box.md
+26
View File
@@ -0,0 +1,26 @@
---
title: "How to: Open a Dialog Box"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "opening dialog boxes [WPF]"
- "dialog boxes [WPF], opening"
ms.assetid: 6b1557d2-da98-4ef4-9f68-4089f04ab9ea
---
# How to: Open a Dialog Box
This example shows how to open a dialog box.
## Example
A dialog box is a window that is opened by instantiating <xref:System.Windows.Window> and calling the <xref:System.Windows.Window.ShowDialog%2A> method. <xref:System.Windows.Window.ShowDialog%2A> opens a window and doesn't return until the new dialog box has been closed. This type of window is also known as a *modal* window, and restricts user input.
[!code-csharp[HOWTOWindowManagementSnippets#OpenNewDialogBoxCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/CSharp/MainWindow.xaml.cs#opennewdialogboxcode)]
[!code-vb[HOWTOWindowManagementSnippets#OpenNewDialogBoxCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/visualbasic/mainwindow.xaml.vb#opennewdialogboxcode)]
## .NET Framework Security
Calling <xref:System.Windows.Window.ShowDialog%2A> requires permission to use all windows and user input events without restriction.
## See also
- [Return a Dialog Box Result](how-to-return-a-dialog-box-result.md)
dotnet-desktop-guide/framework/wpf/app-development/how-to-open-a-message-box.md
+23
View File
@@ -0,0 +1,23 @@
---
title: "How to: Open a Message Box"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "message boxes [WPF], opening"
- "opening message boxes [WPF]"
ms.assetid: acaad17f-af43-4eca-a004-f1c9e7c6f292
---
# How to: Open a Message Box
This example shows how to open a message box.
## Example
A message box is a prefabricated modal dialog box for displaying information to users. A message box is opened by calling the static <xref:System.Windows.MessageBox.Show%2A> method of the <xref:System.Windows.MessageBox> class. When <xref:System.Windows.MessageBox.Show%2A> is called, the message is passed using a string parameter. Several overloads of <xref:System.Windows.MessageBox.Show%2A> allow you to configure how a message box will appear (see <xref:System.Windows.MessageBox>).
[!code-csharp[MessageBoxSnippets#MessageBoxShow1CODE](~/samples/snippets/csharp/VS_Snippets_Wpf/MessageBoxSnippets/CSharp/Show1Window.xaml.cs#messageboxshow1code)]
[!code-vb[MessageBoxSnippets#MessageBoxShow1CODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/MessageBoxSnippets/visualbasic/show1window.xaml.vb#messageboxshow1code)]
## See also
- [MessageBox Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Windows/MessageBox)
dotnet-desktop-guide/framework/wpf/app-development/how-to-open-a-window.md
+22
View File
@@ -0,0 +1,22 @@
---
title: "How to: Open a Window"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "windows [WPF], opening"
- "opening windows [WPF]"
ms.assetid: 6b91b2bb-fda7-491d-a72e-139dd630a5b0
---
# How to: Open a Window
This example shows how to open a window.
## Example
A window is opened by instantiating <xref:System.Windows.Window> and calling the <xref:System.Windows.Window.Show%2A> method. <xref:System.Windows.Window.Show%2A> opens a window and returns immediately without waiting for the new window to close. This type of window is also known as a *modeless* window, and doesn't restrict user input.
[!code-csharp[HOWTOWindowManagementSnippets#OpenNewWindowCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/CSharp/MainWindow.xaml.cs#opennewwindowcode)]
[!code-vb[HOWTOWindowManagementSnippets#OpenNewWindowCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/visualbasic/mainwindow.xaml.vb#opennewwindowcode)]
## .NET Framework Security
Instantiating <xref:System.Windows.Window> requires permission to call unsafe native methods (see <xref:System.Windows.Window.%23ctor%2A>).
dotnet-desktop-guide/framework/wpf/app-development/how-to-refresh-a-page.md
+19
View File
@@ -0,0 +1,19 @@
---
title: "How to: Refresh a Page"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "pages [WPF], refreshing"
- "refreshing pages [WPF]"
ms.assetid: 06dd1bbd-81c4-40ad-ac0d-7a5b326b1465
---
# How to: Refresh a Page
This example shows how to call the <xref:System.Windows.Navigation.NavigationWindow.Refresh%2A> method to refresh the current content in a <xref:System.Windows.Navigation.NavigationWindow>.
## Example
<xref:System.Windows.Navigation.NavigationWindow.Refresh%2A> refreshes the current content in a <xref:System.Windows.Navigation.NavigationWindow> to be reloaded from its source.
[!code-csharp[HOWTONavigationSnippets#NavigateRefreshCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTONavigationSnippets/CSharp/MainWindow.xaml.cs#navigaterefreshcode)]
[!code-vb[HOWTONavigationSnippets#NavigateRefreshCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTONavigationSnippets/visualbasic/mainwindow.xaml.vb#navigaterefreshcode)]
dotnet-desktop-guide/framework/wpf/app-development/how-to-return-a-dialog-box-result.md
+24
View File
@@ -0,0 +1,24 @@
---
title: "How to: Return a Dialog Box Result"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "dialog boxes [WPF], returning results"
ms.assetid: 4c5cf286-746b-4052-934d-d80cbf8acba3
---
# How to: Return a Dialog Box Result
This example shows how to retrieve the dialog result for a window that is opened by calling <xref:System.Windows.Window.ShowDialog%2A>.
## Example
Before a dialog box closes, its <xref:System.Windows.Window.DialogResult%2A> property should be set with a <xref:System.Nullable%601><xref:System.Boolean> that indicates how the user closed the dialog box. This value is returned by <xref:System.Windows.Window.ShowDialog%2A> to allow client code to determine how the dialog box was closed and, consequently, how to process the result.
> [!NOTE]
> <xref:System.Windows.Window.DialogResult%2A> can only be set if a window was opened by calling <xref:System.Windows.Window.ShowDialog%2A>.
[!code-csharp[HOWTOWindowManagementSnippets#GetDialogResultCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/CSharp/MainWindow.xaml.cs#getdialogresultcode)]
[!code-vb[HOWTOWindowManagementSnippets#GetDialogResultCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOWindowManagementSnippets/visualbasic/mainwindow.xaml.vb#getdialogresultcode)]
## .NET Framework Security
Calling <xref:System.Windows.Window.ShowDialog%2A> requires permission to use all windows and user input events without restriction.
dotnet-desktop-guide/framework/wpf/app-development/how-to-return-from-a-page-function.md
+27
View File
@@ -0,0 +1,27 @@
---
title: "How to: Return from a Page Function"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "returning from page functions [WPF]"
- "page functions [WPF], returning from"
- "functions [WPF], returning from"
ms.assetid: 87804905-7e8f-417b-b0e3-5622da686396
---
# How to: Return from a Page Function
This example shows how to return a result from a page function.
## Example
To return from a page function, you need to call <xref:System.Windows.Navigation.PageFunction%601.OnReturn%2A> and pass an instance of <xref:System.Windows.Navigation.ReturnEventArgs%601>.
[!code-xaml[HOWTOPageFunctionSnippets#PageFunctionReturnAResultXAML1](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/CSharp/GetStringPageFunction.xaml#pagefunctionreturnaresultxaml1)]
[!code-xaml[HOWTOPageFunctionSnippets#PageFunctionReturnAResultXAML2](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/CSharp/GetStringPageFunction.xaml#pagefunctionreturnaresultxaml2)]
[!code-csharp[HOWTOPageFunctionSnippets#PageFunctionReturnAResultCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/CSharp/GetStringPageFunction.xaml.cs#pagefunctionreturnaresultcodebehind)]
[!code-vb[HOWTOPageFunctionSnippets#PageFunctionReturnAResultCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTOPageFunctionSnippets/VisualBasic/GetStringPageFunction.xaml.vb#pagefunctionreturnaresultcodebehind)]
## See also
- <xref:System.Windows.Navigation.PageFunction%601>
dotnet-desktop-guide/framework/wpf/app-development/how-to-set-the-height-of-a-window-from-a-page.md
+19
View File
@@ -0,0 +1,19 @@
---
title: "How to: Set the Height of a Window from a Page"
ms.date: "03/30/2017"
helpviewer_keywords:
- "windows [WPF], setting height from a page"
- "pages [WPF], setting window height from"
- "height of window [WPF], setting from a page"
ms.assetid: 4e4488ff-ab5c-4ee9-81a4-e1addb55c5cc
---
# How to: Set the Height of a Window from a Page
This example illustrates how to set the height of the window from a <xref:System.Windows.Controls.Page>.
## Example
A <xref:System.Windows.Controls.Page> can set the height of its host window by setting <xref:System.Windows.Controls.Page.WindowHeight%2A>. This property allows the <xref:System.Windows.Controls.Page> to not have explicit knowledge of the type of window that hosts it.
> [!NOTE]
> To set the height of a window using <xref:System.Windows.Controls.Page.WindowHeight%2A>, a <xref:System.Windows.Controls.Page> must be the child of a window.
[!code-xaml[HOWTONavigationSnippets#SetPageWindowHeightXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTONavigationSnippets/CSharp/SetWindowHeightPage.xaml#setpagewindowheightxaml)]
dotnet-desktop-guide/framework/wpf/app-development/how-to-set-the-title-of-a-window-from-a-page.md
+19
View File
@@ -0,0 +1,19 @@
---
title: "How to: Set the Title of a Window from a Page"
ms.date: "03/30/2017"
helpviewer_keywords:
- "windows [WPF], setting title from a page"
- "title of window [WPF], setting from a page"
- "pages [WPF], setting window title from"
ms.assetid: fecf0d19-3eb6-4f8c-a44f-ff1b6f2b34b3
---
# How to: Set the Title of a Window from a Page
This example shows how to set the title of the window in which a <xref:System.Windows.Controls.Page> is hosted.
## Example
A page can change the title of the window that is hosting it by setting the <xref:System.Windows.Controls.Page.WindowTitle%2A> property, like so:
[!code-xaml[HOWTONavigationSnippets#SetPageWindowTitleXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTONavigationSnippets/CSharp/SetWindowTitlePage.xaml#setpagewindowtitlexaml)]
> [!NOTE]
> Setting the <xref:System.Windows.Controls.Page.Title%2A> property of a page does not change the value of the window title. Instead, <xref:System.Windows.Controls.Page.Title%2A> specifies the name of a page entry in navigation history.
dotnet-desktop-guide/framework/wpf/app-development/how-to-set-the-width-of-a-window-from-a-page.md
+19
View File
@@ -0,0 +1,19 @@
---
title: "How to: Set the Width of a Window from a Page"
ms.date: "03/30/2017"
helpviewer_keywords:
- "width of windows [WPF], setting from a page"
- "windows [WPF], setting width from a page"
- "pages [WPF], setting window width from"
ms.assetid: 31601c92-7889-472a-b07e-bf675ad21c92
---
# How to: Set the Width of a Window from a Page
This example illustrates how to set the width of the window from a <xref:System.Windows.Controls.Page>.
## Example
A <xref:System.Windows.Controls.Page> can set the width of its host window by setting <xref:System.Windows.Controls.Page.WindowWidth%2A>. This property allows the <xref:System.Windows.Controls.Page> to not have explicit knowledge of the type of window that hosts it.
> [!NOTE]
> To set the width of a window using <xref:System.Windows.Controls.Page.WindowWidth%2A>, a <xref:System.Windows.Controls.Page> must be the child of a window.
[!code-xaml[HOWTONavigationSnippets#SetPageWindowWidthXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTONavigationSnippets/CSharp/SetWindowWidthPage.xaml#setpagewindowwidthxaml)]
dotnet-desktop-guide/framework/wpf/app-development/how-to-stop-a-page-from-loading.md
+23
View File
@@ -0,0 +1,23 @@
---
title: "How to: Stop a Page from Loading"
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "pages [WPF], stopping from loading"
- "methods [WPF], Stoploading"
- "events [WPF], NavigationStopped"
- "NavigationStopped properties [WPF]"
- "stopping pages from loading [WPF]"
- "loading [WPF], stopping"
ms.assetid: e2b695b0-517e-462c-8ccf-90cc8d6ba864
---
# How to: Stop a Page from Loading
This example shows how to call the <xref:System.Windows.Navigation.NavigationWindow.StopLoading%2A> method to stop navigation to content before it has finished being downloaded.
## Example
<xref:System.Windows.Navigation.NavigationWindow.StopLoading%2A> stops the download of the requested content, and causes the <xref:System.Windows.Navigation.NavigationWindow.NavigationStopped> event to be raised.
[!code-csharp[HOWTONavigationSnippets#NavigateStopLoadingCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTONavigationSnippets/CSharp/MainWindow.xaml.cs#navigatestoploadingcode)]
[!code-vb[HOWTONavigationSnippets#NavigateStopLoadingCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HOWTONavigationSnippets/visualbasic/mainwindow.xaml.vb#navigatestoploadingcode)]
dotnet-desktop-guide/framework/wpf/app-development/how-to-topics.md
+20
View File
@@ -0,0 +1,20 @@
---
title: "How-to Topics"
ms.date: "03/30/2017"
f1_keywords:
- "AutoGeneratedOrientationPage"
helpviewer_keywords:
- "add-ins [WPF], is a UI"
- "creating add-ins [WPF]"
- "add-ins [WPF], returns a UI"
ms.assetid: c33980e8-36e7-45ce-a485-8c826dd29009
---
# How-to Topics
The following topics show how to create Windows Presentation Foundation (WPF) add-ins.
## In This Section
[Create an Add-In That Returns a UI](how-to-create-an-add-in-that-returns-a-ui.md)
[Create an Add-In That Is a UI](how-to-create-an-add-in-that-is-a-ui.md)
## Related Sections
[WPF Add-Ins Overview](wpf-add-ins-overview.md)
dotnet-desktop-guide/framework/wpf/app-development/how-to-use-an-application-scope-resource-dictionary.md
+44
View File
@@ -0,0 +1,44 @@
---
title: "How to: Use an Application-Scope Resource Dictionary"
description: Learn how to define and use an application-scope custom resource dictionary in Windows Presentation Foundation (WPF).
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "dictionaries [WPF], resource"
- "resource dictionaries [WPF], application-scope"
- "application-scope resource dictionaries"
ms.assetid: 53857682-bd2c-4f2c-8f25-1307d0b451a2
---
# How to: Use an Application-Scope Resource Dictionary
This example shows how to define and use an application-scope custom resource dictionary.
## Example
<xref:System.Windows.Application> exposes an application-scope store for shared resources: <xref:System.Windows.Application.Resources%2A>. By default, the <xref:System.Windows.Application.Resources%2A> property is initialized with an instance of the <xref:System.Windows.ResourceDictionary> type. You use this instance when you get and set application-scope properties using <xref:System.Windows.Application.Resources%2A>. For more information, see [How to: Get and Set an Application-Scope Resource](https://docs.microsoft.com/previous-versions/dotnet/netframework-4.0/aa348547(v=vs.100)).
If you have multiple resources that you set using <xref:System.Windows.Application.Resources%2A>, you can instead use a custom resource dictionary to store those resources and set <xref:System.Windows.Application.Resources%2A> with it instead. The following shows how you declare a custom resource dictionary using XAML.
[!code-xaml[HOWTOResourceDictionaries#1](~/samples/snippets/csharp/VS_Snippets_Wpf/HowToResourceDictionaries/CSharp/MyResourceDictionary.xaml#1)]
Swapping entire resource dictionaries using <xref:System.Windows.Application.Resources%2A> allows you to support application-scope themes, where each theme is encapsulated by a single resource dictionary. The following example shows how to set the <xref:System.Windows.ResourceDictionary>.
[!code-xaml[HOWTOResourceDictionaries#2](~/samples/snippets/csharp/VS_Snippets_Wpf/HowToResourceDictionaries/CSharp/App.xaml#2)]
The following shows how you can get application-scope resources from the resource dictionary exposed by <xref:System.Windows.Application.Resources%2A> in XAML.
[!code-xaml[HOWTOResourceDictionaries#4](~/samples/snippets/csharp/VS_Snippets_Wpf/HowToResourceDictionaries/CSharp/MainWindow.xaml#4)]
The following shows how you can also get the resources in code.
[!code-csharp[HOWTOResourceDictionaries#3](~/samples/snippets/csharp/VS_Snippets_Wpf/HowToResourceDictionaries/CSharp/MainWindow.xaml.cs#3)]
[!code-vb[HOWTOResourceDictionaries#3](~/samples/snippets/visualbasic/VS_Snippets_Wpf/HowToResourceDictionaries/VB/MainWindow.xaml.vb#3)]
There are two considerations to make when using <xref:System.Windows.Application.Resources%2A>. First, the dictionary *key* is an object, so you must use exactly the same object instance when both setting and getting a property value. (Note that the key is case-sensitive when using a string.) Second, the dictionary *value* is an object, so you will have to convert the value to the desired type when getting a property value.
## See also
- <xref:System.Windows.ResourceDictionary>
- <xref:System.Windows.Application.Resources%2A>
- [XAML Resources](/dotnet/desktop-wpf/fundamentals/xaml-resources-define)
- [Merged Resource Dictionaries](../advanced/merged-resource-dictionaries.md)
dotnet-desktop-guide/framework/wpf/app-development/how-to-use-mailto-to-send-mail-from-a-page.md
+20
View File
@@ -0,0 +1,20 @@
---
title: "How to: Use mailto: to Send Mail From a Page"
ms.date: "03/30/2017"
helpviewer_keywords:
- "sending mail from pages with mailto:"
- "mailto:, sending mail from pages"
- "mail [WPF], sending from pages"
ms.assetid: b64b9518-df17-4232-94f2-455a4f77ee48
---
# How to: Use mailto: to Send Mail From a Page
This example shows how to use <xref:System.Windows.Documents.Hyperlink> in conjunction with a **mailto:** uniform resource identifier (URI).
## Example
The following code shows how to use a **mailto:** uniform resource identifier (URI) to open a new mail window that contains an email address, and email address and a subject, and an email address, subject, and body.
[!code-xaml[HOWTONavigationMailToSnippet#MailToMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/HOWTONavigationMailToSnippet/CS/HomePage.xaml#mailtomarkup)]
## See also
- [Pack URIs in WPF](pack-uris-in-wpf.md)
dotnet-desktop-guide/framework/wpf/app-development/ienumrawinputdevic-clone.md
+26
View File
@@ -0,0 +1,26 @@
---
title: "IEnumRAWINPUTDEVIC:Clone"
ms.date: "03/30/2017"
helpviewer_keywords:
- "Clone method [WPF]"
ms.assetid: 2a6a1900-aa55-45fa-9382-241d569a2dc4
---
# IEnumRAWINPUTDEVIC:Clone
Creates another raw input device enumerator with the same state as the current enumerator to iterate over the same list.
## Syntax
```cpp
HRESULT Clone( [out] IEnumRAWINPUTDEVICE **ppenum);
```
## Parameters
`ppenum`
[out] Address of output variable that receives the [IEnumRAWINPUTDEVICE](ienumrawinputdevice.md) interface pointer. If the method is unsuccessful, the value of this output variable is undefined.
## Property Value/Return Value
HRESULT: This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED.
## Remarks
This method makes it possible to record a point in the enumeration sequence in order to return to that point at a later time. The caller must release this new enumerator separately from the first enumerator.
dotnet-desktop-guide/framework/wpf/app-development/ienumrawinputdevic-next.md
+34
View File
@@ -0,0 +1,34 @@
---
title: "IEnumRAWINPUTDEVIC:Next"
ms.date: "03/30/2017"
helpviewer_keywords:
- "Next method [WPF]"
ms.assetid: 3698b44d-510e-4d18-b32b-85f17188ee26
---
# IEnumRAWINPUTDEVIC:Next
Enumerates the next `celt` [RAWINPUTDEVICE](/windows/desktop/api/winuser/ns-winuser-rawinputdevice) structures in the enumerator's list, returning them in `rgelt` along with the actual number of enumerated elements in `pceltFetched`.
## Syntax
```cpp
HRESULT Next(
[in] ULONG celt,
[out, size_is(celt), length_is(*pceltFetched)] RAWINPUTDEVICE *rgelt,
[out] ULONG *pceltFetched);
```
## Parameters
`celt`
[in] Number of [RAWINPUTDEVICE](/windows/desktop/api/winuser/ns-winuser-rawinputdevice) structures returned in `rgelt`.
`rgelt`
[out] Array of size celt (or larger) to receive enumerated RAWINPUTDEVICE structures.
`pceltFetched`
[out] Pointer to the number of elements actually supplied in `rgelt`. Caller can pass in `NULL` if `rgelt` is one.
## Property Value/Return Value
HRESULT: S_OK if the number of elements supplied is `celt`; S_FALSE otherwise.
dotnet-desktop-guide/framework/wpf/app-development/ienumrawinputdevic-reset.md
+18
View File
@@ -0,0 +1,18 @@
---
title: "IEnumRAWINPUTDEVIC:Reset"
ms.date: "03/30/2017"
helpviewer_keywords:
- "Reset method [WPF]"
ms.assetid: 6f3255f0-90e0-4736-b184-c1d3b8387bd3
---
# IEnumRAWINPUTDEVIC:Reset
Resets the enumeration sequence to the beginning.
## Syntax
```cpp
HRESULT Reset();
```
## Property Value/Return Value
HRESULT: S_OK.
dotnet-desktop-guide/framework/wpf/app-development/ienumrawinputdevic-skip.md
+23
View File
@@ -0,0 +1,23 @@
---
title: "IEnumRAWINPUTDEVIC:Skip"
ms.date: "03/30/2017"
helpviewer_keywords:
- "Skip method [WPF]"
ms.assetid: c967b0f8-1c6a-459c-8c16-d4f08918ab65
---
# IEnumRAWINPUTDEVIC:Skip
Instructs the enumerator to skip the next `celt` elements in the enumeration so that the next call to [IEnumRAWINPUTDEVIC:Next](ienumrawinputdevic-next.md) will not return those elements.
## Syntax
```cpp
HRESULT Skip( [in] ULONG celt);
```
## Parameters
`celt`
[in] Number of elements to be skipped.
## Property Value/Return Value
HRESULT: S_OK if the number of elements supplied is `celt`; S_FALSE otherwise.
dotnet-desktop-guide/framework/wpf/app-development/ienumrawinputdevice.md
+25
View File
@@ -0,0 +1,25 @@
---
title: "IEnumRAWINPUTDEVICE"
ms.date: "03/30/2017"
helpviewer_keywords:
- "IEnumRAWINPUTDEVICE interface [WPF]"
ms.assetid: 88c8b389-a48b-46b9-b895-8ed7b1e26fea
---
# IEnumRAWINPUTDEVICE
This interface enumerates the raw input devices, and is only used by PresentationHost.exe.
> [!NOTE]
> This API is only intended and supported for use on the local client machine
## Members
|Member|Description|
|------------|-----------------|
|[IEnumRAWINPUTDEVIC:Next](ienumrawinputdevic-next.md)|Enumerates the next `celt` elements (that is, RAWINPUTDEVICE structures) in the enumerator's list, returning them in `rgelt` along with the actual number of enumerated elements in `pceltFetched`.|
|[IEnumRAWINPUTDEVIC:Skip](ienumrawinputdevic-skip.md)|Instructs the enumerator to skip the next `celt` elements in the enumeration so that the next call to [IEnumRAWINPUTDEVIC:Next](ienumrawinputdevic-next.md) will not return those elements.|
|[IEnumRAWINPUTDEVIC:Reset](ienumrawinputdevic-reset.md)|Resets the enumeration sequence to the beginning.|
|[IEnumRAWINPUTDEVIC:Clone](ienumrawinputdevic-clone.md)|Creates another raw input device enumerator with the same state as the current enumerator to iterate over the same list.|
## See also
- [About Raw Input](/windows/desktop/inputdev/about-raw-input)
dotnet-desktop-guide/framework/wpf/app-development/index.md
+126
View File
@@ -0,0 +1,126 @@
---
title: "Application Development"
description: Learn how to build a variety of applications using the framework of Windows Presentation Foundation (WPF).
ms.date: "01/26/2018"
helpviewer_keywords:
- "WPF [WPF], about application development"
- "application development [WPF], about"
ms.assetid: 2996ce5e-81e9-49ae-881b-952db3dd1b7e
---
# Application Development
<a name="introduction"></a>
Windows Presentation Foundation (WPF) is a presentation framework that can be used to develop the following types of applications:
- Standalone Applications (traditional style Windows applications built as executable assemblies that are installed to and run from the client computer).
- XAML browser applications (XBAPs) (applications composed of navigation pages that are built as executable assemblies and hosted by Web browsers such as Microsoft Internet Explorer or Mozilla Firefox).
- Custom Control Libraries (non-executable assemblies containing reusable controls).
- Class Libraries (non-executable assemblies that contain reusable classes).
> [!NOTE]
> Using WPF types in a Windows service is strongly discouraged. If you attempt to use these features in a Windows service, they may not work as expected.
To build this set of applications, WPF implements a host of services. This topic provides an overview of these services and where to find more information.
<a name="Application_Management"></a>
## Application Management
Executable WPF applications commonly require a core set of functionality that includes the following:
- Creating and managing common application infrastructure (including creating an entry point method and a Windows message loop to receive system and input messages).
- Tracking and interacting with the lifetime of an application.
- Retrieving and processing command-line parameters.
- Sharing application-scope properties and [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] resources.
- Detecting and processing unhandled exceptions.
- Returning exit codes.
- Managing windows in standalone applications.
- Tracking navigation in XAML browser applications (XBAPs), and standalone applications with navigation windows and frames.
These capabilities are implemented by the <xref:System.Windows.Application> class, which you add to your applications using an *application definition*.
For more information, see [Application Management Overview](application-management-overview.md).
<a name="WPF_Application_Resource__Content__and_Data_Files"></a>
## WPF Application Resource, Content, and Data Files
WPF extends the core support in the Microsoft .NET Framework for embedded resources with support for three kinds of non-executable data files: resource, content, and data. For more information, see [WPF Application Resource, Content, and Data Files](wpf-application-resource-content-and-data-files.md).
A key component of the support for WPF non-executable data files is the ability to identify and load them using a unique URI. For more information, see [Pack URIs in WPF](pack-uris-in-wpf.md).
<a name="Windows_and_Dialog_Boxes"></a>
## Windows and Dialog Boxes
Users interact with WPF standalone applications through windows. The purpose of a window is to host application content and expose application functionality that usually allows users to interact with the content. In WPF, windows are encapsulated by the <xref:System.Windows.Window> class, which supports:
- Creating and showing windows.
- Establishing owner/owned window relationships.
- Configuring window appearance (for example, size, location, icons, title bar text, border).
- Tracking and interacting with the lifetime of a window.
For more information, see [WPF Windows Overview](wpf-windows-overview.md).
<xref:System.Windows.Window> supports the ability to create a special type of window known as a dialog box. Both modal and modeless types of dialog boxes can be created.
For convenience, and the benefits of reusability and a consistent user experience across applications, WPF exposes three of the common Windows dialog boxes: <xref:Microsoft.Win32.OpenFileDialog>, <xref:Microsoft.Win32.SaveFileDialog>, and <xref:System.Windows.Controls.PrintDialog>.
A message box is a special type of dialog box for showing important textual information to users, and for asking simple Yes/No/OK/Cancel questions. You use the <xref:System.Windows.MessageBox> class to create and show message boxes.
For more information, see [Dialog Boxes Overview](dialog-boxes-overview.md).
<a name="Navigation"></a>
## Navigation
WPF supports Web-style navigation using pages (<xref:System.Windows.Controls.Page>) and hyperlinks (<xref:System.Windows.Documents.Hyperlink>). Navigation can be implemented in a variety of ways that include the following:
- Standalone pages that are hosted in a Web browser.
- Pages compiled into an XBAP that is hosted in a Web browser.
- Pages compiled into a standalone application and hosted by a navigation window (<xref:System.Windows.Navigation.NavigationWindow>).
- Pages that are hosted by a frame (<xref:System.Windows.Controls.Frame>), which may be hosted in a standalone page, or a page compiled into either an XBAP or a standalone application.
To facilitate navigation, WPF implements the following:
- <xref:System.Windows.Navigation.NavigationService>, the shared navigation engine for processing navigation requests that is used by <xref:System.Windows.Controls.Frame>, <xref:System.Windows.Navigation.NavigationWindow>, and XBAPs to support intra-application navigation.
- Navigation methods to initiate navigation.
- Navigation events to track and interact with navigation lifetime.
- Remembering back and forward navigation using a journal, which can also be inspected and manipulated.
For information, see [Navigation Overview](navigation-overview.md).
WPF also supports a special type of navigation known as structured navigation. Structured navigation can be used to call one or more pages that return data in a structured and predictable way that is consistent with calling functions. This capability depends on the <xref:System.Windows.Navigation.PageFunction%601> class, which is described further in [Structured Navigation Overview](structured-navigation-overview.md). <xref:System.Windows.Navigation.PageFunction%601> also serves to simplify the creation of complex navigation topologies, which are described in [Navigation Topologies Overview](navigation-topologies-overview.md).
<a name="Hosting"></a>
## Hosting
XBAPs can be hosted in Microsoft Internet Explorer or Firefox. Each hosting model has its own set of considerations and constraints that are covered in [Hosting](hosting-wpf-applications.md).
<a name="Build_and_Deploy"></a>
## Build and Deploy
Although simple WPF applications can be built from a command prompt using command-line compilers, WPF integrates with Visual Studio to provide additional support that simplified the development and build process. For more information, see [Building a WPF Application](building-a-wpf-application-wpf.md).
Depending on the type of application you build, there are one or more deployment options to choose from. For more information, see [Deploying a WPF Application](deploying-a-wpf-application-wpf.md).
<a name="related_topics"></a>
## Related Topics
|Title|Description|
|-----------|-----------------|
|[Application Management Overview](application-management-overview.md)|Provides an overview of the <xref:System.Windows.Application> class including managing application lifetime, windows, application resources, and navigation.|
|[Windows in WPF](windows-in-wpf-applications.md)|Provides details of managing windows in your application including how to use the <xref:System.Windows.Window> class and dialog boxes.|
|[Navigation Overview](navigation-overview.md)|Provides an overview of managing navigation between pages of your application.|
|[Hosting](hosting-wpf-applications.md)|Provides an overview of XAML browser applications (XBAPs).|
|[Build and Deploy](building-and-deploying-wpf-applications.md)|Describes how to build and deploy your WPF application.|
|[Introduction to WPF in Visual Studio](../getting-started/introduction-to-wpf-in-vs.md)|Describes the main features of WPF.|
|[Walkthrough: My first WPF desktop application](../getting-started/walkthrough-my-first-wpf-desktop-application.md)|A walkthrough that shows how to create a WPF application using page navigation, layout, controls, images, styles, and binding.|
dotnet-desktop-guide/framework/wpf/app-development/iwpfhostsupport.md
+31
View File
@@ -0,0 +1,31 @@
---
title: "IWpfHostSupport"
ms.date: "03/30/2017"
helpviewer_keywords:
- "IWpfHostSupport interface [WPF]"
ms.assetid: cc5a0281-de81-4cc1-87e4-0e46b1a811e9
---
# IWpfHostSupport
Applications that host [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] content via PresentationHost.exe implement this interface to provide a point of integration between the host and PresentationHost.exe.
## Remarks
Win32 applications such as Web browsers can host WPF content, including XAML browser applications (XBAPs) and loose XAML. To host WPF content, Win32 applications create an instance of the [WebBrowser control](https://docs.microsoft.com/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa752040(v=vs.85)). To be hosted, WPF creates an instance of PresentationHost.exe, which provides the hosted WPF content to the host for display in the [WebBrowser control](https://docs.microsoft.com/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa752040(v=vs.85)).
The integration enabled by `IWpfHostSupport` allows PresentationHost.exe to:
- Discover and register with the raw input devices (Human Interface Devices) that the host application is interested in.
- Receive input messages from the registered raw input devices and forward appropriate messages to the host application.
- Query the host application for custom progress and error user interfaces.
> [!NOTE]
> This API is only intended and supported for use on the local client machine
## Members
|Member|Description|
|------------|-----------------|
|[GetRawInputDevices](getrawinputdevices.md)|Allows PresentationHost.exe to discover the raw input devices (Human Interface Devices) that the host application is interested in.|
|[FilterInputMessage](filterinputmessage.md)|Called by PresentationHost.exe whenever a message is received unless E_NOTIMPL is returned.|
|[GetCustomUI](getcustomui.md)|By default, PresentationHost.exe provides its own deployment progress and deployment error user interfaces that are displayed when WPF content is deployed.|
dotnet-desktop-guide/framework/wpf/app-development/media/application-management-overview/unhandled-exception-notification.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/applicationmodeloverview-applicationobjectevents-xbap.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/applicationmodeloverview-applicationobjectevents.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/dialog-boxes-overview/find-modeless-dialog-box.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/dialog-boxes-overview/invalid-left-margin-dialog.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/dialog-boxes-overview/margin-size-dialog-box.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/dialog-boxes-overview/open-file-dialog-box.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/dialog-boxes-overview/print-data-dialog-box.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/dialog-boxes-overview/save-file-dialog-box.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/dialog-boxes-overview/word-processor-dialog.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/back-and-forward-buttons-in-navigation-window.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/back-and-forward-navigation.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/contents-of-person-xaml-file.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/data-remembered-across-page-navigations.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/frame-navigation-between-multiple-pages.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 86 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/frame-uses-its-own-journal.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/journal-navigation-within-pages-hosted-by-a-frame.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.3 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/loaded-and-unloaded-events.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.4 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/multiple-journals-in-one-application.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/navigated-page-lifetime.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.9 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/navigating-to-a-class.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/navigation-host-construction.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.0 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/navigation-window-and-frame.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.5 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/navigation-window-as-dialog-box.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/navigation-window-as-main-window.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/order-of-navigation-events.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.8 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/page-navigates-to-an-object.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/window-title-width-height.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/xbap-launched-from-a-web-server.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-overview/xbap-with-a-page-with-a-hyperlink.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-topologies-overview/navigation-topology-data-items.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 91 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-topologies-overview/navigation-topology-dynamically-generated.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.6 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-topologies-overview/navigation-topology-fixed-hierarchical.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.9 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-topologies-overview/navigation-topology-fixed-linear.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.5 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-topologies-overview/navigation-topology-multiple-pages.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.1 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/navigation-topologies-overview/navigation-topology-sequence-chosen-run-time.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.2 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/pack-uris-in-wpf/wpf-pack-uri-scheme.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.5 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/pack-uris-in-wpf/wpf-package-parts-diagram.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.6 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/pack-uris-in-wpf/wpf-relationship-diagram.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.1 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/structured-navigation-overview/flow-between-calling-page-called-page.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.0 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/wpf-windows-overview/non-rectangular-window-figure.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.2 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/wpf-windows-overview/window-border-styles.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/wpf-windows-overview/window-constituent-elements.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.8 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/wpf-windows-overview/window-lifetime-events.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/wpf-windows-overview/window-lifetime-no-activation.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.6 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/wpf-windows-overview/window-opened-show-method.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.6 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/wpf-windows-overview/window-taskbar-button.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

dotnet-desktop-guide/framework/wpf/app-development/media/wpfbuildsystem-figure1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.1 KiB

dotnet-desktop-guide/framework/wpf/app-development/native-wpf-browser-hosting-support-apis.md
+30
View File
@@ -0,0 +1,30 @@
---
title: "Native Browser Hosting Support APIs"
ms.date: "03/30/2017"
f1_keywords:
- "AutoGeneratedOrientationPage"
helpviewer_keywords:
- "browser hosting support [WPF]"
- "WPF browser hosting support APIs [WPF]"
ms.assetid: 82c133a8-d760-45fb-a2b9-3a997537f1d4
---
# Native WPF Browser Hosting Support APIs
Hosting of WPF applications in Web browsers is facilitated by an Active Document server (also known as a DocObject) registered out of the WPF Host. Internet Explorer can directly activate and integrate with an Active Document. For hosting of XBAPs and loose XAML documents in Mozilla browsers, WPF provides an NPAPI plugin, which provides a similar hosting environment to the WPF Active Document server as Internet Explorer does. However, the easiest practical way to host XBAPs and XAML documents in other browsers and standalone applications is via the Internet Explorer Web Browser control. The Web Browser control provides the complex Active Document server hosting environment, yet it enables its own host to customize and extend that environment and communicate directly with the current Active Document object.
The WPF Active Document server implements several common hosting interfaces, including [IOleObject](/windows/win32/api/oleidl/nn-oleidl-ioleobject), [IOleDocument](/windows/win32/api/docobj/nn-docobj-ioledocument), [IOleInPlaceActiveObject](/windows/win32/api/oleidl/nn-oleidl-ioleinplaceactiveobject), [IPersistMoniker](https://docs.microsoft.com/previous-versions/windows/internet-explorer/ie-developer/platform-apis/ms775042(v=vs.85)), [IOleCommandTarget](/windows/win32/api/docobj/nn-docobj-iolecommandtarget). When hosted in the Web Browser control, these interfaces can be queries from the object returned by the [IWebBrowser2::Document](https://docs.microsoft.com/previous-versions/aa752116(v=vs.85)) property.
## IOleCommandTarget
WPF Active Document server's implementation of [IOleCommandTarget](/windows/win32/api/docobj/nn-docobj-iolecommandtarget) supports numerous navigation-related and browser-specific commands of the standard OLE command group (with a null command group GUID). In addition, it recognizes a custom command group called CGID_PresentationHost. Currently, there is only one command defined within this group.
```cpp
DEFINE_GUID(CGID_PresentationHost, 0xd0288c55, 0xd6, 0x4f5e, 0xa8, 0x51, 0x79, 0xde, 0xc5, 0x1b, 0x10, 0xec);
enum PresentationHostCommands {
PHCMDID_TABINTO = 1
};
```
PHCMDID_TABINTO instructs PresentationHost to switch focus to the first or last focusable element in its content, depending on the state of the Shift key.
## In This Section
[IEnumRAWINPUTDEVICE](ienumrawinputdevice.md)
[IWpfHostSupport](iwpfhostsupport.md)
dotnet-desktop-guide/framework/wpf/app-development/navigation-how-to-topics.md
+22
View File
@@ -0,0 +1,22 @@
---
title: "Navigation How-to Topics"
ms.date: "03/30/2017"
f1_keywords:
- "AutoGeneratedOrientationPage"
helpviewer_keywords:
- "navigation [WPF]"
ms.assetid: f804648e-558c-4f60-8e48-d11f4a23c436
---
# Navigation How-to Topics
The following topics show how to use [!INCLUDE[TLA#tla_winclient](../../../includes/tlasharptla-winclient-md.md)] navigation.
## In This Section
[Call a Page Function](how-to-call-a-page-function.md)
[Get the Return Value of a Page Function](how-to-get-the-return-value-of-a-page-function.md)
[Navigate Forward or Back Through Navigation History](how-to-navigate-forward-or-back-through-navigation-history.md)
[Return from a Page Function](how-to-return-from-a-page-function.md)
## Related Sections
[Navigation Overview](navigation-overview.md)
[Structured Navigation Overview](structured-navigation-overview.md)
dotnet-desktop-guide/framework/wpf/app-development/navigation-overview.md
+787
View File
@@ -0,0 +1,787 @@
---
title: "Navigation Overview"
description: Learn about support for browser-style navigation used in standalone applications and XAML browser applications in Windows Presentation Foundation (WPF).
ms.date: "03/30/2017"
dev_langs:
- "csharp"
- "vb"
helpviewer_keywords:
- "loose XAML files [WPF]"
- "windows [WPF]"
- "Start page [WPF]"
- "HTML files [WPF]"
- "structured navigation [WPF]"
- "fragment navigation [WPF]"
- "URIs (Uniform Resource Identifiers)"
- "custom objects [WPF]"
- "Uniform Resource Identifiers (URIs)"
- "pages [WPF]"
- "frames [WPF]"
- "navigation hosts [WPF]"
- "journals [WPF]"
- "lifetimes [WPF]"
- "retaining content state [WPF]"
- "content state [WPF]"
- "programmatic navigation [WPF]"
- "hyperlinks [WPF]"
ms.assetid: 86ad2143-606a-4e34-bf7e-51a2594248b8
---
# Navigation Overview
Windows Presentation Foundation (WPF) supports browser-style navigation that can be used in two types of applications: standalone applications and XAML browser applications (XBAPs). To package content for navigation, WPF provides the <xref:System.Windows.Controls.Page> class. You can navigate from one <xref:System.Windows.Controls.Page> to another declaratively, by using a <xref:System.Windows.Documents.Hyperlink>, or programmatically, by using the <xref:System.Windows.Navigation.NavigationService>. WPF uses the journal to remember pages that have been navigated from and to navigate back to them.
<xref:System.Windows.Controls.Page>, <xref:System.Windows.Documents.Hyperlink>, <xref:System.Windows.Navigation.NavigationService>, and the journal form the core of the navigation support offered by WPF. This overview explores these features in detail before covering advanced navigation support that includes navigation to loose [!INCLUDE[TLA#tla_xaml](../../../includes/tlasharptla-xaml-md.md)] files, HTML files, and objects.
> [!NOTE]
> In this topic, the term "browser" refers only to browsers that can host WPF applications, which currently includes Microsoft Internet Explorer and Firefox. Where specific WPF features are supported only by a particular browser, the browser version is referred to.
## Navigation in WPF Applications
This topic provides an overview of the key navigation capabilities in WPF. These capabilities are available to both standalone applications and XBAPs, although this topic presents them within the context of an XBAP.
> [!NOTE]
> This topic doesn't discuss how to build and deploy XBAPs. For more information on XBAPs, see [WPF XAML Browser Applications Overview](wpf-xaml-browser-applications-overview.md).
This section explains and demonstrates the following aspects of navigation:
- [Implementing a Page](#CreatingAXAMLPage)
- [Configuring a Start Page](#Configuring_a_Start_Page)
- [Configuring the Host Window's Title, Width, and Height](#ConfiguringAXAMLPage)
- [Hyperlink Navigation](#NavigatingBetweenXAMLPages)
- [Fragment Navigation](#FragmentNavigation)
- [Navigation Service](#NavigationService)
- [Programmatic Navigation with the Navigation Service](#Programmatic_Navigation_with_the_Navigation_Service)
- [Navigation Lifetime](#Navigation_Lifetime)
- [Remembering Navigation with the Journal](#NavigationHistory)
- [Page Lifetime and the Journal](#PageLifetime)
- [Retaining Content State with Navigation History](#RetainingContentStateWithNavigationHistory)
- [Cookies](#Cookies)
- [Structured Navigation](#Structured_Navigation)
<a name="CreatingAXAMLPage"></a>
### Implementing a Page
In WPF, you can navigate to several content types that include .NET Framework objects, custom objects, enumeration values, user controls, [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files, and HTML files. However, you'll find that the most common and convenient way to package content is by using <xref:System.Windows.Controls.Page>. Furthermore, <xref:System.Windows.Controls.Page> implements navigation-specific features to enhance their appearance and simplify development.
Using <xref:System.Windows.Controls.Page>, you can declaratively implement a navigable page of [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] content by using markup like the following.
[!code-xaml[NavigationOverviewSnippets#Page1XAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/Page1.xaml#page1xaml)]
A <xref:System.Windows.Controls.Page> that is implemented in [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] markup has `Page` as its root element and requires the WPF XML namespace declaration. The `Page` element contains the content that you want to navigate to and display. You add content by setting the `Page.Content` property element, as shown in the following markup.
[!code-xaml[NavigationOverviewSnippets#Page2XAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/Page2.xaml#page2xaml)]
`Page.Content` can only contain one child element; in the preceding example, the content is a single string, "Hello, Page!" In practice, you will usually use a layout control as the child element (see [Layout](../advanced/layout.md)) to contain and compose your content.
The child elements of a `Page` element are considered to be the content of a <xref:System.Windows.Controls.Page> and, consequently, you don't need to use the explicit `Page.Content` declaration. The following markup is the declarative equivalent to the preceding sample.
[!code-xaml[NavigationOverviewSnippets#Page3XAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/Page3.xaml#page3xaml)]
In this case, `Page.Content` is automatically set with the child elements of the `Page` element. For more information, see [WPF Content Model](../controls/wpf-content-model.md).
A markup-only <xref:System.Windows.Controls.Page> is useful for displaying content. However, a <xref:System.Windows.Controls.Page> can also display controls that allow users to interact with the page, and it can respond to user interaction by handling events and calling application logic. An interactive <xref:System.Windows.Controls.Page> is implemented by using a combination of markup and code-behind, as shown in the following example.
[!code-xaml[XBAPAppDefSnippets#HomePageMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/XBAPAppDefSnippets/CSharp/HomePage.xaml#homepagemarkup)]
[!code-csharp[XBAPAppDefSnippets#HomePageCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/XBAPAppDefSnippets/CSharp/HomePage.xaml.cs#homepagecodebehind)]
[!code-vb[XBAPAppDefSnippets#HomePageCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/XBAPAppDefSnippets/VisualBasic/HomePage.xaml.vb#homepagecodebehind)]
To allow a markup file and code-behind file to work together, the following configuration is required:
- In markup, the `Page` element must include the `x:Class` attribute. When the application is built, the existence of `x:Class` in the markup file causes Microsoft build engine (MSBuild) to create a `partial` class that derives from <xref:System.Windows.Controls.Page> and has the name that is specified by the `x:Class` attribute. This requires the addition of an XML namespace declaration for the [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] schema ( `xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"` ). The generated `partial` class implements `InitializeComponent`, which is called to register the events and set the properties that are implemented in markup.
- In code-behind, the class must be a `partial` class with the same name that is specified by the `x:Class` attribute in markup, and it must derive from <xref:System.Windows.Controls.Page>. This allows the code-behind file to be associated with the `partial` class that is generated for the markup file when the application is built (see [Building a WPF Application](building-a-wpf-application-wpf.md)).
- In code-behind, the <xref:System.Windows.Controls.Page> class must implement a constructor that calls the `InitializeComponent` method. `InitializeComponent` is implemented by the markup file's generated `partial` class to register events and set properties that are defined in markup.
> [!NOTE]
> When you add a new <xref:System.Windows.Controls.Page> to your project using Visual Studio, the <xref:System.Windows.Controls.Page> is implemented using both markup and code-behind, and it includes the necessary configuration to create the association between the markup and code-behind files as described here.
Once you have a <xref:System.Windows.Controls.Page>, you can navigate to it. To specify the first <xref:System.Windows.Controls.Page> that an application navigates to, you need to configure the start <xref:System.Windows.Controls.Page>.
<a name="Configuring_a_Start_Page"></a>
### Configuring a Start Page
XBAPs require a certain amount of application infrastructure to be hosted in a browser. In WPF, the <xref:System.Windows.Application> class is part of an application definition that establishes the required application infrastructure (see [Application Management Overview](application-management-overview.md)).
An application definition is usually implemented using both markup and code-behind, with the markup file configured as an MSBuild`ApplicationDefinition` item. The following is an application definition for an XBAP.
[!code-xaml[XBAPAppDefSnippets#XBAPApplicationDefinitionMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/XBAPAppDefSnippets/CSharp/App.xaml#xbapapplicationdefinitionmarkup)]
[!code-csharp[XBAPAppDefSnippets#XBAPApplicationDefinitionCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/XBAPAppDefSnippets/CSharp/App.xaml.cs#xbapapplicationdefinitioncodebehind)]
[!code-vb[XBAPAppDefSnippets#XBAPApplicationDefinitionCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/XBAPAppDefSnippets/VisualBasic/Application.xaml.vb#xbapapplicationdefinitioncodebehind)]
An XBAP can use its application definition to specify a start <xref:System.Windows.Controls.Page>, which is the <xref:System.Windows.Controls.Page> that is automatically loaded when the XBAP is launched. You do this by setting the <xref:System.Windows.Application.StartupUri%2A> property with the uniform resource identifier (URI) for the desired <xref:System.Windows.Controls.Page>.
> [!NOTE]
> In most cases, the <xref:System.Windows.Controls.Page> is either compiled into or deployed with an application. In these cases, the URI that identifies a <xref:System.Windows.Controls.Page> is a pack URI, which is a URI that conforms to the *pack* scheme. Pack URIs are discussed further in [Pack URIs in WPF](pack-uris-in-wpf.md). You can also navigate to content using the http scheme, which is discussed below.
You can set <xref:System.Windows.Application.StartupUri%2A> declaratively in markup, as shown in the following example.
[!code-xaml[NavigationOverviewSnippets#XBAPApplicationDefinitionMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/App.xaml#xbapapplicationdefinitionmarkup)]
In this example, the `StartupUri` attribute is set with a relative pack URI that identifies HomePage.xaml. When the XBAP is launched, HomePage.xaml is automatically navigated to and displayed. This is demonstrated by the following figure, which shows an XBAP that was launched from a Web server.
![XBAP page](./media/navigation-overview/xbap-launched-from-a-web-server.png "This shows an XBAP launched from a Web server.")
> [!NOTE]
> For more information regarding the development and deployment of XBAPs, see [WPF XAML Browser Applications Overview](wpf-xaml-browser-applications-overview.md) and [Deploying a WPF Application](deploying-a-wpf-application-wpf.md).
<a name="ConfiguringAXAMLPage"></a>
### Configuring the Host Window's Title, Width, and Height
One thing you may have noticed from the previous figure is that the title of both the browser and the tab panel is the URI for the XBAP. Besides being long, the title is neither attractive nor informative. For this reason, <xref:System.Windows.Controls.Page> offers a way for you to change the title by setting the <xref:System.Windows.Controls.Page.WindowTitle%2A> property. Furthermore, you can configure the width and height of the browser window by setting <xref:System.Windows.Controls.Page.WindowWidth%2A> and <xref:System.Windows.Controls.Page.WindowHeight%2A>, respectively.
<xref:System.Windows.Controls.Page.WindowTitle%2A>, <xref:System.Windows.Controls.Page.WindowWidth%2A>, and <xref:System.Windows.Controls.Page.WindowHeight%2A> can be set declaratively in markup, as shown in the following example.
[!code-xaml[NavigationOverviewSnippets#HomePageMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/HomePage.xaml#homepagemarkup)]
The result is shown in the following figure.
![Window title, height, width](./media/navigation-overview/window-title-width-height.png "This shows the window title, height, and width you can configure.")
<a name="NavigatingBetweenXAMLPages"></a>
### Hyperlink Navigation
A typical XBAP comprises several pages. The simplest way to navigate from one page to another is to use a <xref:System.Windows.Documents.Hyperlink>. You can declaratively add a <xref:System.Windows.Documents.Hyperlink> to a <xref:System.Windows.Controls.Page> by using the `Hyperlink` element, which is shown in the following markup.
[!code-xaml[NavigationOverviewSnippets#HyperlinkXAML1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithHyperlink.xaml#hyperlinkxaml1)]
[!code-xaml[NavigationOverviewSnippets#HyperlinkXAML2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithHyperlink.xaml#hyperlinkxaml2)]
[!code-xaml[NavigationOverviewSnippets#HyperlinkXAML3](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithHyperlink.xaml#hyperlinkxaml3)]
A `Hyperlink` element requires the following:
- The pack URI of the <xref:System.Windows.Controls.Page> to navigate to, as specified by the `NavigateUri` attribute.
- Content that a user can click to initiate the navigation, such as text and images (for the content that the `Hyperlink` element can contain, see <xref:System.Windows.Documents.Hyperlink>).
The following figure shows an XBAP with a <xref:System.Windows.Controls.Page> that has a <xref:System.Windows.Documents.Hyperlink>.
![Page with Hyperlink](./media/navigation-overview/xbap-with-a-page-with-a-hyperlink.png "This shows an XBAP with a page with a hyperlink.")
As you would expect, clicking the <xref:System.Windows.Documents.Hyperlink> causes the XBAP to navigate to the <xref:System.Windows.Controls.Page> that is identified by the `NavigateUri` attribute. Additionally, the XBAP adds an entry for the previous <xref:System.Windows.Controls.Page> to the Recent Pages list in Internet Explorer. This is shown in the following figure.
![Back and Forward buttons](./media/navigation-overview/back-and-forward-navigation.png "Navigate with the back and forward buttons.")
As well as supporting navigation from one <xref:System.Windows.Controls.Page> to another, <xref:System.Windows.Documents.Hyperlink> also supports fragment navigation.
<a name="FragmentNavigation"></a>
### Fragment Navigation
*Fragment navigation* is the navigation to a content fragment in either the current <xref:System.Windows.Controls.Page> or another <xref:System.Windows.Controls.Page>. In WPF, a content fragment is the content that is contained by a named element. A named element is an element that has its `Name` attribute set. The following markup shows a named `TextBlock` element that contains a content fragment.
[!code-xaml[NavigationOverviewSnippets#PageWithContentFragmentsMARKUP1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithFragments.xaml#pagewithcontentfragmentsmarkup1)]
[!code-xaml[NavigationOverviewSnippets#PageWithContentFragmentsMARKUP2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithFragments.xaml#pagewithcontentfragmentsmarkup2)]
[!code-xaml[NavigationOverviewSnippets#PageWithContentFragmentsMARKUP3](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithFragments.xaml#pagewithcontentfragmentsmarkup3)]
For a <xref:System.Windows.Documents.Hyperlink> to navigate to a content fragment, the `NavigateUri` attribute must include the following:
- The URI of the <xref:System.Windows.Controls.Page> with the content fragment to navigate to.
- A "#" character.
- The name of the element on the <xref:System.Windows.Controls.Page> that contains the content fragment.
A fragment URI has the following format.
*PageURI* `#` *ElementName*
The following shows an example of a `Hyperlink` that is configured to navigate to a content fragment.
[!code-xaml[NavigationOverviewSnippets#PageThatNavigatesXAML1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageThatNavigatesToFragment.xaml#pagethatnavigatesxaml1)]
[!code-xaml[NavigationOverviewSnippets#PageThatNavigatesXAML2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageThatNavigatesToFragment.xaml#pagethatnavigatesxaml2)]
[!code-xaml[NavigationOverviewSnippets#PageThatNavigatesXAML3](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageThatNavigatesToFragment.xaml#pagethatnavigatesxaml3)]
> [!NOTE]
> This section describes the default fragment navigation implementation in WPF. WPF also allows you to implement your own fragment navigation scheme which, in part, requires handling the <xref:System.Windows.Navigation.NavigationService.FragmentNavigation?displayProperty=nameWithType> event.
> [!IMPORTANT]
> You can navigate to fragments in loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages (markup-only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files with `Page` as the root element) only if the pages can be browsed via HTTP.
>
> However, a loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] page can navigate to its own fragments.
<a name="NavigationService"></a>
### Navigation Service
While <xref:System.Windows.Documents.Hyperlink> allows a user to initiate navigation to a particular <xref:System.Windows.Controls.Page>, the work of locating and downloading the page is performed by the <xref:System.Windows.Navigation.NavigationService> class. Essentially, <xref:System.Windows.Navigation.NavigationService> provides the ability to process a navigation request on behalf of client code, such as the <xref:System.Windows.Documents.Hyperlink>. Additionally, <xref:System.Windows.Navigation.NavigationService> implements higher-level support for tracking and influencing a navigation request.
When a <xref:System.Windows.Documents.Hyperlink> is clicked, WPF calls <xref:System.Windows.Navigation.NavigationService.Navigate%2A?displayProperty=nameWithType> to locate and download the <xref:System.Windows.Controls.Page> at the specified pack URI. The downloaded <xref:System.Windows.Controls.Page> is converted to a tree of objects whose root object is an instance of the downloaded <xref:System.Windows.Controls.Page>. A reference to the root <xref:System.Windows.Controls.Page> object is stored in the <xref:System.Windows.Navigation.NavigationService.Content%2A?displayProperty=nameWithType> property. The pack URI for the content that was navigated to is stored in the <xref:System.Windows.Navigation.NavigationService.Source%2A?displayProperty=nameWithType> property, while the <xref:System.Windows.Navigation.NavigationService.CurrentSource%2A?displayProperty=nameWithType> stores the pack URI for the last page that was navigated to.
> [!NOTE]
> It is possible for a WPF application to have more than one currently active <xref:System.Windows.Navigation.NavigationService>. For more information, see [Navigation Hosts](#Navigation_Hosts) later in this topic.
<a name="Programmatic_Navigation_with_the_Navigation_Service"></a>
### Programmatic Navigation with the Navigation Service
You don't need to know about <xref:System.Windows.Navigation.NavigationService> if navigation is implemented declaratively in markup using <xref:System.Windows.Documents.Hyperlink>, because <xref:System.Windows.Documents.Hyperlink> uses the <xref:System.Windows.Navigation.NavigationService> on your behalf. This means that, as long as either the direct or indirect parent of a <xref:System.Windows.Documents.Hyperlink> is a navigation host (see [Navigation Hosts](#Navigation_Hosts)), <xref:System.Windows.Documents.Hyperlink> will be able to find and use the navigation host's navigation service to process a navigation request.
However, there are situations when you need to use <xref:System.Windows.Navigation.NavigationService> directly, including the following:
- When you need to instantiate a <xref:System.Windows.Controls.Page> using a non-parameterless constructor.
- When you need to set properties on the <xref:System.Windows.Controls.Page> before you navigate to it.
- When the <xref:System.Windows.Controls.Page> that needs to be navigated to can only be determined at run time.
In these situations, you need to write code to programmatically initiate navigation by calling the <xref:System.Windows.Navigation.NavigationService.Navigate%2A> method of the <xref:System.Windows.Navigation.NavigationService> object. That requires getting a reference to a <xref:System.Windows.Navigation.NavigationService>.
#### Getting a Reference to the NavigationService
For reasons that are covered in the [Navigation Hosts](#Navigation_Hosts) section, a WPF application can have more than one <xref:System.Windows.Navigation.NavigationService>. This means that your code needs a way to find a <xref:System.Windows.Navigation.NavigationService>, which is usually the <xref:System.Windows.Navigation.NavigationService> that navigated to the current <xref:System.Windows.Controls.Page>. You can get a reference to a <xref:System.Windows.Navigation.NavigationService> by calling the `static`<xref:System.Windows.Navigation.NavigationService.GetNavigationService%2A?displayProperty=nameWithType> method. To get the <xref:System.Windows.Navigation.NavigationService> that navigated to a particular <xref:System.Windows.Controls.Page>, you pass a reference to the <xref:System.Windows.Controls.Page> as the argument of the <xref:System.Windows.Navigation.NavigationService.GetNavigationService%2A> method. The following code shows how to get the <xref:System.Windows.Navigation.NavigationService> for the current <xref:System.Windows.Controls.Page>.
[!code-csharp[NavigationOverviewSnippets#GetNSCODEBEHIND1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/GetNSPage.xaml.cs#getnscodebehind1)]
[!code-csharp[NavigationOverviewSnippets#GetNSCODEBEHIND2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/GetNSPage.xaml.cs#getnscodebehind2)]
[!code-vb[NavigationOverviewSnippets#GetNSCODEBEHIND2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/GetNSPage.xaml.vb#getnscodebehind2)]
As a shortcut for finding the <xref:System.Windows.Navigation.NavigationService> for a <xref:System.Windows.Controls.Page>, <xref:System.Windows.Controls.Page> implements the <xref:System.Windows.Controls.Page.NavigationService%2A> property. This is shown in the following example.
[!code-csharp[NavigationOverviewSnippets#GetNSShortcutCODEBEHIND1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/GetNSPageShortCut.xaml.cs#getnsshortcutcodebehind1)]
[!code-csharp[NavigationOverviewSnippets#GetNSShortcutCODEBEHIND2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/GetNSPageShortCut.xaml.cs#getnsshortcutcodebehind2)]
[!code-vb[NavigationOverviewSnippets#GetNSShortcutCODEBEHIND2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/GetNSPageShortCut.xaml.vb#getnsshortcutcodebehind2)]
> [!NOTE]
> A <xref:System.Windows.Controls.Page> can only get a reference to its <xref:System.Windows.Navigation.NavigationService> when <xref:System.Windows.Controls.Page> raises the <xref:System.Windows.FrameworkElement.Loaded> event.
#### Programmatic Navigation to a Page Object
The following example shows how to use the <xref:System.Windows.Navigation.NavigationService> to programmatically navigate to a <xref:System.Windows.Controls.Page>. Programmatic navigation is required because the <xref:System.Windows.Controls.Page> that is being navigated to can only be instantiated using a single, non-parameterless constructor. The <xref:System.Windows.Controls.Page> with the non-parameterless constructor is shown in the following markup and code.
[!code-xaml[NavigationOverviewSnippets#PageWithNonDefaultConstructorXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithNonDefaultConstructor.xaml#pagewithnondefaultconstructorxaml)]
[!code-csharp[NavigationOverviewSnippets#PageWithNonDefaultConstructorCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithNonDefaultConstructor.xaml.cs#pagewithnondefaultconstructorcodebehind)]
[!code-vb[NavigationOverviewSnippets#PageWithNonDefaultConstructorCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/PageWithNonDefaultConstructor.xaml.vb#pagewithnondefaultconstructorcodebehind)]
The <xref:System.Windows.Controls.Page> that navigates to the <xref:System.Windows.Controls.Page> with the non-parameterless constructor is shown in the following markup and code.
[!code-xaml[NavigationOverviewSnippets#NSNavigationPageXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NSNavigationPage.xaml#nsnavigationpagexaml)]
[!code-csharp[NavigationOverviewSnippets#NSNavigationPageCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NSNavigationPage.xaml.cs#nsnavigationpagecodebehind)]
[!code-vb[NavigationOverviewSnippets#NSNavigationPageCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/NSNavigationPage.xaml.vb#nsnavigationpagecodebehind)]
When the <xref:System.Windows.Documents.Hyperlink> on this <xref:System.Windows.Controls.Page> is clicked, navigation is initiated by instantiating the <xref:System.Windows.Controls.Page> to navigate to using the non-parameterless constructor and calling the <xref:System.Windows.Navigation.NavigationService.Navigate%2A?displayProperty=nameWithType> method. <xref:System.Windows.Navigation.NavigationService.Navigate%2A> accepts a reference to the object that the <xref:System.Windows.Navigation.NavigationService> will navigate to, rather than a pack URI.
#### Programmatic Navigation with a Pack URI
If you need to construct a pack URI programmatically (when you can only determine the pack URI at run time, for example), you can use the <xref:System.Windows.Navigation.NavigationService.Navigate%2A?displayProperty=nameWithType> method. This is shown in the following example.
[!code-xaml[NavigationOverviewSnippets#NSUriNavigationPageXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NSUriNavigationPage.xaml#nsurinavigationpagexaml)]
[!code-csharp[NavigationOverviewSnippets#NSUriNavigationPageCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NSUriNavigationPage.xaml.cs#nsurinavigationpagecodebehind)]
[!code-vb[NavigationOverviewSnippets#NSUriNavigationPageCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/NSUriNavigationPage.xaml.vb#nsurinavigationpagecodebehind)]
#### Refreshing the Current Page
A <xref:System.Windows.Controls.Page> is not downloaded if it has the same pack URI as the pack URI that is stored in the <xref:System.Windows.Navigation.NavigationService.Source%2A?displayProperty=nameWithType> property. To force WPF to download the current page again, you can call the <xref:System.Windows.Navigation.NavigationService.Refresh%2A?displayProperty=nameWithType> method, as shown in the following example.
[!code-xaml[NavigationOverviewSnippets#NSRefreshNavigationPageXAML1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NSRefreshNavigationPage.xaml#nsrefreshnavigationpagexaml1)]
[!code-csharp[NavigationOverviewSnippets#NSRefreshNavigationPageCODEBEHIND1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NSRefreshNavigationPage.xaml.cs#nsrefreshnavigationpagecodebehind1)]
[!code-vb[NavigationOverviewSnippets#NSRefreshNavigationPageCODEBEHIND1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/NSRefreshNavigationPage.xaml.vb#nsrefreshnavigationpagecodebehind1)]
[!code-csharp[NavigationOverviewSnippets#NSRefreshNavigationPageCODEBEHIND2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NSRefreshNavigationPage.xaml.cs#nsrefreshnavigationpagecodebehind2)]
[!code-vb[NavigationOverviewSnippets#NSRefreshNavigationPageCODEBEHIND2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/NSRefreshNavigationPage.xaml.vb#nsrefreshnavigationpagecodebehind2)]
<a name="Navigation_Lifetime"></a>
### Navigation Lifetime
There are many ways to initiate navigation, as you've seen. When navigation is initiated, and while navigation is in progress, you can track and influence the navigation using the following events that are implemented by <xref:System.Windows.Navigation.NavigationService>:
- <xref:System.Windows.Navigation.NavigationService.Navigating>. Occurs when a new navigation is requested. Can be used to cancel the navigation.
- <xref:System.Windows.Navigation.NavigationService.NavigationProgress>. Occurs periodically during a download to provide navigation progress information.
- <xref:System.Windows.Navigation.NavigationService.Navigated>. Occurs when the page has been located and downloaded.
- <xref:System.Windows.Navigation.NavigationService.NavigationStopped>. Occurs when the navigation is stopped (by calling <xref:System.Windows.Navigation.NavigationService.StopLoading%2A>), or when a new navigation is requested while a current navigation is in progress.
- <xref:System.Windows.Navigation.NavigationService.NavigationFailed>. Occurs when an error is raised while navigating to the requested content.
- <xref:System.Windows.Navigation.NavigationService.LoadCompleted>. Occurs when content that was navigated to is loaded and parsed, and has begun rendering.
- <xref:System.Windows.Navigation.NavigationService.FragmentNavigation>. Occurs when navigation to a content fragment begins, which happens:
- Immediately, if the desired fragment is in the current content.
- After the source content has been loaded, if the desired fragment is in different content.
The navigation events are raised in the order that is illustrated by the following figure.
![Page navigation flow chart](./media/navigation-overview/order-of-navigation-events.png "Page navigation event flow chart")
In general, a <xref:System.Windows.Controls.Page> isn't concerned about these events. It is more likely that an application is concerned with them and, for that reason, these events are also raised by the <xref:System.Windows.Application> class:
- <xref:System.Windows.Application.Navigating?displayProperty=nameWithType>
- <xref:System.Windows.Application.NavigationProgress?displayProperty=nameWithType>
- <xref:System.Windows.Application.Navigated?displayProperty=nameWithType>
- <xref:System.Windows.Application.NavigationFailed?displayProperty=nameWithType>
- <xref:System.Windows.Application.NavigationStopped?displayProperty=nameWithType>
- <xref:System.Windows.Application.LoadCompleted?displayProperty=nameWithType>
- <xref:System.Windows.Application.FragmentNavigation?displayProperty=nameWithType>
Every time <xref:System.Windows.Navigation.NavigationService> raises an event, the <xref:System.Windows.Application> class raises the corresponding event. <xref:System.Windows.Controls.Frame> and <xref:System.Windows.Navigation.NavigationWindow> offer the same events to detect navigation within their respective scopes.
In some cases, a <xref:System.Windows.Controls.Page> might be interested in these events. For example, a <xref:System.Windows.Controls.Page> might handle the <xref:System.Windows.Navigation.NavigationService.Navigating?displayProperty=nameWithType> event to determine whether or not to cancel navigation away from itself. This is shown in the following example.
[!code-xaml[NavigationOverviewSnippets#CancelNavigationPageXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/CancelNavigationPage.xaml#cancelnavigationpagexaml)]
[!code-csharp[NavigationOverviewSnippets#CancelNavigationPageCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/CancelNavigationPage.xaml.cs#cancelnavigationpagecodebehind)]
[!code-vb[NavigationOverviewSnippets#CancelNavigationPageCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/CancelNavigationPage.xaml.vb#cancelnavigationpagecodebehind)]
If you register a handler with a navigation event from a <xref:System.Windows.Controls.Page>, as the preceding example does, you must also unregister the event handler. If you don't, there may be side effects with respect to how WPF navigation remembers <xref:System.Windows.Controls.Page> navigation using the journal.
<a name="NavigationHistory"></a>
### Remembering Navigation with the Journal
WPF uses two stacks to remember the pages that you have navigated from: a back stack and a forward stack. When you navigate from the current <xref:System.Windows.Controls.Page> to a new <xref:System.Windows.Controls.Page> or forward to an existing <xref:System.Windows.Controls.Page>, the current <xref:System.Windows.Controls.Page> is added to the *back stack*. When you navigate from the current <xref:System.Windows.Controls.Page> back to the previous <xref:System.Windows.Controls.Page>, the current <xref:System.Windows.Controls.Page> is added to the *forward stack*. The back stack, the forward stack, and the functionality to manage them, are collectively referred to as the journal. Each item in the back stack and the forward stack is an instance of the <xref:System.Windows.Navigation.JournalEntry> class, and is referred to as a *journal entry*.
#### Navigating the Journal from Internet Explorer
Conceptually, the journal operates the same way that the **Back** and **Forward** buttons in Internet Explorer do. These are shown in the following figure.
![Back and Forward buttons](./media/navigation-overview/back-and-forward-navigation.png "Navigate with the back and forward buttons.")
For XBAPs that are hosted by Internet Explorer, WPF integrates the journal into the navigation [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] of Internet Explorer. This allows users to navigate pages in an XBAP by using the **Back**, **Forward**, and **Recent Pages** buttons in Internet Explorer.
> [!IMPORTANT]
> In Internet Explorer, when a user navigates away from and back to an XBAP, only the journal entries for pages that were not kept alive are retained in the journal. For discussion on keeping pages alive, see [Page Lifetime and the Journal](#PageLifetime) later in this topic.
By default, the text for each <xref:System.Windows.Controls.Page> that appears in the **Recent Pages** list of Internet Explorer is the URI for the <xref:System.Windows.Controls.Page>. In many cases, this is not particularly meaningful to the user. Fortunately, you can change the text using one the following options:
1. The attached `JournalEntry.Name` attribute value.
2. The `Page.Title` attribute value.
3. The `Page.WindowTitle` attribute value and the URI for the current <xref:System.Windows.Controls.Page>.
4. The URI for the current <xref:System.Windows.Controls.Page>. (Default)
The order in which the options are listed matches the order of precedence for finding the text. For example, if `JournalEntry.Name` is set, the other values are ignored.
The following example uses the `Page.Title` attribute to change the text that appears for a journal entry.
[!code-xaml[NavigationOverviewSnippets#PageTitleMARKUP1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithTitle.xaml#pagetitlemarkup1)]
[!code-xaml[NavigationOverviewSnippets#PageTitleMARKUP2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithTitle.xaml#pagetitlemarkup2)]
[!code-csharp[NavigationOverviewSnippets#PageTitleCODEBEHIND1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithTitle.xaml.cs#pagetitlecodebehind1)]
[!code-vb[NavigationOverviewSnippets#PageTitleCODEBEHIND1](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/PageWithTitle.xaml.vb#pagetitlecodebehind1)]
[!code-csharp[NavigationOverviewSnippets#PageTitleCODEBEHIND2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/PageWithTitle.xaml.cs#pagetitlecodebehind2)]
[!code-vb[NavigationOverviewSnippets#PageTitleCODEBEHIND2](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigationOverviewSnippets/VisualBasic/PageWithTitle.xaml.vb#pagetitlecodebehind2)]
#### Navigating the Journal Using WPF
Although a user can navigate the journal by using the **Back**, **Forward**, and **Recent Pages** in Internet Explorer, you can also navigate the journal using both declarative and programmatic mechanisms provided by WPF. One reason to do this is to provide custom navigation UIs in your pages.
You can declaratively add journal navigation support by using the navigation commands exposed by <xref:System.Windows.Input.NavigationCommands>. The following example demonstrates how to use the `BrowseBack` navigation command.
[!code-xaml[NavigationOverviewSnippets#NavigationCommandsPageXAML1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NavigationCommandsPage.xaml#navigationcommandspagexaml1)]
[!code-xaml[NavigationOverviewSnippets#NavigationCommandsPageXAML2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NavigationCommandsPage.xaml#navigationcommandspagexaml2)]
[!code-xaml[NavigationOverviewSnippets#NavigationCommandsPageXAML3](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NavigationCommandsPage.xaml#navigationcommandspagexaml3)]
[!code-xaml[NavigationOverviewSnippets#NavigationCommandsPageXAML4](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/NavigationCommandsPage.xaml#navigationcommandspagexaml4)]
You can programmatically navigate the journal by using one of the following members of the <xref:System.Windows.Navigation.NavigationService> class:
- <xref:System.Windows.Navigation.NavigationService.GoBack%2A>
- <xref:System.Windows.Navigation.NavigationService.GoForward%2A>
- <xref:System.Windows.Navigation.NavigationService.CanGoBack%2A>
- <xref:System.Windows.Navigation.NavigationService.CanGoForward%2A>
The journal can also be manipulated programmatically, as discussed in [Retaining Content State with Navigation History](#RetainingContentStateWithNavigationHistory) later in this topic.
<a name="PageLifetime"></a>
### Page Lifetime and the Journal
Consider an XBAP with several pages that contain rich content, including graphics, animations, and media. The memory footprint for pages like these could be quite large, particularly if video and audio media are used. Given that the journal "remembers" pages that have been navigated to, such an XBAP could quickly consume a large and noticeable amount of memory.
For this reason, the default behavior of the journal is to store <xref:System.Windows.Controls.Page> metadata in each journal entry rather than a reference to a <xref:System.Windows.Controls.Page> object. When a journal entry is navigated to, its <xref:System.Windows.Controls.Page> metadata is used to create a new instance of the specified <xref:System.Windows.Controls.Page>. As a consequence, each <xref:System.Windows.Controls.Page> that is navigated has the lifetime that is illustrated by the following figure.
![Page lifetime](./media/navigation-overview/navigated-page-lifetime.png "This shows the lifetime when a page is navigated.")
Although using the default journaling behavior can save on memory consumption, per-page rendering performance might be reduced; reinstantiating a <xref:System.Windows.Controls.Page> can be time-intensive, particularly if it has a lot of content. If you need to retain a <xref:System.Windows.Controls.Page> instance in the journal, you can draw on two techniques for doing so. First, you can programmatically navigate to a <xref:System.Windows.Controls.Page> object by calling the <xref:System.Windows.Navigation.NavigationService.Navigate%2A?displayProperty=nameWithType> method.
Second, you can specify that WPF retain an instance of a <xref:System.Windows.Controls.Page> in the journal by setting the <xref:System.Windows.Controls.Page.KeepAlive%2A> property to `true` (the default is `false`). As shown in the following example, you can set <xref:System.Windows.Controls.Page.KeepAlive%2A> declaratively in markup.
[!code-xaml[NavigationOverviewSnippets#KeepAlivePageXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/KeepAlivePage.xaml#keepalivepagexaml)]
The lifetime of a <xref:System.Windows.Controls.Page> that is kept alive is subtly different from one that is not. The first time a <xref:System.Windows.Controls.Page> that is kept alive is navigated to, it is instantiated just like a <xref:System.Windows.Controls.Page> that is not kept alive. However, because an instance of the <xref:System.Windows.Controls.Page> is retained in the journal, it is never instantiated again for as long as it remains in the journal. Consequently, if a <xref:System.Windows.Controls.Page> has initialization logic that needs to be called every time the <xref:System.Windows.Controls.Page> is navigated to, you should move it from the constructor into a handler for the <xref:System.Windows.FrameworkElement.Loaded> event. As shown in the following figure, the <xref:System.Windows.FrameworkElement.Loaded> and <xref:System.Windows.FrameworkElement.Unloaded> events are still raised each time a <xref:System.Windows.Controls.Page> is navigated to and from, respectively.
![When the Loaded and Unloaded events are raised](./media/navigation-overview/loaded-and-unloaded-events.png "Loaded and unloaded events are raised when a page is navigated to and from.")
When a <xref:System.Windows.Controls.Page> is not kept alive, you should not do either of the following:
- Store a reference to it, or any part of it.
- Register event handlers with events that are not implemented by it.
Doing either of these will create references that force the <xref:System.Windows.Controls.Page> to be retained in memory, even after it has been removed from the journal.
In general, you should prefer the default <xref:System.Windows.Controls.Page> behavior of not keeping a <xref:System.Windows.Controls.Page> alive. However, this has state implications that are discussed in the next section.
<a name="RetainingContentStateWithNavigationHistory"></a>
### Retaining Content State with Navigation History
If a <xref:System.Windows.Controls.Page> is not kept alive, and it has controls that collect data from the user, what happens to the data if a user navigates away from and back to the <xref:System.Windows.Controls.Page>? From a user experience perspective, the user should expect to see the data they entered previously. Unfortunately, because a new instance of the <xref:System.Windows.Controls.Page> is created with each navigation, the controls that collected the data are reinstantiated and the data is lost.
Fortunately, the journal provides support for remembering data across <xref:System.Windows.Controls.Page> navigations, including control data. Specifically, the journal entry for each <xref:System.Windows.Controls.Page> acts as a temporary container for the associated <xref:System.Windows.Controls.Page> state. The following steps outline how this support is used when a <xref:System.Windows.Controls.Page> is navigated from:
1. An entry for the current <xref:System.Windows.Controls.Page> is added to the journal.
2. The state of the <xref:System.Windows.Controls.Page> is stored with the journal entry for that page, which is added to the back stack.
3. The new <xref:System.Windows.Controls.Page> is navigated to.
When the page <xref:System.Windows.Controls.Page> is navigated back to, using the journal, the following steps take place:
1. The <xref:System.Windows.Controls.Page> (the top journal entry on the back stack) is instantiated.
2. The <xref:System.Windows.Controls.Page> is refreshed with the state that was stored with the journal entry for the <xref:System.Windows.Controls.Page>.
3. The <xref:System.Windows.Controls.Page> is navigated back to.
WPF automatically uses this support when the following controls are used on a <xref:System.Windows.Controls.Page>:
- <xref:System.Windows.Controls.CheckBox>
- <xref:System.Windows.Controls.ComboBox>
- <xref:System.Windows.Controls.Expander>
- <xref:System.Windows.Controls.Frame>
- <xref:System.Windows.Controls.ListBox>
- <xref:System.Windows.Controls.ListBoxItem>
- <xref:System.Windows.Controls.MenuItem>
- <xref:System.Windows.Controls.ProgressBar>
- <xref:System.Windows.Controls.RadioButton>
- <xref:System.Windows.Controls.Slider>
- <xref:System.Windows.Controls.TabControl>
- <xref:System.Windows.Controls.TabItem>
- <xref:System.Windows.Controls.TextBox>
If a <xref:System.Windows.Controls.Page> uses these controls, data entered into them is remembered across <xref:System.Windows.Controls.Page> navigations, as demonstrated by the **Favorite Color**<xref:System.Windows.Controls.ListBox> in the following figure.
![Page with controls that remember state](./media/navigation-overview/data-remembered-across-page-navigations.png "Data entered is remembered across page navigations.")
When a <xref:System.Windows.Controls.Page> has controls other than those in the preceding list, or when state is stored in custom objects, you need to write code to cause the journal to remember state across <xref:System.Windows.Controls.Page> navigations.
If you need to remember small pieces of state across <xref:System.Windows.Controls.Page> navigations, you can use dependency properties (see <xref:System.Windows.DependencyProperty>) that are configured with the <xref:System.Windows.FrameworkPropertyMetadata.Journal%2A?displayProperty=nameWithType> metadata flag.
If the state that your <xref:System.Windows.Controls.Page> needs to remember across navigations comprises multiple pieces of data, you may find it less code intensive to encapsulate your state in a single class and implement the <xref:System.Windows.Navigation.IProvideCustomContentState> interface.
If you need to navigate through various states of a single <xref:System.Windows.Controls.Page>, without navigating from the <xref:System.Windows.Controls.Page> itself, you can use <xref:System.Windows.Navigation.IProvideCustomContentState> and <xref:System.Windows.Navigation.NavigationService.AddBackEntry%2A?displayProperty=nameWithType>.
<a name="Cookies"></a>
### Cookies
Another way that WPF applications can store data is with cookies, which are created, updated, and deleted by using the <xref:System.Windows.Application.SetCookie%2A> and <xref:System.Windows.Application.GetCookie%2A> methods. The cookies that you can create in WPF are the same cookies that other types of Web applications use; cookies are arbitrary pieces of data that are stored by an application on a client machine either during or across application sessions. Cookie data typically takes the form of a name/value pair in the following format.
*Name* `=` *Value*
When the data is passed to <xref:System.Windows.Application.SetCookie%2A>, along with the <xref:System.Uri> of the location for which the cookie should be set, a cookie is created in-memory, and it is only available for the duration of the current application session. This type of cookie is referred to as a *session cookie*.
To store a cookie across application sessions, an expiration date must be added to the cookie, using the following format.
*NAME* `=` *VALUE* `; expires=DAY, DD-MMM-YYYY HH:MM:SS GMT`
A cookie with an expiration date is stored in the current Windows installation's Temporary Internet Files folder until the cookie expires. Such a cookie is known as a *persistent cookie* because it persists across application sessions.
You retrieve both session and persistent cookies by calling the <xref:System.Windows.Application.GetCookie%2A> method, passing the <xref:System.Uri> of the location where the cookie was set with the <xref:System.Windows.Application.SetCookie%2A> method.
The following are some of the ways that cookies are supported in WPF:
- WPF standalone applications and XBAPs can both create and manage cookies.
- Cookies that are created by an XBAP can be accessed from the browser.
- XBAPs from the same domain can create and share cookies.
- XBAPs and HTML pages from the same domain can create and share cookies.
- Cookies are dispatched when XBAPs and loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages make Web requests.
- Both top-level XBAPs and XBAPs hosted in IFRAMES can access cookies.
- Cookie support in WPF is the same for all supported browsers.
- In Internet Explorer, P3P policy that pertains to cookies is honored by WPF, particularly with respect to first-party and third-party XBAPs.
<a name="Structured_Navigation"></a>
### Structured Navigation
If you need to pass data from one <xref:System.Windows.Controls.Page> to another, you can pass the data as arguments to a non-parameterless constructor of the <xref:System.Windows.Controls.Page>. Note that if you use this technique, you must keep the <xref:System.Windows.Controls.Page> alive; if not, the next time you navigate to the <xref:System.Windows.Controls.Page>, WPF reinstantiates the <xref:System.Windows.Controls.Page> by using the parameterless constructor.
Alternatively, your <xref:System.Windows.Controls.Page> can implement properties that are set with the data that needs to be passed. Things become tricky, however, when a <xref:System.Windows.Controls.Page> needs to pass data back to the <xref:System.Windows.Controls.Page> that navigated to it. The problem is that navigation doesn't natively support mechanisms for guaranteeing that a <xref:System.Windows.Controls.Page> will be returned to after it is navigated from. Essentially, navigation doesn't support call/return semantics. To solve this problem, WPF provides the <xref:System.Windows.Navigation.PageFunction%601> class that you can use to ensure that a <xref:System.Windows.Controls.Page> is returned to in a predictable and structured fashion. For more information, see [Structured Navigation Overview](structured-navigation-overview.md).
<a name="The_NavigationWindow_Class"></a>
## The NavigationWindow Class
To this point, you've seen the gamut of navigation services that you are most likely to use to build applications with navigable content. These services were discussed in the context of XBAPs, although they are not limited to XBAPs. Modern operating systems and Windows applications take advantage of the browser experience of modern users to incorporate browser-style navigation into standalone applications. Common examples include:
- **Word Thesaurus**: Navigate word choices.
- **File Explorer**: Navigate files and folders.
- **Wizards**: Breaking down a complex task into multiple pages that can be navigated between. An example is the Windows Components Wizard that handles adding and removing Windows features.
To incorporate browser-style navigation into your standalone applications, you can use the <xref:System.Windows.Navigation.NavigationWindow> class. <xref:System.Windows.Navigation.NavigationWindow> derives from <xref:System.Windows.Window> and extends it with the same support for navigation that XBAPs provide. You can use <xref:System.Windows.Navigation.NavigationWindow> as either the main window of your standalone application or as a secondary window such as a dialog box.
To implement a <xref:System.Windows.Navigation.NavigationWindow>, as with most top-level classes in WPF (<xref:System.Windows.Window>, <xref:System.Windows.Controls.Page>, and so on), you use a combination of markup and code-behind. This is shown in the following example.
[!code-xaml[IntroToNavNavigationWindowSnippets#NavigationWindowMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/IntroToNavNavigationWindowSnippets/CSharp/MainWindow.xaml#navigationwindowmarkup)]
[!code-csharp[IntroToNavNavigationWindowSnippets#NavigationWindowCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/IntroToNavNavigationWindowSnippets/CSharp/MainWindow.xaml.cs#navigationwindowcodebehind)]
[!code-vb[IntroToNavNavigationWindowSnippets#NavigationWindowCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/IntroToNavNavigationWindowSnippets/VisualBasic/MainWindow.xaml.vb#navigationwindowcodebehind)]
This code creates a <xref:System.Windows.Navigation.NavigationWindow> that automatically navigates to a <xref:System.Windows.Controls.Page> (HomePage.xaml) when the <xref:System.Windows.Navigation.NavigationWindow> is opened. If the <xref:System.Windows.Navigation.NavigationWindow> is the main application window, you can use the `StartupUri` attribute to launch it. This is shown in the following markup.
[!code-xaml[IntroToNavNavigationWindowSnippets#AppLaunchNavWindow](~/samples/snippets/csharp/VS_Snippets_Wpf/IntroToNavNavigationWindowSnippets/CSharp/App.xaml#applaunchnavwindow)]
The following figure shows the <xref:System.Windows.Navigation.NavigationWindow> as the main window of a standalone application.
![A main window](./media/navigation-overview/navigation-window-as-main-window.png "Navigation window as the main window")
From the figure, you can see that the <xref:System.Windows.Navigation.NavigationWindow> has a title, even though it wasn't set in the <xref:System.Windows.Navigation.NavigationWindow> implementation code from the preceding example. Instead, the title is set using the <xref:System.Windows.Controls.Page.WindowTitle%2A> property, which is shown in the following code.
[!code-xaml[IntroToNavNavigationWindowSnippets#HomePageMARKUP1](~/samples/snippets/csharp/VS_Snippets_Wpf/IntroToNavNavigationWindowSnippets/CSharp/HomePage.xaml#homepagemarkup1)]
[!code-xaml[IntroToNavNavigationWindowSnippets#HomePageMARKUP2](~/samples/snippets/csharp/VS_Snippets_Wpf/IntroToNavNavigationWindowSnippets/CSharp/HomePage.xaml#homepagemarkup2)]
Setting the <xref:System.Windows.Controls.Page.WindowWidth%2A> and <xref:System.Windows.Controls.Page.WindowHeight%2A> properties also affects the <xref:System.Windows.Navigation.NavigationWindow>.
Usually, you implement your own <xref:System.Windows.Navigation.NavigationWindow> when you need to customize either its behavior or its appearance. If you do neither, you can use a shortcut. If you specify the pack URI of a <xref:System.Windows.Controls.Page> as the <xref:System.Windows.Application.StartupUri%2A> in a standalone application, <xref:System.Windows.Application> automatically creates a <xref:System.Windows.Navigation.NavigationWindow> to host the <xref:System.Windows.Controls.Page>. The following markup shows how to enable this.
[!code-xaml[IntroToNavNavigationWindowSnippets#AppLaunchPage](~/samples/snippets/csharp/VS_Snippets_Wpf/IntroToNavNavigationWindowSnippets/CSharp/AnotherApp.xaml#applaunchpage)]
If you want a secondary application window such as a dialog box to be a <xref:System.Windows.Navigation.NavigationWindow>, you can use the code in the following example to open it.
[!code-csharp[IntroToNavNavigationWindowSnippets#CreateNWDialogBox](~/samples/snippets/csharp/VS_Snippets_Wpf/IntroToNavNavigationWindowSnippets/CSharp/DialogOwnerWindow.xaml.cs#createnwdialogbox)]
[!code-vb[IntroToNavNavigationWindowSnippets#CreateNWDialogBox](~/samples/snippets/visualbasic/VS_Snippets_Wpf/IntroToNavNavigationWindowSnippets/VisualBasic/DialogOwnerWindow.xaml.vb#createnwdialogbox)]
The following figure shows the result.
![A dialog box](./media/navigation-overview/navigation-window-as-dialog-box.png "Navigation window as a dialog box")
As you can see, <xref:System.Windows.Navigation.NavigationWindow> displays Internet Explorer-style **Back** and **Forward** buttons that allow users to navigate the journal. These buttons provide the same user experience, as shown in the following figure.
![Back and Forward buttons in a NavigationWindow](./media/navigation-overview/back-and-forward-buttons-in-navigation-window.png "Back and Forward buttons in a Navigation window")
If your pages provide their own journal navigation support and UI, you can hide the **Back** and **Forward** buttons displayed by <xref:System.Windows.Navigation.NavigationWindow> by setting the value of the <xref:System.Windows.Navigation.NavigationWindow.ShowsNavigationUI%2A> property to `false`.
Alternatively, you can use customization support in WPF to replace the [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] of the <xref:System.Windows.Navigation.NavigationWindow> itself.
<a name="Frame_in_Standalone_Applications"></a>
## The Frame Class
Both the browser and <xref:System.Windows.Navigation.NavigationWindow> are windows that host navigable content. In some cases, applications have content that does not need to be hosted by an entire window. Instead, such content be hosted inside other content. You can insert navigable content into other content by using the <xref:System.Windows.Controls.Frame> class. <xref:System.Windows.Controls.Frame> provides the same support as <xref:System.Windows.Navigation.NavigationWindow> and XBAPs.
The following example shows how to add a <xref:System.Windows.Controls.Frame> to a <xref:System.Windows.Controls.Page> declaratively by using the `Frame` element.
[!code-xaml[NavigationOverviewSnippets#FrameHostPageXAML1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHostPage.xaml#framehostpagexaml1)]
[!code-xaml[NavigationOverviewSnippets#FrameHostPageXAML2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHostPage.xaml#framehostpagexaml2)]
[!code-xaml[NavigationOverviewSnippets#FrameHostPageXAML3](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHostPage.xaml#framehostpagexaml3)]
This markup sets the `Source` attribute of the `Frame` element with a pack URI for the <xref:System.Windows.Controls.Page> that the <xref:System.Windows.Controls.Frame> should initially navigate to. The following figure shows an XBAP with a <xref:System.Windows.Controls.Page> that has a <xref:System.Windows.Controls.Frame> that has navigated between several pages.
![A frame that has navigated between multiple pages](./media/navigation-overview/frame-navigation-between-multiple-pages.png "This shows a frame navigation between multiple pages.")
You don't only have to use <xref:System.Windows.Controls.Frame> inside the content of a <xref:System.Windows.Controls.Page>. It is also common to host a <xref:System.Windows.Controls.Frame> inside the content of a <xref:System.Windows.Window>.
By default, <xref:System.Windows.Controls.Frame> only uses its own journal in the absence of another journal. If a <xref:System.Windows.Controls.Frame> is part of content that is hosted inside either a <xref:System.Windows.Navigation.NavigationWindow> or an XBAP, <xref:System.Windows.Controls.Frame> uses the journal that belongs to the <xref:System.Windows.Navigation.NavigationWindow> or XBAP. Sometimes, though, a <xref:System.Windows.Controls.Frame> might need to be responsible for its own journal. One reason to do so is to allow journal navigation within the pages that are hosted by a <xref:System.Windows.Controls.Frame>. This is illustrated by the following figure.
![Frame and Page diagram](./media/navigation-overview/journal-navigation-within-pages-hosted-by-a-frame.png "This shows journal navigation within pages hosted by a frame.")
In this case, you can configure the <xref:System.Windows.Controls.Frame> to use its own journal by setting the <xref:System.Windows.Controls.Frame.JournalOwnership%2A> property of the <xref:System.Windows.Controls.Frame> to <xref:System.Windows.Navigation.JournalOwnership.OwnsJournal>. This is shown in the following markup.
[!code-xaml[NavigationOverviewSnippets#FrameHostPageOwnJournalXAML1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHostPageOwnJournal.xaml#framehostpageownjournalxaml1)]
[!code-xaml[NavigationOverviewSnippets#FrameHostPageOwnJournalXAML2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHostPageOwnJournal.xaml#framehostpageownjournalxaml2)]
[!code-xaml[NavigationOverviewSnippets#FrameHostPageOwnJournalXAML3](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHostPageOwnJournal.xaml#framehostpageownjournalxaml3)]
The following figure illustrates the effect of navigating within a <xref:System.Windows.Controls.Frame> that uses its own journal.
![A frame that uses its own journal](./media/navigation-overview/frame-uses-its-own-journal.png "This shows the effect of navigating within a frame that uses its own journal.")
Notice that the journal entries are shown by the navigation [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] in the <xref:System.Windows.Controls.Frame>, rather than by Internet Explorer.
> [!NOTE]
> If a <xref:System.Windows.Controls.Frame> is part of content that is hosted in a <xref:System.Windows.Window>, <xref:System.Windows.Controls.Frame> uses its own journal and, consequently, displays its own navigation [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)].
If your user experience requires a <xref:System.Windows.Controls.Frame> to provide its own journal without showing the navigation [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)], you can hide the navigation [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] by setting the <xref:System.Windows.Controls.Frame.NavigationUIVisibility%2A> to <xref:System.Windows.Visibility.Hidden>. This is shown in the following markup.
[!code-xaml[NavigationOverviewSnippets#FrameHostPageHidesUIXAML1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHostPageOwnHiddenJournal.xaml#framehostpagehidesuixaml1)]
[!code-xaml[NavigationOverviewSnippets#FrameHostPageHidesUIXAML2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHostPageOwnHiddenJournal.xaml#framehostpagehidesuixaml2)]
[!code-xaml[NavigationOverviewSnippets#FrameHostPageHidesUIXAML3](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHostPageOwnHiddenJournal.xaml#framehostpagehidesuixaml3)]
<a name="Navigation_Hosts"></a>
## Navigation Hosts
<xref:System.Windows.Controls.Frame> and <xref:System.Windows.Navigation.NavigationWindow> are classes that are known as navigation hosts. A *navigation host* is a class that can navigate to and display content. To accomplish this, each navigation host uses its own <xref:System.Windows.Navigation.NavigationService> and journal. The basic construction of a navigation host is shown in the following figure.
![Navigator diagrams](./media/navigation-overview/navigation-host-construction.png "Basic construction of a navigation host")
Essentially, this allows <xref:System.Windows.Navigation.NavigationWindow> and <xref:System.Windows.Controls.Frame> to provide the same navigation support that an XBAP provides when hosted in the browser.
Besides using <xref:System.Windows.Navigation.NavigationService> and a journal, navigation hosts implement the same members that <xref:System.Windows.Navigation.NavigationService> implements. This is illustrated by the following figure.
![A journal in a Frame and in a NavigationWindow](./media/navigation-overview/navigation-window-and-frame.png "Navigation Window and Frame")
This allows you to program navigation support directly against them. You may consider this if you need to provide a custom navigation [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] for a <xref:System.Windows.Controls.Frame> that is hosted in a <xref:System.Windows.Window>. Furthermore, both types implement additional, navigation-related members, including `BackStack` (<xref:System.Windows.Navigation.NavigationWindow.BackStack%2A?displayProperty=nameWithType>, <xref:System.Windows.Controls.Frame.BackStack%2A?displayProperty=nameWithType>) and `ForwardStack` (<xref:System.Windows.Navigation.NavigationWindow.ForwardStack%2A?displayProperty=nameWithType>, <xref:System.Windows.Controls.Frame.ForwardStack%2A?displayProperty=nameWithType>), which allow you to enumerate the journal entries in the back stack and forward stack, respectively.
As mentioned earlier, more than one journal can exist within an application. The following figure provides an example of when this can happen.
![Multiple journals within one application](./media/navigation-overview/multiple-journals-in-one-application.png "This is an example of more than one journal in an application.")
<a name="Navigating_to_Content_Other_than_Pages"></a>
## Navigating to Content Other than XAML Pages
Throughout this topic, <xref:System.Windows.Controls.Page> and pack XBAPs have been used to demonstrate the various navigation capabilities of WPF. However, a <xref:System.Windows.Controls.Page> that is compiled into an application is not the only type of content that can be navigated to, and pack XBAPs aren't the only way to identify content.
As this section demonstrates, you can also navigate to loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] files, HTML files, and objects.
<a name="Navigating_to_Loose_XAML_Files"></a>
### Navigating to Loose XAML Files
A loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file is a file with the following characteristics:
- Contains only [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] (that is, no code).
- Has an appropriate namespace declaration.
- Has the .xaml file name extension.
For example, consider the following content that is stored as a loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file, Person.xaml.
[!code-xaml[NavigationOverviewSnippets#LooseXAML](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/Person.xaml#loosexaml)]
When you double-click the file, the browser opens and navigates to and displays the content. This is shown in the following figure.
![Display of the content in the Person.XAML file](./media/navigation-overview/contents-of-person-xaml-file.png "Shows the contents of the Person.XAML file.")
You can display a loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file from the following:
- A Web site on the local machine, the intranet, or the Internet.
- A Universal Naming Convention (UNC) file share.
- The local disk.
A loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file can be added to the browser's favorites, or be the browser's home page.
> [!NOTE]
> For more information about publishing and launching loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] pages, see [Deploying a WPF Application](deploying-a-wpf-application-wpf.md).
One limitation with respect to loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] is that you can only host content that is safe to run in partial trust. For example, `Window` cannot be the root element of a loose [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] file. For more information, see [WPF Partial Trust Security](../wpf-partial-trust-security.md).
<a name="Navigating_to_HTML_Files_Using_Frame"></a>
### Navigating to HTML Files by Using Frame
As you might expect, you can also navigate to HTML. You simply need to provide a URI that uses the http scheme. For example, the following [!INCLUDE[TLA2#tla_xaml](../../../includes/tla2sharptla-xaml-md.md)] shows a <xref:System.Windows.Controls.Frame> that navigates to an HTML page.
[!code-xaml[NavigationOverviewSnippets#FrameHtmlNavMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationOverviewSnippets/CSharp/FrameHTMLNavPage.xaml#framehtmlnavmarkup)]
Navigating to HTML requires special permissions. For example, you can't navigate from an XBAP that is running in the Internet zone partial trust security sandbox. For more information, see [WPF Partial Trust Security](../wpf-partial-trust-security.md).
<a name="Navigating_to_HTML_Files_Using_WebBrowser"></a>
### Navigating to HTML Files by Using the WebBrowser Control
The <xref:System.Windows.Controls.WebBrowser> control supports HTML document hosting, navigation and script/managed code interoperability. For detailed information regarding the <xref:System.Windows.Controls.WebBrowser> control, see <xref:System.Windows.Controls.WebBrowser>.
Like <xref:System.Windows.Controls.Frame>, navigating to HTML using <xref:System.Windows.Controls.WebBrowser> requires special permissions. For example, from a partial-trust application, you can navigate only to HTML located at the site of origin. For more information, see [WPF Partial Trust Security](../wpf-partial-trust-security.md).
<a name="Navigating_to_Objects"></a>
### Navigating to Custom Objects
If you have data that is stored as custom objects, one way to display that data is to create a <xref:System.Windows.Controls.Page> with content that is bound to those objects (see [Data Binding Overview](/dotnet/desktop-wpf/data/data-binding-overview)). If you don't need the overhead of creating an entire page just to display the objects, you can navigate directly to them instead.
Consider the `Person` class that is implemented in the following code.
[!code-csharp[NavigateToObjectSnippets#PersonClassCODE](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigateToObjectSnippets/CSharp/Person.cs#personclasscode)]
[!code-vb[NavigateToObjectSnippets#PersonClassCODE](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigateToObjectSnippets/VisualBasic/Person.vb#personclasscode)]
To navigate to it, you call the <xref:System.Windows.Navigation.NavigationWindow.Navigate%2A?displayProperty=nameWithType> method, as demonstrated by the following code.
[!code-xaml[NavigateToObjectSnippets#PageThatNavsToObject1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigateToObjectSnippets/CSharp/HomePage.xaml#pagethatnavstoobject1)]
[!code-xaml[NavigateToObjectSnippets#PageThatNavsToObject2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigateToObjectSnippets/CSharp/HomePage.xaml#pagethatnavstoobject2)]
[!code-xaml[NavigateToObjectSnippets#PageThatNavsToObject3](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigateToObjectSnippets/CSharp/HomePage.xaml#pagethatnavstoobject3)]
[!code-csharp[NavigateToObjectSnippets#PageThatNavsToObjectCODEBEHIND](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigateToObjectSnippets/CSharp/HomePage.xaml.cs#pagethatnavstoobjectcodebehind)]
[!code-vb[NavigateToObjectSnippets#PageThatNavsToObjectCODEBEHIND](~/samples/snippets/visualbasic/VS_Snippets_Wpf/NavigateToObjectSnippets/VisualBasic/HomePage.xaml.vb#pagethatnavstoobjectcodebehind)]
The following figure shows the result.
![A page that navigates to a class](./media/navigation-overview/page-navigates-to-an-object.png "This is an example of a page that navigates to an object.")
From this figure, you can see that nothing useful is displayed. In fact, the value that is displayed is the return value of the `ToString` method for the **Person** object; by default, this is the only value that WPF can use to represent your object. You could override the `ToString` method to return more meaningful information, although it will still only be a string value. One technique you can use that takes advantage of the presentation capabilities of WPF is to use a data template. You can implement a data template that WPF can associate with an object of a particular type. The following code shows a data template for the `Person` object.
[!code-xaml[NavigateToObjectSnippets#DataTemplateMARKUP](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigateToObjectSnippets/CSharp/App.xaml#datatemplatemarkup)]
Here, the data template is associated with the `Person` type by using the `x:Type` markup extension in the `DataType` attribute. The data template then binds `TextBlock` elements (see <xref:System.Windows.Controls.TextBlock>) to the properties of the `Person` class. The following figure shows the updated appearance of the `Person` object.
![Navigating to a class that has a data template](./media/navigation-overview/navigating-to-a-class.png "Navigating to a class that has a data template.")
An advantage of this technique is the consistency you gain by being able to reuse the data template to display your objects consistently anywhere in your application.
For more information on data templates, see [Data Templating Overview](../data/data-templating-overview.md).
<a name="Security"></a>
## Security
WPF navigation support allows XBAPs to be navigated to across the Internet, and it allows applications to host third-party content. To protect both applications and users from harmful behavior, WPF provides a variety of security features that are discussed in [Security](../security-wpf.md) and [WPF Partial Trust Security](../wpf-partial-trust-security.md).
## See also
- <xref:System.Windows.Application.SetCookie%2A>
- <xref:System.Windows.Application.GetCookie%2A>
- [Application Management Overview](application-management-overview.md)
- [Pack URIs in WPF](pack-uris-in-wpf.md)
- [Structured Navigation Overview](structured-navigation-overview.md)
- [Navigation Topologies Overview](navigation-topologies-overview.md)
- [How-to Topics](navigation-how-to-topics.md)
- [Deploying a WPF Application](deploying-a-wpf-application-wpf.md)
dotnet-desktop-guide/framework/wpf/app-development/navigation-topologies-overview.md
+142
View File
@@ -0,0 +1,142 @@
---
title: "Navigation Topologies Overview"
ms.date: "03/30/2017"
helpviewer_keywords:
- "linear topology [WPF]"
- "fixed hierarchical topology [WPF]"
- "fixed linear topology [WPF]"
- "topologies [WPF]"
- "navigation topologies [WPF]"
- "dynamically-generated topology"
ms.assetid: 5d5ee837-629a-4933-869a-186dc22ac43d
---
# Navigation Topologies Overview
<a name="introduction"></a> This overview provides an introduction to navigation topologies in WPF. Three common navigation topologies, with samples, are subsequently discussed.
> [!NOTE]
> Before reading this topic, you should be familiar with the concept of structured navigation in WPF using page functions. For more information on both of these topics, see [Structured Navigation Overview](structured-navigation-overview.md).
This topic contains the following sections:
- [Navigation Topologies](#Navigation_Topologies)
- [Structured Navigation Topologies](#Structured_Navigation_Topologies)
- [Navigation over a Fixed Linear Topology](#Navigation_over_a_Fixed_Linear_Topology)
- [Dynamic Navigation over a Fixed Hierarchical Topology](#Dynamic_Navigation_over_a_Fixed_Hierarchical_Topology)
- [Navigation over a Dynamically Generated Topology](#Navigation_over_a_Dynamically_Generated_Topology)
<a name="Navigation_Topologies"></a>
## Navigation Topologies
In WPF, navigation typically consists of pages (<xref:System.Windows.Controls.Page>) with hyperlinks (<xref:System.Windows.Documents.Hyperlink>) that navigate to other pages when clicked. Pages that are navigated to are identified by uniform resource identifiers (URIs) (see [Pack URIs in WPF](pack-uris-in-wpf.md)). Consider the following simple example that shows pages, hyperlinks, and uniform resource identifiers (URIs):
[!code-xaml[NavigationTopologiesOverviewSnippets#Page1](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationTopologiesOverviewSnippets/CS/Page1.xaml#page1)]
[!code-xaml[NavigationTopologiesOverviewSnippets#Page2](~/samples/snippets/csharp/VS_Snippets_Wpf/NavigationTopologiesOverviewSnippets/CS/Page2.xaml#page2)]
These pages are arranged in a *navigation topology* whose structure is determined by how you can navigate between the pages. This particular navigation topology is suitable in simple scenarios, although navigation can require more complex topologies, some of which can only be defined when an application is running.
This topic covers three common navigation topologies: *fixed linear*, *fixed hierarchical*, and *dynamically generated*. Each navigation topology is demonstrated with a sample that has a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)] like the one that is shown in the following figure:
![Task pages with data items and navigation buttons.](./media/navigation-topologies-overview/navigation-topology-data-items.png)
<a name="Structured_Navigation_Topologies"></a>
## Structured Navigation Topologies
There are two broad types of navigation topologies:
- **Fixed Topology**: defined at compile time and does not change at run time. Fixed topologies are useful for navigation through a fixed sequence of pages in either a linear or hierarchical order.
- **Dynamic Topology**: defined at run time based on input that is collected from the user, the application, or the system. Dynamic topologies are useful when pages can be navigated in different sequences.
Although it is possible to create navigation topologies using pages, the samples use page functions because they provide additional support that simplifies support for passing and returning data through the pages of a topology.
<a name="Navigation_over_a_Fixed_Linear_Topology"></a>
## Navigation over a Fixed Linear Topology
A fixed linear topology is analogous to the structure of a wizard that has one or more wizard pages that are navigated in a fixed sequence. The following figure shows the high-level structure and flow of a wizard with a fixed linear topology:
![Diagram that shows a fixed linear topology.](./media/navigation-topologies-overview/navigation-topology-fixed-linear.png)
The typical behaviors for navigating over a fixed linear topology include the following:
- Navigating from the calling page to a launcher page that initializes the wizard and navigates to the first wizard page. A launcher page (a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]-less <xref:System.Windows.Navigation.PageFunction%601>) is not required, since a calling page can call the first wizard page directly. Using a launcher page, however, can simplify wizard initialization, particularly if initialization is complex.
- Users can navigate between pages by using Back and Forward buttons (or hyperlinks).
- Users can navigate between pages using the journal.
- Users can cancel the wizard from any wizard page by pressing a Cancel button.
- Users can accept the wizard on the last wizard page by pressing a Finish button.
- If a wizard is canceled, the wizard returns an appropriate result, and does not return any data.
- If a user accepts a wizard, the wizard returns an appropriate result, and returns the data it collected.
- When the wizard is complete (accepted or canceled), the pages that the wizard comprises are removed from the journal. This keeps each instance of the wizard isolated, thereby avoiding potential data or state anomalies.
<a name="Dynamic_Navigation_over_a_Fixed_Hierarchical_Topology"></a>
## Dynamic Navigation over a Fixed Hierarchical Topology
In some applications, pages allow navigation to two or more other pages, as shown in the following figure:
![Diagram that shows a page that can navigate to multiple pages.](./media/navigation-topologies-overview/navigation-topology-multiple-pages.png)
This structure is known as a fixed hierarchical topology, and the sequence in which the hierarchy is traversed is often determined at run time by either the application or the user. At run time, each page in the hierarchy that allows navigation to two or more other pages gathers the data required to determine which page to navigate to. The following figure illustrates one of several possible navigation sequences based on the previous figure:
![Diagram that shows a possible navigation sequence.](./media/navigation-topologies-overview/navigation-topology-fixed-hierarchical.png)
Even though the sequence in which pages in a fixed hierarchical structure are navigated is determined at run time, the user experience is the same as the user experience for a fixed linear topology:
- Navigating from the calling page to a launcher page that initializes the wizard and navigates to the first wizard page. A launcher page (a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]-less <xref:System.Windows.Navigation.PageFunction%601>) is not required, since a calling page can call the first wizard page directly. Using a launcher page, however, can simplify wizard initialization, particularly if initialization is complex.
- Users can navigate between pages by using Back and Forward buttons (or hyperlinks).
- Users can navigate between pages using the journal.
- Users can change the navigation sequence if they navigate back through the journal.
- Users can cancel the wizard from any wizard page by pressing a Cancel button.
- Users can accept the wizard on the last wizard page by pressing a Finish button.
- If a wizard is canceled, the wizard returns an appropriate result, and does not return any data.
- If a user accepts a wizard, the wizard returns an appropriate result, and returns the data it collected.
- When the wizard is complete (accepted or canceled), the pages that the wizard comprises are removed from the journal. This keeps each instance of the wizard isolated, thereby avoiding potential data or state anomalies.
<a name="Navigation_over_a_Dynamically_Generated_Topology"></a>
## Navigation over a Dynamically Generated Topology
In some applications, the sequence in which two or more pages are navigated can only be determined at run time, whether by the user, the application, or external data. The following figure illustrates a set of pages with an undetermined navigation sequence:
![A set of pages with an undetermined navigation sequence.](./media/navigation-topologies-overview/navigation-topology-dynamically-generated.png)
The next figure illustrates a navigation sequence that was chosen by the user at run time:
![Diagram that shows a navigation sequence chosen at run time.](./media/navigation-topologies-overview/navigation-topology-sequence-chosen-run-time.png)
The navigation sequence is known as a dynamically generated topology. For the user, as with the other navigation topologies, the user experience is the same as it is for the previous topologies:
- Navigating from the calling page to a launcher page that initializes the wizard and navigates to the first wizard page. A launcher page (a [!INCLUDE[TLA2#tla_ui](../../../includes/tla2sharptla-ui-md.md)]-less <xref:System.Windows.Navigation.PageFunction%601>) is not required, since a calling page can call the first wizard page directly. Using a launcher page, however, can simplify wizard initialization, particularly if initialization is complex.
- Users can navigate between pages by using Back and Forward buttons (or hyperlinks).
- Users can navigate between pages using the journal.
- Users can cancel the wizard from any wizard page by pressing a Cancel button.
- Users can accept the wizard on the last wizard page by pressing a Finish button.
- If a wizard is canceled, the wizard returns an appropriate result, and does not return any data.
- If a user accepts a wizard, the wizard returns an appropriate result, and returns the data it collected.
- When the wizard is complete (accepted or canceled), the pages that the wizard comprises are removed from the journal. This keeps each instance of the wizard isolated, thereby avoiding potential data or state anomalies.
## See also
- <xref:System.Windows.Controls.Page>
- <xref:System.Windows.Navigation.PageFunction%601>
- <xref:System.Windows.Navigation.NavigationService>
- [Structured Navigation Overview](structured-navigation-overview.md)

Some files were not shown because too many files have changed in this diff Show More