MSBuild Team Blog : Jeffery Callahan

New Registry syntax in MSBuild v3.5

msbuild — Sat, 05 May 2007 01:25:00 GMT

During development of the multi-targeting feature of the next version of MSBuild, we found it convenient to expose a new method for accessing the registry from project and target files. I hadn't really thought much more about it since we implemented it, but today I needed to make a change to Microsoft.Common.targets for which this new syntax was perfect, so I thought I'd share.

So here's how it works: suppose there's some value in the registry you're interested in consuming. Using the 2.0 version of MSBuild, you may have written a task which took the names of the key and value, and output the value of the value (ha, I always think it's funny saying that). Now, with the 3.5 version of MSBuild, it's very simple. Say the key you're interested in is "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework" and the value at that key you'd like to retrieve is "InstallRoot". On my machine, this value is set to "C:\WINDOWS\Microsoft.NET\Framework\". In your project/targets file - anywhere a property reference is allowed (which is pretty much everywhere), you could obtain this value with the property

$(Registry:HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework@InstallRoot)

This sort of shows off the pieces of the new syntax, which can be described like this

$(Registry:<key name>[@<value name>])

Note the value name is optional - this is because the registry supports a notion of default values. If you omit the value from the specification, MSBuild will simply retrieve the default value (if it exists).

I think this is a neat new feature which hopefully many of you will find useful. Enjoy!

[ Author: Jeffery Callahan ]

New Reference Assemblies Location

msbuild — Thu, 12 Apr 2007 21:16:00 GMT

Those of you who've been using the 3.0 Framework may have noticed a folder under Program Files called "Reference Assemblies". This folder contains those assemblies that ship with the 3.0 Framework which are useful for referencing during the design and build of new components. Those of you who haven't yet used the 3.0 Framework, but plan on using the 3.5 Framework when it's released to the wild, will notice this change has continued.

This change is largely about disentangling design time and runtime scenarios. At runtime, these components will still be loaded from the GAC in most cases. At design time, going forward there will be a single location where users can find assemblies available for reference. This location for the 3.5 Framework is:

"%ProgramFiles%\Reference Assemblies\Microsoft\Framework\v3.5"

For MSBuild, we've placed the 3.5 versions of the assemblies Microsoft.Build.Engine.dll, Microsoft.Build.Framework.dll, Microsoft.Build.Conversion.v3.5.dll and Microsoft.Build.Utilities.v3.5.dll (explanation of the "v3.5" in the filenames coming in a subsequent blog post!) at this location, and as mentioned earlier they will continue installing to the GAC for runtime use. Notice I didn't list Microsoft.Build.Tasks.v3.5.dll here - because this assembly is essentially for runtime use only, we didn't decide to install it under the Reference Assemblies location.

The tools themselves that ship with the .NET Framework v3.5 (csc.exe, msbuild.exe, vbc.exe) will continue installing to their expected locations.

At build time, we actually had little work to do to accommodate this change. For the version of MSBuild that shipped with the .NET Framework 2.0, we used a single location under the WINDOWS folder in different ways for different parts of the build. For example, the compiler tasks looked in this location to find the executable they called, and the reference resolution task (ResolveAssemblyReference) would look in this location to resolve certain system assemblies. Now, the reference resolution task has a location set aside expressly for this purpose, so it no longer needs to inspect the location under WINDOWS (for 3.0 and 3.5, anyways).

[ Author: Jeffery Callahan ]

Restrictions on the Exclude attribute in an item tag

msbuild — Wed, 09 Nov 2005 02:09:00 GMT

An item exclude only works with the corresponding include on the same actual item tag-- in other words, if the exclude occurs in a later item tag of the same type, it will not affect any files previously included.

For example: suppose you have files a.cs, b.cs, c.cs, a.dll, b.dll, c.dll in the same directory as this project file:


<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <Files Include="*.cs" />
  <Files Include="*.dll" Exclude="a.cs" />
  <Target Name="Default">
    <Message Text="@(Files)" />
  </Target>
</Project>

Then the output looks like this:

a.cs;b.cs;c.cs;a.dll;b.dll;c.dll

In particular, a.cs is not excluded.

There are several reasons why an "Exclude" only excludes items from the current item tag, instead of any item in the project file.

If an "Exclude" could exclude any item that had previously been included anywhere in the project file, it would make the project file much more confusing and hard to read. Imagine a project file including *.cs, and some imported .TARGETS file excluding a.cs. The user would spend hours trying to figure out why a.cs is not getting compiled. When you see Include="*.cs" in a project file, it's very nice to be able to know for sure that all of the .CS files are being included in the project.
There's really no compelling scenario for excluding items from a previous item's Include. The main scenario for "Exclude" is that you're using a wildcard in a particular "Include", but because of the simplistic syntax of wildcards, there's no way to be as specific as you would like. So you tweak the "Include" by specifying an "Exclude". It doesn't really make too much sense to do this for items that have already been included previously.
Since you can have multiple items with the same "Include" (with perhaps different item attributes), it's not clear which item we would exclude if the "Exclude" could occur in any random place in the project.
With VS integration, it would be extremely difficult to support certain edits to the project file if an item could be excluded anywhere in the project file. Imagine this:


<ItemGroup>
  <Compile Include="b.cs" />
</ItemGroup>
....
<ItemGroup>
  <Compile Exclude="a.cs" />
</ItemGroup>

Now the user loads this into the IDE, and in his Solution Explorer, he sees only "b.cs". Now in Solution Explorer, he renames b.cs to a.cs. What should the project file look like now? This type of thing causes unnecessary ambiguity and difficulty.

[ Author: Jeffery Callahan ]

what happens before msbuild decides to build a target?

msbuild — Fri, 14 Oct 2005 22:00:00 GMT

there are several elements to processing a target tag: processing its dependencies, processing the condition, and performing TLDA (top level dependency analysis) or up-to-date checks. it can be confusing to figure out if a target will execute or not, so we on the msbuild team toss around a nifty mnemonic to help us remember (originally pointed out by rajeev, as far as i can remember). this is the order in which msbuild processes the attributes of a target element:

Condition
DependsOnTargets
Inputs
Outputs

notice they're in alphabetical order. first, msbuild will evaluate the Condition. if the Condition is false, msbuild skips the target (and never even bothers looking at the DependsOnTargets attribute). if the Condition is true, msbuild will then execute each of the targets listed in DependsOnTargets. once the dependencies have been built, it will then examine the Inputs and Outputs to determine if the target even needs to be built, or if it can be partially built (do you know what this means?). then msbuild can actually begin running your tasks....

[ Author: Jeffery Callahan ]