Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
ce14b16
support ref fields and scoped
RexJaeschke Mar 28, 2026
d9a11af
support ref fields and scoped
RexJaeschke Mar 28, 2026
b825e28
support ref fields and scoped
RexJaeschke Mar 28, 2026
26fb248
support ref fields and scoped
RexJaeschke Mar 28, 2026
60283fe
support ref fields and scoped
RexJaeschke Mar 28, 2026
cf89040
support ref fields and scoped
RexJaeschke Mar 28, 2026
f08f3b4
support ref fields and scoped
RexJaeschke Mar 28, 2026
c40e813
support ref fields and scoped
RexJaeschke Mar 28, 2026
13e2856
support ref fields and scoped
RexJaeschke Mar 28, 2026
adb1bed
fix md formatting
RexJaeschke Mar 28, 2026
4b4a6e1
fix md formatting
RexJaeschke Mar 28, 2026
447cbf8
fix md formatting
RexJaeschke Mar 28, 2026
03124fc
fix md formatting
RexJaeschke Mar 28, 2026
e47b6df
fix md formatting
RexJaeschke Mar 28, 2026
5c93b4a
fix md formatting
RexJaeschke Mar 28, 2026
3fa0f84
Introduces the 4th safe-context value
BillWagner Apr 3, 2026
552120a
Method invocation rules
BillWagner Apr 3, 2026
466043d
MAMM, declaration expressions, object initializers
BillWagner Apr 3, 2026
c89873a
Grammar corrections.
BillWagner Apr 3, 2026
c2c4888
unsafe context changes
BillWagner Apr 3, 2026
66f22b4
Parameter scope variance + UnscopedRef xref
BillWagner Apr 3, 2026
05b50df
Editorial fixes
BillWagner Apr 3, 2026
db3c644
Add examples for complicated examples
BillWagner Apr 6, 2026
7bcd0ac
Add additional examples.
BillWagner Apr 6, 2026
f14cff3
fix md formatting
RexJaeschke Apr 7, 2026
359a6ef
Review and update ref fields
BillWagner May 4, 2026
4e0e927
add Attribute suffix
RexJaeschke Sep 15, 2026
b9a22b1
Fix markdown lint issues in ref fields text
BillWagner Sep 18, 2026
d8ed7a5
Restore consistent attributes table style
BillWagner Sep 18, 2026
083db42
Update safe-context cross-reference
BillWagner Sep 18, 2026
8174afa
Fix scoped-reference blockquote lint
BillWagner Sep 18, 2026
5c2318d
Fix ref-fields validation failures
BillWagner Sep 21, 2026
b22432b
Keep ref-fields contents links coherent with authoring placeholders
BillWagner Oct 14, 2026
715c95f
[v11 ref fields and scoped] Complete Annex C scoped handler API param…
BillWagner Nov 13, 2026
dc5c57c
Review and edit ref and scoped ref
BillWagner Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion standard/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -727,7 +727,9 @@
- [§16.6.5](structs.md#1665-default-values) Default values
- [§16.6.6](structs.md#1666-boxing-and-unboxing) Boxing and unboxing
- [§16.6.7](structs.md#1667-meaning-of-this) Meaning of this
- [§16.6.8](structs.md#1668-field-initializers) Field initializers
- [§fields](structs.md#fields-fields) Fields
- [§field-initializers](structs.md#field-initializers-field-initializers) Field initializers
- [§Ref-Fields](structs.md#ref-fields-ref-fields) Ref fields
- [§16.6.9](structs.md#1669-constructors) Constructors
- [§16.6.10](structs.md#16610-static-constructors) Static constructors
- [§16.6.11](structs.md#16611-properties) Properties
Expand Down
50 changes: 37 additions & 13 deletions standard/attributes.md
Original file line number Diff line number Diff line change
Expand Up @@ -504,6 +504,7 @@ A number of attributes affect the language in some way. These attributes include
- `System.Runtime.CompilerServices.EnumeratorCancellationAttribute` ([§23.5.8](attributes.md#2358-the-enumeratorcancellation-attribute)), which is used to specify parameter for the cancellation token in an asynchronous iterator.
- `System.Runtime.CompilerServices.ModuleInitializerAttribute` ([§23.5.9](attributes.md#2359-the-moduleinitializer-attribute)), which is used to mark a method as a module initializer.
- `System.Runtime.CompilerServices.InterpolatedStringHandlerAttribute` and `System.Runtime.CompilerServices.InterpolatedStringHandlerArgumentAttribute`, which are used to declare a custom interpolated string expression handler ([§23.5.9.1](attributes.md#23591-custom-interpolated-string-expression-handlers)) and to call one of its constructors, respectively.
- System.Diagnostics.CodeAnalysis.UnscopedRefAttribute (§UnscopedRefAttribute), which allows an otherwise implicitly scoped ref to be treated as not being scoped.

The Nullable static analysis attributes ([§23.5.7](attributes.md#2357-code-analysis-attributes)) can improve the correctness of warnings generated for nullabilities and null states ([§8.9.5](types.md#895-nullabilities-and-null-states)).

Expand Down Expand Up @@ -1058,19 +1059,19 @@ The attributes in this subclause are used to provide additional information to s

The code-analysis attributes are declared in namespace `System.Diagnostics.CodeAnalysis`.

**Attribute** | **Meaning**
------------------ | ------------------
`AllowNullAttribute` ([§23.5.7.2](attributes.md#23572-the-allownull-attribute)) | A non-nullable argument may be null.
`DisallowNullAttribute` ([§23.5.7.3](attributes.md#23573-the-disallownull-attribute)) | A nullable argument should never be null.
`MaybeNullAttribute` ([§23.5.7.6](attributes.md#23576-the-maybenull-attribute)) | A non-nullable return value may be null.
`NotNullAttribute` ([§23.5.7.10](attributes.md#235710-the-notnull-attribute)) | A nullable return value will never be null.
`MaybeNullWhenAttribute` ([§23.5.7.7](attributes.md#23577-the-maybenullwhen-attribute)) | A non-nullable argument may be null when the method returns the specified `bool` value.
`NotNullWhenAttribute` ([§23.5.7.12](attributes.md#235712-the-notnullwhen-attribute)) | A nullable argument will not be null when the method returns the specified `bool` value.
`NotNullIfNotNullAttribute` ([§23.5.7.11](attributes.md#235711-the-notnullifnotnull-attribute)) | A return value is not null if the argument for the specified parameter is not null.
`MemberNotNullAttribute` ([§23.5.7.8](attributes.md#23578-the-membernotnull-attribute)) | The listed member will not be null when the method returns.
`MemberNotNullWhenAttribute` ([§23.5.7.9](attributes.md#23579-the-membernotnullwhen-attribute)) | The listed member will not be null when the method returns the specified `bool` value.
`DoesNotReturnAttribute` ([§23.5.7.4](attributes.md#23574-the-doesnotreturn-attribute)) | This method never returns.
`DoesNotReturnIfAttribute` ([§23.5.7.5](attributes.md#23575-the-doesnotreturnif-attribute)) | This method never returns if the associated `bool` parameter has the specified value.
| **Attribute** | **Meaning** |
| --- | --- |
| `AllowNullAttribute` ([§23.5.7.2](attributes.md#23572-the-allownull-attribute)) | A non-nullable argument may be null. |
| `DisallowNullAttribute` ([§23.5.7.3](attributes.md#23573-the-disallownull-attribute)) | A nullable argument should never be null. |
| `MaybeNullAttribute` ([§23.5.7.6](attributes.md#23576-the-maybenull-attribute)) | A non-nullable return value may be null. |
| `NotNullAttribute` ([§23.5.7.10](attributes.md#235710-the-notnull-attribute)) | A nullable return value will never be null. |
| `MaybeNullWhenAttribute` ([§23.5.7.7](attributes.md#23577-the-maybenullwhen-attribute)) | A non-nullable argument may be null when the method returns the specified `bool` value. |
| `NotNullWhenAttribute` ([§23.5.7.12](attributes.md#235712-the-notnullwhen-attribute)) | A nullable argument will not be null when the method returns the specified `bool` value. |
| `NotNullIfNotNullAttribute` ([§23.5.7.11](attributes.md#235711-the-notnullifnotnull-attribute)) | A return value is not null if the argument for the specified parameter is not null. |
| `MemberNotNullAttribute` ([§23.5.7.8](attributes.md#23578-the-membernotnull-attribute)) | The listed member will not be null when the method returns. |
| `MemberNotNullWhenAttribute` ([§23.5.7.9](attributes.md#23579-the-membernotnullwhen-attribute)) | The listed member will not be null when the method returns the specified `bool` value. |
| `DoesNotReturnAttribute` ([§23.5.7.4](attributes.md#23574-the-doesnotreturn-attribute)) | This method never returns. |
| `DoesNotReturnIfAttribute` ([§23.5.7.5](attributes.md#23575-the-doesnotreturnif-attribute)) | This method never returns if the associated `bool` parameter has the specified value. |

The following subclauses in [§23.5.7](attributes.md#2357-code-analysis-attributes) are conditionally normative.

Expand Down Expand Up @@ -1315,6 +1316,29 @@ Specifies that a nullable argument will not be `null` when the method returns th
>
> *end example*

### §UnscopedRefAttribute The UnscopedRef attribute

`System.Diagnostics.CodeAnalysis.UnscopedRefAttribute` widens the ref-safe-context of a parameter, including the implicit `this` parameter, according to the following table:

| UnscopedRef applied to | Original ref-safe-context | New ref-safe-context |
| --- | --- | --- |
| struct instance method or property (applies to `this`) | function-member | return-only |
| `in` / `ref` parameter | return-only | caller-context |
| `out` parameter | function-member | return-only |

The permitted targets are:

- A struct instance method or property, other than an `init` accessor or constructor, that does not implement an interface member.
- A `ref`, `in`, or `out` parameter that is not explicitly declared `scoped`, including an ordinary `ref` or `in` parameter.

An application to any other target is a compile-time error.

See §scoped-modifier for more information.

### §ScopedRefAttribute The ScopedRef attribute

The name `System.Runtime.CompilerServices.ScopedRefAttribute` is reserved for compiler use. The compiler emits this attribute on a parameter when the parameter's `scoped` annotation differs from its default state, in order to encode the `scoped` modifier (§scoped-modifier) in metadata. This attribute is not permitted in source.

### 23.5.8 The EnumeratorCancellation attribute

Specifies the parameter representing the `CancellationToken` for an asynchronous iterator ([§15.15](classes.md#1515-synchronous-and-asynchronous-iterators)). The argument for this parameter shall be combined with the argument passed to `IAsyncEnumerable<T>.GetAsyncEnumerator(CancellationToken)`. This combined token shall be polled by `IAsyncEnumerator<T>.MoveNextAsync()` ([§15.15.5.2](classes.md#151552-advance-the-enumerator)). The tokens shall be combined into a single token as if by `CancellationToken.CreateLinkedTokenSource` and its `Token` property. The combined token will be canceled if either of the two source tokens are canceled. The combined token is seen as the argument to the asynchronous iterator method ([§15.15](classes.md#1515-synchronous-and-asynchronous-iterators)) in the body of that method.
Expand Down
8 changes: 4 additions & 4 deletions standard/basic-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -625,11 +625,11 @@ The following accessibility constraints exist:

Methods, instance constructors, indexers, and operators are characterized by their ***signature***s:

- The signature of a method consists of the name of the method, the number of type parameters, and the type and parameter-passing mode of each of its parameters, considered in the order left to right. For these purposes, any type parameter of the method that occurs in the type of a parameter is identified not by its name, but by its ordinal position in the type parameter list of the method. The signature of a method specifically does not include the return type, parameter names, type parameter names, type parameter constraints, the `params` or `this` parameter modifiers, nor whether parameters are required or optional.
- The signature of a method consists of the name of the method, the number of type parameters, and the type and parameter-passing mode of each of its parameters, considered in the order left to right. For these purposes, any type parameter of the method that occurs in the type of a parameter is identified not by its name, but by its ordinal position in the type parameter list of the method. The signature of a method specifically does not include the return type, parameter names, type parameter names, type parameter constraints, the `params`, `scoped`, or `this` parameter modifiers, nor whether parameters are required or optional.
- The signature of an instance constructor consists of the type and parameter-passing mode of each of its parameters, considered in the order left to right. The signature of an instance constructor specifically does not include the `params` modifier that may be specified for the right-most parameter, nor whether parameters are required or optional.
- The signature of an indexer consists of the type of each of its parameters, considered in the order left to right. The signature of an indexer specifically does not include the element type, nor does it include the `params` modifier that may be specified for the right-most parameter, nor whether parameters are required or optional.
- The signature of an operator consists of the name of the operator and the type of each of its parameters, considered in the order left to right. The signature of an operator specifically does not include the result type.
- The signature of a conversion operator consists of the source type and the target type. The implicit or explicit classification of a conversion operator is not part of the signature.
- The signature of an indexer consists of the type of each of its parameters, considered in the order left to right. The signature of an indexer specifically does not include the element type, or the `scoped` modifier, nor does it include the `params` modifier that may be specified for the right-most parameter, or the `scoped` modifier, nor whether parameters are required or optional.
- The signature of an operator consists of the name of the operator and the type of each of its parameters, considered in the order left to right. The signature of an operator specifically does not include the result type or the `scoped` modifier.
- The signature of a conversion operator consists of the source type and the target type. The implicit or explicit classification of a conversion operator is not part of the signature nor is the `scoped` modifier.
- Two signatures of the same member kind (method, instance constructor, indexer or operator) are considered to be the *same signatures* if they have the same name, number of type parameters, number of parameters, and parameter-passing modes, and an identity conversion exists between the types of their corresponding parameters ([§10.2.2](conversions.md#1022-identity-conversion)).

Signatures are the enabling mechanism for ***overloading*** of members in classes, structs, and interfaces:
Expand Down
25 changes: 20 additions & 5 deletions standard/classes.md
Original file line number Diff line number Diff line change
Expand Up @@ -1700,6 +1700,10 @@ The value of a field is obtained in an expression using a *simple_name* ([§12.8

A field declaration that declares multiple fields is equivalent to multiple declarations of single fields with the same attributes, modifiers, and type.

> *Note*: Inside a `ref struct`, a field may also be declared as a reference variable; see §Ref-Fields. *end note*

<!-- markdownlint-disable MD028 -->

> *Example*:
>
> <!-- Example: {template:"standalone-lib-without-using", name:"Fields1", ignoredWarnings:["CS0649"]} -->
Expand Down Expand Up @@ -2255,8 +2259,9 @@ default_argument

parameter_modifier
: parameter_mode_modifier
| 'this' parameter_mode_modifier?
| parameter_mode_modifier? 'this'
| 'this' 'scoped'? parameter_mode_modifier?
| 'scoped'? parameter_mode_modifier? 'this'
| 'scoped' parameter_mode_modifier?
;

parameter_mode_modifier
Expand All @@ -2272,7 +2277,11 @@ parameter_array

The parameter list consists of one or more comma-separated parameters of which only the last may be a *parameter_array*.

A *fixed_parameter* consists of an optional set of *attributes* ([§23](attributes.md#23-attributes)); an optional `in`, `out`, `ref`, or `this` modifier; a *type*; an *identifier*; and an optional *default_argument*. Each *fixed_parameter* declares a parameter of the given type with the given name. The `this` modifier designates the method as an extension method and is only allowed on the first parameter of a static method in a non-generic, non-nested static class. If the parameter is a `struct` type or a type parameter constrained to a `struct`, the `this` modifier may be combined with either the `ref` or `in` modifier, but not the `out` modifier. Extension methods are further described in [§15.6.10](classes.md#15610-extension-methods). A *fixed_parameter* with a *default_argument* is known as an ***optional parameter***, whereas a *fixed_parameter* without a *default_argument* is a ***required parameter***. A required parameter shall not appear after an optional parameter in a *parameter_list*.
A *fixed_parameter* consists of an optional set of *attributes* ([§23](attributes.md#23-attributes)); an optional `this` modifier; an optional `scoped` modifier; an optional `in`, `out`, `ref` modifier; a *type*; an *identifier*; and an optional *default_argument*. Each *fixed_parameter* declares a parameter of the given type with the given name. The `this` modifier designates the method as an extension method and is only allowed on the first parameter of a static method in a non-generic, non-nested static class. If the parameter is a `struct` type or a type parameter constrained to a `struct`, the `this` modifier may be combined with either the `ref` or `in` modifier, but not the `out` modifier. Extension methods are further described in [§15.6.10](classes.md#15610-extension-methods). A *fixed_parameter* with a *default_argument* is known as an ***optional parameter***, whereas a *fixed_parameter* without a *default_argument* is a ***required parameter***. A required parameter shall not appear after an optional parameter in a *parameter_list*.

An output parameter implicitly has the `scoped` modifier.

For a discussion of `scoped`, see §scoped-modifier.

A parameter with a `ref`, `out` or `this` modifier cannot have a *default_argument*. An input parameter may have a *default_argument*. The *expression* in a *default_argument* shall be one of the following:

Expand Down Expand Up @@ -2344,7 +2353,7 @@ The following kinds of parameters exist:
- Reference parameters ([§15.6.2.3.3](classes.md#156233-reference-parameters)).
- Parameter arrays ([§15.6.2.4](classes.md#15624-parameter-arrays)).

> *Note*: As described in [§7.5](basic-concepts.md#75-signatures-and-overloading), the `in`, `out`, and `ref` modifiers are part of a method’s signature, but the `params` modifier is not. *end note*
> *Note*: As described in [§7.5](basic-concepts.md#75-signatures-and-overloading), the `in`, `out`, and `ref` modifiers are part of a method’s signature, but the `params` and `scoped` modifiers are not. *end note*

#### 15.6.2.2 Value parameters

Expand Down Expand Up @@ -2378,6 +2387,8 @@ It is a compile-time error to modify the value of an input parameter.

> *Note*: The primary purpose of input parameters is for efficiency. When the type of a method parameter is a large struct (in terms of memory requirements), it is useful to be able to avoid copying the whole value of the argument when calling the method. Input parameters allow methods to refer to existing values in memory, while providing protection against unwanted changes to those values. *end note*

An input parameter may carry the `scoped` modifier (§scoped-modifier) or the `[UnscopedRef]` attribute (§UnscopedRefAttribute).

##### 15.6.2.3.3 Reference parameters

A parameter declared with a `ref` modifier is a ***reference parameter***. For definite-assignment rules, see [§9.2.6](variables.md#926-reference-parameters).
Expand Down Expand Up @@ -2441,14 +2452,18 @@ A parameter declared with a `ref` modifier is a ***reference parameter***. For d
>
> *end example*

For a `struct` type, within an instance method, instance accessor ([§12.2.1](expressions.md#1221-general)), or instance constructor with a constructor initializer, the `this` keyword behaves exactly as a reference parameter of the struct type ([§12.8.14](expressions.md#12814-this-access)).
For a `struct` type, within an instance method, instance accessor ([§12.2.1](expressions.md#1221-general)), or instance constructor with a constructor initializer, the `this` keyword behaves exactly as a reference parameter of the struct type ([§12.8.14](expressions.md#12814-this-access)). The `this` parameter of a struct instance method is implicitly `scoped ref` (§scoped-modifier).

A reference parameter may carry the `scoped` modifier (§scoped-modifier) or the `[UnscopedRef]` attribute (§UnscopedRefAttribute).

##### 15.6.2.3.4 Output parameters

A parameter declared with an `out` modifier is an ***output parameter***. For definite-assignment rules, see [§9.2.7](variables.md#927-output-parameters).

A method declared as an optional partial method ([§15.6.9.2](classes.md#15692-optional-partial-methods)) shall not have output parameters.

An output parameter is implicitly `scoped` (§scoped-modifier); the `[UnscopedRef]` attribute (§UnscopedRefAttribute) may be applied to widen its ref-safe-context.

> *Note*: Output parameters are typically used in methods that produce multiple return values. *end note*
<!-- markdownlint-disable MD028 -->

Expand Down
Loading
Loading