Check all C# 15 docs against updated feature specs and .NET 11 preview 7 behavior (dotnet#55444)

* First pass: Fix dotnet#55322

Elaborate on the explanation for IUnionProviders.

* Document C# 15 unsafe updates (dotnet#55330)

Add unsafe(expression) coverage to What's new in C# 15 and to the
Language Reference (unsafe-code.md and keywords/unsafe.md), including
a field-initializer example and an await-with-unsafe-expression
example verified against the .NET 11 Preview 6 SDK. Explain why the
expression form is useful where an unsafe block can't appear
syntactically (field initializers, constructor initializers, catch
filters), without claiming await is permitted inside an unsafe
context; it remains illegal (CS4004).

Update keywords/safe.md: the compiler now recognizes the safe
modifier on extern members and explicit-layout fields (verified
against Preview 6), but caller-safety/requires-unsafe enforcement
has no public opt-in and isn't active under ordinary preview
settings. Align xmldoc/recommended-tags.md safety guidance with
the same caveat so it doesn't imply caller obligations are already
enforced.

Fixes dotnet#55330

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4c0acfc3-7e62-4739-a09e-2dedc26b27af

* Clarify C# 15 union pattern matching (dotnet#55330)

Fix residual wording in operators/patterns.md and the "Non-boxing
access pattern" section of builtin-types/union.md that conflated
TryGetValue and HasValue as a single combined mechanism. State
plainly that TryGetValue supports type-pattern checks without
boxing and HasValue supports null-pattern checks; neither is a
fallback for the other, and the compiler checks Value for the
corresponding pattern when a member is omitted. Cross-link to the
detailed "Union member providers" section (accepted in dotnet#55322)
instead of duplicating its explanation.

Fixes dotnet#55330

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4c0acfc3-7e62-4739-a09e-2dedc26b27af

* Update C# 15 closed hierarchy docs (dotnet#55330)

Remove the obsolete ClosedAttribute workaround from What's new and
the shared snippet projects. The .NET 11 Preview 6 runtime already
supplies System.Runtime.CompilerServices.IsClosedTypeAttribute
(verified: the compiler synthesizes it automatically), so projects
no longer need to declare a substitute attribute.

Fix a discovered inaccuracy while validating snippets against the
Preview 6 SDK: exhaustiveness checking for a switch governed by a
type parameter constrained to a closed class isn't implemented yet,
even though the specification defines it and the docs claimed it
worked. Keep the example (it shows valid syntax from the
specification) but add an accurate NOTE explaining the current
compiler limitation in both closed.md and patterns.md, instead of
leaving readers with example code whose "no warning" comment
contradicts what the compiler actually reports.

Fixes dotnet#55330

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4c0acfc3-7e62-4739-a09e-2dedc26b27af

* Clarify C# 15 collection expression arguments (dotnet#55330)

Add a restriction to operators/collection-expressions.md stating
that with(...) arguments don't affect conversion, overload
resolution, or type inference: only the presence of a with(...)
element affects whether a conversion from the collection expression
to a candidate target type exists, and the arguments themselves are
ignored. This matches the resolved LDM decision in the collection
expression arguments feature specification, verified against the
.NET 11 Preview 6 SDK (overload resolution stays ambiguous and type
arguments still can't be inferred when with(...) supplies them).

Fixes dotnet#55330

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4c0acfc3-7e62-4739-a09e-2dedc26b27af

* proofread

Proofread and grammar check all changed files in this PR.

* Validate against preview 7

* Apply suggestions from code review

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot-Session: 4c0acfc3-7e62-4739-a09e-2dedc26b27af

Author: 3 people

docs/csharp/language-reference/builtin-types/snippets/unions/MemberProvider.cs

@@ -12,7 +12,7 @@ public interface IUnionMembers
         static Outcome<T> Create(Exception? value) => new(value);
         object? Value { get; }
 
-        // only when needed
+        // Optional but recommended: TryGetValue enables efficient pattern matching
         bool TryGetValue(out T value);
         bool TryGetValue(out Exception value);
     }

docs/csharp/language-reference/builtin-types/union.md

@@ -1,7 +1,7 @@
 ---
 title: "Union types"
 description: Learn about union types in C#. Unions express values from a closed set of types with exhaustive pattern matching support.
-ms.date: 06/05/2026
+ms.date: 08/14/2026
 f1_keywords:
   - "union_CSharpKeyword"
 helpviewer_keywords:
@@ -141,7 +141,7 @@ Any class or struct with a `[Union]` attribute is a *union type* if it follows t
 - One or more public constructors, each with a single by-value or `in` parameter. The parameter type of each constructor defines a *case type*.
 - A public `Value` property of type `object?` (or `object`) with a `get` accessor.
 
-All the preceding union members must be public. The compiler uses these members to implement union conversions, pattern matching, and exhaustiveness checks. You can also implement the [non-boxing access pattern](#non-boxing-access-pattern) or create a [class-based union type](#class-based-union-types). Your custom union type can add additional members.
+All the preceding union members must be public. The compiler uses these members to implement union conversions, pattern matching, and exhaustiveness checks. You can also implement the [non-boxing access pattern](#non-boxing-access-pattern) or create a [class-based union type](#class-based-union-types). Your custom union type can add more members.
 
 The compiler assumes that custom union types satisfy these behavioral rules:
 
@@ -167,11 +167,28 @@ A custom union type can optionally implement the *non-boxing access pattern* to
 
 :::code language="csharp" source="snippets/unions/NonBoxingAccess.cs" id="NonBoxingExample":::
 
-The compiler prefers `TryGetValue` over the `Value` property when implementing pattern matching, which avoids boxing value types.
+For pattern matching, the compiler calls `TryGetValue` for type-pattern checks (such as `union is T`) and `HasValue` for null-pattern checks (such as `union is null`), avoiding boxing for value-type cases. Each member applies to its own pattern kind—neither is a fallback for the other. When a member is missing, the compiler checks the `Value` property for that pattern instead. For more information, see [How the compiler generates code for pattern matching](#union-member-providers).
 
 ### Union member providers
 
-A union type can delegate its union members to a nested `IUnionMembers` interface. When this interface is present, the `union` type behaves as a *union member provider*. The compiler generates code to call the `IUnionMembers` interface. It won't generate calls to members declared on the union type that aren't members of the nested `IUnionMembers` interface. As the following example shows, that means you must add the necessary factory methods and the appropriate `TryGetValue` methods for all case types:
+A union type can delegate its union members to a nested `IUnionMembers` interface. When this interface is present, the `union` type behaves as a *union member provider*, and the compiler generates calls only to the members declared on `IUnionMembers`. Members declared on the union type itself, but omitted from the `IUnionMembers` interface, aren't used by the compiler.
+
+When using a union member provider, the interface must declare these required members:
+
+- **Static `Create` methods**: One for each case type, with a single parameter and a return type identity-convertible to the union type. These methods establish your case types.
+- **`Value` property**: A public `object` or `object?` property with a `get` accessor that returns the contained value.
+
+You can optionally declare these members on the interface so the compiler generates more efficient pattern matching code:
+
+- **`TryGetValue` methods**: One for each case type, returning `bool` with an `out` parameter of the case type.
+- **`HasValue` property**: A public `bool` property with a `get` accessor returning `true` when `Value` isn't `null`.
+
+**How the compiler generates code for pattern matching**: `TryGetValue` and `HasValue` apply to different kinds of patterns—neither is a fallback for the other:
+
+- For a *type pattern*, such as `union is T`, the compiler calls `TryGetValue(out T value)` when declared, extracting the value and applying the pattern to it without boxing. Otherwise, the compiler applies the pattern to the `Value` property, which performs a runtime type check against `T` and can box the value when `T` is a value type.
+- For a *null pattern*, such as `union is null`, the compiler calls `HasValue` when declared to test whether the union contains a value. Otherwise, the compiler applies the null pattern to the `Value` property directly.
+
+Each member is independently optional: without `TryGetValue`, type patterns use `Value`; without `HasValue`, null patterns use `Value`. Declaring either member lets the compiler generate more efficient, strongly typed code for that pattern kind:
 
 :::code language="csharp" source="snippets/unions/MemberProvider.cs" id="MemberProvider":::
 

docs/csharp/language-reference/keywords/closed.md

@@ -1,7 +1,7 @@
 ---
 title: "closed modifier"
 description: "Learn about the closed class modifier in C#. A closed class restricts derivation to its declaring assembly so consumers can write exhaustive switch expressions over its direct descendants."
-ms.date: 06/02/2026
+ms.date: 08/14/2026
 f1_keywords:
   - "closed"
   - "closed_CSharpKeyword"
@@ -75,12 +75,10 @@ For more information about how the compiler determines exhaustiveness, including
 
 ## Type parameters constrained to a closed type
 
-A type parameter constrained to a closed class is treated as that closed class for exhaustiveness checks. A `switch` expression whose governing value has such a type parameter is exhaustive when it handles every direct descendant of the closed constraint:
+The [closed hierarchies feature specification](~/_csharplang/proposals/csharp-15.0/closed-hierarchies.md#exhaustiveness-of-type-parameters-constrained-to-closed-type) treats a type parameter constrained to a closed class the same as that closed class for exhaustiveness checks: a `switch` expression whose governing value has such a type parameter is exhaustive when it handles every direct descendant of the closed constraint, regardless of whether the type parameter appears on a method or on the containing type:
 
 :::code language="csharp" source="./snippets/shared/Closed.cs" id="TypeParameterConstrained":::
 
-This rule applies whether the type parameter appears on a method or on the containing type.
-
 ## C# language specification
 
 For more information, see the [Closed hierarchies](~/_csharplang/proposals/csharp-15.0/closed-hierarchies.md) feature specification.

docs/csharp/language-reference/keywords/safe.md

@@ -1,7 +1,7 @@
 ---
 description: "safe modifier - C# Reference"
 title: "safe modifier"
-ms.date: 06/17/2026
+ms.date: 08/14/2026
 ai-usage: ai-assisted
 f1_keywords:
   - "safe_CSharpKeyword"
@@ -14,29 +14,29 @@ helpviewer_keywords:
 The `safe` contextual keyword attests that a declaration is sound in places where the [updated memory safety model](../unsafe-code.md#the-updated-memory-safety-model-preview) requires you to make the safety choice explicit. You apply `safe` as a modifier on a declaration that the compiler can't classify on its own, such as an `extern` member or a field in a struct with explicit layout. The `safe` modifier is the counterpart to [`unsafe`](unsafe.md): `safe` attests that callers need no `unsafe` context, while `unsafe` propagates the obligation to audit safety to the caller.
 
 > [!IMPORTANT]
-> The `safe` keyword is part of the updated memory safety model, a preview feature in C# 15 and .NET 11. The compiler in .NET 11 Preview 5 doesn't yet recognize the keyword. To follow the feature, set the [`LangVersion`](../compiler-options/language.md#langversion) compiler option to `preview`. For the full design, see the [memory safety feature specification](~/_csharplang/proposals/unsafe-evolution.md). The code in this article shows the proposed syntax and doesn't compile with the current preview compiler.
+> The `safe` keyword is part of the updated memory safety model, a preview feature in C# 15 and .NET 11. The compiler accepts `safe` as a modifier on `extern` members and explicit-layout fields. However, there's no public opt-in for the updated caller-safety rules yet, so the compiler doesn't enforce the safety choice that `safe` and [`unsafe`](unsafe.md) express: omitting both modifiers doesn't produce an error, and neither modifier changes what callers can do. To follow the feature, set the [`LangVersion`](../compiler-options/language.md#langversion) compiler option to `preview`. For the full design, see the [memory safety feature specification](~/_csharplang/proposals/unsafe-evolution.md).
 
 ## Extern members
 
 An `extern` member calls into native code, so the compiler can't classify its safety. Under the updated model, you mark every `extern` declaration, including a `LibraryImport` partial method, either `safe` or `unsafe`:
 
 ```csharp
-// Preview: illustrates the updated model, which the current compiler doesn't enforce yet.
+// Compiles under LangVersion preview, but the safety choice isn't enforced yet.
 [LibraryImport("libc")]
 internal static safe partial int getpid();
 
 [LibraryImport("libc", StringMarshalling = StringMarshalling.Utf8)]
 internal static unsafe partial nint strlen(byte* str);
 ```
 
-`getpid` takes no parameters and returns a primitive, so the author attests that the call is safe, and callers use it without an `unsafe` context. `strlen` takes a raw pointer that the native code dereferences, so the declaration is `unsafe` and propagates the obligation to its callers. Omitting both modifiers is an error, which forces you to make the safety decision.
+`getpid` takes no parameters and returns a primitive, so the author attests that the call is safe, and callers use it without an `unsafe` context. `strlen` takes a raw pointer that the native code dereferences, so the declaration is `unsafe` and propagates the obligation to its callers. Omitting both modifiers is intended to be an error under the updated model, but the compiler doesn't yet enforce that rule because there's no public opt-in for the updated rules.
 
 ## Explicit-layout fields
 
 In a struct with `[StructLayout(LayoutKind.Explicit)]`, fields can overlap in memory, so the compiler can't reason about whether a read through one field is sound. You mark every field of such a struct either `safe` or `unsafe`:
 
 ```csharp
-// Preview
+// Compiles under LangVersion preview, but the safety choice isn't enforced yet.
 [StructLayout(LayoutKind.Explicit)]
 internal struct Union
 {
@@ -48,7 +48,7 @@ internal struct Union
 }
 ```
 
-A field that holds a native pointer, or whose type otherwise carries an invariant the type system can't express, is `unsafe`. A field whose type is fully described by the type system is `safe`. As with `extern` members, omitting both modifiers is an error.
+A field that holds a native pointer, or whose type otherwise carries an invariant the type system can't express, is `unsafe`. A field whose type is fully described by the type system is `safe`. As with `extern` members, omitting both modifiers is intended to be an error under the updated model, but the compiler doesn't yet enforce that rule.
 
 ## C# language specification
 

docs/csharp/language-reference/keywords/snippets/shared/Closed.cs

@@ -42,7 +42,8 @@ public static class ClosedSwitchExamples
         Running(var percent) => $"{percent}% complete",
         Completed(var elapsed) => $"finished in {elapsed.TotalSeconds:F1}s",
         Failed(var error) => $"failed: {error}",
-        // No warning: 'X' is constrained to a closed type, so its direct descendants exhaust the switch.
+        // No warning: 'X' is constrained to a closed type, so the compiler treats
+        // this switch as exhaustive because every direct descendant is handled.
     };
     //</TypeParameterConstrained>
 }

docs/csharp/language-reference/keywords/snippets/shared/ClosedAttribute.cs

@@ -1,7 +1,7 @@
 ---
 description: "unsafe keyword - C# Reference"
 title: "unsafe keyword"
-ms.date: 06/16/2026
+ms.date: 08/14/2026
 f1_keywords:
   - "unsafe_CSharpKeyword"
   - "unsafe"
@@ -43,7 +43,7 @@ To compile unsafe code, you must specify the [**AllowUnsafeBlocks**](../compiler
 > [!NOTE]
 > The [memory safety](../unsafe-code.md#the-updated-memory-safety-model-preview) preview feature available in C# 15 narrows the operations that require an `unsafe` context.
 > An `unsafe` context is no longer required for creating a pointer, the `fixed` statement, converting a `stackalloc` expression to a pointer, and using `sizeof` on an unmanaged type.
-> Only operations that access the pointed-to memory, such as pointer indirection, still require an `unsafe` context. A later preview also changes `unsafe` on a member to mark it as *requires-unsafe*, so callers must use the member from an `unsafe` context.
+> Only operations that access the pointed-to memory, such as pointer indirection, still require an `unsafe` context. The same preview also adds an `unsafe(expression)` form that establishes an unsafe context for a single expression, for positions where an `unsafe` block can't appear, such as a field initializer or a `catch` filter. For more information, see [Unsafe expressions](../unsafe-code.md#unsafe-expressions). The preview also gives the `unsafe` modifier on a member a new meaning: the compiler recognizes it as marking the member *requires-unsafe*. Caller enforcement of that obligation isn't implemented yet, so marking a member `unsafe` currently has no effect on its callers. For more information, see [Caller-unsafe members](../unsafe-code.md#caller-unsafe-members).
 
 ## Example
 

docs/csharp/language-reference/keywords/unsafe.md

@@ -1,7 +1,7 @@
 ---
 title: "Collection expressions (Collection literals)"
 description: Collection expressions convert to many collection types. You can write literal values, expressions, or other collections to create a new collection.
-ms.date: 02/04/2026
+ms.date: 08/14/2026
 helpviewer_keywords:
   - "Collection expressions"
 ---
@@ -105,31 +105,31 @@ The first parameter provides the name of the *Builder* class. The second attribu
 
 Starting in C# 15, you can pass arguments to the underlying collection's constructor or factory method by using a `with(...)` element as the first element in a collection expression. This feature enables you to specify capacity, comparers, or other constructor parameters directly within the collection expression syntax. For more information, see the [collection expression arguments feature specification](~/_csharplang/proposals/csharp-15.0/collection-expression-arguments.md).
 
-The `with(...)` element must be the first element in the collection expression. The arguments declared in the `with(...)` element are passed to the appropriate constructor or create method based on the target type. You can use any valid expression for the arguments in the `with` element.
+The `with(...)` element must be the first element in the collection expression. The arguments declared in the `with(...)` element go to the appropriate constructor or create method based on the target type. You can use any valid expression for the arguments in the `with` element.
 
 ### Constructor arguments
 
-When the target type is a class or struct that implements <xref:System.Collections.IEnumerable?displayProperty=nameWithType>, the arguments in `with(...)` are evaluated and the results are passed to the constructor. The compiler uses overload resolution to select the best matching constructor:
+When the target type is a class or struct that implements <xref:System.Collections.IEnumerable?displayProperty=nameWithType>, the arguments in `with(...)` are evaluated and the results go to the constructor. The compiler uses overload resolution to select the best matching constructor:
 
 :::code language="csharp" source="./snippets/shared/CollectionExpressionExamples.cs" id="WithArgumentsExamples":::
 
 In the preceding example:
 
-- The `List<string>` constructor with a `capacity` parameter is called with `values.Length * 2`.
-- The `HashSet<string>` constructor with an <xref:System.Collections.Generic.IEqualityComparer`1?displayProperty=nameWithType> parameter is called with `StringComparer.OrdinalIgnoreCase`.
+- The `List<string>` constructor with a `capacity` parameter gets called with `values.Length * 2`.
+- The `HashSet<string>` constructor with an <xref:System.Collections.Generic.IEqualityComparer`1?displayProperty=nameWithType> parameter gets called with `StringComparer.OrdinalIgnoreCase`.
 - For interface target types like <xref:System.Collections.Generic.IList`1?displayProperty=nameWithType>, the compiler creates a `List<T>` with the specified capacity.
 
 ### Collection builder arguments
 
-For types with a <xref:System.Runtime.CompilerServices.CollectionBuilderAttribute?displayProperty=nameWithType>, the arguments declared in the `with(...)` element are evaluated and the results are passed to the create method *before* the `ReadOnlySpan<T>` parameter. This feature allows create methods to accept configuration parameters:
+For types with a <xref:System.Runtime.CompilerServices.CollectionBuilderAttribute?displayProperty=nameWithType>, the arguments declared in the `with(...)` element get evaluated and the results go to the create method *before* the `ReadOnlySpan<T>` parameter. This feature allows create methods to accept configuration parameters:
 
 :::code language="csharp" source="./snippets/shared/CollectionExpressionExamples.cs" id="BuilderClassWithComparer":::
 
 You can then use the `with(...)` element to pass the comparer:
 
 :::code language="csharp" source="./snippets/shared/CollectionExpressionExamples.cs" id="WithBuilderArgumentsExample":::
 
-The create method is selected using overload resolution based on the arguments provided. The `ReadOnlySpan<T>` containing the collection elements is always the last parameter.
+The create method gets selected by using overload resolution based on the arguments you provide. The `ReadOnlySpan<T>` containing the collection elements is always the last parameter.
 
 ### Interface target types
 
@@ -149,3 +149,4 @@ The `with(...)` element has the following restrictions:
 - It must be the first element in the collection expression.
 - Arguments can't have `dynamic` type.
 - It's not supported for arrays or span types (`Span<T>`, `ReadOnlySpan<T>`).
+- The arguments in `with(...)` don't affect whether a conversion exists from the collection expression to a candidate target type. The compiler ignores them during overload resolution and type inference. Only the presence of a `with(...)` element, not its arguments, affects whether the conversion exists.