-
-
Notifications
You must be signed in to change notification settings - Fork 2.9k
General Usage
This guide introduces the general concepts involved when developing an application using `CefSharp`. It's important to remember that **`CefSharp` is a .Net wrapper around the [Chromium](https://bitbucket.org/chromiumembedded/cef/overview)**. CEF is an open source project based on the Google Chromium project. Unlike the Chromium project itself, which focuses mainly on Google Chrome application development, CEF focuses on facilitating embedded browser use cases in third-party applications. `CEF` is based on the multi-process Chromium Content API and as a result only a subset of the features that exist in `Chromium` are currently available. For example, support for extensions is limited, only a subset of the `Extension API` is implemented.
The `CEF` project has its own [website](https://bitbucket.org/chromiumembedded/cef/overview) and [Support](http://magpcss.org/ceforum/index.php) if you're dealing with a low level problem or your question is pretty generic you can search or post on the forum. Be sure to mention which `CEF` version you're using. `CefSharp` versions look like `73.1.130`, which maps to `CEF 73.1.13+g6e3c989+chromium-73.0.3683.75`. Open `chrome://version/` or check your `packages.config` to easily determine the version. Post on `ceforum` before opening an issue on the `CEF Issue Tracker`.
It's **important** to remember that `CefSharp` is limited by the `API` that `CEF` exposes, and even then not all of the `CEF API` is currently implemented. If you are chasing a particular feature then check through the [CEF](https://github.com/chromiumembedded/cef/tree/master/include). The [CEF](http://magpcss.org/ceforum/apidocs3/index-all.html) is a helpful resource. If there is a piece of the `CEF API` that is not currently exposed, then you can implement it yourself and submit a `PR` for inclusion in the main project.
This document is based on [CEF](https://bitbucket.org/chromiumembedded/cef/wiki/GeneralUsage.md)
`CefSharp` provides four different implementations, `WinForms`, `WPF`, `WPF.HwndHost` and `OffScreen`. The `WPF` and `OffScreen` versions use the `OffScreen Rendering(OSR)` rendering mode. In `OSR` mode each frame is rendered to a buffer and then either drawn on the screen as in the case of `WPF` or available as a `Bitmap` in `OffScreen`. Performance of the `WPF` version is slower than the `WinForms` version. `Wpf.HwndHost` implementation is equivilent ot hosting the `WinForms` version in `WPF` with support for `WPF Data Binding`.
All versions use the `CefSharp`, `CefSharp.Core` and `CefSharp.Core.Runtime` libraries, as a result much of the `API` is used exactly the same within all three flavors. This limits code duplication and reduces the maintenance burden of adding a new feature.
- Table of Contents
* [AnyCPU Support](#anycpu-support)
- [Need](#need-to-knowlimitations) - [Examples](#examples) - [Logging](#logging) - [Processes](#processes) - [Threads](#threads) - [Initialize](#initialize-and-shutdown) - [CefSettings](#cefsettings-and-browsersettings) - [IBrowser,](#ibrowser-iframe-and-ibrowserhost) - [Handlers](#handlers)
* [Resource Handling](#resource-handling) * [Scheme Handler](#scheme-handler) * [Request Interception](#request-interception) * [ResourceHandler](#resourcehandler) * [Response Filtering](#response-filtering) * [Loading Html/css/javascript/etc from disk/database/embedded resource/stream](#loading-htmlcssjavascriptetc-from-diskdatabaseembedded-resourcestream) * [Request Handling](#request-handling)
- [File](#file-uri-file) - [Proxy](#proxy-resolution) - [Request](#request-context-browser-isolation) - [Printing](#printing) - [High](#high-dpi-displayssupport)
* [WinForms](#winforms-high-dpi) * [WPF](#wpf-high-dpi) * [OffScreen](#offscreen-high-dpi)
- [MultiThreadedMessageLoop](#multithreadedmessageloop) - [Popups](#popups) - [JavaScript](#javascript-integration)
* [1. How do you call a Javascript method from .NET?](#1-how-do-you-call-a-javascript-method-from-net)
+ [When can I start executing `Javascript`?](#when-can-i-start-executing-javascript)
* [2. How do you call a Javascript method that return a result?](#2-how-do-you-call-a-javascript-method-that-returns-a-result)
* [3. How do you expose a .NET class to Javascript?](#3-how-do-you-expose-a-net-class-to-javascript)
+ [Async JavaScript Binding (JSB)](#async-javascript-binding-jsb)
+ [Sync JavaScript Binding (JSB)](#sync-javascript-binding-jsb)
+ [RegisterAsyncJsObject](#registerasyncjsobject)
+ [RegisterJsObject](#registerjsobject)
- [Adobe Flash Player (Pepper Flash)](#adobe-flash-player-pepper-flash)
- [Offscreen Rendering (OSR)](#offscreen-rendering-osr)
- [UserAgent](#useragent)
- [DevTools](#devtools)
- [Screenshots](#screenshots)
- [Win32 Out of Memory](#win32-out-of-memory)
- [Load URL with PostData](#load-url-with-postdata)
- [Spellchecking](#spellchecking)
- [WebAssembly](#webassembly)
- [Exception Handling](#exception-handling)
- [Dependency Checking](#dependency-checking)
- [Multimedia (Audio/Video)](#multimedia-audiovideo)
- [OnScreen (Virtual) Keyboard](#onscreen-virtual-keyboard)
- [Cookie Manager](#cookie-manager)
- Release Notes
- Software Requirements
- CefSharp requires**:
Notes: - You can package the `VC++ Redist Dll's` with your application see https://github.com/cefsharp/CefSharp/wiki/Frequently-asked-questions#Including_vcredist for details - The Microsoft .NET Framework 4.5.2 Developer Pack for Visual Studio 2012 and Visual Studio 2013 is available here: https://www.microsoft.com/en-gb/download/details.aspx?id=42637
- AnyCPU Support
- Need to Know/Limitations
- Examples
https://github.com/cefsharp/CefSharp.MinimalExample
- Logging
When debugging a problem, the first place to check is this log file as it contains low level `Chromium` messages. If you see errors or warnings then search on http://magpcss.org/ceforum/index.php and https://bitbucket.org/chromiumembedded/cef/issues?status=new&status=open
- Processes
- `Render Processes` (--type=renderer) - V8(Javascript) and rendering - `GPU Process` (--type=gpu-process) - handles GPU accelerated compositing - `Network Service` (--type=utility --utility-sub-type=network.mojom.NetworkService) - Entire Chromium network stack runs in this process - `Storage Service` (--type=utility --utility-sub-type=storage.mojom.StorageService) - html5 storage e.g. localStorage - `Audio Service` (--type=utility --utility-sub-type=audio.mojom.AudioService) - Playing of audio - `CrashPad Handler` (--type=crashpad-handler) - creates crash dumps
By default a spare renderer process may be created on initial browser creation or cross- origin navigation. This spare process may be used with a future cross-origin navigation or discarded on when [Cef.Shutdown](#initialize-and-shutdown) has been called.
`CefSharp` comes with a process called `CefSharp.BrowserSubProcess.exe` which will be spawned multiple times to represent separate processes as described above. Opening `Task Manager` and seeing multiple instances of `CefSharp.BrowserSubProcess.exe` is perfectly normal and required for the browser to function correctly. It is possible as of version `51.0.0` to provide your own custom `BrowserSubProcess`. An example of self hosting the BrowserSubProcess using your own executable using `WinForms` is available as part of the [MinimalExample](https://github.com/cefsharp/CefSharp.MinimalExample/blob/cefsharp/95/CefSharp.MinimalExample.WinForms/Program.PublishSingleFile.cs#L25)
Resources: - https://www.chromium.org/servicification - https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/servicification.md#overview - https://bitbucket.org/chromiumembedded/cef/issues/2498/add-support-for-site-per-process#comment-54186905 has details on the current default process model.
- Threads
- _UI thread_ is the main thread in the browser process. By default `CefSharp` uses `setting.MultiThreadedMessageLoop = true` so the `CEF UI` thread is different to your main application thread
- _IO thread_ is used in the browser process to process IPC and network messages
- _FILE thread_ is used in the browser process to interact with the file system
- _RENDERER thread_ is the main thread in the renderer process
- Initialize and Shutdown
See [Request](#request-context-browser-isolation) for details on how to change settings at runtime, isolate browser instances, set different cache paths for different instances.
It's important to note that it's necessary to initialize the underlying `CEF` library. This can be achieved in one of two ways, manually calling `Cef.Initialize` before creating your first `ChromiumWebBrowser` instance, secondly if you don't need to specify any custom settings then the first `ChromiumWebBrowser` instance you create will call `Cef.Initialize` if it hasn't been called already. For those wishing to specify some custom settings then you can initialize `CEF` yourself like below:
public static void Init()
{
var settings = new CefSettings();
// Increase the log severity so CEF outputs detailed information, useful for debugging
settings.LogSeverity = LogSeverity.Verbose;
// By default CEF uses an in memory cache, to save cached data e.g. to persist cookies you need to specify a cache path
// NOTE: The executing user must have sufficient privileges to write to this folder.
settings.CachePath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "CefSharp\\Cache");
Cef.Initialize(settings);
}It's important to note CEF that `Initialize`/`Shutdown` ***MUST*** be called on your main application thread (typically the UI thread). If you call them on different threads, your application will hang.
An example of calling `Initialize`/`Shutdown` manually using `WinForms`, the same can be applied to `WPF` and console applications that use the `CefSharp.OffScreen` package (The `OffScreen` example at https://github.com/cefsharp/CefSharp.MinimalExample is an excellent place to start, there is also one in the main project repository that's a little more advanced).
public class Program
{
[STAThread]
public static void Main()
{
//For Windows 7 and above, best to include relevant app.manifest entries as well
Cef.EnableHighDPISupport();
//We're going to manually call Cef.Shutdown below, this maybe required in some complex scenarios
CefSharpSettings.ShutdownOnExit = false;
//Perform dependency check to make sure all relevant resources are in our output directory.
Cef.Initialize(new CefSettings(), performDependencyCheck: true, browserProcessHandler: null);
var browser = new BrowserForm();
Application.Run(browser);
//Shutdown before your application exists or it will hang.
Cef.Shutdown();
}
}In summary - `Cef.Initialize` and `Cef.Shutdown` can only called Initialize once per process(application). There is no way around this, so only call `Shutdown` when you're finished using `CefSharp`. - `Cef.Initialize` and `Cef.Shutdown` must be called on the same thread. - `Cef.Initialize` will be called for you implicitly if you create a new `ChromiumWebBrowser` instance and haven't already called `Cef.Initialize`. - For the WinForms and WPF instances of `ChromiumWebBrowser` the relevant Application Exit event is hooked and `Cef.Shutdown()` called by default. Set `CefSharpSettings.ShutdownOnExit = false;` to disable this behavior. This value needs to be set before the first instance of `ChromiumWebBrowser` is created as the event handlers are hooked in the static constructor for the `ChromiumWebBrowser` class. - In `CefSharp.OffScreen` you must explicitly call `Cef.Shutdown()` before your application exists or it will hang.
- CefSettings and BrowserSettings
- `AcceptLanguageList` comma delimited ordered list of language codes without any whitespace that will be used in the "Accept-Language" HTTP header.
- `BrowserSubprocessPath` The path to a separate executable that will be launched for sub-processes. Typically there is no need to change this.
- `MultiThreadedMessageLoop` the default is True in `CefSharp`, though it is possible to integrate `CEF` into your apps existing message loop see [MultiThreadedMessageLoop](#multithreadedmessageloop) below.
- `CommandLineArgsDisabled` Set to true to disable configuration of browser process features using standard CEF and Chromium command-line arguments.
- `RootCachePath` The root directory that all `CefSettings.CachePath` and `RequestContextSettings.CachePath` values must have in common. If this value is empty and `CefSettings.CachePath` is non-empty then it will default to the `CefSettings.CachePath` value. If this value is non-empty then it must be an absolute path. A non-empty RootCachePath can be used in conjunction with an empty CefSettings.CachePath in instances where you would like browsers attached to the Global RequestContext (the default) created in "incognito mode" and instances created with a custom RequestContext using a disk based cache. See the [RequestContext](#request-context-browser-isolation) section below for more details.
- `CachePath` The location where data for the global browser cache will be stored on disk. In this value is non-empty then it must be an absolute path that is must be either equal to or a child directory of CefSettings.RootCachePath (if RootCachePath is empty it will default to this value). If the value is empty then browsers will be created in "incognito mode" where in-memory caches are used for storage and no data is persisted to disk. HTML5 databases such as localStorage will only persist across sessions if a cache path is specified. Can be overridden for individual `RequestContext` instances via the `RequestContextSettings.CachePath` value. See the [RequestContext](#request-context-browser-isolation) section below for more details.
- `Locale` The locale string that will be passed to Blink. If empty the default locale of "en-US" will be used. Also configurable using the "lang" command-line switch. Change this to set the Context menu language as well.
- `LogFile` The directory and file name to use for the debug log. If empty, the default name of "debug.log" will be used and the file will be written to the application directory. Also configurable using the "log-file" command-line switch.
- `LogSeverity` The log severity. Only messages of this severity level or higher will be logged. Also configurable using the "log-severity" command-line switch with a value of "verbose", "info", "warning", "error", "error-report" or "disable".
- `ResourcesDirPath` The fully qualified path for the resources directory. If this value is empty the cef.pak and/or devtools_resources.pak files must be located in the module directory. Also configurable using the "resources-dir-path" command-line switch.
- `LocalesDirPath` The fully qualified path for the locales directory. If this value is empty the locales directory must be located in the module directory. This value is ignored on Mac OS X where pack files are always loaded from the app bundle Resources directory. Also configurable using the "locales-dir-path" command-line switch.
- `RemoteDebuggingPort` Set to a value between 1024 and 65535 to enable remote debugging on the specified port. For example, if 8080 is specified the remote debugging URL will be http://localhost:8080. CEF can be remotely debugged from any CEF or Chrome browser window. Also configurable using the "remote-debugging-port" command-line switch.
There are many settings and command line arguments that can influence the way CEF behaves. Here are some examples:
public static void Init()
{
// Specify Global Settings and Command Line Arguments
var settings = new CefSettings();
// By default CEF uses an in memory cache, to save cached data e.g. to persist cookies you need to specify a cache path
// NOTE: The executing user must have sufficient privileges to write to this folder.
settings.CachePath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "CefSharp\\Cache");;
// There are many command line arguments that can either be turned on or off
// Enable WebRTC
settings.CefCommandLineArgs.Add("enable-media-stream");
//Disable GPU Acceleration
settings.CefCommandLineArgs.Add("disable-gpu");
// Don't use a proxy server, always make direct connections. Overrides any other proxy server flags that are passed.
// Slightly improves Cef initialize time as it won't attempt to resolve a proxy
settings.CefCommandLineArgs.Add("no-proxy-server");
Cef.Initialize(settings);
}There are some settings which can be applied to a specific `ChromiumWebBrowser` instance. If you're using `WPF`, you can specify `BrowserSettings` in `XAML`.
var browser = new ChromiumWebBrowser(url)
{
BrowserSettings =
{
DefaultEncoding = "UTF-8",
WebGl = CefState.Disabled
}
};<!--xmlns:cefSharpCore="clr-namespace:CefSharp;assembly=CefSharp.Core"-->
<!--xmlns:cefSharpWpf="clr-namespace:CefSharp.Wpf;assembly=CefSharp.Wpf"-->
<cefSharpWpf:ChromiumWebBrowser>
<cefSharpWpf:ChromiumWebBrowser.BrowserSettings>
<cefSharpCore:BrowserSettings DefaultEncoding="UTF-8"/>
</cefSharpWpf:ChromiumWebBrowser.BrowserSettings>
</cefSharpWpf:ChromiumWebBrowser>- IBrowser, IFrame and IBrowserHost
For example, a browser that loads two HTML `<iframe></iframe>`s will have three `IFrame` objects (the top-level frame and the two `<iframe></iframe>`s).
To load a URL in the browser main frame:
browser.MainFrame.LoadUrl(someurl);`CefSharp` provides many extension methods to make executing common tasks easier. See `WebBrowserExtensions` for the source of these methods and to get a better understanding of how common tasks are performed.
`IBrowserHost` represents the more low level browser methods.
- Handlers
- [ConsoleMessage](https://cefsharp.github.io/api/99.2.x/html/E_CefSharp_IChromiumWebBrowserBase_ConsoleMessage.htm) - [StatusMessage](https://cefsharp.github.io/api/99.2.x/html/E_CefSharp_IChromiumWebBrowserBase_StatusMessage.htm) - [FrameLoadStart](https://cefsharp.github.io/api/99.2.x/html/E_CefSharp_IChromiumWebBrowserBase_FrameLoadStart.htm) - [FrameLoadEnd](https://cefsharp.github.io/api/99.2.x/html/E_CefSharp_IChromiumWebBrowserBase_FrameLoadEnd.htm) - [LoadError](https://cefsharp.github.io/api/99.2.x/html/E_CefSharp_IChromiumWebBrowserBase_LoadError.htm) - [LoadingStateChanged](https://cefsharp.github.io/api/99.2.x/html/E_CefSharp_IChromiumWebBrowserBase_LoadingStateChanged.htm)
These are simple events that expose a small percentage of the underlying handlers that `CEF` provides. These events are only called for the main browser, for popup handling you can access the notifications using `IDisplayHandler` and `ILoadHandler`.
To determine when a page has finished loading I recommend using `LoadingStateChanged` over `FrameLoadEnd`. It's important to remember that **finished loading** is different to **finished rendering**. There is currently no method of determining when a web page has finished rendering (and unlikely ever will be as with features like flash, dynamic content, animations, even simple tasks like moving your mouse or scrolling will cause new frames to be rendered).
`IDialogHandler`, `IDisplayHandler`, `IDownloadHandler`, `IContextMenuHandler`, `ILifeSpanHandler`, `ILoadHandler` and `IRequestHandler` are some of the more common handlers (see the source/API doc for the rest). These simply wrap the underlying CEF handlers in a convenient .NET fashion. For example CEF's `CefDownloadHandler` is `IDownloadHandler` in `CefSharp`. Implementing these handlers will provide you access to the underlying events and callbacks that are the foundation of CEF. A number of handlers' members can be executed in an async fashion using a callback. All the handlers follow a consistent pattern: those that return a `bool` are asking you whether you'd like to handle this yourself. If no, then return `false` for the default action. Return `true` if you will handle it yourself.
They are basic interfaces which you implement and then assign to your `ChromiumWebBrowser` instance. e.g.
browser.DownloadHandler = new DownloadHandler();Some general notes about the handlers - [IDownloadHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IDownloadHandler.htm) needs to be implemented to allow downloading of files, progress notifications, pause, cancel, etc - [IRequestHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IRequestHandler.htm) is for dealing with navigation, redirects, resource load notifications etc - [IDialogHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IDialogHandler.htm) is for file dialog notifications - [IDisplayHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IDisplayHandler.htm) is for address change, status message, console message, fullscreen mode change notifications (and more) - [ILoadHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_ILoadHandler.htm) is for load status some of these are mapped to events, use this for popups - [ILifeSpanHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_ILifeSpanHandler.htm) is for dealing with popups and close events - [IKeyboardHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IKeyboardHandler.htm) is for keyboard events - [IJsDialogHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IJsDialogHandler.htm) is for javascript message boxes/popups - [IDragHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IDragHandler.htm) is for drag start - [IContextMenuHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IContextMenuHandler.htm) is for customising the context menu - [IFocusHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IFocusHandler.htm) is for focus related notifications - [IResourceRequestHandlerFactory](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IResourceRequestHandlerFactory.htm) is an interface unique to CefSharp and allows for intercepting resource requests without having to implement a IRequestHandler and IResourceRequestHandler. - [IRenderProcessMessageHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IRenderProcessMessageHandler.htm) is for custom `CefSharp` messages sent from the render process - [IFindHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IFindHandler.htm) is for find notifications
It is possible to modify the response using a `ResponseFilter`. See section below.
- Resource Handling
1. The [Scheme](#scheme-handler) approach allows registration of a handler for requests targeting a particular origin (scheme + domain). 2. The [Request](#request-interception) approach allows handling of arbitrary requests at the application's discretion.
Use the HTTP(S) scheme instead of a custom scheme to avoid a range of potential issues.
If you choose to use a custom scheme (anything other than `http://`, `https://`, etc) you must register it with CEF so that it will behave as expected. If you would like your custom scheme to behave similar to HTTP (support POST requests and enforce HTTP access control (CORS) restrictions) then it should be registered as a "standard" scheme. If you are planning to perform cross-origin requests to other schemes or send POST requests via `XMLHttpRequest` to your scheme handler then you should use the HTTP scheme instead of a custom scheme to avoid potential issues. `IsSecure` and `IsCorsEnabled` params were added recently.
Handlers can be used with both built-in schemes (`http://`, `https://`, etc) and custom schemes. When using a built-in scheme choose a domain name unique to your application (like `myapp` or `internal`). Implement the `ISchemeHandlerFactory` and [IResourceHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IResourceHandler.htm) classes to handle the request and provide response data. See [ResourceHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_ResourceHandler.htm) for the default implementation of [IResourceHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IResourceHandler.htm), which has lots of useful static helper methods.
- Scheme Handler
A scheme handler is registered via the [CefSettings.RegisterScheme](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_AbstractCefSettings_RegisterScheme.htm) function. For example, you can register a handler for 'localfolder://cefsharp/' requests (there is another example below and there are working examples in the project source):
settings.RegisterScheme(new CefCustomScheme
{
SchemeName = "localfolder",
DomainName = "cefsharp",
SchemeHandlerFactory = new FolderSchemeHandlerFactory(rootFolder: @"..\..\..\..\CefSharp.Example\Resources",
hostName: "cefsharp", //Optional param no hostname/domain checking if null
defaultPage: "home.html") //Optional param will default to index.html
});The [FolderSchemeHandlerFactory](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_SchemeHandler_FolderSchemeHandlerFactory.htm) is a simple default implementation for reading files from disk using a scheme handler. You can use either a custom scheme (In other words, you can provide a URL in the form `customscheme://folder/yourfile`) or a standard scheme (`https://`, `https://`).
An example of implementing your own factory might look like:
public class CefSharpSchemeHandlerFactory : ISchemeHandlerFactory
{
public const string SchemeName = "custom";
private static readonly IDictionary<string, string> ResourceDictionary;
static CefSharpSchemeHandlerFactory()
{
ResourceDictionary = new Dictionary<string, string>
{
{ "/home.html", Resources.home_html },
{ "/bootstrap/bootstrap.min.css", Resources.bootstrap_min_css },
{ "/bootstrap/bootstrap.min.js", Resources.bootstrap_min_js },
{ "/BindingTest.html", Resources.BindingTest },
{ "/ExceptionTest.html", Resources.ExceptionTest },
{ "/PopupTest.html", Resources.PopupTest },
{ "/SchemeTest.html", Resources.SchemeTest }
};
}
public IResourceHandler Create(IBrowser browser, IFrame frame, string schemeName, IRequest request)
{
//Notes:
// - The 'host' portion is entirely ignored by this scheme handler.
// - If you register a ISchemeHandlerFactory for http/https schemes you should also specify a domain name
// - Avoid doing lots of processing in this method as it will affect performance.
// - Uses the Default ResourceHandler implementation
var uri = new Uri(request.Url);
var fileName = uri.AbsolutePath;
string resource;
if (ResourceDictionary.TryGetValue(fileName, out resource) && !string.IsNullOrEmpty(resource))
{
var fileExtension = Path.GetExtension(fileName);
return ResourceHandler.FromString(resource, , mimeType: Cef.GetMimeType(fileExtension));
}
return null;
}
}The [ResourceHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_ResourceHandler.htm) is provided as a default implementation of [IResourceHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IResourceHandler.htm) and contains many static helper methods for creating classes. See the [Resource](#resourcehandler) section below for further details.
A few examples of using the static methods are:
ResourceHandler.FromStream(stream, mimeType);
ResourceHandler.FromString(htmlString, includePreamble:true, mimeType:Cef.GetMimeType(fileExtension));
ResourceHandler.FromFilePath("CefSharp.Core.xml", mimeType);Finally, you have to register this scheme handler using some code like this:
public static void Init()
{
// Pseudo code; you probably need more in your CefSettings also.
var settings = new CefSettings();
settings.RegisterScheme(new CefCustomScheme
{
SchemeName = "custom",
SchemeHandlerFactory = new CefSharpSchemeHandlerFactory()
});
Cef.Initialize(settings);
}- Request Interception
public class CustomResourceRequestHandler : CefSharp.Handler.ResourceRequestHandler
{
protected override IResourceHandler GetResourceHandler(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request)
{
//ResourceHandler has many static methods for dealing with Streams,
// byte[], files on disk, strings
// Alternatively ou can inheir from IResourceHandler and implement
// a custom behaviour that suites your requirements.
return ResourceHandler.FromString("Welcome to CefSharp!", mimeType: Cef.GetMimeType("html"));
}
}
public class CustomRequestHandler : CefSharp.Handler.RequestHandler
{
protected override IResourceRequestHandler GetResourceRequestHandler(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request, bool isNavigation, bool isDownload, string requestInitiator, ref bool disableDefaultHandling)
{
//Only intercept specific Url's
if (request.Url == "http://cefsharp.test/" || request.Url == "https://cefsharp.test/")
{
return new CustomResourceRequestHandler();
}
//Default behaviour, url will be loaded normally.
return null;
}
}
browser.RequestHandler = new CustomRequestHandler();The [IWebBrowser.RegisterResourceHandler](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_WebBrowserExtensions_RegisterResourceHandler.htm) and [IWebBrowser.UnRegisterResourceHandler](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_WebBrowserExtensions_UnRegisterResourceHandler.htm) extension methods provide a simple means of providing an [IResourceHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IResourceHandler.htm) for a given `Url`.
You could for example request a fictitious URL and provide a response just as if the site was real.
- ResourceHandler
[ResourceHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_ResourceHandler.htm) contains many static methods for convenience - [ResourceHandler.FromString](https://cefsharp.github.io/api/99.2.x/html/Overload_CefSharp_ResourceHandler_FromString.htm) - [ResourceHandler.FromByteArray](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_ResourceHandler_FromByteArray.htm) - [ResourceHandler.ForErrorMessage](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_ResourceHandler_ForErrorMessage.htm) - [ResourceHandler.FromStream](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_ResourceHandler_FromStream.htm) - [ResourceHandler.FromFilePath](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_ResourceHandler_FromFilePath.htm)
A few examples of using the static methods are:
ResourceHandler.FromStream(stream, mimeType);
ResourceHandler.FromString(htmlString, includePreamble:true, mimeType:Cef.GetMimeType(fileExtension));
ResourceHandler.FromFilePath("CefSharp.Core.xml", mimeType);The source contains detailed examples of [ISchemeHandlerFactory](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_ISchemeHandlerFactory.htm).
Examples of how to implement `ResourceHandler.ProcessRequestAsync`. If you require complete control then implement [IResourceHandler](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IResourceHandler.htm), however in most cases this is not necessary.
//A simple example of a ResourceHandler that downloads a file from the internet.
//A task is called to perform processing then executes the callback when the response is ready.
//You could do Database queries + html generation or other backend type operation
public class ExampleResourceHandler : ResourceHandler
{
public override CefReturnValue ProcessRequestAsync(IRequest request, ICallback callback)
{
Task.Run(() =>
{
using (callback)
{
var httpWebRequest = (HttpWebRequest)WebRequest.Create("https://raw.githubusercontent.com/cefsharp/CefSharp/master/README.md");
var httpWebResponse = (HttpWebResponse)httpWebRequest.GetResponse();
// Get the stream associated with the response.
var receiveStream = httpWebResponse.GetResponseStream();
var mime = httpWebResponse.ContentType;
var stream = new MemoryStream();
receiveStream.CopyTo(stream);
httpWebResponse.Close();
//Reset the stream position to 0 so the stream can be copied into the underlying unmanaged buffer
stream.Position = 0;
//Populate the response values
ResponseLength = stream.Length;
MimeType = mime;
StatusCode = (int)HttpStatusCode.OK;
Stream = stream;
callback.Continue();
}
});
return CefReturnValue.ContinueAsync;
}
}- Response Filtering
The basic example of getting the response as a `UTF8` string is:
public class CustomResourceRequestHandler : CefSharp.Handler.ResourceRequestHandler
{
private readonly System.IO.MemoryStream memoryStream = new System.IO.MemoryStream();
protected override IResponseFilter GetResourceResponseFilter(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request, IResponse response)
{
return new CefSharp.ResponseFilter.StreamResponseFilter(memoryStream);
}
protected override void OnResourceLoadComplete(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request, IResponse response, UrlRequestStatus status, long receivedContentLength)
{
//You can now get the data from the stream
var bytes = memoryStream.ToArray();
if (response.Charset == "utf-8")
{
var str = System.Text.Encoding.UTF8.GetString(bytes);
}
else
{
//Deal with different encoding here
}
}
}
public class CustomRequestHandler : CefSharp.Handler.RequestHandler
{
protected override IResourceRequestHandler GetResourceRequestHandler(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request, bool isNavigation, bool isDownload, string requestInitiator, ref bool disableDefaultHandling)
{
//Only intercept specific Url's
if (request.Url == "http://cefsharp.github.io/" || request.Url == "https://cefsharp.github.io/")
{
return new CustomResourceRequestHandler();
}
//Default behaviour, url will be loaded normally.
return null;
}
}
browser.RequestHandler = new CustomRequestHandler();Currently [StreamResponseFilter](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_ResponseFilter_StreamResponseFilter.htm) is the only filter provided as part of the framework.
A simple response filter that copies dataIn to dataOut. Data is streamed in chunks, typically 64kb in size.
/// <summary>
/// PassThruResponseFilter - copies all data from DataIn to DataOut.
/// Upstream documentation link
/// https://magpcss.org/ceforum/apidocs3/projects/(default)/CefResponseFilter.html#Filter(void*,size_t,size_t&,void*,size_t,size_t&)
/// </summary>
public class PassThruResponseFilter : IResponseFilter
{
bool IResponseFilter.InitFilter()
{
return true;
}
FilterStatus IResponseFilter.Filter(Stream dataIn, out long dataInRead, Stream dataOut, out long dataOutWritten)
{
if (dataIn == null)
{
dataInRead = 0;
dataOutWritten = 0;
return FilterStatus.Done;
}
//Calculate how much data we can read, in some instances dataIn.Length is
//greater than dataOut.Length
dataInRead = Math.Min(dataIn.Length, dataOut.Length);
dataOutWritten = dataInRead;
var readBytes = new byte[dataInRead];
dataIn.Read(readBytes, 0, readBytes.Length);
dataOut.Write(readBytes, 0, readBytes.Length);
//If we read less than the total amount avaliable then we need
//return FilterStatus.NeedMoreData so we can then write the rest
if (dataInRead < dataIn.Length)
{
return FilterStatus.NeedMoreData;
}
return FilterStatus.Done;
}
public void Dispose()
{
}
}See the `CefSharp.Example`project within the source for additional example implementations of [IResourceFilter](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IResponseFilter.htm). This feature is **quite complex** to implement. Make sure you read over and debug the existing examples before asking any questions.
- Loading HTML/CSS/JavaScript/etc from disk/database/embedded resource/stream
//Load a data encoded Uri
//NOTE There are limits to the size of a Data Uri, use the overload that takes a Url if you need to load large files
LoadHtml(this IWebBrowser browser, string html, bool base64Encode = false);
//Register a ResourceHandler with the `ResourceRequestHandlerFactory` and calls browser.Load
LoadHtml(this IWebBrowser browser, string html, string url)`;
//Register a resource handler with the `ResourceRequestHandlerFactory`
RegisterResourceHandler(this IWebBrowser browser, string url, Stream stream, string mimeType =
ResourceHandler.DefaultMimeType);
//Unregister a resource handler with the `ResourceRequestHandlerFactory`
UnRegisterResourceHandler(this IWebBrowser browser, string url);
//In `WinForms` you can pass a `HtmlString` directly into the constructor and have it load as a Data Uri
new ChromiumWebBrowser((CefSharp.Web.HtmlString)"<html><body style='background:red;'>Data Uri Test</body></html>");For more information on `data:` encoded URI, which contains the body of the request in the URI itself see https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
Generating your own `Data URI` would look something like:
const string html = "<html><head><title>Test</title></head><body><h1>Html Encoded in URL!</h1></body></html>";
var base64EncodedHtml = Convert.ToBase64String(Encoding.UTF8.GetBytes(html));
browser.Load("data:text/html;base64," + base64EncodedHtml);- Request Handling
For loading resources from memory/disk/database see [Resource](#resource-handling)
The following provides an example of how to only allow loading of resources from a specific host.
public class CustomResourceRequestHandler : CefSharp.Handler.ResourceRequestHandler
{
protected override CefReturnValue OnBeforeResourceLoad(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request, IRequestCallback callback)
{
if (Uri.TryCreate(request.Url, uriKind: UriKind.Absolute, out Uri result))
{
if (string.Compare(result.Host, "www.google.com", StringComparison.OrdinalIgnoreCase) == 0)
{
return CefReturnValue.Continue;
}
}
return CefReturnValue.Cancel;
//If you wanted to perform some sort of database lookup to validate the Url then you should use a Task for processing
//System.Threading.Tasks.Task.Run(() =>
//{
// using (callback)
// {
// if (Uri.TryCreate(request.Url, uriKind: UriKind.Absolute, out Uri uri))
// {
// //Query Database here and confirm Url matches
// var validUrl = string.Compare(uri.Host, "www.google.com", StringComparison.OrdinalIgnoreCase) == 0;
// //Continue if it's a valid Url
// callback.Continue(validUrl);
// }
// else
// {
// //Failed to parse the Url, we'll cancel
// callback.Cancel();
// }
// }
//});
//return CefReturnValue.ContinueAsync;
}
}
public class CustomRequestHandler : CefSharp.Handler.RequestHandler
{
protected override IResourceRequestHandler GetResourceRequestHandler(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request, bool isNavigation, bool isDownload, string requestInitiator, ref bool disableDefaultHandling)
{
//Use our custom ResourceRequestHandler to hook OnBeforeResourceLoad
return new CustomResourceRequestHandler();
//For the default behaviour, return null
//url will be loaded normally.
//return null;
}
}
browser.RequestHandler = new CustomRequestHandler();- File URI (file:///)
If you choose to ignore this advice you'll have to resolve any issues you have using `file:///` yourself. `ceforum` is the best resource.
- Proxy Resolution
//Create a new RequestContext that users a specific proxy server
//By default an in memory cache is used
var requestContext = RequestContext
.Configure()
.WithProxyServer("127.0.0.1", 8080)
.Create();
//Create a RequestContext with a proxy and cache path
//Making sure that CachePath is equal to or a child of CefSettings.RootCachePath
//See https://github.com/cefsharp/CefSharp/issues/3111#issuecomment-629713608 for more info on cache path
var requestContext = RequestContext
.Configure()
.WithProxyServer("127.0.0.1", 8080)
.WithCachePath(Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "CefSharp\\Cache"))
.Create();
//Set the proxy at runtime, the RequestContext must be initialized
Cef.UIThreadTaskFactory.StartNew(delegate
{
string errorMessage;
if (!requestContext.CanSetPreference("proxy"))
{
//Unable to set proxy, if you set proxy via command line args it cannot be modified.
}
success = requestContext.SetProxy("127.0.0.1", 8080, out errorMessage);
});Some Additional examples of setting proxy using `Preferences` in `CefSharp` are available at http://stackoverflow.com/questions/36095566/cefsharp-3-set-proxy-at-runtime
- Proxy Authentication
Example of providing UserName/Password for Proxy
browser.RequestHandler = new CustomRequestHandler();
public class CustomRequestHandler : CefSharp.Handler.RequestHandler
{
protected override bool GetAuthCredentials(IWebBrowser chromiumWebBrowser, IBrowser browser, string originUrl, bool isProxy, string host, int port, string realm, string scheme, IAuthCallback callback)
{
//Cast IWebBrowser to ChormiumWebBrowser if you need to access the UI control
//You can Invoke onto the UI Thread if you need to show a dialog
var b = (ChromiumWebBrowser)chromiumWebBrowser;
if(isProxy)
{
using (callback)
{
callback.Continue(username: "user", password: "pass");
}
return true;
}
//Return false to cancel the request
return false;
}
}- Request Context (Browser Isolation)
Here are some key points:
- By default a Global Request Context will be used (settings shared by all browsers) - You can change some (not all) settings at run time using `Preferences` - Don't use the command line argument if you wish to change the value using `SetPreference` - `SetPreference` must be called on the `CEF UI Thread`. Use [Cef.UIThreadTaskFactory](https://cefsharp.github.io/api/99.2.x/html/P_CefSharp_Cef_UIThreadTaskFactory.htm) to spawn a task on the `CEF UI Thread` - `WinForms`: set the `RequestContext` immediately after you create your browser instance - `OffScreen`: Pass `RequestContext` into the constructor - `WPF`: Set in your `Control`/`Window` constructor after `InitializeComponent()` is called - Set [RequestContextSettings.CachePath](https://cefsharp.github.io/api/99.2.x/html/P_CefSharp_RequestContextSettings_CachePath.htm) to persist cookies, data, localStorage, etc - [RequestContextSettings.CachePath](https://cefsharp.github.io/api/99.2.x/html/P_CefSharp_RequestContextSettings_CachePath.htm) **must** be equal to or a child of [CefSettings.RootCachePath](https://cefsharp.github.io/api/99.2.x/html/P_CefSharp_AbstractCefSettings_RootCachePath.htm) see https://github.com/cefsharp/CefSharp/issues/3111#issuecomment-629713608
//WinForms Examples - WPF and OffScreen are similar, see notes above.
//Default implementation of RequestContext
//Default settings will be used, this means an in-memory cache (no data persisted)
browser = new ChromiumWebBrowser();
browser.RequestContext = new RequestContext();
// Use RequestContext.Configure to create a RequestContext using a
// Fluent style interface, can be used to set proxy, set preferences, cachePath
// Use WithSharedSettings to share settings with another RequestContext
// This one will share the same CachePath as the Global RequestContext
var ctx = RequestContext.Configure()
.WithSharedSettings(Cef.GetGlobalRequestContext())
.WithPreference("webkit.webprefs.minimum_font_size", 24)
.Create();
browser = new ChromiumWebBrowser("www.google.com");
browser.RequestContext = ctx;
//CustomRequestContextHanler needs to implement `IRequestContextHandler`
//Default settings will be used, this means an in-memory cache (no data persisted)
browser = new ChromiumWebBrowser();
browser.RequestContext = new RequestContext(new CustomRequestContextHandler());
//Custom settings and CustomRequestContextHandler
//Use the specified cache path (if empty, in memory cache will be used). To share the global
//browser cache and related configuration set this value to match the CefSettings.CachePath
//value.
var requestContextSettings = new RequestContextSettings { CachePath = cachePath };
browser = new ChromiumWebBrowser();
browser.RequestContext = new RequestContext(requestContextSettings, new CustomRequestContextHandler());See the project source for more detailed examples.
//When you are already on the CEF UI Thread you can use the following
string errorMessage;
//You can set most preferences using a `.` notation rather than having to create a complex set of dictionaries.
//Disable resizing of text areas
//The default is true, you can change to false to disable
context.SetPreference("webkit.webprefs.text_areas_are_resizable", true, out errorMessage);
//Change the minimum font size to 24pt
context.SetPreference("webkit.webprefs.minimum_font_size", 24, out errorMessage);
//To execute on the CEF UI Thread you can use
Cef.UIThreadTaskFactory.StartNew(delegate
{
string errorMessage;
//Use this to check that settings preferences are working in your code
//the browser variable is an instance of ChromiumWebBrowser
var success = browser.RequestContext.SetPreference("webkit.webprefs.minimum_font_size", 24, out errorMessage);
}); Setting preferences in OnRequestContextInitialized (this approach is recommended for setting a proxy as it will be called before the browser attempts to load any web page)
public class RequestContextHandler : CefSharp.Handler.RequestContextHandler
{
protected override IResourceRequestHandler GetResourceRequestHandler(IBrowser browser, IFrame frame, IRequest request, bool isNavigation, bool isDownload, string requestInitiator, ref bool disableDefaultHandling)
{
// Return null for the default behaviour
// Implement CefSharp.IResourceRequestHandler or inherit from CefSharp.Handler.ResourceRequestHandler
// To handle resource requests at the RequestContext level
return null;
}
protected override void OnRequestContextInitialized(IRequestContext requestContext)
{
//You can set preferences here on your newly initialized request context.
//Note, there is called on the CEF UI Thread, so you can directly call SetPreference
//Use this to check that settings preferences are working in your code
//You should see the minimum font size is now 24pt
string errorMessage;
var success = requestContext.SetPreference("webkit.webprefs.minimum_font_size", 24, out errorMessage);
//Set proxy to fixed_servers
//Make sure to include using CefSharp; to access this extension method
var setProxySuccess = requestContext.SetProxy("scheme", "host", port: 8080, out string error);
//Alternatively you can set the proxy with code similar to the code below
//https://stackoverflow.com/questions/36095566/cefsharp-3-set-proxy-at-runtime has some additional examples
//var v = new Dictionary<string, object>
//{
// ["mode"] = "fixed_servers",
// ["server"] = "scheme://host:port"
//};
//string errorMessage;
//bool success = requestContext.SetPreference("proxy", v, out errorMessage);
}
}- Printing
If you need better printing support then you should discuss that on `ceforum`. There are already open discussions and an open issue on the CEF Issue Tracker.
- http://magpcss.org/ceforum/viewtopic.php?f=7&t=14196 - https://bitbucket.org/chromiumembedded/cef/issues/1283/adding-print-options-to-cef3 - http://magpcss.org/ceforum/viewtopic.php?f=6&t=12567&p=27604
- High DPI Displays/Support
- Note** If you mouse cursor is incorrectly positioned in the browser or the browser displays black boxes/border with rendering/resizing then your app needs to be made `DPI Aware`. Other parts of your application may also appear blurry or incorrectly-sized.
1. [Through](https://docs.microsoft.com/en-us/windows/win32/hidpi/setting-the-default-dpi-awareness-for-a-process#setting-default-awareness-with-the-application-manifest) (This is generally the preferred option) 2. Via [app.config](https://docs.microsoft.com/en-us/dotnet/desktop/winforms/high-dpi-support-in-windows-forms?view=netframeworkdesktop-4.8#configuring-your-windows-forms-app-for-high-dpi-support) (**WinForms Only** where targeting .Net 4.7 and above) 3. [Programmatically](https://docs.microsoft.com/en-us/windows/win32/hidpi/setting-the-default-dpi-awareness-for-a-process#setting-default-awareness-programmatically)
Windows 10 1703 has additional improvements see https://blogs.windows.com/windowsdeveloper/2017/04/04/high-dpi-scaling-improvements-desktop-applications-windows-10-creators-update/ for more details.
- WinForms High DPI
- App.manifest
- IMPORTANT**
Set the default awareness using the [application](https://docs.microsoft.com/en-us/windows/win32/hidpi/setting-the-default-dpi-awareness-for-a-process#setting-default-awareness-with-the-application-manifest). The following example is PerMonitor DPI Aware on Win 10 1703 and above and PerMonitor DPI aware on older version. Make sure you read https://docs.microsoft.com/en-us/windows/win32/hidpi/high-dpi-desktop-application-development-on-windows#dpi-awareness-mode which discusses the different `DPI Awareness` options. If you project doesn't already have an `app.manifest` use the `Visual Studio New Item` template to add one rather than doing so manually to ensure the relevant `` entry in your `csproj/vbproj` file is added (it's a special type).
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<application xmlns="urn:schemas-microsoft-com:asm.v3">
<windowsSettings>
<dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
<dpiAware>true/PM</dpiAware>
</windowsSettings>
</application>
</assembly>- Programmatically
[Cef.EnableHighDPISupport();](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_Cef_EnableHighDPISupport.htm) **must** be called very early on in your application execution, preferably in your application entry point (Program.Main).
The [CefSharp.MinimalExample.WinForms](https://github.com/cefsharp/CefSharp.MinimalExample/tree/master/CefSharp.MinimalExample.WinForms) project contains a working example.
- WPF High DPI
- App.manifest
- WPF High DPI
For a working example see https://github.com/cefsharp/CefSharp/blob/cefsharp/84/CefSharp.Wpf.Example/app.manifest for a working example. If you project doesn't already have an `app.manifest` use the `Visual Studio New Item` template to add one rather than doing so manually to ensure the relevant `` entry in your `csproj/vbproj` file is added (it's a special type).
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<application xmlns="urn:schemas-microsoft-com:asm.v3">
<windowsSettings>
<dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
<dpiAware>true/PM</dpiAware>
</windowsSettings>
</application>
</assembly>- Programatically
- OffScreen High DPI
- High DPI Additional Info
var settings = new CefSettings();
settings.CefCommandLineArgs.Add("disable-gpu-compositing");
Cef.Initialize(settings);Alternatively you can try the [force-device-scale-factor](https://peter.sh/experiments/chromium-command-line-switches/#force-device-scale-factor) command line flag. This should only be used in conjunction with the WinForms implementation.
var settings = new CefSettings();
settings.CefCommandLineArgs.Add("force-device-scale-factor", "1");
Cef.Initialize(settings);- https://msdn.microsoft.com/en-us/library/windows/desktop/dn469266(v=vs.85).aspx It's a very long MSDN article, but it's necessary reading if your app needs to be run on high DPI displays. - https://blogs.windows.com/windowsdeveloper/2017/05/19/improving-high-dpi-experience-gdi-based-desktop-apps/ - https://docs.microsoft.com/en-us/windows/win32/hidpi/setting-the-default-dpi-awareness-for-a-process#setting-default-awareness-with-the-application-manifest
- MultiThreadedMessageLoop
- Uses a different thread for the message pump. - The CEF UI thread is different to your application's UI thread, which can cause some disconnects in message processing. - One example is opening a menu and clicking within the browser control with the menu staying open. - Low level Win32 messages don't propagate between `CEF` and `WinForms`
It is possible to integrate CEF into your app's existing message loop. A very minimal implementation of integrating CEF into your existing message loop involves using a timer that's called 30/60 times per second on the UI thread.
var settings = new CefSettings();
settings.MultiThreadedMessageLoop = false; //This defaults to true
Cef.Initialize(settings);
- For WPF use [DispatcherTimer](https://docs.microsoft.com/en-us/dotnet/api/system.windows.threading.dispatchertimer?view=netframework-4.8)
- For WinForms use [Timer](https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.timer?view=netframework-4.8)
//Set the timer Interval to 30 times per second, can be increased to 60 if required
//For WPF
timer.Interval = TimeSpan.FromMilliseconds(1000 / 30);
//For WinForms
timer.Interval = 1000 / 30;
timer.Tick += UiThreadTimerTick;
timer.Start();
//Before closing your app
//Calling Cef.DoMessageLoopWork() after Cef.Shutdown has been called will result in
//an access violation, make sure you stop you timer first.
timer.Tick -= UiThreadTimerTick;
timer.Stop();
private void UiThreadTimerTick(object sender, EventArgs e)
{
//Must be called on the UI Thread.
Cef.DoMessageLoopWork();
}A more advanced option involves setting [CefSettings.ExternalMessagePump](https://cefsharp.github.io/api/99.2.x/html/P_CefSharp_AbstractCefSettings_ExternalMessagePump.htm) and implementing [IBrowserProcessHandler.OnScheduleMessagePumpWork](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_IBrowserProcessHandler_OnScheduleMessagePumpWork.htm). This allows `CEF` to notify when it needs to perform work, in some instances this may make your application more responsive. See https://github.com/cefsharp/CefSharp/issues/1748 for additional details. There are more advanced/working examples contained within the projects source.
You can hook the message loop whilst using `MultiThreadedMessageLoop`, though this is quite complex. The project source contains an example at https://github.com/cefsharp/CefSharp/blob/v53.0.0/CefSharp.WinForms.Example/BrowserTabUserControl.cs#L224 You can use this method to obtain Win32 mouse messages.
- Popups
bool ILifeSpanHandler.OnBeforePopup(IWebBrowser browserControl, IBrowser browser, IFrame frame, string targetUrl, string targetFrameName, WindowOpenDisposition targetDisposition, bool userGesture, IPopupFeatures popupFeatures, IWindowInfo windowInfo, IBrowserSettings browserSettings, ref bool noJavascriptAccess, out IWebBrowser newBrowser)
{
//Set newBrowser to null unless you're attempting to host the popup in a new instance of ChromiumWebBrowser
newBrowser = null;
return true; //Return true to cancel the popup creation
}You can cancel popup creation and open the URL in a new `ChromiumWebBrowser` instance of your choosing using this method. It is important to note the parent-child relationship will not exist using this method. So in general it's not recommended.
- EXPERIMENTAL** OPTION 1:
- EXPERIMENTAL** OPTION 2:
- Grab the `IBrowserHost` from the newly created `IBrowser` instance that represents the popup then subscribe to window move notifications and call `NotifyMoveOrResizeStarted` - Call `SetWindowPos` on the browser HWND when the size changes (set to 0,0 when hidden to stop rendering)
There are examples in the project source though they are **EXPERIMENTAL** and there are no guarantees they're working. Option 2 has an incomplete example though reports suggest it works well, though the person never contributed a working example.
- JavaScript Integration
- 1. How do you call a JavaScript method from .NET?
- JavaScript Integration
//There are a number of extension methods that simplify execution, they all work on the main frame
//They all exists in the CefSharp.WebBrowserExtensions class, make sure you add "using CefSharp;"
browser.ExecuteScriptAsync("document.body.style.background = 'red';");
// When executing multiple statements, group them together in an IIFE
// https://developer.mozilla.org/en-US/docs/Glossary/IIFE
// For Google.com pre-populate the search text box and click the search button
browser.ExecuteJavaScriptAsync("(function(){ document.getElementsByName('q')[0].value = 'CefSharp Was Here!'; document.getElementsByName('btnK')[0].click(); })();");If you have a web page with multiple frames you can execute the script on the sub frames
browser.GetBrowser().GetFrame("SubFrame").ExecuteJavaScriptAsync("document.body.style.background = 'red';");- When can I start executing JavaScript?
It's tempting to start trying to access the `DOM` in `OnFrameLoadStart`, whilst the `V8Context` will have been created and you will be able to execute a script the `DOM` will not have finished loading. If you need to access the `DOM` at it's earliest possible point then subscribe to `DOMContentLoaded`, some examples of executing `JavaScript` are below.
browser.RenderProcessMessageHandler = new RenderProcessMessageHandler();
public class RenderProcessMessageHandler : IRenderProcessMessageHandler
{
// Wait for the underlying JavaScript Context to be created. This is only called for the main frame.
// If the page has no JavaScript, no context will be created.
void IRenderProcessMessageHandler.OnContextCreated(IWebBrowser browserControl, IBrowser browser, IFrame frame)
{
const string script = "document.addEventListener('DOMContentLoaded', function(){ alert('DomLoaded'); });";
frame.ExecuteJavaScriptAsync(script);
}
}
//Wait for the page to finish loading (all resources will have been loaded, rendering is likely still happening)
browser.LoadingStateChanged += (sender, args) =>
{
//Wait for the Page to finish loading
if (args.IsLoading == false)
{
browser.ExecuteJavaScriptAsync("alert('All Resources Have Loaded');");
}
}
//Wait for the MainFrame to finish loading
browser.FrameLoadEnd += (sender, args) =>
{
//Wait for the MainFrame to finish loading
if(args.Frame.IsMain)
{
args.Frame.ExecuteJavaScriptAsync("alert('MainFrame finished loading');");
}
};Some notes about executing `JavaScript`:
- Scripts are executed at the frame level, and every page has at least one frame (`MainFrame`). - The `IWebBrowser.ExecuteScriptAsync` extension method is left for backwards compatibility, you can use it as a shortcut to execute `js` on the main frame. - If a frame does not contain JavaScript then no `V8Context` will be created. - For a frame that doesn't have a context executing a script once the frame has loaded it's possible to create a V8Context using `IFrame.ExecuteJavaScriptAsync`. - The `DOM` won't have finished loading when `OnFrameLoadStart` is fired - `IRenderProcessMessageHandler.OnContextCreated/OnContextReleased` are only called for the main frame.
- 2. How do you call a JavaScript method that returns a result?
//An extension method that evaluates JavaScript against the main frame.
JavascriptResponse response = await browser.EvaluateScriptAsync(script);
//Evaluate javascript directly against a frame
JavascriptResponse response = await frame.EvaluateScriptAsync(script);
//An extension method that evaluates Javascript Promise against the main frame.
//Uses Promise.resolve to return the script execution into a promise regardless of the return type
//This method differs from EvaluateScriptAsync in that your script **must return** a value
//Examples below
JavascriptResponse response = await browser.EvaluateScriptAsPromiseAsync(script);JavaScript code is executed asynchronously and as such returns [Task](https://cefsharp.github.io/api/99.2.x/html/Properties_T_CefSharp_JavascriptResponse.htm) which contains error message, result and a success (`bool`) flag. Here are the fundamentals you need to know when evaluating `JavaScript`
- Please **make sure you read** [When](#when-can-i-start-executing-javascript). - Scripts are executed at the Frame level, and every page has at least one frame (`MainFrame`). - Scripts are executed in the render process and are transmitted via `IPC`, return **only the data you require** for performance reasons. - Primitive data types int, double, date, bool and string are supported. - Objects are supported to a degree and will be returned as `IDictionary<string,></string,>`, the use of the `dynamic` keyword is supported to make accessing the property values easier. - You cannot directly return a `DOM` [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) (or anything with a cyclic reference), you need to create a new object that has just the information you need to return. - Arrays containing the primitives listed above and objects are supported and will be returned as `IList<object></object>`. - `Array Like` objects like [HTMLCollection](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCollection) cannot be returned directly use [Array.from](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) to return and array - There are limits to the complexity of the object graph that can be returned (graphs with cyclic references aren't supported currently), in these cases you may need to turn the JavaScript object into a JSON string with the JavaScript `JSON.stringify()` method and return that string to your .NET code. Then you can decode that string into a .NET object with something like JSON.NET. See [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) for more details. See https://stackoverflow.com/a/46881092/4583726 for some guidence on using `JSON.stringify` with `HTMLElement`.
//Start with something simple, the following will return the value 2 as type int
//Don't use the `return` keyword
//chromiumWebBrowser.EvaluateScriptAsync executes on the main frame, scripts can be executed
//per frame if required
JavascriptResponse response = await frame.EvaluateScriptAsync("1 + 1");
JavascriptResponse response = await chromiumWebBrowser.EvaluateScriptAsync("1 + 1");
var onePlusOne = (int)response.Result;
//A javascript IFFE will be evaluated and it's result returned.
//https://developer.mozilla.org/en-US/docs/Glossary/IIFE
//If you want to execute multiple lines of javascript then an IIFE is recommended to
//avoid any variable scoping issues
var script = @"(function() { let val = 1 + 1; return val; })();";
JavascriptResponse response = await frame.EvaluateScriptAsync(script);
var onePlusOne = (int)response.Result;
//If your script uses a Promise then you must use the EvaluateScriptAsPromiseAsync method, it differs slightly
//in that you must return the value.
//The following will return a Promise that after one second resolves with a simple objec
var script = "return new Promise(function(resolve, reject) { setTimeout(resolve.bind(null, { a: 'CefSharp', b: 42, }), 1000); });"
JavascriptResponse javascriptResponse = await browser.EvaluateScriptAsPromiseAsync(script);
//You can access the object using the dynamic keyword for convenience.
dynamic result = javascriptResponse.Result;
var a = result.a;
var b = result.b;
//EvaluateScriptAsPromiseAsync calls Promise.resolve internally so even if your code doesn't
//return a Promise it will still execute successfully.
var script = @"return (function() { return 1 + 1; })();";
JavascriptResponse response = await frame.EvaluateScriptAsPromiseAsync(script);
// An example that gets the Document Height
var task = frame.EvaluateScriptAsync("(function() { var body = document.body, html = document.documentElement; return Math.max( body.scrollHeight, body.offsetHeight, html.clientHeight, html.scrollHeight, html.offsetHeight ); })();");
//Continue execution on the UI Thread
task.ContinueWith(t =>
{
if (!t.IsFaulted)
{
var response = t.Result;
EvaluateJavaScriptResult = response.Success ? (response.Result ?? "null") : response.Message;
}
}, TaskScheduler.FromCurrentSynchronizationContext());
//HTMLElement/HTMLCollection Examples
//As stated above, you cannot return a HTMLElement/HTMLCollection directly.
//It's best to return only the data you require, here are some examples of using Array.from to convert a HTMLCollection into an array of objects
//which can be returned to your .Net application.
//Get all the span elements and create an array that contains their innerText
var script = @"Array.from(document.getElementsByTagName('span')).map(x => ( x.innerText));";
JavascriptResponse response = await frame.EvaluateScriptAsync(script);
//Get all the a tags and create an array that contains a list of objects
//Second param is the mapping function
var script = @"Array.from(document.getElementsByTagName('a'), x => ({ innerText : x.innerText, href : x.href }));";
JavascriptResponse response = await frame.EvaluateScriptAsync(script);
//List of Links, click represents a function pointer which can be used to execute the link click)
//In .Net the https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_IJavascriptCallback.htm is used
//to represent the function.
var script = @"Array.from(document.getElementsByTagName('a')).map(x => ({ innerText: x.innerText, click: x.click}));";
JavascriptResponse response = await frame.EvaluateScriptAsync(script);
//Execute the following against google.com to get the `I'm Feeling Lucky` button then click the button in .Net
//NOTE: This is a simple example, you could return an aggregate object consisting of data from multiple html elements.
const string script = @"(function()
{
let element = document.getElementsByName('btnI')[0];
let obj = {};
obj.id = element.id;
obj.nodeValue = element.nodeValue;
obj.localName = element.localName;
obj.tagName = element.tagName;
obj.innerText = element.innerText;
obj.click = element.click;
obj.attributes = Array.from(element.attributes).map(x => ({name: x.name, value: x.value}));
return obj;
})();";
var javascriptResponse = await chromiumWebBrowser.EvaluateScriptAsync(script);
dynamic result = javascriptResponse.Result;
var clickJavascriptCallback = (IJavascriptCallback)result.click;
await clickJavascriptCallback.ExecuteAsync();
//Dispose of the click callback when done
clickJavascriptCallback.Dispose();
//Get all rows/cells for the first table in the DOM
//dynamic can be used in c# to simplify accessing the result
var response = await chromiumWebBrowser.EvaluateScriptAsync(@"(function (){
let srcTable = document.getElementsByTagName('table')[0];
return Array.from(srcTable.rows, row => Array.from(row.cells, cell => cell.innerText));
})();
");
dynamic arr = response.Result;
foreach(dynamic row in arr)
{
foreach(var cell in row)
{
var data = (string)cell;
}
}Additional examples see [Gist](https://gist.github.com/amaitland/9d354376960b0cd9305a#file-oneplusone-cs)
- 3. How do you expose a .NET class to JavaScript?
- Async JavaScript Binding (JSB)
- Summary**
- See the [Advanced](https://github.com/cefsharp/CefSharp/wiki/Advanced-Async-JavaScript-Binding-(JSB)), **please make sure you finish reading this first**.
If you are not familiar with all `Chromium` has to offer when it comes to `async programming` here are some very useful articles
- https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise - https://developers.google.com/web/fundamentals/primers/async-functions - https://developers.google.com/web/fundamentals/primers/promises
- Binding an `Async` object in `JavaScript`
- The simple workflow would look like:**
- Only Methods are supported.** If you need to set a property, then create `Get`/`Set` methods.
- Step 1** Create a class
public class BoundObject
{
public int Add(int a, int b)
{
return a + b;
}
}- Step 2** Register an instance of your class with the `JavaScriptObjectRepository`
First Option:
//For async object registration (equivalent to the old RegisterAsyncJsObject)
browser.JavascriptObjectRepository.Register("boundAsync", new BoundObject(), true, BindingOptions.DefaultBinder);Second Option (Preferred):
browser.JavascriptObjectRepository.ResolveObject += (sender, e) =>
{
var repo = e.ObjectRepository;
if (e.ObjectName == "boundAsync")
{
BindingOptions bindingOptions = null; //Binding options is an optional param, defaults to null
bindingOptions = BindingOptions.DefaultBinder //Use the default binder to serialize values into complex objects
bindingOptions = new BindingOptions { Binder = new MyCustomBinder() }); //Specify a custom binder
repo.NameConverter = null; //No CamelCase of Javascript Names
//For backwards compatability reasons the default NameConverter doesn't change the case of the objects returned from methods calls.
//https://github.com/cefsharp/CefSharp/issues/2442
//Use the new name converter to bound object method names and property names of returned objects converted to camelCase
repo.NameConverter = new CamelCaseJavascriptNameConverter();
repo.Register("boundAsync", new BoundObject(), isAsync: true, options: bindingOptions);
}
};To be notified in `.Net` when objects have been bound in `JavaScript` then you can subscribe to [ObjectBoundInJavascript](https://cefsharp.github.io/api/99.2.x/html/E_CefSharp_IJavascriptObjectRepository_ObjectBoundInJavascript.htm) event or the [ObjectsBoundInJavascript](https://cefsharp.github.io/api/99.2.x/html/E_CefSharp_IJavascriptObjectRepository_ObjectsBoundInJavascript.htm) event (both events are very similar obviously).
browser.JavascriptObjectRepository.ObjectBoundInJavascript += (sender, e) =>
{
var name = e.ObjectName;
Debug.WriteLine($"Object {e.ObjectName} was bound successfully.");
}; - Step 3** Call [CefSharp.BindObjectAsync](https://github.com/cefsharp/CefSharp/wiki/JavaScript-Binding-API#cefsharpbindobjectasyncsettings-objectname)
<script type="text/javascript">
(async function()
{
await CefSharp.BindObjectAsync("boundAsync");
//The default is to camel case method names (the first letter of the method name is changed to lowercase)
boundAsync.add(16, 2).then(function (actualResult)
{
const expectedResult = 18;
assert.equal(expectedResult, actualResult, "Add 16 + 2 resulted in " + expectedResult);
});
})();When a [CefSharp.BindObjectAsync](https://github.com/cefsharp/CefSharp/wiki/JavaScript-Binding-API#cefsharpbindobjectasyncsettings-objectname) call is made, the `JavascriptObjectRepository` is queried to see if an object with the given name is already registered, if no matching object is found then the `ResolveObject` event is raised. For calls to [CefSharp.BindObjectAsync](https://github.com/cefsharp/CefSharp/wiki/JavaScript-Binding-API#cefsharpbindobjectasyncsettings-objectname) without any params, then if objects have already been registered then they will all be bound, if no objects have been registered then `ResolveObject` will be called with the `ObjectName` set to `All`.
Only the basics are covered in this section, there are many advanced options check out [Advanced](https://github.com/cefsharp/CefSharp/wiki/Advanced-Async-JavaScript-Binding-(JSB))
If you'd like to see a working example then checkout [CefSharp](https://github.com/cefsharp/CefSharp.MinimalExample/tree/demo/javascriptbinding) branch, specifically [commit](https://github.com/cefsharp/CefSharp.MinimalExample/commit/9f817888fad8e5f7c602f90170102cec2db29a5f)
---
- Sync JavaScript Binding (JSB)
- THIS IS A LEGACY FEATURE** - anyone creating a new application use the [Async](#async-javascript-binding-jsb) implementation as it's under active development. The `Sync` version will only receive bug fixes for regressions.
- Binding an object in `JavaScript`
The simple workflow would look like:
- **Step 1** Create a class that you wish to expose to JavaScript (don't use your `Form/Window` or `Control`) - **Step 2** Call `CefSharp.BindObjectAsync` with the name of the object you wish to register, e.g. `CefSharp.BindObjectAsync("myObject");` (Objects will only be available after the `Promise` has resolved. - **Step 3** Register your object with the `JavaScriptObjectRepository`
- Step 1**
public class BoundObject
{
public string MyProperty { get; set; }
public void MyMethod()
{
// Do something really cool here.
}
public void TestCallback(IJavascriptCallback javascriptCallback)
{
const int taskDelay = 1500;
Task.Run(async () =>
{
await Task.Delay(taskDelay);
using (javascriptCallback)
{
//NOTE: Classes are not supported, simple structs are
var response = new CallbackResponseStruct("This callback from C# was delayed " + taskDelay + "ms");
await javascriptCallback.ExecuteAsync(response);
}
});
}
}- Step 2** Call `CefSharp.BindObjectAsync`, Some examples below of `Binding` an object look like:
- NOTE** This is a two part process, see below the examples for details
<script type="text/javascript">
(async function()
{
await CefSharp.BindObjectAsync("boundAsync");
boundAsync.div(16, 2).then(function (actualResult)
{
const expectedResult = 8
assert.equal(expectedResult, actualResult, "Divide 16 / 2 resulted in " + expectedResult);
});
boundAsync.error().catch(function (e)
{
var msg = "Error: " + e + "(" + Date() + ")";
});
})();
(async () =>
{
await CefSharp.BindObjectAsync("boundAsync");
boundAsync.hello('CefSharp').then(function (res)
{
assert.equal(res, "Hello CefSharp")
});
})();
CefSharp.BindObjectAsync("boundAsync2").then(function(result)
{
boundAsync2.hello('CefSharp').then(function (res)
{
assert.equal(res, "Hello CefSharp")
// NOTE the ability to delete a bound object
assert.equal(true, CefSharp.DeleteBoundObject("boundAsync2"), "Object was unbound");
assert.ok(window.boundAsync2 === undefined, "boundAsync2 is now undefined");
});
});
</script>- Step 3**
When a `CefSharp.BindObjectAsync` call is made, the `JavascriptObjectRepository` is queries to see if an object with the given name is specified is already registered, if no matching object is found then the `ResolveObject` event is raised. For calls to `CefSharp.BindObjectAsync` without any params, then if objects have already been registered then they will all be bound, if no objects have been registered then `ResolveObject` will be called with the `ObjectName` set to `All`.
//When a
browser.JavascriptObjectRepository.ResolveObject += (sender, e) =>
{
var repo = e.ObjectRepository;
if (e.ObjectName == "boundAsync2")
{
BindingOptions bindingOptions = null; //Binding options is an optional param, defaults to null
bindingOptions = BindingOptions.DefaultBinder //Use the default binder to serialize values into complex objects,
bindingOptions = new BindingOptions { Binder = new MyCustomBinder() }); //No camelcase of names and specify a custom binder
//For backwards compatability reasons the default NameConverter doesn't change the case of the objects returned from methods calls.
//https://github.com/cefsharp/CefSharp/issues/2442
//Use the new name converter to bound object method names and property names of returned objects converted to camelCase
repo.NameConverter = new CamelCaseJavascriptNameConverter();
repo.Register("bound", new BoundObject(), isAsync: false, options: bindingOptions);
}
};In the actual JS code, you would use the object like this (default is to CamelCase Javascript Names, this is controllable via [JavascriptObjectRepository.NameConverter](https://cefsharp.github.io/api/99.2.x/html/P_CefSharp_IJavascriptObjectRepository_NameConverter.htm), see above for an example).
bound.myProperty; // use this syntax to access the property
bound.myMethod(); // use this to call the method.
bound.testCallback(callback); //Pass a function in to use as a callback_**Please note:**_ - **DO NOT REGISTER YOUR FORM/WINDOW/CONTROL**. Create a class and proxy calls if required. - By default, methods and properties are changed into _camelCase_ (i.e. the first letter is lower-cased) to make its usage be natural in JavaScript code. To disable set [browser.JavascriptObjectRepository.NameConverter](https://cefsharp.github.io/api/99.2.x/html/P_CefSharp_IJavascriptObjectRepository_NameConverter.htm) to null - Complex objects are supported for properties (where applicable) so you can now do `bound.subObject.myFunction()` and `bound.subObject.myProperty = 1`. - Complex object support for functions is now possible thorugh the `IBinder` interface, you can implement your own or use the `DefaultBinder` e.g. `repo.Register("bound", new BoundObject(), BindingOptions.DefaultBinder);`
- RegisterAsyncJsObject
- RegisterJsObject
- Adobe Flash Player (Pepper Flash)
- NOTE**: Flash is now deprecated and `Chromium` has removed support, see https://www.chromium.org/flash-roadmap#TOC-Upcoming-Changes for further details.
- Offscreen Rendering (OSR)
- WPF
A special note should be made about hosting the `ChromiumWebBrowser` within a `ViewBox`. This is far from ideal, as every frame is rendered then post-processing happens to resize/scale the image. This is a huge performance hit and often reduces quality (it's usually quite blurry). You can adjust the resize quality using `RenderOptions.SetBitmapScalingMode`. It's best to avoid using a `ViewBox`. You can scale the content contained within the browser by adjusting the `ZoomLevel`, which is by far the most performant option.
- OffScreen
- UserAgent
var settings = new CefSettings();
settings.UserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36 - Testing 123";
Cef.Initialize(settings);2) Starting with version `85`, the `UserAgent` can be changed at runtime using the DevTools protocol.
using (var client = chromiumWebBrowser.GetDevToolsClient())
{
_ = client.Network.SetUserAgentOverrideAsync("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36 - Testing 123");
}To change the `UserAgent` at runtime before the browser has made it's first request see https://gist.github.com/amaitland/0b05701710064203171bfd05f5002514#file-setuseragentoverrideasync-cs for an example.
3) You can modify the `User-Agent` HTTP header in `IResourceRequestHandler.OnBeforeResourceLoad`, which would need to be done for every request. What it doesn't do is change the `UserAgent` the browser reports to JavaScript.
public class CustomResourceRequestHandler : CefSharp.Handler.ResourceRequestHandler
{
protected override CefReturnValue OnBeforeResourceLoad(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request, IRequestCallback callback)
{
//Set the header by name, override the existing value
request.SetHeaderByName("user-agent", "MyBrowser CefSharp Browser", true);
return CefReturnValue.Continue;
}
}
public class CustomRequestHandler : CefSharp.Handler.RequestHandler
{
protected override IResourceRequestHandler GetResourceRequestHandler(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request, bool isNavigation, bool isDownload, string requestInitiator, ref bool disableDefaultHandling)
{
//Where possible only intercept specific Url's
//Load https://www.whatismybrowser.com/detect/what-is-my-user-agent in the browser and you'll
//see our custom user agent
if (request.Url == "https://www.whatismybrowser.com/detect/what-is-my-user-agent")
{
return new CustomResourceRequestHandler();
}
//Default behaviour, url will be loaded normally.
return null;
}
}
browser.RequestHandler = new CustomRequestHandler();- DevTools
browser.ShowDevTools();You can connect Chrome to a running instance. This will likely give you more options (not all that exist within Chrome unfortunately).
var settings = new CefSettings();
settings.RemoteDebuggingPort = 8088;
Cef.Initialize(settings);Open `http://localhost:8088` in Chrome.
- Screenshots
- [Page.CaptureScreenshotAsync](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_DevTools_Page_PageClient_CaptureScreenshotAsync.htm) - DevTools [Page.captureScreenshot](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-captureScreenshot) API for upstream documentation.
The example below shows capturing with default settings. Additionally you can specify viewport size, quality, and other options.
//Make sure to dispose of our observer registration when done
//If you need to make multiple calls then reuse the devtools client
//and Dispose when done.
using (var devToolsClient = chromiumWebBrowser.GetDevToolsClient())
{
var result = await devToolsClient.Page.CaptureScreenshotAsync();
return result.Data;
}The example below queries the current size of the content and captures currently rendered content. Note: Pages that delay load their content will need to be forced to render before you can take a whole page screenshot.
using (var devToolsClient = chromiumWebBrowser.GetDevToolsClient())
{
//Get the content size
var layoutMetricsResponse = await devToolsClient.Page.GetLayoutMetricsAsync();
var contentSize = layoutMetricsResponse.ContentSize;
var viewPort = new Viewport()
{
Height= contentSize.Height,
Width = contentSize.Width,
X = 0,
Y = 0,
Scale = 1
};
// https://bugs.chromium.org/p/chromium/issues/detail?id=1198576#c17
var result = await devToolsClient.Page.CaptureScreenshotAsync(clip: viewPort, fromSurface:true, captureBeyondViewport: true);
return result.Data;
}Additionally the DevTools protocol can be used to stream frames using [Page.screencastFrame](https://chromedevtools.github.io/devtools-protocol/tot/Page/#event-screencastFrame). [Page](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_DevTools_Page_PageClient.htm) API doc for methods/events currently avaliable.
- OffScreen/WPF
- Lower frame rate, to make it easier to capture frames may be worth considering - You'll need to wait a period of time after the page has finished loading to allow the browser to render - There is currently no method of determining when a web page has finished rendering (and unlikely ever will be as with features like flash, dynamic content, animations, even simple tasks like moving your mouse or scrolling will cause new frames to be rendered). - A hack method to determine when rendering has approximately finished is to have a timer that's reset every time a frame is rendered, when no additional frames are rendered then the timer will file (not ideal)
- WinForms
- Win32 Out of Memory
As per suggestion in http://magpcss.org/ceforum/viewtopic.php?f=6&t=15120#p34802 it appears that setting The Large Address Aware linker setting on your application executable when running as a 32bit application may now be necessary where high memory load is experienced.
- https://msdn.microsoft.com/en-us/library/wz223b1z.aspx - https://www.nuget.org/packages/LargeAddressAware/
The default x86 SubProcess shipped with CefSharp is large address aware, you should make your application large address aware as well.
After applying the Large Address Aware linker setting to your executable, if your still experiencing the exact same problem then discuss your issue at http://magpcss.org/ceforum/viewtopic.php?f=6&t=15120
- Load URL with PostData
public class CustomRequestHandler : CefSharp.Handler.RequestHandler
{
protected override IResourceRequestHandler GetResourceRequestHandler(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request, bool isNavigation, bool isDownload, string requestInitiator, ref bool disableDefaultHandling)
{
//Where possible only intercept specific Url's
//Load http://httpbin.org/post in the browser and you'll
//see the post data
if (request.Url == "http://httpbin.org/post")
{
return new CustomResourceRequestHandler();
}
//Default behaviour, url will be loaded normally.
return null;
}
}
public class CustomResourceRequestHandler : CefSharp.Handler.ResourceRequestHandler
{
protected override CefReturnValue OnBeforeResourceLoad(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request, IRequestCallback callback)
{
//Modify the request to add post data
//Make sure to read https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST
var postData = new PostData();
postData.AddData("test=123&data=456");
request.Method = "POST";
request.PostData = postData;
//Set the Content-Type header to whatever suites your requirement
request.SetHeaderByName("Content-Type", "application/x-www-form-urlencoded", true);
//Set additional Request headers as required.
return CefReturnValue.Continue;
}
}
//Load http://httpbin.org/post in the browser to see the post data
browser = new ChromiumWebBrowser("http://httpbin.org/post");
browser.RequestHandler = new CustomRequestHandler();The second method is to use [IFrame.LoadRequest](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_IFrame_LoadRequest.htm), this method can only be used if you have first successfully performed to a domain of the same origin. For example, you must navigate to say http://httpbin.org/ before you can call [IFrame.LoadRequest](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_IFrame_LoadRequest.htm) for http://httpbin.org/post.
public void LoadCustomRequestExample()
{
var frame = browser.GetMainFrame();
//Create a new request knowing we'd like to use PostData
var request = frame.CreateRequest(initializePostData:true);
request.Method = "POST";
request.Url = "http://httpbin.org/post";
//Set AllowStoredCredentials so cookies are sent with Request
request.Flags = UrlRequestFlags.AllowStoredCredentials;
request.PostData.AddData("test=123&data=456");
frame.LoadRequest(request);
}The [browser.LoadUrlWithPostData](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_WebBrowserExtensions_LoadUrlWithPostData.htm) extension method can be used for simple cases, it calls `LoadRequest` and the same restrictions regarding having performed a successful navigation apply.
- Spellchecking
Spellcheck can only be changed dynamically using `spellcheck.dictionaries` preference (important to use the plural version) https://bitbucket.org/chromiumembedded/cef/issues/2222/spell-checking-language-cannot-be-changed#comment-38338016
Here are some useful links
http://magpcss.org/ceforum/viewtopic.php?f=6&t=14911&p=33882&hilit=spellcheck#p33882 https://cs.chromium.org/chromium/src/components/spellcheck/browser/pref_names.cc?type=cs&q=%22spellcheck.dictionary%22&l=11 https://cs.chromium.org/chromium/src/components/spellcheck/browser/pref_names.cc?type=cs&q=%22spellcheck.dictionary%22&l=15
Not all language support spell checking, see https://magpcss.org/ceforum/viewtopic.php?f=6&t=16508#p40684
- WebAssembly
For older versions you need to manually enable `WebAssembly` see https://bitbucket.org/chromiumembedded/cef/issues/2101/add-webassembly-support
`settings.javascript_flags` translates to `settings.JavascriptFlags = "--expose-wasm";`
- Exception Handling
http://stackoverflow.com/questions/233255/how-does-setunhandledexceptionfilter-work-in-net-winforms-applications https://msdn.microsoft.com/en-us/library/windows/desktop/ms680634(v=vs.85).aspx https://referencesource.microsoft.com/#System.Windows.Forms/winforms/Managed/System/WinForms/Application.cs,8243b844777a16c3 https://referencesource.microsoft.com/#System.Windows.Forms/winforms/Managed/System/WinForms/Application.cs,3192
Capturing unhandled exceptions in a mixed native/CLR environment http://www.ikriv.com/blog/?p=1440
- Dependency Checking
//Perform dependency check to make sure all relevant resources are in our output directory.
//https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_Cef_Initialize_1.htm
Cef.Initialize(settings, performDependencyCheck: true, browserProcessHandler: null);
//Manually check
//https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_DependencyChecker.htm
DependencyChecker.AssertAllDependenciesPresent(cefSettings.Locale, cefSettings.LocalesDirPath, cefSettings.ResourcesDirPath, cefSettings.PackLoadingDisabled, cefSettings.BrowserSubprocessPath);
```
It's not `100%` foolproof, if your having problems and all resources exist then disable dependency checking. There are certain scenarios when it's not going to work.
https://github.com/cefsharp/CefSharp/wiki/Output-files-description-table-%28Redistribution%29
## Multimedia (Audio/Video)
`CEF` and subsequently `CefSharp` only supports freely available audio and video codecs. To see what the version of `CefSharp` you are working with supports open http://html5test.com/ in a `ChromiumWebBrowser` instance.
- `MP3` patent has expired and as a result is supported in version `65.0.0` on wards.
- `H264/AAC` are classed as `Proprietary Codecs` and are not supported, they require you to obtain a license. Sites like `Netflix/Twitter/Instagram` use `H264` and as a result their videos won't play. See https://www.fsf.org/licensing/h264-patent-license for some comments from the `Free Software Foundation` on the subject.
Compiling `CEF` with support for `H264/AAC` is outside the scope of this project. The following are provided for reference only, please don't ask for support for compiling `CEF`.
- http://magpcss.org/ceforum/viewtopic.php?f=6&t=13515
- https://github.com/cefsharp/CefSharp/issues/1934#issuecomment-279305821
- https://github.com/mitchcapper/CefSharpDockerfiles
## OnScreen (Virtual) Keyboard
The `WinForms` version has built in support for onscreen keyboard, it has been reported that on occasion it doesn't always popup correctly, using `disable-usb-keyboard-detect` command line argument
https://github.com/cefsharp/CefSharp/issues/1691#issuecomment-323603277 has reported to resolve this problem.
The `WPF` does not have built in support for onscreen (virtual) keyboard, starting with version `73` a new `VirtualKeyboardRequested` event now provides notification when you application should display a virtual keyboard. Unfortunately it's difficult to provide a default implementation that supports `Windows 7, 8.1 and 10` as there is no `.Net API` for display a virtual keyboard. A `Windows 10 Only` example was added in https://github.com/cefsharp/CefSharp/commit/0b57e526158e57e522d46671404c557256529416 If you need to support `Windows 8 and 10` then https://github.com/maximcus/WPFTabTip might be useful. For `Windows 7` https://stackoverflow.com/questions/1168203/incorporating-the-windows-7-onscreen-keyboard-into-a-wpf-app has some suggestions.
## Protocol Execution
The following example calls [Process.Start](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.process.start?view=net-5.0) to open a `mailto` link with the default associated mail client.
```c#
public class CustomRequestHandler : CefSharp.Handler.RequestHandler
{
protected override bool OnBeforeBrowse(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IRequest request, bool userGesture, bool isRedirect)
{
//For security reasons you should perform validation on the url to confirm that it's safe before proceeding.
if (request.Url.StartsWith("mailto:"))
{
//Cancel the request and defer to Windows to open the Url with the associated
//Handler (in this case the default email client should be opened).
Process.Start(request.Url);
return true;
}
return base.OnBeforeBrowse(chromiumWebBrowser, browser, frame, request, userGesture, isRedirect);
}
}
browser.RequestHandler = new CustomRequestHandler();- Cookie Manager
- Create/Update Cookie
using CefSharp;
var cookieManager = Cef.GetGlobalCookieManager();
//success == false if an invalid URL is specified or if cookies cannot be accessed.
//The cookie itself will be created/updated async, use SetCookieAsync (example below) to be sure
//the cookie has been created/updated successfully.
var success = cookieManager.SetCookie("custom://cefsharp/home.html", new Cookie
{
Name = "CefSharpTestCookie",
Value = "ILikeCookies",
Expires = DateTime.Now.AddDays(1)
});Cookies are created in an async fashion, using [ICookieManager.SetCookieAsync](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_AsyncExtensions_SetCookieAsync.htm) if you need to make sure the cookie has been created before continuing then use
using CefSharp;
var cookieManager = Cef.GetGlobalCookieManager();
//If success == true the cookie will have been created/updated successfully.
var success = await cookieManager.SetCookieAsync("custom://cefsharp/home.html", new Cookie
{
Name = "CefSharpTestCookie",
Value = "ILikeCookies",
Expires = DateTime.Now.AddDays(1)
});- Delete Cookie(s)
using CefSharp;
var cookieManager = Cef.GetGlobalCookieManager();
//Delete cookies by name
await cookieManager.DeleteCookiesAsync(url: "custom://cefsharp/home.html", name: "CefSharpTestCookie");
//Delete all cookies for a Url
await cookieManager.DeleteCookiesAsync(url: "custom://cefsharp/home.html");
//Delete all cookies for the cookie manager
await cookieManager.DeleteCookiesAsync();- Retrieve Cookies
using CefSharp;
var cookieManager = Cef.GetGlobalCookieManager();
//Using await
var result = await cookieManager.VisitUrlCookiesAsync("custom://cefsharp/home.html", includeHttpOnly: false);
var cookieCount = result.Count;
//Using ContinueWith
cookieManager.VisitUrlCookiesAsync("custom://cefsharp/home.html", includeHttpOnly: false).ContinueWith(t =>
{
if (t.Status == TaskStatus.RanToCompletion)
{
//All the cookies for the specified URL
var cookies = t.Result;
foreach (var cookie in cookies)
{
Debug.WriteLine("CookieName: " + cookie.Name);
}
}
else
{
Debug.WriteLine("No Cookies found");
}
});If you are using multiple [RequestContexts](#request-context-browser-isolation) then you can use the [IWebBrowser.GetCookieManager](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_WebBrowserExtensions_GetCookieManager.htm) extension method. (All instances of `ChromiumWebBrowser` implement `IWebBrowser`). This will also work when using the default Global Cookie Manager.
using CefSharp;
var cookieManager = chromiumWebBrowser.GetCookieManager();
var result = await cookieManager.VisitUrlCookiesAsync("custom://cefsharp/home.html", includeHttpOnly: false);
var cookieCount = result.Count;- Cookie Manager Initialized
using CefSharp;
public class BrowserProcessHandler : IBrowserProcessHandler
{
void IBrowserProcessHandler.OnContextInitialized()
{
//The Global CookieManager has been initialized, you can now create/retrieve/update/delete cookies
var cookieManager = Cef.GetGlobalCookieManager();
}
void IBrowserProcessHandler.OnScheduleMessagePumpWork(long delay)
{
}
public virtual void Dispose()
{
}
}
var settings = new CefSettings()
{
//By default CefSharp will use an in-memory cache, you need to specify a Cache Folder to persist data
CachePath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "CefSharp\\Cache")
};
Cef.Initialize(settings, performDependencyCheck: true, browserProcessHandler: new BrowserProcessHandler());Alternatively [Cef.GetGlobalCookieManager](https://cefsharp.github.io/api/99.2.x/html/M_CefSharp_Cef_GetGlobalCookieManager.htm) takes a [ICompletionCallback](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_ICompletionCallback.htm) param which can be used to wait for the cookie store to be initialized. [TaskCompletionCallback](https://cefsharp.github.io/api/99.2.x/html/T_CefSharp_TaskCompletionCallback.htm) is a default implement that exposes a Task.
using CefSharp;
var callback = new TaskCompletionCallback();
var cookieManager = Cef.GetGlobalCookieManager(callback);
await callback.Task.ConfigureAwait(false);
return cookieManager;- SSL/TLS Certificate Errors
- Option 1 (Preferred)
- SSL/TLS Certificate Errors
//Make sure you assign your RequestHandler instance to the `ChromiumWebBrowser`
browser.RequestHandler = new ExampleRequestHandler();
public class ExampleRequestHandler : RequestHandler
{
protected override bool OnCertificateError(IWebBrowser chromiumWebBrowser, IBrowser browser, CefErrorCode errorCode, string requestUrl, ISslInfo sslInfo, IRequestCallback callback)
{
//NOTE: I suggest wrapping callback in a using statement or explicitly execute callback.Dispose as callback wraps an unmanaged resource.
//Example #1
//Return true and call IRequestCallback.Continue() at a later time to continue or cancel the request.
//In this instance we'll use a Task, typically you'd invoke a call to the UI Thread and display a Dialog to the user
Task.Run(() =>
{
//NOTE: When executing the callback in an async fashion need to check to see if it's disposed
if (!callback.IsDisposed)
{
using (callback)
{
//We'll allow the expired certificate from badssl.com
if (requestUrl.ToLower().Contains("https://expired.badssl.com/"))
{
callback.Continue(true);
}
else
{
callback.Continue(false);
}
}
}
});
return true;
//Example #2
//Execute the callback and return true to immediately allow the invalid certificate
//callback.Continue(true); //Callback will Dispose it's self once exeucted
//return true;
//Example #3
//Return false for the default behaviour (cancel request immediately)
//callback.Dispose(); //Dispose of callback
//return false;
}
}- Option 2
var settings = new CefSettings();
settings.CefCommandLineArgs.Add("ignore-certificate-errors");
Cef.Initialize(settings);