Enumerations by themselves are powerful, but pretty plain.  Since 95% of my development work is in ASP.NET MVC these days, I wanted an easy way to render the options an enumeration provides as a drop-down or radio button list.  I could do this manually, and it’s not a lot of code, but I felt like there needed to be an easier, more generic way to handle things.

So let’s assume you have input model that looks like this:

public class VehicleInputModel {
    public int Year { get; set; }
    public string Make { get; set; }
    public string Model { get; set; }
    public VehicleType VehicleType { get; set; }

    public enum VehicleType {
        Car = 1,
        Truck = 2,
        SUV = 3
    }
}

This is pretty standard stuff.  You’ll have to forgive the contrived example, but it basically works.  I may have two database tables.  One called “Vehicle” and the other called “VehicleType,” and they have a foreign-key relationship between them.  All I’ve done here is make an enumeration that matches my VehicleType table so I can refer to them in code without having to sprinkle ID numbers all over the place.  But what happens when I want to make a form in ASP.NET MVC to create or edit a vehicle?  Some people might reach for the database and grab the data from the reference table to create our drop-down.  I offer an alternative: let’s beef up the enumeration:

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

public enum VehicleType {
    [Display(Name="Car")]
    Car = 1,

    [Display(Name="Truck")]
    Truck = 2,

    [Display(Name="Sport Utility Vehicle (SUV)")]
    SUV = 3
}

Data annotations to the rescue!  You’re already using them all over the place in ASP.NET MVC because of the validation system (at least I hope you are).  Why not put them to work for our enumerations, too?  In this case, I’ve attached some arbitrary metadata to my enumeration that will make displaying data a bit easier.

First, let’s create a generic helper method that will read data from these attributes.  I like to use an extension method for this, and I extend the System.Enum class:

public static string GetAttributeValue<T>(this Enum e,
    Func<T, object> selector) where T : Attribute {

    var output = e.ToString();
    var member = e.GetType().GetMember(output).First();
    var attributes = member.GetCustomAttributes(typeof (T), false);

    if (attributes.Length > 0) {
        var firstAttr = (T)attributes[0];
        var str = selector(firstAttr).ToString();
        output = string.IsNullOrWhiteSpace(str) ? output : str;
    }

    return output;
}

This helper is fairly straightforward.  All I’m doing is finding the custom attributes on the enumeration and then using a simple function to grab any value I want.  If there are no attributes defined, then I just return the default ToString() value.

Because the Html.DropDownListFor() method takes an IEnumerable<SelectListItem>, I’ve written another handy method that converts an enumeration into that type:

public static IEnumerable<SelectListItem> ConvertToSelectList<T>(int? selectedItem = null) {
    return Enum.GetValues(typeof (T)).Cast<T>().Select(x => new SelectListItem {
        Text = (x as Enum).GetAttributeValue<DisplayAttribute>(y => y.Name),
        Value = Convert.ToInt32(x).ToString(),
        Selected = selectedItem.HasValue ? selectedItem == Convert.ToInt32(x) : false
    });
}

This method grabs all the values in an enumeration, then uses the extension method above to read the Name property from the DisplayAttribute on each value.  If there is no DisplayAttribute present, then a simple ToString() is called on each value.  It also takes an optional selectedItem argument that can be used to determine which item in the list should be selected.  This leaves me with a collection of SelectListItem objects where the Text property on each object is determined by the DisplayAttribute.  Pretty sweet, huh?  Now I can extend my VehicleInputModel like so:

public class VehicleInputModel {
    public int Year { get; set; }
    public string Make { get; set; }
    public string Model { get; set; }
    public VehicleType VehicleType { get; set; }
    public IEnumerable<SelectListItem> VehicleTypeSelection { get; set; }

    public VehicleInputModel() {
        VehicleTypeSelection = EnumExtensions.ConvertToSelectList<VehicleType>();
    }

    public enum VehicleType {
        Car = 1,
        Truck = 2,
        SUV = 3
    }
}

And finally, I can render this drop-down list in my view like so:

@Html.DropDownListFor(m => m.VehicleType, Model.VehicleTypeSelection)

I hope you can see how a couple easy, generic methods and the built-in data annotations can make your enumerations a lot beefier.  This can save you some time and database hits in the long run.  I’m not suggesting that you use enumerations for every single reference table in your project, and I know this example is a bit contrived.  My goal is simply to illustrate the power of a few well-placed attributes and a handy method in certain situations that can clean up your controllers and views a bit.  Cheers!

SPAM Sucks

Apparently it’s my fault.  Apparently I didn’t read some fine print somewhere that says that the STLDODN organizers were going to give my email address to every vendor that sponsored this event so they could flood my inbox with sales pitches and bullshit.  Never mind the fact that this year’s conference was even more mediocre than last year’s.  Never mind the fact that the keynote was on Visual Studio LightSwitch – a product that Microsoft is pushing on business users to somehow make my job obsolete.  Never mind the fact that some of my co-workers are junior level and/or interns, and they couldn’t get into the jumpstart classes because they decided to put them in undersized rooms.  Never mind the fact that advanced content is glaringly absent.

There is a lot wrong with this conference, but the biggest problem of all is that now my work email address is being spammed by the conference vendors and sponsors.  What the hell?  I thought you guys had more integrity.  I thought—of all people—my fellow programmers would hate spam at least as much as I do.  I guess I assumed too much.  Goodbye St. Louis Day of .NET, and good riddance.  I will not be back next year.

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!

I’ve recently released a new version (0.4.1) of this library which adds support for true multi-part messaging and a whole bunch of URL and HTML helpers that you can use in your views.  ActionMailer.Net also has a pretty thorough set of unit tests, so feel free to hack around and let me know what you think! 

The Video

I’d love to make some more of these covering some of the more advanced features in ActionMailer.Net.  Any feedback is welcome and appreciated!

Cheers!

P.S. – For those of you that would rather watch the uncompressed video or can’t access YouTube at work, feel free to grab the video here (you’ll need 7-zip to decompress it).

So I took a step back.  I realized that the Rails framework really has this nailed.  Through the awesome ActionMailer library within Rails, you can use the built-in template engines to generate emails almost exactly like you would generate a view.  This leads to very small helper methods, and it’s just so darn clean.  I think the MVC community could use a cool library like this, so I decided to write one.

Introducing ActionMailer.Net for MVC 3

First off, the code is completely open source.  My boss was cool enough to let me share this with the community, so I’ve chosen the MIT license as it seems most fitting.  The code is up on bitbucket right now, so feel free to download it and tinker with it to your heart’s content.  This is still very alpha, so I’ll warn you that it might have a few bugs.  I’ve tried to be diligent with my unit tests, but I’m sure I’ve missed a few things.

The error handling could use some work, and I also need to add support for multi-part messages and attachments.  I also want to throw this thing up on NuGet soon to make it easier to download. These features are in the works, but patches and pull requests are most certainly welcome!

Cool, Now Show Me the Code!

So once you’ve downloaded and referenced the ActionMailer.Net.dll within your project, using it is pretty easy.  First, you need to add a new controller.  For this example, mine will be called MailController.  This new controller should inherit from ActionMailer.Net.MailerBase:

public class MailController : MailerBase
{
    public EmailResult VerificationEmail(User model)
    {
        To.Add(model.EmailAddress);
        From = "no-reply@mycoolsite.com";
        Subject = "MyCoolSite Account Verification";
        return Email(model);
    }
}

Notice that we’re returning a special type from the action defined above.  This type EmailResult is provided by ActionMailer.Net.  We’re also using a special helper method called Email() instead of the normal View() method you’re probably used to.

The next step is to create a view that matches this action.  I’ve only tested the Razor view engine, but the library should be view engine agnostic, meaning that you could just as easily use the Web Forms view engine, or even Spark, or NHaml as long as they are registered as proper view engines within your application.  To correspond with the sample method above, the view for this action should live in ~/Views/Mail/VerificationEmail.cshtml:

@model User

@{
    Layout = null;
}

Welcome to My Cool Site, @User.FirstName

We need you to verify your email.  Click this nifty link to get verified!

@Url.Action("Verify", "Account", new { code = @User.EmailActivationToken.ToString() })

Thanks!

Right now the links are generated with a relative URL.  I’m working on a couple of helpers to fix that for you, but just be aware of it at the moment.  The final step is to actually call this action from somewhere else, and that’s the easiest part.  Let’s say you’ve got a registration action and you want to send out email verification.  All it takes is one line of code:

new MailController().VerificationEmail(newUser).Deliver();

That’s it!  I’ve tried to make the library as fluid as possible to save you some headaches, but I could definitely use some input from you guys.

Configuration

There is a little bit of configuration that needs to be done, but it’s pretty easy.  Under the hood, ActionMailer.Net is using the default System.Net.Mail.SmtpClient to send all your messages.  This means that you need to add some configuration options in your project’s Web.config file.  While I’m in development, I like to send all emails to a local folder on my hard drive:

<system.net>
  <mailSettings>
    <smtp deliveryMethod="SpecifiedPickupDirectory">
      <specifiedPickupDirectory pickupDirectoryLocation="C:\temp\"/>
    </smtp>
  </mailSettings>
</system.net>

But later, when you move to production, you’ll need some more appropriate settings:

<system.net>
  <mailSettings>
    <smtp deliveryMethod="Network">
      <network host="smtp.mysite.com" userName="myuser" password="mypassword" />
    </smtp>
  </mailSettings>
</system.net>

What Else Does it Do?

I’ve tried to make this library as extensible as possible through interfaces.  If you would rather using something like Amazon SES to send your messages, all you need to do is implement the IMailSender interface, and then override the default MailSender with your own like this:

public MailController() {
    MailSender = new MyCustomSender();
}

Another feature is the ability to override a couple of methods on the MailerBase class within your controller to inspect mail messages before and after they are sent.  You can even cancel certain messages from going out:

protected override void OnMailSending(MailSendingContext context) {
    // here I could set context.Cancel to stop the message
    // or I could see the message as context.Mail
}

protected override void OnMailSent(MailMessage mail) {
    // the mail message that was sent is passed in for you
}

Wrapping Up

So that’s it for now.  I’ve got a lot of plans for this library.  I’d like to make it just as full-featured as its Rails counterpart.  I could also use some testing and even contributions from the community.  Sending email sucks, so let’s make it easier on each other, right?  Cheers!

Long story short, I had to scrape my content out of Google cache to get this blog back in action. One lovely side effect, however, is that all my post comments were blasted to smithereens. I do apologize for those of you that were thoughtful enough to lend me your words. I’ve learned the hard way to always confirm your backup strategy. I hereby join the ranks of Phil Haack and Jeff Atwood (*facepalm*).

My former host was Linode.  For the most part, things were incredibly stable.  Barring recent events, I never had any major issues that weren’t somehow my fault.  I signed up with them in June of 2009 because I noticed their packages offered more bang for the buck than Slicehost (my first host for this blog).  They had a lot of positive reviews, and their control panel software was pretty sweet.  My geek side fell in love with Linode, and I was a happy customer for a long time.  Recently, though… things haven’t been so great.

Hurricane Electric?  Woohoo!

One of the great benefits of Linode is that they have multiple data centers.  You can pick between five of them at the time of this writing.  One of my key concerns was IPv6 connectivity (which Linode does not yet provide natively), and I knew that Hurricane Electric’s Tunnel Broker service had a POP in Fremont.  I was pleasantly surprised to find out that Linode actually co-located within Hurricane Electric’s Fremont facility, so the latency over my IPv6 tunnel was extremely low.  I mean the times were sub-millisecond.  Color me happy.

Hurricane Electric’s Lack of Redundancy

At first I was amazingly happy with my service.  Again, it was a year and a half of pretty solid performance.  I’d have a couple blips here and there in my network connectivity, but Linode was always on top of things and had issues resolved usually within a few minutes.  The problems started, however, toward the end of last month.  The Fremont facility suffered some major issues.  You can see more about them on Linode’s status page, but suffice it to say that I was a bit upset after these two incidents within days of each other.

What Hurricane Electric decided to leave out of the RFO was the fact that customer equipment was damaged due to their faulty systems.  What they describe as a 3-second power issue (the first outage) actually destroyed customer equipment.  Thank god Linode was prepared for this.  My VPS was down for hours, but Linode had hot standby systems in place.  I hate to think how long I’d have been down if Linode wasn’t as prepared.  I really don’t understand how a top-tier ISP like Hurricane Electric can suffer so much damage and downtime because of a simple lightning storm.  To me, this is complete and total failure on their part.  I didn’t blame Linode at all.

Next comes downtime number two within 3 days of the previous one.  They had another “incident” which caused a 1-second power failure due to the fact that they were still running on their N + 1 redundant UPS which failed.  Again, Linode was quick to respond.  Tell me something Hurricane Electric… if the power was only interrupted for 1 second, why did you not enhance the degraded UPS?  I understand you were waiting for parts, but you should have been better prepared in the meantime.  Again, I can’t fathom how a company of your position and stature could be in this situation.

Sticking It Out

So to be completely fair, the first two downtimes weren’t Linode’s fault.  I realize that.  I completely blame the incompetence of Hurricane Electric for those issues.  After those two incidents, I decided to stick it out with Linode.  Let’s face it:  migrating servers is a pain in the ass, and I really didn’t want to do it.  Not only that, but I felt like it wasn’t fair to blame Linode for something that was completely out of their control.

So stick it out, I did.  I was obviously very angry at this point, but I convinced myself that 1.5 years of solid service was enough to offset a few hours of downtime that wasn’t their fault.  But then the third issue happened, and this time, it was Linode’s fault.  This was the straw that broke the camel’s back.

Linode posted about some network maintenance they needed to perform on December 12.  I figured this wouldn’t be a big deal.  Any decent ISP has redundancy built in at every point possible, so even if they were replacing several core switches, there shouldn’t have been any need for downtime.  There was, however, substantial downtime.  I couldn’t take it anymore.  Between Hurricane Electric and Linode, it seemed like my server was doomed.  I decided to make a move.

Rackspace Cloud

So here we are, rolling on the Rackspace Cloud.  I must say that I’ve been very impressed so far.  It hasn’t all been candy and roses, though.  I did have an issue with the webserver that is hosting this site right now.  It was very unresponsive and slow.  Here’s the difference though:  Rackspace support is amazing.  I clicked the little “Live Chat” button in my dashboard, and instantly I was connected with a fellow named Ethan.  Ethan stuck with me while we tried a few things, and then eventually he decided that it would be a good idea to move my server to another host.  Once my server was moved, the problems went away, and everything just worked.  Rackspace support is stellar, and I can’t recommend them highly enough.

Wrapping It Up (TLDR)

I couldn’t take the downtime with Linode.  I know Rackspace Cloud is just rebranded Slicehost, but that’s fine with me.  Rackspace support is stellar, and I don’t mind paying just a few extra dollars per month to have a company like Rackspace behind me.  I’m looking at launching my small startup venture soon, and I need reliability from my host.  Thanks for all the fish, Linode.  It was good while it lasted, but I’m a happy Rackspace customer now.  Woot!

Basically, each of our projects has a “Data” layer where we store everything needed to communicate with the database.  This is also where the ISession interface lives, so it’s easy to provide the implementation.  There is one caveat, however, because we need to provide a generic EF4 implementation that can work with any data context.  In our projects, sometimes we need to speak with multiple databases, and then it becomes just a matter of plugging the right entity collection into our implementation.  Here’s what the code looks like:

public class EntityFrameworkSession<O> : ISession where O : ObjectContext, new() {
    protected readonly ObjectContext _db;

    public EntityFrameworkSession() {
        _db = new O();
    }

    public virtual void CommitChanges() {
        _db.SaveChanges();
    }

    public virtual void Refresh<T>(T item) where T : class {
        _db.Refresh(RefreshMode.StoreWins, item);
    }

    public virtual void Delete<T>(Expression<Func<T, bool>> expression) where T : class {
        IQueryable<T> query = _db.CreateObjectSet<T>().Where(expression);

        foreach (T item in query) {
            _db.DeleteObject(item);
        }
    }

    public virtual void Delete<T>(T item) where T : class {
        if (item == null)
            throw new ArgumentNullException("item");

        _db.DeleteObject(item);
    }

    public virtual void DeleteAll<T>() where T : class {
        ObjectSet<T> query = _db.CreateObjectSet<T>();

        foreach (T item in query) {
            _db.DeleteObject(item);
        }
    }

    public virtual T Single<T>(Expression<Func<T, bool>> expression) where T : class {
        return All<T>().SingleOrDefault(expression);
    }

    public virtual IQueryable<T> All<T>() where T : class {
        return _db.CreateObjectSet<T>().AsQueryable();
    }

    public virtual void Add<T>(T item) where T : class {
        _db.CreateObjectSet<T>().AddObject(item);
    }

    public virtual void Add<T>(IEnumerable<T> items) where T : class {
        foreach (T item in items) {
            _db.CreateObjectSet<T>().AddObject(item);
        }
    }

    public virtual void Update<T>(T item) where T : class {
        // EF4 tracks updates on its own, so nothing is needed here
        return;
    }

    public virtual void Dispose() {
        _db.Dispose();
    }
}

As you can see, it’s actually pretty small.  The beauty comes from the fact that it’s completely generic.  When we create an EF4 Entity Data Model (*.EDMX file), we name the data context, and then we can pass it into this implementation, like so:

// First, we need to build the session
var session = new EntityFrameworkSession<NorthwindEntities>();

// Now I can get any table I want from the session.
var products = session.All<Product>();

// Maybe I want and individual item.
var product = session.Single<Product>(x => x.ProductID = 1);

// We can use the more verbose LINQ syntax, too.
var products = from p in session.All<Product>()
               where p.Price > 2.50m
               select p;

As you can see, working with ISession is pretty easy from this implementation.  One thing I haven’t covered in this post is support for logical deletes.  We have another subclass for that which uses this EF4 implementation as its base.  This is why all the methods in our implementation are virtual.  I’ll save that implementation for another post!

Step 1:  Environment and Pre-Requisites

This section probably looks familiar.  The only difference now is that I’m running Ubuntu 10.04 LTS on my main server now.  The packages are pretty much the same.  First we make sure the universe repository is enabled by editing /etc/apt/sources.list and removing the hash marks in front of universe lines:

deb http://us.archive.ubuntu.com/ubuntu/ lucid universe multiverse
deb-src http://us.archive.ubuntu.com/ubuntu/ lucid universe multiverse
deb http://us.archive.ubuntu.com/ubuntu/ lucid-updates universe restricted main multiverse
deb-src http://us.archive.ubuntu.com/ubuntu/ lucid-updates universe multiverse
deb http://security.ubuntu.com/ubuntu lucid-security universe multiverse
deb-src http://security.ubuntu.com/ubuntu lucid-security universe multiverse

Next we need to snag a lot of packages that are requried to build the various packages.  Run the following commands to get what we need:

sudo apt-get update
sudo apt-get install build-essential libxml2-dev libssl-dev libbz2-dev curl libcurl4-openssl-dev libpng12-dev libmcrypt-dev mysql-server libmysqlclient-dev libxslt1-dev autoconf2.13 libltdl-dev libreadline5-dev libsqlite3-ruby postgresql-server-dev-8.4 libpcre3-dev

Finally, libevent still hasn’t been updated to a suitable version for PHP-FPM, so we need to install that manually:

wget http://monkey.org/~provos/libevent-1.4.14b-stable.tar.gz
cd libevent-1.4.14b-stable
./configure
make && sudo checkinstall

You’ll notice above that I use the "checkinstall" command to install this package.  The main reason I use this is that it makes upgrading a lot easier in the future.  It’s especially nice when you want to update something like PHP.  This handy command will generate a nice *.deb file for you, and then you can remove the package using “dpkg –r packagename” when you’re ready to upgrade down the road.  Neat, huh?  Note:  if you get an error during building the package with checkinstall, it’s probably because you need to change the version of your package to say “1.4.14b-stable” instead of just “stable.”  For reference, here are the checkinstall values I use:

This package will be built according to these values:

0 -  Maintainer: [ Scott Anderson <scott@geeksharp.com> ]
1 -  Summary: [ My custom version of libevent-1.4.14b-stable ]
2 -  Name:    [ libevent ]
3 -  Version: [ 1.4.14b-stable ]
4 -  Release: [ 1 ]
5 -  License: [ GPL ]
6 -  Group:   [ checkinstall ]
7 -  Architecture: [ i386 ]
8 -  Source location: [ libevent-1.4.14b-stable ]
9 -  Alternate source location: [  ]
10 - Requires: [  ]
11 - Provides: [ libevent ]

Step 2:  Compiling PHP From Source with the Suhosin Patch

Since the FPM module is now included in PHP as of version 5.3.3, we don’t have to download it separately.  All we need to snag is the latest Suhosin patch and apply to to the 5.3.3 source. 

wget http://us2.php.net/get/php-5.3.3.tar.bz2/from/this/mirror
bzip2 -dc php-5.3.3.tar.bz2 | tar xf -
wget http://download.suhosin.org/suhosin-patch-5.3.3-0.9.10.patch.gz
gunzip suhosin-patch-5.3.3-0.9.10.patch.gz
cd php-5.3.3
patch -p 1 -i ../suhosin-patch-5.3.3-0.9.10.patch

Now all we have to do is configure and build PHP itself.  Thankfully this process is a lot simpler now that PHP-FPM has been integrated into the core PHP source.

./configure --enable-bcmath --with-bz2 --enable-calendar --enable-fpm --with-fpm-user=www-data --with-fpm-group=www-data --with-curl --enable-dba --enable-exif --enable-ftp --with-gd --with-gettext --enable-mbstring --with-mysql --with-mysqli --with-pdo-mysql --with-openssl --with-pcre-regex --enable-shmop --enable-soap --enable-sockets --enable-sysvmsg --enable-wddx --enable-zip --with-zlib --enable-sysvsem --enable-sysvshm --with-mcrypt --enable-pcntl --enable-mbregex --with-mhash --with-xsl
make && sudo checkinstall

Now we need to copy the init.d script and the new php-fpm.conf into place.  Even if you already had PHP-FPM installed, these steps are essential because the configuration format has changed, and we need to modify a couple of settings.  You can move the new files into place like so:

sudo cp sapi/fpm/init.d.php-fpm /etc/init.d/php-fpm
sudo chmod +x /etc/init.d/php-fpm
sudo cp sapi/fpm/php-fpm.conf /usr/local/etc/php-fpm.conf
sudo cp php.ini-production /usr/local/lib/php.ini

There are a few things you’ll need to change in the config file before we can actually start PHP.  Make sure you open /usr/local/etc/php-fpm.conf in your favorite text editor and change the following values.  Please note that the “pm” settings are what I use on my VPS, but you might want to adjust them to better suit your environment.

pid = /usr/local/var/run/php-fpm.pid
pm.max_children = 10
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 5

Now you can stop and start PHP-FPM like so:

sudo /etc/init.d/php-fpm restart

Step 3:  Ruby Enterprise Edition, Nginx, and Phusion Passenger

By far the best way to run a Rails site in production is by using Phusion Passenger and Ruby Enterprise Edition.  The performance benefits are huge, and this setup is very friendly to limited resource environments (like VPS’s).  During the installation of Ruby Enterprise Edition, we will have the opportunity to customize our Nginx install, so we need to snag its source too.  Here’s how:

wget http://nginx.org/download/nginx-0.7.67.tar.gz
wget http://rubyforge.org/frs/download.php/71096/ruby-enterprise-1.8.7-2010.02.tar.gz
tar -zxf nginx-0.7.67.tar.gz
tar -zxf ruby-enterprise-1.8.7-2010.02.tar.gz
./ruby-enterprise-1.8.7-2010.02/installer

This install process is pretty seamless.  Once you’re done, you need to run one more command to enable Phusion Passenger support in Nginx:

sudo /opt/ruby-enterprise-1.8.7-2010.02/bin/passenger-install-nginx-module

This install script will ask you a series of questions.  I prefer to customize my Nginx install, so here are my answers.  Obviously, you’ll need to adjust any paths to places appropriate for your system and where you extracted the nginx source tarball.

Enter your choice (1 or 2) or press Ctrl-C to abort: 2
Please specify the directory: <enter your directory, in my case it was /home/scott/nginx-0.7.67>
Please specify a prefix directory [/opt/nginx]: /usr/local/nginx
Extra arguments to pass to configure script: --sbin-path=/usr/local/sbin --with-http_ssl_module --without-mail_pop3_module --without-mail_imap_module --without-mail_smtp_module --with-http_stub_status_module --with-http_gzip_static_module

Step 4:  Nginx Configuration

We took care of PHP above, so all we need to do now is configure Nginx.  My default configuration file is below.  You can tweak it however you like, but these settings work really well in my environment.  If you used the same options as I did above, you can find this file at /usr/local/nginx/conf/nginx.conf:

user  www-data;
worker_processes  4;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  10 10;

    passenger_root /opt/ruby-enterprise-1.8.7-2010.02/lib/ruby/gems/1.8/gems/passenger-2.2.15;
    passenger_ruby /opt/ruby-enterprise-1.8.7-2010.02/bin/ruby;
    passenger_pool_idle_time 1000;

    gzip  on;
    gzip_comp_level 1;
    gzip_proxied any;
    gzip_types text/plain text/css application/x-javascript text/xml application/xml application/xml+rss text/javascript;

    log_format main '$remote_addr - $remote_user [$time_local] '
        '"$request" $status  $body_bytes_sent "$http_referer" '
        '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx_access.log main;

    error_log  /var/log/nginx_error.log crit;

    include /usr/local/nginx/sites-enabled/*;
}

Now we need to set some default fastcgi options in /usr/local/nginx/conf/fastgci_params.  I just appended these to the end of the file.

fastcgi_connect_timeout 60;
fastcgi_send_timeout 180;
fastcgi_read_timeout 180;
fastcgi_buffer_size 128k;
fastcgi_buffers 4 256k;
fastcgi_busy_buffers_size 256k;
fastcgi_temp_file_write_size 256k;
fastcgi_intercept_errors on;

Next, I like to create a "/usr/local/nginx/sites-enabled" directory that houses each website’s configuration details.  First I’ll show the configuration I used to handle URL rewrites for WordPress (this blog).  I called the file /usr/local/nginx/sites-enabled/geeksharp.com.

server {
 listen 80;
 server_name *.geeksharp.com *.geeksharp.info *.geeksharp.org geeksharp.info geeksharp.org;
 rewrite ^(.*) http://geeksharp.com$1 permanent;
}

server {
 listen 80;
 server_name geeksharp.com;
 location / {
 root   /var/www;  # absolute path to your WordPress installation
 index  index.php index.html index.htm;

 # this serves static files that exist without running other rewrite tests
 if (-f $request_filename) {
 expires 30d;
 break;
 }

 # this sends all non-existing file or directory requests to index.php
 if (!-e $request_filename) {
 rewrite ^(.+)$ /index.php?q=$1 last;
 }
 }

 location ~ \.php$ {
 fastcgi_pass 127.0.0.1:9000;
 fastcgi_index index.php;
 fastcgi_param SCRIPT_FILENAME /var/www$fastcgi_script_name;
 include fastcgi_params;
 }
}

Here’s how I’d set up a rails site.  In this example, the file is called /usr/local/nginx/sites-enabled/geeksharp.net.

server {
 listen 80;
 server_name *.geeksharp.net;
 rewrite ^(.*) http://geeksharp.net$1 permanent;
}

server {
 listen 80;
 server_name geeksharp.net;
 root /home/scott/geeksharp.net/public;
 passenger_enabled on;
 access_log /home/scott/geeksharp.net-access.log;
 error_log /home/scott/geeksharp.net-error.log;
}

Step 5:  Startup Scripts

We already copied the PHP startup script into place earlier, however we need to create one for Nginx, too.  Place this file at /etc/init.d/nginx and use the following contents:

#! /bin/sh

### BEGIN INIT INFO
# Provides:          nginx
# Required-Start:    $all
# Required-Stop:     $all
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: starts the nginx web server
# Description:       starts nginx using start-stop-daemon
### END INIT INFO

PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
DAEMON=/usr/local/sbin/nginx
NAME=nginx
DESC=nginx 

test -x $DAEMON || exit 0

# Include nginx defaults if available
if [ -f /etc/default/nginx ] ; then
 . /etc/default/nginx
fi

set -e

case "$1" in
 start)
 echo -n "Starting $DESC: "
 start-stop-daemon --start --quiet --pidfile /usr/local/nginx/logs/$NAME.pid \
 --exec $DAEMON -- $DAEMON_OPTS
 echo "$NAME."
 ;;
 stop)
 echo -n "Stopping $DESC: "
 start-stop-daemon --stop --quiet --pidfile /usr/local/nginx/logs/$NAME.pid \
 --exec $DAEMON
 echo "$NAME."
 ;;
 restart|force-reload)
 echo -n "Restarting $DESC: "
 start-stop-daemon --stop --quiet --pidfile \
 /usr/local/nginx/logs/$NAME.pid --exec $DAEMON
 sleep 1
 start-stop-daemon --start --quiet --pidfile \
 /usr/local/nginx/logs/$NAME.pid --exec $DAEMON -- $DAEMON_OPTS
 echo "$NAME."
 ;;
 reload)
 echo -n "Reloading $DESC configuration: "
 start-stop-daemon --stop --signal HUP --quiet --pidfile /usr/local/nginx/logs/$NAME.pid \
 --exec $DAEMON
 echo "$NAME."
 ;;
 *)
 N=/etc/init.d/$NAME
 echo "Usage: $N {start|stop|restart|force-reload}" >&2
 exit 1
 ;;
esac

exit 0

Finally, make sure you update your rc.d

sudo update-rc.d nginx defaults
sudo update-rc.d php-fpm defaults

Please note that if for some reason nginx won’t start, chances are you have a config issue.  When you issue a restart command, the config errors usually will not be displayed.  The best way to track them down is to is to simply issue a stop command followed by a start command, and your errors will be displayed.  If you ever need to restart your services manually, you can use these commands (I find that restart can be buggy, which is why I explicity stop and start each one):

sudo /etc/init.d/php-fpm stop && sudo /etc/init.d/php-fpm start
sudo /etc/init.d/nginx stop && sudo /etc/init.d/nginx start

So that’s it! I know this is an epic post, but I hope it helps someone. Leave comments if you have specific questions or if I left out something particularly useful. Again, I understand that there’s probably a better way to do something, so feel free to share your thoughts!  As a final thought, I would like to thank Joshua Dorkin for providing a great article on which I based a lot of this material!

using System;
using System.Collections.Generic;
using System.Linq;
using System.Linq.Expressions;

namespace MyApplication.Models {
    public interface ISession : IDisposable {
        void CommitChanges();
        void Delete<T>(Expression<Func<T, bool>> expression) where T : class;
        void Delete<T>(T item) where T : class;
        void DeleteAll<T>() where T : class;
        T Single<T>(Expression<Func<T, bool>> expression) where T : class;
        IQueryable<T> All<T>() where T : class;
        void Add<T>(T item) where T : class;
        void Add<T>(IEnumerable<T> items) where T : class;
        void Update<T>(T item) where T : class;
    }
}

This simple interface is pretty powerful. Using Ninject (our DI/IoC library of choice), it’s simple to inject our concrete EF4 implementation of this interface into the service layer of our MVC projects.  Since our service layer sits in between our MVC application and the database, it’s critical that we put tests around them.  It’s important to realize, though, that we only want to test the service itself, not the EF4 integration.  We can test the EF4 integration separately using integration tests.  Since our services all take ISession objects in their constructors, we are left with no other options but to mock ISession.

Enter Moq

Moq is a sweet mocking library for the .NET framework.  We use it extensively in our tests to help focus our tests on specific concerns.  As stated above, our services rely on an ISession implementation to work properly, but that doesn’t mean we have to feed it a real ISession.  Moq allows us to create a fake ISession that our services can call.  This, in turn, allows us to focus our tests on just the service itself.

If you’ve ever used Moq before, and you look at the very generic ISession interface above, you quickly realize that mocking this behavior is a little challenging.  Luckily, it’s definitely not impossible… we just have to flex our lambda muscles.  I’ve written a class called “FakeSessionBuilder” for my applications so we can build up a mocked ISession object for use in tests.  Here’s the class:

// This code is released under the Creative Commons CC0 License
// Find the license here:  http://creativecommons.org/publicdomain/zero/1.0/
using System;
using System.Collections.Generic;
using System.Linq;
using System.Linq.Expressions;
using Moq;
using MyApplication.Models;

namespace MyApplication.Tests.Mocks {
    public class FakeSessionBuilder {
        public readonly Mock<ISession> Mock;

        public FakeSessionBuilder() {
            Mock = new Mock<ISession>();
        }

        public void LoadFakeCollection<T>(List<T> collection) where T : class {
            if (collection != null) {
                Mock.Setup(x => x.Single(It.Is<Expression<Func<T, bool>>>(z => z != null)))
                    .Returns((Expression<Func<T, bool>> func) => collection.SingleOrDefault(func.Compile()));
                Mock.Setup(x => x.All<T>())
                    .Returns(collection.AsQueryable());
                Mock.Setup(x => x.Add(It.IsAny<T>()))
                    .Callback((T item) => collection.Add(item));
                Mock.Setup(x => x.Add(It.IsAny<IEnumerable<T>>()))
                    .Callback((IEnumerable<T> items) => items.ToList().ForEach(collection.Add));
                Mock.Setup(x => x.Delete(It.Is<Expression<Func<T, bool>>>(z => z != null)))
                    .Callback((Expression<Func<T, bool>> func) => collection.Remove(collection.SingleOrDefault(func.Compile())));
                Mock.Setup(x => x.Delete(It.IsAny<T>()))
                    .Callback((T item) => collection.Remove(item));
                Mock.Setup(x => x.DeleteAll<T>())
                    .Callback((T type) => collection.Clear());
            }
        }
    }
}

The bread and butter of this class is obviously the LoadFakeCollection() method.  Basically, we’re setting up a fake session that will actually perform the tasks that we want it to.  This might make a few people cringe.  I can hear the questions now:

1. Why are you creating logic within the mocked methods?

   I think the better question is “why not?”  Honestly I don’t think we’re really creating any logic here that needs to be tested.  If you look closely, we’re using internal .NET collections (List<T>) and their built-in methods.  We’re actually hitting the framework here, not custom code.  I don’t typically worry about testing the actual .NET framework.  Do you?

2. All these crazy lambda expressions make my head hurt.  Couldn’t you do this another way?

   Yes, I probably could.  But I wanted to make this session builder as generic as possible.  This allows us to reuse the fake session in service test class.  I don’t want to repeat myself any more than I have to.  And let’s face it, the ISession interface itself may look simple (and actually implementing it is easy as pie), but slinging all those generics around does make mocking harder.

3. Couldn’t you avoid mocking completely and just write another concrete implementation of ISession that isn’t tied to your database?

   Yeah, I suppose I could.  But I honestly think it would be a lot harder, and it would repeat a lot more code.  Moq also lets me do neat things like verifying that a method is actually called in a much easier way.  I like the flexibility that Moq gives me, and this code is actually pretty elegant, in my opinion.  I dare you to write a concrete implementation that handles everything as cleanly as Moq does.

So how do you use this thing?

It’s actually pretty simple.  I’m sure you’re familiar with the arrange, act, assert method of testing, right?  Well in my tests for my service layer, I create my fake session, load it up with any collections I want it to contain, and then use that in the arrangement for my tests.  I’m sure a code sample would help here, so here you go:

using System.Collections.Generic;
using System.Linq;
using MyApplication.Models;
using MyApplication.Services;
using MyApplication.Tests.Mocks;
using Xunit;

namespace MyApplication.Tests.Admin {
    public class MyCustomServiceTests {

        public ISession GetFakeSession() {
            // First grab collections of fake objects used in the test
            List<MyCustomModel> models1 = Mocks.GetListOfFakeCustomModels();
            List<MyOtherModel> models2 = Mocks.GetListOfFakeOtherModels();

            // Now build a fake session loaded with these collections
            var fakeSession = new FakeSessionBuilder();
            fakeSession.LoadFakeCollection(models1);
            fakeSession.LoadFakeCollection(models2);
            return fakeSession.Mock.Object;
        }

        [Fact]
        public void GetMyCustomModelByID() {
            // Arrange
            ISession session = GetFakeSession();
            var service = new MyCustomService(session);

            // Act
            MyCustomModel model = service.GetByID(1);

            // Assert
            Assert.NotNull(model);
            Assert.Equal(1, model.ID);
        }
    }
}

Wrapping it up

I hope you can see how easy it is to use the FakeSessionBuilder object.  I’m definitely not a TDD guru.  I’d love to hear from you to see exactly how you would accomplish the same tests in your application.  Hopefully you find this useful.  I’ve released it under the most free license I could find.  Cheers!