Solution configurations & project configurations

Greetings, dear readers!  Today I want
to talk about solution configurations and project configurations.  These
are important concepts that are essential to understand if you’re trying to do complex
coordination of builds using VS, esp. if you're using the DTE or devenv /build at
the command line.  However, this is a
tricky subject which even a lot of people within the Developer Division don’t fully
understand.  Also be sure to see the documentation
page for project & solution configurations

"urn:schemas-microsoft-com:office:office" />

Let’s start with projects.  Projects can
have an arbitrary set of configurations.  Think
of a configuration as a knob that tells Visual Studio how to
build a project.  The classic configurations
are “Debug” and “Release”.  For most users,
there is no need to go beyond these.  However,
you might want to define your own project configuration if you want additional ways
to build your project (say, with additional diagnostics built in) that don’t exactly
map to what you want in a debug build or in your final release build.

You can create (or delete) project configurations in a dialog called the Configuration
Manager.  You can reach this via Build.Configuration
Manager menu item.  To add a new project
configuration, find row for the project and find the “Configuration” column.  Click
on the dropdown and click on “<New…>” (this dialog will never win any usability
awards).  This lets you create a new project
configuration.  You specify three pieces
of information.  First, the name.  Second,
you can optionally specify another configuration to copy settings from (for example,
if you’re making a configuration that’s just like your Debug configuration but only
differs in a few settings, pick Debug to copy from).  Third,
you can create a solution configuration that corresponds to it (more about that later).

Understand that a project configuration is a parallel bucket of settings.  If
you create a new project configuration that copies from the Debug project configuration,
you are doing a copy, but any changes you make later to the Debug project configuration
won’t be reflected in your copy.  (The
same principle applies to solution configurations.)

Now, what’s a solution configuration?  Think
of a solution configuration as a bucket of arbitrary project configurations.  Solution
configurations don’t have to have the same name as project configurations.  A
solution configuration is essentially a list of all your projects where you pick which
projects should be included and which configurations should be built.

Let’s try an example.  Create a new C#
Windows Application project.  Now click
on Build.Configuration Manager again to return to the Configuration Manager dialog.  What
you are looking at is the list of projects and configurations for the solution’s “Debug”
configuration.  There is only one project
in the list.  The configuration for this
project that we’re building is “Debug”, and the platform is “.NET”.  The
“Build” checkbox is checked.

If you uncheck the “Build” checkbox, it means that the “Debug” solution configuration
shouldn’t build your C# winapp project.  So
when you do Build.Build Solution, nothing will be built.  This
is useless for a single-project solution, but can be useful if you have a lot of projects
and there are scenarios where you only want to build a few.  In
that case you can create a new solution configuration to do this.

How do you create a new solution configuration?  At
the top of the Configuration Manager dialog there’s a dropdown with a list of solution
configurations.  Click this dropdown and
pick “<New…>”.  Then you can create
a new solution configuration.  It’s just
like creating a new project configuration except that instead of being asked if you
want to create a new solution configuration, you’re now asked if you want to create
new project configurations to mirror the new solution configuration.  (To
get rid of either a solution or project configuration, click on <Edit…> in the
appropriate dropdown.)

Let’s go back to the Configuration Manager dialog for the C# winapp we created.  We’ve
discussed the “Build” checkbox, but what about the Configuration and Platform columns?  These
are very important.  The two of these
put together make a true project configuration.  For
example, if you have Debug and .NET selected, your project configuration is “Debug|.NET”.  This
is a very important point.  When you reference
a project configuration via the DTE or via the command line (devenv /build), you need
to refer to project configurations using the combined form.  Note
that the platform can be different, e.g. in VC++ if you are targeting Win64.  You
can then have Debug|Win32 and Debug|Win64, and these represent totally different project
configurations.

If you’re back at the Configuration Manager dialog with our little C# app, you should
see the “Debug” solution configuration selected in the dropdown at the top.  If
I go down to my project and go to the “Configuration” row, the dropdown says “Debug”.  Just
for fun, change it to “Release”.  If you
hit OK, then every time you build the “Debug” solution configuration, you’ll be building
the “Release” configuration of your project!  This
is kind of a silly example, but a practical application would be if you want to enable
a special diagnostic build (e.g. heavy assertions) in one of your projects but not
others.  For a given solution configuration,
you can pick arbitrary configurations for your projects.

In different parts of the VS IDE, you will sometimes interact with solution configurations
and sometimes with project configurations.  On
the main IDE toolbar, there’s a dropdown that controls your active solution configuration.  This
is what solution configuration gets build if you do Build.Build Solution.

Project configurations come into play when editing project settings.  For
example, if you right-click on a project in the solution explorer & bring up the
project’s properties (or if you just pick Project.Properties in the main menu) you’ll
see a property sheet with the project configuration settings (expressed via its two
halves, the basic configuration plus the platform).  Once
again, I want to remind you that when referring to a project configuration via DTE
or devenv /build, you need to refer to the whole thing, e.g. “Debug|.NET” or “Release|Win32”.

One other note.  You might be wondering
if you can have a solution configuration with multiple instances of the same project.  You
cannot.  However, you can approximate
this using the Batch
Build dialog (Build.Batch Build in the main menu), which I might cover in a future
blog entry.

That’s all for now! -Chris

Comments

• Anonymous
  August 15, 2003
  I found the interaction between solution and project configurations to be quite intuitive when using the Configuration Manager (we use four configurations - debug, release, readonlydebug and readonlyrelease). Unfortunately I had lots of problems when upgrading our VS6 build (ANSI MFC app with VB6 plug-ins) to a VS.NET build (Unicode MFC app with VB.NET/C# plug-ins). The old system used a "build everything to one location" approach, but this just didn't seem to work well in VS.NET as I ran into lots of build errors due to files being locked and some very weird ones along the lines of "Cannot convert from NamespaceA.TypeA to NamespaceA.TypeA". Eventually it was fixed by using project references rather than binary references where appropriate, and building assemblies to their own private location with CopyLocal set to True. What was disappointing was that there seemed to be very little documentation with regards to setting up mixed language solutions and it seemed to me that, although the options exist to build in a variety of ways, there are only one or two ways to build large solutions successfully. It also seems strange to me that there are no build events associated with VB.NET projects, since this makes it unnecessarily awkward to add/remove VB.NET assemblies in the GAC as part of the build.
• Anonymous
  August 18, 2003
  Hi Kevin - Sorry to hear that you ran into these issues. I expect (but can't promise) that most of these issues will be fixed (or at least made much simpler to cope with) in the next major release. -Chris