NAnt or MSBuild, which one to choose and when?

I've done a similar investigation this week. Here's what I've been able to determine:

NAnt:

• Cross-platform (supports Linux/Mono). It may be handy for installing a web site to multiple targets (that is, Linux Apache and Windows IIS), for example.
• 95% similar in syntax to Ant (easy for current Ant users or Java builders to pick up)
• Integration with NUnit for running unit tests as part of the build, and with NDoc for producting documentation.

MSBuild:

• Built-in to .NET.
• Integrated with Visual Studio
• Easy to get started with MSBuild in Visual Studio - it's all behind the scenes. If you want to get deeper, you can hand edit the files.

Subjective Differences: (YMMV)

• NAnt documentation is a little more straightforward. For example, the MSBuild Task Reference lists "Csc Task - Describes the Csc task and its parameters. " (thanks for the "help"?), vs the NAnt Task Reference "csc - Compiles C# programs." UPDATE: I've noticed the MSBuild documentation has been improved and is much better now (probably on par with NAnt).
• Not easy to figure out how to edit the build script source (*.*proj file) directly from within Visual Studio. With NAnt I just have Visual Studio treat the .build script as an XML file.
• Apparently, in Visual Studio, Web Application Projects don't get a *.*proj file by default, so I had great difficulty figuring out how to even get MSBuild to run on mine to create a deployment script.
• NAnt is not built-in to Visual Studio and has to be added, either with an Add-In, or as an "External Tool". This is a bit of a pain to set up.
• (Edit:) One of my coworkers brought this up--if you want to set up a build machine using CruiseControl for continuous integration, CruiseControl integrates with NAnt nicely out of the box. UPDATE: CruiseControl also has an MSBuild task.
• Please see comments below for full and up-to-date discussion of subjective differences.

One of the major draws of MSBuild for me (on Windows platforms) is that it comes as part of .NET itself. That means that any Windows machine that is up-to-date with Windows Update will have MSBuild available. Add to this the fact that C# compiler is also part of .NET itself and you have a platform that can build projects on clean machines. No need to install Visual Studio behemoth. NAnt, on the other hand, has to be explicitly installed before a build can be triggered.

Just for the record, I've used NMake, Make, Ant, Rake, NAnt and MSBuild on non-trivial builds in the past (in that order). My favourite is MSBuild, hands down (and I do not favour it because "that's what Visual Studio uses"). IMHO, it is a very under-appreciated build tool.

I would compare NAnt vs. MSBuild to the difference between procedural and functional programming. NAnt is quite straightforward and you-get-what-you-see. MSBuild on the other hand requires a bit more thought. The learning curve is steeper. But once you "get it", you can do some amazing things with it.

So I would recommend looking at MSBuild if you also gravitate towards functional or logical style programming - if you are willing to invest a bit of time and effort before seeing tangible results (of course, I also strongly believe that the investment eventually pays off and you can do more powerful things more efficiently).

Personally, I use both - for the same project.

MSBuild is great at building Visual Studio solutions and projects - that's what it's made for.

NAnt is more easily hand-editable, in my opinion - particularly if you already know Ant. NAnt can call MSBuild very easily with NAntContrib. So, I hand-craft a NAnt script to do things like copying built files, cleaning up etc - and call MSBuild to do the actual "turn my C# source code into assemblies" part.

If you want an example of that, look at my Protocol Buffers build file. (I wouldn't claim it's a fabulous NAnt script, but it does the job.)

NAnt has more features out of the box, but MSBuild has a much better fundamental structure (item metadata rocks) which makes it much easier to build reusable MSBuild scripts.

MSBuild takes a while to understand, but once you do it's very nice.

Learning materials:

• Inside the Microsoft Build Engine: Using MSBuild and Team Foundation Build
  by Sayed Ibrahim Hashimi (Jan, 2009)
• Deploying .NET Applications: Learning MSBuild and ClickOnce by Sayed
  by Y. Hashimi (Sep, 2008)

KISS = Use MSBuild.

Why add something else into the mix when you have something that will do a reasonable job out of the box? When MSBuild arrived, NAnt died. And Mono will have an MSBuild implementation, (xbuild).

DRY = Use MSBuild.

Ask yourself what do you want out of a build system? I want a build system that is also used by my IDE rather than the maintaining two different configurations.

Personally, I'd love to hear some real arguments for NAnt, because I just can't think of any that really hold water.