System.Net.Mail.SmtpClient is marked as obsolete in docs, but not in the source code

[PashaPash]

System.Net.Mail.SmtpClient class page is currently states that class is obsolete, and offers https://github.com/jstedfast/MailKit as a replacement.

[System.Obsolete("SmtpClient and its network of types are poorly designed, we strongly recommend you use https://github.com/jstedfast/MailKit and https://github.com/jstedfast/MimeKit instead")]
public class SmtpClient : IDisposable

That class has no Obsolete attribute in both Reference Source for 4.7 and corefx source.

Mono version of SmtpClient was marked as Obsolete few years ago by @migueldeicaza, and then that external lib link somehow made its way to official 4.7 docs. Please remove it.

[jstedfast]

Sssshhhhhh!!!! This is epic for MimeKit and MailKit 😃

[rpetrusha]

Thanks, @PashaPash, for pointing this out and providing context on how it might have happened.
Obsolete information (types and members tagged with the Obsolete attribute) is generated by reflection, so we can't simply remove it; this points to some false assumptions in the reflection process. I've opened an internal bug, #968551, to track the issue.

[dend]

Thanks @mairaw @rpetrusha @PashaPash - we are investigating. This is indeed a byproduct of how we auto-generate documentation.

Opened a mdoc issue:
mono/api-doc-tools#76

[svick]

I think there's another instance of this on Socket.​Duplicate​And​Close. All versions of the docs for that have the MonoLimitation attribute:

[System.MonoLimitation("We do not support passing sockets across processes, we merely allow this API to pass the socket across AppDomains")]

[ocdtrekkie]

This is actually slightly more baffling if you come from the VB display, where the [System.Obsolete( bit doesn't display. The docs just appear to say "it's obsolete" and fails to offer up an alternative. I came here to seek an answer. So System.Net.Mail is not obsolete?

[mairaw]

Yes @ocdtrekkie, I was just discussing this with @dend last week. Here's an issue related to that request: mono/api-doc-tools#274

[joelmartinez]

Yes, this change is very close to landing ... will be in the next release of mdoc :)

[ocdtrekkie]

Great to hear. :)

[Allon-Guralnek]

Has the obsolete notice been removed from the docs? I can't find it on the linked page.

[mairaw]

Temporarily removed @Allon-Guralnek. Next time we run CI in our docs this will be added back.
We're still waiting for the fix that can distinguish attributes per .NET implementation.

[joelmartinez]

Just FYI, the next time it's added back, it will have the appropriate attributes (FrameworkAlternate) to indicate that the attribute only exists in a subset of frameworks (the feature became available two releases of mdoc ago) ... however, not sure when the additional upstream work will be completed, so that the front-end properly filters this attribute out for frameworks like .net desktop, and .net core :)

[af4jm]

I'm seeing this in .NET Core 2.1.2 today... warning DE0005: SmtpClient is deprecated... does that mean there's also a bug in <PackageReference Include="Microsoft.DotNet.Analyzers.Compatibility" Version="0.2.12-alpha" PrivateAssets="All" />?

[karelz]

BTW: SmtpClient is obsolete API: https://github.com/dotnet/platform-compat/blob/master/docs/DE0005.md (that is what causes the warning DE0005.
We do not plan to add the Obsolete attribute on it to avoid breaking everyone's compilation (with warnings treated as errors).

[ocdtrekkie]

@karelz I am very sad if that's the official position of Microsoft, to dump basic Internet functionality off to random third parties. Given examples from other platforms like left-pad, I am extremely hesitant to add random dependencies to software I develop because I have no reason to trust the developer.

I do see in the case of MailKit that it appears to be being maintained by a Microsoft employee, but as a personal project, which means there's really no guarantee of quality or support.

[jstedfast]

Hi @ocdtrekkie,

I'm the MimeKit and MailKit maintainer.

FWIW, I think you'll find that both projects are very high quality codebases and I am very active with maintenance of both projects. This includes fixing bugs, answering questions, adding new features, etc.

Hope that helps assuage your fears... at least somewhat.