Sendgrid-csharp: Breaking changes without documentation!!!

[jewpaltz]

Issue Summary

If you introduce breaking changes, then you _MUST_ provide adequate documentation.

Steps to Reproduce

1. Program ANYTHING with the Nuget v 8.x
2. Upgrade the Nuget packages to 9.x
3. Receive absolutely no notification of breaking changes
4. Have your code stop compiling
5. Scratch your head to figure out what happened.
6. Go to [https://github.com/sendgrid/sendgrid-csharp] and see a link to a page about breaking changes
7. Click the link to [https://github.com/sendgrid/sendgrid-csharp/issues/317] and realize that they mention that there are breaking changes but They don't list them anywhere or have any recomendations on how to upgrade
8. Back to square one - How do I rewrite my code to work with the new code?

Technical details:

• sendgrid-csharp Version: master (latest commit: [commit number])
• .NET Version: 4.5.2

[thinkingserious]

Hello @jewpaltz,

My apologies for the poor upgrade experience. I am very much interested in fixing this situation.

Currently, our recommendation is to refactor your code based on the examples in the README as the interface is completely different. It is my hope that the new implementation should be much easier to implement as compared to v8.

Where do you suggest we place our upgrade recommendations? (e.g. Where did you look?)

With Best Regards,

Elmer

[jewpaltz]

I am sorry for my outburst.
I thought I was making a quick edit on a project for a client. Then I was hit by this. Thank you for maintaining this software and thank you for the quick response. You did not deserve the harsh attitude in the post.
I think that you need a shot list of what was removed and if it was replaced by something comparable (interface wise) then a note to that fact. There should be a link to that list in the Readme.md at https://github.com/sendgrid/sendgrid-csharp
Even better would be if you made use of the [Depreciated] Attribute for a few versions before removing a class, property, or method.
I ended up just reverting to v 8.0.5 because v9.x wouldn't allow me to clear the To list. You seam to have reverted from C# style properties to Java style setters.

[thinkingserious]

Hi @jewpaltz,

No worries, I view this type of feedback as a great opportunity to improve. Thank you very much for elaborating on the specifics.

We will get the documentation updated per your suggestions.

I'm not quite sure what you mean about reverting from C# style properties, could you please elaborate?

Here is how you would clear the Tos:

using SendGrid;
using SendGrid.Helpers.Mail;
using System;
using System.Threading.Tasks;

namespace Example
{
    internal class Example
    {
        private static void Main()
        {
            Execute().Wait();
        }

        static async Task Execute()
        {
            var apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
            var client = new SendGridClient(apiKey);
            var from = new EmailAddress("[email protected]", "Example User");
            var subject = "Hello World from the SendGrid CSharp SDK!";
            var to = new EmailAddress("[email protected]", "Example User");
            var plainTextContent = "Hello, Email!";
            var htmlContent = "<strong>Hello, Email!</strong>";
            var msg = MailHelper.CreateSingleEmail(from, to, subject, plainTextContent, htmlContent);
            await client.SendEmailAsync(msg);
            Console.WriteLine(msg.Personalizations[0].Tos[0].Email); // [email protected]
            msg.Personalizations[0].Tos.Clear();
            Console.WriteLine(msg.Personalizations[0].Tos[0].Email); // Empty
            Console.ReadLine();
        }
    }
}

It looks like we may want to have a helper, similar to:

msg.ClearTos()

Thanks!

With Best Regards,

Elmer