[Meta] List of APIs considered for "Better Obsoletion"

[Joe4evr]

Rationale

Immo Landwerth (@terrajobst) has proposed a mechanism to improve obsoleting APIs by extending ObsoleteAttribute, affectionally known as Better Obsoletion. Recently, that proposed addition was merged into the framework and the compilers honor the new properties as of dotnet/roslyn#42518. In light of this, it seems like a good idea to gather a list of APIs that should be considered for Better Obsoletion, so there's a central place to discuss/review/suggest these.

Obsolete APIs

This list is by no means exhaustive, but it'll kickstart the discussion.

The three examples from the design doc:

• SecureString - Obsolete the SecureString type #30612
• HttpWebRequest (and related) - Obsolete old HTTP APIs #33125
• Non-generic collections - (no issue)

A quick search for 'obsolete' in dotnet/runtime revealed these:

• Uri.EscapeUriString - [Uri] Uri.EscapeUriString should be deprecated #31387
  • This comment by @karelz mentions there's a few other bad APIs on Uri, but doesn't specify which.
• Assembly.CodeBase - Mark Assembly.CodeBase as obsolete #31127
• RuntimeHelpers.OffsetToStringData - API proposal: Obsolete RuntimeHelpers.OffsetToStringData #31406
• Thread.Abort - Request Thread.Abort to be marked [Obsolete] #28664 (Handled in Add spec for obsoletions in .NET 5 designs#139)
• IAsyncResult - Deprecate IAsyncResult #27936
• HandleProcessCorruptedStateExceptionsAttribute - Consider marking HandleProcessCorruptedStateExceptionsAttribute as obsolete/hidden #31157
• BinaryFormatter - Remove BinaryFormatter from the shared framework in .NET 5 #29976
• StringDictionary - Mark StringDictionary as obsolete #889
• UTF-7 Encoding - Proposal: Obsolete UTF-7 encoding in the framework #32284 (Handled in Obsolete Encoding.UTF7 property and UTF7Encoding ctors #37535)
• PrincipalPermissionAttribute (and related) - Non-support of PrincipalPermissionAttribute #31279 (Handled in Add spec for obsoletions in .NET 5 designs#139)

Other APIs to be considered:

• implicit operator DateTimeOffset(DateTime) - Feature proposal: remove implicit construction of DateTimeOffset from DateTime #32954
• UnmanagedType.AnsiBStr (and a few others) - UnmanagedType.AnsiBStr is marked as obsolete with no alternative given #31006
  • These values are already marked obsolete, but it would be an improvement to give them a dedicated diagnostic ID.

[Kryptos-FR]

There was an issue I opened a while ago regarding ArrayList in .Net Standard (dotnet/standard#296).

Which leads me to the question: would that obsoletion also be applied to the standard, or only to .NET5?

[Joe4evr]

@Kryptos-FR The idea of .NET Standard was to unify the API surface area across multiple implementations of the .NET runtime. With .NET 5 being the unification of those to a single runtime implementation, the purpose of .NET Standard loses its meaning in that new world.

As such, don't hold your breath on the Standard still evolving.

[jeffhandley]

We created dotnet/designs#139, which includes a few APIs mentioned here.

[slavanap]

Can I obsolete specific objects from another library (including .NET itself) in my project, if they aren't obsoleted in their source?

[chucker]

You can write an analyzer. Consider forking https://github.com/dotnet/platform-compat

[slavanap]

@chucker is it correct if I would ever want to restrict some API usages in my project, I would need to build custom analyzer for it which I would later use for code check?

[Joe4evr]

@slavanap For code that you own, you can simply apply [Obsolete] with your own value for the new DiagnosticId property.

[slavanap]

What about the case when I want to restrict usage of implicit operator, code of which I do not own?

[jeffhandley]

You can write an analyzer. Consider forking https://github.com/dotnet/platform-compat

Note that we are working to fully productize the platform-compat analyzer, to get it integrated into the .NET SDK for .NET 5. It will use the new platform-specific support attributes and respect the new IsOSPlatformOrLater and IsOSPlatformEarlierThan methods.

Here's the draft PR from @buyaa-n if you're curious; we expect the PR into dotnet/runtime will be created within the next couple weeks.

@slavanap Other than including an analyzer in your package as was suggested, there isn't a way to cast [Obsolete] attributes onto APIs exposed from one of your dependencies (or the .NET Libraries).

[jeffhandley]

Ha -- my goodness, I got my wires crossed on the previous comment, @slavanap, and I referenced the wrong attributes that the Platform Compat Analyzer will be using. I've fixed the comment above to be accurate.

[jeffhandley]

With the bulk of these issues now addressed, I'm going to close this issue. #46767 captured the obsoletions completed in .NET 6 and I filed #57207 to capture the remaining items from that list and this one for carrying forward into .NET 7.

Thanks for originally filing this, @Joe4evr--this was a big help to steer our efforts and shape our obsoletion work.