geek#techno-babble for the masses

Well it’s been a few months since the last release, and I decided it was time to get cracking.  I’m sorry for the delay, but I hope you’ll agree that it was worth the wait.  So without further adieu, let’s  go over the new stuff!

Separating Components

So one of the things a lot of people have been asking for is a version of ActionMailer.Net that works without a dependency on ASP.NET MVC.  It took me a while to come up with a strategy for doing this, but I think I’ve covered all the bases.  That said, I had to move things around.  So here’s how the project is laid out now:

• ActionMailer.Net – This project contains generic code that can be applied to either the MVC or Standalone versions of ActionMailer.Net.  This DLL is referenced by the other two projects as sort of a “Core” set of functionality.
• ActionMailer.Net.Mvc (Nuget:  ActionMailer) – All the MVC-specific stuff has been moved into this project.  This means that MailerBase, EmailResult, and all the Html/Url helpers live in this project.  In most cases, all you’ll have to do is change your “using” statement to this new namespace, and your existing code should work just like it has been.
• ActionMailer.Net.Standalone (Nuget:  ActionMailer.Standalone) – This project contains a standalone version of the ActionMailer.Net email rendering engine.  Right now we only support Razor views through two new classes:  RazorMailerBase and RazorEmailResult.  I’ve decided to use the RazorEngine project to power this system.  This engine supports models in the same way MVC does, but some other features (i.e.: layouts) have not been implemented, yet.  This support is still pretty basic, but it should be enough to do most things fairly well.

Installation

As I’ve linked above, there are now two Nuget packages for ActionMailer.Net.  There are also two downloadable ZIP files on the Bitbucket project page.  I recommend the Nuget packages because it’s just so easy, and it will take care of any dependencies for you.  However, I do keep the ZIP files updated, so feel free to use them as well.

Standalone:  How Does it Work?

The good news is that I’ve tried to keep the standalone usage very similar to the MVC version.  All you really need to do is inherit from RazorMailerBase and return RazorEmailResults, just like you do with MVC.  I’m sure code is more helpful, so step 1 is to create your mailer:

public class Mailer : RazorMailerBase {
    public override string ViewPath {
        get { return "Templates"; }
    }

    public RazorEmailResult Verification(User model) {
        To.Add(model.EmailAddress);
        From = "foo@bar.com";
        Subject = "Account Verification";
        return Email("Verification", model);
    }
}

You should notice that RazorMailerBase is an abstract class with only one property that you must implement, and that’s the ViewPath.  This tells ActionMailer.Net where you have stored your views.  In this case, I’ve chosen a folder called “Templates.”  You can see my first email configured in the Verification method.  Now I need to create a view in the folder configured as the ViewPath:

Hello @Model.Name,

This is a sample email.

You’ll notice that I did not specify a @model line in the Razor view.  This is because the Razor engine does not need it.  The Model object will exist, however, if you pass it to the Email method just as we did above.  This is all you need to make a view.  There’s one other important thing to note, however:  When you make a view, it needs to end in .txt.cshtml or .html.cshtml depending on the format.  The standalone version of ActionMailer.Net supports multipart messaging just like the MVC version, so we have to specify the format we wish to use.  In the example above, the view should have been named:  Verification.txt.cshtml.

The final step is to call your new Mailer class anywhere in your application like so:

var user = FindUserByID(123);
new Mailer().Verification(user).DeliverAsync();

As you can see, the RazorEmailResult has delivery methods defined.  Here I’m using DeliverAsync to send the email, but there is also a Deliver method if you’d like the call to happen synchronously.

Wrapping it Up

I hope you can see that using the standalone version of ActionMailer.Net is just as easy as the MVC version.  I’ve tried to keep things as simple as possible.  Keep in mind that RazorEngine is not as full-featured as the MVC razor engine, so more advanced features like partials, HTML helpers, and layouts just don’t work.  However, I still believe that the basic support that is enough for most use cases.  I have plans to expand the default standalone template in the future to give some email-friendly HTML helpers, just like we have in the MVC version.  Please test this out and let me know what you think.  It needs more features, for sure, but this is a good start, I think.  Cheers!

Tags: .NET, ActionMailer.Net, C#

This entry was posted on Wednesday, July 6th, 2011 at 8:41 am and is filed under Development. You can follow any comments to this entry through the RSS 2.0 feed. You can leave a comment, or trackback from your own site.