Peter Morlion logo


Understanding the .NET Build Configuration System

Editorial note: I originally wrote this post for the Submain blog. You can check out the original here, at their site.
When you create a .NET application in Visual Studio, it contains two build configurations: Debug and Release. But what does this mean exactly? Most developers will tell you that you can transform your Web.config or App.config based on the selected build configuration. For example, when you select “Debug,” your database connection string might point to a database on your PC (i.e. “localhost”). Then, when you select “Release,” it could point to the production database.

But the build configuration system in .NET goes beyond just transforming the config file. There is a whole system of solution and project configuration management that you can use to your advantage.

A project configuration contains a set of properties to be used when building the project. Likewise, a solution configuration contains a set of properties at the solution level. But it also contains the selected project configurations for that solution configuration. An example should clarify.

Build Configurations In Visual Studio

The easiest way to see this in action, is to open Visual Studio and create a new ASP.NET Web Application:

Note that I’ve chosen the traditional .NET Framework instead of ASP.NET Core because it’s easier to demonstrate the points I want to make. But the concepts explained here also work for .NET Core.

Next, choose the MVC template:

By default, Visual Studio will have created two configurations: Debug and Release. The idea is to use Debug locally, when debugging your application. When you want to deploy your application, use Release.

Project Configurations

A project can have a different set of properties per combination of configuration and platform. For example, this means you could optimize your build output size for the x64 platform in the Release configuration, while optimizing for diagnostics when building for any CPU in the Debug configuration.

To see what you can change in a project configuration, right-click the project and select Properties. Some tabs will allow you to differ the chosen settings per configuration, others will not. Here you can see the Build tab, with two dropdowns at the top:

Changing the selected values in these dropdowns will change the settings in the part below them.

Solution Configurations

A solution configuration can been seen as a combination of project configurations. By default, there are two solution configurations that match the default project configurations: Debug and Release. To see this, right-click the solution and choose Properties. Then open the Configuration Properties item and choose Configuration:

In the top part of the window, you can see the selected solution configuration and platform. Then in the main part, you can see the selected project configurations and platforms. You can also see if the project should be built or deployed.

This now provides us with some powerful options. Look at this solution configuration for example:

Here we’ve chosen the Release configuration for the x64 platform. In this solution configuration, UnitTestProject1 will not be built and ClassLibrary2 will be built against the AnyCPU platform (meaning it works on both 32-bit and 64-bit). The WebApplication2 and ClassLibrary2, however, will be built for 64-bit only.

In theory, you can take this very far. You could have a solution configuration for Release and x64 but still have some projects be built in Debug and for x86 (i.e. 32-bit). Needless to say, you should make sure that everything still works when you run the application. It’s equally important┬áthat the combination of configurations and platforms makes sense and doesn’t confuse developers.

More Than Just Debug and Release

In my examples above, I only talked about the Debug and Release configurations. But in more complex projects, you will probably need more than just these two.

Luckily, making new build configurations in Visual Studio is very easy. Right-click your solution and choose Configuration Manager. In the following window, you can once again select the different project configurations and platforms under your solution configuration. But in each drop-down, you will now also see the option to create a new configuration or platform and to edit the available options:

In the next window, you can specify the name for your configuration, choose to copy existing settings, and create matching project configurations:

If you haven’t changed the default Visual Studio layout too much, you will see that the top toolbar contains two drop-downs, indicating in which solution build configuration you will be running or building:

One Final Tip

There are many little known gems in Visual Studio. One of them concerns the build configuration system. In the Build menu, there is an option named “Batch Build.” When you select this, you will see the following window open:

In this window, you can select all the configurations you want to build, rebuild, or clean. Visual Studio will then perform the selected action for all selected projects, configurations, and platforms.

Proceed with Caution

As I’ve mentioned above, you can quickly create a confusing set of build configurations when the names don’t match between project configurations and solution configurations.

And try to keep the amount of configurations to a minimum. Typically, you will see configurations match the name of environments where the application can be deployed (e.g., Debug (for local development), Staging, QA, and Production).

But if you create a sensible set of build configurations, you will be able to easily build for and switch between different environments, settings, and platforms.

Leave a Reply

Your email address will not be published. Required fields are marked *