Class CoreWebView2Frame

Namespace

Microsoft.Web.WebView2.Core

Assembly

Microsoft.Web.WebView2.Core.dll

CoreWebView2Frame provides direct access to the iframes information and handling.

public class CoreWebView2Frame

Inheritance

object

CoreWebView2Frame

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Properties

FrameId

The unique identifier of the current frame. It's the same kind of ID as with the FrameId and FrameId.

public uint FrameId { get; }

Property Value

uint

Name

The value of iframe's window.name property. The default value equals to iframe html tag declaring it.

public string Name { get; }

Property Value

string

Methods

AddHostObjectToScript(string, object, IEnumerable<string>)

Adds the provided host object to script running in the WebViewFrame with the specified name for the list of the specified origins. The host object will be accessible for this iframe only if the iframe's origin during access matches one of the origins which are passed. The provided origins will be normalized before comparing to the origin of the document. So the scheme name is made lower case, the host will be punycode decoded as appropriate, default port values will be removed, and so on. This means the origin's host may be punycode encoded or not and will match regardless. If list contains malformed origin the call will fail. The method can be called multiple times in a row without calling RemoveHostObjectFromScript for the same object name. It will replace the previous object with the new object and new list of origins. List of origins will be treated as following:

1. empty list - call will succeed and object will be added for the iframe but it will not be exposed to any origin;
2. list with origins - during access to host object from iframe the origin will be checked that it belongs to this list;
3. list with "*" element - host object will be available for iframe for all origins. We suggest not to use this feature without understanding security implications of giving access to host object from from iframes with unknown origins.
4. list with "file://" element - host object will be available for iframes loaded via file protocol.

public void AddHostObjectToScript(string name, object rawObject, IEnumerable<string> origins)

Parameters

name string

The name of the host object.

rawObject object

The host object to be added to script.

origins IEnumerable<string>

The list of the iframe origins for which host object will be accessible.

See Also

AddHostObjectToScript(string, object)

ExecuteScriptAsync(string)

Runs JavaScript code from the javaScript parameter in the current frame.

public Task<string> ExecuteScriptAsync(string javaScript)

Parameters

javaScript string

The JavaScript code to be run in the current frame.

Returns

Task<string>

A JSON encoded string that represents the result of running the provided JavaScript.

Examples

Remarks

A function that has no explicit return value returns undefined. If the script that was run throws an unhandled exception, then the result is also null. This method is applied asynchronously. If the method is run before ContentLoading, the script will not be executed and the JSON null will be returned. This operation works even if IsScriptEnabled is set to false.

IsDestroyed()

Check whether a frame is destroyed. Returns true during the Destroyed event.

public int IsDestroyed()

Returns

int

PostSharedBufferToScript(CoreWebView2SharedBuffer, CoreWebView2SharedBufferAccess, string)

Share a shared buffer object with script of the iframe in the WebView.

public void PostSharedBufferToScript(CoreWebView2SharedBuffer sharedBuffer, CoreWebView2SharedBufferAccess access, string additionalDataAsJson)

Parameters

sharedBuffer CoreWebView2SharedBuffer

The CoreWebView2SharedBuffer object to be shared with script.

access CoreWebView2SharedBufferAccess

The desired CoreWebView2SharedBufferAccess given to script.

additionalDataAsJson string

Additional data to be send to script. If it is not null or empty string, and it is not a valid JSON string, ArgumentException will be thrown.

Examples

Remarks

The script will receive a sharedbufferreceived event from chrome.webview. The event arg for that event will have the following methods and properties.

Property	Description
getBuffer()	A method that returns an ArrayBuffer object with the backing content from the shared buffer.
additionalData	An object as the result of parsing additionalDataAsJson as JSON string. This property will be undefined if additionalDataAsJson is nullptr or empty string.
source	With a value set as chrome.webview object.

If access is ReadOnly, the script will only have read access to the buffer. If the script tries to modify the content in a read only buffer, it will cause an access violation in WebView renderer process and crash the renderer process.

If the shared buffer is already closed, the API throws COMException with error code of RO_E_CLOSED. The script code should call chrome.webview.releaseBuffer with the shared buffer as the parameter to release underlying resources as soon as it does not need access to the shared buffer any more.

The application can post the same shared buffer object to multiple web pages or iframes, or post to the same web page or iframe multiple times. Each PostSharedBufferToScript will create a separate ArrayBuffer object with its own view of the memory and is separately released. The underlying shared memory will be released when all the views are released.

Sharing a buffer to script has security risk. You should only share buffer with trusted site. If a buffer is shared to a untrusted site, possible sensitive information could be leaked. If a buffer is shared as modifiable by the script and the script modifies it in an unexpected way, it could result in corrupted data that might even crash the application.

The example code shows how to send data to script for one time read only consumption.

PostWebMessageAsJson(string)

Posts the specified webMessageAsJson to the current frame.

public void PostWebMessageAsJson(string webMessageAsJson)

Parameters

webMessageAsJson string

The web message to be posted to the iframe.

Examples

Runs the message event of the window.chrome.webview of the iframe. JavaScript in that document may subscribe and unsubscribe to the event using the following code:

window.chrome.webview.addEventListener('message', handler)
window.chrome.webview.removeEventListener('message', handler)

Remarks

The event args is an instance of MessageEvent. The IsWebMessageEnabled setting must be true or the message will not be sent. The event arg's data property of the event arg is the webMessageAsJson string parameter parsed as a JSON string into a JavaScript object. The event arg's source property of the event arg is a reference to the window.chrome.webview object. For information about sending messages from the iframe to the host, navigate to WebMessageReceived. The message is sent asynchronously. If a navigation occurs before the message is posted to the iframe, the message is not be sent.

See Also

IsWebMessageEnabled

WebMessageReceived

PostWebMessageAsString(string)

PostWebMessageAsString(string)

Posts a message that is a simple string rather than a JSON string representation of a JavaScript object.

public void PostWebMessageAsString(string webMessageAsString)

Parameters

webMessageAsString string

The web message to be posted to the iframe.

Remarks

This behaves in exactly the same manner as PostWebMessageAsJson(string), but the data property of the event arg of the window.chrome.webview message is a string with the same value as webMessageAsString. Use this instead of PostWebMessageAsJson(string) if you want to communicate using simple strings rather than JSON objects.

See Also

WebMessageReceived

PostWebMessageAsJson(string)

RemoveHostObjectFromScript(string)

Remove the host object specified by the name so that it is no longer accessible from JavaScript code in the iframe.

public void RemoveHostObjectFromScript(string name)

Parameters

name string

Remarks

While new access attempts are denied, if the object is already obtained by JavaScript code in the iframe, the JavaScript code continues to have access to that object. Calling this method for a name that is already removed or was never added fails. If the iframe is destroyed this method will return fail also.

Events

ContentLoading

ContentLoading is raised before any content is loaded, including scripts added with AddScriptToExecuteOnDocumentCreatedAsync(string). ContentLoading is not raised if a same page navigation occurs.

public event EventHandler<CoreWebView2ContentLoadingEventArgs> ContentLoading

Event Type

EventHandler<CoreWebView2ContentLoadingEventArgs>

Remarks

This operation follows the NavigationStarting event and precedes the DOMContentLoaded and NavigationCompleted events.

DOMContentLoaded

DOMContentLoaded is raised when the initial HTML document has been parsed.

public event EventHandler<CoreWebView2DOMContentLoadedEventArgs> DOMContentLoaded

Event Type

EventHandler<CoreWebView2DOMContentLoadedEventArgs>

Remarks

This aligns with the the document's DOMContentLoaded event in HTML.

Destroyed

Destroyed event is raised when the iframe corresponding to this CoreWebView2Frame object is removed or the document containing that iframe is destroyed.

public event EventHandler<object> Destroyed

Event Type

EventHandler<object>

See Also

RemoveHostObjectFromScript(string)

NameChanged

NameChanged is raised when the iframe changes its window.name property.

public event EventHandler<object> NameChanged

Event Type

EventHandler<object>

See Also

RemoveHostObjectFromScript(string)

NavigationCompleted

NavigationCompleted is raised when the current frame has completely loaded (body.onload has been raised) or loading stopped with error.

public event EventHandler<CoreWebView2NavigationCompletedEventArgs> NavigationCompleted

Event Type

EventHandler<CoreWebView2NavigationCompletedEventArgs>

NavigationStarting

NavigationStarting is raised when the current frame is requesting permission to navigate to a different URI.

public event EventHandler<CoreWebView2NavigationStartingEventArgs> NavigationStarting

Event Type

EventHandler<CoreWebView2NavigationStartingEventArgs>

Remarks

A frame navigation will raise a NavigationStarting event and a FrameNavigationStarting event. All of the FrameNavigationStarting event handlers will be run before the NavigationStarting event handlers. All of the event handlers share a common CoreWebView2NavigationStartingEventArgs object. Whichever event handler is last to change the Cancel property will decide if the frame navigation will be cancelled. Redirects raise this event as well, and the navigation id is the same as the original one. You may block corresponding navigations until the event handler returns.

PermissionRequested

PermissionRequested is raised when content in an iframe or any of its descendant iframes requests permission to access some privileged resources.

public event EventHandler<CoreWebView2PermissionRequestedEventArgs> PermissionRequested

Event Type

EventHandler<CoreWebView2PermissionRequestedEventArgs>

Remarks

This relates to the PermissionRequested event on the CoreWebView2. Both these events will be raised in the case of an iframe requesting permission. The CoreWebView2Frame's event handlers will be invoked before the event handlers on the CoreWebView2. If the Handled property of the PermissionRequestedEventArgs is set to TRUE within the CoreWebView2Frame event handler, then the event will not be raised on the CoreWebView2, and it's event handlers will not be invoked. In the case of nested iframes, the PermissionRequested event will be raised from the top level iframe. If a deferral is not taken on the event args, the subsequent scripts are blocked until the event handler returns. If a deferral is taken, the scripts are blocked until the deferral is completed.

WebMessageReceived

WebMessageReceived is raised when the IsWebMessageEnabled setting is set and the iframe runs window.chrome.webview.postMessage.

public event EventHandler<CoreWebView2WebMessageReceivedEventArgs> WebMessageReceived

Event Type

EventHandler<CoreWebView2WebMessageReceivedEventArgs>

Examples

Remarks

The postMessage function is void postMessage(object) where object is any object supported by JSON conversion. When postMessage is called, the handler's Invoke method will be called with the object parameter postMessage converted to a JSON string.