Class CoreWebView2EnvironmentOptions

Namespace

Microsoft.Web.WebView2.Core

Assembly

Microsoft.Web.WebView2.Core.dll

Options used to create WebView2 Environment.

public class CoreWebView2EnvironmentOptions

Inheritance

object

CoreWebView2EnvironmentOptions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Default values will use your defaulted Edge WebView2 Runtime binaries and user data folder.

Constructors

CoreWebView2EnvironmentOptions(string, string, string, bool, List<CoreWebView2CustomSchemeRegistration>)

Initializes a new instance of the CoreWebView2EnvironmentOptions class.

public CoreWebView2EnvironmentOptions(string additionalBrowserArguments = null, string language = null, string targetCompatibleBrowserVersion = null, bool allowSingleSignOnUsingOSPrimaryAccount = false, List<CoreWebView2CustomSchemeRegistration> customSchemeRegistrations = null)

Parameters

additionalBrowserArguments string

AdditionalBrowserArguments can be specified to change the behavior of the WebView.

language string

The default language that WebView will run with.

targetCompatibleBrowserVersion string

The version of the Edge WebView2 Runtime binaries required to be compatible with the calling application.

allowSingleSignOnUsingOSPrimaryAccount bool

Set to true if single sign on be enabled using the end user's OS primary account. Defaults to false.

customSchemeRegistrations List<CoreWebView2CustomSchemeRegistration>

List of custom scheme registrations to be applied to the CoreWebView2Environment.

CoreWebView2EnvironmentOptions(string, string, string, bool, List<CoreWebView2CustomSchemeRegistration>, CoreWebView2ReleaseChannels, CoreWebView2ChannelSearchKind)

Initializes a new instance of the CoreWebView2EnvironmentOptions class.

public CoreWebView2EnvironmentOptions(string additionalBrowserArguments, string language, string targetCompatibleBrowserVersion, bool allowSingleSignOnUsingOSPrimaryAccount, List<CoreWebView2CustomSchemeRegistration> customSchemeRegistrations, CoreWebView2ReleaseChannels releaseChannels = (CoreWebView2ReleaseChannels)31, CoreWebView2ChannelSearchKind channelSearchKind = CoreWebView2ChannelSearchKind.MostStable)

Parameters

additionalBrowserArguments string

AdditionalBrowserArguments can be specified to change the behavior of the WebView.

language string

The default language that WebView will run with.

targetCompatibleBrowserVersion string

The version of the Edge WebView2 Runtime binaries required to be compatible with the calling application.

allowSingleSignOnUsingOSPrimaryAccount bool

Set to true if single sign on be enabled using the end user's OS primary account. Defaults to false.

customSchemeRegistrations List<CoreWebView2CustomSchemeRegistration>

List of custom scheme registrations to be applied to the CoreWebView2Environment.

releaseChannels CoreWebView2ReleaseChannels

The release channels that are searched for during environment creation.

channelSearchKind CoreWebView2ChannelSearchKind

Set to CoreWebView2ChannelSearchKind.LeastStable so that environment creation searches for binaries from least to most stable: Canary -> Dev -> Beta -> WebView2 Runtime. Defaults to CoreWebView2RuntimeChannel.MostStable.

Properties

AdditionalBrowserArguments

Gets or sets the additional browser arguments to change the behavior of the WebView.

public string AdditionalBrowserArguments { get; set; }

Property Value

string

Remarks

The arguments are passed to the browser process as part of the command. For more information about using command-line switches with Chromium browser processes, navigate to [Run Chromium with Flags](https://aka.ms/RunChromiumWithFlags). The value appended to a switch is appended to the browser process, for example, in --edge-webview-switches=xxx the value is xxx. If you specify a switch that is important to WebView functionality, it is ignored, for example, --user-data-dir. Specific features are disabled internally and blocked from being enabled. If a switch is specified multiple times, only the last instance is used.

A merge of the different values of the same switch is not attempted, except for disabled and enabled features. The features specified by --enable-features and --disable-features will be merged with simple logic:

• The features are the union of the specified features and built-in features. If a feature is disabled, it is removed from the enabled features list.

If you specify command-line switches and sets this property, the --edge-webview-switches value takes precedence and is processed last. If a switch fails to parse, the switch is ignored. The default state for the operation is to run the browser process with no extra flags.

Please note that calling this API twice will replace the previous value rather than appending to it. If there are multiple switches, there should be a space in between them. The one exception is if multiple features are being enabled/disabled for a single switch, in which case the features should be comma-separated. Ex. "--disable-features=feature1,feature2 --some-other-switch --do-something"

AllowSingleSignOnUsingOSPrimaryAccount

Determines whether to enable single sign on with Azure Active Directory (AAD) resources inside WebView using the logged in Windows account and single sign on (SSO) with web sites using Microsoft account associated with the login in Windows account.

public bool AllowSingleSignOnUsingOSPrimaryAccount { get; set; }

Property Value

bool

Remarks

The default value is false. Universal Windows Platform apps must also declare enterpriseCloudSSO restricted capability for the single sign on (SSO) to work.

AreBrowserExtensionsEnabled

Enable/disable browser extensions.

public bool AreBrowserExtensionsEnabled { get; set; }

Property Value

bool

Remarks

When AreBrowserExtensionsEnabled is set to true, new extensions can be added to user profile and used. AreBrowserExtensionsEnabled is default to be false, in this case, new extensions can't be installed, and already installed extension won't be available to use in user profile. If connecting to an already running environment with a different value for AreBrowserExtensionsEnabled property, it will fail with HRESULT_FROM_WIN32(ERROR_INVALID_STATE). See CoreWebView2BrowserExtension for Extensions API details.

ChannelSearchKind

Set ChannelSearchKind to CoreWebView2ChannelSearchKind.LeastStable so that the WebView2 loader searches for binaries from least to most stable: Canary -> Dev -> Beta -> WebView2 Runtime.

public CoreWebView2ChannelSearchKind ChannelSearchKind { get; set; }

Property Value

CoreWebView2ChannelSearchKind

Remarks

The ChannelSearchKind property is CoreWebView2ChannelSearchKind.MostStable by default and environment creation searches for a release channel on the machine from most to least stable using the first channel found. The default search order is: WebView2 Release -> Beta -> Dev -> Canary. Set ChannelSearchKind to CoreWebView2ChannelSearchKind.LeastStable to reverse the search order so that environment creation searches for a channel from least to most stable. If a ReleaseChannels has been provided, environment creation will only search for channels in the set. See CoreWebView2ReleaseChannels for more details on channels. This property can be overridden by the corresponding registry key ChannelSearchKind or the environment variable WEBVIEW2_CHANNEL_SEARCH_KIND. Set the value to 1 to reverse the search order. See CreateAsync(string, string, CoreWebView2EnvironmentOptions) for more details on overrides.

CustomSchemeRegistrations

List of custom scheme registrations to be applied to the CoreWebView2Environment

public List<CoreWebView2CustomSchemeRegistration> CustomSchemeRegistrations { get; }

Property Value

List<CoreWebView2CustomSchemeRegistration>

EnableTrackingPrevention

The EnableTrackingPrevention property is used to enable/disable tracking prevention feature in WebView2. This property enable/disable tracking prevention for all the WebView2's created in the same environment. By default this feature is enabled to block potentially harmful trackers and trackers from sites that aren't visited before and set to Balanced or whatever value was last changed/persisted on the profile.

public bool EnableTrackingPrevention { get; set; }

Property Value

bool

Remarks

You can set this property to false to disable the tracking prevention feature if the app only renders content in the WebView2 that is known to be safe. Disabling this feature when creating environment also improves runtime performance by skipping related code.

You shouldn't disable this property if WebView2 is being used as a "full browser" with arbitrary navigation and should protect end user privacy.

There is PreferredTrackingPreventionLevel property to control levels of tracking prevention of the WebView2's associated with a same profile. However, you can also disable tracking prevention later using PreferredTrackingPreventionLevel property and None value but that doesn't improves runtime performance.

See PreferredTrackingPreventionLevel for more details.

Tracking prevention protects users from online tracking by restricting the ability of trackers to access browser-based storage as well as the network. See Tracking prevention.

ExclusiveUserDataFolderAccess

Determines whether other processes can create CoreWebView2Controller from CoreWebView2Environment created with the same user data folder and therefore sharing the same WebView browser process instance.

public bool ExclusiveUserDataFolderAccess { get; set; }

Property Value

bool

Remarks

The default value is false.

IsCustomCrashReportingEnabled

When IsCustomCrashReportingEnabled is set to true, Windows won't send crash data to Microsoft endpoint.

public bool IsCustomCrashReportingEnabled { get; set; }

Property Value

bool

Remarks

The default value is false. In this case, WebView will respect OS consent.

Language

Gets or sets the default display language for WebView.

public string Language { get; set; }

Property Value

string

Remarks

It applies to browser UIs such as context menu and dialogs. It also applies to the accept-languages HTTP header that WebView sends to websites. The intended locale value is in the format of BCP 47 Language Tags. More information can be found from IETF BCP47.

ReleaseChannels

Sets the ReleaseChannels, which is a mask of one or more CoreWebView2ReleaseChannels indicating which channels environment creation should search for.

public CoreWebView2ReleaseChannels ReleaseChannels { get; set; }

Property Value

CoreWebView2ReleaseChannels

Remarks

OR operation(s) can be applied to multiple CoreWebView2ReleaseChannels to create a mask. The default value is a mask of all the channels. By default, environment creation searches for channels from most to least stable, using the first channel found on the device. When ReleaseChannels is provided, environment creation will only search for the channels specified in the set. Set ChannelSearchKind to CoreWebView2ChannelSearchKind.LeastStable to reverse the search order so that environment creation searches for the least stable build first. See CoreWebView2ReleaseChannels for descriptions of each channel. Environment creation fails if it is unable to find any channel from the ReleaseChannels installed on the device. Use GetAvailableBrowserVersionString(string, CoreWebView2EnvironmentOptions) to verify which channel is used. If both a BrowserExecutableFolder and ReleaseChannels are provided, the BrowserExecutableFolder takes precedence. The ReleaseChannels can be overridden by the corresponding registry override ReleaseChannels or the environment variable WEBVIEW2_RELEASE_CHANNELS. Set the value to a comma-separated string of integers, which map to the following release channel values: Stable (0), Beta (1), Dev (2), and Canary (3). For example, the values "0,2" and "2,0" indicate that environment creation should only search for Dev channel and the WebView2 Runtime, using the order indicated by ChannelSearchKind. Environment creation attempts to interpret each integer and treats any invalid entry as Stable channel.

ReleaseChannels	Channel Search Kind: Most Stable (default)	Channel Search Kind: Least Stable
CoreWebView2ReleaseChannels.Beta | CoreWebView2ReleaseChannels.Stable	WebView2 Runtime -> Beta	Beta -> WebView2 Runtime
CoreWebView2ReleaseChannels.Canary | CoreWebView2ReleaseChannels.Dev | CoreWebView2ReleaseChannels.Beta | CoreWebView2ReleaseChannels.Stable	WebView2 Runtime -> Beta -> Dev -> Canary	Canary -> Dev -> Beta -> WebView2 Runtime
CoreWebView2ReleaseChannels.Canary	Canary	Canary
CoreWebView2ReleaseChannels.Beta | CoreWebView2ReleaseChannels.Canary | CoreWebView2ReleaseChannels.Stable	WebView2 Runtime -> Beta -> Canary	Canary -> Beta -> WebView2 Runtime

ScrollBarStyle

Set ScrollBar style to be used.

public CoreWebView2ScrollbarStyle ScrollBarStyle { get; set; }

Property Value

CoreWebView2ScrollbarStyle

Remarks

The default is CoreWebView2ScrollbarStyle.Default which specifies the default browser ScrollBar style. CSS styles that modify the ScrollBar applied on top of native ScrollBar styling that is selected with CoreWebView2ScrollbarStyle.

TargetCompatibleBrowserVersion

Gets or sets the version of the WebView2 Runtime binaries required to be compatible with your app.

public string TargetCompatibleBrowserVersion { get; set; }

Property Value

string

Remarks

This defaults to the WebView2 Runtime version that corresponds with the version of the SDK the app is using. The format of this value is the same as the format of the BrowserVersionString property and other BrowserVersion values. Only the version part of the BrowserVersion value is respected. The channel suffix, if it exists, is ignored. The version of the WebView2 Runtime binaries actually used may be different from the specified TargetCompatibleBrowserVersion. The binaries are only guaranteed to be compatible. Verify the actual version on the BrowserVersionString property.