[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]
XAML browser applications (XBAPs) combines features of both Web applications and rich-client applications. Like Web applications, XBAPs can be deployed to a Web server and started from Internet Explorer or Firefox. Like rich-client applications, XBAPs can take advantage of the capabilities of WPF. Developing XBAPs is also similar to rich-client development. This topic provides a simple, high-level introduction to XBAP development and describes where XBAP development differs from standard rich-client development.
This topic contains the following sections:
Creating a New XAML Browser Application (XBAP)
The simplest way to create a new XBAP project is with Microsoft Visual Studio 2010:
On the File menu, point to New, and then click Project.
In the New Project dialog box, in the left pane, select either Visual Basic or Visual C#.
In the list of templates, select WPF Browser Application.
Specify a name and location, and then click OK to create the new project.
The WPF Browser Application project template creates an XBAP project that includes the following files:
When you run the XBAP project, it opens in a browser window instead of a stand-alone window. When you debug the XBAP from Visual Studio, the application runs with Internet zone permission and will therefore throw security exceptions if those permissions are exceeded. For more information, see Building a WPF Application (WPF).
When you build an XBAP, the output includes the following three files:
File | Description |
|---|
Executable (.exe) | This contains the compiled code and has an .exe extension. |
Application manifest (.manifest) | This contains metadata associated with the application and has a .manifest extension. |
Deployment manifest (.xbap) | This file contains the information that ClickOnce uses to deploy the application and has the .xbap extension. |
You deploy XBAPs to a Web server, for example,Microsoft Internet Information Services (IIS) 5.0 or later versions. You do not have to install the .NET Framework on the Web server, but you do have to register the WPF Multipurpose Internet Mail Extensions (MIME) types and file name extensions. For more information, see How to: Configure IIS 5.0 and IIS 6.0 to Deploy WPF Applications.
To prepare your XBAP for deployment, copy the .exe and the associated manifests to the Web server. Create an HTML page that contains a hyperlink to open the deployment manifest, which is the file that has the .xbap extension. When the user clicks the link to the .xbap file, ClickOnce automatically handles the mechanics of downloading and starting the application. The following example code shows an HTML page that contains a hyperlink that points to an XBAP.
<html>
<head></head>
<body>
<a href="XbapEx.xbap">Click this link to launch the application</a>
</body>
</html>
You can also host an XBAP in the frame of a Web page. Create a Web page with one or more frames. Set the source property of a frame to the deployment manifest file. If you want to use the built-in mechanism to communicate between the hosting Web page and the XBAP, you must host the application in a frame. The following example code shows an HTML page with two frames, the source for the second frame is set to an XBAP.
<html>
<head>A page with frames.</head>
<frameset cols="50%,50%">
<frame src="introduction.htm" >
<frame src="XbapEx.xbap" >
</frameset>
</html>
Clearing Cached XBAPs
In some situations after rebuilding and starting your XBAP, you may find that an earlier version of the XBAP is opened. For example, this behavior may occur when your XBAP assembly version number is static and you start the XBAP from the command line. In this case, because the version number between the cached version (the version that was previously started) and the new version remains the same, the new version of the XBAP is not downloaded. Instead, the cached version is loaded.
In these situations, you can remove the cached version by using the Mage command (installed with Visual Studio or the Windows SDK) at the command prompt. The following command clears the application cache.
Mage.exe -cc
This command guarantees that the latest version of your XBAP is started. When you debug your application in Visual Studio, the latest version of your XBAP should be started. In general, you should update your deployment version number with each build. For more information about Mage, see Mage.exe (Manifest Generation and Editing Tool).
Communicating with the Host Web Page
When the application is hosted in an HTML frame, you can communicate with the Web page that contains the XBAP. You do this by retrieving the HostScript property of BrowserInteropHelper. This property returns a script object that represents the HTML window. You can then access the properties, methods, and events on the window object by using regular dot syntax. You can also access script methods and global variables. The following example shows how to retrieve the script object and close the browser.
Private Sub Button_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
' Retrieve the script object The XBAP must be hosted in a frame or
' the HostScript object will be null.
Dim scriptObject = BrowserInteropHelper.HostScript
' Call close to close the browser window.
scriptObject.Close()
End Sub
private void Button_Click(object sender, RoutedEventArgs e)
{
// Retrieve the script object. The XBAP must be hosted in a frame or
// the HostScript object will be null.
var scriptObject = BrowserInteropHelper.HostScript;
// Call close to close the browser window.
scriptObject.Close();
}
Debugging XBAPs that Use HostScript
If your XBAP uses the HostScript object to communicate with the HTML window, there are two settings that you must specify to run and debug the application in Visual Studio. The application must have access to its site of origin and you must start the application with the HTML page that contains the XBAP. The following steps describe how to check these two settings:
In Visual Studio, open the project properties.
On the Security tab, click Advanced.
In the Advanced Security Setting dialog box, make sure that the Grant the application access to its site of origin check box is checked.
On the Debug tab, select the Start browser with URL option and specify the URL for the HTML page that contains the XBAP.
.gif) Note |
|---|
When you run the application, you may receive a warning that Internet Explorer has blocked the content because of security reasons. If this occurs, right-click the warning, select Allow Blocked Content, and the application will continue. |
XBAP Security Considerations
XBAPs typically execute in a partial-trust security sandbox that is restricted to the Internet zone permission set. Consequently, your implementation must support the subset of WPF elements that are supported in the Internet zone or you must elevate the permissions of your application. For more information, see WPF Security.
When you host the WebBrowser ActiveX control (WebOC) in the Internet Explorer browser process, the following security limitations apply.
Internet Explorer blocks modal dialog boxes from the DHTML alert function and ActiveX controls hosted in HTML. Internet Explorer suppresses dialog boxes that originate from threads other than the active tab’s thread.
Hosting the WebOC control raises an exception when an XBAP is loaded cross-domain in an HTML page.
Creating a Full-Trust XBAP
If your XBAP requires full trust, you can change your project to enable this permission. The following steps describe how to enable full trust:
In Visual Studio, right-click the project and select Properties.
On the Security tab, select the This is a full trust application option.
This setting makes the following changes:
In the project file, the <TargetZone> element value is changed to Custom.
In the application manifest (app.manifest), an Unrestricted="true" attribute is added to the PermissionSet element.
<PermissionSet class="System.Security.PermissionSet"
version="1"
ID="Custom"
SameSite="site"
Unrestricted="true"
/>
Deploying a Full-Trust XBAP
When you deploy a full-trust XBAP that does not follow the ClickOnce Trusted Deployment model, the behavior when the user runs the application will depend on the security zone. In some cases, the user will receive a warning when they attempt to install it. The user can choose to continue or cancel the installation. The following table describes the behavior of the application for each security zone and what you have to do for the application to receive full trust.
Security Zone | Behavior | Getting Full Trust |
|---|
Local computer | Automatic full trust | No action is needed. |
Intranet and trusted sites | Prompt for full trust | Sign the XBAP with a certificate so that the user sees the source in the prompt. |
Internet | Fails with "Trust Not Granted" | Sign the XBAP with a certificate. |
| Note |
|---|
The behavior described in the previous table is for full-trust XBAPs that do not follow the ClickOnce Trusted Deployment model. |
It is recommended that you use the ClickOnce Trusted Deployment model for deploying a full-trust XBAP. This model allows your XBAP to be granted full trust automatically, regardless of the security zone, so that the user is not prompted. As part of this model, you must sign your application with a certificate from a trusted publisher. For more information, see Trusted Application Deployment Overview and Introduction to Code Signing.
XBAP Start Time Performance Considerations
An important aspect of XBAP performance is its start time. If an XBAP is the first WPF application to load, the cold start time can be ten seconds or more. This is because the progress page is rendered by WPF, and both the CLR and WPF must be cold-started to display the application.
Starting in .NET Framework 3.5 SP1, XBAP cold-start time is mitigated by displaying an unmanaged progress page early in the deployment cycle. The progress page appears almost immediately after the application is started, because it is displayed by native hosting code and rendered in HTML.
In addition, improved concurrency of the ClickOnce download sequence improves the start time by up to ten percent. After ClickOnce downloads and validates manifests, the application download starts, and the progress bar starts to update.
Tasks
Concepts