WebBrowser Hosting Rules: AllowNavigation, Drag-Drop and Script Errors
A maintainer inherits the WinForms HTML Editor codebase with a folder of legacy notes that read like superstition: "never set this property", "delete that line from the designer or double-click word selection breaks". They are not superstition. Each one is a real, reproducible consequence of how the WinForms WebBrowser control hosts the legacy MSHTML (Trident) engine, and every one of them is still enforced in the current source. This page documents the four rules, the exact place each is honoured in code, and -- critically -- which of them must not be carried over to the WPF editor.
This is a hosting-and-internals reference, not the field-support article. If your symptom is "embedded YouTube videos do not play on some end-user machines", see the separate Preview YouTube Video page in this same category -- that is a codec/GPU story, not the property rule described here.
Quick reference: what must never change
| Setting | Required value (WinForms) | What breaks if you change it | WPF equivalent |
|---|---|---|---|
AllowNavigation on the preview browser | Left at default true (no line in the designer) | Embedded YouTube / iframe media stops rendering in Preview mode | No such property; WPF cancels navigation on the editor only, via a Navigating handler |
AllowWebBrowserDrop in the Designer file | Must not appear in the designer at all; set to false in code | Design-time image resize handles and double-click word selection stop working | N/A -- WPF has no WinForms designer file |
ScriptErrorsSuppressed on the WYSIWYG editor browser | false (never set; only the preview browser sets it true) | Design-time image resize and double-click word selection stop working | Intentionally true on the WPF editor -- the opposite rule |
| WYSIWYG editor parent container | Added directly to the UserControl with DockStyle.Fill -- never inside a Panel | The MSHTML edit surface breaks (no resize handles / word select) | WPF editor sits inside DockPanel > Grid > Border and works fine |
EmbedInteropTypes for MSHTML.dll | Obsolete -- no longer applicable | Nothing; the COM reference is gone | Obsolete -- identical NuGet package on both |
Rule 1 - Never set AllowNavigation = false on the Preview browser
The Preview browser (webBrowserForPreview) deliberately has no AllowNavigation line in WinFormHtmlEditor.designer.cs, so it keeps the framework default of true. Only the WYSIWYG editor browser (webBrowserEditor) sets AllowNavigation = false (designer line 129).
This split is intentional. Embedded YouTube and other iframe-based media perform an internal navigation when they initialise. If AllowNavigation is forced to false on the preview browser, that internal navigation is blocked and the video never appears in Preview mode. The verified rule: the WYSIWYG editor may lock navigation; the preview browser never may.
Status: still true and still honoured in the current WinForms source.
Rule 2 - AllowWebBrowserDrop must never appear in the Designer file
If you open WinFormHtmlEditor.designer.cs and see a line like this.webBrowserEditor.AllowWebBrowserDrop = ...;, delete it. The property is set deliberately in code instead -- in WinFormHtmlEditor.cs at OnLoad (webBrowserEditor.AllowWebBrowserDrop = false;, line 576) and for the preview browser in PrivateHelpers.cs (lines 404-405).
When the WinForms designer serialises this property into the designer file, the MSHTML editing surface initialises in a state where the design-time image-resize handles and double-click word selection silently stop working. Setting it from code after the control loads avoids that. The current source already follows this rule: the line is absent from the designer.
Status: still true and still honoured (WinForms only -- WPF has no designer file).
Rule 3 - The three conditions for design-time image resize and double-click word selection
For the MSHTML edit surface to expose image-resize handles and respond to double-click word selection, three conditions must all hold for the WYSIWYG editor browser:
- Never placed on a Panel.
webBrowserEditoris added directly to the UserControl withDockStyle.Fill(designer ~lines 935-944). Re-parenting the WinFormsWebBrowserinto a Panel disturbs the ActiveX window and the edit surface breaks. ScriptErrorsSuppressedmust befalse. The WYSIWYG editor never sets it (so it staysfalse); only the preview browser sets ittrue(PrivateHelpers.cslines 406-407).AllowWebBrowserDropmust befalseand not in the designer file (see Rule 2).
All three are still honoured in the current WinForms source. These are WinForms ActiveX-hosting quirks; see the final section for why they are inverted in WPF.
Rule 4 - The old MSHTML EmbedInteropType warning is now obsolete
The legacy note "never set EmbedInteropType = true for MSHTML.dll when compiling for .NET 4.0" no longer applies. The product no longer uses a COM reference to MSHTML.dll. Both the WinForms and WPF projects reference the NuGet package Unofficial.Microsoft.mshtml.NetStandard version 7.0.3300.2, which has no EmbedInteropTypes concept, and neither project targets .NET 4.0 (the target frameworks run from net45 through net10.0-windows). Keep this note only as historical context.
Why these WinForms rules do NOT transfer to the WPF editor
The WinForms editor hosts a custom SpiceWebBrowser (a subclass of System.Windows.Forms.WebBrowser). The WPF editor hosts the native System.Windows.Controls.WebBrowser. Both wrap the same MSHTML engine behind a shared IWebBrowser abstraction, but they host the ActiveX control very differently, so Rules 2 and 3 are WinForms-specific:
- The WPF WYSIWYG browser is nested inside DockPanel > Grid > Border and still works.
- The WPF editor browser explicitly sets
ScriptErrorsSuppressed = true(WpfHtmlEditor.xaml.csline 780) -- the exact opposite of Rule 3. - WPF has no designer file, so Rule 2 has no meaning there.
Do not "fix" the WPF editor to match these WinForms rules. The WPF-side reference is the mirror of this page in the WPF product's Known Issues category.