webviewloader

README

Webviewloader

Webviewloader is a port of OpenWebView2Loader to Go.

It is intended to be feature-complete with the original WebView2Loader distributed with the WebView2 NuGet package, but some features are intentionally not implemented.

Status

• CompareBrowserVersions
• CreateCoreWebView2Environment
• CreateCoreWebView2EnvironmentWithOptions
• GetAvailableCoreWebView2BrowserVersionString

Not implemented features

• Registry Overrides of Parameters
• Env Variable Overrides of Parameters
• Does not incorporate GetCurrentPackageInfo to search for an installed runtime

Documentation

Index

• func CompareBrowserVersions(v1 string, v2 string) (int, error)
• func CreateCoreWebView2Environment(...) error
• func CreateCoreWebView2EnvironmentWithOptions(...) error
• func GetAvailableCoreWebView2BrowserVersionString(browserExecutableFolder string) (string, error)
• func WithAdditionalBrowserArguments(args string) option
• func WithAllowSingleSignOnUsingOSPrimaryAccount(allow bool) option
• func WithBrowserExecutableFolder(folder string) option
• func WithExclusiveUserDataFolderAccess(exclusive bool) option
• func WithLanguage(lang string) option
• func WithTargetCompatibleBrowserVersion(version string) option
• func WithUserDataFolder(folder string) option
• type HRESULT
• type ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler
• type ICoreWebView2Environment

Functions

func CompareBrowserVersions

func CompareBrowserVersions(v1 string, v2 string) (int, error)

CompareBrowserVersions will compare the 2 given versions and return:

-1 = v1 < v2
 0 = v1 == v2
 1 = v1 > v2

func CreateCoreWebView2Environment

func CreateCoreWebView2Environment(environmentCompletedHandler ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler) error

CreateCoreWebView2Environment creates an evergreen WebView2 Environment using the installed WebView2 Runtime version.

This is equivalent to running CreateCoreWebView2EnvironmentWithOptions without any options. For more information, see CreateCoreWebView2EnvironmentWithOptions.

func CreateCoreWebView2EnvironmentWithOptions

func CreateCoreWebView2EnvironmentWithOptions(environmentCompletedHandler ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler, opts ...option) error

CreateCoreWebView2EnvironmentWithOptions creates an environment with a custom version of WebView2 Runtime, user data folder, and with or without additional options.

See https://docs.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/webview2-idl?#createcorewebview2environmentwithoptions

func GetAvailableCoreWebView2BrowserVersionString

func GetAvailableCoreWebView2BrowserVersionString(browserExecutableFolder string) (string, error)

GetAvailableCoreWebView2BrowserVersionString get the browser version info including channel name if it is the WebView2 Runtime. Channel names are Beta, Dev, and Canary.

func WithAdditionalBrowserArguments

func WithAdditionalBrowserArguments(args string) option

WithAdditionalBrowserArguments changes the behavior of the WebView.

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]ChromiumDevelopersHowTosRunWithFlags. 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.

\> [!NOTE]\n\> 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` are merged with simple logic.\n\> * The features is 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 use the `additionalBrowserArguments` parameter, 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.

func WithAllowSingleSignOnUsingOSPrimaryAccount

func WithAllowSingleSignOnUsingOSPrimaryAccount(allow bool) option

WithAllowSingleSignOnUsingOSPrimaryAccount is used to enable single sign on with Azure Active Directory (AAD) and personal Microsoft Account (MSA) resources inside WebView. All AAD accounts, connected to Windows and shared for all apps, are supported. For MSA, SSO is only enabled for the account associated for Windows account login, if any. Default is disabled. Universal Windows Platform apps must also declare `enterpriseCloudSSO` [Restricted capabilities][WindowsUwpPackagingAppCapabilityDeclarationsRestrictedCapabilities] for the single sign on (SSO) to work.

[WindowsUwpPackagingAppCapabilityDeclarationsRestrictedCapabilities]: /windows/uwp/packaging/app-capability-declarations\#restricted-capabilities "Restricted capabilities - App capability declarations | Microsoft Docs"

func WithBrowserExecutableFolder

func WithBrowserExecutableFolder(folder string) option

WithBrowserExecutableFolder to specify whether WebView2 controls use a fixed or installed version of the WebView2 Runtime that exists on a user machine.

To use a fixed version of the WebView2 Runtime, pass the folder path that contains the fixed version of the WebView2 Runtime. BrowserExecutableFolder supports both relative (to the application's executable) and absolute files paths. To create WebView2 controls that use the installed version of the WebView2 Runtime that exists on user machines, pass a empty string to WithBrowserExecutableFolder. In this scenario, the API tries to find a compatible version of the WebView2 Runtime that is installed on the user machine (first at the machine level, and then per user) using the selected channel preference. The path of fixed version of the WebView2 Runtime should not contain \Edge\Application\. When such a path is used, the API fails with HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED).

func WithExclusiveUserDataFolderAccess

func WithExclusiveUserDataFolderAccess(exclusive bool) option

WithExclusiveUserDataFolderAccess specifies that the WebView environment obtains exclusive access to the user data folder.

If the user data folder is already being used by another WebView environment with a different value for `ExclusiveUserDataFolderAccess` property, the creation of a WebView2Controller using the environment object will fail with `HRESULT_FROM_WIN32(ERROR_INVALID_STATE)`. When set as TRUE, no other WebView can be created from other processes using WebView2Environment objects with the same UserDataFolder. This prevents other processes from creating WebViews which share the same browser process instance, since sharing is performed among WebViews that have the same UserDataFolder. When another process tries to create a WebView2Controller from an WebView2Environment object created with the same user data folder, it will fail with `HRESULT_FROM_WIN32(ERROR_INVALID_STATE)`.

func WithLanguage

func WithLanguage(lang string) option

WithLanguage sets the default display language for WebView.

It applies to browser UI such as context menu and dialogs. It also applies to the `accept-languages` HTTP header that WebView sends to websites. It is in the format of

`language[-country]` where `language` is the 2-letter code from [ISO 639]ISO639LanguageCodesHtml and `country` is the 2-letter code from [ISO 3166]ISOStandard72482Html.

func WithTargetCompatibleBrowserVersion

func WithTargetCompatibleBrowserVersion(version string) option

WithTargetCompatibleBrowserVersion secifies the version of the WebView2 Runtime binaries required to be compatible with your app.

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 on the `ICoreWebView2Environment`.

func WithUserDataFolder

func WithUserDataFolder(folder string) option

WithUserDataFolder specifies to user data folder location for WebView2

You may specify the userDataFolder to change the default user data folder location for WebView2. The path is either an absolute file path or a relative file path that is interpreted as relative to the compiled code for the current process. Dhe default user data ({Executable File Name}.WebView2) folder is created in the same directory next to the compiled code for the app. WebView2 creation fails if the compiled code is running in a directory in which the process does not have permission to create a new directory. The app is responsible to clean up the associated user data folder when it is done.

Types

type HRESULT

type HRESULT int32

HRESULT

See https://docs.microsoft.com/en-us/windows/win32/seccrypto/common-hresult-values

type ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler

type ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler interface {
	// EnvironmentCompleted is invoked to receive the created WebView2Environment
	//
	// See https://docs.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2createcorewebview2environmentcompletedhandler?#invoke
	EnvironmentCompleted(errorCode HRESULT, createdEnvironment *ICoreWebView2Environment) HRESULT
}

ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler receives the WebView2Environment created using CreateCoreWebView2Environment.

type ICoreWebView2Environment

type ICoreWebView2Environment = combridge.IUnknownImpl

ICoreWebView2Environment Represents the WebView2 Environment

See https://docs.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2environment