Skip to content

Commit 683ea41

Browse files
Chetan PandeyCopilot
andcommitted
Address review feedback: prose fixes, code sample improvements, and convention alignment
- Fix grammar: 'An empty JSON' -> 'An empty JSON object' (2x) - Clarify ambiguity: 'mixed-content blocks' -> 'mixed-content blocked requests' - Use prescriptive language: 'should match' -> 'must match' in API contract - Add missing 'that' in relative clause + imperative voice for CoTaskMemFree - Remove markdown bold (**any**) from IDL comments (plain text only) - Add missing comma after introductory phrase 'On failure' - Split run-on sentence in event handler comment - Add missing comma before 'but' in compound sentence - Remove 'NetworkContext' reference from profile scope comment - C++ destructor: unsubscribe before Reset() for proper cleanup order - C# Dispose: unsubscribe before Dispose() for proper cleanup order - Add _environment field declaration in filtered C# sample - Name opaque error codes: ERR_NAME_NOT_RESOLVED (-105), ERR_TIMED_OUT (-7) - Align section headers: 'COM' -> 'Win32 C++', '.NET C#' -> '.NET, WinRT' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent eea022d commit 683ea41

1 file changed

Lines changed: 37 additions & 24 deletions

File tree

specs/DiagnosticMonitor.md

Lines changed: 37 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -79,9 +79,14 @@ DiagnosticComponent::DiagnosticComponent(
7979

8080
DiagnosticComponent::~DiagnosticComponent()
8181
{
82-
// Releasing the monitor automatically stops all
83-
// events and clears filters.
84-
m_monitor.Reset();
82+
if (m_monitor)
83+
{
84+
// Unsubscribe before releasing the monitor to
85+
// ensure no callbacks arrive during teardown.
86+
m_monitor->remove_DiagnosticReceived(
87+
m_diagnosticToken);
88+
m_monitor.Reset();
89+
}
8590
}
8691

8792
void DiagnosticComponent::SetupDiagnostics()
@@ -139,7 +144,7 @@ void DiagnosticComponent::HandleDiagnosticEvent(
139144
}
140145
```
141146
142-
### .NET C#
147+
### .NET, WinRT
143148
144149
```c#
145150
using Microsoft.Web.WebView2.Core;
@@ -188,18 +193,23 @@ public class DiagnosticComponent : IDisposable
188193
189194
public void Dispose()
190195
{
191-
// Disposing the monitor stops all events and
192-
// clears filters automatically.
193-
_monitor?.Dispose();
196+
if (_monitor != null)
197+
{
198+
// Unsubscribe before disposing the monitor.
199+
_monitor.DiagnosticReceived -=
200+
OnDiagnosticReceived;
201+
_monitor.Dispose();
202+
_monitor = null;
203+
}
194204
}
195205
}
196206
```
197207

198208
## Filter with field-level JSON criteria
199209

200210
You can pass a JSON object to `AddDiagnosticReceivedFilter` to
201-
restrict which events are delivered. An empty JSON `"{}"` receives
202-
all events in that category. A non-empty JSON applies field-level
211+
restrict which events are delivered. An empty JSON object `"{}"` receives
212+
all events in that category. A non-empty JSON object applies field-level
203213
matching. Calling the method again for the same category replaces
204214
the previous filter.
205215

@@ -211,7 +221,8 @@ void DiagnosticComponent::SetupFilteredDiagnostics()
211221
CHECK_FAILURE(
212222
m_environment->CreateDiagnosticMonitor(&m_monitor));
213223

214-
// Only receive DNS and timeout errors (-105, -7)
224+
// Only receive DNS (ERR_NAME_NOT_RESOLVED, -105)
225+
// and timeout (ERR_TIMED_OUT, -7) errors
215226
// for GET/POST requests from the "Default" profile.
216227
CHECK_FAILURE(
217228
m_monitor->AddDiagnosticReceivedFilter(
@@ -238,14 +249,17 @@ void DiagnosticComponent::SetupFilteredDiagnostics()
238249
}
239250
```
240251

241-
### .NET C#
252+
### .NET, WinRT
242253

243254
```c#
255+
private CoreWebView2Environment _environment;
256+
244257
private void SetupFilteredDiagnostics()
245258
{
246259
_monitor = _environment.CreateDiagnosticMonitor();
247260

248-
// Only DNS and timeout errors for GET/POST requests
261+
// Only DNS (ERR_NAME_NOT_RESOLVED, -105) and timeout
262+
// (ERR_TIMED_OUT, -7) errors for GET/POST requests
249263
// from the "Default" profile.
250264
_monitor.AddDiagnosticReceivedFilter(
251265
CoreWebView2DiagnosticCategory.NetworkError,
@@ -263,7 +277,7 @@ private void SetupFilteredDiagnostics()
263277

264278
# API Details
265279

266-
## COM
280+
## Win32 C++
267281

268282
```idl
269283
/// Specifies the category of diagnostic event.
@@ -272,7 +286,7 @@ typedef enum COREWEBVIEW2_DIAGNOSTIC_CATEGORY {
272286
/// Network request failure including DNS resolution
273287
/// errors, TLS handshake failures, connection timeouts,
274288
/// HTTP error status codes (4xx/5xx), CORS violations,
275-
/// and mixed-content blocks.
289+
/// and mixed-content blocked requests.
276290
COREWEBVIEW2_DIAGNOSTIC_CATEGORY_NETWORK_ERROR,
277291
} COREWEBVIEW2_DIAGNOSTIC_CATEGORY;
278292
@@ -319,7 +333,7 @@ interface ICoreWebView2DiagnosticEventArgs : IUnknown {
319333
/// Returns category-specific diagnostic data as a JSON
320334
/// string for the specified category.
321335
///
322-
/// The `category` parameter should match the value
336+
/// The `category` parameter must match the value
323337
/// returned by `get_Category`. If a different category
324338
/// is passed, the method returns `"{}"`.
325339
///
@@ -345,11 +359,10 @@ interface ICoreWebView2DiagnosticEventArgs : IUnknown {
345359
/// `protocol` is the protocol scheme (e.g. "https").
346360
/// `uri` is the request URI.
347361
///
348-
/// For categories the runtime does not yet populate,
362+
/// For categories that the runtime does not yet populate,
349363
/// this method returns `"{}"`.
350364
///
351-
/// The caller must free the returned string with
352-
/// `CoTaskMemFree`.
365+
/// Free the returned string with `CoTaskMemFree`.
353366
HRESULT GetCategoryDetailsAsJson(
354367
[in] COREWEBVIEW2_DIAGNOSTIC_CATEGORY category,
355368
[out, retval] LPWSTR* value);
@@ -410,7 +423,7 @@ interface ICoreWebView2DiagnosticMonitor : IUnknown {
410423
/// `profileName` is a single string that must match
411424
/// the profile name exactly. All other fields are
412425
/// arrays of accepted values. An event passes if it
413-
/// matches **any** value in each specified field
426+
/// matches any value in each specified field
414427
/// (OR within a field, AND across fields). String
415428
/// fields in `uriPattern` support wildcard patterns
416429
/// using `*` and `?`.
@@ -419,7 +432,7 @@ interface ICoreWebView2DiagnosticMonitor : IUnknown {
419432
/// replaces the previous filter for that category.
420433
///
421434
/// Returns `E_INVALIDARG` if the JSON is malformed.
422-
/// On failure the filter state is unchanged.
435+
/// On failure, the filter state is unchanged.
423436
HRESULT AddDiagnosticReceivedFilter(
424437
[in] COREWEBVIEW2_DIAGNOSTIC_CATEGORY category,
425438
[in] LPCWSTR jsonFilter);
@@ -435,8 +448,8 @@ interface ICoreWebView2DiagnosticMonitor : IUnknown {
435448
436449
/// Subscribes to diagnostic events on this monitor.
437450
/// The handler is invoked on the thread that created
438-
/// the environment every time a diagnostic signal
439-
/// passes a filter added with
451+
/// the environment. It fires every time a diagnostic
452+
/// signal passes a filter added with
440453
/// `AddDiagnosticReceivedFilter`.
441454
///
442455
/// Multiple handlers can be registered. They are
@@ -465,7 +478,7 @@ interface ICoreWebView2Environment17
465478
/// consumers such as a telemetry pipeline and a debug
466479
/// panel to operate without interfering with each other.
467480
///
468-
/// The monitor is active immediately but no events fire
481+
/// The monitor is active immediately, but no events fire
469482
/// until a filter is added via
470483
/// `AddDiagnosticReceivedFilter`.
471484
///
@@ -497,7 +510,7 @@ namespace Microsoft.Web.WebView2.Core
497510
/// Signal from a specific WebView instance.
498511
WebView = 0,
499512

500-
/// Signal from a profile / NetworkContext.
513+
/// Signal from a profile.
501514
Profile = 1,
502515

503516
/// Signal from the environment.

0 commit comments

Comments
 (0)