HOWTO: Upgrading to 2012 R3

With the release of .NET 4.5 and Visual Studio 2012, the time has come for a major upgrade of Rebex libraries API to make it up-to-date with the latest trends. We tried very hard to maintain backward compatibility, but in some cases, we had to change things a bit. This document lists the changes we made and steps you might need to take when upgrading to the latest release of our libraries (2012 R3).

1. Task-based Asynchronous Pattern

Before the 2012 R3 release, Rebex Mail (IMAP, POP3, SMTP), Rebex FTP and Rebex SFTP provided asynchronous methods using the APM pattern (also known as IAsyncResult pattern) with BeginMethodName/EndMethodName methods. Rebex ZIP provided asynchronous methods using the EAP pattern (event-based asynchronous pattern) with void MethodName methods and corresponding MethodNameCompleted events.

With the advent of .NET 4.0, both these patterns were rendered obsolete by the new and very versatile Task-based asynchronous pattern (TAP) with the Task<TResult> MethodNameAsync methods. And recently, .NET 4.5 added the await operator, which builds upon the TPM pattern and finally makes asynchronous programming easy and seamless.

In 2012 R3, we have upgraded the .NET 4.0/4.5 version of our libraries to support the TAP pattern and the await operator. The BeginMethodName/EndMethodName methods were replaced by MethodNameAsync. But don't worry - the original APM methods are still available as extension methods - just add using Rebex.Legacy; (C#) or Imports Rebex.Legacy (VB.NET) to your code if you would like to upgrade and keep using the old APM API.

In .NET 4.0/4.5 build of Rebex ZIP, the event-based asynchronous methods were extended to support both EAP and TAP patterns at the same time. Instead of void, they now return an instance of Task. However, its up to you whether you will actually utilize this task - if you currently use the MethodNameCompleted events, you can ignore it.

Summary:
a) If you are upgrading to a .NET 4.0/4.5 version of Rebex FTP, Rebex SFTP, Rebex Mail (IMAP, POP3, SMTP), you can now use the new TPM-based methods and/or the await operator. If you use the old asynchronous methods and would like to keep using your current code, import the 'Rebex.Legacy' namespace.
b) If you are upgrading to a .NET 4.0./4.5 version of Rebex ZIP, you can use the new TPM-based methods and/or the await operator as well, but you don't have to (you can keep your current code).

2. Events

We added several new events to Rebex FTP, Rebex SFTP and the shared IFtp interface, but you can still keep using their old counterparts. In addition to this, we have also changed the event raising code for asynchronous methods to raise events on whatever SynchronizationContext was captured when the method was started. This means that you no longer have to marshal callbacks to your application's GUI thread. In most cases, you don't have to change any code. However, if this new behavior doesn't suit your needs, set the Ftp/Sftp/Scp/Imap/Pop3/Smtp object's Settings.RaiseEventsFromCurrentThread property to true.

3. Connecting with SSL

We simplified even the most common task - connecting to a server. All you have to supply to the Connect method of Ftp, Imap, Pop3 or Smtp object is the server hostname and an SslMode. The Connect method automatically chooses the port according to the communication protocol and the specified SSL mode.

We also added a new ValidatingCertificate event to those 4 classes, which makes it much easier to write custom certificate validation routines.

Don't worry, the old-style Connect methods and certificate validators are still supported as well, which means you don't have to change your code.