Skip to content

Commit d0251eb

Browse files
richlanderCopilot
richlander
and
Copilot
committed
Reformat examples: content first, metadata in footer blocks
New format per file: ## Heading (H2) Actual content (copy/paste from original) --- Source: link to original Commentary: why it was selected Why it works: what makes it effective --- Clear separation between the example content and the editorial commentary. Content reads exactly as it would in release notes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 68d022c commit d0251eb

5 files changed

Lines changed: 104 additions & 89 deletions

File tree

‎.github/skills/release-notes/references/examples/aspnetcore.md‎

Lines changed: 35 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,31 +2,28 @@
22

33
## Configure suppressing exception handler diagnostics
44

5-
> Source: [.NET 10 Preview 7 — ASP.NET Core](../../../../release-notes/10.0/preview/preview7/aspnetcore.md)
5+
A new configuration option has been added to the [ASP.NET Core exception handler middleware](https://learn.microsoft.com/aspnet/core/fundamentals/error-handling#exception-handler-page) to control diagnostic output: `ExceptionHandlerOptions.SuppressDiagnosticsCallback`. This callback is passed context about the request and exception, allowing you to add logic that determines whether the middleware should write exception logs and other telemetry.
66

7-
Short — three sentences covering the new option, the use case, and a behavior change. No code needed.
7+
This setting is useful when you know an exception is transient, or has been handled by the exception handler middleware, and don't want the error logs written to your observability platform.
88

9-
> A new configuration option has been added to the [ASP.NET Core exception handler middleware](https://learn.microsoft.com/aspnet/core/fundamentals/error-handling#exception-handler-page) to control diagnostic output: `ExceptionHandlerOptions.SuppressDiagnosticsCallback`. This callback is passed context about the request and exception, allowing you to add logic that determines whether the middleware should write exception logs and other telemetry.
10-
>
11-
> This setting is useful when you know an exception is transient, or has been handled by the exception handler middleware, and don't want the error logs written to your observability platform.
12-
>
13-
> Additionally, the middleware's default behavior has changed: it no longer writes exception diagnostics for exceptions handled by `IExceptionHandler`. Based on user feedback, logging handled exceptions at the error level was often undesirable when `IExceptionHandler.TryHandleAsync` returned `true`.
9+
Additionally, the middleware's default behavior has changed: it no longer writes exception diagnostics for exceptions handled by `IExceptionHandler`. Based on user feedback, logging handled exceptions at the error level was often undesirable when `IExceptionHandler.TryHandleAsync` returned `true`.
1410

15-
**Why it works**: concise problem/solution. The reader immediately knows what changed, why, and whether they're affected.
11+
---
12+
Source: [.NET 10 Preview 7 — ASP.NET Core](../../../../release-notes/10.0/preview/preview7/aspnetcore.md)
13+
Commentary: Short and focused — three sentences covering the new option, the use case, and a behavior change. No code needed.
14+
Why it works: The reader immediately knows what changed, why, and whether they're affected.
1615

1716
---
1817

1918
## Use PipeReader support in System.Text.Json
2019

21-
> Source: [.NET 10 Preview 7 — ASP.NET Core](../../../../release-notes/10.0/preview/preview7/aspnetcore.md)
20+
MVC, Minimal APIs, and the `HttpRequestJsonExtensions.ReadFromJsonAsync` methods have all been updated to use the new PipeReader support in System.Text.Json without requiring any code changes from applications.
2221

23-
Medium — behavioral change with workaround guidance and two code samples (quick fix and optimal fix).
22+
For the majority of applications this should have no impact on behavior. However, if the application is using a custom `JsonConverter`, there is a chance that the converter doesn't handle [Utf8JsonReader.HasValueSequence](https://learn.microsoft.com/dotnet/api/system.text.json.utf8jsonreader.hasvaluesequence) correctly. This can result in missing data and errors like `ArgumentOutOfRangeException` when deserializing.
2423

25-
> MVC, Minimal APIs, and the `HttpRequestJsonExtensions.ReadFromJsonAsync` methods have all been updated to use the new PipeReader support in System.Text.Json without requiring any code changes from applications.
26-
>
27-
> For the majority of applications this should have no impact on behavior. However, if the application is using a custom `JsonConverter`, there is a chance that the converter doesn't handle `Utf8JsonReader.HasValueSequence` correctly. This can result in missing data and errors like `ArgumentOutOfRangeException` when deserializing.
28-
>
29-
> The quick workaround (especially if you don't own the custom `JsonConverter` being used) is to set the `"Microsoft.AspNetCore.UseStreamBasedJsonParsing"` AppContext switch to `true`. This should be a temporary workaround and the `JsonConverter`(s) should be updated to support `HasValueSequence`.
24+
The quick workaround (especially if you don't own the custom `JsonConverter` being used) is to set the `"Microsoft.AspNetCore.UseStreamBasedJsonParsing"` [AppContext](https://learn.microsoft.com/dotnet/api/system.appcontext) switch to `true`. This should be a temporary workaround and the `JsonConverter`(s) should be updated to support `HasValueSequence`.
25+
26+
To fix `JsonConverter` implementations, there is the quick fix which allocates an array from the `ReadOnlySequence`:
3027

3128
```csharp
3229
public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
@@ -36,28 +33,27 @@ public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSeria
3633
}
3734
```
3835

39-
**Why it works**: acknowledges most users won't notice, identifies who *will* be affected, gives an immediate workaround, then the proper fix. Good template for "mostly invisible but has an edge case."
40-
4136
---
37+
Source: [.NET 10 Preview 7 — ASP.NET Core](../../../../release-notes/10.0/preview/preview7/aspnetcore.md)
38+
Commentary: Medium — behavioral change that's mostly invisible but has an edge case. Gives the workaround and the proper fix.
39+
Why it works: Acknowledges most users won't notice, identifies who *will* be affected, gives an immediate workaround, then the proper fix.
4240

43-
## OpenIdConnectHandler support for Pushed Authorization Requests (PAR)
41+
---
4442

45-
> Source: [.NET 9 Preview 7 — ASP.NET Core](../../../../release-notes/9.0/preview/preview7/aspnetcore.md)
43+
## `OpenIdConnectHandler` support for Pushed Authorization Requests (PAR)
4644

47-
Long — community contribution with extensive quoted motivation, configuration example, and operational guidance.
45+
We'd like to thank @josephdecock from @DuendeSoftware for adding Pushed Authorization Requests (PAR) to ASP.NET Core's `OpenIdConnectHandler`. Joe described the background and motivation for enabling PAR in [his API proposal](https://github.com/dotnet/aspnetcore/issues/51686) as follows:
4846

49-
> We'd like to thank @josephdecock from @DuendeSoftware for adding Pushed Authorization Requests (PAR) to ASP.NET Core's `OpenIdConnectHandler`. Joe described the background and motivation for enabling PAR in [his API proposal](https://github.com/dotnet/aspnetcore/issues/51686) as follows:
47+
> Pushed Authorization Requests (PAR) is a relatively new [OAuth standard](https://datatracker.ietf.org/doc/html/rfc9126) that improves the security of OAuth and OIDC flows by moving authorization parameters from the front channel to the back channel (that is, from redirect URLs in the browser to direct machine to machine http calls on the back end).
48+
>
49+
> This prevents an attacker in the browser from:
5050
>
51-
> > Pushed Authorization Requests (PAR) is a relatively new [OAuth standard](https://datatracker.ietf.org/doc/html/rfc9126) that improves the security of OAuth and OIDC flows by moving authorization parameters from the front channel to the back channel (that is, from redirect URLs in the browser to direct machine to machine http calls on the back end).
52-
> >
53-
> > This prevents an attacker in the browser from:
54-
> >
55-
> > - Seeing authorization parameters (which could leak PII) and from
56-
> > - Tampering with those parameters (e.g., the attacker could change the scope of access being requested).
57-
> >
58-
> > The use of PAR is encouraged by the [FAPI working group](https://openid.net/wg/fapi/) within the OpenID Foundation.
51+
> - Seeing authorization parameters (which could leak PII) and from
52+
> - Tampering with those parameters (e.g., the attacker could change the scope of access being requested).
53+
>
54+
> The use of PAR is encouraged by the [FAPI working group](https://openid.net/wg/fapi/) within the OpenID Foundation.
5955
60-
> PAR is now enabled by default if the identity provider's discovery document advertises support for it. This change should provide enhanced security for providers that support PAR. If this causes problems, disable PAR via `OpenIdConnectOptions.PushedAuthorizationBehavior`:
56+
PAR is now enabled by default if the identity provider's discovery document advertises support for it. The identity provider's discovery document is usually found at `.well-known/openid-configuration`. This change should provide enhanced security for providers that support PAR. If this causes problems, disable PAR via `OpenIdConnectOptions.PushedAuthorizationBehavior` as follows:
6157

6258
```csharp
6359
builder.Services
@@ -74,6 +70,13 @@ builder.Services
7470
});
7571
```
7672

77-
> To ensure that authentication only succeeds if PAR is used, use `PushedAuthorizationBehavior.Require`.
73+
To ensure that authentication only succeeds if PAR is used, use `PushedAuthorizationBehavior.Require`.
74+
75+
This change also introduces a new `OnPushAuthorization` event to `OpenIdConnectEvents` which can be used to customize the pushed authorization request or handle it manually. Refer to the [API proposal](https://github.com/dotnet/aspnetcore/issues/51686) for more details.
7876

79-
**Why it works**: the block quote lets the contributor explain the significance in their own words — more credible than the agent paraphrasing. Then practical: default behavior, how to disable, how to require. Good template for features with security or compliance significance.
77+
---
78+
Source: [.NET 9 Preview 7 — ASP.NET Core](../../../../release-notes/9.0/preview/preview7/aspnetcore.md)
79+
Commentary: Long — community contribution with the contributor's own words explaining significance. Good template for features with security or compliance importance.
80+
Why it works: The block quote lets the contributor explain the significance — more credible than paraphrasing. Then practical: default behavior, how to disable, how to require.
81+
82+
---

‎.github/skills/release-notes/references/examples/csharp.md‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,7 @@
22

33
## Extension operators
44

5-
> Source: [.NET 10 Preview 7 — C#](../../../../release-notes/10.0/preview/preview7/csharp.md)
6-
7-
Medium — one sentence of context, then a code block showing the new syntax, then rule bullets. Code-first because the syntax *is* the feature.
8-
9-
> The new extension blocks now include support for *operators*, with the exception of implicit and explicit conversion operators. You can declare operators in extension blocks, as shown in the following example:
5+
The new extension blocks now include support for *operators*, with the exception of implicit and explicit conversion operators. You can declare operators in extension blocks, as shown in the following example:
106

117
```csharp
128
public static class Operators
@@ -22,11 +18,18 @@ public static class Operators
2218
}
2319
```
2420

25-
> Several of the rules for extension operators are demonstrated in the preceding example:
26-
>
27-
> - At least one of the operands must be the *extended type*, `TElement[]` in the preceding example.
28-
> - For operators that require pair-wise declarations, such as `==` and `!=`, both operators must be declared in the same static class.
29-
> - Instance compound assignment operators, and instance increment and decrement operators are expected to mutate the current instance.
30-
> - Extension operators, like other extension members, can't use the `abstract`, `virtual`, `override`, or `sealed` modifiers.
21+
Several of the rules for extension operators are demonstrated in the preceding example:
22+
23+
- At least one of the operands must be the *extended type*, `TElement[]` in the preceding example.
24+
- For operators that require pair-wise declarations, such as `==` and `!=` in the preceding example, both operators must be declared in the same static class. They are not required to be in the same `extension` container.
25+
- Instance compound assignment operators, and instance increment and decrement operators are expected to mutate the current instance. Therefore reference type parameters must be passed by value and value type parameters must be passed by `ref`. These operators can't be declared when the extended type is an unconstrained type parameter.
26+
- Extension operators, like other extension members, can't use the `abstract`, `virtual`, `override`, or `sealed` modifiers. This is consistent with other extension members.
27+
28+
Extension members are only considered for overload resolution when no applicable predefined or user defined non-extension members are found.
29+
30+
---
31+
Source: [.NET 10 Preview 7 — C#](../../../../release-notes/10.0/preview/preview7/csharp.md)
32+
Commentary: Code-first — one sentence of context, then the syntax, then rule bullets. Language features need to be seen, not just described.
33+
Why it works: Shows the code immediately. The rule bullets follow naturally as "here's what you need to know." No motivation section needed.
3134

32-
**Why it works**: shows the code immediately — language features need to be seen, not just described. The rule bullets follow naturally as "here's what you need to know." No motivation section needed because C# developers will already understand why extension operators are useful.
35+
---

‎.github/skills/release-notes/references/examples/libraries.md‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,9 @@
22

33
## Post-Quantum Cryptography Updates
44

5-
> Source: [.NET 10 Preview 7 — Libraries](../../../../release-notes/10.0/preview/preview7/libraries.md)
5+
### ML-DSA
66

7-
Long — subheadings, diff-style before/after, multiple API examples spanning two related features.
8-
9-
> ### ML-DSA
10-
>
11-
> The `System.Security.Cryptography.MLDsa` class gained ease-of-use updates in this release, allowing some common code patterns to be simplified:
7+
The `System.Security.Cryptography.MLDsa` class gained ease-of-use updates in this release, allowing some common code patterns to be simplified:
128

139
```diff
1410
private static byte[] SignData(string privateKeyPath, ReadOnlySpan<byte> data)
@@ -23,7 +19,7 @@ private static byte[] SignData(string privateKeyPath, ReadOnlySpan<byte> data)
2319
}
2420
```
2521

26-
> Additionally, this release added support for HashML-DSA, which we call "PreHash" to help distinguish it from "pure" ML-DSA.
22+
Additionally, this release added support for HashML-DSA, which we call "PreHash" to help distinguish it from "pure" ML-DSA. As the underlying specification interacts with the Object Identifier (OID) value, the SignPreHash and VerifyPreHash methods on this `[Experimental]` type take the dotted-decimal OID as a string. This may evolve as more scenarios using HashML-DSA become well-defined.
2723

2824
```csharp
2925
private static byte[] SignPreHashSha3_256(MLDsa signingKey, ReadOnlySpan<byte> data)
@@ -33,9 +29,9 @@ private static byte[] SignPreHashSha3_256(MLDsa signingKey, ReadOnlySpan<byte> d
3329
}
3430
```
3531

36-
> ### Composite ML-DSA
37-
>
38-
> This release also introduces new types to support ietf-lamps-pq-composite-sigs (currently at draft 7), and an implementation of the primitive methods for RSA variants.
32+
### Composite ML-DSA
33+
34+
This release also introduces new types to support ietf-lamps-pq-composite-sigs (currently at draft 7), and an implementation of the primitive methods for RSA variants.
3935

4036
```csharp
4137
var algorithm = CompositeMLDsaAlgorithm.MLDsa65WithRSA4096Pss;
@@ -52,4 +48,9 @@ signature[0] ^= 1; // Tamper with signature
5248
Console.WriteLine(publicKey.VerifyData(data, signature)); // False
5349
```
5450

55-
**Why it works**: the `diff` block for ML-DSA immediately shows the simplification — red lines removed, green line added. Subheadings organize related-but-distinct features. The Composite ML-DSA sample is a complete, runnable scenario (generate → sign → verify → tamper → verify-fails).
51+
---
52+
Source: [.NET 10 Preview 7 — Libraries](../../../../release-notes/10.0/preview/preview7/libraries.md)
53+
Commentary: Long — subheadings organize related-but-distinct features. Uses `diff` blocks for API simplification and complete runnable scenarios for new APIs.
54+
Why it works: The `diff` block immediately shows the simplification (red lines removed, green line added). The Composite ML-DSA sample is a complete scenario (generate → sign → verify → tamper → verify-fails).
55+
56+
---

0 commit comments

Comments
 (0)