Replace [Obsolete] with [Experimental] attributes

[WhitWaldo]

Description

There are some places where it makes sense to mark things as [Obsolete], but it'd be nice to reserve that attribute only for those places where something is truly obsolete and not recommended as a path going forward. It's all we've had to date to mark non-stable functionality, but with the shift to .NET 8 as the minimal version, this brings with it two new attributes: [Experimental] and [RequiresPreviewFeatures].

Unfortunately, [Experimental] seems to have something to do with code analyzers as it has a required string argument for the analyzer ID, so because I'm not entirely sure what this entails for the downstream user experience, I'm skipping over it.

Rather, I've replaced the pre-stable functionality previously marked with [Obsolete] with [RequiresPreviewFeatures] and retained the original message text, e.g. [RequiresPreviewFeatures("The API is currently not stable as it is in the Alpha stage. This attribute will be removed once it is stable.")]

Issue reference

We strive to have all PR being opened based on an issue, where the problem or feature have been discussed prior to implementation.

Please reference the issue this PR will close: #1219

Checklist

Please make sure you've completed the relevant tasks for this PR, out of the following list:

• Code compiles correctly
• Created/updated tests
• Extended the documentation

[WhitWaldo]

@philliphoff It looks like [RequirePreviewFeature] requires that the csproj include the <EnablePreviewFeatures>true</EnablePreviewFeatures> and I don't think we want devs to have to opt into experimental compiler fun just for Dapr alpha/beta functionality.

[Experimental] similarly requires an analyzer ID be provided as it does something with code analyzers.

I haven't been able to identify any other attributes that quite flag a warning like [Obsolete] does. While I briefly contemplated just making a [Preview] attribute and an analyzer that would warn on it, that would require a separate package and I expect rather few people would actually install it (and that's rather beside the point).

To that end, I propose we keep [Obsolete] as-is and see if the .NET devs introduce a better option in a later release. Thoughts?

[philliphoff]

It looks like [RequirePreviewFeature] requires that the csproj include the true and I don't think we want devs to have to opt into experimental compiler fun just for Dapr alpha/beta functionality.

[Experimental] similarly requires an analyzer ID be provided as it does something with code analyzers.

@WhitWaldo The guidance says [RequirePreviewFeature] is intended primarily for components of the .NET Runtime itself. For most other things (in particular, 3rd-party libraries), one should use [Experimental] as this attribute is expressly intended to flag preview APIs in otherwise stable libraries. The diagnostic IDs just need to be reasonably unique/specific to the library as they serve both as a way to identify a specific feature/API as well as the means for disabling warnings/errors when intentionally used.

I would still suggest a switch to [Experimental] from [Obsolete].

[WhitWaldo]

It looks like [RequirePreviewFeature] requires that the csproj include the true and I don't think we want devs to have to opt into experimental compiler fun just for Dapr alpha/beta functionality.

[Experimental] similarly requires an analyzer ID be provided as it does something with code analyzers.

@WhitWaldo The guidance says [RequirePreviewFeature] is intended primarily for components of the .NET Runtime itself. For most other things (in particular, 3rd-party libraries), one should use [Experimental] as this attribute is expressly intended to flag preview APIs in otherwise stable libraries. The diagnostic IDs just need to be reasonably unique/specific to the library as they serve both as a way to identify a specific feature/API as well as the means for disabling warnings/errors when intentionally used.

I would still suggest a switch to [Experimental] from [Obsolete].

I'll give it a shot and see what happens!

[philliphoff]

[Experimental("...")]?

[philliphoff]

A couple of suggestions:

• Use a common constant for each ID to make changes simpler and allow for documentation
• Use a different ID for each "category" or "area" in which the experimental APIs reside (e.g. storage vs. encryption vs. jobs) so that developers can opt into (i.e. suppress warnings) certain APIs without having to opt into every API.

[WhitWaldo]

@philliphoff Have you seen much guidance around this front? Following your suggestion, I've been thinking about it and I'm inclined towards "DAPR-WORKFLOW-001". We don't have much in the way of analyzers or other constants like this yet so definitely want consistency, so should I drop the hyphens altogether or keep them here for readability?

[WhitWaldo]

Apparently hyphens are not allowed, so assume the same for underscores instead, e.g. "DAPR_WORKFLOW_001".

[philliphoff]

Approved with a couple of suggestions.