MSBuild ProjectReference item documentation

Question

I cannot find documentation about ProjectReference tag in MSBuild projects. Where can I read detailed description of it?

Edit: I have a .vcxproj created by others. It contains ProjectReference item. ProjectReference contains subtags: Private, ReferenceOutputAssembly, CopyLocalSatelliteAssemblies, LinkLibraryDependencies, UseLibraryDependencyInputs. Where I can read about those tags? Which values can they contain? What other subtags can ProjectReference contain?

I have searched in MSDN and Google but have not found documentation pages, only discussions and documentation about other products, not MSBuild.

Answer 1

Starting from the MSBuild source code links that Jason Pyeron provided in his comment, I learned that when MSBuild prepares build dependencies, it includes all item metadata (what you refer to as subtags) from each ProjectReference item. As a result, downstream Tasks and Targets can and sometimes do read arbitrary ProjectReference metadata.

For answers to your questions about C++ projects, you can examine Microsoft.CppBuild.targets and Microsoft.CppCommon.targets (their default path in MSBuild 14, coinciding with Visual Studio 2015, is C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\V140\). As the following example shows, however, it is not simple to do so:

1. In Microsoft.CppBuild.targets, the Target ResolvedXDCMake creates _ResolvedNativeProjectReferencePaths Items dynamically.
2. From those Items, the Target ComputeReferenceLinkInputs creates ProjectReferenceToLink items dynamically.
3. For each of those Items that do not have CopyLocal metadata, the same Target adds it, copying any Private metadata value.
4. For each those Items with a distinct path, the same target creates a Link item dynamically.
5. Switching now to Microsoft.CppCommon.targets, Link items are passed in the Sources parameter of the Link Task in the Link Target! Although to be fair, their metadata was cleared in the previous step, so you do not have to dive into the Link Target documentation in this particular case.

Here are additional portions that relate your question:

Parameters

• Include (attribute): Path to project file
• Project (metadata): Project GUID, in the form {00000000-0000-0000-0000-000000000000}
• ReferenceOutputAssembly (metadata): Boolean specifying whether the outputs of the project referenced should be passed to the compiler. Default is true.
• SpecificVersion (metadata): Whether the exact version of the assembly should be used.
• Targets (metadata): Semicolon-separated list of targets in the referenced projects that should be built. Default is the value of $(ProjectReferenceBuildTargets) whose default is blank, indicating the default targets.
• OutputItemType (metadata): Item type to emit target outputs into. Default is blank. If ReferenceOutputAssembly is set to "true" (default) then target outputs will become references for the compiler.
• EmbedInteropTypes (metadata): Optional boolean. Whether the types in this reference need to embedded into the target assembly - interop asemblies only

Remarks

When the OutputItemType parameter is used, additional parameters (metadata) may be applicable. For example, when OutputItemType is set to Content, CopyToOutputDirectory can be used:

• CopyToOutputDirectory (metadata): Optional string. Determines whether to copy the file to the output directory. Values: Never, Always, PreserveNewest.

Answer 2

You will notice that the ProjectReference element is a child of an ItemGroup element.

ItemGroups are a fully documented schema item thankfully. What you will find is that child elements of ItemGroups can by anything. Think of it as the name of a collection. That item within the ItemGroup can have "metadata" values.

For example,

<ItemGroup>
    <WindowsFiles Include="C:\Windows\*">
       <IsSystem>true</IsSystem>
    </WindowsFiles>
</ItemGroup>

This is defining an itemgroup called WindowsFiles. It essentially becomes a collection of files that match the Include attribute. All item group items have metadata built in - such as filename, extension, fullpath, directory, etc. but you can add your own - in this case IsSystem is an additional one.

Referencing item groups is done in one of two ways:

<Message Text="%(WindowsFiles.FullPath)"/>

<Message Text="@(WindowsFiles->'%(FullPath)')"/>

The latter is referred to as a transform which is more advanced. Best stick to the former until you get your head around ItemGroups or transforms just won't go in.

The ProjectReference itemgroup you are interested in will be processed by a targets file somewhere. As itemgroups are fairly arbitrary in what they are called, conceptually they are variables so it's how they get processed by the targets file that defines the usage.

Work your way up the files mentioned in the Import statements to see where the ProjectReference item group gets consumed.