cWebView2Host Property & Method Usage Timing Reference

Different APIs have different availability timings within the WebView2 lifecycle. This document categorizes all properties and methods by earliest available timing, helping developers avoid calling them at incorrect stages where they may fail or have no effect.

Lifecycle Stage Overview

The WebView2 complete lifecycle includes an Initialization Phase and a Runtime Phase, with all events as follows:

Initialization Phase (one-time, sequential)

User calls Initialize()
  ↓
① Create event ─── Configure EnvironmentOptions / Security (only available in this event)
  ↓
② Internally creates Environment (reads EnvironmentOptions configuration)
  ↓
③ Internally creates Controller + CoreWebView (reads Settings configuration)
  ↓
④ Ready event ─── Control fully ready, all APIs become available
  ↓
⑤ First Navigate (if InitialURL is specified)

Runtime Phase (triggered per navigation cycle)

Navigate / NavigateCustom / NavigateToString / GoBack / GoForward / Reload
  ↓
⑥ NavigationStarting ─── Can Cancel to block navigation
  ↓
⑦ SourceChanged ─── URL change (IsNewDocument indicates new page)
  ↓  ┌─ ContentLoading (internal event, not exposed)
     │
⑧ DOMContentLoaded ─── DOM ready, can BindUI / BindData / execute JS
  ↓  │
⑨ DocumentTitleChanged ─── Title change
     │
⑩ NavigationComplete ─── Page fully loaded (including images and other resources)
     └────────────────────────────────────────┘

Each navigation re-triggers ⑥→⑩

Runtime Phase (interaction events that may fire at any time)

┌─ Permissions/Dialogs ───────────────────────────────┐
│  PermissionRequested    Page requests permission (geo/camera etc.)│
│  ScriptDialogOpening    JS dialogs (alert/confirm) │
│  NewWindowRequested     Page requests new window          │
│  AcceleratorKeyPressed  Shortcut key pressed               │
└──────────────────────────────────────────────────────┘

┌─ Resources/Downloads ───────────────────────────────┐
│  WebResourceRequested  Resource request intercepted (must register first) │
│  DownloadStarting      Download about to start (can Cancel)  │
│  ProcessFailed         Browser process crashed             │
└──────────────────────────────────────────────────────┘

┌─ Script Callbacks ──────────────────────────────────┐
│  JsAsyncResult         Async JS execution complete          │
│  JsMessage             JS postMessage to host     │
│  DevToolsProtocolResponse  CDP async response          │
└──────────────────────────────────────────────────────┘

┌─ Host Interaction ──────────────────────────────────┐
│  HostMouseDown/Up/DblClick/Move/Wheel/ContextMenu│
│  HostKeyDown/Up/Press   Keyboard events                 │
│  HostFocus / HostBlur   Focus in/out                 │
│  HostResize             Host window size change           │
└──────────────────────────────────────────────────────┘

┌─ Content Area Mouse (requires EnableUserMouseEvents=True)────┐
│  UserMouseDown/Up/Move/Wheel/ContextMenu/DblClick│
└──────────────────────────────────────────────────────┘

┌─ Async Operation Callbacks ──────────────────────────┐
│  SuspendCompleted / SuspendFailed                │
│  PrintToPdfCompleted / PrintToPdfFailed          │
│  OnGetCookiesFull                                │
└──────────────────────────────────────────────────────┘

┌─ Errors ─────────────────────────────────────────────┐
│  Error                  Creation/runtime error           │
└──────────────────────────────────────────────────────┘

Stage & API Availability Reference

Stage	Timing	What you can do
Before Initialize call	Object just created	Only set EnvironmentOptions sub-properties
Create event	Before Environment creation	Set EnvironmentOptions, Security configuration
Ready event	Control fully ready	Navigate, register bindings, inject scripts, set runtime properties
DOMContentLoaded	DOM ready	BindUI, BindData, execute JS (ensure elements exist)
NavigationComplete	Page fully loaded	All runtime APIs unrestricted
Any time at runtime	After Ready	All APIs unrestricted

---

Property Usage Timing Overview

🔴 Only in Create Event (pre-creation configuration)

These properties affect WebView2 Environment creation parameters and must be set in the wv_Create event. Changes after this have no effect.

Property	Sub-property	Description
EnvironmentOptions	UserDataFolder	User data directory, read when Environment is created, changes afterwards have no effect
	BrowserExecutableFolder	Browser executable folder
	AdditionalBrowserArguments	Additional command-line arguments (e.g., --ignore-certificate-errors)
	Language	Browser default language
	TargetCompatibleBrowserVersion	Target compatible version
	AllowSingleSignOnUsingOSPrimaryAccount	SSO configuration
	ExclusiveUserDataFolderAccess	Exclusive data folder
	EnableTrackingPrevention	Tracking prevention
Security	CertificateErrorAction	Certificate error handling policy, must be set before Create

Example:

Private Sub wv_Create()
    ' ★ These can ONLY be set in the Create event!
    wv.EnvironmentOptions.UserDataFolder = App.Path & "\UserDir\account-001"
    wv.EnvironmentOptions.AdditionalBrowserArguments = "--ignore-certificate-errors"
    wv.Security.CertificateErrorAction = CEA_AlwaysAllow
End Sub

🟡 Available from Ready Event (runtime settings)

These properties require the CoreWebView2 Controller/Settings object to be created and can be set from the wv_Ready event onwards. Setting them in the Create event may have no effect (the underlying Settings object has not been created yet).

Property	Description	Note
IsPasswordAutoSaveEnabled	Password auto-save	Default False, only effective after Ready
IsGeneralAutoFillEnabled	Form auto-fill	Default False, only effective after Ready
IsScriptEnabled	JS execution toggle	Default True
AreDevToolsEnabled	DevTools toggle	Default True, recommended off for production
IsStatusBarEnabled	Status bar display	Default False
IsZoomControlEnabled	User zoom control	Default True
AreDefaultContextMenusEnabled	Right-click menus	Default True
UserAgent	Custom UA	Takes effect for subsequent requests after setting
IsPinchZoomEnabled	Pinch zoom	Default True
IsSwipeNavigationEnabled	Swipe navigation	Default True
AreBrowserAcceleratorKeysEnabled	Browser shortcut keys	Default True
ZoomFactor	Zoom factor	Default 1.0, requires page loaded
EnableUserMouseEvents	Content area mouse events	Default False, set after Ready and auto-injects proxy
EnableUserMouseMove	Content area mousemove	Requires EnableUserMouseEvents to be True
EnableMouseMoveEvents	Host mousemove	Default False

Example:

Private Sub wv_Ready()
    ' ★ Runtime property settings
    wv.IsPasswordAutoSaveEnabled = True
    wv.IsGeneralAutoFillEnabled = True
    wv.AreDevToolsEnabled = False      ' Disable DevTools in production
    wv.UserAgent = "Mozilla/5.0 (MyApp)"
    
    ' Enable mouse event proxy
    wv.EnableUserMouseEvents = True
End Sub

🟢 Available any time (read-only state)

These properties are read-only and can be read at any time, but only have valid values after Ready.

Property	Description	Value before Ready
IsReady	Whether ready	False → True
hWnd	Child window handle	0 → Valid handle
BrowserProcessId	Process ID	0 → Valid ID
CanGoBack	Can go back	False
CanGoForward	Can go forward	False
IsSuspended	Whether suspended	False
IsMuted	Whether muted	False
IsDocumentPlayingAudio	Playing audio	False
IsDefaultDownloadDialogOpen	Download dialog	False
DocumentURL	Current URL	"" → Valid URL
DocumentTitle	Current title	"" → Valid title
SupportsWebView2~9	Feature detection	Accurate values only after Ready
Cookies	Cookie object	Available after Ready
Script	Script object	Available after Ready
HostAdapterName	Adapter name	Has value at Initialize time

---

Method Usage Timing Overview

🔴 Only in Create Event

Method	Description
—	No methods are currently restricted to only the Create event

Note: Although some methods can be called in the Create event, the underlying CoreWebView object has not been created yet, and most methods will silently fail (protected by If m_Core Is Nothing Then Exit Sub). The sole purpose of the Create event is to configure EnvironmentOptions and Security.

🟡 Available from Ready Event

These methods require the CoreWebView object to be created and can only be called from the wv_Ready event onwards:

Method	Description	Note
Navigate	Navigate to URL	Call after Ready, calling in Create has no effect
NavigateCustom	Custom request navigation	Same as above
NavigateToString	Load HTML string	Same as above
GoBack / GoForward / Reload	Navigation control	Requires navigation history
ExecuteScript	Async execute JS	Requires page loaded
JsRun	Sync call JS	Requires page loaded
JsRunAsync	Async call JS	Requires page loaded
JsProp	Read JS property	Requires page loaded
PostWebMessage	Send string message	Requires page loaded
PostWebMessageJSON	Send JSON message	Requires page loaded
AddObject	Inject COM object	Inject after Ready, page JS can access
RemoveObject	Remove COM object
AddScriptToExecuteOnDocumentCreated	Inject script	Inject after Ready, subsequent pages execute
AddWebResourceRequestedFilter	Add resource filter	Register after Ready to take effect
RemoveWebResourceRequestedFilter	Remove filter
SetVirtualHostNameToFolderMapping	Virtual host mapping	Set after Ready, then Navigate
ClearVirtualHostNameToFolderMapping	Clear mapping
PrintToPdf	Print to PDF	Requires page loaded
Suspend / Resume	Suspend/Resume
OpenDevToolsWindow	Open DevTools
CallDevToolsProtocolMethod	Async CDP
CallDevToolsProtocolMethodSync	Sync CDP
OpenDefaultDownloadDialog	Open download dialog
CloseDefaultDownloadDialog	Close download dialog
OpenTaskManagerWindow	Task manager
Resize	Resize
SetFocus	Set focus
BindUI	DOM event binding	Requires page DOM to exist
UnbindUI	Remove event binding
BindData	Data binding	Requires page DOM to exist
UnbindData	Remove data binding
SetData	Push data	Requires BindData already done
SetDataBatch	Batch push	Requires BindData already done

🟢 Available any time (but recommended after Ready)

Method	Description
Initialize	Initialize control, the starting point
Cleanup	Clean up resources, can be called anytime

🔵 Recommended after DOMContentLoaded

The following methods depend on the page DOM being rendered. It is recommended to call them after the wv_DOMContentLoaded or wv_NavigationComplete event:

Method	Description	Reason
BindUI	DOM event binding	Requires elements already in DOM
BindData	Data binding	Requires elements already in DOM
SetData / SetDataBatch	Push data	Requires BindData completed
JsRun / JsProp	Sync JS calls	Requires JS environment ready
Script.Eval	Sync execute JS	Requires page JS executable

Best Practice:

Private Sub wv_DOMContentLoaded()
    ' ★ Bind UI and data after DOM is ready
    wv.BindData "name", "#name-input", "value"
    wv.BindData "name", "#name-preview", "textContent"
    wv.BindUI Me, "OnNameInput", "#name-input", EventName:="input"
    wv.SetData "name", "Initial value"
End Sub

---

⚠️ Common Error Scenarios

Wrong approach	Problem	Correct approach
Setting EnvironmentOptions.UserDataFolder in Form_Load	Initialize internally overwrites defaults, but user settings before Create are preserved	Set in wv_Create event
Calling Navigate in Create event	CoreWebView not yet created, silently fails	Navigate in wv_Ready event
Calling AddObject before Ready	Underlying CoreWebView is Nothing	AddObject in wv_Ready event
Calling BindData in NavigationStarting	DOM may not yet be loaded	BindData in wv_DOMContentLoaded
Setting IsPasswordAutoSaveEnabled in Create	Settings4 object not yet created, may have no effect	Set after wv_Ready

---

🗺️ Quick Decision Flowchart

Need to configure EnvironmentOptions or Security?
  → ★ wv_Create event

Need to set runtime properties (IsPasswordAutoSaveEnabled etc.)?
  → ★ From wv_Ready event onwards

Need to navigate, inject scripts, register filters?
  → ★ From wv_Ready event onwards

Need to bind UI/data, execute JS?
  → ★ From wv_DOMContentLoaded event onwards (ensure DOM is ready)

Need to read state (URL, title, etc.)?
  → ★ Any time (but valid values only after Ready)

---

Last Updated: 2026-06-26