VS 2003+

Switching Configuration Files for Debug and Release Modes

by Richard Carr, published at http://www.blackwasp.co.uk/SwitchConfig.aspx

Configuration data can be held in the App.config file, which is renamed and copied to the output folder during compilation. If the debug and release modes of a project require different settings, the configuration file can be switched using a build event.

App.config File

When you wish to create a project that can be configured at run-time, a good approach is to include a plain text configuration file. The file's contents can be edited using any standard text editor, such as Notepad, and be read and acted upon whilst your program is executing. A standard way of creating such a configuration is using the App.config file. This can be added to most types of project and edited directly in Visual Studio using the text editor or the Settings designer, which is found in the project's properties. NB: The settings designer is not available in all versions of Visual Studio.

It is possible to include many different types of setting in a configuration file. For example, you might add a database connection string, allowing the database or server name to be changed without needing to recompile the software. You may include an option to enable or disable logging so that you can temporarily enable it on the user's computer whilst diagnosing a problem.

Sometimes the configuration settings should have different values according to whether you are debugging your program or if it is executing in a production environment. Unfortunately Visual Studio does not provide a simple option to allow the configuration file to change depending upon the build settings. However, by using Visual Studio's build events we can use one file for projects compiled in debug mode and an alternative file when building a release mode executable. This article describes a walkthrough of this technique.

Creating the Walkthrough Project

Our test project will be a simple Windows Forms application containing a single form that includes a button. When clicked, the button will display a message that can be set in the configuration file. You could equally apply the techniques described here to other types of executable project, including console applications, Windows services or Windows Presentation Foundation (WPF) projects.

To begin, create a new Windows Forms application. If you have configured Visual Studio to create unsaved projects by default, make sure that you save the new solution.

Creating the Configuration File

The new project should include an App.config file by default. If it does not, add one. Depending upon the version of Visual Studio that you are using it is possible that the file will already contain some settings or it may be relatively empty. In any case, update the file to include the following "Message" application setting. You can leave any existing settings in place. The message will be displayed the user clicks a button.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <appSettings>
        <add key="Message" value="Built in Debug Mode"/>
    </appSettings>
</configuration>

Once the configuration file is updated, build the project to ensure that the file is correctly structured.

Adding the Release Mode Configuration File

The App.config file's configuration settings will be used automatically when you execute the program in the Visual Studio debugger. It will also be copied to the build output folder when you compile in Debug mode. At this time it will be renamed to include the file name of the executable. For example, "MyProject.exe.config".

When we build the project in Release mode, we want to replace the default App.config with an alternative that contains the live configuration. The release mode version of the configuration needs to be held somewhere so we'll store it in a new file named, "Release.config". To set up this file create a copy of the App.config file and rename it accordingly. Once renamed, edit the file's contents to modify the message, as in the example below:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <appSettings>
        <add key="Message" value="Built in Release Mode"/>
    </appSettings>
</configuration>

NB: It is important to remember to update the Release.config file whenever a new setting is added to the App.config, either manually or via the settings designer in the project's properties.

Displaying a Message

So that we can see the effect of changing the configuration file at compilation time we need to use the Message setting in our Windows Forms application. Open the designer for the automatically added form and add a button. Double-click the button to create an event handler for the click event and add the following code to the generated method. This shows the message from the configuration file when the user clicks the button.

string msg = ConfigurationSettings.AppSettings["Message"];
MessageBox.Show(msg);

You may also need to add the following using directive to the code to provide access to the System.Configuration namespace.

using System.Configuration;

Adding the Build Event

Currently, if we build the project in any mode, we'll see the message from the App.config file when we click the button. We now need to detect Release mode and substitute our Release.config file for the copied and renamed App.config. We can do this by adding a post-build event. NB: We must use a post-build event. If we operate pre-build our configuration file will be overwritten during compilation.

Build events contain commands that would normally be used in a command window. We need to add the following:

if "Debug"=="$(ConfigurationName)" goto :nocopy
del "$(TargetPath).config"
copy "$(ProjectDir)\Release.config" "$(TargetPath).config"
:nocopy

The first line of the build event code checks the current configuration option to see if it is set to "Debug". If it is, the configuration file does not need to be changed so the goto causes control to move to the final line.

If we are building in Release mode, the existing configuration file is deleted from the output folder by the second line of the build event. The third command copies the Release.config file from the project folder into the output folder and renames it to match the name of the file that was previously removed. This replaces the Debug mode configuration file with the Release mode variant.

Testing the Build Event

To check that the build event is working, compile the project in both modes. Open Windows Explorer and browse to the build folders. You should find that the Debug folder contains a configuration file with the message, "Built in Debug Mode". If you double-click the EXE file and click the button you should see this message. In the Release folder the message found in the configuration file, and that displayed when the program is executed, should be, "Built in Release Mode".