Click or drag to resize

ChromiumWebBrowser Class

Version 130.1.90
An offscreen instance of Chromium that you can use to take snapshots or evaluate JavaScript.
Inheritance Hierarchy
SystemObject
  CefSharp.OffScreenChromiumWebBrowser

Namespace: CefSharp.OffScreen
Assembly: CefSharp.OffScreen (in CefSharp.OffScreen.dll) Version: 129.0.110.0 (129.0.110.0)
Syntax
public class ChromiumWebBrowser : IWebBrowser, 
	IChromiumWebBrowserBase, IDisposable

The ChromiumWebBrowser type exposes the following members.

Constructors
 NameDescription
Public methodChromiumWebBrowser(HtmlString, IBrowserSettings, IRequestContext, Boolean, ActionIBrowser, Boolean) Create a new OffScreen Chromium Browser. If you use LegacyBindingEnabled = true then you must set automaticallyCreateBrowser to false and call CreateBrowser(IWindowInfo, IBrowserSettings) after the objects are registered. The underlying Chromium Embedded Framework(CEF) Browser is created asynchronouly, to subscribe to the BrowserInitialized event it is recommended that you set automaticallyCreateBrowser to false, subscribe to the event and then call CreateBrowser(IWindowInfo, IBrowserSettings) to ensure you are subscribe to the event before it's fired (Issue https://github.com/cefsharp/CefSharp/issues/3552).
Public methodChromiumWebBrowser(String, IBrowserSettings, IRequestContext, Boolean, ActionIBrowser, Boolean) Create a new OffScreen Chromium Browser. If you use LegacyBindingEnabled = true then you must set automaticallyCreateBrowser to false and call CreateBrowser(IWindowInfo, IBrowserSettings) after the objects are registered. The underlying Chromium Embedded Framework(CEF) Browser is created asynchronouly, to subscribe to the BrowserInitialized event it is recommended that you set automaticallyCreateBrowser to false, subscribe to the event and then call CreateBrowser(IWindowInfo, IBrowserSettings) to ensure you are subscribe to the event before it's fired (Issue https://github.com/cefsharp/CefSharp/issues/3552).
Top
Properties
 NameDescription
Public propertyAccessibilityHandler Implement IAccessibilityHandler to handle events related to accessibility.
Public propertyAddress The address (URL) which the browser control is currently displaying. Will automatically be updated as the user navigates to another page (e.g. by clicking on a link).
Public propertyAudioHandler Implement IAudioHandler to handle audio events.
Public propertyBrowserCore Get access to the core IBrowser instance. Maybe null if the underlying CEF Browser has not yet been created or if this control has been disposed. Check IsDisposed before accessing.
Public propertyCanExecuteJavascriptInMainFrame A flag that indicates if you can execute javascript in the main frame. Flag is set to true in IRenderProcessMessageHandler.OnContextCreated. and false in IRenderProcessMessageHandler.OnContextReleased
Public propertyCanGoBack A flag that indicates whether the state of the control current supports the GoBack action (true) or not (false).
Public propertyCanGoForward A flag that indicates whether the state of the control currently supports the GoForward action (true) or not (false).
Public propertyDeviceScaleFactor Device scale factor. Specifies the ratio between physical and logical pixels.
Public propertyDialogHandler Implement IDialogHandler and assign to handle dialog events.
Public propertyDisplayHandler Implement IDisplayHandler and assign to handle events related to browser display state.
Public propertyDownloadHandler Implement IDownloadHandler and assign to handle events related to downloading files.
Public propertyDragHandler Implement IDragHandler and assign to handle events related to dragging.
Public propertyFindHandler Implement IFindHandler to handle events related to find results.
Public propertyFocusHandler The IFocusHandler for this ChromiumWebBrowser.
Public propertyFrameHandler Implement IFrameHandler to handle frame events.
Public propertyIsBrowserInitialized A flag that indicates whether the WebBrowser is initialized (true) or not (false).
Public propertyIsDisposed Gets a value indicating whether this instance is disposed.
Public propertyIsLoading A flag that indicates whether the control is currently loading one or more web pages (true) or not (false).
Public propertyJavascriptObjectRepository The javascript object repository, one repository per ChromiumWebBrowser instance.
Public propertyJsDialogHandler Implement IJsDialogHandler and assign to handle events related to JavaScript Dialogs.
Public propertyKeyboardHandler Implement IKeyboardHandler and assign to handle events related to key press.
Public propertyLifeSpanHandler Implement ILifeSpanHandler and assign to handle events related to popups.
Public propertyLoadHandler Implement ILoadHandler and assign to handle events related to browser load status.
Public propertyMenuHandler Implement IContextMenuHandler and assign to handle events related to the browser context menu
Public propertyPermissionHandler Implement IPermissionHandler to handle events related to permission requests.
Public propertyRenderHandler Implement IRenderHandler and assign to handle events related to browser rendering.
Public propertyRenderProcessMessageHandler Implement IRenderProcessMessageHandler and assign to handle messages from the render process.
Public propertyRequestContext Gets the request context.
Public propertyRequestHandler Implement IRequestHandler and assign to handle events related to browser requests.
Public propertyResourceRequestHandlerFactory Implement IResourceRequestHandlerFactory and control the loading of resources
Public propertySize Get/set the size of the Chromium viewport, in pixels. This also changes the size of the next rendered bitmap.
Public propertyTooltipText The text that will be displayed as a ToolTip
Top
Methods
 NameDescription
Public methodCaptureScreenshotAsync Capture page screenshot.
Public methodCreateBrowser Create the underlying browser. The instance address, browser settings and request context will be used.
Public methodCreateBrowserAsync Create the underlying CEF browser. The address and request context passed into the constructor will be used. If a ActionT delegate was passed into the constructor it will not be called as this method overrides that value internally.
Public methodDispose Releases all resources used by the ChromiumWebBrowser object
Protected methodDispose(Boolean) Releases unmanaged and - optionally - managed resources for the ChromiumWebBrowser
Public methodEqualsDetermines whether the specified object is equal to the current object.
(Inherited from Object)
Protected methodFinalize Finalizes an instance of the ChromiumWebBrowser class.
(Overrides ObjectFinalize)
Public methodGetBrowser Returns the current CEF Browser Instance
Public methodGetContentSizeAsync Size of scrollable area in CSS pixels
Public methodGetHashCodeServes as the default hash function.
(Inherited from Object)
Protected methodGetScreenInfo Gets the screen information (scale factor).
Protected methodGetScreenPoint Called to retrieve the translation from view coordinates to actual screen coordinates.
Public methodGetTypeGets the Type of the current instance.
(Inherited from Object)
Protected methodGetViewRect Gets the view rect (width, height)
Public methodLoad Loads the specified url in the Main Frame. If IsDisposed is true then the method call will be ignored. Same as calling LoadUrl(String)
Public methodLoadUrl Loads the specified url in the Main Frame. Same as calling Load(String)
Public methodLoadUrlAsync Load the url in the main frame of the browser
Protected methodMemberwiseCloneCreates a shallow copy of the current Object.
(Inherited from Object)
Public methodResizeAsync Resize the browser
Public methodScreenshotAsyncObsolete.
Starts a task that waits for the next rendering from Chrome. Chrome also renders the page loading, so if you want to see a complete rendering, only start this task once your page is loaded (which you can detect via FrameLoadEnd or your own heuristics based on evaluating JavaScript). It is your responsibility to dispose the returned Bitmap. The bitmap size is determined by the Size property set earlier.
Public methodScreenshotOrNull Immediately returns a copy of the last rendering from Chrome, or null if no rendering has occurred yet. Chrome also renders the page loading, so if you want to see a complete rendering, only start this task once your page is loaded (which you can detect via FrameLoadEnd or your own heuristics based on evaluating JavaScript). It is your responsibility to dispose the returned Bitmap. The bitmap size is determined by the Size property set earlier.
Public methodToStringReturns a string that represents the current object.
(Inherited from Object)
Public methodTryGetBrowserCoreById Try and get a reference to the IBrowser instance that matches the browserId. Primarily used for geting a reference to the IBrowser used by popups.
Public methodWaitForInitialLoadAsync Wait for the Browser to finish loading the initial web page.
Public methodCode exampleWaitForNavigationAsync This resolves when the browser navigates to a new URL or reloads. It is useful for when you run code which will indirectly cause the browser to navigate. A common use case would be when executing javascript that results in a navigation. e.g. clicks a link This must be called before executing the action that navigates the browser. It may not resolve correctly if called after.
Public methodWaitForRenderIdleAsync Waits for the page rendering to be idle for idleTimeInMs. Rendering is considered to be idle when no Paint events have occured for idleTimeInMs. This is useful for scenarios like taking a screen shot.
Top
Events
 NameDescription
Public eventAddressChanged Occurs when the browser address changed. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread. (The exception to this is when you're running with settings.MultiThreadedMessageLoop = false, then they'll be the same thread).
Public eventBrowserInitialized Event called after the underlying CEF browser instance has been created. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread. (The exception to this is when you're running with settings.MultiThreadedMessageLoop = false, then they'll be the same thread).
Public eventConsoleMessage Event handler for receiving Javascript console messages being sent from web pages. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread. (The exception to this is when you're running with settings.MultiThreadedMessageLoop = false, then they'll be the same thread).
Public eventFrameLoadEnd Event handler that will get called when the browser is done loading a frame. Multiple frames may be loading at the same time. Sub-frames may start or continue loading after the main frame load has ended. This method will always be called for all frames irrespective of whether the request completes successfully. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread.
Public eventFrameLoadStart Event handler that will get called when the browser begins loading a frame. Multiple frames may be loading at the same time. Sub-frames may start or continue loading after the main frame load has ended. This method may not be called for a particular frame if the load request for that frame fails. For notification of overall browser load status use OnLoadingStateChange instead. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread.
Public eventJavascriptMessageReceived Event handler that will get called when the message that originates from CefSharp.PostMessage
Public eventLoadError Event handler that will get called when the resource load for a navigation fails or is canceled. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread.
Public eventLoadingStateChanged Event handler that will get called when the Loading state has changed. This event will be fired twice. Once when loading is initiated either programmatically or by user action, and once when loading is terminated due to completion, cancellation of failure. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread.
Public eventPaint Fired on the CEF UI thread, which by default is not the same as your application main thread. Called when an element should be painted. Pixel values passed to this method are scaled relative to view coordinates based on the value of ScreenInfo.DeviceScaleFactor returned from GetScreenInfo.
Public eventStatusMessage Event handler for changes to the status message. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread. (The exception to this is when you're running with settings.MultiThreadedMessageLoop = false, then they'll be the same thread).
Public eventTitleChanged Occurs when [title changed]. It's important to note this event is fired on a CEF UI thread, which by default is not the same as your application UI thread. It is unwise to block on this thread for any length of time as your browser will become unresponsive and/or hang.. To access UI elements you'll need to Invoke/Dispatch onto the UI Thread. (The exception to this is when you're running with settings.MultiThreadedMessageLoop = false, then they'll be the same thread).
Top
Fields
Extension Methods
 NameDescription
Public Extension MethodAddWordToDictionary Add the specified word to the spelling dictionary.
(Defined by WebBrowserExtensions)
Public Extension MethodBack Navigates back, must check CanGoBack before calling this method.
(Defined by WebBrowserExtensions)
Public Extension MethodCloseDevTools Explicitly close the developer tools window if one exists for this browser instance.
(Defined by WebBrowserExtensions)
Public Extension MethodCopy Execute Copy on the focused frame.
(Defined by WebBrowserExtensions)
Public Extension MethodCut Execute Cut on the focused frame.
(Defined by WebBrowserExtensions)
Public Extension MethodDelete Execute Delete on the focused frame.
(Defined by WebBrowserExtensions)
Public Extension MethodCode exampleDestroyWindow Manually call https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-destroywindow passing in the handle returned from GetWindowHandle. This method can be used to manually close the underlying CefBrowser instance. This will avoid the WM_Close message that CEF sends by default to the top level window. (Which closes your application). This method should generally only be used in the WinForms version.
(Defined by WebBrowserExtensions)
Public Extension MethodDisposeDevToolsContext Dispose of the DevToolsContext (if any). Used in conjunction with CefSharp.Dom
(Defined by WebBrowserExtensions)
Public Extension MethodEnsureObjectBoundAsync Make sure an object is bound in javascript. Executes against the main frame
(Defined by JavascriptBindingExtensions)
Public Extension MethodEvaluateScriptAsPromiseAsync Evaluate Javascript in the context of the MainFrame of the ChromiumWebBrowser. The script will be executed asynchronously and the method returns a Task encapsulating the response from the Javascript. The result of the script execution in javascript is Promise.resolve so even no promise values will be treated as a promise. Your javascript should return a value. The javascript will be wrapped in an Immediately Invoked Function Expression. When the promise either trigger then/catch this returned Task will be completed.
(Defined by WebBrowserExtensions)
Public Extension MethodEvaluateScriptAsync Evaluate some Javascript code in the context of this WebBrowser. The script will be executed asynchronously and the method returns a Task encapsulating the response from the Javascript This simple helper extension will encapsulate params in single quotes (unless int, uint, etc)
(Defined by WebBrowserExtensions)
Public Extension MethodEvaluateScriptAsync Evaluate Javascript code in the context of this WebBrowser using the specified timeout. The script will be executed asynchronously and the method returns a Task encapsulating the response from the Javascript This simple helper extension will encapsulate params in single quotes (unless int, uint, etc).
(Defined by WebBrowserExtensions)
Public Extension MethodEvaluateScriptAsync Evaluate Javascript in the context of this Browsers Main Frame. The script will be executed asynchronously and the method returns a Task encapsulating the response from the Javascript
(Defined by WebBrowserExtensions)
Public Extension MethodEvaluateScriptAsyncT Evaluate Javascript in the context of this Browsers Main Frame. The script will be executed asynchronously and the method returns a Task encapsulating the response from the Javascript
(Defined by WebBrowserExtensionsEx)
Public Extension MethodExecuteDevToolsMethodAsync Execute a method call over the DevTools protocol. This is a more structured version of SendDevToolsMessage. ExecuteDevToolsMethod(IBrowserHost, Int32, String, JsonString) can only be called on the CEF UI Thread, this method can be called on any thread. See the DevTools protocol documentation at https://chromedevtools.github.io/devtools-protocol/ for details of supported methods and the expected parameters dictionary contents. See the SendDevToolsMessage documentation for additional usage information.
(Defined by DevToolsExtensions)
Public Extension MethodExecuteScriptAsync Execute Javascript in the context of this Browsers Main Frame. As the method name implies, the script will be executed asynchronously, and the method therefore returns before the script has actually been executed.
(Defined by WebBrowserExtensions)
Public Extension MethodExecuteScriptAsync Execute Javascript code in the context of this Browser. As the method name implies, the script will be executed asynchronously, and the method therefore returns before the script has actually been executed. This simple helper extension will encapsulate params in single quotes (unless int, uint, etc)
(Defined by WebBrowserExtensions)
Public Extension MethodExecuteScriptAsyncWhenPageLoaded Execute Javascript code in the context of this Browsers Main Frame. This extension method uses the LoadingStateChanged event. As the method name implies, the script will be executed asynchronously, and the method therefore returns before the script has actually been executed.
(Defined by WebBrowserExtensions)
Public Extension MethodFind Search for text within the current page.
(Defined by WebBrowserExtensions)
Public Extension MethodForward Navigates forward, must check CanGoForward before calling this method.
(Defined by WebBrowserExtensions)
Public Extension MethodFreeDevToolsContext Set the DevToolsContext property to null. Used in conjunction with CefSharp.Dom
(Defined by WebBrowserExtensions)
Public Extension MethodGetBrowserHost Shortcut method to get the browser IBrowserHost.
(Defined by WebBrowserExtensions)
Public Extension MethodGetCookieManager Gets the default cookie manager associated with the IChromiumWebBrowserBase instance.
(Defined by WebBrowserExtensions)
Public Extension MethodGetDevToolsClient Gets a new Instance of the DevTools client for the chromiumWebBrowser instance.
(Defined by DevToolsExtensions)
Public Extension MethodGetFocusedFrame Returns the focused frame for the browser window.
(Defined by WebBrowserExtensions)
Public Extension MethodGetMainFrame Returns the main (top-level) frame for the browser window.
(Defined by WebBrowserExtensions)
Public Extension MethodGetRequestContext Gets the RequestContext associated with the IChromiumWebBrowserBase instance.
(Defined by WebBrowserExtensions)
Public Extension MethodGetSourceAsync Retrieve the main frame's HTML source using a TaskTResult.
(Defined by WebBrowserExtensions)
Public Extension MethodGetTextAsync Retrieve the main frame's display text using a TaskTResult.
(Defined by WebBrowserExtensions)
Public Extension MethodGetVisibleNavigationEntryAsync Retrieve the current NavigationEntry. Contains information like HttpStatusCode and SslStatus
(Defined by WebBrowserExtensionsEx)
Public Extension MethodGetZoomLevelAsync Asynchronously gets the current Zoom Level.
(Defined by WebBrowserExtensions)
Public Extension MethodLoadHtml Registers and loads a ResourceHandler that represents the HTML content.
(Defined by WebBrowserExtensions)
Public Extension MethodLoadHtml Loads html as Data Uri See https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs for details If base64Encode is false then html will be Uri encoded.
(Defined by WebBrowserExtensions)
Public Extension MethodLoadHtml Registers and loads a ResourceHandler that represents the HTML content.
(Defined by WebBrowserExtensions)
Public Extension MethodLoadUrlWithPostData Creates a new instance of IRequest with the specified Url and Method = POST and then calls LoadRequest(IRequest).
(Defined by WebBrowserExtensions)
Public Extension MethodPaste Execute Paste on the focused frame.
(Defined by WebBrowserExtensions)
Public Extension MethodPrint Opens a Print Dialog which if used (can be user cancelled) will print the browser contents.
(Defined by WebBrowserExtensions)
Public Extension MethodPrintToPdfAsync Asynchronously prints the current browser contents to the PDF file specified. The caller is responsible for deleting the file when done.
(Defined by WebBrowserExtensions)
Public Extension MethodRedo Execute Redo on the focused frame.
(Defined by WebBrowserExtensions)
Public Extension MethodRegisterAsyncJsObject

Asynchronously registers a Javascript object in this specific browser instance.

Only methods of the object will be availabe.


(Defined by WebBrowserExtensions)
Public Extension MethodRegisterJsObject Registers a Javascript object in this specific browser instance.
(Defined by WebBrowserExtensions)
Public Extension MethodRegisterResourceHandler Register a ResourceHandler. Can only be used when browser.ResourceHandlerFactory is an instance of DefaultResourceHandlerFactory.
(Defined by WebBrowserExtensions)
Public Extension MethodReload Reloads the page being displayed. This method will use data from the browser's cache, if available.
(Defined by WebBrowserExtensions)
Public Extension MethodReload Reloads the page being displayed, optionally ignoring the cache (which means the whole page including all .css, .js etc. resources will be re-fetched).
(Defined by WebBrowserExtensions)
Public Extension MethodReplaceMisspelling If a misspelled word is currently selected in an editable node calling this method will replace it with the specified word.
(Defined by WebBrowserExtensions)
Public Extension MethodSelectAll Execute SelectAll on the focused frame.
(Defined by WebBrowserExtensions)
Public Extension MethodSendMouseWheelEvent Send a mouse wheel event to the browser.
(Defined by WebBrowserExtensions)
Public Extension MethodSetAsPopup An IWebBrowser extension method that sets the HasParent property used when passing a ChromiumWebBrowser instance to OnBeforePopup(IWebBrowser, IBrowser, IFrame, String, String, WindowOpenDisposition, Boolean, IPopupFeatures, IWindowInfo, IBrowserSettings, Boolean, IWebBrowser)
(Defined by WebBrowserExtensions)
Public Extension MethodSetMainFrameDocumentContentAsync Set the Document Content for the Main Frame using DevTools Protocol.
(Defined by DevToolsExtensions)
Public Extension MethodSetZoomLevel Change the ZoomLevel to the specified value. Can be set to 0.0 to clear the zoom level.
(Defined by WebBrowserExtensions)
Public Extension MethodShowDevTools Open developer tools in its own window.
(Defined by WebBrowserExtensions)
Public Extension MethodShowDevToolsDocked Open DevTools using your own Control as the parent. If inspectElementAtX and/or inspectElementAtY are specified then the element at the specified (x,y) location will be inspected. For resize/moving to work correctly you will need to use the LifeSpanHandler implementation. (Set LifeSpanHandler to an instance of LifeSpanHandler)
(Defined by WebBrowserExtensions)
Public Extension MethodShowDevToolsDocked Open DevTools using parentControl as the parent control. If inspectElementAtX and/or inspectElementAtY are specified then the element at the specified (x,y) location will be inspected. For resize/moving to work correctly you will need to use the LifeSpanHandler implementation. (Set LifeSpanHandler to an instance of LifeSpanHandler)
(Defined by WebBrowserExtensions)
Public Extension MethodStartDownload Download the file at url using IDownloadHandler.
(Defined by WebBrowserExtensions)
Public Extension MethodStop Stops loading the current page.
(Defined by WebBrowserExtensions)
Public Extension MethodStopFinding Cancel all searches that are currently going on.
(Defined by WebBrowserExtensions)
Public Extension MethodToggleAudioMute Toggles audio mute for the current browser. If the browser is null or has been disposed then this command will be a no-op.
(Defined by WebBrowserExtensionsEx)
Public Extension MethodUndo Execute Undo on the focused frame.
(Defined by WebBrowserExtensions)
Public Extension MethodUnRegisterResourceHandler Unregister a ResourceHandler. Can only be used when browser.ResourceHandlerFactory is an instance of DefaultResourceHandlerFactory.
(Defined by WebBrowserExtensions)
Public Extension MethodViewSource Opens up a new program window (using the default text editor) where the source code of the currently displayed web page is shown.
(Defined by WebBrowserExtensions)
Public Extension MethodCode exampleWaitForSelectorAsync Waits for a DOM element specified by the selector string to be added to or removed from the DOM. A simplified version of Puppeteer WaitForSelector. Uses a MutationObserver to wait for the element to become added or removed.
(Defined by WebBrowserExtensions)
Top
See Also