Visual Studio Build Events

Visual Studio Build Events

Some projects require that preparatory steps be taken prior to compiling the code. Others require processes to be executed after a successful build. Visual Studio's Build Events allow such pre-build and post-build steps to be automated.

What are Build Events?

Visual Studio allows you to define build events for each project in a solution. These events contain commands that will be executed automatically when you compile the project. Two types of event are available; each containing commands that you could normally run at the command line. Pre-build eventsrun before the compilation of the project begins. Post-build events are executed after the build is completed, if certain specified conditions are met.

Build events have many uses. For example, before compiling you may wish to automatically copy up-to-date resource files from a networked location into the project folder for inclusion in the build. Following a successful build you may wish to copy the output files to a central server, start an automated testing procedure or use ILMerge to combine multiple assemblies into a single library.

Macros

To provide flexibility when writing build events, Visual Studio provides a set of simple macros. These are special codes that can be inserted into the commands in the event. When the event is executed, the macros are replaced with project-specific information, such as project or solution file paths, platform information or project configuration details. This is useful when several developers are working on a project but each has a different location for the local copy of the source code.

The key macros are as follows:

• $(ConfigurationName). The project's configuration details. This is useful if you wish to execute a different event for debug and release mode builds.
• $(DevEnvDir). The installation folder of Visual Studio.
• $(OutDir). This macro is replaced with the relative path to the project's output folder. As with all paths, the macro outputs a trailing backslash (\).
• $(PlatformName). The name of the target platform. For example, "Any CPU".
• $(ProjectDir). The absolute path to the project's folder.
• $(ProjectExt). The extension of the project file.
• $(ProjectFileName). The filename of the project file.
• $(ProjectName). The name of the project.
• $(ProjectPath). The absolute path to the project file.
• $(TargetDir). The absolute path to the project's primary output folder.
• $(TargetExt). The extension of the primary output file, generally ".dll" or ".exe".
• $(TargetFileName). The filename of the project's primary output file.
• $(TargetName). The name of the target assembly.
• $(TargetPath). The absolute path to the project's primary output file, including the name of the executable or dynamic linked library (DLL).
• $(SolutionDir). The absolute path to the solution's folder.
• $(SolutionExt). The extension of the solution file.
• $(SolutionFileName). The filename of the solution file.
• $(SolutionName). The name of the solution.
• $(SolutionPath). The absolute path to the solution file.

Limitations

There are some limitations that you should consider when creating build events. Possibly the most important of these is that error checking within the event is limited. When using events that require a series of commands to be executed, it is usually advisable to move these commands into a batch file within the project folder. The build event can be used to call the batch file, which should include its own error checking.

Adding Build Events

To demonstrate the use of build events, the remainder of this article will describe the process of creating a post-build event that copies a project's compiled output files to another folder. Creating a pre-build event is an almost identical process. The key difference is that pre-build events are not conditional upon the results of the build process. Pre-build and post-build events are also available in Visual Studio 2003, though with a slightly difference user interface.

To add a build event, you use your project's property pages. You can open these by right-clicking the project name in the Solution Explorer pane and choosing "Properties" from the context-sensitive menu that appears. You can also use the project's properties option from the Project menu. Once the property pages are visible, click the Build Events tab.

The Build Events page contains two multi-line textboxes where you can type the commands that you wish to execute before and after the compilation process. Each textbox has an associated button that can be clicked to open a larger editing window for the event. Click the Edit Post Build button to continue with the process. A resizable editor dialog box will be displayed.

If you click the Macros button you will see a list of macros that can be used within the event. These can be added to the event by selecting them and clicking the Insert button, or by simply double-clicking the macro name. You can also type the macro manually if you wish. To create the post-build event, enter the command below into the main editing area. The macro copies the compiled output of the project to the c:\temp folder. Once you have added the build event command, click the OK button to return to the project's property pages.

copy "$(TargetDir)*.*" c:\temp

NB: Ensure that you have created a "temp" folder in the root of your C: disk or use another suitable folder in the build event. The quotation marks (") in the command are used to allow paths to be generated that contain spaces.

The final option when creating a post-build event is to specify the conditions under which it will execute. The drop-down list at the bottom of the page provides three options:

• Always. The post-build event will run whenever the project is compiled. The event will execute even if the build fails.
• On successful build. The event will execute only if the build completes without errors.
• When the build updates the project output. The event will run only when the output files are updated by the build. This prevents the event from executing if the project is recompiled with no changes made.

Select the "On successful build" option. You can now compile the project and see that the output files are copied to the temporary folder automatically.