Support marking generated public APIs as experimental #82131

333fred · 2026-01-23T20:24:09Z

We now mark preview language feature public APIs as experimental before the language version ships fully. As demonstration, I've marked the collection expression arguments public APIs as experimental, so we can see what this actually looks like.

…ssary.

jasonmalinowski

Let a few comments at least. My biggest high level thought is whether we should just be suppressing the experimental warning for our entire codebase; since if we build together and ship together, I'm not sure we're getting any benefit for it. (The attribute absolutely makes sense for other projects!)

jasonmalinowski · 2026-01-24T00:11:52Z

src/Compilers/Core/Portable/InternalUtilities/RoslynExperiments.cs

    internal const string GeneratorHostOutputs = "RSEXPERIMENTAL004";
    internal const string GeneratorHostOutputs_Url = "https://github.com/dotnet/roslyn/issues/74753";

+    // The URL is customized per-api to point at the test plan for the feature


Seeing this comment made me think 'which URL?' Given the other examples in this file I expected to see a URL here; maybe it's expanding on this comment a bit.

src/Features/CSharp/Portable/Completion/CompletionProviders/NamedParameterCompletionProvider.cs

src/Tools/Source/CompilerGeneratorTools/Source/IOperationGenerator/IOperationClassWriter.cs

src/Compilers/CSharp/Portable/Syntax/Syntax.xsd

333fred · 2026-01-24T00:25:44Z

My biggest high level thought is whether we should just be suppressing the experimental warning for our entire codebase; since if we build together and ship together, I'm not sure we're getting any benefit for it.

No. This will help ensure that manually-written public APIs that include the API are also marked Experimental. #Closed

jcouv · 2026-01-24T19:21:21Z

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

                        (node is ExpressionSyntax && (isSpeculative || allowNamedArgumentName || !SyntaxFacts.IsNamedArgumentName(node))) ||
                        (node is ConstructorInitializerSyntax
                              or PrimaryConstructorBaseTypeSyntax
+#pragma warning disable RSEXPERIMENTAL006 // With Element: https://github.com/dotnet/roslyn/issues/80613


Could we instead suppress this warning globally within the compiler codebase?
That would avoid sprinkling of suppressions and would make it much easier for the PR that adds a new LangVer #Closed

No. The non-suppressed global warning helped me catch manually-written public APIs that also need to be marked as Experimental. We could consider suppressing it in test projects/IDE, but I very much do not think we should do so in the main compiler codebase.

The non-suppressed global warning helped me catch manually-written public APIs that also need to be marked as Experimental.

How exactly did that help you?

jcouv · 2026-01-24T19:25:10Z

src/Compilers/CSharp/Test/CommandLine/CommandLineTests.cs

            // - [ ] update _MaxAvailableLangVersion cap (a relevant test should break when new version is introduced)
            // - [ ] update the "UpgradeProject" codefixer
+            // - [ ] Remove the `Experimental` section from any entries being shipped in Syntax.xml and OperationInterfaces.xml, and rerun the generator
+            // - [ ] Search the codebase for the URLs that were linked in the Syntax.xml and OperationInterfaces.xml files and remove suppressions or attributes added for those issues.


I'm hoping we can remove this work item by using a global suppression for the compiler codebase #Closed

No. See previous comment.

Can we remove this work item now that we've landed decision to suppress globally?

We can adjust it, not remove it. Some APIs may still need to be adjusted because they were manually marked.

Search the codebase for the URLs [...] and remove suppressions

URLs wouldn't be linked in the suppressions, right?

src/Compilers/CSharp/Test/CommandLine/CommandLineTests.cs

jcouv · 2026-01-24T19:32:42Z

This will help ensure that manually-written public APIs that include the API are also marked Experimental.

I can think of two cases:

INamedTypeSymbol.IsExtension: I don't know that local suppression would help remind us to mark this as Experimental
GetCreationMethods(WithElementSyntax, ...): local suppression means we'd be reminded to mark this as Experimental, but since the WithElementSyntax is already marked as Experimental, any callers would already be notified

I'm still in favor of a global suppression, but maybe we could pick a few files (those where we put public APIs) to re-enable the warning?

In reply to: 3793141614

jcouv · 2026-01-24T19:36:07Z

A possible middle-ground: we add file-level suppression for files with internal types (Binder, SemanticModel, etc) and all our test projects to reduce need for local suppressions

In reply to: 3795392872

src/Tools/Source/CompilerGeneratorTools/Source/IOperationGenerator/IOperationClassWriter.cs

jcouv

Done with review pass (commit 5)

src/Compilers/Core/Portable/Operations/OperationInterfaces.xml

src/Compilers/Core/Portable/Generated/FlowAnalysis.Generated.cs

src/Compilers/Core/Portable/Generated/OperationKind.Generated.cs

AlekseyTs · 2026-01-28T16:36:44Z

src/Compilers/CSharp/Portable/Syntax/Syntax.xsd

            <xs:complexType>
              <xs:attribute name="Name" type="xs:string" use="required" />
              <xs:attribute name="Base" type="xs:string" use="required" />
+              <xs:attribute name="ExperimentalUrl" type="xs:string" use="optional" />


<xs:attribute name="ExperimentalUrl" type="xs:string" use="optional" />

Is this file maintained manually? If so, why do we need it?

It is maintained manually. It predates my time here, and presumably provides completion for the XML structure in Syntax.xml. If we decide we don't want it, that's ok with me, but I think that should be a separate PR. For now, I'm going to keep this as is and update appropriately.

Yes, it's used for that. I think the checker also uses this to validate the structure of the XML too?

AlekseyTs · 2026-01-28T16:43:26Z

@333fred I think it would be good to provide a general description:

How an experimental APIs is supposed to be marked. I.e. what constitutes a properly parked experimental API
What artifacts should be placed and where they should be placed in order to achieve proper marking of generated APIs.

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

AlekseyTs · 2026-01-28T17:06:59Z

I very much dislike the suppressions sprinkled throughout the code base and would like to understand what benefits they provide by comparison to a global suppression. #Closed

AlekseyTs · 2026-01-28T17:07:24Z

Done with review pass (commit 6) #Closed

…d more details.

333fred · 2026-01-29T20:17:32Z

@dotnet/roslyn-compiler for review

AlekseyTs · 2026-01-29T20:44:53Z

It looks like there are some related CI errors

AlekseyTs · 2026-01-29T20:45:08Z

Done with review pass (commit 10)

This reverts commit 1bbf7d9.

jcouv · 2026-01-29T22:47:25Z

src/Compilers/Core/Portable/Generated/FlowAnalysis.Generated.cs

 // See the LICENSE file in the project root for more information.
 // < auto-generated />
 #nullable enable
+#pragma warning disable RSEXPERIMENTAL006 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.


Do we still need this suppression given the suppression editorconfig?
Also applies to other generated files #Closed

I can remove it from the iop trees, but not the syntax generator ones, since those actually use source generation and the .editorconfig value does not apply to them.

jcouv · 2026-01-29T22:49:31Z

src/Compilers/CSharp/Portable/PublicAPI.Unshipped.txt

-static Microsoft.CodeAnalysis.CSharp.SyntaxFactory.WithElement(Microsoft.CodeAnalysis.SyntaxToken withKeyword, Microsoft.CodeAnalysis.CSharp.Syntax.ArgumentListSyntax! argumentList) -> Microsoft.CodeAnalysis.CSharp.Syntax.WithElementSyntax!
-virtual Microsoft.CodeAnalysis.CSharp.CSharpSyntaxVisitor.VisitWithElement(Microsoft.CodeAnalysis.CSharp.Syntax.WithElementSyntax! node) -> void
-virtual Microsoft.CodeAnalysis.CSharp.CSharpSyntaxVisitor<TResult>.VisitWithElement(Microsoft.CodeAnalysis.CSharp.Syntax.WithElementSyntax! node) -> TResult?
+[RSEXPERIMENTAL006]Microsoft.CodeAnalysis.CSharp.Syntax.WithElementSyntax


Should the SyntaxKind above bet considered experimental too?

jcouv · 2026-01-29T22:55:37Z

src/Compilers/Core/Portable/PublicAPI.Unshipped.txt

 Microsoft.CodeAnalysis.IPropertySymbol.ReduceExtensionMember(Microsoft.CodeAnalysis.ITypeSymbol! receiverType) -> Microsoft.CodeAnalysis.IPropertySymbol?
-Microsoft.CodeAnalysis.OperationKind.CollectionExpressionElementsPlaceholder = 129 -> Microsoft.CodeAnalysis.OperationKind
-Microsoft.CodeAnalysis.Operations.ICollectionExpressionElementsPlaceholderOperation
+[RSEXPERIMENTAL006]Microsoft.CodeAnalysis.OperationKind.CollectionExpressionElementsPlaceholder = 129 -> Microsoft.CodeAnalysis.OperationKind


Should ConstructArguments below be marked as experimental?

This appears to be a bug in the analyzer. It is marked as experimental: https://github.com/dotnet/roslyn/pull/82131/changes#diff-4f30dad78155dc7e2f28813d10dab3bb825c845d1f14233117a362615aa83343R3972-R3973

I've fixed the bug in the PR, but since we reference the package via nuget, not via a project reference, consuming the bugfix will need to wait for the next time we bump this.

jcouv

Done with review pass (commit 11)

…g properties.

jasonmalinowski · 2026-01-30T01:08:02Z

src/Tools/Source/CompilerGeneratorTools/Source/IOperationGenerator/IOperationClassWriter.cs


+                if (!string.IsNullOrEmpty(experimentalUrl))
+                {
+                    WriteLine($"[Experimental(global::Microsoft.CodeAnalysis.RoslynExperiments.PreviewLanguageFeatureApi, UrlFormat = {QuoteString(experimentalUrl)})]");


I think this is the same as WriteExperimentalAttribute? And then delete QuoteString since this might be the only user?

jjonescz · 2026-01-30T14:41:42Z

docs/contributing/Compiler Test Plan.md

-    - Any time the compiler reads in metadata containing crypto hashes, even if it's an attribute value, ensure the crypto hash algorithm name is included in the metadata (e.g. prefixing it to the hash value), so that it can be changed over time and the compiler can continue to read both metadata using both the old and new algorithms.
+- All newly added APIs are experimental
+    - Tracking issue for marking APIs as non-experimental
+    - APIs are marked with `[Experimental(RoslynExperiments.PreviewLanguageFeatureApi, UrlFormat = @"link to tracking issue")]`


I wouldn't expect backslashes in the URL

Suggested change

- APIs are marked with `[Experimental(RoslynExperiments.PreviewLanguageFeatureApi, UrlFormat = @"link to tracking issue")]`

- APIs are marked with `[Experimental(RoslynExperiments.PreviewLanguageFeatureApi, UrlFormat = "link to tracking issue")]`

jjonescz · 2026-01-30T14:47:00Z

.editorconfig

 dotnet_diagnostic.xUnit2029.severity = none

+# RS0006: Roslyn experimental language API
+dotnet_diagnostic.RSEXPERIMENTAL006.severity = none


Did you consider putting this into a .globalconfig file instead? Then we wouldn't need separate suppressions in source-generated files.

jjonescz · 2026-01-30T14:47:56Z

src/Compilers/CSharp/Test/CommandLine/CommandLineTests.cs

            // - [ ] update _MaxAvailableLangVersion cap (a relevant test should break when new version is introduced)
            // - [ ] update the "UpgradeProject" codefixer
+            // - [ ] Remove the `Experimental` section from any entries being shipped in Syntax.xml and OperationInterfaces.xml, and rerun the generator
+            // - [ ] Search the codebase for the URLs that were linked in the Syntax.xml and OperationInterfaces.xml files and remove suppressions or attributes added for those issues.


Search the codebase for the URLs [...] and remove suppressions

URLs wouldn't be linked in the suppressions, right?

333fred added 5 commits January 23, 2026 11:29

Support marking syntax node types and fields as experimental.

96ef084

Mark collection expression nodes as experimental, suppress where nece…

4250ca1

…ssary.

Support marking IOperation types as experimental.

b3ed922

Mark collection expression arguments IOperation types as experimental

c690aa9

Update canary instructions

175b78d

333fred requested review from a team as code owners January 23, 2026 20:24

github-actions bot added the Area-Compilers label Jan 23, 2026

333fred requested a review from jcouv January 23, 2026 20:24

dotnet-policy-service bot added VSCode Needs API Review Needs to be reviewed by the API review council labels Jan 23, 2026

jasonmalinowski reviewed Jan 24, 2026

View reviewed changes

jcouv reviewed Jan 24, 2026

View reviewed changes

src/Compilers/CSharp/Test/CommandLine/CommandLineTests.cs Outdated Show resolved Hide resolved

jcouv reviewed Jan 24, 2026

View reviewed changes

src/Tools/Source/CompilerGeneratorTools/Source/IOperationGenerator/IOperationClassWriter.cs Outdated Show resolved Hide resolved

jcouv reviewed Jan 24, 2026

View reviewed changes

jcouv self-assigned this Jan 24, 2026

Addressing non-suppression comments.

21ed3b1

This was referenced Jan 26, 2026

The Operation will be canceled. The next steps may not contain expected logs. dotnet/dnceng#3008

Open

[android-arm64] The Operation will be canceled. The next steps may not contain expected logs. dotnet/dnceng#6408

Open

AlekseyTs reviewed Jan 28, 2026

View reviewed changes

src/Compilers/Core/Portable/Operations/OperationInterfaces.xml Outdated Show resolved Hide resolved

AlekseyTs reviewed Jan 28, 2026

View reviewed changes

src/Compilers/Core/Portable/Generated/FlowAnalysis.Generated.cs Show resolved Hide resolved

AlekseyTs reviewed Jan 28, 2026

View reviewed changes

src/Compilers/Core/Portable/Generated/OperationKind.Generated.cs Show resolved Hide resolved

AlekseyTs reviewed Jan 28, 2026

View reviewed changes

src/Compilers/CSharp/Portable/Binder/Binder_Expressions.cs Outdated Show resolved Hide resolved

jaredpar mentioned this pull request Jan 28, 2026

Un-obsolete extension ITypeSymbol APIs #82192

Merged

333fred added 4 commits January 29, 2026 12:06

Add a global suppression

c74c04d

Update issue link

26a3976

Remove suppression from generated files

1bbf7d9

Break out public APIs into a section in the compiler test plan and ad…

bab901b

…d more details.

Revert "Remove suppression from generated files"

7f620b1

This reverts commit 1bbf7d9.

jcouv reviewed Jan 29, 2026

View reviewed changes

333fred added 4 commits January 29, 2026 15:08

Remove generation from the operation generator.

da1a98f

Mark SyntaxKind.WithElement as experimental.

ab2f266

Fix public api bug that was not looking for experimental on containin…

364ec38

…g properties.

Fix api file

1e4c68f

jasonmalinowski approved these changes Jan 30, 2026

View reviewed changes

jjonescz reviewed Jan 30, 2026

View reviewed changes

	- APIs are marked with `[Experimental(RoslynExperiments.PreviewLanguageFeatureApi, UrlFormat = @"link to tracking issue")]`
	- APIs are marked with `[Experimental(RoslynExperiments.PreviewLanguageFeatureApi, UrlFormat = "link to tracking issue")]`

Support marking generated public APIs as experimental #82131

Are you sure you want to change the base?

Support marking generated public APIs as experimental #82131

Conversation

333fred commented Jan 23, 2026

Uh oh!

jasonmalinowski left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

333fred commented Jan 24, 2026 • edited by jcouv Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jcouv Jan 24, 2026 • 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!

333fred Jan 26, 2026 • 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!

jcouv Jan 24, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jcouv commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jcouv commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jcouv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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 commented Jan 28, 2026

Uh oh!

Uh oh!

AlekseyTs commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AlekseyTs commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

333fred commented Jan 29, 2026

Uh oh!

AlekseyTs commented Jan 29, 2026

Uh oh!

AlekseyTs commented Jan 29, 2026

Uh oh!

jcouv Jan 29, 2026 • 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!

333fred commented Jan 24, 2026 •

edited by jcouv

Loading

jcouv Jan 24, 2026 •

edited

Loading

333fred Jan 26, 2026 •

edited

Loading

jcouv Jan 24, 2026 •

edited

Loading

jcouv commented Jan 24, 2026 •

edited

Loading

jcouv commented Jan 24, 2026 •

edited

Loading

AlekseyTs commented Jan 28, 2026 •

edited

Loading

AlekseyTs commented Jan 28, 2026 •

edited

Loading

jcouv Jan 29, 2026 •

edited

Loading