Preface
When I had just graduated and started working, I spent some time studying CEF and solved several fairly painful problems. After changing direction later, I stopped paying attention to it. Then, a few days ago, someone I did not know somehow found my QQ and added me to ask a few CEF-related questions. At that moment I suddenly realized that this experience might be worth recording. This is written for myself from four years ago.
Background
On the .NET platform, Microsoft’s built-in WebBrowser
control has several problems:
- It cannot guarantee a consistent browser version. On Windows XP, you
may be calling IE 6.0, while on Windows 7 or later, the version used by
WebBrowsermay still differ from the IE version installed on the machine. - HTML compatibility is troublesome. Different browsers interpret the
same page differently. Even when IE 8 or a newer IE browser is
installed, the
WebBrowsercontrol defaults to IE7 compatibility mode, which causes many page styles to render incorrectly. For example, IE7 does not support HTML5. One workaround is to specify the IE version for your process in the registry.
More details can be found here.
To solve these problems more thoroughly, after some research we
decided to use a third-party open-source browser: the Chromium Embedded
Framework, or CEF. CEF is an open-source project created by Marshall
Greenblatt in 2008. Its main purpose is to provide a
WebBrowser control based on Google Chromium. CEF supports a
range of programming languages and operating systems, and it can be
integrated fairly easily into both new and existing projects.
Its design goal is ease of use while still taking performance into account. The basic CEF framework exposes C/C++ APIs through native libraries. These libraries isolate the host application from the implementation details of Chromium and WebKit. CEF provides tight integration between the browser control and the host application. It supports plugins, custom protocols, JavaScript objects, and JavaScript extensions. The host application can control resource downloading, navigation, printing, and more, while benefiting from performance and HTML5 support similar to Google Chrome.
The overall dependency structure of CEFGlue is shown above. There were two urgent and tricky problems:
- Make CEF support regular audio and video playback.
- Solve the problem of JavaScript calling native functionality.
CEF Audio and Video Support
To make CEF support common audio and video playback, the CEF kernel needs to be rebuilt.
CEF Kernel Build Process
The CEF kernel build process is full of tears. Anyone who has built it probably knows that feeling. Here is a summary of the steps and things to watch out for:
- The operating system must be Windows 7 Ultimate, and it must be 64-bit. 32-bit is not supported.
- The system language must be set to English, otherwise various encoding errors may appear. The setting is under Control Panel -> Region -> Administrative -> Language.
- Install Visual Studio 2013 Update 4. Earlier versions are not supported.
- Prepare a stable and reliable VPN. It must really be stable.
- Install
depot_tools. After downloading it, unzip it directly. Download URL: https://src.chromium.org/svn/trunk/tools/depot_tools.zip
- Configure the
depot_toolsenvironment variables: set GYP_GENERATORS=ninja,msvs-ninja set GYP_MSVS_VERSION=2013 set DEPOT_TOOLS_WIN_TOOLCHAIN=0 set USE_PROPRIETARY_CODECS=1
- Download the Chromium source code. CEF cannot be built independently; it depends on Chromium. - Choose a folder without special characters or Chinese characters, such as
workspace/chromium/. - Enter the folder and runfetch --nohooks chromium. This takes a very long time. If it fails midway, rungclient sync. - Determine the CEF kernel version, then determine the corresponding Chrome version, for example4d096306deb9e86953c81f08454dd6db07b406b5. - Fetch the required Chromium revision:gclient sync --revision 4d096306deb9e86953c81f08454dd6db07b406b5 --jobs 16This step can take a very long time, so patience is required.
- Copy the matching CEF source directory into
chromium/src. Modify the CEF build options: opencef.gypiand add these two lines:'proprietary_codecs': 1,'ffmpeg_branding':'Chrome',To inspect detailed audio and video codec support, check:workspace\chromium\src\third_party\ffmpeg\chromium\scripts\build_ffmpeg.py
- Build CEF:
export GYP_GENERATORS='ninja'cd workspace/chromium/src/cefcef_create_projects.batcd workspace/chromium/srcninja -C out/Release cefclient cef_unittests
- Package the CEF kernel:
cd workspace/chromium/src/cef/toolsmake_distrib.bat --ninja-build
CEF Kernel H5 Score
- Chromium version: 43.0.2357.81
- CEF version: 3.2357.1280.geba024d
- Dependency chain: CEFGlue -> CEF -> Chromium
JavaScript Calling Native Functionality
Xilium CefGlue is an open-source WebKit-kernel browser
project based on the Chromium Embedded Framework (CEF). It
wraps many parts with .NET, has many advantages, and the kernel keeps
evolving, so it has good prospects. However, it has one serious problem:
CLR Object cannot interact smoothly with frontend
JavaScript. The implementation is complicated and
tedious.
Official Native Registration Method
The native method provided officially requires the class object to
inherit from CefV8Handler. All operations must be written
inside that class’s Execute() method. All properties and
methods of the class object must have corresponding JavaScript code
manually written in the background for registration and binding. If you
want to perform different operations, you need to keep writing a large
number of class objects, because each class can only do one thing.
The steps are as follows:
- Define
MyV8Handler, inheriting fromCefV8Handler. Note that the registered object must inherit fromCefV8Handler, which means the registered object is constrained.
1 | public class MyV8Handler : CefV8Handler |
- Define
WpfRenderProcessHandler, inheriting fromCefRenderProcessHandler, and override theOnWebKitInitialized()event. Inside it, write the operations to execute, manually generate JavaScript according to the class structure, and register it through the officialRegisterExtensionmethod. Notice that registration is completed inOnWebKitInitialized, which means the timing is also constrained. Once WebKit initialization finishes, the registration opportunity is gone.
1 | class WpfRenderProcessHandler:CefRenderProcessHandler |
- In the
Execute()event ofMyV8Handler, write the operation logic:
1 | protected override bool Execute(string name, CefV8Value obj, CefV8Value[] arguments, out CefV8Value returnValue, out string exception) |
- Write a web page and call it from JavaScript, for example:
myHandle.myFunction().
As you can see, registering one native method costs a lot. The native registration method is also rigid. To support different operations, you need to keep writing many class objects, because each class can only do one thing. This has neither generality nor extensibility, and the resulting code is almost lifeless.
Advanced Registration Method
Understanding the Core Registration Principle
Although the official registration approach is extremely verbose, the
core principle is not hard to discover:
registration essentially asks the V8 context to remember a
method name and its parameter count and types. It tells the V8 engine
that when it encounters a registered name, it should pass the method
name and arguments out through the Execute method, and then
native code can match and invoke the local method. As for who calls
Execute and how it is called, the V8 engine handles that;
we do not need to care.
Once this core principle is clear, and since .NET has good reflection support, it is natural to infer that given a CLR object, we can use reflection to analyze its method list and obtain the parameter count and parameter type list for each method. With that information, we can register automatically and implement a general-purpose registration scheme.
Multi-process Communication Solution
Starting from CEF 3.0, CEF moved from the old single-process model to a multi-process model. For example, rendering is handled by a dedicated render process, while the main process, the Browser process, communicates with the Render process through message passing.
Because registered objects can only be registered in the V8 context, and the V8 context can only be accessed by the Render process, registering a native object usually means serializing the native object in the Browser process, sending it to the Render process, deserializing it there, and then registering it.
However, this approach runs into a serious practical problem: not every object in .NET supports serialization. This is especially true when the object comes from an already packaged DLL that we cannot modify. Therefore this route does not work. I also considered shared memory, but in the end it still could not avoid serialization.
After digging deeper into CEF’s internal registration mechanism, I found that registration only cares about the object’s method names and property names; it does not care about the concrete implementation of those methods. So the Browser process can first store the real object in its own object pool, then use reflection to parse the object’s method names and property names and send only that metadata to the Render process. After receiving the method and property names, the Render process performs the actual registration in its own context.
Once JavaScript calls a native method and triggers
CefV8Handler.Execute, the Render process obtains the object
hash, method name, and arguments, and sends them back to the Browser
process. The Browser process then finds the real object in the local
registration pool and chooses the best matching method to invoke. In
other words, actual execution happens entirely in the Browser process,
while the communication between Browser and Render only carries method
names and simple argument data, avoiding object serialization.
Here are several English excerpts about CEF multi-process communication that inspired me:
I have been struggling with this as well. I do not think there is a way to do this synchronously…or easily :) Perhaps what can be done is this:
From browser do sendProcessMessage with all JS information to renderer process. You can pass all kinds of parameters to this call in a structured way so encapsulating the JS method name and params in order should not be difficult to do. In renderer process (RenderProcessHandler onProcessMessageReceived method) do TryEval on the V8Context and get the return value via out parameters and sendProcessMessage back to the browser process with the JS return value (Note that this supports ordinary return semantics from your JS method).You get the browser instance reference in the onProcessMessageReceived so it is as easy as this (mixed pseudo code) browser.GetMainFrame().CefV8Context.tryEval(js-code,out retValue, out exception); process retValue; browser.sendProcessMessage(…); Browser will get a callback in the WebClient in onProcessMessageReceived. There is nothing special here in terms of setting up JS. I have for example a loaded html page with a js function in it. It takes a param as input and returns a string. in js-code parameter to TryEval I simply provide this value:
It is slightly convoluted but seems like a neat workable approach – better than doing ExecuteJavaScript and posting results via XHR on custom handler in my view. I tried this and it does work quite well indeed….and is not bad as it is all non-blocking. The wiring in the browser process needs to be done to process the response properly. This can be extended and built into a set of classes to abstract this out for all kinds of calls.. Take a look at the Xilium demo app. Most of the necessary wiring is already there for onProcessMessage – do a global search. Look for DemoRendererProcessHandler.cs – renderer side this is where you will invoke tryEval DemoApp.cs – this is browser side, look for sendProcessMessage – this will initiate your JS invocation process. WebClient.cs – this is browser side. Here you receive messages from renderer with return value from your JS Cheers.
Fully Automatic Reflection-based Registration
Combining the core registration principle with CEF’s multi-process communication model, and after reading some source code, the final solution can be broken down into these steps:
- Define
MyV8Handler, but do not inherit fromCefV8Handleranymore. This removes the inheritance restriction, which means any object in the program can be registered. The flexibility is greatly improved. The reason this works is the underlying CEF registration principle described above.
1 | public class MyV8Handler |
- Define
CefGlueRuntimeto start the CEF kernel and register native objects in the Browser process. This registration is only a fake registration: all it does is store the object.
1 | public class CefGlueRuntime |
In real situations, one exportName may correspond to
multiple objects. Because serialization and deserialization change
object hash values, the original hash should be passed in at the
beginning, and that hash should be used to decide whether an object has
already been registered. This solves duplicate registration.
- Define a
WebView. In the Browser process,RegisterJsObjectuses reflection to extract the object’s method list, the parameter count and parameter types of each method, and the property list. It packages this metadata and sends it to the Render process. At the same time, it callsCefGlueRuntime.RegisterJsObjectto store the native object locally.
1 | public class WebView : WpfCefBrowser |
- Define
WpfRenderProcessHandler, inheriting fromCefRenderProcessHandler. InOnProcessMessageReceived, receive messages from the Browser process. Registration messages are handled byProcessRegisterMessage.
1 | protected override bool OnProcessMessageReceived(CefBrowser browser, CefProcessId sourceProcess, CefProcessMessage message) |
1 | private void ProcessRegisterMessage(CefProcessMessage message) |
Define CefRenderRuntime as the Render process object
pool. It receives the metadata passed from the Browser process:
1 | class CefRenderRuntime |
- In
WpfRenderProcessHandler.OnContextCreated, useBindingHandlerto register. Note that this is no longerOnWebKitInitialized, butOnContextCreated. This means that even after WebKit starts, registration can still happen whenever each context is created. The registration timing is no longer locked down.
1 | protected override void OnContextCreated(CefBrowser browser, CefFrame frame, CefV8Context context) |
BindingHandler is defined as follows. It inherits from
CefV8Handler. The Bind function is the
core. The final key registration statement is
window.SetValue, and what it registers is a
CefV8Value object. Therefore, before registration, the CLR
object must be converted into data that V8 can understand.
1 | class BindingHandler:CefV8Handler |
- Write a web page and call from JavaScript, such as
myHandle.myFunction(). This first triggersBindingHandler.Executein the Render process. That method parses the method name and arguments passed from JavaScript.TypeUtilconverts V8 data types into CLR data types. Then the parsed data is packaged and sent to the Browser process.
1 | class BindingHandler:CefV8Handler |
- In the Browser process,
OnProcessMessageReceivedreceives the message from the Render process that asks it to execute the method. It parses the method name and arguments, callsBindingHandler.ExecuteMethod, and finally sends the return value back to the Render process.
1 | public class WebView : WpfCefBrowser |
BindingHandler.ExecuteMethod is shown below. It first
calls FindBestMethod to match the most suitable method, and
then invokes it.
1 | public static void ExecuteMethod(object obj, string methodName, object[] suppliedArguments) |
The method matching logic in FindBestMethod is:
1 | public static void FindBestMethod(MemberInfo[] methods, object[] suppliedArguments, ref MethodInfo bestMethod,ref object[] bestMethodArguments) |
It iterates through all methods and matches arguments one by one. If there are no parameters and no supplied arguments, it returns directly. Otherwise, it calculates conversion costs, rejects methods whose parameters cannot be converted, and picks the method with the lowest cost. This allows overloaded methods to be selected more reasonably.
Summary
This article mentioned two problems.
The first is building the CEF kernel. It requires patience and persistence.
The second is supporting JavaScript calls into native functionality. The key is to follow these two paths:
- Registration path: CLR object -> Browser process stores it ->
reflection parses method names and parameters -> metadata is sent to
the Render process ->
BindingHandlerregisters it in the V8 engine. - Invocation path: H5 calls a method ->
Executein the Render process parses the method name and arguments -> a message is sent to the Browser process -> the Browser process callsBindingHandler.ExecuteMethod-> the return value is sent back to the Render process.