Postbuild Projects (Visual Studio)

On any project of sufficient complexity, there comes a time when things need to be setup a particular way in order for the product to function correctly. It could be late-bound assemblies, native libraries, data files, etc. Visual Studio provides a means to perform pre- and post-build actions on a given project in the project properties dialog. There are countless other blogs out there which cover this in detail. In this post I make the case against that approach and why you should probably use a dedicated project for all your postbuild needs.

First, what's wrong with having postbuild steps on every individual project?

1. Postbuild steps almost always involve an implicit relationship between projects. For instance, your new chat plugin must be copied to the same directory as the chat application in another project. Thus, the steps are generally not useful to the project by itself.
2. Conceptually, a solution is an arbitrary collection of projects. If you create a postbuild step on your project which makes a lot of sense in one solution, it most likely will fail when that project is referenced in another solution.
3. It is very difficult to create and maintain custom postbuild steps for different environments of configurations. For instance, there is no easy for developers to comment out certain steps which do not apply to the build environment on their machine.
4. Eventually, the number of separate postbuild steps will become confusing and hard to manage easily.

Now let's look at what a postbuild project is and then how it addresses these issues. The postbuild project is its own dedicated project which serves no other purpose but to run the postbuild script. Creating this in Visual Studio 2008 is not obvious since the removal of the "Utility Project" template.

For convenience, I have created a postbuild template you can use and attached it to this post (scroll down). Download the file and copy it to My Documents\Visual Studio 2008\Templates\ProjectTemplates. Do not unzip the file. Now when you create a new project in Visual Studio, you should find a new template in "Visual C#" under the "My Templates" heading called "PostBuild". Go ahead and create one.

The template creates a very minimalist project which contains a PostBuild.bat DOS batch file and has the project postbuild step set to execute it passing in the configuration type. Note that Visual Studio no longer allows projects with no output, so a PostBuild.dll will be created. It can be safely ignored. One other detail is the encoding of the batch file. By default, Visual Studio saves files in UTF-8. This does not work for batch files. The PostBuild.bat in the template is already set to save using the correct codepage (1252).

Important: You must set the PostBuild.bat project to depend on all other projects so you can be guaranteed it will build last. Right-click on the project, click "Project Dependencies" and then click all the boxes. You can verify this was done correctly by verifying that PostBuild is the last item in the Build Order dialog.

Now let's look at the batch file itself. Visual Studio will pass in the configuration type as the first parameter to the batch file. Switch on this value to perform different tasks. In the example, the DLLs are copied for both configuration types, but PDBs are only copied in the Debug configuration. From here it is easy to set conditions based on machine-local environment variables (not shown).

Now that we've seen what a PostBuild project looks like, let's revisit the list above and see how it compares:

1. The PostBuild project makes no claim to being isolated and functional within the scope of a single project, so this issue is eliminated.
2. The PostBuild project violates the basic concept of projects being independent of one another within a solution. But it does so in an obvious way which reduces confusion and makes it obvious what is going on. The big advantage is that now when a project is referenced in another solution which has different postbuild needs, there is no conflict or errors.
3. By switching on machine-local environment variables, it is easy to skip some steps for running the application on the developers' machines.
4. The PostBuild.bat is a one-stop-shop for all your postbuild needs. It's obvious where all the commands are and what they are doing.

One final point of note is the relationship between the PostBuild script and the build script. Of course, you could skip the PostBuild project and put all the commands in the build script, but this often doesn't work in situations where the developers need to test rapidly no their local machines. Build scripts often reset databases and perform other tasks which would be undesirable to the developer. This segmentation makes the build process flexible.