-
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Microsoft.Web.WebView2.Core.xml
8805 lines (8584 loc) · 602 KB
/
Microsoft.Web.WebView2.Core.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0"?>
<doc>
<assembly>
<name>Microsoft.Web.WebView2.Core</name>
</assembly>
<members>
<member name="T:Microsoft.Web.WebView2.Core.CoreWebView2">
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
<summary>
WebView2 enables you to host web content using the latest Microsoft Edge browser and web technology.
</summary>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.CreateFromComICoreWebView2(System.IntPtr)">
<summary>
Creates a CoreWebView2 object that wraps an existing COM ICoreWebView2 object.
This allows interacting with the CoreWebView2 using .NET, even if it was originally created using COM.
</summary>
<param name="value">Pointer to a COM object that implements the ICoreWebView2 COM interface.</param>
<returns>Returns a .NET CoreWebView2 object that wraps the COM object.</returns>
<exception cref="T:System.ArgumentNullException">Thrown when the provided COM pointer is null.</exception>
<exception cref="T:System.Runtime.InteropServices.InvalidComObjectException">Thrown when the value is not an ICoreWebView2 COM object and cannot be wrapped.</exception>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.GetComICoreWebView2">
<summary>
Returns the existing COM ICoreWebView2 object underlying this .NET CoreWebView2 object.
This allows interacting with the WebView2 control using COM APIs,
even if the control was originally created using .NET.
</summary>
<returns>Pointer to a COM object that implements the ICoreWebView2 COM interface.</returns>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.PrintToPdfAsync(System.String,Microsoft.Web.WebView2.Core.CoreWebView2PrintSettings)">
<summary>
Print the current page to PDF asynchronously with the provided settings.
</summary>
<remarks>
See <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2PrintSettings"/> for description of settings. Passing null for <c>printSettings</c> results in default print settings used.
Use <c>resultFilePath</c> to specify the path to the PDF file. The host should provide an absolute path, including file name. If the path points to an existing file, the file will be overwritten. If the path is not valid, the method fails.
The async PrintToPdf operation completes when the data has been written to the PDF file. If the application exits before printing is complete, the file is not saved. Only one `Printing` operation can be in progress at a time.
If PrintToPdf is called while a `PrintToPdf` or `PrintToPdfStream` or `Print` operation is in progress, the operation completes and returns false.
</remarks>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddWebResourceRequestedFilter(System.String,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceContext,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceRequestSourceKinds)">
<summary>
Adds a URI and resource context filter for corresponding request sources for the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceRequested"/> event.
</summary>
<param name="uri">A URI to be added to the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceRequested"/> event.</param>
<param name="ResourceContext">A resource context filter to be added to the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceRequested"/> event.</param>
<param name="RequestSourceKinds">A request source filter to be added to the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceRequested"/> event.</param>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.RemoveWebResourceRequestedFilter(System.String,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceContext,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceRequestSourceKinds)">
<summary>
Removes a matching WebResource filter that was previously added for the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceRequested"/> event.
</summary>
<param name="uri">An URI to be added to the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceRequested"/> event.</param>
<param name="ResourceContext">A resource context filter to be added to the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceRequested"/> event.</param>
<param name="RequestSourceKinds">A request source filter to be added to the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceRequested"/> event.</param>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.PostWebMessageAsJson(System.String,System.Collections.Generic.List{System.Object})">
<summary>
Same as <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.PostWebMessageAsJson(System.String)"/>, but also has support for posting DOM
objects to page content.
</summary>
<param name="webMessageAsJson">The web message to be posted to the top level document in
this WebView.</param>
<param name="additionalObjects"> Additional DOM objects posted to the content.</param>
<remarks>
The event args is an instance of <c>MessageEvent</c>. The <see
cref="P:Microsoft.Web.WebView2.Core.CoreWebView2Settings.IsWebMessageEnabled"/> setting must be <c>true</c> or the message
will not be sent. The event arg's <c>data</c> property of the event arg is the
<c>webMessageAsJson</c> string parameter parsed as a JSON string into a JavaScript object.
The event arg's <c>source</c> property of the event arg is a reference to the
<c>window.chrome.webview</c> object. For information about sending messages from the HTML
document in the WebView to the host, navigate to <see
cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebMessageReceived"/>. The message is sent asynchronously. If a
navigation occurs before the message is posted to the page, the message is not be sent.
This additionalObjects is retrieved in web content via the DOM MessageEvent <c>additionalObjects</c>
property as an array-like list of DOM objects. Currently these type of objects can be
posted:
<list type="table">
<listheader>
<description> .NET / WinRT </description>
<description> DOM type </description>
</listheader>
<item>
<description> <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2FileSystemHandle"/> </description>
<description> [FileSystemHandle](https://developer.mozilla.org/docs/Web/API/FileSystemHandle) </description>
</item>
<item>
<description> <c>null</c> </description>
<description> null </description>
</item>
</list>
The objects are posted to web content, following the
[structured-clone](https://developer.mozilla.org/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)
semantics, meaning only objects that can be cloned can be posted. They will also behave as
if they had been created by the web content they are posted to. For example, if a
<c>FileSystemFileHandle</c> is posted to a web content it can only be re-transferred via
<c>postMessage</c> to other web content [with the same
origin](https://fs.spec.whatwg.org/#filesystemhandle).
Warning: An app needs to be mindful when using this API to post DOM objects as this API
provides the web content with unusual access to sensitive Web Platform features such as
filesystem access! Similar to <c>PostWebMessageAsJson</c>, the app should check the <see
cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.Source"/> property right before posting the message to ensure the message
and objects will only be sent to the target web content that it expects to receive the DOM
objects. Additionally, the order of messages that are posted between <c>PostWebMessageAsJson</c>
and <c>PostWebMessageAsJsonWithAdditionalObjects</c> may not be preserved.
</remarks>
<seealso cref="P:Microsoft.Web.WebView2.Core.CoreWebView2Settings.IsWebMessageEnabled"/>
<seealso cref="P:Microsoft.Web.WebView2.Core.CoreWebView2WebMessageReceivedEventArgs.AdditionalObjects"/>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.ShowPrintUI">
<summary>
Opens the browser print preview dialog to print the current web page
</summary>
</member>
<member name="P:Microsoft.Web.WebView2.Core.CoreWebView2.Settings">
<summary>
Gets the <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2Settings"/> object contains various modifiable settings for the running WebView.
</summary>
</member>
<member name="P:Microsoft.Web.WebView2.Core.CoreWebView2.Source">
<summary>
Gets the URI of the current top level document.
</summary>
<remarks>
This value potentially changes as a part of the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.SourceChanged"/> event raised for some cases such as navigating to a different site or fragment navigations. It remains the same for other types of navigations such as page refreshes or <c>history.pushState</c> with the same URL as the current page.
</remarks>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.SourceChanged"/>
</member>
<member name="P:Microsoft.Web.WebView2.Core.CoreWebView2.BrowserProcessId">
<summary>
Gets the process ID of the browser process that hosts the WebView.
</summary>
</member>
<member name="P:Microsoft.Web.WebView2.Core.CoreWebView2.CanGoBack">
<summary>
<c>true</c> if the WebView is able to navigate to a previous page in the navigation history.
</summary>
<remarks>
If CanGoBack changes value, the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.HistoryChanged"/> event is raised.
</remarks>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.HistoryChanged"/>
</member>
<member name="P:Microsoft.Web.WebView2.Core.CoreWebView2.CanGoForward">
<summary>
<c>true</c> if the WebView is able to navigate to a next page in the navigation history.
</summary>
<remarks>
If CanGoForward changes value, the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.HistoryChanged"/> event is raised.
</remarks>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.HistoryChanged"/>
</member>
<member name="P:Microsoft.Web.WebView2.Core.CoreWebView2.DocumentTitle">
<summary>
Gets the title for the current top-level document.
</summary>
<remarks>
If the document has no explicit title or is otherwise empty, a default that may or may not match the URI of the document is used.
</remarks>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="DocumentTitle":::
</example>
</member>
<member name="P:Microsoft.Web.WebView2.Core.CoreWebView2.ContainsFullScreenElement">
<summary>
Indicates if the WebView contains a fullscreen HTML element.
</summary>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationStarting">
<summary>
NavigationStarting is raised when the WebView main frame is requesting permission to navigate to a different URI.
</summary>
<remarks>
Redirects raise this event as well, and the navigation id is the same as the original one. You may block corresponding navigations until the event handler returns.
</remarks>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="NavigationStarting":::
</example>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.ContentLoading">
<summary>
ContentLoading is raised before any content is loaded, including scripts added with <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync(System.String)"/>. ContentLoading is not raised if a same page navigation occurs (such as through fragment navigations or <c>history.pushState</c> navigations).
</summary>
<remarks>
This operation follows the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationStarting"/> and <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.SourceChanged"/> events and precedes the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.HistoryChanged"/> and <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationCompleted"/> events.
</remarks>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationStarting"/>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.SourceChanged"/>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.HistoryChanged"/>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationCompleted"/>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.SourceChanged">
<summary>
SourceChanged is raised when the <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.Source"/> property changes.
</summary>
<remarks>
SourceChanged is raised when navigating to a different site or fragment navigations. It is not raised for other types of navigations such as page refreshes or <c>history.pushState</c> with the same URL as the current page. This event is raised before <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.ContentLoading"/> for navigation to a new document.
</remarks>
<seealso cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.Source"/>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.ContentLoading"/>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.HistoryChanged">
<summary>
HistoryChanged is raised for changes to joint session history, which consists of top-level and manual frame navigations.
</summary>
<remarks>
Use HistoryChanged to verify that the <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.CanGoBack"/> or <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.CanGoForward"/> value has changed. HistoryChanged is also raised for using <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.GoBack"/> or <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.GoForward"/>. HistoryChanged is raised after <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.SourceChanged"/> and <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.ContentLoading"/>. CanGoBack is false for navigations initiated through CoreWebView2Frame APIs if there has not yet been a user gesture.
</remarks>
<seealso cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.CanGoBack"/>
<seealso cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.CanGoForward"/>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.SourceChanged"/>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.ContentLoading"/>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationCompleted">
<summary>
NavigationCompleted is raised when the WebView has completely loaded (<c>body.onload</c> has been raised) or loading stopped with error.
</summary>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="NavigationCompleted":::
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="DOMContentLoaded":::
</example>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.FrameNavigationStarting">
<summary>
FrameNavigationStarting is raised when a child frame in the WebView requests permission to navigate to a different URI.
</summary>
<remarks>
Redirects raise this operation as well, and the navigation id is the same as the original one. You may block corresponding navigations until the event handler returns.
</remarks>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.FrameNavigationCompleted">
<summary>
FrameNavigationCompleted is raised when a child frame has completely loaded (<c>body.onload</c> has been raised) or loading stopped with error.
</summary>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.ScriptDialogOpening">
<summary>
ScriptDialogOpening is raised when a JavaScript dialog (<c>alert</c>, <c>confirm</c>, <c>prompt</c>, or <c>beforeunload</c>) displays for the WebView.
</summary>
<remarks>
This event only is raised if the <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2Settings.AreDefaultScriptDialogsEnabled"/> property is set to <c>false</c>. This event suppresses dialogs or replaces default dialogs with custom dialogs.
If a deferral is not taken on the event args, the subsequent scripts are blocked until the event handler returns. If a deferral is taken, the scripts are blocked until the deferral is completed.
</remarks>
<seealso cref="P:Microsoft.Web.WebView2.Core.CoreWebView2Settings.AreDefaultScriptDialogsEnabled"/>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.PermissionRequested">
<summary>
PermissionRequested is raised when content in a WebView requests permission to access some privileged resources.
</summary>
<remarks>
If a deferral is not taken on the event args, the subsequent scripts are blocked until the event handler returns. If a deferral is taken, the scripts are blocked until the deferral is completed.
</remarks>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.ProcessFailed">
<summary>
ProcessFailed is raised when a WebView process ends unexpectedly or becomes unresponsive.
</summary>
<remarks>
<c>ProcessFailed</c> is raised when any of the processes in the <a href="/microsoft-edge/webview2/concepts/process-model?tabs=csharp#processes-in-the-webview2-runtime">WebView2 Process Group</a> encounters one of the following conditions:
<list type="table">
<listheader>
<term>Condition</term>
<description>Details</description>
</listheader>
<item>
<term>Unexpected exit</term>
<description>
The process indicated by the event args has exited unexpectedly (usually due to a crash). The failure might or might not be recoverable, and some failures are auto-recoverable.
</description>
</item>
<item>
<term>Unresponsiveness</term>
<description>
The process indicated by the event args has become unresponsive to user input. This is only reported for renderer processes, and will run every few seconds until the process becomes responsive again.
</description>
</item>
</list>
<b>Note:</b> When the failing process is the browser process, a <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2Environment.BrowserProcessExited"/> event will run too.
Your application can use <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2ProcessFailedEventArgs"/> to identify which condition and process the event is for, and to collect diagnostics and handle recovery if necessary. For more details about which cases need to be handled by your application, see <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2ProcessFailedKind"/>.
</remarks>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="ProcessFailed":::
</example>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebMessageReceived">
<summary>
WebMessageReceived is raised when the <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2Settings.IsWebMessageEnabled"/> setting is set and the top-level document of the WebView runs <c>window.chrome.webview.postMessage</c> or <c>window.chrome.webview.postMessageWithAdditionalObjects</c>.
</summary>
<remarks>
The <c>postMessage</c> function is <c>void postMessage(object)</c> where object is any object supported by JSON conversion.
When <c>postMessage</c> is called, the handler's Invoke method will be called with the <c>object</c> parameter <c>postMessage</c> converted to a JSON string.
If the same page calls <c>postMessage</c> multiple times, the corresponding <c>WebMessageReceived</c> events are guaranteed to be fired in the same order. However, if multiple frames call <c>postMessage</c>, there is no guaranteed order. In addition, <c>WebMessageReceived</c> events caused by calls to <c>postMessage</c> are not guaranteed to be sequenced with events caused by DOM APIs. For example, if the page runs
<code>
chrome.webview.postMessage("message");
window.open();
</code>
then the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NewWindowRequested"/> event might be fired before the <c>WebMessageReceived</c> event. If you need the <c>WebMessageReceived</c> event to happen before anything else, then in the <c>WebMessageReceived</c> handler you can post a message back to the page and have the page wait until it receives that message before continuing.
</remarks>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.NewWindowRequested">
<summary>
NewWindowRequested is raised when content inside the WebView requests to open a new window, such as through <c>window.open()</c>.
</summary>
<remarks>
The app can pass a target WebView that is considered the opened window or mark the event as <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2NewWindowRequestedEventArgs.Handled"/>, in which case WebView2 does not open a window.
If either <c>Handled</c> or <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2NewWindowRequestedEventArgs.NewWindow"/> properties are not set, the target content will be opened on a popup window.
If a deferral is not taken on the event args, scripts that resulted in the new window that are requested are blocked until the event handler returns. If a deferral is taken, then scripts are blocked until the deferral is completed.
On Hololens 2, if the <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2NewWindowRequestedEventArgs.NewWindow"/> property is not set and the <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2NewWindowRequestedEventArgs.Handled"/> property is not set to <c>true</c>, the WebView2 will navigate to the <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2NewWindowRequestedEventArgs.Uri"/>.
If either of these properties are set, the WebView2 will not navigate to the <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2NewWindowRequestedEventArgs.Uri"/> and the the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NewWindowRequested"/> event will continue as normal.
</remarks>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.DocumentTitleChanged">
<summary>
DocumentTitleChanged is raised when the <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.DocumentTitle"/> property changes and may be raised before or after the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationCompleted"/> event.
</summary>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="DocumentTitleChanged":::
</example>
<seealso cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.DocumentTitle"/>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.ContainsFullScreenElementChanged">
<summary>
ContainsFullScreenElementChanged is raised when the <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.ContainsFullScreenElement"/> property changes.
</summary>
<remarks>
An HTML element inside the WebView may enter fullscreen to the size of the WebView or leave fullscreen. This event is useful when, for example, a video element requests to go fullscreen. The listener of this event may resize the WebView in response.
</remarks>
<seealso cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.ContainsFullScreenElement"/>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceRequested">
<summary>
WebResourceRequested is raised when the WebView is performing a URL request to a matching URL and resource context filter that was added with <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddWebResourceRequestedFilter(System.String,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceContext,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceRequestSourceKinds)"/>.
</summary>
<remarks>
At least one filter must be added for the event to be raised.
The web resource requested may be blocked until the event handler returns if a deferral is not taken on the event args. If a deferral is taken, then the web resource requested is blocked until the deferral is completed.
If this event is subscribed in the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NewWindowRequested"/> handler it should be called after the new window is set. For more details see <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2NewWindowRequestedEventArgs.NewWindow"/>.
This event is by default raised for file, http, and https URI schemes. This is also raised for registered custome URI schemes. See <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2CustomSchemeRegistration"/> for more details.
</remarks>
<seealso cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddWebResourceRequestedFilter(System.String,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceContext,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceRequestSourceKinds)"/>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.WindowCloseRequested">
<summary>
WindowCloseRequested is raised when content inside the WebView requested to close the window, such as after <c>window.close()</c> is run.
</summary>
<remarks>
The app should close the WebView and related app window if that makes sense to the app.
After the first window.close() call, this event may not fire for any immediate back to back window.close() calls.
</remarks>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.Navigate(System.String)">
<summary>
Causes a navigation of the top level document to the specified URI.
</summary>
<param name="uri">The URI to navigate to.</param>
<remarks>
For more information, navigate to [Navigation event](/microsoft-edge/webview2/concepts/navigation-events). Note that this operation starts a navigation and the corresponding <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationStarting"/> event is raised sometime after Navigate runs.
</remarks>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="Navigate":::
</example>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationStarting"/>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationCompleted"/>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.NavigateToString(System.String)">
<summary>
Initiates a navigation to <c>htmlContent</c> as source HTML of a new document.
</summary>
<param name="htmlContent">A source HTML of a new document.</param>
<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>
<example>
<code>
webView.CoreWebView2.SetVirtualHostNameToFolderMapping(
"appassets.example", "assets", CoreWebView2HostResourceAccessKind.DenyCors);
string htmlContent =
@"
<head><link rel='stylesheet' href ='http://appassets.example/wv2.css' /></head>
<body>
<img src='http://appassets.example/wv2.png' />
<p><a href='http://appassets.example/winrt_test.txt'> Click me</a></p>
</body>
";
webview.NavigateToString(htmlContent);
</code>
</example>
<seealso cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.SetVirtualHostNameToFolderMapping(System.String,System.String,Microsoft.Web.WebView2.Core.CoreWebView2HostResourceAccessKind)"/>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationStarting"/>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationCompleted"/>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync(System.String)">
<summary>
Adds the provided JavaScript to a list of scripts that should be run after the global object has been created, but before the HTML document has been parsed and before any other script included by the HTML document is run.
</summary>
<param name="javaScript">The JavaScript code to be run.</param>
<returns>A script ID that may be passed when calling <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.RemoveScriptToExecuteOnDocumentCreated(System.String)"/>.</returns>
<remarks>
The injected script will apply to all future top level document and child frame navigations until removed with <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.RemoveScriptToExecuteOnDocumentCreated(System.String)"/>.
This is applied asynchronously and you must wait for the returned <see cref="T:System.Threading.Tasks.Task`1"/> to complete before you can be sure that the script is ready to execute on future navigations.
If the method is run in <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NewWindowRequested"/> handler, it should be called before the new window is set. For more details see <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2NewWindowRequestedEventArgs.NewWindow"/>.
Note that if an HTML document has sandboxing of some kind via [sandbox](https://developer.mozilla.org/docs/Web/HTML/Element/iframe#attr-sandbox) properties or the [Content-Security-Policy HTTP header](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) this will affect the script run here. So, for example, if the <c>allow-modals</c> keyword is not set then calls to the <c>alert</c> function will be ignored.
</remarks>
<seealso cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.RemoveScriptToExecuteOnDocumentCreated(System.String)"/>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.RemoveScriptToExecuteOnDocumentCreated(System.String)">
<summary>
Removes the corresponding JavaScript added via <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync(System.String)"/> with the specified script ID.
</summary>
<param name="id">The ID corresponds to the JavaScript code to be removed from the list of scripts.</param>
Both use <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync(System.String)"/> and this method in <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NewWindowRequested"/> handler at the same time sometimes causes trouble. Since invalid scripts will be ignored, the script IDs you got may not be valid anymore.
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.ExecuteScriptAsync(System.String)">
<summary>
Runs JavaScript code from the <c>javaScript</c> parameter in the current top-level document rendered in the WebView.
</summary>
<param name="javaScript">The JavaScript code to be run in the current top-level document rendered in the WebView.</param>
<returns>A JSON encoded string that represents the result of running the provided JavaScript.</returns>
<remarks>
If the result is <c>undefined</c>, contains a reference cycle, or otherwise is not able to be encoded into JSON, the JSON <c>null</c> value is returned as the <c>"null"</c> string.
A function that has no explicit return value returns <c>undefined</c>. If the script that was run throws an unhandled exception, then the result is also <c>null</c>. This method is applied asynchronously. If the method is run after the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationStarting"/> event during a navigation, the script runs in the new document when loading it, around the time <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.ContentLoading"/> is run. This operation works even if <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2Settings.IsScriptEnabled"/> is set to <c>false</c>.
</remarks>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="ExecuteScript":::
</example>
<seealso cref="P:Microsoft.Web.WebView2.Core.CoreWebView2Settings.IsScriptEnabled"/>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.CapturePreviewAsync(Microsoft.Web.WebView2.Core.CoreWebView2CapturePreviewImageFormat,System.IO.Stream)">
<summary>
Captures an image of what WebView is displaying.
</summary>
<param name="imageFormat">The format of the image to be captured.</param>
<param name="imageStream">The stream to which the resulting image binary data is written.</param>
<remarks>
When CapturePreviewAsync finishes writing to the stream, the Invoke method on the provided handler parameter is called. This method fails if called before the first <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.ContentLoading"/> event. For example if this is called in the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NavigationStarting"/> event for the first navigation it will fail. For subsequent navigations, the method may not fail, but will not capture an image of a given webpage until the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.ContentLoading"/> event has been fired for it. Any call to this method prior to that will result in a capture of the page being navigated away from.
</remarks>
<seealso cref="T:Microsoft.Web.WebView2.Core.CoreWebView2CapturePreviewImageFormat"/>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.Reload">
<summary>
Reloads the current page.
</summary>
<remarks>
This is similar to navigating to the URI of current top level document including all navigation events firing and respecting any entries in the HTTP cache. But, the back or forward history will not be modified.
</remarks>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.PostWebMessageAsJson(System.String)">
<summary>
Posts the specified <c>webMessageAsJson</c> to the top level document in this WebView.
</summary>
<param name="webMessageAsJson">The web message to be posted to the top level document in this WebView.</param>
<remarks>
The event args is an instance of <c>MessageEvent</c>. The <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2Settings.IsWebMessageEnabled"/> setting must be <c>true</c> or the message will not be sent. The event arg's <c>data</c> property of the event arg is the <c>webMessageAsJson</c> string parameter parsed as a JSON string into a JavaScript object. The event arg's <c>source</c> property of the event arg is a reference to the <c>window.chrome.webview</c> object. For information about sending messages from the HTML document in the WebView to the host, navigate to <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebMessageReceived"/>. The message is sent asynchronously. If a navigation occurs before the message is posted to the page, the message is not be sent.
</remarks>
<example>
Runs the message event of the <c>window.chrome.webview</c> of the top-level document. JavaScript in that document may subscribe and unsubscribe to the event using the following code:
<code>
window.chrome.webview.addEventListener('message', handler)
window.chrome.webview.removeEventListener('message', handler)
</code>
</example>
<seealso cref="P:Microsoft.Web.WebView2.Core.CoreWebView2Settings.IsWebMessageEnabled"/>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebMessageReceived"/>
<seealso cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.PostWebMessageAsString(System.String)"/>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.PostWebMessageAsString(System.String)">
<summary>
Posts a message that is a simple string rather than a JSON string representation of a JavaScript object.
</summary>
<param name="webMessageAsString">The web message to be posted to the top level document in this WebView.</param>
<remarks>
This behaves in exactly the same manner as <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.PostWebMessageAsJson(System.String)"/>, but the <c>data</c> property of the event arg of the <c>window.chrome.webview</c> message is a string with the same value as <c>webMessageAsString</c>. Use this instead of <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.PostWebMessageAsJson(System.String)"/> if you want to communicate using simple strings rather than JSON objects.
</remarks>
<seealso cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebMessageReceived"/>
<seealso cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.PostWebMessageAsJson(System.String)"/>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.CallDevToolsProtocolMethodAsync(System.String,System.String)">
<summary>
Runs an asynchronous DevToolsProtocol method.
</summary>
<param name="methodName">The full name of the method in the format <c>{domain}.{method}</c>.</param>
<param name="parametersAsJson">A JSON formatted string containing the parameters for the corresponding method.</param>
<returns>A JSON string that represents the method's return object.</returns>
<remarks>
For more information about available methods, navigate to [DevTools Protocol Viewer](https://aka.ms/DevToolsProtocolDocs). The returned task is completed when the method asynchronously completes and will return the method's return object as a JSON string. Note even though WebView2 dispatches the CDP messages in the order called, CDP method calls may be processed out of order. If you require CDP methods to run in a particular order, you should await for the previous method call.
If the method is to run in <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.NewWindowRequested"/> handler it should be called
before the new window is set if the cdp messages should affect the initial navigation. If
called after setting the NewWindow property, the cdp messages
may or may not apply to the initial navigation and may only apply to the subsequent navigation.
For more details <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2NewWindowRequestedEventArgs.NewWindow"/>.
</remarks>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.GoBack">
<summary>
Navigates the WebView to the previous page in the navigation history.
</summary>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.GoForward">
<summary>
Navigates the WebView to the next page in the navigation history.
</summary>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.GetDevToolsProtocolEventReceiver(System.String)">
<summary>
Gets a DevTools Protocol event receiver that allows you to subscribe to a DevToolsProtocol event.
</summary>
<param name="eventName">The full name of the event in the format <c>{domain}.{event}</c>.</param>
<returns>A Devtools Protocol event receiver.</returns>
<remarks>
For more information about DevToolsProtocol events description and event args, navigate to [DevTools Protocol Viewer](https://aka.ms/DevToolsProtocolDocs).
</remarks>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.Stop">
<summary>
Stops all navigations and pending resource fetches.
</summary>
<remarks>
Does not stop scripts.
</remarks>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddHostObjectToScript(System.String,System.Object)">
<summary>
Adds the provided host object to script running in the WebView with the specified name.
</summary>
<param name="name">The name of the host object.</param>
<param name="rawObject">The host object to be added to script.</param>
<remarks>
Host objects are exposed as host object proxies via <c>window.chrome.webview.hostObjects.{name}</c>. Host object proxies are promises and will resolve to an object representing the host object. Only the COM visible objects/properties/methods can be accessed from script.
The app can control which part of .NET objects are exposed using <see cref="T:System.Runtime.InteropServices.ComVisibleAttribute"/>.
JavaScript code in the WebView will be able to access appObject as following and then access attributes and methods of appObject.
Note that while simple types, <c>IDispatch</c> and array are supported, and <c>IUnknown</c> objects that also implement <c>IDispatch</c> are treated as <c>IDispatch</c>, generic <c>IUnknown</c>, <c>VT_DECIMAL</c>, or <c>VT_RECORD</c> variant is not supported. Remote JavaScript objects like callback functions are represented as an <c>VT_DISPATCH</c> VARIANT with the object implementing <c>IDispatch</c>. The JavaScript callback method may be invoked using DISPID_VALUE for the DISPID. Such callback method invocations will return immediately and will not wait for the JavaScript function to run and so will not provide the return value of the JavaScript function. Nested arrays are supported up to a depth of 3. Arrays of by reference types are not supported. <c>VT_EMPTY</c> and <c>VT_NULL</c> are mapped into JavaScript as <c>null</c>. In JavaScript <c>null</c> and <c>undefined</c> are mapped to <c>VT_EMPTY</c>.
Additionally, all host objects are exposed as <c>window.chrome.webview.hostObjects.sync.{name}</c>. Here the host objects are exposed as synchronous host object proxies. These are not promises and calls to functions or property access synchronously block running script waiting to communicate cross process for the host code to run. Accordingly this can result in reliability issues and it is recommended that you use the promise based asynchronous <c>window.chrome.webview.hostObjects.{name}</c> API described above.
Synchronous host object proxies and asynchronous host object proxies can both proxy the same host object. Remote changes made by one proxy will be reflected in any other proxy of that same host object whether the other proxies and synchronous or asynchronous.
While JavaScript is blocked on a synchronous call to native code, that native code is unable to call back to JavaScript. Attempts to do so will fail with <c>HRESULT_FROM_WIN32(ERROR_POSSIBLE_DEADLOCK)</c>.
Host object proxies are JavaScript Proxy objects that intercept all property get, property set, and method invocations. Properties or methods that are a part of the Function or Object prototype are run locally. Additionally any property or method in the array <c>chrome.webview.hostObjects.options.forceLocalProperties</c> will also be run locally. This defaults to including optional methods that have meaning in JavaScript like <c>toJSON</c> and <c>Symbol.toPrimitive</c>. You can add more to this array as required.
There's a method <c>chrome.webview.hostObjects.cleanupSome</c> that will best effort garbage collect host object proxies.
The <c>chrome.webview.hostObjects.options</c> object provides the ability to change some functionality of host objects.
<list type="table">
<listheader>
<term>Options property</term>
<description>Details</description>
</listheader>
<item>
<term><c>forceLocalProperties</c></term>
<description>
This is an array of host object property names that will be run locally, instead of being called on the native host object. This defaults to <c>then</c>, <c>toJSON</c>, <c>Symbol.toString</c>, and <c>Symbol.toPrimitive</c>. You can add other properties to specify that they should be run locally on the JavaScript host object proxy.
</description>
</item>
<item>
<term><c>log</c></term>
<description>
This is a callback that will be called with debug information. For example, you can set this to <c>console.log.bind(console)</c> to have it print debug information to the console to help when troubleshooting host object usage. By default this is null.
</description>
</item>
<item>
<term><c>shouldSerializeDates</c></term>
<description>
By default this is false, and JavaScript Date objects will be sent to host objects as a string using <c>JSON.stringify</c>. You can set this property to true to have Date objects properly serialize as a <c>System.DateTime</c> when sending to the .NET host object, and have <c>System.DateTime</c> properties and return values create a JavaScript <c>Date</c> object.
</description>
</item>
<item>
<term><c>defaultSyncProxy</c></term>
<description>
When calling a method on a synchronous proxy, the result should also be a synchronous proxy. But in some cases, the sync/async context is lost (for example, when providing to native code a reference to a function, and then calling that function in native code). In these cases, the proxy will be asynchronous, unless this property is set.
</description>
</item>
<item>
<term><c>forceAsyncMethodMatches</c></term>
<description>
This is an array of regular expressions. When calling a method on a synchronous proxy, the method call will be performed asynchronously if the method name matches a string or regular expression in this array. Setting this value to <c>Async</c> will make any method that ends with Async be an asynchronous method call. If an async method doesn't match here and isn't forced to be asynchronous, the method will be invoked synchronously, blocking execution of the calling JavaScript and then returning the resolution of the promise, rather than returning a promise.
</description>
</item>
<item>
<term><c>ignoreMemberNotFoundError</c></term>
<description>
By default, an exception is thrown when attempting to get the value of a proxy property that doesn't exist on the corresponding native class. Setting this property to <c>true</c> switches the behavior to match Chakra WinRT projection (and general JavaScript) behavior of returning <c>undefined</c> with no error.
</description>
</item>
<item>
<term><c>shouldPassTypedArraysAsArrays</c></term>
<description>
By default, typed arrays are passed to the host as <c>IDispatch</c>. To instead pass typed arrays to the host as <c>array</c>, set this to <c>true</c>.
</description>
</item>
</list>
Host object proxies additionally have the following methods:
<list type="table">
<listheader>
<term>Method name</term>
<description>Details</description>
</listheader>
<item>
<term><c>applyHostFunction</c>, <c>getHostProperty</c>, <c>setHostProperty</c></term>
<description>
Perform a method invocation, property get, or property set on the host object. You can use these to explicitly force a method or property to run remotely if there is a conflicting local method or property. For instance, <c>proxy.toString()</c> will run the local <c>toString</c> method on the proxy object. But <c>proxy.applyHostFunction('toString')</c> runs <c>toString</c> on the host proxied object instead.
</description>
</item>
<item>
<term><c>getLocalProperty</c>, <c>setLocalProperty</c></term>
<description>
Perform property get, or property set locally. You can use these methods to force getting or setting a property on the host object proxy itself rather than on the host object it represents. For instance, <c>proxy.unknownProperty</c> will get the property named <c>unknownProperty</c> from the host proxied object. But <c>proxy.getLocalProperty('unknownProperty')</c> will get the value of the property <c>unknownProperty</c> on the proxy object itself.
</description>
</item>
<item>
<term><c>addEventListener</c></term>
<description>
This method only exists on proxies for .NET objects. Bind the JavaScript handler to the C# event, so that the JavaScript handler can be called through the C# event. For example, <c>chrome.webview.hostObjects.sample.addEventListener('TestEvent', () => { alert('Invoked from remote');});</c> bind an anonymous JavaScript function to a C# event called 'TestEvent'. When calling <c>TestEvent?.Invoke()</c> on C# side, the JavaScript function that was just bound will be called asynchronously. It allows adding more than one handler for an event, but if the handler is already in the list of event handler, it will not be added a second time. If the host object cannot find the event with the name passed in by the <c>addEventListener</c> function or it is no public or its return type is not void, an exception will be thrown. If the count and type of C# event's parameters do not match the count and type of JavaScript handler, invoke <c>addEventListener</c> will be successful but an exception will be passed to JavaScript when invoke the event on C# side. If the host object has defined <c>addEventListener</c> function, use the defined function rather than the additionally <c>addEventListener</c> function.
</description>
</item>
<item>
<term><c>removeEventListener</c></term>
<description>
This method only exists on proxies for .NET objects. Removes a handler previously bound with <c>addEventListener()</c>. If the handler does not exist in the list of event handler, nothing will happen. If the host object cannot find the event with the name passed in by the <c>removeEventListener</c> function or it is no public, an exception will be thrown. If the host object has defined <c>removeEventListener</c> function, use the defined function rather than the additionally <c>removeEventListener</c> function.
</description>
</item>
<item>
<term><c>sync</c></term>
<description>
Asynchronous host object proxies expose a sync method which returns a promise for a synchronous host object proxy for the same host object. For example, <c>chrome.webview.hostObjects.sample.methodCall()</c> returns an asynchronous host object proxy. You can use the <c>sync</c> method to obtain a synchronous host object proxy instead:
<c>const syncProxy = await chrome.webview.hostObjects.sample.methodCall().sync()</c>
</description>
</item>
<item>
<term><c>async</c></term>
<description>
Synchronous host object proxies expose an async method which blocks and returns an asynchronous host object proxy for the same host object. For example, <c>chrome.webview.hostObjects.sync.sample.methodCall()</c> returns a synchronous host object proxy. Calling the <c>async</c> method on this blocks and then returns an asynchronous host object proxy for the same host object: <c>const asyncProxy = chrome.webview.hostObjects.sync.sample.methodCall().async()</c>
</description>
</item>
<item>
<term><c>then</c></term>
<description>
Asynchronous host object proxies have a then method. This allows them to be awaitable. <c>then</c> will return a promise that resolves with a representation of the host object. If the proxy represents a JavaScript literal then a copy of that is returned locally. If the proxy represents a function then a non-awaitable proxy is returned. If the proxy represents a JavaScript object with a mix of literal properties and function properties, then the a copy of the object is returned with some properties as host object proxies.
</description>
</item>
<item>
<term><c>cancelPromise</c></term>
<description>
This method attempts to cancel the fulfillment of a promised value. If the promise hasn't already been fulfilled and cancelation is supported, the promise will get rejected. <c>cancelPromise</c> supports cancelation of IAsyncOperation and IAsyncAction methods. If the promise is successfully canceled, then calling await on the promise will throw. For example, <c>chrome.webview.hostObjects.cancelPromise(promise); await promise;</c> will throw with "Promise Canceled". Once a promise has been canceled, a subsequent cancel on the same promise will throw an exception as well.
</description>
</item>
</list>
All other property and method invocations (other than the above Remote object proxy methods, <c>forceLocalProperties</c> list, and properties on Function and Object prototypes) are run remotely. Asynchronous host object proxies return a promise representing asynchronous completion of remotely invoking the method, or getting the property. The promise resolves after the remote operations complete and the promises resolve to the resulting value of the operation. Synchronous host object proxies work similarly but block JavaScript execution and wait for the remote operation to complete.
Setting a property on an asynchronous host object proxy works slightly differently. The set returns immediately and the return value is the value that will be set. This is a requirement of the JavaScript Proxy object. If you need to asynchronously wait for the property set to complete, use the <c>setHostProperty</c> method which returns a promise as described above. Synchronous object property set property synchronously blocks until the property is set.
Exposing host objects to script has security risk. Please follow [best practices](/microsoft-edge/webview2/concepts/security).
</remarks>
<example>
To create a [IDispatch](/windows/win32/api/oaidl/nn-oaidl-idispatch) implementing class in C# use the following attributes on each class you intend to expose.
<code>
// Bridge and BridgeAnotherClass are C# classes that implement IDispatch and works with AddHostObjectToScript.
[ClassInterface(ClassInterfaceType.AutoDual)]
[ComVisible(true)]
public class BridgeAnotherClass
{
// Sample property.
public string Prop { get; set; } = "Example";
}
[ClassInterface(ClassInterfaceType.AutoDual)]
[ComVisible(true)]
public class Bridge
{
public string Func(string param)
{
return "Example: " + param;
}
public BridgeAnotherClass AnotherObject { get; set; } = new BridgeAnotherClass();
// Sample indexed property.
[System.Runtime.CompilerServices.IndexerName("Items")]
public string this[int index]
{
get { return m_dictionary[index]; }
set { m_dictionary[index] = value; }
}
private Dictionary<int, string> m_dictionary = new Dictionary<int, string>();
}
</code>
Then add instances of those classes via <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddHostObjectToScript(System.String,System.Object)"/>:
<code>
webView.CoreWebView2.AddHostObjectToScript("bridge", new Bridge());
</code>
And then in script you can call the methods, and access those properties of the objects added via <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddHostObjectToScript(System.String,System.Object)"/>.
Note that `CoreWebView2.AddHostObjectToScript` only applies to the top-level document and not to frames. To add host objects to frames use `CoreWebView2Frame.AddHostObjectToScript`.
<code>
// Find added objects on the hostObjects property
const bridge = chrome.webview.hostObjects.bridge;
// Call a method and pass in a parameter.
// The result is another proxy promise so you must await to get the result.
console.log(await bridge.Func("testing..."));
// A property may be another object as long as its class also implements
// IDispatch.
// Getting a property also gets a proxy promise you must await.
const propValue = await bridge.AnotherObject.Prop;
console.log(propValue);
// Indexed properties
let index = 123;
bridge[index] = "test";
let result = await bridge[index];
console.log(result);
</code>
</example>
<seealso cref="T:System.Runtime.InteropServices.ComVisibleAttribute"/>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.RemoveHostObjectFromScript(System.String)">
<summary>
Removes the host object specified by the name so that it is no longer accessible from JavaScript code in the WebView.
</summary>
<param name="name">The name of the host object to be removed.</param>
<remarks>
While new access attempts are denied, if the object is already obtained by JavaScript code in the WebView, the JavaScript code continues to have access to that object. Running this method for a name that is already removed or never added fails.
</remarks>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.OpenDevToolsWindow">
<summary>
Opens the DevTools window for the current document in the WebView.
</summary>
<remarks>
Does nothing if run when the DevTools window is already open.
</remarks>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddWebResourceRequestedFilter(System.String,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceContext)">
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.RemoveWebResourceRequestedFilter(System.String,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceContext)">
<summary>
Warning: This method and <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddWebResourceRequestedFilter(System.String,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceContext)"/> are deprecated.
</summary>
Removes a matching WebResource filter that was previously added for the <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceRequested"/> event.
<param name="uri">An URI to at which a web resource filter was added.</param>
<param name="ResourceContext">A previously added resource context filter to be removed.</param>
<exception cref="T:System.ArgumentException">A filter that was never added.</exception>
<remarks>
If the same filter was added multiple times, then it must need to be removed as many times as it was added for the removal to be effective.
</remarks>
<seealso cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.AddWebResourceRequestedFilter(System.String,Microsoft.Web.WebView2.Core.CoreWebView2WebResourceContext)"/>
</member>
<member name="P:Microsoft.Web.WebView2.Core.CoreWebView2.CookieManager">
<summary>
Gets the <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2CookieManager"/> object associated with this <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2"/>.
</summary>
<seealso cref="T:Microsoft.Web.WebView2.Core.CoreWebView2CookieManager"/>
</member>
<member name="P:Microsoft.Web.WebView2.Core.CoreWebView2.Environment">
<summary>
Exposes the <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2Environment"/> used to create this <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2"/>.
</summary>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceResponseReceived">
<summary>
WebResourceResponseReceived is raised when the WebView receives the response for a request for a web resource (any URI resolution performed by the WebView; such as HTTP/HTTPS, file and data requests from redirects, navigations, declarations in HTML, implicit Favicon lookups, and fetch API usage in the document).
</summary>
<remarks>
The host app can use this event to view the actual request and response for a web resource. There is no guarantee about the order in which the WebView processes the response and the host app's handler runs. The app's handler will not block the WebView from processing the response.
The event args include the <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2WebResourceRequest"/> as sent by the wire and <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2WebResourceResponse"/> received, including any additional headers added by the network stack that were not be included as part of the associated <see cref="E:Microsoft.Web.WebView2.Core.CoreWebView2.WebResourceRequested"/> event, such as Authentication headers.
</remarks>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="WebResourceResponseReceived":::
</example>
</member>
<member name="E:Microsoft.Web.WebView2.Core.CoreWebView2.DOMContentLoaded">
<summary>
DOMContentLoaded is raised when the initial HTML document has been parsed.
</summary>
<remarks>
This aligns with the the document's DOMContentLoaded event in HTML.
</remarks>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="DOMContentLoaded":::
</example>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.NavigateWithWebResourceRequest(Microsoft.Web.WebView2.Core.CoreWebView2WebResourceRequest)">
<summary>
Navigates using a constructed <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2WebResourceRequest"/> object.
</summary>
<param name="Request">The constructed web resource object to provide post data or additional request headers during navigation.</param>
<remarks>
The headers in the <see cref="T:Microsoft.Web.WebView2.Core.CoreWebView2WebResourceRequest"/> override headers added by WebView2 runtime except for Cookie headers. Method can only be either <c>GET</c> or <c>POST</c>. Provided post data will only be sent only if the method is <c>POST</c> and the uri scheme is <c>HTTP(S)</c>.
</remarks>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="NavigateWithWebResourceRequest":::
</example>
</member>
<member name="P:Microsoft.Web.WebView2.Core.CoreWebView2.IsSuspended">
<summary>
Whether WebView is suspended.
</summary>
<remarks>
True when WebView is suspended, from the time when <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.TrySuspendAsync"/> has completed successfully until WebView is resumed.
</remarks>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.TrySuspendAsync">
<summary>
An app may call this API to have the WebView2 consume less memory.
</summary>
<remarks>
This is useful when a Win32 app becomes invisible, or when a Universal Windows Platform app is being suspended, during the suspended event handler before completing the suspended event.
The <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2Controller.IsVisible"/> property must be false when the API is called. Otherwise, the API throws COMException with error code of <c>HRESULT_FROM_WIN32(ERROR_INVALID_STATE)</c>.
Suspending is similar to putting a tab to sleep in the Edge browser. Suspending pauses WebView script timers and animations, minimizes CPU usage for the associated browser renderer process and allows the operating system to reuse the memory that was used by the renderer process for other processes.
Note that Suspend is best effort and considered completed successfully once the request is sent to browser renderer process. If there is a running script, the script will continue to run and the renderer process will be suspended after that script is done.
See [Sleeping Tabs FAQ](https://techcommunity.microsoft.com/t5/articles/sleeping-tabs-faq/m-p/1705434) for conditions that might prevent WebView from being suspended. In those situations, the result of the async task is false.
The WebView will be automatically resumed when it becomes visible. Therefore, the app normally does not have to call <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.Resume"/> explicitly.
The app can call <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.Resume"/> and then <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.TrySuspendAsync"/> periodically for an invisible WebView so that the invisible WebView can sync up with latest data and the page ready to show fresh content when it becomes visible.
All WebView APIs can still be accessed when a WebView is suspended. Some APIs like Navigate will auto resume the WebView. To avoid unexpected auto resume, check <see cref="P:Microsoft.Web.WebView2.Core.CoreWebView2.IsSuspended"/> property before calling APIs that might change WebView state.
</remarks>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="TrySuspend":::
</example>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.Resume">
<summary>
Resumes the WebView so that it resumes activities on the web page.
</summary>
<remarks>
This API can be called while the WebView2 controller is invisible.
The app can interact with the WebView immediately after <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.Resume"/>.
WebView will be automatically resumed when it becomes visible.
</remarks>
<example>
:::code language="csharp" source="../code/sample/SampleApps/WebView2WpfBrowser/MainWindow.xaml.cs" id="Resume":::
</example>
</member>
<member name="M:Microsoft.Web.WebView2.Core.CoreWebView2.SetVirtualHostNameToFolderMapping(System.String,System.String,Microsoft.Web.WebView2.Core.CoreWebView2HostResourceAccessKind)">
<summary>
Sets a mapping between a virtual host name and a folder path to make available to web sites via that host name.
</summary>
<param name="hostName">A virtual host name.</param>
<param name="folderPath">A folder path name to be mapped to the virtual host name. The length must not exceed the Windows MAX_PATH limit.</param>
<param name="accessKind">The level of access to resources under the virtual host from other sites.</param>
<remarks>
<para>
After setting the mapping, documents loaded in the WebView can use HTTP or HTTPS URLs at the specified host name specified by <c>hostName</c> to access files in the local folder specified by <c>folderPath</c>.
This mapping applies to both top-level document and iframe navigations as well as subresource references from a document. This also applies to dedicated and shared worker scripts but does not apply to service worker scripts.
Due to a current implementation limitation, media files accessed using virtual host name can be very slow to load.
As the resource loaders for the current page might have already been created and running, changes to the mapping might not be applied to the current page and a reload of the page is needed to apply the new mapping.
Both absolute and relative paths are supported for <c>folderPath</c>. Relative paths are interpreted as relative to the folder where the exe of the app is in.
</para>
<para>
For example, after calling <c>SetVirtualHostNameToFolderMapping("appassets.example", "assets", CoreWebView2HostResourceAccessKind.Deny);</c>, navigating to <c>https://appassets.example/my-local-file.html</c> will show content from my-local-file.html in the assets subfolder located on disk under the same path as the app's executable file.
DOM elements that want to reference local files will have their host reference virtual host in the source. If there are multiple folders being used, define one unique virtual host per folder.
</para>
<para>
You should typically choose virtual host names that are never used by real sites.
If you own a domain such as <c>example.com</c>, another option is to use a subdomain reserved for the app (like <c>my-app.example.com</c>).
</para>
<para>
[RFC 6761](https://tools.ietf.org/html/rfc6761) has reserved several special-use domain names that are guaranteed to not be used by real sites (for example, <c>.example</c>, <c>.test</c>, and <c>.invalid</c>).
</para>
<para>
Note that using <c>.local</c> as the top-level domain name will work but can cause a delay during navigations. You should avoid using <c>.local</c> if you can.
</para>
<para>
Apps should use distinct domain names when mapping folder from different sources that should be isolated from each other. For instance, the app might use app-file.example for files that ship as part of the app, and book1.example might be used for files containing books from a less trusted source that were previously downloaded and saved to the disk by the app.
</para>
<para>
The host name used in the APIs is canonicalized using Chromium's host name parsing logic before being used internally.
For more information see [HTML5 2.6 URLs](https://dev.w3.org/html5/spec-LC/urls.html).
</para>
<para>
All host names that are canonicalized to the same string are considered identical.
For example, <c>EXAMPLE.COM</c> and <c>example.com</c> are treated as the same host name.
An international host name and its Punycode-encoded host name are considered the same host name. There is no DNS resolution for host name and the trailing '.' is not normalized as part of canonicalization.
</para>
<para>
Therefore <c>example.com</c> and <c>example.com.</c> are treated as different host names. Similarly, <c>virtual-host-name</c> and <c>virtual-host-name.example.com</c> are treated as different host names even if the machine has a DNS suffix of <c>example.com</c>.
</para>
<para>
Specify the minimal cross-origin access necessary to run the app. If there is not a need to access local resources from other origins, use <see cref="F:Microsoft.Web.WebView2.Core.CoreWebView2HostResourceAccessKind.Deny"/>.
</para>
</remarks>
<example>
<code>
webView.CoreWebView2.SetVirtualHostNameToFolderMapping(
"appassets.example", "assets", CoreWebView2HostResourceAccessKind.DenyCors);
webView.Source = new Uri("https://appassets.example/index.html");
</code>
This in an example on how to embed a local image. For more information see <see cref="M:Microsoft.Web.WebView2.Core.CoreWebView2.NavigateToString(System.String)"/>.
<code>
webView.CoreWebView2.SetVirtualHostNameToFolderMapping(
"appassets.example", "assets", CoreWebView2HostResourceAccessKind.DenyCors);