New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
PashaPash opened this Issue Apr 11, 2017 · 20 comments

Comments

Projects
None yet
@PashaPash
Copy link

PashaPash commented Apr 11, 2017

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

This comment has been minimized.

Copy link

jstedfast commented Apr 11, 2017

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

@rpetrusha

This comment has been minimized.

Copy link
Contributor

rpetrusha commented Apr 11, 2017

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

This comment has been minimized.

Copy link
Contributor

dend commented Apr 27, 2017

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

This comment has been minimized.

Copy link
Collaborator

svick commented Jun 26, 2017

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")]

@mairaw mairaw referenced this issue Apr 10, 2018

Closed

[Feature] Span<T> #4400

0 of 3 tasks complete

@joelmartinez joelmartinez referenced this issue Jun 4, 2018

Merged

mdoc 5.7 #261

@ocdtrekkie

This comment has been minimized.

Copy link

ocdtrekkie commented Jun 25, 2018

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

This comment has been minimized.

Copy link
Contributor

mairaw commented Jun 25, 2018

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

This comment has been minimized.

Copy link

joelmartinez commented Jun 25, 2018

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

@ocdtrekkie

This comment has been minimized.

Copy link

ocdtrekkie commented Jun 25, 2018

Great to hear. :)

@Allon-Guralnek

This comment has been minimized.

Copy link

Allon-Guralnek commented Jul 11, 2018

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

@mairaw

This comment has been minimized.

Copy link
Contributor

mairaw commented Jul 17, 2018

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

This comment has been minimized.

Copy link

joelmartinez commented Jul 17, 2018

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

This comment has been minimized.

Copy link

af4jm commented Aug 28, 2018

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

This comment has been minimized.

Copy link
Member

karelz commented Oct 17, 2018

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

This comment has been minimized.

Copy link

ocdtrekkie commented Oct 18, 2018

@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

This comment has been minimized.

Copy link

jstedfast commented Oct 18, 2018

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.

@svick

This comment has been minimized.

Copy link
Collaborator

svick commented Oct 18, 2018

@ocdtrekkie MailKit is also part of the .Net Foundation, in case that makes a difference for you.

@PashaPash

This comment has been minimized.

Copy link
Author

PashaPash commented Oct 18, 2018

@karelz @jstedfast "doesn't scale to modern requirements of the protocol" is too generic.

Is there any specific reason to use MailKit instead of SmtpClient to send mail over SMTP? Will it be faster or more reliable?
It seems that SmtpClient does not support pipelining and rfc2231 for filenames, but I'm not sure about other protocol features.

@karelz

This comment has been minimized.

Copy link
Member

karelz commented Oct 18, 2018

@PashaPash we do not have list of all missing RFCs and features in SmtpClient. The fact is that SmtpClient hasn't been innovated in a long time, while MailKit was.
We've also heard that the performance of SmtpClient is not as good as MailKit.

If you are sending just occasional emails (e.g. alerts, or tooling), then SmtpClient is likely good enough for you. If you need modern, high-perf, latest technology, then I would recommend to use MailKit.

@ocdtrekkie

This comment has been minimized.

Copy link

ocdtrekkie commented Oct 18, 2018

@jstedfast My comment wasn't intended to be a slight at your projects, I do hope you didn't take it as one.

But I think there's definitely a strong value to features in .NET Framework code being officially managed and distributed by Microsoft, and of course, that projects (and other dependencies) declaring compatibility with a .NET Framework version are stating compatibility with all of the features included. (Watching Node-based projects talk about what they have to do to upgrade what dependencies is incredible.)

Documentation is, of course, tightly integrated with the the documentation for .NET as a whole as well, etc. And as my project currently is .NET Framework-based, of course, another huge benefit is not carrying much extra code with my program, as it comes with Windows.

In my personal code projects, I've set the general intention to solely use .NET Framework/Core as my sole "dependency" and eschew third party functionality as much as possible. In a few cases, this means I've reinvented the wheel (which has been educational!), but I've heavily relied on things like SmtpClient being taken care of for me. For an example, my project had to implement IMAP since .NET Framework doesn't. MailKit is larger than my entire project, and the rudimentary IMAP functionality I needed is only about three dozen lines of code. 10xing the size of my project and the scope of code I drag along with it for one function would be unfortunate.

I get a little bit of pride every time I can remove a NuGet package, so it's just a little disappointing that Microsoft is moving in the opposite direction. Just something I'm going to have to deal with as everything becomes irritatingly more like the JavaScript world.

(I'm gonna step off my soapbox now...)

@jstedfast

This comment has been minimized.

Copy link

jstedfast commented Oct 18, 2018

@ocdtrekkie Don't worry, I did not take any offense at your comment :-)

FWIW, I also like to use as few nugets as possible in my projects as well, so I can understand your position on that.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment