Extensions: allow cref references to extension members #78735

jcouv · 2025-05-28T20:27:28Z

Relates to test plan #76130
Review of public API: #78738

jcouv · 2025-05-29T17:28:14Z

...Compilers/CSharp/Portable/DocumentationComments/DocumentationCommentIDVisitor.PartVisitor.cs

                }

-                builder.Append(symbol.IsExtension ? symbol.ExtensionName : symbol.Name);
+                builder.Append(symbol.IsExtension ? escape(symbol.ExtensionName) : symbol.Name);


📝 I debated whether to escape here, or push that responsibility to the caller of DocumentationCommentIDVisitor. What do you think? #Resolved

Since we replace </> with {/} for type argument list below, it probably makes sense to avoid using them here as well.

I did some additional thinking about this issue. Now, I think we need to consider possible usage scenarios for the ids that we produce here. What users actually might want to do with them. On one hand, the ids are included into an XML document and reserved XML characters must be replaced with XML entities inside the document. On the other hand, if I am not mistaken, when an XML document is read by an XML reader, the reader replaces the XML entities back to the corresponding characters. Is there a scenario when one tries to match an id gotten from an XML reader with an id that we produce here and exposing through GetDocumentationCommentId API? Or vise versa? If so, doing this transformation here is not the right thing to do. The replacement for </> with {/} for type argument lists is different, it doesn't involve XML entities, an XML reader wouldn't reverse it.

I am leaning towards doing one of the following:

Moving this "escaping" to the step that serializes an XML document. Basically, during serialization all ids should be checked for presence of </> and they should be replaced with corresponding XML entities.

Or we can by pass the problem by simply avoiding using reserved XML characters in unspeakable extension names that we generate.

One additional data point: in error scenarios, we already escape CREF strings in ToBadCrefString (that's done outside of GetDocumentationCommentId.
I'll move the escaping outside for now. We can discuss the other option (using a different unspeakable name) in WG.

AlekseyTs · 2025-05-30T13:59:51Z

src/Compilers/CSharp/Portable/Syntax/Syntax.xml

+    <Field Name="DotToken" Type="SyntaxToken">
+      <Kind Name="DotToken"/>
+    </Field>
+    <Field Name="Member" Type="MemberCrefSyntax"/>


"MemberCrefSyntax"

This feels too flexible. For example, this cannot be ExtensionMemberCrefSyntax. Could we restrict allowed nodes by kind? If not, perhaps for the syntax model it is fine as is. Is there a corresponding proposal for the grammar change?
#Closed

The member cref syntax currently covered name members, indexers, operators and conversion operators. We'll need all those as extension members at some point.
I think the only questionable scenario then is nested extensions.

If we really care to block this in the syntax model, I think we'd need to create an additional level in the hierarchy:
MemberCrefSyntax <- NonExtensionCrefSyntax <- (existing types for named members, indexers, etc)
Then ExtensionMemberCrefSyntax would only hold a NonExtensionCrefSyntax as its member.

I think such model seems a bit overkill and the flexibility doesn't disturb me. We can just restrict the scenario in the parser...
This is scheduled for discussion in API review tomorrow.

Is there a corresponding proposal for the grammar change?

Not yet. I didn't find a spec baseline for the CREF grammar... The Annex D section is as close as it gets.

It looks like the following question was not answered:

Could we restrict allowed nodes by kind?

I was specifically asking about an ability to restrict nodes by kind in this description. For example, like we do this for tokens:

<Field Name="ExtensionKeyword" Type="SyntaxToken"> <Kind Name="ExtensionKeyword"/> </Field>

Thanks for the clarification. Adding <Kind Name="NameMemberCrefSyntax"/> to the Member doesn't do anything even after regenerating compiler code. WriteGreenFactory only validates Kind on fields of type SyntaxToken.
I'll block the nested scenario by adding an error in parser.

AlekseyTs · 2025-05-30T14:16:18Z

src/Compilers/CSharp/Portable/Parser/DocumentationCommentParser.cs

+            }
+
+            SyntaxToken dotToken = EatToken(SyntaxKind.DotToken);
+            MemberCrefSyntax member = ParseMemberCref();


ParseMemberCref()

It looks like this is going to allow an indirect recursion, which is not expected. #Closed

There was no response to this comment. To clarify, I think we need to restrict the parsing and not accept nested extensions even if our syntax nodes technically allow creating such a hierarchy.

AlekseyTs · 2025-05-30T14:28:50Z

src/Compilers/CSharp/Portable/Binder/Binder_Crefs.cs

+
+                TypeArgumentListSyntax? extensionTypeArguments = syntax.TypeArgumentList;
+                int extensionArity = extensionTypeArguments?.Arguments.Count ?? 0;
+                sortedSymbols = computeSortedAndFilteredCrefExtensionMembers(namedContainer, simpleName.Identifier.ValueText, extensionArity, arity, extensionTypeArguments, diagnostics, syntax);


ValueText

Do we have a test with escaped identifier at this position? #Closed

AlekseyTs · 2025-05-30T14:35:16Z

src/Compilers/CSharp/Portable/Binder/Binder_Crefs.cs

+            if (sortedSymbols.IsDefaultOrEmpty)
+            {
+                ambiguityWinner = null;
+                return [];


return [];

Consider leaving a follow up comment to handle operators. #Closed

AlekseyTs · 2025-05-30T14:46:07Z

src/Compilers/CSharp/Portable/Binder/Binder_Crefs.cs

+                         refCustomModifiers: [],
+                         explicitInterfaceImplementations: []);
+
+                    ImmutableArray<ParameterSymbol> extensionParameterSymbols = syntax.Parameters is { } extensionParameterListSyntax ? BindCrefParameters(extensionParameterListSyntax, diagnostics) : default;


syntax.Parameters is { } extensionParameterListSyntax

Can this be false? #Closed

AlekseyTs · 2025-05-30T14:49:09Z

src/Compilers/CSharp/Portable/Binder/Binder_Crefs.cs

+
+                    var constructedNested = (NamedTypeSymbol)ConstructWithCrefTypeParameters(extensionArity, extensionTypeArguments, nested);
+
+                    var candidateExtensionSignature = new SignatureOnlyMethodSymbol(


var candidateExtensionSignature = new SignatureOnlyMethodSymbol(

Consider adding a comment that we are using signature method symbols to match extension blocks #Closed

AlekseyTs · 2025-05-30T14:51:12Z

src/Compilers/CSharp/Portable/Binder/Binder_Crefs.cs

+
+                    ImmutableArray<ParameterSymbol> extensionParameterSymbols = syntax.Parameters is { } extensionParameterListSyntax ? BindCrefParameters(extensionParameterListSyntax, diagnostics) : default;
+
+                    var providedExtensionSignature = new SignatureOnlyMethodSymbol(


providedExtensionSignature

It looks like we can initialize outside of the loop #Closed

We need an arity which is specific to an iteration of the loop

We need an arity which is specific to an iteration of the loop

Don't we make sure nested.Arity == extensionArity when we reach this point, and extensionArity doesn't change in the loop?

AlekseyTs · 2025-05-30T14:52:34Z

src/Compilers/CSharp/Portable/Binder/Binder_Crefs.cs

+                         refCustomModifiers: [],
+                         explicitInterfaceImplementations: []);
+
+                    ImmutableArray<ParameterSymbol> extensionParameterSymbols = syntax.Parameters is { } extensionParameterListSyntax ? BindCrefParameters(extensionParameterListSyntax, diagnostics) : default;


BindCrefParameters(extensionParameterListSyntax, diagnostics)

It looks like we should attempt to bind parameters even when the enclosing loop never reaches this line. #Closed

AlekseyTs · 2025-05-30T15:06:13Z

src/Compilers/CSharp/Portable/Compilation/CSharpSemanticModel.cs

                case SyntaxKind.ConversionOperatorMemberCref:
                    return ((ConversionOperatorMemberCrefSyntax)crefSyntax).Parameters != null;
+                case SyntaxKind.ExtensionMemberCref:
+                    return HasParameterList(((ExtensionMemberCrefSyntax)crefSyntax).Member);


return HasParameterList(((ExtensionMemberCrefSyntax)crefSyntax).Member);

What about ExtensionMemberCrefSyntax.Parameters? #Closed

Parameters on extension are intentionally not considered here.
The value from HasParameterList affects the result kind from GetCrefSymbolInfo below, to report "ambiguous" vs. "overload resolution failure". In E.extension(int).M... we only allow the last parameter list to be omitted, so the presence/absence of the parameter list on extension is not relevant to was result kind we report.

AlekseyTs · 2025-05-30T15:19:17Z

src/Compilers/CSharp/Test/Syntax/Parsing/CrefParsingTests.cs

+                        N(SyntaxKind.CloseParenToken);
+                    }
+                    N(SyntaxKind.DotToken);
+                    N(SyntaxKind.ExtensionMemberCref);


N(SyntaxKind.ExtensionMemberCref);

The nested ExtensionMemberCref feels wrong #Closed

AlekseyTs · 2025-05-30T15:21:44Z

src/Compilers/CSharp/Test/Emit3/Semantics/ExtensionTests.cs

            //         void I.M() { }
-            Diagnostic(ErrorCode.ERR_ExplicitInterfaceImplementationInNonClassOrStruct, "M").WithArguments("Extensions.extension(object).M()").WithLocation(10, 16));
+            Diagnostic(ErrorCode.ERR_ExplicitInterfaceImplementationInNonClassOrStruct, "M").WithArguments("Extensions.extension(object).M()").WithLocation(10, 16),
+            // (10,16): error CS9282: Extension declarations can include only methods or properties


// (10,16): error CS9282: Extension declarations can include only methods or properties

Technically this error reported for a method. #Closed

AlekseyTs · 2025-05-30T15:36:49Z

src/Compilers/CSharp/Test/Emit3/Semantics/ExtensionTests2.cs

+    public void Cref_44()
+    {
+        var src = """
+/// <see cref="extension(int).M"/>


extension(int).M

Do we have a test for a success scenario with syntax like that? #Closed

I don't think that's possible. If extension(int) is interpreted as a reference to an extension block, then it's an error (shown). If it's interpreted as a named member cref, it would refer to a method and the .M would therefore fail to bind.

Do we have a test for a success scenario with syntax like that?

I don't think that's possible.

Even when it is used on or inside the static class containing the target extension block? Could you please add tests like that nonetheless

AlekseyTs · 2025-05-30T15:38:09Z

src/Compilers/CSharp/Test/Emit3/Semantics/ExtensionTests2.cs

+/// <see cref="E.extension(int).M2"/>
+static class E
+{
+    extension(int i)


extension(int i)

Consider adding a test where ambiguous candidates are in different blocks. #Closed

AlekseyTs · 2025-05-30T15:38:53Z

Done with review pass (commit 1) #Closed

AlekseyTs · 2025-06-02T13:35:37Z

...Compilers/CSharp/Portable/DocumentationComments/DocumentationCommentIDVisitor.PartVisitor.cs

                }

-                builder.Append(symbol.IsExtension ? symbol.ExtensionName : symbol.Name);
+                builder.Append(symbol.IsExtension ? escape(symbol.ExtensionName) : symbol.Name);


escape(symbol.ExtensionName)

It looks like now one can refer to an extension type by name across assembly boundaries. I.e. doc comments for one assembly can refer to an extension type defined in a different assembly by using its unspeakable name. BTW, are we testing this scenario? Should a reference like this be considered a subject for a binary breaking change when a source change in the referenced assembly causes a change in the unspeakable name? #Closed

Should a reference like this be considered a subject for a binary breaking change when a source change in the referenced assembly causes a change in the unspeakable name?

I have a follow-up to discuss with WG: "Are extension metadata names problematic for versioning docs?".
Yes, I think the current scheme means that shuffling extensions around breaks CREF/XML doc consumers.

AlekseyTs · 2025-06-04T13:32:31Z

src/Compilers/CSharp/Test/Emit3/Semantics/ExtensionTests2.cs

+        var comp = CreateCompilation(src, parseOptions: TestOptions.RegularPreviewWithDocumentationComments);
+        comp.VerifyEmitDiagnostics(
+            // (10,24): warning CS1574: XML comment has cref attribute 'M(string)' that could not be resolved
+            //         /// <see cref="M(string)"/>


///

Should this work instead? Let's capture a design question. #Closed

Confirmed with Mads over email thread

AlekseyTs · 2025-06-04T13:34:00Z

src/Compilers/CSharp/Test/Emit3/Semantics/ExtensionTests2.cs

+            // /// <see cref="E2.extension()"/>
+            Diagnostic(ErrorCode.WRN_BadXMLRef, "E2.extension()").WithArguments("extension()").WithLocation(9, 16),
+            // (10,16): warning CS1574: XML comment has cref attribute 'extension(int)' that could not be resolved
+            // /// <see cref="E2.extension(int)"/>


// ///

Let's capture a design question whether this should work #Closed

Resolved in LDM today

AlekseyTs · 2025-06-04T13:36:45Z

src/Compilers/CSharp/Test/Emit3/Semantics/ExtensionTests2.cs

+    [Fact]
+    public void Cref_47()
+    {
+        // TODO2 error in Ioperation 


// TODO2 error in Ioperation

Is the comment still relevant? #Closed

AlekseyTs · 2025-06-04T13:41:51Z

src/Compilers/CSharp/Test/Emit3/Semantics/ExtensionTests2.cs

+{
+    extension(int)
+    {
+        /// <see cref="extension(int).M2"/>


///

It looks like we are missing a test covering usage of cref like this outside the extension block, but inside class E. For example, on another extension block, on a method declaration, etc. #Closed

Also on class E itself.

AlekseyTs · 2025-06-04T13:45:31Z

Done with review pass (commit 5)

AlekseyTs

LGTM (commit 10)

jjonescz · 2025-06-11T08:37:42Z

src/Compilers/CSharp/Test/Emit3/Semantics/ExtensionTests2.cs

+    {
+        var src = """
+/// <see cref="E.extension(int).M(string)"/>
+/// <see cref="E.M(int, string)"/>


Consider testing E.M(string) as well #Resolved

jjonescz · 2025-06-11T09:18:02Z

src/Compilers/CSharp/Portable/Binder/Binder_Crefs.cs

+        private ImmutableArray<Symbol> BindExtensionMemberCref(ExtensionMemberCrefSyntax syntax, NamespaceOrTypeSymbol? containerOpt, out Symbol? ambiguityWinner, BindingDiagnosticBag diagnostics)
+        {
+            // Tracked by https://github.com/dotnet/roslyn/issues/76130 : handle extension operators
+            CheckFeatureAvailability(syntax, MessageID.IDS_FeatureExtensions, diagnostics);


Is there a test for this langversion check? #Resolved

See Cref_54

jjonescz · 2025-06-11T09:30:52Z

src/Compilers/CSharp/Portable/Parser/DocumentationCommentParser.cs

+            Debug.Assert(CurrentToken.ContextualKind == SyntaxKind.ExtensionKeyword);
+
+            SyntaxToken identifierToken = EatToken();
+            TypeArgumentListSyntax? typeArguments = (CurrentToken.Kind == SyntaxKind.LessThanToken) ? ParseTypeArguments(typeArgumentsMustBeIdentifiers: true) : null;


Do we have a test for errors produced by typeArgumentsMustBeIdentifiers: true? #Resolved

See Cref_43

jcouv self-assigned this May 28, 2025

jcouv added Area-Compilers Feature - Extension Everything The extension everything feature labels May 28, 2025

jcouv force-pushed the extensions-cref branch from 34b59c7 to 34ef1fb Compare May 28, 2025 21:34

dotnet-policy-service bot added the Needs API Review Needs to be reviewed by the API review council label May 28, 2025

jcouv mentioned this pull request May 28, 2025

Extensions: public API for extension syntax in CREF #78738

Closed

Extensions: allow cref references to extension members

15fdb0b

jcouv force-pushed the extensions-cref branch from 34ef1fb to 15fdb0b Compare May 28, 2025 23:01

jcouv commented May 29, 2025

View reviewed changes

jcouv marked this pull request as ready for review May 29, 2025 17:30

jcouv requested review from a team as code owners May 29, 2025 17:30

AlekseyTs reviewed May 30, 2025

View reviewed changes

This was referenced May 30, 2025

Compiler crash generating XML docs for extension #78768

Closed

Update XML output for extensions dotnet/csharplang#9416

Draft

AlekseyTs reviewed Jun 2, 2025

View reviewed changes

Address feedback

e6876dd

AlekseyTs reviewed Jun 4, 2025

View reviewed changes

jcouv marked this pull request as draft June 4, 2025 21:11

Julien Couvreur added 3 commits June 9, 2025 18:31

Reflect LDM decisions

015a342

Address feedback

e59e48c

Remove comment

9a29064

jcouv marked this pull request as ready for review June 10, 2025 04:07

Merge remote-tracking branch 'dotnet/main' into extensions-cref

26f047b

jcouv requested a review from AlekseyTs June 10, 2025 04:29

Tweaks

5d277a9

AlekseyTs approved these changes Jun 10, 2025

View reviewed changes

jcouv requested a review from jjonescz June 10, 2025 18:08

jjonescz approved these changes Jun 11, 2025

View reviewed changes

Add test

abdae5b

jcouv enabled auto-merge (squash) June 11, 2025 21:03

Merge remote-tracking branch 'dotnet/main' into extensions-cref

f02ef4f

jcouv disabled auto-merge June 12, 2025 16:38

jcouv enabled auto-merge (squash) June 12, 2025 18:09

jcouv merged commit 345419e into dotnet:main Jun 12, 2025
27 of 28 checks passed

dotnet-policy-service bot added this to the Next milestone Jun 12, 2025

dotnet-bot mentioned this pull request Jun 14, 2025

[Automated] PRs inserted in VS build main-10713.56 #78974

Closed

dotnet-bot mentioned this pull request Jun 17, 2025

[Automated] PRs inserted in VS build feature.debugger.main-10716.51 #78998

Closed

dotnet-bot mentioned this pull request Jun 17, 2025

[Automated] PRs inserted in VS build feature.Wix5-10716.138 #79003

Closed

RikkiGibson modified the milestones: Next, 18.0 P1 Aug 19, 2025


		var constructedNested = (NamedTypeSymbol)ConstructWithCrefTypeParameters(extensionArity, extensionTypeArguments, nested);

		var candidateExtensionSignature = new SignatureOnlyMethodSymbol(


		ImmutableArray<ParameterSymbol> extensionParameterSymbols = syntax.Parameters is { } extensionParameterListSyntax ? BindCrefParameters(extensionParameterListSyntax, diagnostics) : default;

		var providedExtensionSignature = new SignatureOnlyMethodSymbol(

Extensions: allow cref references to extension members #78735

Extensions: allow cref references to extension members #78735

Uh oh!

Conversation

jcouv commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jcouv May 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlekseyTs May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

jcouv commented May 28, 2025 •

edited

Loading

jcouv May 29, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs May 30, 2025 •

edited

Loading

AlekseyTs commented May 30, 2025 •

edited

Loading

AlekseyTs Jun 2, 2025 •

edited

Loading

AlekseyTs Jun 4, 2025 •

edited

Loading

AlekseyTs Jun 4, 2025 •

edited

Loading

AlekseyTs Jun 4, 2025 •

edited

Loading

AlekseyTs Jun 4, 2025 •

edited

Loading

jjonescz Jun 11, 2025 •

edited by jcouv

Loading

jjonescz Jun 11, 2025 •

edited by jcouv

Loading