[Proposal] [.NET 8] Use `ExperimentalAttribute` instead of `ObsoleteAttribute` to indicate alpha APIs.

[philliphoff]

Describe the proposal

Currently alpha APIs are decorated with the ObsoleteAttribute which causes the compiler to generate a warning/error when used. While the generated message is not entirely accurate, it does ensure users see and understand the risks of using a potentially unstable API.

.NET 6 introduced a new attribute, RequiresPreviewFeaturesAttribute, which serves a purpose similar to our use of ObsoleteAttribute. This generates a similar message (but from the Rosyln analyzer rather than the compiler itself), and requires a slightly different method to disable (via MSBuild property). The main disadvantage is disabling applies to all uses of such decorated APIs, rather than individual uses.

Still, RequiresPreviewFeaturesAttribute feels like a more appropriate way to indicate alpha APIs.

Another option is to create our own attribute and set of Roslyn analyzers that have our specific desired semantics; this could then be a start to additional work to help ensure best practices when using the SDK.

Update: .NET 8 introduces ExperimentalAttribute, which is even more closely aligned with our use case.

[halspang]

@philliphoff - Would this be a breaking change if we switched them all over? Or is there a way to avoid that?

Or, is this proposal just to use it for new features and the old features will be [Obsolete] until they're no longer preview?

[philliphoff]

@halspang Yes, it would be breaking in that it's a different compiler/analyzer error to disable. That said, I just discovered that .NET 8 includes a new ExperimentalAttribute which seems even closer to what we want. (RequiresPreviewFeaturesAttribute was originally targeted at APIs in .NET itself but would still have been better than ObsoleteAttribute.) I suggest we wait until .NET 6 support is dropped and then switch to ExperimentalAttribute, as a whole, so users needn't have to change how they suppress the warnings more than once.

[Neme12]

@philliphoff Couldn't the analyzer just suggest using ExperimentalAttribute if it exists? That means for users on .NET 8 and others who define it. From what I understand, others can define it in their own code as well even on a lower TFM, just like many other attributes that the compiler understands - they're not required to come from mscorlib.

Also, regardless of whether it supports the atribute being defined manually (which it should IMO, there's no reason not to - it's simple to just check whether a type named System.Diagnostics.CodeAnalysis.ExperimentalAttribute exists), why wait until .NET 6 support is dropped when .NET 8 already exists and the analyzer could already work on .NET 8?

[Neme12]

Oh, this isn't about an analyzer, my bad.

[WhitWaldo]

Unfortunately, ExperimentalAttribute requires that one specify a diagnostic ID since it's got some association with code analyzers, but I like using these attributes more than [Obsolete], especially as we do have some truly obsolete code in here. So, I'm implementing with RequiresPreviewFeaturesAttribute and I'll add some page to the documentation clarifying that this isn't referring to .NET compiler preview features, so much as non-stable Dapr functionality.