Click or drag to resize

Deployment and Upgrading

The viewer displays documents with Microsoft Edge WebView2, the browser engine of Windows. This topic describes what your application needs on the computers where it runs.

The WebView2 Runtime

The Evergreen WebView2 Runtime is part of Windows 10 and Windows 11 and is updated by Windows. On Windows Server and on older systems it may be missing. The viewer offers three ways to deploy it.

When the runtime is missing and none of these is used, the viewer shows a message with the download address and raises the LoadError event.

Install the runtime when it is missing

The NuGet package copies Microsoft's WebView2 Runtime installer (bootstrapper), MicrosoftEdgeWebview2Setup.exe, next to your application (the Bin folder of the download has it too). Set InstallWebView2RuntimeIfMissing to true before the control is shown: when the runtime is missing, the viewer runs the installer for the current user, silently (it downloads the runtime, so the computer needs internet access), waits for it and starts.

pdfViewer.InstallWebView2RuntimeIfMissing = true;

To install the runtime at another time - in your setup program, or with your own progress message - call InstallWebView2Runtime from a background thread; it returns true when the runtime is installed. The installer is looked for in the application folder; set WebView2BootstrapperPath when you put it elsewhere. To leave the installer out of a build with the NuGet package, set the MSBuild property ExpertPdfViewerCopyWebView2Bootstrapper to false.

Install the runtime with your setup

Microsoft provides installers you can redistribute with your setup program (the bootstrapper above and a standalone installer that works offline): https://developer.microsoft.com/microsoft-edge/webview2/.

Ship a fixed version of the runtime

A fixed version runtime is a folder of files that you distribute with your application; it is not updated by Windows. Download it from the Fixed Version section of the page above (one .cab file per architecture) and expand it into a WebView2Runtime folder next to your application:

expand -F:* Microsoft.WebView2.FixedVersionRuntime.<version>.x64.cab WebView2Runtime\x64
expand -F:* Microsoft.WebView2.FixedVersionRuntime.<version>.x86.cab WebView2Runtime\x86

The viewer finds it without code: WebView2Runtime\x64 or WebView2Runtime\x86 (the bitness of the process), the WebView2Runtime folder itself, or the folder the .cab file creates inside them (Microsoft.WebView2.FixedVersionRuntime.<version>.x64). To keep the runtime elsewhere, set BrowserExecutableFolder to its folder before the control is shown. Update the folder with newer versions from Microsoft for security fixes.

Files to deploy
  • PdfViewerWinNet.dll

  • The files of the Microsoft.Web.WebView2 package: Microsoft.Web.WebView2.Core.dll, Microsoft.Web.WebView2.WinForms.dll, Microsoft.Web.WebView2.Wpf.dll and the WebView2Loader.dll for your platform. A build with the NuGet package copies them to your output folder.

The viewer works in 32-bit, 64-bit and ARM64 processes.

The browser data folder

WebView2 keeps its cache and settings in a data folder. The viewer uses %LOCALAPPDATA%\ExpertPdf\PdfViewer\WebView2. To use another folder - for example when your application runs from a read-only location with a redirected profile - set UserDataFolder before the control is shown.

WebView2 cannot use one data folder for two runtimes: a viewer on a fixed version runtime uses %LOCALAPPDATA%\ExpertPdf\PdfViewer\WebView2-<hash> (a folder for each runtime folder), and when the default folder is in use by WebView2 with other settings (another application), the viewer uses a folder of your application's own. A folder you set in UserDataFolder is always used as it is: give viewers with different runtimes different folders.

The Windows Forms and the WPF control work side by side in one application, in any order: a Windows Forms application that shows the WPF viewer (in a WPF window or an ElementHost), or a WPF application that shows the Windows Forms viewer (in a Windows Forms window or a WindowsFormsHost). When a DPI-unaware Windows Forms application first shows WPF content, WPF makes the application DPI aware, and WebView2 cannot serve windows of two DPI awareness modes from one data folder: the viewers created after that use %LOCALAPPDATA%\ExpertPdf\PdfViewer\WebView2-dpi-<awareness>. With a folder set in UserDataFolder, give the viewers created after the first WPF content another folder.

Advanced customization

CoreWebView2 gives access to the WebView2 instance of the viewer once it has started, for browser settings that the control does not expose. Drive the viewer through the members of the control.

Upgrading from version 9

Version 10 replaces the viewer based on Adobe Reader (ActiveX) with a built-in viewer. Adobe Reader is no longer needed, and the viewer works the same on every computer. The programming interface is kept: existing code builds and runs after you reference the new version. Note:

  • The minimum framework is .NET Framework 4.6.2; .NET 8 and later are supported too.

  • The Microsoft.Web.WebView2 package is needed in the project, and the WebView2 Runtime on the computer.

  • Loading is asynchronous: use the DocumentLoaded event before reading PageCount or CurrentPage.

  • New members: LoadBytes, CloseDocument, IsDocumentLoaded, PrintAsync, the DocumentLoaded, CurrentPageChanged and LoadError events, the Attachments display mode, and the WPF control.

  • As in version 9, the page numbers of SetCurrentPage and CurrentPage start at 1, and those of PrintPages and PrintPagesFit start at 0. CurrentPage can now also be read: it is the page shown.

See Also

Other Resources

Getting Started