msbuild - how does task MSBuild loop over files

Question

<Target Name="Build">
...

    <MSBuild
            Projects="$(MSBuildProjectFile)"
            Condition="'@(FilesToCompile)' != ''"
            Targets="buildcpp"
            Properties="CPPFILE=%(FilesToCompile.FullPath);OBJFILE=$(ObjectFolder)\%(FilesToCompile.Filename).doj;IncludeDirs=$(IncludeDirs)"
        />

FilesToCompile is an ItemGroup of all .cpp files.

When I look at the build log, it shows the target buildcpp being run for each of the files in CPPFILE.

I understand that is what I logically want to happen but my question is, what rule of element <MSBuild> or the MSBuild schema causes task MSBuild to be executed for each value of CPPFILE?

In short, where in the documentation does it state that is what will happen?

I want to pass in an entire ItemGroup once instead of calling the MSBuild target once for each item.

Answer 1

The msbuild concept this is based on is called "batching" - in your case task batching (see MSBuild's task batching documentation).

Any task that contains a %() reference to an item group will be split up into batches that share the same metadata and the task will be executed once for each batch. When using built-in metadata like Identity or FullPath, this essentially means "execute this task for ever item", though there can also be more complex use cases.