Creating the .targets file

The .targets file is where you specify what values you want your properties to have. In the vast majority of cases this will be determined by the value of the $(Configuration) built-in variable - this is what you have selected in the little combo-box at the top of Visual Studio:

This example .targets file contains virtually everything you need to know about how MSBuild processes these files:

<PropertyGroup>
    <!-- No condition and processed first means this Property Group specifies the defaults -->
    <csConnStr1>Data Source=localhost;Initial Catalog=Db1;Integrated Security=True;</csConnStr1>
    <csConnStr2>Data Source=localhost;Initial Catalog=Db2;Integrated Security=True;</csConnStr2>
</PropertyGroup>

<PropertyGroup Condition="'$(Configuration)'=='Release'">
    <csConnStr1>Data Source=PRDSQL;Initial Catalog=Db1;Integrated Security=True;</csConnStr1>
    <csConnStr2>Data Source=PRDSQL;Initial Catalog=Db2;Integrated Security=True;</csConnStr2>
</PropertyGroup>

<!-- This is a call to String.Contains. You can use this technique to create "hierarchies" of build configurations.
     See http://msdn.microsoft.com/en-us/library/dd633440.aspx -->
<PropertyGroup>
    <IsEurope>$(Configuration.Contains("Europe"))</IsEurope>
</PropertyGroup>

<PropertyGroup Condition="'$(IsEurope)'=='true'">
    <csConnStr1>Data Source=DEVSQL_EUROPE;Initial Catalog=Db1;Integrated Security=True;</csConnStr1>
    <csConnStr2>Data Source=DEVSQL_EUROPE;Initial Catalog=Db2;Integrated Security=True;</csConnStr2>
</PropertyGroup>

<PropertyGroup>
    <prop1>Hello</prop1>
    <prop2>$(prop1) World!</prop2>
</PropertyGroup>

<!-- This example is how ConfigZilla sets the default document comment -->
<PropertyGroup>
    <czComment1 Condition="'$(czComment1)'==''"> Built using configuration $(Configuration) on machine $(ComputerName) by $(UserName) at $([System.DateTime]::Now.ToString("dd-MMM-yyyy HH:mm")) </czComment1>
</PropertyGroup>


<!-- You can import other MSBuild files. Normally this would be at the
     top (recall that files are processed top-to-bottom). -->
<Import Project="$(MSBuildProjectDirectory)\CommonSettings.targets" />

• Properties can have any name you want (it's a good idea to use a prefix to avoid name clashes)
• They need to be nested inside <PropertyGroup> elements
• They are simple text strings and you can call .Net string methods on them
• The file is processed from top to bottom and later definitions override earlier ones
• A "Condition" can be attached to a PropertyGroup or an individual property. If it's false then the line is ignored.
• Properties and conditions can refer to other properties using the $(name) syntax.
• You can call .Net string instance and static methods on properties because they are just strings
• You can test (czComment1) a property to see if it is already set by comparing it to a blank string
• MSBuild files can import other MSBuild files using the Import element. This is an advanced technique.
• All existing MSBuild properties are available, including the important $(Configuration) property and most environment variables. If you increase the logging level of MSBuild to "normal" ConfigZilla will dump out the values of all properties it is considering.
• More on MSBuild properties in general.
• MSBuild Reserved and Well-Known Properties
• Common MSBuild Project Properties
• Macros for Build Commands and Properties

Using per-project targets

Normally you can simply define all your .targets under the Transforms folder in the ConfigZilla project, and because properties such as $(MSBuildProjectName) are evaluated in the context of the including project this is normally enough flexibility to achieve everything you want, for example you can given log files a unique name for each project using a construct such as this:

<filename>C:\temp\$(MSBuildProjectName).log</filename>

However, ConfigZilla will also look for a "Transforms" folder under each project that you are compiling, and will include those .targets files after the ones from ConfigZilla\Transforms. Should you need it, this gives you even more flexibility to override properties within each project (recall that properties are evaluated from top to bottom so the ones from your project will override the ConfigZilla properties).

Hints and tips

• It's a good idea to start your file with a PropertyGroup that has no conditions as this will establish defaults for all properties. I use this for the "Debug" configuration (in other words, my .target files do not contain explicit overrides for the Debug configuration).
• You can override individual properties or entire groups with an appropriate condition.
• It's a good idea to have the .target file be the only place that mentions the values - edit your .template.config file to have blank settings. That way you won't get confused about where something is being set.
• By using properties in properties you can create a very DRYish .target file, for example instead of writing "localhost" in every connection string you could write $(DbServer).
• If you have many configurations you can arrange them into "hierarchies" if you name them appropriately. For example there might be Debug.Europe.London, Debug.Europe.Madrid, Debug.Europe.Berlin. If they can all be treated the same way for some purposes use "Contains" or some other string method to determine if you are dealing with a European configuration and then act appropriately. Note that in the example above "Contains" returns a Boolean, which MSBuild then calls ToString() on, which is why the =='true' syntax works.
• You can use conditions other than "==" but for real power you will need to use the one-level-of-indirection technique shown above with <IsEurope>. This gives you access to the System.String methods and even regexes.
• When ConfigZilla imports all the .targets files it first sorts them, so that they are imported in directory/file order. Therefore, if you want to define properties that are useful across more than one file (such as <IsEurope> above, then do it in the first file - that is, the first .targets file you come across when you expand the Transforms folder.