Skip to content

Frequently asked questions

Jump to bottom Edit New page
Alex Maitland edited this page May 4, 2024 · 134 revisions

Quick FAQ TOC

This FAQ tries to showcase some cool CefSharp features and some of the most common gotcha's. For an in-depth guide to many of the features please read General Usage Guide.

For more hints see the growing list of issues labelled as faq-able!

1. How do you call a JavaScript method from .NET?

See General Usage Guide - How do you call a JavaScript method

When can I start executing JavaScript?

See General Usage Guide - When can I start executing JavaScript

2. How do you call a JavaScript method that return a result?

See General Usage Guide - How do you call a Javascript method that return a result?

3. How do you expose a .NET class to JavaScript?

See General Usage Guide - How do I expose a .Net class

4. Why do I get an error about "Could not load file or assembly 'CefSharp.Core.dll' or one of its dependencies. The specified module could not be found." when trying to run my CefSharp-based application? It compiles successfully, but does not run? It runs on my developer machine, though throws an exception when I copy it to another computer?

This is a common error, typically one of the following

  1. VC++ 2015/2019 Redistributable Package is required in order to run CefSharp on non developer machines. See FAQ #6 below for more information. You can include the required dlls as part of your application.
  2. Not all dependencies are present in the executing folder. CefSharp includes unmanaged dll's and resources, these are copied to the executing folder via two .props file which are included in your project when you install the Nuget packages. See list of required files below, make sure the required files are present.
  3. You packaged your application for distribution via an installer and it doesn't run on the target machine. Installers don't include the unmanaged resources by default, you'll need to add them manually. For ClickOnce, see #1314 for some pointers and solutions other users have come up with.
  4. "Generate serialization assembly" is set to "On" or "Auto" in Properties->Build tab. Setting this to "Off" seems to resolve the issue.
  5. If run on Windows Server Core, some Direct X dependencies may not be installed. Install the Server Core App Compatibility Feature on Demand to resolve this issue.

A list of required files can be found here: Output files description (Redistribution)

NOTE: This also applies if you get a FileNotFoundException when initializing the WPF control in XAML.

NOTE 2: If compiling from source (not recommended, use the Nuget packages) and you notice that you can no longer build in debug mode, but release builds work just fine you may need to repair your version of Visual Studio. This happens in rare cases where you will get the same exact message as a missing unmanaged .dll file as shown above.

5. Why does the Visual Studio WPF designer not work when I add a ChromiumWebBrowser to my app?

Version 57.0.0 adds minimal designer support, see https://github.com/cefsharp/CefSharp/pull/1989 for details.

6. How do I include the Visual Studio C++ 2012/2013/2015 redistributables with my application?

CefSharp requires the Microsoft Visual C++ Runtime.

For versions 115.3.110 and above

CefSharp Nuget Package VC++ Version .Net Version
WinForms/WPF/OffScreen 2019 4.6.2 or higher
WinForms.NETCore/WPF.NETCore/OffScreen.NETCore 2019 .Net Core 3.1 or Net 5.0

For versions 91.1.111 and above

CefSharp Nuget Package VC++ Version .Net Version
WinForms/WPF/OffScreen 2019 4.5.2 or higher
WinForms.NETCore/WPF.NETCore/OffScreen.NETCore 2019 .Net Core 3.1 or Net 5.0

For versions 87.1.132 and above

CefSharp Nuget Package VC++ Version .Net Version
WinForms/WPF/OffScreen 2015 or higher 4.5.2 or higher
WinForms.NETCore/WPF.NETCore/OffScreen.NETCore 2019 .Net Core 3.1 or Net 5.0

For versions older than 87.1.132

CefSharp Version VC++ Version .Net Version
65.0.0 and above 2015* 4.5.2
51.0.0 to 63.0.0 2013 4.5.2
45.0.0 to 49.0.0 2013 4.0.0
43.0.0 and below 2012 4.0.0

* Visual C++ 2015 is the minimum version, VC++ 2017/2019 are backwards compatible.

For Microsoft's official guide see Redistributing Visual C++ Files on MSDN. To download visit Visual Studio C++ redistributables.

A brief summary of your options for installing/including VC++ with your application are:

  • Install the Microsoft Visual C++ Redistributable Package on every machine on which you wish to run your CefSharp based application. Once installed updates can then be managed via Windows Update.
  • You can either set the Visual Studio C++ redistributables as pre-requisites of the installer (i.e. ClickOnce or WiX Toolset)
  • Copying over to your project the contents of this folder (Only present if you have the matching version of Visual Studio installed on your computer and if you have chosen the option Desktop development with C++ during the installation process):
# Visual Studio 2022
# Example for VC++ 2022 (x64) using VS 2022 Community would look something like:
C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Redist\MSVC\14.38.33135\x64\Microsoft.VC143.CRT
# Example for VC++ 2022 (x86) using VS 2022 Community would look something like:
C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Redist\MSVC\14.38.33135\x86\Microsoft.VC143.CRT
# Example for VC++ 2022 (arm64) using VS 2022 Community would look something like:
C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Redist\MSVC\14.38.33135\arm64\Microsoft.VC143.CRT

# Visual Studio 2019
# Example for VC++ 2019 (x86) using VS 2019 Community would look something like:
C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Redist\MSVC\14.29.30133\x64\Microsoft.VC142.CRT
# Example for VC++ 2019 (x64) using VS 2019 Community would look something like:
C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Redist\MSVC\14.29.30133\x64\Microsoft.VC142.CRT

# Visual Studio 2015
# For VC++ 2015 (x86)
C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\redist\x86\Microsoft.VC140.CRT
# For VC++ 2015 (x64)
C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\redist\x64\Microsoft.VC140.CRT

With the 3rd approach you won't need to install the prerequisite Visual C++ 2015/2019 Runtime Files to your client. If you build your own version of CefSharp from source what you deploy of course has to match your build environment. For the official Nuget releases see the Releases Branches table for details.

For VC++ 2015/2019 you may also need to package the Universal CRT, see the Distributing Software that uses the Universal CRT section of https://blogs.msdn.microsoft.com/vcblog/2015/03/03/introducing-the-universal-crt/ the last dot point titled App-local deployment of the Universal CRT is supported has details. Windows 10 includes the Universal CRT as an operating system component and there is no need to copy those files. UPDATE: See also https://docs.microsoft.com/en-us/cpp/windows/universal-crt-deployment?view=vs-2019

Note When building from source make sure you compile in Release mode when deploying to machines that don't have Visual Studio installed. Visual C++ uses a different set of run-time libraries for Debug and Release builds. The Debug run-time libraries are only installed with Visual Studio. If you use the official Nuget packages they're already built in Release mode and you can subsequently build your app in debug mode as only the Visual C++ projects need to be compiled in Release mode.

7. How do I override Javascript window.alert actions and similar?

Implement IJsDialogHandler and assign your instance to the browser.JsDialogHandler property of the ChromiumWebBrowser instance to override the default behaviour.

8. Where are the CefSharp3 binaries?

CefSharp3 is released as Nuget packages. Please see https://github.com/cefsharp/CefSharp/blob/master/README.md#nuget-packages for the latest stable and pre-release versions.

For a very simple example projects using the NuGet packages, see the CefSharp.MinimalExample repository. Clone it/download the source if you want a really small and simple example of how CefSharp3 can be used.

_Please Note: Platform Target
CefSharp supports AnyCPU for version 51.0.0 and above, see https://github.com/cefsharp/CefSharp/issues/1714 for details.

The simplest option to get up and running quickly is to either select x86 or x64. See Steps to configure your solution here.

9. Windows XP/2003 Support

Chromium has removed support for Windows XP/2003. It is no longer possible to run CefSharp on a computer running Windows XP/2003. Please don't create new issues related to Windows XP. The following https://github.com/cefsharp/CefSharp/wiki/Windows-XP-No-Longer-Supported Wiki page may be useful and can be edited by anyone with a GitHub account, so feel free to contribute any information you think may prove useful.

10. What files do I need to include when I redistribute an application that uses CefSharp?

See: Output files description (Redistribution)

11. Build process can't copy CEF files

Sometimes the build process can't copy CEF files and will retry many times before it finally fails. This happens when CefSharp.BrowserSubprocess.exe is still running even though the application was closed.
The solution is to manually kill the CefSharp.BrowserSubprocess.exe using i.e. Task Manager.

12. Why does IndexedDB return a QuotaExceededError?

When working with IndexedDB you must set the CefSettings CachePath to a directory where the current user has write access. In most cases you can use code like this to create a cache directory and pass the setting to Cef during Initialize():

// On Win7 this will create a directory in AppData.
var cache = System.IO.Path.Combine(Environment.GetFolderPath (Environment.SpecialFolder.ApplicationData), System.IO.Path.Combine("MyApplication","cache"));
if (!System.IO.Directory.Exists (cache))
    System.IO.Directory.CreateDirectory (cache);

// Set the CachePath during initialization.
var settings = new CefSettings(){CachePath = cache};
Cef.Initialize (settings);

13. How do you handle a Javascript event in C#?

For basic communication you can use CefSharp.PostMessage(message); in Javascript to send a message to .Net which triggers the browser.JavascriptMessageReceived event.

// After your ChromiumWebBrowser instance has been instantiated (for WPF directly after `InitializeComponent();` in the control constructor).
// Subscribe to the following events
browser.JavascriptMessageReceived += OnBrowserJavascriptMessageReceived;
browser.FrameLoadEnd += OnFrameLoadEnd;

public void OnFrameLoadEnd (object sender, FrameLoadEndEventArgs e)
{
  if(e.Frame.IsMain)
  {
    //In the main frame we inject some javascript that's run on mouseUp
	//You can hook any javascript event you like.
	browser.ExecuteScriptAsync(@"
	  document.body.onmouseup = function()
	  {
		//CefSharp.PostMessage can be used to communicate between the browser
		//and .Net, in this case we pass a simple string,
		//complex objects are supported, passing a reference to Javascript methods
		//is also supported.
		//See https://github.com/cefsharp/CefSharp/issues/2775#issuecomment-498454221 for details
		CefSharp.PostMessage(window.getSelection().toString());
	  }
	");
  }
}

private void OnBrowserJavascriptMessageReceived(object sender, JavascriptMessageReceivedEventArgs e)
{
	var windowSelection = (string)e.Message;
	//DO SOMETHING WITH THIS MESSAGE
	//This event is called on the threads pool, to access your UI thread
        //You can cast sender to ChromiumWebBrowser
	//use Control.BeginInvoke/Dispatcher.BeginInvoke
}

See https://stackoverflow.com/a/66431326/4583726 for another detailed example.

14. How can I implement WinForms drag & drop?

One possible solution is outlined in https://github.com/cefsharp/CefSharp/issues/1593#issuecomment-304451518

15. WPF blurry rendering

There are two common reasons the browser will render incorrectly

High DPI

If your app is running on a HighDPI enabled display/monitor. You will need to make your application DPI Aware, see https://github.com/cefsharp/CefSharp/wiki/General-Usage#high-dpi-displayssupport

Rounding/BitmapScaling

WPF represents width/height using the double data type, this causes problems as CEF uses int for width/height values. It's necessary to cast double to int, UseLayoutRounding is enabled by default on the ChromiumWebBrowser control to have the values rounded to whole pixel values by WPF. UseLayoutRounding is inherited by child elements, so it's possible for a parent element to override the UseLayoutRounding setting.

  • Try setting UseLayoutRounding=true on the parent of the ChromiumWebBrowser or even on an ancestor up the visual tree as this has helped others in the past.

  • UseLayoutRounding disables anti-aliasing for children, so set it to false for the children of the container where you want to keep the anti-aliasing, see #166

  • Every frame is rendered as a bitmap, the default BitmapScalingMode used is HighQuality

  • Changing RenderOptions.BitmapScalingModetoNearestNeighbor` may also work

Visual Studios Live XAML Debugger is very useful in determining the root cause of the problem.

.Net Core 3.1/.Net 5/6/7+ BadImageFormatException

When using .Net Core 3.1/Net 5/6/7+ a BadImageFormatException can be very misleading.

Our diagnostics for mixed-mode assembly loading need a bit of work since they throw a BadImageFormatException for basically every failure.

As per https://github.com/dotnet/runtime/issues/31743#issuecomment-582168696

Basically any failure from the .Net Runtime when loading a mixed mode assembly (VC++ dll like CefSharp.Core.Runtime.dll) will cause a BadImageFormatException. Hopefully one day Microsoft will improve the error messaging.

Most common cause are:

  • Missing Microsoft Visual C++ Runtime
  • Forgetting to distribute ijwhost.dll (must be next to CefSharp.Core.Runtime.dll).
  • The bitness of the dlls doesn't match, for instance you are trying to load an x64 dll from an x86 executable.

Anyone with a GitHub account can edit this wiki, contributions are encouraged and welcomed.

Add a custom sidebar
Clone this wiki locally