This class is a bundle of the most common parameters used to create <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2Environment"/> and <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2Controller"/> instances.
Its main purpose is to be set to <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CreationProperties"/> in order to customize the environment and/or controller used by a <seecref="T:Microsoft.Web.WebView2.WinForms.WebView2"/> during implicit initialization.
</summary>
<remarks>
This class isn't intended to contain all possible environment or controller customization options.
If you need complete control over the environment and/or controller used by a WebView2 control then you'll need to initialize the control explicitly by
creating your own environment (with <seecref="M:Microsoft.Web.WebView2.Core.CoreWebView2Environment.CreateAsync(System.String,System.String,Microsoft.Web.WebView2.Core.CoreWebView2EnvironmentOptions)"/>) and/or controller options (with <seecref="M:Microsoft.Web.WebView2.Core.CoreWebView2Environment.CreateCoreWebView2ControllerOptions"/>) and passing them to <seecref="M:Microsoft.Web.WebView2.WinForms.WebView2.EnsureCoreWebView2Async(Microsoft.Web.WebView2.Core.CoreWebView2Environment,Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions)"/>
*before* you set the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.Source"/> property to anything.
See the <seecref="T:Microsoft.Web.WebView2.WinForms.WebView2"/> class documentation for an initialization overview.
Gets or sets the value to pass as the browserExecutableFolder parameter of <seecref="M:Microsoft.Web.WebView2.Core.CoreWebView2Environment.CreateAsync(System.String,System.String,Microsoft.Web.WebView2.Core.CoreWebView2EnvironmentOptions)"/> when creating an environment with this instance.
Gets or sets the value to pass as the userDataFolder parameter of <seecref="M:Microsoft.Web.WebView2.Core.CoreWebView2Environment.CreateAsync(System.String,System.String,Microsoft.Web.WebView2.Core.CoreWebView2EnvironmentOptions)"/> when creating an environment with this instance.
Gets or sets the value to use for the Language property of the CoreWebView2EnvironmentOptions parameter passed to <seecref="M:Microsoft.Web.WebView2.Core.CoreWebView2Environment.CreateAsync(System.String,System.String,Microsoft.Web.WebView2.Core.CoreWebView2EnvironmentOptions)"/> when creating an environment with this instance.
Gets or sets the value to use for the ProfileName property of the CoreWebView2ControllerOptions parameter passed to CreateCoreWebView2ControllerWithOptionsAsync when creating an controller with this instance.
Gets or sets the value to pass as the AdditionalBrowserArguments parameter of <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2EnvironmentOptions"/> which is passed to <seecref="M:Microsoft.Web.WebView2.Core.CoreWebView2Environment.CreateAsync(System.String,System.String,Microsoft.Web.WebView2.Core.CoreWebView2EnvironmentOptions)"/> when creating an environment with this instance.
Gets or sets the value to use for the IsInPrivateModeEnabled property of the CoreWebView2ControllerOptions parameter passed to CreateCoreWebView2ControllerWithOptionsAsync when creating an controller with this instance.
Creates a <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions"/> using the current values of this instance's properties.
</summary>
<returns>A <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions"/> object or null if no controller-related properties are set.</returns>
<exceptioncref="T:System.NullReferenceException">Thrown if the parameter environment is null.</exception>
After construction the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> property is <c>null</c>.
Call <seecref="M:Microsoft.Web.WebView2.WinForms.WebView2.EnsureCoreWebView2Async(Microsoft.Web.WebView2.Core.CoreWebView2Environment,Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions)"/> to initialize the underlying <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2"/>.
</summary>
<remarks>
This control is effectively a wrapper around the WebView2 COM API, which you can find documentation for here: https://aka.ms/webview2
You can directly access the underlying ICoreWebView2 interface and all of its functionality by accessing the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> property.
Some of the most common COM functionality is also accessible directly through wrapper methods/properties/events on the control.
Upon creation, the control's CoreWebView2 property will be null.
This is because creating the CoreWebView2 is an expensive operation which involves things like launching Edge browser processes.
There are two ways to cause the CoreWebView2 to be created:
1) Call the <seecref="M:Microsoft.Web.WebView2.WinForms.WebView2.EnsureCoreWebView2Async(Microsoft.Web.WebView2.Core.CoreWebView2Environment,Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions)"/> method. This is referred to as explicit initialization.
2) Set the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.Source"/> property. This is referred to as implicit initialization.
Either option will start initialization in the background and return back to the caller without waiting for it to finish.
To specify options regarding the initialization process, either pass your own <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2Environment"/> to EnsureCoreWebView2Async or set the control's <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CreationProperties"/> property prior to initialization.
When initialization has finished (regardless of how it was triggered) then the following things will occur, in this order:
1) The control's <seecref="E:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2InitializationCompleted"/> event will be invoked. If you need to perform one time setup operations on the CoreWebView2 prior to its use then you should do so in a handler for that event.
2) If a Uri has been set to the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.Source"/> property then the control will start navigating to it in the background (i.e. these steps will continue without waiting for the navigation to finish).
3) The Task returned from <seecref="M:Microsoft.Web.WebView2.WinForms.WebView2.EnsureCoreWebView2Async(Microsoft.Web.WebView2.Core.CoreWebView2Environment,Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions)"/> will complete.
For more details about any of the methods/properties/events involved in the initialization process, see its specific documentation.
Accelerator key presses (e.g. Ctrl+P) that occur within the control will
fire standard key press events such as OnKeyDown. You can suppress the
control's default implementation of an accelerator key press (e.g.
printing, in the case of Ctrl+P) by setting the Handled property of its
EventArgs to true. Also note that the underlying browser process is
blocked while these handlers execute, so:
<listtype="number">
<item>
You should avoid doing a lot of work in these handlers.
</item>
<item>
Some of the WebView2 and CoreWebView2 APIs may throw errors if
invoked within these handlers due to being unable to communicate with
the browser process.
</item>
</list>
If you need to do a lot of work and/or invoke WebView2 APIs in response to
accelerator keys then consider kicking off a background task or queuing
Gets or sets a bag of options which are used during initialization of the control's <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/>.
This property cannot be modified (an exception will be thrown) after initialization of the control's CoreWebView2 has started.
</summary>
<exceptioncref="T:System.InvalidOperationException">Thrown if initialization of the control's CoreWebView2 has already started.</exception>
Explicitly trigger initialization of the control's <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/>.
</summary>
<paramname="environment">
A pre-created <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2Environment"/> that should be used to create the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/>.
Creating your own environment gives you control over several options that affect how the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> is initialized.
If you pass <c>null</c> (the default value) then a default environment will be created and used automatically.
</param>
<paramname="controllerOptions">
A pre-created <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions"/> that should be used to create the <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2"/>.
Creating your own controller options gives you control over several options that affect how the <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2"/> is initialized.
If you pass a controllerOptions to this method then it will override any settings specified on the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CreationProperties"/> property.
If you pass <c>null</c> (the default value) and no value has been set to <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CreationProperties"/> then a default controllerOptions will be created and used automatically.
</param>
<returns>
A Task that represents the background initialization process.
When the task completes then the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> property will be available for use (i.e. non-null).
Note that the control's <seecref="E:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2InitializationCompleted"/> event will be invoked before the task completes
or on exceptions.
</returns>
<remarks>
Unless previous initialization has already failed, calling this method additional times with the same parameter will have no effect (any specified environment is ignored) and return the same Task as the first call.
Unless previous initialization has already failed, calling this method after initialization has been implicitly triggered by setting the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.Source"/> property will have no effect if no environment is given
and simply return a Task representing that initialization already in progress.
Unless previous initialization has already failed, calling this method with a different environment after initialization has begun will result in an <seecref="T:System.ArgumentException"/>. For example, this can happen if you begin initialization
by setting the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.Source"/> property and then call this method with a new environment, if you begin initialization with <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CreationProperties"/> and then call this method with a new
environment, or if you begin initialization with one environment and then call this method with no environment specified.
When this method is called after previous initialization has failed, it will trigger initialization of the control's <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> again.
Note that even though this method is asynchronous and returns a Task, it still must be called on the UI thread like most public functionality of most UI controls.
<para>
The following summarizes the possible error values and a description of why these errors occur.
Thrown if this instance of <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> is already disposed, or if the calling thread isn't the thread which created this object (usually the UI thread). See <seecref="P:System.Windows.Forms.Control.InvokeRequired"/> for more info.
May also be thrown if the browser process has crashed unexpectedly and left the control in an invalid state. We are considering throwing a different type of exception for this case in the future.
Explicitly trigger initialization of the control's <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/>.
</summary>
<paramname="environment">
A pre-created <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2Environment"/> that should be used to create the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/>.
Creating your own environment gives you control over several options that affect how the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> is initialized.
If you pass <c>null</c> then a default environment will be created and used automatically.
</param>
<returns>
A Task that represents the background initialization process.
When the task completes then the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> property will be available for use (i.e. non-null).
Note that the control's <seecref="E:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2InitializationCompleted"/> event will be invoked before the task completes
or on exceptions.
</returns>
<remarks>
Unless previous initialization has already failed, calling this method additional times with the same parameter will have no effect (any specified environment is ignored) and return the same Task as the first call.
Unless previous initialization has already failed, calling this method after initialization has been implicitly triggered by setting the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.Source"/> property will have no effect if no environment is given
and simply return a Task representing that initialization already in progress.
Unless previous initialization has already failed, calling this method with a different environment after initialization has begun will result in an <seecref="T:System.ArgumentException"/>. For example, this can happen if you begin initialization
by setting the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.Source"/> property and then call this method with a new environment, if you begin initialization with <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CreationProperties"/> and then call this method with a new
environment, or if you begin initialization with one environment and then call this method with no environment specified.
When this method is called after previous initialization has failed, it will trigger initialization of the control's <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> again.
Note that even though this method is asynchronous and returns a Task, it still must be called on the UI thread like most public functionality of most UI controls.
</remarks>
<exceptioncref="T:System.ArgumentException">
Thrown if this method is called with a different environment than when it was initialized. See Remarks for more info.
Thrown if this instance of <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> is already disposed, or if the calling thread isn't the thread which created this object (usually the UI thread). See <seecref="P:System.Windows.Forms.Control.InvokeRequired"/> for more info.
May also be thrown if the browser process has crashed unexpectedly and left the control in an invalid state. We are considering throwing a different type of exception for this case in the future.
This is the private function which implements the actual background initialization task.
Cannot be called if the control is already initialized or has been disposed.
</summary>
<paramname="environment">
The environment to use to create the <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2Controller"/>.
If that is null then a default environment is created with <seecref="M:Microsoft.Web.WebView2.Core.CoreWebView2Environment.CreateAsync(System.String,System.String,Microsoft.Web.WebView2.Core.CoreWebView2EnvironmentOptions)"/> and its default parameters.
</param>
<paramname="controllerOptions">
The controllerOptions to use to create the <seecref="T:Microsoft.Web.WebView2.Core.CoreWebView2Controller"/>.
If that is null then a default controllerOptions is created with its default parameters.
</param>
<returns>A task representing the background initialization process.</returns>
<remarks>All the event handlers added here need to be removed in <seecref="M:Microsoft.Web.WebView2.WinForms.WebView2.Dispose(System.Boolean)"/>.</remarks>
The underlying CoreWebView2. Use this property to perform more operations on the WebView2 content than is exposed
on the WebView2. This value is null until it is initialized and the object itself has undefined behaviour once the control is disposed.
You can force the underlying CoreWebView2 to
initialize via the <seecref="M:Microsoft.Web.WebView2.WinForms.WebView2.EnsureCoreWebView2Async(Microsoft.Web.WebView2.Core.CoreWebView2Environment,Microsoft.Web.WebView2.Core.CoreWebView2ControllerOptions)"/> method.
</summary>
<exceptioncref="T:System.InvalidOperationException">Thrown if the calling thread isn't the thread which created this object (usually the UI thread). See <seecref="P:System.Windows.Forms.Control.InvokeRequired"/> for more info.</exception>
The Source property is the URI of the top level document of the
WebView2. Setting the Source is equivalent to calling <seecref="M:Microsoft.Web.WebView2.Core.CoreWebView2.Navigate(System.String)"/>.
Setting the Source will trigger initialization of the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/>, if not already initialized.
The default value of Source is <c>null</c>, indicating that the <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> is not yet initialized.
</summary>
<exceptioncref="T:System.ArgumentException">Specified value is not an absolute <seecref="T:System.Uri"/>.</exception>
<exceptioncref="T:System.NotImplementedException">Specified value is <c>null</c> and the control is initialized.</exception>
Executes the provided script in the top level document of the <seecref="T:Microsoft.Web.WebView2.WinForms.WebView2"/>.
This is equivalent to <seecref="M:Microsoft.Web.WebView2.Core.CoreWebView2.ExecuteScriptAsync(System.String)"/>.
</summary>
<exceptioncref="T:System.InvalidOperationException">The underlying <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> is not yet initialized.</exception>
<exceptioncref="T:System.InvalidOperationException">Thrown when browser process has unexpectedly and left this control in an invalid state. We are considering throwing a different type of exception for this case in the future.</exception>
Reloads the top level document of the <seecref="T:Microsoft.Web.WebView2.WinForms.WebView2"/>.
This is equivalent to <seecref="M:Microsoft.Web.WebView2.Core.CoreWebView2.Reload"/>.
</summary>
<exceptioncref="T:System.InvalidOperationException">The underlying <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> is not yet initialized.</exception>
<exceptioncref="T:System.InvalidOperationException">Thrown when browser process has unexpectedly and left this control in an invalid state. We are considering throwing a different type of exception for this case in the future.</exception>
Renders the provided HTML as the top level document of the <seecref="T:Microsoft.Web.WebView2.WinForms.WebView2"/>.
This is equivalent to <seecref="M:Microsoft.Web.WebView2.Core.CoreWebView2.NavigateToString(System.String)"/>.
</summary>
<exceptioncref="T:System.InvalidOperationException">The underlying <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> is not yet initialized.</exception>
<exceptioncref="T:System.InvalidOperationException">Thrown when browser process has unexpectedly and left this control in an invalid state. We are considering throwing a different type of exception for this case in the future.</exception>
<remarks>The <c>htmlContent</c> parameter may not be larger than 2 MB (2 * 1024 * 1024 bytes) in total size. The origin of the new page is <c>about:blank</c>.</remarks>
This event is triggered either 1) when the control's <seecref="P:Microsoft.Web.WebView2.WinForms.WebView2.CoreWebView2"/> has finished being initialized (regardless of how it was triggered or whether it succeeded) but before it is used for anything
OR 2) the initialization failed.
You should handle this event if you need to perform one time setup operations on the CoreWebView2 which you want to affect all of its usages