API Review: Shared WebView2 Cluster Environment - #5654
Open
Navdeep Singh (Navdeep-ss) wants to merge 33 commits into
Open
API Review: Shared WebView2 Cluster Environment#5654Navdeep Singh (Navdeep-ss) wants to merge 33 commits into
Navdeep Singh (Navdeep-ss) wants to merge 33 commits into
Conversation
API proposal for a shared WebView2 cluster environment using the symmetric Create + synchronous Get model (Approach 2). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- (1.7) Rename PerExeProfileIsolation -> PerHostProfileIsolation for OS-neutrality - (1.6) Document per-Id persisted state in the Get reference doc-comment - (1.10) Add API-shape decisions section: new options type vs extending ICoreWebView2EnvironmentOptions, and WinRT mismatch-surfacing (result/status enum vs COMException) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Per repo spec conventions (template: 'talk about behavior, not implementation'), replace the storage/locking pseudocode (registry paths, AcquireLock/WriteRecord, WAIT_ABANDONED) with observable behavior guarantees, and condense the alternatives-considered section. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Top-level sections now exactly match the spec template (Background, Conceptual, Examples, API Details, Appendix). Remove the 'Open questions' section (no other spec has one) and the reviewer-facing 'API-shape decisions'/'Behavior guarantees' Appendix subsections; keep a lean 'Alternatives considered' and 'Relationship to existing options', matching how other specs use the Appendix. Also fix the C++ example's Get error handling and add Id constraints. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
CreateCoreWebView2ClusterEnvironment -> CreateOrJoinCoreWebView2ClusterEnvironment, the handler and the .NET/WinRT async method renamed to match. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The GUIDs were fabricated placeholders; real IIDs are allocated at implementation time. Matches specs like CustomDataPartition.md that omit uuid in the review IDL. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
No WebView2 spec exposes an HRESULT constant as API. Match the convention (e.g. MultiProfile.md) of throwing a COMException and comparing ex.HResult against the HRESULT value with a comment naming the error. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Trim API Details doc-comments to concise behavior, matching LMC reference conventions and the template style guide (describe behavior, not implementation). Removed implementation detail (storage/persistence 'State' note, Id->folder mapping rationale), design commentary (OS-neutral naming, sync justification), and conceptual/strategy narrative already covered in the Conceptual section. Standardized on 'options' over 'pinned set' jargon. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Drop internal shell/widgets example - Use 'WebView2 environment' rather than 'browser process tree' - Remove 'by accident' framing for cooperating apps - Remove reviewer-meta spec-scope/alternatives line from Background - Remove template conceptual-note line - Remove 'constant in a shared header' parenthetical Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The full P1/P2/P3 comparison lives in the internal design doc; the condensed duplicate is not public-doc material and most specs do not carry a rejected-designs section. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ChannelSearchKind only defines search order and is incomplete without ReleaseChannels (its matched pair). Keep the first iteration minimal; channel-selection options can be appended later on a derived options interface without breaking compat. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The prior text cited remote-debugging port/logging as omitted, but those are set via AdditionalBrowserArguments, which is included. Reframe: every exposed option is process-wide and first-creator-supplied; runtime-locating options (BrowserExecutableFolder, TargetCompatibleBrowserVersion, ReleaseChannels/ChannelSearchKind) are deferred to a later derived interface. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Appendix: keep only the process-wide new-type paragraph; drop the omitted-options list and any future-addition promise - Standardize 'attach to an identical cluster' -> 'attach to a cluster with matching options' - Name the model 'symmetric create-or-join' to match CreateOrJoin... - Re-flow the awkward Background line wrap - Remove the duplicate mismatch comment in the .NET example Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Model create/join outcomes with a COREWEBVIEW2_CLUSTER_ENVIRONMENT_STATUS enum (Succeeded, OptionsMismatch) returned in the completion handler, alongside errorCode (Print-style), instead of a bespoke HRESULT. - Surface not-supported (sandboxed/low-integrity/UWP, cannot share/access the UDF) via the synchronous return HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) for CreateOrJoin (handler not called) and as the HRESULT/COMException for the synchronous Get. - Add ERROR_NOT_SUPPORTED handling to both examples; fix .NET Get-inside-try and retry status check. - Address PR feedback: gets->creates; recommend a stable descriptive Id (need not be a GUID); define 'cooperating host apps'; state a cluster occupies its own UDF namespace and never joins a CreateCoreWebView2EnvironmentWithOptions environment. - Standardize terminology (cluster options, shared browser process, matching options); trim implementation detail from PerHostProfileIsolation; clarify profile-isolation wording. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adopt the ICoreWebView2ClusterEnvironmentCreateResult interface (Status + Environment) in the completion handler instead of separate status/environment parameters, matching the ICoreWebView2ExperimentalUpdateRuntimeResult / ICoreWebView2ExecuteScriptResult idiom and making the COM handler a clean source for the existing WinRT CreateResult projection. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Reframe the excluded options as a deliberate scoping choice for this initial version, not a technical 'cannot be shared'. - Simplify the Id-to-folder sentence and drop the confusing on-disk-layout clause. - Clarify that a private fallback environment uses your own user data folder with its own separate data. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Address Priyank's editorial comments: determines vs fixes; drop informal phrasing ('paid to launch', 'we mean', 'likes it'); apps -> applications; runtime -> WebView2 Runtime; de-emphasize sync/async in prose; rename BuildMyOptions -> BuildClusterOptions; standardize 'exists' over 'configured'; use nullptr in COM doc-comments; name the shared browser process; fix a missing blank line.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Label the Win32 C++ API Details code block as cpp. - Reword the CreateOrJoin doc-comment to drop synchronous/asynchronous adjectives and name CreateOrJoinCoreWebView2ClusterEnvironment and the handler parameter directly. - Standardize on Id for the concept/property in prose and doc-comments; keep the literal signature parameters lowercase id. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ainer, errors - Add ReleaseChannels and ChannelSearchKind to cluster options (COM + WinRT), matching the PoC implementation; defaults all-channels and MOST_STABLE. - Fix options lifetime: a cluster exists only while its browser process is running; Get returns ERROR_NOT_FOUND when not running (was incorrectly 'available whether or not running'). - Define what 'match' means: all options except Id equal, AdditionalBrowserArguments exact string, custom schemes same in same order. - Tighten NOT_SUPPORTED wording to sandboxed AppContainer (UWP), matching the AppContainer gate in the implementation. - Rename heading to Description; add Win32-only support note; add cross-host diagnostics trust note; validate existing options in samples; make failing-create handling concrete; state handler errorCode carries the same failures as CreateCoreWebView2EnvironmentWithOptions; align custom-scheme memory wording. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add %LOCALAPPDATA%\Microsoft\WebView2Clusters\<Id> as the runtime-derived cluster user data folder, and state that CreateCoreWebView2EnvironmentWithOptions cannot join a cluster even when passed a cluster folder path explicitly. Matches DeriveClusterUserDataFolder and the IsClusterUserDataFolder guard in entry.cc. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…l match, concurrency, trust/identity/session model, loader-override contract, and consistency fixes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: ef97d825-5b56-4882-8226-a3af1d04c96a
…and fix consistency Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: ef97d825-5b56-4882-8226-a3af1d04c96a
…ed-options rationale Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: ef97d825-5b56-4882-8226-a3af1d04c96a
…eview) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: ef97d825-5b56-4882-8226-a3af1d04c96a
…draft Add spec for SharedClusterEnvironment.md
Navdeep Singh (Navdeep-ss)
added
the
API Proposal Review
Navdeep Singh (Navdeep-ss)
changed the title
Navdeep Singh (Navdeep-ss)
changed the title
FrankC-msft
reviewed
Jul 28, 2026
FrankC-msft
reviewed
Jul 29, 2026
Replace the ERROR_NOT_SUPPORTED failure path with COREWEBVIEW2_CLUSTER_ENVIRONMENT_STATUS_NOT_SUPPORTED so an unsupported host is reported as a status on the completed handler rather than as a failure of the call. Transient user data folder access failures continue to surface as ordinary create failures. Add a runtime version check to the create samples so hosts feature-detect cluster support before use, and handle unknown future status values by falling back to a private environment. Treat a missing cluster as a null options result rather than ERROR_NOT_FOUND, which simplifies the create-or-join samples. Clarify that ClusterName is not a security boundary, since cluster folders can be enumerated under the per-user cluster root, and that PerHostProfileIsolation namespaces Edge browser profile names within the cluster's shared user data folder. Note that cluster environments target well coordinated applications. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e06cf32e-340d-4329-82e8-3470cba3b532
The previous guidance had the last cooperating application delete the folder during its own uninstall, using BrowserProcessExited. That does not work for MSIX, which cannot run code on uninstall, so the samples are removed. Applications now read UserDataFolder when they first create or join the cluster and persist the path, since the path can only be read from a live environment and none exists at uninstall time. Deletion is then driven by the installer: an uninstall custom action or script for MSI, and a self-removing scheduled task for MSIX. How an application determines that the other cooperating applications have been uninstalled remains app-specific and outside the scope of this API. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e06cf32e-340d-4329-82e8-3470cba3b532
The completion handler contract listed only Succeeded and OptionsMismatch, so a reader would conclude NotSupported could not be delivered there. Add the missing bullet. Bring the PerHostProfileIsolation IDL comment in line with the description, which now says the namespacing applies to Edge browser profile names within the cluster's shared user data folder. Reword the unsupported-host sentence, which read as though the application rather than the outcome was reported, and reflow two paragraphs left ragged by an earlier edit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e06cf32e-340d-4329-82e8-3470cba3b532
The C# sample checked GetAvailableBrowserVersionString for null, but that method throws WebView2RuntimeNotFoundException and never returns null, so the fallback to a private environment was unreachable on the one case step 0 exists to handle. Catch the exception instead. Split the C# sample into a create method and a create-with-options helper carrying an allowRetry flag, mirroring the C++ sample. The mismatch case now resolves in one place rather than falling through to a second status check after the switch, which was the misleading part of the earlier shape. Note both failure modes on the helper, matching the two checks the C++ sample makes, and align the shared step comments. Drop three restatements: that a missing cluster is expected rather than an error, stated in the sentence before it, and that retrying once bounds the work, which described a loop the C# sample does not contain. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: e06cf32e-340d-4329-82e8-3470cba3b532
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: ef97d825-5b56-4882-8226-a3af1d04c96a
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces the specification for a Shared WebView2 Cluster Environment, a first-class, explicit way for a set of cooperating host applications to opt into one shared WebView2 environment (a "cluster") and agree on the shared options up front. Today apps can share a browser process only implicitly by passing the same user data folder; this API makes the sharing intent explicit, keyed on a well-known
ClusterName, with a clear options-match contract and a way to read a cluster's options before joining.New APIs:
CreateOrJoinCoreWebView2ClusterEnvironment(options, handler)— Symmetric create-or-join. The first host to establish a cluster for a givenClusterNamefixes the cluster's options (first-creator-wins). A later host with matching options attaches to the running cluster; a host with different options receivesCOREWEBVIEW2_CLUSTER_ENVIRONMENT_STATUS_OPTIONS_MISMATCH.GetCoreWebView2ClusterEnvironmentOptions(clusterName, options)— Synchronously reads a running cluster's options without launching the shared browser process, so a host can decide before joining.New Interfaces and Enums:
ICoreWebView2ClusterEnvironmentOptions— the shared options (ClusterName,AdditionalBrowserArguments,Language,AllowSingleSignOnUsingOSPrimaryAccount,EnableTrackingPrevention,AreBrowserExtensionsEnabled,PerHostProfileIsolation,ReleaseChannels,ChannelSearchKind,CustomSchemeRegistrations).ICoreWebView2ClusterEnvironmentCreateResult—StatusplusEnvironment(non-null only when the status is Succeeded).ICoreWebView2CreateOrJoinClusterEnvironmentCompletedHandler— completion handler for the create-or-join operation.COREWEBVIEW2_CLUSTER_ENVIRONMENT_STATUS—Succeeded,OptionsMismatch.Details covered in the spec:
ClusterName, lifetime and liveness model, options-matching semantics, trust/identity/session model, host-dependent option resolution, the loader-override contract, and user-data-folder deletion guidance.