Skip to content

Commit 7eab2a3

Browse files
LiangTheDevLiangTheDev
authored
Merge pull request #3195 from MicrosoftEdge/CustomStoragePartition-draft
Create CustomStoragePartition.md
2 parents 3892f91 + 98f2e1f commit 7eab2a3

1 file changed

Lines changed: 208 additions & 0 deletions

File tree

‎specs/CustomStoragePartition.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
Custom Storage Partition
2+
===
3+
4+
# Background
5+
For certain WebView host apps, there is a desire to have different contexts for
6+
different WebViews using the same profile so that when the same websites run in
7+
these WebViews, they will have different DOM storages and cookie jars. An example
8+
is different accounts within an application.
9+
Previosly, the application can use different profiles for different contexts, but
10+
that has 2 short comings:
11+
- WebViews from different profiles are not allowed to have opener/opened window relationship.
12+
- Using profiles means totally different storage for all files like http caches and less performance.
13+
14+
To help managing different application contexts while using the same profile, we are
15+
introducing an API to set custom storage parition and an API to clear all data in
16+
a custom storage partition.
17+
18+
When an application sets custom storage parition for a WebView, the sites and iframes
19+
running inside the WebView will act as if the site were running in a third party iframe
20+
inside a top level site uniquelly associated with the custom storage partition id and have
21+
separate [storage partition](https://developer.chrome.com/docs/privacy-sandbox/storage-partitioning/)
22+
and [cookie partition](https://developer.chrome.com/docs/privacy-sandbox/chips/).
23+
24+
# Conceptual pages (How To)
25+
This feature depends on [storage partition](https://developer.chrome.com/docs/privacy-sandbox/storage-partitioning/)
26+
and [cookie partition](https://developer.chrome.com/docs/privacy-sandbox/chips/) browser
27+
features which are currently experimental. Before those features are enabled by default,
28+
the application must enable them by ensuring `--enable-features=ThirdPartyStoragePartitioning,PartitionedCookies`
29+
is set in [CoreWebView2EnvironmentOptions.AdditionalBrowserArguments](https://learn.microsoft.com/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environmentoptions#additionalbrowserarguments)
30+
used to create CoreWebView2Environment. If not set, no custom storage partition will be
31+
created and all data will be treated as unpartitioned and stored in the global default
32+
location for the profile.
33+
The custom storage partition APIs will remain experiemental when related browser features
34+
are still experimental.
35+
36+
# Examples
37+
38+
The example below illustrates how to set partition id on WebView and how to clear all
39+
data stored in the custom storage partition.
40+
41+
## Win32 C++
42+
```cpp
43+
wil::com_ptr<ICoreWebView2_18> m_webView;
44+
45+
void OnWebViewCreated()
46+
{
47+
// ...
48+
// other WebView setup like add event handlers, update settings.
49+
50+
// Sets custom storage partition identified by the partitionId, which uniquely
51+
// identifies an application context.
52+
PCWSTR partitionId = L"Partition 1";
53+
CHECK_FAILURE(m_webview->put_CustomStoragePartitionId(partitionId));
54+
55+
// Navigate to start page
56+
m_webview->Navigation(startPage);
57+
}
58+
59+
// Clears all data in custom storage partition identified by the partitionId.
60+
// Called when the application context is removed.
61+
HRESULT ClearPartitionData(PCWSTR partitionId)
62+
{
63+
wil::com_ptr<ICoreWebView2Profile> webView2Profile;
64+
CHECK_FAILURE(m_webview->get_Profile(&webView2Profile));
65+
auto webView2Profile8 = webView2Profile.try_query<ICoreWebView2Profile8>();
66+
CHECK_FEATURE_RETURN(webView2Profile8);
67+
CHECK_FAILURE(webView2Profile8->ClearCustomStoragePartitionData(
68+
partitionId,
69+
Callback<ICoreWebView2StagingClearCustomStoragePartitionDataCompletedHandler>(
70+
[this](HRESULT result) -> HRESULT
71+
{
72+
if (SUCCEEDED(result))
73+
{
74+
AsyncMessageBox(L"Completed", L"Clear Custom Partition Data");
75+
}
76+
else
77+
{
78+
std::wstringstream message;
79+
message << L"Failed: " << std::to_wstring(result) << L"(0x" << std::hex
80+
<< result << L")" << std::endl;
81+
AsyncMessageBox(message.str(), L"Clear Custom Partition Data");
82+
}
83+
return S_OK;
84+
}).Get()));
85+
return S_OK;
86+
}
87+
88+
```
89+
90+
## .NET/WinRT
91+
```c#
92+
private CoreWebView2 m_webview;
93+
94+
// Sets custom storage partition identified by the partitionId, which uniquely
95+
// identifies an application context.
96+
void CoreWebView_Created()
97+
{
98+
// ...
99+
// other WebView setup like add event handlers, update settings.
100+
101+
// Sets custom storage partition identified by the partitionId, which uniquely
102+
// identifies an application context.
103+
string partitionId = "Partition 1";
104+
m_webview.CustomStoragePartitionId = partitionId;
105+
106+
// Navigate to start page
107+
m_webview.Navigation(startPage);
108+
}
109+
110+
// Clears all data in custom storage partition identified by the partitionId.
111+
// Called when the application context is removed.
112+
async void ClearPartitionData(string partitionId)
113+
{
114+
await m_webview.Profile.ClearCustomStoragePartitionDataAsync(partitionId);
115+
MessageBox.Show(this, "Completed", "Clear Custom Partition Data");
116+
}
117+
118+
```
119+
120+
# API Details
121+
## Win32 C++
122+
```
123+
interface ICoreWebView2_18 : ICoreWebView2_17 {
124+
/// Gets the `CustomStoragePartitionId` property.
125+
[propget] HRESULT CustomStoragePartitionId([out, retval] LPWSTR* customStoragePartitionId);
126+
127+
/// Sets the `CustomStoragePartitionId` property.
128+
/// This feature requires enabling 2 experimental browser features to work properly.
129+
/// These features will be enabled by default in the future.
130+
/// Before these features are enabled by default, please enable them by ensuring
131+
/// `--enable-features=ThirdPartyStoragePartitioning,PartitionedCookies` is set in
132+
/// `AdditionalBrowserArguments` in `CoreWebView2EnvironmentOptions` used to create
133+
/// CoreWebView2Environment. If these features are not enabled, all data are treated
134+
/// as unpartitioned and stored in the global default location for the profile.
135+
/// When it is set, the page in the WebView will act as if the page were hosted in a
136+
/// top level site uniquely associated with the `partitionId` and have a separate
137+
/// storage partition as described in https://developer.chrome.com/docs/privacy-sandbox/storage-partitioning/
138+
/// and separete cookie partition as described in https://developer.chrome.com/docs/privacy-sandbox/chips/
139+
/// with all cookies partitioned.
140+
/// If `customStoragePartitionId` is nullptr or empty string, the
141+
/// `CustomStoragePartitionId` will be reset and the page inside the WebView
142+
/// will work normally with data treated as unpartitioned.
143+
/// The `customStoragePartitionId` parameter is case sensitive. The default is
144+
/// an empty string. There is no restriction on the length or what characters
145+
/// can be used in partition id.
146+
/// The change of the custom storage partition id will be applied to new
147+
/// page or iframe navigations and not impact existing pages and iframes.
148+
/// To avoid accidentally use new partition id for pending navigations of old page
149+
/// or iframe, it is recommended to create a new WebView for new partition instead
150+
/// of changing partition. If you really have to change partition, it is
151+
/// recommended to navigate to a blank page before setting the new partition
152+
/// id and navigate to a page for the new partition.
153+
///
154+
/// As setting custom storage partition id does not change DOM security
155+
/// model, developers should be very careful for WebViews with opener and
156+
/// opened window relationship, especially when the pages in the WebViews
157+
/// have same origin, like when the opened window is the same site or
158+
/// about:blank. The pages in these WebViews can access each other’s DOM and
159+
/// therefore can potentially access DOM storage and cookies in different
160+
/// partition for the same site. It is recommended to set the same custom
161+
/// storage partition id for these WebViews, unless there is an absolute need
162+
/// to set different partition ids and only trusted code is hosted in them.
163+
///
164+
[propput] HRESULT CustomStoragePartitionId([in] LPCWSTR customStoragePartitionId);
165+
}
166+
167+
interface ICoreWebView2Profile8 : ICoreWebView2Profile7 {
168+
/// Clears all DOM storage and cookies in the custom storage partition
169+
/// identified by the `customStoragePartitionId`.
170+
/// As DOM storage and cookies in the custom storage partition is also browsing
171+
/// data, they will also be cleared when `ClearBrowsingData`,
172+
/// `ClearBrowsingDataInTimeRange` or `ClearBrowsingDataAll` is called and
173+
/// the clearing condition is met.
174+
///
175+
HRESULT ClearCustomStoragePartitionData(
176+
[in] LPCWSTR customStoragePartitionId,
177+
[in] ICoreWebView2ClearCustomStoragePartitionDataCompletedHandler* handler);
178+
}
179+
180+
interface ICoreWebView2ClearCustomStoragePartitionDataCompletedHandler : IUnknown {
181+
182+
/// Provide the completion status of the corresponding asynchronous method.
183+
HRESULT Invoke([in] HRESULT errorCode);
184+
}
185+
186+
```
187+
188+
## .NET/WinRT
189+
```c#
190+
namespace Microsoft.Web.WebView2.Core
191+
{
192+
193+
class CoreWebView2
194+
{
195+
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2_18")]
196+
{
197+
public string CustomStoragePartitionId { get; set; };
198+
}
199+
}
200+
201+
class CoreWebView2Profile
202+
{
203+
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Profile8")]
204+
{
205+
public async Task ClearCustomStoragePartitionDataAsync(string customStoragePartitionId);
206+
}
207+
}
208+
```

0 commit comments

Comments
 (0)