Clean edit pass on attributes #44513
Open
+111
−16
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Fixes dotnet#42850: Add a new page to reference attributes that cause the compiler to emit different IL modifiers instead of putting the attribute in the emitted IL.
Fixes dotnet#43109 Most of these have been added to the general page. A few are expressed in source differently, and were added to the new pseudo-attributes page.
Add a list of attributes that are written by the compiler that shouldn't be added in users' source code.
Some attributes weren't in the `displayName` element for the TOC. Review all of them and add them again.
Mostly fix anchors. The one C# 9 spec was never intended to be published.
dotnet-policy-service
bot
added
dotnet-fundamentals/svc
dotnet-networking/subsvc
labels
gewarren
approved these changes
Jan 24, 2025
|
|
||
| Beginning in C# 12, types, methods, and assemblies can be marked with the <xref:System.Diagnostics.CodeAnalysis.ExperimentalAttribute?displayProperty=nameWithType> to indicate an experimental feature. The compiler issues a warning if you access a method or type annotated with the <xref:System.Diagnostics.CodeAnalysis.ExperimentalAttribute>. All types declared in an assembly or module marked with the `Experimental` attribute are experimental. The compiler issues a warning if you access any of them. You can disable these warnings to pilot an experimental feature. | ||
|
|
||
| > [!WARNING] | ||
| > Experimental features are subject to changes. The APIs may change, or they may be removed in future updates. Including experimental features is a way for library authors to get feedback on ideas and concepts for future development. Use extreme caution when using any feature marked as experimental. | ||
| > Experimental features are subject to changes. The APIs can change, or they can be removed in future updates. Including experimental features is a way for library authors to get feedback on ideas and concepts for future development. Use extreme caution when using any feature marked as experimental. |
There was a problem hiding this comment.
Once #44436 is merged, we should interlink between https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/preview-apis#experimentalattribute and here.
| @@ -242,6 +253,22 @@ Overload resolution considers the two methods equally good for some argument typ | |||
|
|
|||
| All overloads with a lower priority than the highest overload priority are removed from the set of applicable methods. Methods without this attribute have the overload priority set to the default of zero. Library authors should use this attribute as a last resort when adding a new and better method overload. Library authors should have a deep understanding of how [Overload resolution](~/_csharplang/proposals/csharp-13.0/overload-resolution-priority.md#overload-resolution-priority) impacts choosing the better method. Otherwise, unexpected errors can result. | |||
|
|
|||
| ## EnumeratorCancellation attribute | |||
|
|
|||
| The <xref:System.Runtime.CompilerServices.EnumeratorCancellationAttribute?displayProperty=nameWithType> attribute specifies which parameter should receive the cancellation token from <xref:System.Collections.Generic.IAsyncEnumerable`1.GetAsyncEnumerator(System.Threading.CancellationToken)?displayProperty=fullName> API. It's part of the infrastructure for the [async streams](../../asynchronous-programming/generate-consume-asynchronous-stream.md) feature. | |||
There was a problem hiding this comment.
Suggested change
| The <xref:System.Runtime.CompilerServices.EnumeratorCancellationAttribute?displayProperty=nameWithType> attribute specifies which parameter should receive the cancellation token from <xref:System.Collections.Generic.IAsyncEnumerable`1.GetAsyncEnumerator(System.Threading.CancellationToken)?displayProperty=fullName> API. It's part of the infrastructure for the [async streams](../../asynchronous-programming/generate-consume-asynchronous-stream.md) feature. | |
| The <xref:System.Runtime.CompilerServices.EnumeratorCancellationAttribute?displayProperty=nameWithType> attribute specifies which parameter should receive the cancellation token from the <xref:System.Collections.Generic.IAsyncEnumerable`1.GetAsyncEnumerator(System.Threading.CancellationToken)?displayProperty=fullName> API. It's part of the infrastructure for the [async streams](../../asynchronous-programming/generate-consume-asynchronous-stream.md) feature. |
|
|
||
| ## CollectionBuilder attribute | ||
|
|
||
| The <xref:System.Runtime.CompilerServices.CollectionBuilderAttribute?displayProperty=nameWithType> specifies a method that builds an instance of a collection type from a [collection expression](../operators/collection-expressions.md). You use this attribute to specify a method that builds the collection. The compiler generates code to call that method when a collection expression is converted to that type. |
There was a problem hiding this comment.
Suggested change
| The <xref:System.Runtime.CompilerServices.CollectionBuilderAttribute?displayProperty=nameWithType> specifies a method that builds an instance of a collection type from a [collection expression](../operators/collection-expressions.md). You use this attribute to specify a method that builds the collection. The compiler generates code to call that method when a collection expression is converted to that type. | |
| The <xref:System.Runtime.CompilerServices.CollectionBuilderAttribute?displayProperty=nameWithType> attribute specifies a method that builds an instance of a collection type from a [collection expression](../operators/collection-expressions.md). You use this attribute to specify a method that builds the collection. The compiler generates code to call that method when a collection expression is converted to that type. |
| --- | ||
| # Custom attributes that generate flags or options in the Intermediate Language (IL) output | ||
|
|
||
| You add these attributes to your code for the compiler to emit specified Intermediate Language (IL) modifier. These attributes instruct the compiler to include the corresponding IL modifier in the output. These IL modifiers can be controlled in C# using these attributes: |
There was a problem hiding this comment.
Suggested change
| You add these attributes to your code for the compiler to emit specified Intermediate Language (IL) modifier. These attributes instruct the compiler to include the corresponding IL modifier in the output. These IL modifiers can be controlled in C# using these attributes: | |
| You add these attributes to your code for the compiler to emit a specified Intermediate Language (IL) modifier. These attributes instruct the compiler to include the corresponding IL modifier in the output. |
There was a problem hiding this comment.
Seemed a bit repetitive so I removed the last sentence.
|
|
||
| You add these attributes to your code for the compiler to emit specified Intermediate Language (IL) modifier. These attributes instruct the compiler to include the corresponding IL modifier in the output. These IL modifiers can be controlled in C# using these attributes: | ||
|
|
||
| - <xref:System.Runtime.InteropServices.ComImportAttribute?displayProperty=fullName>: Specifies the `import` modifier. |
There was a problem hiding this comment.
This might be nice as a table with the attribute in one column, the modifier in the second, and perhaps comments in a third column. Just a suggestion though.
|
|
||
| Some of these custom attributes are applied using other C# syntax rather than adding the attribute to your source code. | ||
|
|
||
| - <xref:System.Runtime.InteropServices.DefaultParameterValueAttribute?displayProperty=fullName>: Specifies the default value for the parameter. Use the [default parameter syntax](../../methods.md#optional-parameters-and-arguments) |
There was a problem hiding this comment.
Suggested change
| - <xref:System.Runtime.InteropServices.DefaultParameterValueAttribute?displayProperty=fullName>: Specifies the default value for the parameter. Use the [default parameter syntax](../../methods.md#optional-parameters-and-arguments) | |
| - <xref:System.Runtime.InteropServices.DefaultParameterValueAttribute?displayProperty=fullName>: Specifies the default value for the parameter. Use the [default parameter syntax](../../methods.md#optional-parameters-and-arguments). |
|
|
||
| - <xref:System.Runtime.InteropServices.DefaultParameterValueAttribute?displayProperty=fullName>: Specifies the default value for the parameter. Use the [default parameter syntax](../../methods.md#optional-parameters-and-arguments) | ||
| - <xref:System.Runtime.InteropServices.InAttribute?displayProperty=fullName>: Specifies the IL `[in]` modifier. Use the [`in`](../keywords/method-parameters.md#in-parameter-modifier) or [`ref readonly`](../keywords/method-parameters.md#ref-readonly-modifier). | ||
| - <xref:System.Runtime.CompilerServices.SpecialNameAttribute?displayProperty=fullName>: Specifies the IL `specialname` modifier. The compiler automatically uses the for methods that require the `specialname` modifier. |
There was a problem hiding this comment.
"the for methods" is correct?
| - <xref:System.Runtime.InteropServices.DefaultParameterValueAttribute?displayProperty=fullName>: Specifies the default value for the parameter. Use the [default parameter syntax](../../methods.md#optional-parameters-and-arguments) | ||
| - <xref:System.Runtime.InteropServices.InAttribute?displayProperty=fullName>: Specifies the IL `[in]` modifier. Use the [`in`](../keywords/method-parameters.md#in-parameter-modifier) or [`ref readonly`](../keywords/method-parameters.md#ref-readonly-modifier). | ||
| - <xref:System.Runtime.CompilerServices.SpecialNameAttribute?displayProperty=fullName>: Specifies the IL `specialname` modifier. The compiler automatically uses the for methods that require the `specialname` modifier. | ||
| - <xref:System.Runtime.InteropServices.UnmanagedCallersOnlyAttribute?displayProperty=nameWithType>: This attribute is required for the `delegate*` feature. The compiler adds it to any [`delegate*`](../unsafe-code.md#function-pointers) requires its use. |
There was a problem hiding this comment.
Suggested change
| - <xref:System.Runtime.InteropServices.UnmanagedCallersOnlyAttribute?displayProperty=nameWithType>: This attribute is required for the `delegate*` feature. The compiler adds it to any [`delegate*`](../unsafe-code.md#function-pointers) requires its use. | |
| - <xref:System.Runtime.InteropServices.UnmanagedCallersOnlyAttribute?displayProperty=nameWithType>: This attribute is required for the `delegate*` feature. The compiler adds it to any [`delegate*`](../unsafe-code.md#function-pointers) that requires its use. |
| - <xref:System.Runtime.CompilerServices.IsUnmanagedAttribute?displayProperty=fullName> - This attribute specifies the `unmanaged` constraint on a type parameter. | ||
| - <xref:System.Runtime.CompilerServices.NullableAttribute?displayProperty=fullName>, <xref:System.Runtime.CompilerServices.NullableContextAttribute?displayProperty=fullName>, <xref:System.Runtime.CompilerServices.NullablePublicOnlyAttribute?displayProperty=fullName>: These attributes encode nullable annotations in your source code. | ||
| - <xref:System.ParamArrayAttribute?displayProperty=fullName>: This attribute encodes the `params` modifier on array parameters. | ||
| - <xref:System.Runtime.CompilerServices.ParamCollectionAttribute?displayProperty=fullName> This attribute encodes the `params` on non-array parameters. |
There was a problem hiding this comment.
Suggested change
| - <xref:System.Runtime.CompilerServices.ParamCollectionAttribute?displayProperty=fullName> This attribute encodes the `params` on non-array parameters. | |
| - <xref:System.Runtime.CompilerServices.ParamCollectionAttribute?displayProperty=fullName> This attribute encodes the `params` modifier on non-array parameters. |
| - <xref:System.Runtime.CompilerServices.RequiredMemberAttribute?displayProperty=fullName>: This attribute indicates that the `required` modifier was placed on a member declaration. It's the encoding of the [required members](../keywords/required.md) language feature. | ||
| - <xref:System.Runtime.CompilerServices.TupleElementNamesAttribute?displayProperty=fullName>: This attribute encodes tuple element names used in signatures. | ||
|
|
||
| In addition, the compiler can generate a declaration for other attributes used internally. For this reason, you should assume other attributes in the <xref:System.Runtime.CompilerServices> namespace. Some aren't in the .NET Runtime. Instead, the compiler synthesizes a definition for an `internal` type declaration in any assembly where the attribute is needed. |
There was a problem hiding this comment.
Second sentence is incomplete.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #42850: Add a new page to reference attributes that cause the compiler to emit different IL modifiers instead of putting the attribute in the emitted IL.
Fixes #43109: Most of these have been added to the general page. A few are expressed in source differently, and were added to the new pseudo-attributes page.
Fixes #43110: Add a list of attributes that are written by the compiler that shouldn't be added in users' source code.
Internal previews