Finally! A Managed WebBrowser
The strength of the COM interoperability services in the .NET Framework is excellent. Despite the strength of the APIs and the flexibility of Visual Studio .NET for hiding how complex it can be to use the System.Runtime.InteropServices
namespace, you most likely found that using complex COM objects or ActiveX controls can produce less than perfect results in some cases. The WebBrowser
object found in Shdocvw.dll
is a fair example. This ActiveX component provides the Web page and HTML visual rendering services of Internet Explorer. Through COM interop, it was trivial to use this browser component on a WinForm application, but a few desirable features did not exist, or were complicated to implement.
The new managed WebBrowser
class is found in the System.Windows.Forms
namespace and extends the functionality provided by the underlying ActiveX control. The rendering behavior did not change, but events have been cleaned up and reorganized, and additional information is available in certain events. Many new properties provide functionality not easily accessible through the underlying browser component.
The WebBrowser class exposes several core navigation events you can handle to process the loading of a document. The primary navigation-related events, in chronological order, are:
event can be cancelled if desired conditions do not exist. The Navigating event wraps and replaces the BeforeNavigate2
event of the underlying component, which was not handled correctly when using a generic COM-interop assembly wrapper. You can use the Stop
method to cancel any active loading operation and the Refresh
method to force the WebBrowser class to load the desired document.
Navigation is initiated by the WebBrowser object whenever one of the following methods is executed:
Table 1: The WebBrowser methods provide core navigation and dialog box display features expected in a browsing control.
- A more complete list of methods provided by the WebBrowser class is provided in Table 1
Navigates to the previous document in the navigation list if one exists. The return value indicates whether a previous entry is available.
Navigates to the subsequent document in the navigation list if one exists. The return value indicates whether a subsequent entry is available.
Navigates to the Home page configured by Internet Explorer.
Navigates to the Search page configured by Internet Explorer.
Basic navigation method used to initiate navigation to a document found at the specified URL
Sends the currently loaded document to the printer as specified by the current default printer settings
Reloads the document currently displayed in the WebBrowser control by checking the server for an updated version
Opens the Internet Explorer Page Setup dialog box
Opens the Internet Explorer Print dialog box
Opens the Internet Explorer Print Preview dialog box
Opens the Internet Explorer Page Properties dialog box
Opens the Internet Explorer Save As dialog box
Cancels any pending navigation and stops any dynamic page elements, such as background sounds and animations.
Navigation is also initiated when one of the following properties is changed:
|Figure 6. Using the Managed WebBrowser: The new managed WebBrowser class wraps and significantly extends the features previously requiring a generic COM-interop assembly, wrapping the WebBrowser ActiveX control found in shdocvw.dll.|
event is your primary mechanism for processing a loaded Web page. When handling this event, you access the Web page contents through the Document
, or DocumentStream
properties. Manually setting the DocumentText
properties causes the WebBrowser class to first navigate to about:blank
. This provides a fully instantiated document object to hold the page contents.
By using the same icons found on the Internet Explorer toolbars, I approximated the look of Internet Explorer. This is a simple example of leveraging the WebBrowser control to create a custom browser application. An example of combining a couple of WinBar controls and a WebBrowser control onto a form is shown in Figure 6
event should be handled to execute code before the Internet Explorer File Download dialog box is displayed. You should handle this event if you want to cancel a file download operation. If you want to cancel the loading of a new browser window, handle the NewWindow
event that is raised before a new browser window is opened. Additional events provided by the WebBrowser class are listed in Table 2
Table 2: WebBrowser events provide critical feedback on the navigation process to allow the implementation of all the standard visual indicators to the application user.
Changing the CanGoBack property raises this event.
Changing the CanGoForward property raises this event.
Raised when the WebBrowser control finishes loading a document. This is the primary event used to process Web pages after loading.
Changing the DocumentTitle property raises this event.
Navigating to or away from a Web site that uses encryption raises this event.
Raised before the WebBrowser control begins downloading
Raised after the WebBrowser control has navigated to a new document but before it has begun loading
Raised before the WebBrowser control navigates to a new document
Raised before a new browser window is opened
Raised when the WebBrowser control has updated information on the download progress of a document it is navigating to. Typically used to modify a progress bar.
The WebBrowser class provides several properties used to leverage extended functionality that is enhanced beyond the behavior directly exposed by the underlying browser component through generic COM-interop wrappers. The AllowWebBrowserDrop
property is set to True
to allow the WebBrowser object to automatically navigate to and load a document dragged and dropped onto the control. Set this property to False
to disable it. Set the ScriptErrorsSuppressed
property to True
to disable the display of the scripting error dialog box in response to errors raised within script embedded in a Web page being loaded.
If you want to disable user interaction with the WebBrowser control and the loaded document, use the IsWebBrowserContextMenuEnabled
properties. Set these properties to False
to disable the most common methods of user/Web page interaction. Additional properties of the WebBrowser class are listed in Table 3
Table 3: The WebBrowser class exposes many useful properties, including many extended properties beyond the core set provided by the underlying Internet Explorer component.
Controls whether the WebBrowser control automatically loads and renders a document dropped onto it. Set to False to assist in concealing the use of the WebBrowser control. Default value is True.
Indicates whether a previous entry in the navigation list exists. If True, the WebBrowser control can successfully navigate to a previous location.
Indicates whether a subsequent entry exists in the navigation list. If True, the WebBrowser control can navigate to the next location in the list.
An HtmlDocument object representing the document currently loaded. The HtmlDocument provides an HTML document object model view of the page and allows programmatic manipulation of the HTML items contained in the Web page.
A Stream object used to get or set the contents of the page currently loaded in the WebBrowser control
Represents the HTML contents of the page displayed in the WebBrowser control. A value of "" is returned or used when no document is loaded.
Read-only value representing the title of the Web page, as defined by the HTML <title> element. Often used to set the text value in the title bar of a form.
The Multipurpose Internet Mail Extensions (MIME) type of the document loaded in the WebBrowser control.
Indicates whether a new document is currently loading
Indicates whether the WebBrowser control is in offline mode. In offline mode, pages are loaded from the local cache.
Determines whether the standard context menu normally displayed when right-clicking on a Web page is shown by the WebBrowser control. Set to False to control user interactions with the loaded document.
Determines the object accessible by scripting code contained within a Web page loaded in the WebBrowser control.
Indicates the current state of the WebBrowser control. Used to provide more information than the IsBusy property.
Indicates whether the WebBrowser control should display scripting error dialog boxes or suppressed them.
Location of the currently loaded document
Retrieves the version of Internet Explorer installed
Retrieves or sets whether keyboard shortcuts are enabled within the WebBrowser control
If you want to enable two-way communication between managed code and client-side script contained within a Web page, use the ObjectForScripting
property. Set this property to the object you want referenced by any Web page scripting code when a reference to window.external
is made in the script. The window.external
object is a built-in DOM object that provides access to the host application of the Web page. Specifically, this provides the page script with a late-bound reference to a managed object and enables communication from the Web page to a managed object.
To make the communication channel two-way, you use the Document
property of the WebBrowser instance. This property is an HtmlDocument
object instance and provides a managed wrapper around the COM-based MSHTML library. This library is also known as the Microsoft HTML Object Library and it provides you with access to elements within the Web page through the document object model, completing the two-way programmatic communication channel. Use the System.Windows.Forms.InvokeScript
method to directly script methods provided by the Web page.